lazypock 0.2.0 → 0.4.0

package/src/http.ts

@@ -3,6 +3,8 @@
 
 import { ApiError, type Method, type RequestOptions } from "./types";
 import type { AuthStore } from "./auth";
+import type { CacheStore } from "./cache";
+import { resolveCacheDirective } from "./cache";
 
 /**
  * Low-level HTTP client wrapping `fetch` with automatic auth token injection.
@@ -20,6 +22,10 @@ export class HttpClient {
 	private baseUrl: string;
 	private authStore: AuthStore;
 	private defaultFetch: typeof globalThis.fetch;
+	/** Optional query cache store (wired when the client enables caching). */
+	private cache?: CacheStore;
+	/** Master switch resolved from CacheConfig.enabled. */
+	private cacheEnabled = false;
 
 	/**
 	 * Abort controllers for in-flight requests, keyed by their cancellation key
@@ -28,6 +34,14 @@ export class HttpClient {
 	 */
 	private cancelControllers: Record<string, AbortController> = {};
 
+	/**
+	 * 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: Record<string, Promise<unknown>> = {};
+
 	/** Global toggle for the auto-cancellation behaviour (default: on). */
 	private enableAutoCancellation = true;
 
@@ -41,6 +55,20 @@ export class HttpClient {
 		this.defaultFetch = globalThis.fetch.bind(globalThis);
 	}
 
