@wocart/storefront 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 1.1.0 — 2026-10-14
+
+### Fixed
+
+- **A read never waits on another read's pending request.** The client used to
+  merge an identical read with one already in flight, and its opt-in caches
+  held the pending request itself. A client kept across requests (one per
+  isolate) could therefore make a request wait on a read another request had
+  started; on Cloudflare Workers that read never settles once the request
+  that started it is cancelled (a shopper leaving mid-load, a navigation
+  interrupted by a click), and every later request for the same URL hung.
+  Each call now makes its own request, and the caches keep finished values
+  only.
+
+### Added
+
+- **`readTimeoutMs`** on `createStoreClient` bounds every read, retries
+  included: 10 000 ms by default, `0` for no limit. A read that runs out of
+  time degrades like any failed read and reports `REQUEST_TIMEOUT` to
+  `onError`, so a server that stops answering costs a page seconds instead of
+  holding it open. Writes keep no default limit: a write cut off by a timer
+  may already have happened.
+
+### Changed
+
+- Parallel identical reads are no longer coalesced into one request. A page
+  that asks for the same data from several places should ask once and share
+  the result within its render.
+
 ## 1.0.0 — 2026-10-13
 
 The first public release.

package/README.md

@@ -115,6 +115,7 @@ import { createBasketStore, formatMoney } from "@wocart/storefront";
 | `locale` | no | read merchant text in a published store language (`"fr"`); one client per language |
 | `theme` | no | your theme's key (`defineTheme({ key })`), to receive the merchant's edits to your theme's text |
 | `onError` | no | observability hook for degraded reads |
+| `readTimeoutMs` | no | how long one read may take, retries included, before it degrades (default 10 000; `0` for no limit) |
 
 A storefront deployed by Wocart receives its origin and key as the
 `COD_SERVER_URL` and `STORE_API_KEY` environment variables. The SDK reads no

package/USAGE.md

@@ -162,9 +162,11 @@ const [config, featuredProducts] = await Promise.all([
 ]);
 ~~~
 
-Parallel identical GET requests made through the same client are coalesced.
-That makes it safe for independent page loaders to ask for the same
-configuration without manually coordinating them.
+Every call makes its own request; a call never waits on another call's
+pending request, even an identical one. Within one render, ask once and share
+the result (`Promise.all`, or a per-request memo) when several parts of a page
+need the same data. A client never holds pending work across calls, so one
+kept for several requests cannot leave a request waiting on another's read.
 
 ### Available imports
 
@@ -438,10 +440,13 @@ conversion event.
 
 ### Caching and retries
 
-- GET requests are fresh by default.
-- Parallel identical GET requests are deduplicated per client instance.
-- config.get(), categories.list(), and geo.communes() use the client
-  lifetime cache after a successful response.
+- GET requests are fresh by default, and each call makes its own request.
+- config.get(), categories.list(), and geo.communes() keep their finished
+  result for the client's lifetime; a call made while the first is still
+  pending makes its own request rather than waiting on it.
+- Every read is bounded by `readTimeoutMs` (10 seconds by default), retries
+  included; a read that runs out of time degrades and reports
+  `REQUEST_TIMEOUT` to `onError`. Writes have no default limit.
 - null results and failures are not cached, so a temporary failure can recover
   on the next call.
 - GET network failures use two short exponential backoff retries.

package/dist/client/core.d.ts

