lazypock 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lazypock",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/collection.ts

@@ -12,6 +12,36 @@ import type {
 } from "./types";
 import type { RealtimeService } from "./realtime";
 
+/**
+ * Deterministic JSON stringify for building a stable cache/dedup key.
+ * Strips request-transport keys (`requestKey`, `singleFlight`, `fetch`,
+ * `signal`) so functionally-identical calls share one key.
+ */
+export function stableStringify(value: unknown): string {
+	const seen = new Set<object>();
+	const sort = (v: unknown): unknown => {
+		if (Array.isArray(v)) return v.map(sort);
+		if (v && typeof v === "object") {
+			if (seen.has(v as object)) return "[Circular]";
+			seen.add(v as object);
+			const out: Record<string, unknown> = {};
+			for (const k of Object.keys(v as object).sort()) {
+				if (k === "requestKey" || k === "singleFlight" || k === "fetch" || k === "signal") {
+					continue;
+				}
+				out[k] = sort((v as Record<string, unknown>)[k]);
+			}
+			return out;
+		}
+		return v;
+	};
+	try {
+		return JSON.stringify(sort(value));
+	} catch {
+		return String(value);
+	}
+}
+
 /**
  * A realtime record-change event delivered to subscription callbacks.
  * Mirrors PocketBase's RealtimeService result shape (`action` + `record`).
@@ -100,6 +130,7 @@ export class CollectionService<T = ApiRecord> {
 			cache,
 			ttl,
 			invalidate,
+			singleFlight,
 			params,
 			...queryParams
 		} = options ?? {};
@@ -124,6 +155,7 @@ export class CollectionService<T = ApiRecord> {
 				cache,
 				ttl,
 				invalidate,
+				singleFlight,
 				params,
 			} as RequestOptions,
 		);
@@ -139,6 +171,17 @@ export class CollectionService<T = ApiRecord> {
 		options?: Record<string, unknown> & RequestOptions,
 	): Promise<Array<T2>> {
 		const { batch = 1000, ...rest } = options ?? {};
+
+		// Build a stable request key for the whole full-list fetch (NOT per page,
+		// which would break dedup). Concurrent identical getFullList() calls share
+		// this key via single-flight, so they don't fire duplicate requests. Pages
+		// still advance correctly: each page's URL differs (page=N in the query),
+		// so the underlying default key is unique per page — no cross-page cancel.
+		const effectiveKey =
+			typeof rest.requestKey === "string"
+				? rest.requestKey
+				: `getFullList:${this.collectionName}:${stableStringify(rest)}`;
+
 		const items: T2[] = [];
 		let page = 1;
 		for (;;) {
@@ -146,9 +189,9 @@ export class CollectionService<T = ApiRecord> {
 				page,
 				batch as number,
 				{
-					// disable auto-cancellation across pages — each page request is unique
 					...rest,
-					requestKey: null,
+					requestKey: effectiveKey,
+					singleFlight: true,
 				} as Record<string, unknown> & RequestOptions,
 			);
 			if (!res || !res.items || res.items.length === 0) break;

package/src/collections.ts

@@ -12,6 +12,7 @@
 
 import type { HttpClient } from "./http";
 import type { RealtimeService } from "./realtime";
+import { stableStringify } from "./collection";
 import type { ListResult, RequestOptions, ApiRecord } from "./types";
 
 const REGISTRY_TOPIC = "collections";
@@ -74,15 +75,50 @@ export class CollectionsService {
 	): Promise<Array<T>> {
 		if (!this.http) return [];
 		const { batch = 1000, ...rest } = options ?? {};
+
+		// Extract request-transport options so they never leak into query params.
+		const {
+			requestKey: reqKey,
+			singleFlight: _singleFlight,
+			fetch: fetchFn,
+			headers: hdrs,
+			signal: sig,
+			cache: cacheOpt,
+			ttl: ttlOpt,
+			invalidate: inval,
+			params: passthroughParams,
+			...queryParams
+		} = rest as Record<string, unknown> & RequestOptions;
+
+		// Stable key for the whole full-list fetch — see CollectionService.getFullList
+		// for the rationale (single-flight dedup, per-page paths stay unique).
+		const effectiveKey =
+			typeof reqKey === "string"
+				? reqKey
+				: `getFullList:collections:${stableStringify(rest)}`;
+
 		const items: T[] = [];
 		let page = 1;
 		// Auto-paginate until empty (bounded by perPage and totalPages).
 		for (;;) {
-			const res = await this.getList<T>({
-				...rest,
-				page,
-				perPage: batch,
-			} as Record<string, unknown>);
+			const res = await this.getList<T>(
+				{
+					...queryParams,
+					...(passthroughParams ?? {}),
+					page,
+					perPage: batch,
+				},
+				{
+					requestKey: effectiveKey,
+					singleFlight: true,
+					...(fetchFn ? { fetch: fetchFn } : {}),
+					...(hdrs ? { headers: hdrs } : {}),
+					...(sig ? { signal: sig } : {}),
+					...(cacheOpt !== undefined ? { cache: cacheOpt } : {}),
+					...(ttlOpt !== undefined ? { ttl: ttlOpt } : {}),
+					...(inval ? { invalidate: inval } : {}),
+				} as RequestOptions,
+			);
 			if (!res || !res.items || res.items.length === 0) break;
 			items.push(...(res.items as T[]));
 			if (page >= (res.totalPages ?? page)) break;

package/src/http.ts

@@ -34,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;
 
@@ -200,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).
@@ -221,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();

package/src/types.ts

@@ -99,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 {