+	/**
+	 * Attach a cache store + master switch.
+	 * Called by the client constructor when cache config is present.
+	 */
+	setCache(cache: CacheStore, enabled: boolean): void {
+		this.cache = cache;
+		this.cacheEnabled = enabled;
+	}
+
+	/** Whether the global cache flag is on (requests opt in/out individually too). */
+	get cacheIsEnabled(): boolean {
+		return this.cacheEnabled;
+	}
+
 	private async refreshAuth(): Promise<{
 		token: string;
 		record: Record<string, unknown>;
@@ -125,6 +153,16 @@ export 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 {
+		this.cache?.invalidate(namespace);
+	}
+
+	/** Current cache statistics (hits/misses/entries), or null when disabled. */
+	cacheStats(): { hits: number; misses: number; entries: number } | null {
+		return this.cache ? this.cache.stats() : null;
+	}
+
 	async request<T = unknown>(
 		method: Method,
 		path: string,
@@ -136,6 +174,28 @@ export class HttpClient {
 			await this.refreshAuth();
 		}
 
+		// ── Cache resolution (read path) ────────────────────────────────
+		// Only cacheable reads (GET) participate. Cache keys are scoped by auth
+		// token so user A's cached list can never leak to user B (or anonymous).
+		//
+		// Effective caching for this request:
+		//   - per-request { cache } / { ttl } present → use it (true enables,
+		//     false bypasses, number/object sets TTL)
+		//   - otherwise → fall back to the global cache.enabled flag
+		const cacheDirective = resolveCacheDirective(options);
+		const wantCache =
+			cacheDirective !== null
+				? cacheDirective.enabled
+				: this.cacheEnabled;
+		const cacheKey =
+			method === "GET" && this.cache && wantCache
+				? this.cacheKeyFor(method, path, options?.params)
+				: null;
+		if (cacheKey !== null) {
+			const hit = await this.cache?.get(cacheKey);
+			if (hit !== undefined) return hit as T;
+		}
+
 		// Resolve the auto-cancellation key (PocketBase `requestKey` semantics):
 		// - options.requestKey null  → disabled for this request
 		// - options.requestKey string → use it verbatim
@@ -148,6 +208,16 @@ export class HttpClient {
 				: options.requestKey;
 		if (options?.autoCancel === false) requestKey = null;
 
+		// Single-flight coalescing: when the same requestKey is already in-flight
+		// and the caller opted in, reuse that promise instead of firing a duplicate
+		// request (no abort rejection for either caller).
+		if (options?.singleFlight && requestKey !== null) {
+			const pending = this.inflight[requestKey];
+			if (pending !== undefined) {
+				return pending as Promise<T | null>;
+			}
+		}
+
 		// Wire a fresh AbortController for this request, merging any caller signal.
 		// When auto-cancellation is enabled, the previous pending request sharing
 		// our key is aborted first (only the last duplicate executes).
@@ -169,6 +239,52 @@ export class HttpClient {
 		}
 		const signal = controller?.signal ?? externalSignal;
 
+		// Register the in-flight promise so later single-flight callers reuse it.
+		// The promise is created from an inner async fn that performs the request
+		// and clears itself from the inflight map on settle.
+		const perform = async (): Promise<T | null> => {
+			try {
+				return await this.doRequest(
+					method,
+					path,
+					body,
+					options,
+					signal,
+					requestKey,
+					controller,
+					cacheKey,
+					cacheDirective,
+				);
+			} finally {
+				if (requestKey !== null) {
+					if (this.inflight[requestKey] === promise) {
+						delete this.inflight[requestKey];
+					}
+				}
+			}
+		};
+		const promise = perform();
+		if (requestKey !== null) {
+			this.inflight[requestKey] = promise;
+		}
+		return promise;
+	}
+
+	/**
+	 * 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 async doRequest<T = unknown>(
+		method: Method,
+		path: string,
+		body: unknown,
+		options: RequestOptions | undefined,
+		signal: AbortSignal | null | undefined,
+		requestKey: string | null,
+		controller: AbortController | null,
+		cacheKey: string | null,
+		cacheDirective: ReturnType<typeof resolveCacheDirective>,
+	): Promise<T | null> {
 		let url = this.baseUrl + path;
 		if (options?.params) {
 			const qs = new URLSearchParams(options.params).toString();
@@ -253,9 +369,83 @@ export class HttpClient {
 			);
 		}
 
+		// ── Cache store (read path) ─────────────────────────────────────
+		// Persist successful GET payloads when the directive wants caching.
+		if (cacheKey !== null && this.cache) {
+			const namespace = this.namespaceFromPath(path);
+			const ttl = cacheDirective?.ttl;
+			const tags = this.cacheTagsFor(path, namespace);
+			this.cache.set(
+				cacheKey,
+				data,
+				ttl,
+				namespace ?? undefined,
+				tags,
+			);
+		}
+
+		// ── Cache invalidation (write path) ────────────────────────────
+		// Mutations invalidate the affected collection's cached entries so
+		// subsequent reads don't serve stale lists. The current collection is
+		// always invalidated; `options.invalidate` adds extra namespaces.
+		if (method !== "GET" && this.cache) {
+			const namespaces = new Set<string>();
+			const ns = this.namespaceFromPath(path);
+			if (ns) namespaces.add(ns);
+			for (const extra of options?.invalidate ?? []) {
+				if (extra) namespaces.add(extra);
+			}
+			for (const nsName of namespaces) this.cache.invalidate(nsName);
+		}
+
 		return data as T;
 	}
 
+	// ── Cache key/namespace helpers ──
+
+	/** Build a token-scoped cache key: `METHOD path|token-hash|params`. */
+	private cacheKeyFor(
+		method: Method,
+		path: string,
+		params?: Record<string, string>,
+	): string {
+		const token = this.authStore.token || "anon";
+		const qs = params ? "?" + new URLSearchParams(params).toString() : "";
+		return `${method} ${path}${qs}|${token}`;
+	}
+
+	/** Best-effort namespace (collection name) from a REST path. */
+	private namespaceFromPath(path: string): string | undefined {
+		// /posts/abc-123 → posts ; /collections/xyz → collections
+		// strip any query string first (/posts?page=1 → /posts)
+		const clean = path.split("?")[0];
+		const parts = clean.split("/").filter(Boolean);
+		if (parts.length === 0) return undefined;
+		if (parts[0] === "collections" || parts[0] === "_superusers") {
+			return parts[0];
+		}
+		return parts[0];
+	}
+
+	/**
+	 * 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(path: string, namespace: string | undefined): string[] {
+		if (!namespace) return [];
+		const clean = path.split("?")[0];
+		const parts = clean.split("/").filter(Boolean);
+		if (parts[0] === "collections" || parts[0] === "_superusers") {
+			const op = parts.length >= 2 ? "getOne" : "getList";
+			return [`${namespace}:${op}`];
+		}
+		// /posts (list) vs /posts/{id} (one)
+		const op = parts.length >= 2 ? "getOne" : "getList";
+		return [`${op}:${namespace}`];
+	}
+
 	/**
 	 * HTTP GET.
 	 * @param path URL path.

package/src/index.ts

@@ -23,6 +23,8 @@ export {
 	fieldTypeScriptType,
 	fieldTypeKind,
 	schemaFieldType,
+	CacheStore,
+	resolveCacheDirective,
 } from "./lazypock";
 export { TypedClient, createClient } from "./client";
 
@@ -38,6 +40,9 @@ export type {
 	SystemFields,
 	RequestOptions,
 	FileRecord,
+	// cache
+	CacheConfig,
+	CacheRequestOptions,
 	// schema
 	CollectionSchema,
 	SchemaField,

package/src/lazypock.ts

@@ -32,6 +32,8 @@ import { CollectionsService } from "./collections";
 import type { CollectionSchema, SchemaField } from "./schema";
 import { generateTypes, collectionTypeName } from "./codegen";
 import { fieldTypeScriptType, fieldTypeKind, schemaFieldType } from "./typegen";
+import { CacheStore, type CacheConfig, type CacheRequestOptions } from "./cache";
+import { resolveCacheDirective } from "./cache";
 
 export {
 	AuthStore,
@@ -65,6 +67,25 @@ export type {
 	CollectionSchema,
 	SchemaField,
 };
+export type { CacheConfig, CacheRequestOptions };
+export { CacheStore, resolveCacheDirective };
+
+/**
+ * Callable cache namespace: `client.cache(config)` configures, and
+ * `client.cache.deleteByPrefix(...)` etc. manage cached entries.
+ */
+export 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}. */
 export interface LazypockClientOptions {
@@ -76,6 +97,24 @@ export 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
@@ -110,6 +149,9 @@ export class LazypockClient {
 	readonly files: FilesService;
 	private collectionCache = new Map<string, CollectionService>();
 	private schemaByName?: Map<string, CollectionSchema>;
+	private cacheStore?: CacheStore;
+	/** Namespace → realtime unsubscribe; used for realtime-driven invalidation. */
+	private realtimeInvalidators = new Map<string, () => void>();
 
 	/**
 	 * Create a new Lazypock client.
@@ -127,6 +169,14 @@ export class LazypockClient {
 		}
 		this.files = new FilesService(this.http);
 		this.collections = new CollectionsService(this.http, this.realtime);
+		if (options.cache) {
+			this.cacheStore = new CacheStore({
+				defaultTTL: options.cache.defaultTTL,
+				store: options.cache.store,
+				maxEntries: options.cache.maxEntries,
+			});
+			this.http.setCache(this.cacheStore, options.cache.enabled ?? false);
+		}
 		if (options.types?.schemas) {
 			this.schemaByName = new Map(
 				options.types.schemas.map((s) => [s.name, s]),
@@ -215,6 +265,100 @@ export class LazypockClient {
 		return this;
 	}
 
+	// ── Query cache (opt-in by default; opt-out per request) ──
+
+	/**
+	 * 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 = Object.assign(
+		((config?: CacheConfig) => {
+			if (!this.cacheStore) {
+				// Lazy-create so `.cache({ enabled: true })` works even when the
+				// constructor wasn't given cache config.
+				this.cacheStore = new CacheStore({
+					defaultTTL: config?.defaultTTL,
+					store: config?.store,
+					maxEntries: config?.maxEntries,
+				});
+				this.http.setCache(this.cacheStore, config?.enabled ?? true);
+			} else {
+				if (config?.enabled !== undefined) {
+					this.http.setCache(this.cacheStore, config.enabled);
+				}
+			}
+			return this;
+		}) as (config?: CacheConfig) => LazypockClient,
+		{
+			deleteByPrefix: (prefix: string) => this.cacheStore?.deleteByPrefix(prefix),
+			invalidate: (namespace: string) => this.cacheStore?.invalidate(namespace),
+			clear: () => {
+				this.cacheStore?.clear();
+				for (const unsub of this.realtimeInvalidators.values()) unsub();
+				this.realtimeInvalidators.clear();
+			},
+			stats: () => (this.cacheStore ? this.cacheStore.stats() : null),
+		},
+	);
+
+	/**
+	 * Drop every cached entry (all collections / namespaces).
+	 * Also disables realtime-driven invalidation subscriptions.
+	 */
+	clearCache(): this {
+		this.cacheStore?.clear();
+		for (const unsub of this.realtimeInvalidators.values()) unsub();
+		this.realtimeInvalidators.clear();
+		return 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 {
+		this.cacheStore?.invalidate(namespace);
+		return this;
+	}
+
+	/**
+	 * Cache hit/miss/entry statistics.
+	 * Returns null when caching was never configured.
+	 */
+	cacheStats(): { hits: number; misses: number; entries: number } | null {
+		return this.cacheStore ? this.cacheStore.stats() : 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 {
+		if (!this.cacheStore) {
+			// ensure a store exists so invalidation has somewhere to go
+			this.cache({ enabled: false });
+		}
+		const existing = this.realtimeInvalidators.get(collectionName);
+		if (existing) return existing;
+		const unsub = this.collection(collectionName).subscribe(() => {
+			this.cacheStore?.invalidate(collectionName);
+		});
+		this.realtimeInvalidators.set(collectionName, unsub);
+		return unsub;
+	}
+
 	// ── Auth ──
 
 	/** Check whether any superuser exists (for login vs setup screen routing). */

package/src/types.ts

@@ -65,6 +65,18 @@ export 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.
 	 *
@@ -87,6 +99,17 @@ export 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;
 }
 
 export class ApiError extends Error {