@@ -17,8 +17,8 @@ export type ClientConfig = StoreScope;
 /**
  * Options every request accepts.
  *
- * `signal` cancels the request — an aborted call never retries, never coalesces
- * with another caller's request, and returns a REQUEST_ABORTED DomainError
+ * `signal` cancels the request — an aborted call never retries, is never
+ * cached, and returns a REQUEST_ABORTED DomainError
  * (a read throws instead). `timeoutMs` bounds the whole operation, retries
  * included, and reads as REQUEST_TIMEOUT. `operation` names the call in the
  * error it produces; namespaces pass a stable label (`orders.otp.send`) so logs
@@ -61,6 +61,8 @@ export interface ClientCore {
     post: <TInput, TOutput>(path: string, body: TInput, opts?: PostOptions<TOutput>) => Promise<ClientResult<TOutput>>;
     patch: <TInput, TOutput>(path: string, body: TInput, optsOrSchema?: z.Schema<TOutput> | PatchOptions<TOutput>) => Promise<ClientResult<TOutput>>;
 }
+/** How long a read may take, retries included, unless the client sets another limit. */
+export declare const DEFAULT_READ_TIMEOUT_MS = 10000;
 /**
  * Create client core infrastructure
  *

package/dist/client/core.js

@@ -237,6 +237,14 @@ async function readBody(response) {
         return { ok: false };
     }
 }
+/** How long a read may take, retries included, unless the client sets another limit. */
+export const DEFAULT_READ_TIMEOUT_MS = 10_000;
+/** A positive limit is used as given; `0` means no limit; anything else falls back to the default. */
+function resolveReadTimeout(value) {
+    if (value === 0)
+        return undefined;
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : DEFAULT_READ_TIMEOUT_MS;
+}
 /**
  * Create client core infrastructure
  *
@@ -245,14 +253,17 @@ async function readBody(response) {
  */
 export function createClientCore(config) {
     const { serverUrl, apiKey } = config;
-    const requestCache = new Map();
-    const inflightRequests = new Map();
+    const readTimeoutMs = resolveReadTimeout(config.readTimeoutMs);
+    // Finished values only, never a pending request. A client may outlive the
+    // request that made it (one per isolate); a request that waits on another
+    // request's pending read never settles on Cloudflare Workers once that other
+    // request is cancelled, and every later caller would wait behind it.
+    const valueCache = new Map();
     let observedCacheGeneration = cacheGeneration;
     function resetClearedCaches() {
         if (observedCacheGeneration === cacheGeneration)
             return;
-        requestCache.clear();
-        inflightRequests.clear();
+        valueCache.clear();
         observedCacheGeneration = cacheGeneration;
     }
     /**
@@ -301,107 +312,80 @@ export function createClientCore(config) {
         throw lastError ?? new Error("Network error");
     }
     /**
-     * GET request with in-flight deduplication and opt-in caching.
+     * GET request with opt-in caching.
      *
-     * Default behaviour: every call fetches fresh,
-     * but parallel identical calls coalesce into one request. Pass
-     * `{ cache: true }` for read-mostly data (config, categories, geo).
+     * Every call makes its own request: a call never waits on another call's
+     * pending request, so no caller can be held by work that belongs to someone
+     * else. Pass `{ cache: true }` for read-mostly data (config, categories,
+     * geo): the finished value is kept and later calls reuse it.
      *
      * Rejected and nullish results are never cached — a transient failure
      * or an absent record must not be pinned for the isolate's lifetime.
      *
+     * A read is bounded by the client's `readTimeoutMs` (10 seconds unless the
+     * client sets another), retries included, so a server that stops answering
+     * degrades the read instead of holding the page.
+     *
      * Pass `{ envelope: true }` for endpoints that carry metadata outside
      * `data` (e.g. pagination totals) and need the full response body.
      *
      * A failing read never resolves to a wrong value: it throws a
      * `StorefrontError` carrying the same `DomainError` the mutation path
-     * returns. A cancelled or timed-out read neither retries nor coalesces —
-     * one caller's abort must not cancel another's request, and an abandoned
-     * request must not be pinned in the cache.
+     * returns. A read the caller cancels never retries and is never cached.
      */
     async function get(path, schema, opts) {
         resetClearedCaches();
         const url = buildUrl(path);
         const operation = opts?.operation ?? `GET ${path}`;
-        const request = composeSignal(opts?.signal, opts?.timeoutMs);
-        const shared = request.signal === undefined;
+        const request = composeSignal(opts?.signal, opts?.timeoutMs ?? readTimeoutMs);
+        // A caller-supplied signal opts the read out of retries and the cache: its
+        // abort is the caller's decision, and an abandoned read must not be kept.
+        const callerCancels = opts?.signal !== undefined;
+        const cacheable = opts?.cache === true && !callerCancels;
         try {
-            // Check cache first (only successful results ever live here)
-            if (opts?.cache && shared) {
-                const cached = requestCache.get(url);
-                if (cached) {
-                    return (await cached);
-                }
-            }
-            // Check in-flight requests for deduplication
-            if (shared) {
-                const inflight = inflightRequests.get(url);
-                if (inflight) {
-                    return (await inflight);
-                }
+            if (cacheable && valueCache.has(url)) {
+                return valueCache.get(url);
             }
-            // Create new request
-            const requestPromise = (async () => {
-                try {
-                    const response = await fetchWithRetry(url, {
-                        method: "GET",
-                        headers: buildHeaders(),
-                        ...(request.signal ? { signal: request.signal } : {}),
-                    }, shared ? 2 : 0, request.signal);
-                    if (!response.ok) {
-                        const body = await readBody(response);
-                        throw new StorefrontError(serverFailure(response.status, body.ok ? body.value : undefined, operation, true)
-                            .domainError);
-                    }
+            const value = await (async () => {
+                const response = await fetchWithRetry(url, {
+                    method: "GET",
+                    headers: buildHeaders(),
+                    ...(request.signal ? { signal: request.signal } : {}),
+                }, callerCancels ? 0 : 2, request.signal);
+                if (!response.ok) {
                     const body = await readBody(response);
-                    if (!body.ok) {
-                        throw new StorefrontError(unreadableSuccess("MALFORMED_RESPONSE", MALFORMED_MESSAGE, operation, true));
-                    }
-                    const json = body.value;
-                    if (opts?.envelope) {
-                        if (schema) {
-                            const parsed = schema.safeParse(json);
-                            if (!parsed.success) {
-                                throw new StorefrontError(unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, true));
-                            }
-                            return parsed.data;
-                        }
-                        return json;
-                    }
-                    const data = isRecord(json) ? json.data : undefined;
-                    // Validate with schema if provided
+                    throw new StorefrontError(serverFailure(response.status, body.ok ? body.value : undefined, operation, true)
+                        .domainError);
+                }
+                const body = await readBody(response);
+                if (!body.ok) {
+                    throw new StorefrontError(unreadableSuccess("MALFORMED_RESPONSE", MALFORMED_MESSAGE, operation, true));
+                }
+                const json = body.value;
+                if (opts?.envelope) {
                     if (schema) {
-                        const parsed = schema.safeParse(data);
+                        const parsed = schema.safeParse(json);
                         if (!parsed.success) {
                             throw new StorefrontError(unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, true));
                         }
                         return parsed.data;
                     }
-                    return data;
+                    return json;
                 }
-                finally {
-                    // Remove from inflight after completion
-                    if (shared) {
-                        inflightRequests.delete(url);
+                const data = isRecord(json) ? json.data : undefined;
+                // Validate with schema if provided
+                if (schema) {
+                    const parsed = schema.safeParse(data);
+                    if (!parsed.success) {
+                        throw new StorefrontError(unreadableSuccess("SCHEMA_VALIDATION_FAILED", SCHEMA_MESSAGE, operation, true));
                     }
+                    return parsed.data;
                 }
+                return data;
             })();
-            // Store in-flight so parallel callers coalesce (only when no individual signal)
-            if (shared) {
-                inflightRequests.set(url, requestPromise);
-            }
-            if (opts?.cache && shared) {
-                requestCache.set(url, requestPromise);
-                // A failed or empty lookup must not be pinned: evict so the next
-                // call retries against the server.
-                requestPromise.then((value) => {
-                    if (value == null)
-                        requestCache.delete(url);
-                }, () => {
-                    requestCache.delete(url);
-                });
-            }
-            return await requestPromise;
+            if (cacheable && value != null)
+                valueCache.set(url, value);
+            return value;
         }
         catch (error) {
             if (error instanceof StorefrontError)

package/dist/client/index.d.ts

@@ -5,9 +5,10 @@
  * shared core: config, products, categories, pages, shipping, geo, cart,
  * orders. The core is internal — consumers see only namespaces.
  *
- * One core means one connection story for every namespace: identical
- * parallel GETs coalesce into a single upstream request, and the opt-in
- * caches (config, categories, communes) are shared per client instance.
+ * One core means one connection story for every namespace: every read is
+ * bounded by the client's `readTimeoutMs`, each call makes its own request
+ * (none waits on another's pending one), and the opt-in caches (config,
+ * categories, communes) keep finished results per client instance.
  * A theme server render typically builds one client per request.
  *
  * ```ts

package/dist/client/index.js

@@ -5,9 +5,10 @@
  * shared core: config, products, categories, pages, shipping, geo, cart,
  * orders. The core is internal — consumers see only namespaces.
  *
- * One core means one connection story for every namespace: identical
- * parallel GETs coalesce into a single upstream request, and the opt-in
- * caches (config, categories, communes) are shared per client instance.
+ * One core means one connection story for every namespace: every read is
+ * bounded by the client's `readTimeoutMs`, each call makes its own request
+ * (none waits on another's pending one), and the opt-in caches (config,
+ * categories, communes) keep finished results per client instance.
  * A theme server render typically builds one client per request.
  *
  * ```ts

package/dist/client/page-data.d.ts

@@ -12,8 +12,7 @@
  * newer document's instances reach the theme verbatim.
  *
  * Fetched fresh on every call (no process-lifetime cache — a save must reach
- * the next render, subject only to the theme's route cache); identical
- * parallel calls coalesce into one request like every other read.
+ * the next render, subject only to the theme's route cache).
  */
 import { type ClientCore } from "./core.js";
 import type { PageDocumentPayload } from "../types.js";

package/dist/client/page-data.js

@@ -12,8 +12,7 @@
  * newer document's instances reach the theme verbatim.
  *
  * Fetched fresh on every call (no process-lifetime cache — a save must reach
- * the next render, subject only to the theme's route cache); identical
- * parallel calls coalesce into one request like every other read.
+ * the next render, subject only to the theme's route cache).
  */
 import { PageDocumentPayloadSchema } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../domain.js";

package/dist/client/pages.d.ts

@@ -3,7 +3,7 @@
  *
  * Deep module: hides URL construction, slug encoding, and transport behind
  * two calls. Pages are fetched fresh every request (a merchant edit is live
- * on the next render); parallel identical calls coalesce into one request.
+ * on the next render).
  *
  * Failure contracts:
  * - `get(slug)` → null means "not published" — the theme 404s, never a

package/dist/client/pages.js

@@ -3,7 +3,7 @@
  *
  * Deep module: hides URL construction, slug encoding, and transport behind
  * two calls. Pages are fetched fresh every request (a merchant edit is live
- * on the next render); parallel identical calls coalesce into one request.
+ * on the next render).
  *
  * Failure contracts:
  * - `get(slug)` → null means "not published" — the theme 404s, never a

package/dist/client/shipping.d.ts

@@ -6,8 +6,7 @@
  * a single wilaya's pair when the caller only needs one.
  *
  * Fetched fresh every request (merchants adjust delivery pricing and expect
- * the next render to show it); parallel identical calls coalesce into one
- * request.
+ * the next render to show it).
  *
  * Failure contract: resolves to `{}` /
  * `null` on any failure — never throws. Absent wilayas have no rule and are

package/dist/client/shipping.js

@@ -6,8 +6,7 @@
  * a single wilaya's pair when the caller only needs one.
  *
  * Fetched fresh every request (merchants adjust delivery pricing and expect
- * the next render to show it); parallel identical calls coalesce into one
- * request.
+ * the next render to show it).
  *
  * Failure contract: resolves to `{}` /
  * `null` on any failure — never throws. Absent wilayas have no rule and are

package/dist/domain.d.ts

@@ -35,6 +35,15 @@ export interface StoreScope {
      * success.
      */
     onError?: (error: DomainError) => void;
+    /**
+     * How long one read may take, retries included, before it gives up: the read
+     * then degrades like any other failed read and `onError` receives a
+     * `REQUEST_TIMEOUT`. A server that stops answering costs a page this long
+     * instead of holding it open. Defaults to 10 000 ms; `0` removes the limit.
+     * Writes have no default limit: a write cut off by a timer may already have
+     * happened, and retrying it could place the same order twice.
+     */
+    readonly readTimeoutMs?: number;
 }
 /** The server's hard limits for one canonical browser basket. */
 export declare const MAX_BASKET_LINES: 20;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",