lazypock 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -50,6 +50,21 @@ interface RequestOptions {
     signal?: AbortSignal;
     /** Custom fetch implementation (for RN or test mocking) */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Cache control for this request (see {@link CacheRequestOptions}).
+     * Resolved against the client's global cache config when unset.
+     */
+    cache?: boolean | number | {
+        ttl?: number;
+        key?: string;
+    };
+    /** Alias of `cache: <ms>` — cache this GET for `ttl` milliseconds. */
+    ttl?: number;
+    /**
+     * Extra cache namespaces to invalidate when this mutation succeeds.
+     * The current collection is always invalidated automatically.
+     */
+    invalidate?: string[];
     /**
      * Request identifier used by the auto-cancellation mechanism.
      *
@@ -72,6 +87,17 @@ interface RequestOptions {
      * Alias of `requestKey` (PocketBase `$cancelKey` compat).
      */
     cancelKey?: string;
+    /**
+     * Coalesce concurrent identical requests (same `requestKey`) onto a single
+     * in-flight promise instead of aborting the earlier one.
+     *
+     * When enabled, a request arriving while another with the same key is still
+     * pending awaits the same result — no duplicate network request, and the
+     * caller of the first request never sees an abort rejection.
+     *
+     * @default false (auto-cancellation aborts the earlier duplicate)
+     */
+    singleFlight?: boolean;
 }
 declare class ApiError extends Error {
     readonly data: unknown;
@@ -158,16 +184,160 @@ declare class AuthStore {
     private notify;
 }
 
+/** Options for enabling/customising the client's query cache. */
+interface CacheConfig {
+    /**
+     * Master switch. When `true`, readable GET requests are cached with the
+     * default TTL unless a request opts out via `{ cache: false }`.
+     *
+     * When `false` (default), caching is disabled unless a request opts in
+     * via `{ cache: true }` or `{ ttl: <ms> }`. Opt-in works regardless.
+     */
+    enabled?: boolean;
+    /**
+     * Default time-to-live for cached entries, in milliseconds.
+     * @default 60_000 (1 minute)
+     */
+    defaultTTL?: number;
+    /**
+     * Optional persistence backend (same interface as AuthStore's storage).
+     * Defaults to an in-memory Map — swap for `localStorage` / `AsyncStorage`
+     * to keep the cache across page reloads / app restarts.
+     */
+    store?: StorageAdapter;
+    /**
+     * Max number of entries to keep in memory (LRU eviction).
+     * @default 500
+     */
+    maxEntries?: number;
+    /**
+     * When true and the client has an active realtime subscription for a
+     * collection, inbound create/update/delete events invalidate that
+     * collection's cached entries automatically.
+     * @default false — only local mutations invalidate (explicit + predictable)
+     */
+    invalidateOnRealtime?: boolean;
+}
+/** Per-request cache controls (mixed into {@link RequestOptions}). */
+interface CacheRequestOptions {
+    /**
+     * Cache control for this request:
+     * - `true` — cache with the default (or global) TTL
+     * - `false` — always fetch fresh, bypass cache (and don't store the result)
+     * - a number — cache with this TTL in milliseconds
+     * - an object — `{ ttl, key }` for finer control
+     *
+     * When unset, the global `cache.enabled` flag decides.
+     */
+    cache?: boolean | number | {
+        ttl?: number;
+        key?: string;
+    };
+    /** Alias of `cache: <ms>` (convenience, reads naturally). */
+    ttl?: number;
+    /**
+     * Extra cache namespaces to invalidate when this mutation succeeds.
+     * The current collection is always invalidated automatically.
+     * @example create({ ... }, { invalidate: ['users'] })
+     */
+    invalidate?: string[];
+}
+/** LRU-ish memory store + optional persistent adapter hybrid. */
+declare class CacheStore {
+    private memory;
+    private readonly ttl;
+    private readonly persistence?;
+    private readonly maxEntries;
+    private hits;
+    private misses;
+    private namespaceEntries;
+    /** Key → set of prefix tags registered for that key (e.g. `getList:posts`). */
+    private prefixEntries;
+    constructor(config?: {
+        defaultTTL?: number;
+        store?: StorageAdapter;
+        maxEntries?: number;
+    });
+    /** Resolve the effective TTL: request override → global default. */
+    private resolveTTL;
+    /**
+     * Read a cached value. Fast sync path (memory) with async persistence
+     * fallback for adapters whose `get` returns a Promise.
+     * @param key Cache key (e.g. `"GET /posts?page=1"`).
+     * @returns The cached value, or undefined when absent/expired (the hit is
+     * cleared on expiry so a stale value is never served).
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /**
+     * Store a value.
+     * @param key Cache key.
+     * @param value The response payload.
+     * @param ttlOverride Optional TTL override (ms).
+     * @param namespace Optional namespace for group invalidation.
+     */
+    set(key: string, value: unknown, ttlOverride?: number, namespace?: string, tags?: string[]): void;
+    /**
+     * Invalidate entries belonging to a namespace (e.g. a collection name).
+     * Also clears the namespace index entry.
+     */
+    invalidate(namespace: string): void;
+    /** Remove a single key. */
+    delete(key: string): void;
+    /**
+     * Delete every entry whose key starts with `prefix`.
+     *
+     * Useful for fine-grained invalidation, e.g.:
+     * ```ts
+     * client.cache.deleteByPrefix('getList:posts'); // delete all getList cache
+     * client.cache.deleteByPrefix('getOne:posts');  // delete all getOne cache
+     * ```
+     */
+    deleteByPrefix(prefix: string): void;
+    /** Drop every cached entry (memory + persistence). */
+    clear(): void;
+    /** Cache hit/miss/entry statistics. */
+    stats(): {
+        hits: number;
+        misses: number;
+        entries: number;
+    };
+    private persistKey;
+    private readPersisted;
+}
+/** Resolve per-request cache options into a usable directive. */
+declare function resolveCacheDirective(opts?: {
+    cache?: boolean | number | {
+        ttl?: number;
+        key?: string;
+    };
+    ttl?: number;
+}): {
+    enabled: boolean;
+    ttl?: number;
+    key?: string;
+} | null;
+
 declare class HttpClient {
     private baseUrl;
     private authStore;
     private defaultFetch;
+    /** Optional query cache store (wired when the client enables caching). */
+    private cache?;
+    /** Master switch resolved from CacheConfig.enabled. */
+    private cacheEnabled;
     /**
      * Abort controllers for in-flight requests, keyed by their cancellation key
      * (default `METHOD path`). A new request with the same key aborts the
      * previous one — PocketBase-style auto-cancellation of duplicated requests.
      */
     private cancelControllers;
+    /**
+     * In-flight request promises, keyed by cancellation key. When auto-cancellation
+     * would abort a pending duplicate, the newer request instead awaits the same
+     * promise — single-flight coalescing (no duplicate network request, no
+     * spurious abort rejection for the caller).
+     */
+    private inflight;
     /** Global toggle for the auto-cancellation behaviour (default: on). */
     private enableAutoCancellation;
     /**
@@ -175,6 +345,13 @@ declare class HttpClient {
      * @param authStore The auth store providing the token for Authorization headers.
      */
     constructor(baseUrl: string, authStore: AuthStore);
+    /**
+     * Attach a cache store + master switch.
+     * Called by the client constructor when cache config is present.
+     */
+    setCache(cache: CacheStore, enabled: boolean): void;
+    /** Whether the global cache flag is on (requests opt in/out individually too). */
+    get cacheIsEnabled(): boolean;
     private refreshAuth;
     /**
      * Globally enable or disable auto-cancellation of duplicated pending requests.
@@ -204,7 +381,31 @@ declare class HttpClient {
      * @throws {ApiError} On non-2xx responses or when the request is aborted
      * (aborted requests throw an `ApiError` with `isAbort === true`).
      */
+    /** Invalidate a namespace (collection name). No-op when cache is off. */
+    invalidateCache(namespace: string): void;
+    /** Current cache statistics (hits/misses/entries), or null when disabled. */
+    cacheStats(): {
+        hits: number;
+        misses: number;
+        entries: number;
+    } | null;
     request<T = unknown>(method: Method, path: string, body?: unknown, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Execute the actual HTTP request (fetch + parse + cache). Called by {@link request}
+     * as the inner in-flight unit so single-flight callers can reuse the promise.
+     */
+    private doRequest;
+    /** Build a token-scoped cache key: `METHOD path|token-hash|params`. */
+    private cacheKeyFor;
+    /** Best-effort namespace (collection name) from a REST path. */
+    private namespaceFromPath;
+    /**
+     * Semantic prefix tags for `deleteByPrefix`, derived from the REST shape:
+     * - `/{collection}?...` → `getList:{collection}`
+     * - `/{collection}/{id}` → `getOne:{collection}`
+     * - `/collections?...` / `/collections/{id}` → `collections:getList` / `collections:getOne`
+     */
+    private cacheTagsFor;
     /**
      * HTTP GET.
      * @param path URL path.
@@ -681,6 +882,26 @@ declare function fieldTypeKind(field: SchemaField): FieldTypeKind;
  */
 declare function schemaFieldType(field: SchemaField): unknown;
 
+/**
+ * Callable cache namespace: `client.cache(config)` configures, and
+ * `client.cache.deleteByPrefix(...)` etc. manage cached entries.
+ */
+interface CacheController {
+    /** Configure the query cache at runtime. */
+    (config?: CacheConfig): LazypockClient;
+    /** Delete every entry whose key starts with `prefix` (e.g. `getList:posts`). */
+    deleteByPrefix(prefix: string): void;
+    /** Invalidate a collection's cached entries (alias of invalidateCache). */
+    invalidate(namespace: string): void;
+    /** Drop every cached entry. */
+    clear(): void;
+    /** Cache hit/miss/entry stats, or null when never configured. */
+    stats(): {
+        hits: number;
+        misses: number;
+        entries: number;
+    } | null;
+}
 /** Options for constructing a {@link LazypockClient}. */
 interface LazypockClientOptions {
     /** API base URL (e.g. 'http://localhost:4000/api') */
@@ -691,6 +912,24 @@ interface LazypockClientOptions {
     authStore?: AuthStore;
     /** Real-time service for Phoenix Channel WebSocket subscriptions */
     realtime?: RealtimeService;
+    /**
+     * Query cache configuration. Disabled by default.
+     *
+     * ```ts
+     * const client = createClient({
+     *   baseUrl: '...',
+     *   cache: {
+     *     enabled: true,
+     *     defaultTTL: 30_000,
+     *     store: myStorage,      // optional persistence (same interface as auth)
+     *   },
+     * });
+     * ```
+     *
+     * When enabled, readable GETs are cached. Requests can opt out via
+     * `{ cache: false }`, or opt in with a custom TTL via `{ ttl: ms }`.
+     */
+    cache?: CacheConfig;
     /**
      * Optional schema types for generating typed services at runtime.
      * When provided, `collection()` returns a service whose create/update
@@ -724,6 +963,9 @@ declare class LazypockClient {
     readonly files: FilesService;
     private collectionCache;
     private schemaByName?;
+    private cacheStore?;
+    /** Namespace → realtime unsubscribe; used for realtime-driven invalidation. */
+    private realtimeInvalidators;
     /**
      * Create a new Lazypock client.
      * @param options Configuration options.
@@ -778,6 +1020,47 @@ declare class LazypockClient {
     cancelRequest(requestKey: string): this;
     /** Abort all pending requests. */
     cancelAllRequests(): this;
+    /**
+     * Configure the query cache at runtime (also a namespace for cache
+     * management methods).
+     *
+     * ```ts
+     * client.cache({ enabled: true, defaultTTL: 30_000 });
+     * client.cache.deleteByPrefix('getList:posts');  // all list caches for posts
+     * client.cache.deleteByPrefix('getOne:posts');   // all one-record caches
+     * ```
+     *
+     * When enabled, GET requests cache their payload; mutations invalidate the
+     * affected collection automatically. Individual requests can opt out with
+     * `{ cache: false }` or override the TTL with `{ ttl: ms }`.
+     */
+    readonly cache: CacheController;
+    /**
+     * Drop every cached entry (all collections / namespaces).
+     * Also disables realtime-driven invalidation subscriptions.
+     */
+    clearCache(): this;
+    /**
+     * Invalidate cached entries for a collection (or custom namespace).
+     * Runs automatically on mutations — call explicitly when data changed
+     * out-of-band (e.g. another client wrote to the same collection).
+     */
+    invalidateCache(namespace: string): this;
+    /**
+     * Cache hit/miss/entry statistics.
+     * Returns null when caching was never configured.
+     */
+    cacheStats(): {
+        hits: number;
+        misses: number;
+        entries: number;
+    } | null;
+    /**
+     * Subscribe a collection's cache to realtime invalidation: any inbound
+     * create/update/delete event for the collection clears its cached entries.
+     * Returns an unsubscribe function.
+     */
+    invalidateCacheOnRealtime(collectionName: string): () => void;
     /** Check whether any superuser exists (for login vs setup screen routing). */
     checkSuperuser(): Promise<{
         has_superuser: boolean;
@@ -870,4 +1153,4 @@ declare class TypedClient<TCollections extends LazypockCollections = LazypockCol
  */
 declare function createClient<TCollections extends LazypockCollections = LazypockCollections>(options: LazypockClientOptions): TypedClient<TCollections>;
 
-export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CollectionsMessage, CollectionsService, type CreateData, type FileRecord, FilesService, HttpClient, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, type RealtimeCallback, type RealtimeMessage, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, getScaleUrl, getThumbUrl, schemaFieldType, wsUrlFromBaseUrl };
+export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CacheConfig, type CacheRequestOptions, CacheStore, type CollectionSchema, CollectionService, type CollectionsMessage, CollectionsService, type CreateData, type FileRecord, FilesService, HttpClient, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, type RealtimeCallback, type RealtimeMessage, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, getScaleUrl, getThumbUrl, resolveCacheDirective, schemaFieldType, wsUrlFromBaseUrl };