@craftainer/crud-sdk 0.7.1 → 0.8.1

package/README.md

@@ -127,7 +127,7 @@ await heroes.update(1, { name: "Ada" }, { ifMatch: etag }); // 412 -> Preconditi
     return next({ ...ctx, request: new Request(ctx.request, { headers }) });
   };
   const client = createClient({
-    baseUrl: "/api/crud",
+    baseUrl: `${location.origin}/api/crud`, // absolute: a relative baseUrl throws
     credentials: "same-origin", // sends the session cookie
     cacheScope: () => currentUser.sub, // string, or sync/async function
     onUnauthorized: () => location.assign("/bff/login"),
@@ -164,6 +164,16 @@ await heroes.update(1, { name: "Ada" }, { ifMatch: etag }); // 412 -> Preconditi
     property.
   - There is no `headers` option: add static headers such as `X-CSRF` with a
     middleware, as above.
+  - **Logout and user switch.** The SDK does not notice that the session
+    changed. On logout, or whenever the `cacheScope` value changes, the app
+    must call `cache.clear()` (the `./cache` object; this also drops the
+    remembered `If-Match` validators and, with `IndexedDbStore`, the persisted
+    entries) and tear down its event streams (call every unsubscribe function
+    that `subscribeEvents` / `invalidateOnEvents` returned, or reload the page), so the next user neither reads the previous
+    user's data nor receives events from the previous user's stream.
+  - `Error.message` is bounded (server `detail` is cut at 200 characters, the
+    URL has no query string); the full text stays on `.detail` / `.errors`.
+    Treat it as a diagnostic, not as text to show to users.
 
 - **Middleware.** > [!WARNING]
   > Middleware must carry context fields through: build the next context with
@@ -226,6 +236,12 @@ objects, snake_case members).
   as a read answered `404`/`410` does. A bulk write of unknown outcome clears
   the whole resource, as its ids are not known. A write aborted before it
   was sent clears nothing.
+- A `no-store` response (the BFF default) is never stored, but its `ETag` is
+  remembered per record and scope (an LRU of 1024) for `If-Match` only:
+  `cachedEtag` and `autoIfMatch` use it, a read never does. A newer `ETag`
+  replaces it; a write, `412`, `404`/`410`, `DELETE`, an SSE invalidation,
+  `clear` or a scope switch drops it (see
+  [ADR 0004](docs/adrs/0004-remember-validators-of-no-store-responses.md)).
 - Wire the stream with `invalidateOnEvents(cache, getEventHub({ fetch, url,
 events }), "heroes")`; `fetch` must be authenticated. Events invalidate and
   never apply snapshots. `subscribeEvents` is the lower-level entry.
@@ -237,6 +253,10 @@ events }), "heroes")`; `fetch` must be authenticated. Events invalidate and
   same manifest `events` object to every subscriber of one stream.
 - A `keepalive_seconds` that is zero, negative or not finite is treated as
   unset: the 15 s default applies (a stream silent for three intervals is dead).
+  The timer keeps running while handlers do and restarts per event, so a
+  handler that takes longer than the dead interval (never settles, say)
+  ends the connection (the hub reconnects). A line or event longer than 1 MiB
+  also ends it.
 - Stores: `MemoryStore` (LRU) and `IndexedDbStore` (store failures are a miss).
   `IndexedDbStore` keeps an `expiresAt` index (database version 2; a version 1
   database upgrades in place and keeps its entries), deletes every expired

package/dist/cache/index.mjs

@@ -1,5 +1,5 @@
 import { n as cacheScope, t as ANON } from "../auth-C5__H0Ln.mjs";
-import { a as tanstackCachePolicy, i as cachePolicyFromManifest, n as subscribeEvents, r as resetOnce, t as getEventHub } from "../events-Dfz-rzC8.mjs";
+import { a as tanstackCachePolicy, i as cachePolicyFromManifest, n as subscribeEvents, r as resetOnce, t as getEventHub } from "../events-swCOTQOS.mjs";
 //#region src/cache/entry.ts
 const statuses = /* @__PURE__ */ new WeakMap();
 /**
@@ -189,6 +189,8 @@ async function contextScope(ctx) {
 //#endregion
 //#region src/cache/middleware.ts
 const MIN_RETENTION_MS = 36e5;
+/** Bound on remembered validators (LRU), the same as `MemoryStore`'s default size. */
+const MAX_VALIDATORS = 1024;
 const MANIFEST_POLICY = cachePolicyFromManifest({});
 const WRITE_METHODS = /* @__PURE__ */ new Set([
 	"POST",
@@ -249,6 +251,24 @@ function createCache(options) {
 	const inflight = /* @__PURE__ */ new Set();
 	const tasks = /* @__PURE__ */ new Set();
 	const background = new AbortController();
+	/**
+	* The last ETag seen per record key from any successful response, `no-store`
+	* included. RFC 9111 forbids storing such a response, not reading its
+	* validator, and the validator is used only for `If-Match` (`cachedEtag`,
+	* `autoIfMatch`), never to serve or revalidate content. Map order is the
+	* recency order. Keys carry the caller scope, so scopes stay isolated;
+	* cleared by the same prefixes as the store.
+	*/
+	const validators = /* @__PURE__ */ new Map();
+	const rememberValidator = (key, etag) => {
+		validators.delete(key);
+		if (etag === void 0) return;
+		validators.set(key, etag);
+		while (validators.size > MAX_VALIDATORS) validators.delete(validators.keys().next().value);
+	};
+	const forgetValidators = (prefixes) => {
+		for (const key of validators.keys()) if (prefixes === void 0 || prefixes.some((prefix) => key.startsWith(prefix))) validators.delete(key);
+	};
 	let globalGeneration = 0;
 	const generation = (resource) => (generations.get(resource ?? "") ?? 0) + globalGeneration;
 	const bump = (resource) => {
@@ -365,6 +385,12 @@ function createCache(options) {
 		]);
 		return clears([...names].sort().map((name) => kindPrefix(name, "filters")));
 	};
+	/** The validator op for a record read or write response (none for other kinds). */
+	const validatorOps = (state, response, key) => [{
+		type: "validator",
+		key,
+		etag: state.policy.etag ? response.headers.get("etag") ?? void 0 : void 0
+	}];
 	const readPlan = (state, response, body) => {
 		const key = state.key;
 		const kind = state.kind;
@@ -372,6 +398,13 @@ function createCache(options) {
 		const at = now();
 		const { fresh, stale } = entryTimes(state, kind);
 		const old = state.entry;
+		const vkey = buildKey({
+			resource: state.ctx.resource,
+			kind: "record",
+			recordId: state.ctx.recordId,
+			scope: state.scope,
+			apiVersion: state.ctx.apiVersion
+		});
 		if (status === 304 && state.validated === true && old !== void 0) {
 			const updated = {
 				...old,
@@ -388,7 +421,11 @@ function createCache(options) {
 					key,
 					entry: updated,
 					ttlMs: retentionMs(fresh, stale)
-				}]
+				}, ...kind === "record" ? [{
+					type: "validator",
+					key: vkey,
+					etag: updated.etag
+				}] : []]
 			};
 		}
 		if (status === 200 && body !== void 0) {
@@ -410,7 +447,7 @@ function createCache(options) {
 				key,
 				entry,
 				ttlMs: retentionMs(fresh, stale)
-			}];
+			}, ...kind === "record" ? validatorOps(state, response, vkey) : []];
 			if (kind === "manifest") ops.push(...manifestOps(old, entry));
 			return {
 				result: response,
@@ -422,7 +459,7 @@ function createCache(options) {
 			ops: [{
 				type: "delete",
 				key
-			}]
+			}, ...kind === "record" && status === 200 ? validatorOps(state, response, vkey) : []]
 		};
 		return {
 			result: response,
@@ -473,7 +510,13 @@ function createCache(options) {
 			...collections,
 			revisionsPrefix(resource, recordId),
 			recordPrefix(resource, recordId)
-		]), ...op === "update" && response !== void 0 && ok ? writeThrough(state, response, body, resource, recordId) : []];
+		]), ...op === "update" && response !== void 0 && ok ? [...writeThrough(state, response, body, resource, recordId), ...validatorOps(state, response, buildKey({
+			resource,
+			kind: "record",
+			recordId,
+			scope: state.scope,
+			apiVersion: state.ctx.apiVersion
+		}))] : []];
 		if (ok && (BULK_OPS.has(op) || op === "restore")) {
 			const ids = idsFromBody(body);
 			if (ids !== void 0) return clears([...collections, ...ids.flatMap((id) => [recordPrefix(resource, id), revisionsPrefix(resource, id)])]);
@@ -482,13 +525,19 @@ function createCache(options) {
 	};
 	/** One pass when the store can, else one `clear` per prefix; a failure is a miss. */
 	const clearPrefixes = async (prefixes) => {
+		forgetValidators(prefixes);
 		if (store.clearMany !== void 0) {
 			await safe(() => store.clearMany?.(prefixes));
 			return;
 		}
 		for (const prefix of prefixes) await safe(() => store.clear(prefix));
 	};
-	const apply = async (op) => {
+	const apply = async (op, keepValidator = false) => {
+		if (op.type === "validator") {
+			rememberValidator(op.key, op.etag);
+			return;
+		}
+		if (op.type === "delete" && !keepValidator) validators.delete(op.key);
 		await safe(() => op.type === "clear" ? clearPrefixes(op.prefixes) : op.type === "set" ? store.set(op.key, op.entry, op.ttlMs) : store.delete(op.key));
 	};
 	/** Plan, then apply, the store changes a response calls for. */
@@ -505,8 +554,12 @@ function createCache(options) {
 	const applyOps = async (state, ops) => {
 		if (state.kind === void 0 && ops.some((op) => op.type === "clear")) bump(state.ctx.resource);
 		const expected = generation(state.ctx.resource);
-		for (const op of ops) await apply(op);
-		if (generation(state.ctx.resource) !== expected) for (const op of ops.filter((candidate) => candidate.type === "set")) await apply({
+		const stale = state.kind !== void 0 && expected !== state.generation;
+		for (const op of ops) {
+			if (stale && op.type === "validator") continue;
+			await apply(op, stale);
+		}
+		if (generation(state.ctx.resource) !== expected) for (const op of ops.filter((candidate) => candidate.type !== "clear")) await apply({
 			type: "delete",
 			key: op.key
 		});
@@ -588,13 +641,19 @@ function createCache(options) {
 		return next(ctx);
 	};
 	const lookupEtag = async (resource, recordId, scope, apiVersion) => {
-		return (await safe(() => store.get(buildKey({
+		const key = buildKey({
 			resource,
 			kind: "record",
 			recordId,
 			scope,
 			apiVersion
-		}))))?.etag;
+		});
+		const remembered = validators.get(key);
+		if (remembered !== void 0) {
+			rememberValidator(key, remembered);
+			return remembered;
+		}
+		return (await safe(() => store.get(key)))?.etag;
 	};
 	return {
 		middleware,
@@ -614,6 +673,7 @@ function createCache(options) {
 		},
 		async clear(prefix) {
 			globalGeneration += 1;
+			forgetValidators(prefix === void 0 ? void 0 : [prefix]);
 			await safe(() => store.clear(prefix));
 		},
 		cachedEtag: lookupEtag,