@craftainer/crud-sdk 0.4.0 → 0.5.0

package/README.md

@@ -51,7 +51,9 @@ await heroes.update(1, { name: "Ada" }, { ifMatch: etag }); // 412 -> Preconditi
 
 - **Discovery.** The manifest loads on first use through
   `/.well-known/api-catalog` (the `describedby` link with the manifest
-  profile), or from `manifestUrl`. Manifest types keep the wire member names
+  profile), or from `manifestUrl`. `client.manifest({ refresh: true })`
+  reloads it; if the reload fails the error is thrown and the last good
+  manifest stays cached. Manifest types keep the wire member names
   (`skip_param`, `max_age`, ...) and ignore unknown members.
 - **Same origin.** The client sends the token to every URL it builds, so a
   manifest `base_path`, `paths.*` or `events.path` that resolves to another
@@ -61,6 +63,20 @@ await heroes.update(1, { name: "Ada" }, { ifMatch: etag }); // 412 -> Preconditi
   (exact origins: scheme, host and port; an entry that is not an http(s)
   origin throws at `createClient`). The same rule already applies to the
   api-catalog's manifest link.
+- **Plain http.** A request that carries an `Authorization` header is
+  refused with `InsecureTransportError` (a `ClientError`, thrown before
+  anything is sent) when its URL is `http:` and the host is not loopback
+  (`localhost`, `*.localhost`, `127.0.0.0/8`, `[::1]`, judged on the parsed
+  hostname). The check runs on the request as it is sent, so a middleware that
+  rewrites the URL or sets its own `Authorization` is covered. Anonymous
+  requests over http are unaffected. To allow it on a trusted network, pass
+  `createClient({ baseUrl, allowInsecureHttp: true })`; the codegen CLI has
+  `--allow-insecure-http` for `CRUD_SDK_TOKEN`. On a redirect, `fetch` drops
+  `Authorization` when the target origin differs (scheme, host or port: so an
+  `https:` to `http:` downgrade drops it too, per the WHATWG Fetch
+  "HTTP-redirect fetch" step); this relies on the `fetch` you pass behaving
+  to spec. `events` streams use the `fetch` you hand to `getEventHub`, which
+  the SDK does not wrap: make that `fetch` the client's authenticated one.
 - **Operations** (each gated on the manifest's capabilities and `paths`,
   else `CapabilityError`): `list`, `iterAll`, `get`, `create`, `update`,
   `updateMany`, `delete`, `deleteMany`, `restore({ id } | { filters })`,
@@ -132,10 +148,34 @@ objects, snake_case members).
   Every connection clears the resource once per cache, including for a
   subscription that joins an already connected stream, which clears before
   its gate opens.
+- A write clears what it touches when it succeeds. A write whose outcome is
+  unknown (the request threw, or the answer was `5xx`) clears the same, since
+  the server may have applied it; a refused write (any other status below `500`) clears
+  nothing, except `412`, which evicts the record. 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.
 - 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.
+- One hub serves every subscriber of the same `(fetch, url)`, and the first
+  subscriber's `events` options win. A later subscriber's differing
+  `resource`, `resume_param`, `replay` or `keepalive_seconds` is ignored; in
+  development (`process.env.NODE_ENV !== "production"`, or when there is no
+  `process`) it gets a `console.warn` naming the URL and the fields. Pass the
+  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).
 - 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
+  entry once when it opens the database, and takes an optional
+  `maxEntries` (a positive integer, default unbounded): a `set` that leaves
+  more entries than that deletes the ones with the earliest `expiresAt` until
+  the cap holds, a just-written short-ttl entry included. Without
+  `maxEntries` nothing but the open-time sweep and per-read expiry removes
+  entries. An older release of the package cannot open a version 2 database
+  (the browser refuses to downgrade); give the new release a fresh `name` if
+  both must coexist.
   `clearMany(prefixes)` is optional on a custom `CacheStore`.
 - `cacheStatus(response)` says `hit`, `stale`, `revalidated` or `miss`;
   `cache.close()` stops background refreshes.
@@ -183,6 +223,15 @@ which returns `{ queryKey }` or `{ predicate }` to spread into
 `invalidateQueries`/`removeQueries`. Mutations and `bridgeEvents` invalidate
 every scope of the client's resource, since a write changes what every caller sees.
 
+The `create`/`update`/`deleteMutationOptions` follow TanStack's "always
+refetch after error or success": `onSettled` invalidates collections (lists,
+stats, predict) and revisions on both outcomes, so a write that failed with a
+`5xx` or a dropped connection (and may have been applied) is refetched too. A
+failed update or delete also invalidates the record's own query. `onSuccess`
+only does `setQueryData` (update) or `removeQueries` (delete), so nothing is
+invalidated twice. If you spread the options into `useMutation` and add your own
+`onSettled`, call the factory's first.
+
 ```ts
 import { createClient } from "@craftainer/crud-sdk";
 import {

package/dist/{auth-DwtNEKrw.mjs → auth-C5__H0Ln.mjs}

@@ -16,7 +16,19 @@ async function cacheScope(token) {
 function staticToken(token) {
 	return () => token;
 }
+/**
+* Whether `url` is plain `http:` to a host that is not loopback. Loopback is
+* `localhost`, `*.localhost`, `127.0.0.0/8` and `[::1]`, judged on the parsed
+* hostname (so `http://localhost.evil.example` is not loopback). `https:` and
+* any other scheme are never insecure here.
+*/
+function isInsecureRemote(url) {
+	const { protocol, hostname } = new URL(url);
+	if (protocol !== "http:") return false;
+	const host = hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+	return !(host === "localhost" || host.endsWith(".localhost") || host === "[::1]" || /^127(?:\.\d{1,3}){3}$/.test(host));
+}
 //#endregion
-export { cacheScope as n, staticToken as r, ANON as t };
+export { staticToken as i, cacheScope as n, isInsecureRemote as r, ANON as t };
 
-//# sourceMappingURL=auth-DwtNEKrw.mjs.map
+//# sourceMappingURL=auth-C5__H0Ln.mjs.map

package/dist/auth-C5__H0Ln.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-C5__H0Ln.mjs","names":[],"sources":["../src/auth.ts"],"sourcesContent":["import type { TokenProvider } from \"./interfaces.ts\";\n\n/** The scope of an anonymous caller. */\nexport const ANON = \"anon\";\n\n/**\n * Cache scope of a caller: `\"anon\"`, or the first 32 hex characters of the\n * SHA-256 of the whole bearer token. Nothing in the token is trusted or\n * decoded (a forged `sub` must not select another caller's entries), and the\n * raw token never leaves this function.\n */\nexport async function cacheScope(\n  token: string | null | undefined,\n): Promise<string> {\n  if (token === null || token === undefined) {\n    return ANON;\n  }\n  const digest = await crypto.subtle.digest(\n    \"SHA-256\",\n    new TextEncoder().encode(token),\n  );\n  return Array.from(new Uint8Array(digest).subarray(0, 16), (byte) =>\n    byte.toString(16).padStart(2, \"0\"),\n  ).join(\"\");\n}\n\n/** A provider that always returns `token` (a refresh changes nothing). */\nexport function staticToken(token: string | null): TokenProvider {\n  return () => token;\n}\n\n/**\n * Whether `url` is plain `http:` to a host that is not loopback. Loopback is\n * `localhost`, `*.localhost`, `127.0.0.0/8` and `[::1]`, judged on the parsed\n * hostname (so `http://localhost.evil.example` is not loopback). `https:` and\n * any other scheme are never insecure here.\n */\nexport function isInsecureRemote(url: string): boolean {\n  const { protocol, hostname } = new URL(url);\n  if (protocol !== \"http:\") {\n    return false;\n  }\n  // WHATWG URL has already normalised numeric hosts (`127.1` -> `127.0.0.1`)\n  // and lower-cased the name; a trailing dot is the same host.\n  const host = hostname.endsWith(\".\") ? hostname.slice(0, -1) : hostname;\n  return !(\n    host === \"localhost\" ||\n    host.endsWith(\".localhost\") ||\n    host === \"[::1]\" ||\n    /^127(?:\\.\\d{1,3}){3}$/.test(host)\n  );\n}\n"],"mappings":";;AAGA,MAAa,OAAO;;;;;;;AAQpB,eAAsB,WACpB,OACiB;CACjB,IAAI,UAAU,QAAQ,UAAU,KAAA,GAC9B,OAAO;CAET,MAAM,SAAS,MAAM,OAAO,OAAO,OACjC,WACA,IAAI,YAAY,CAAC,CAAC,OAAO,KAAK,CAChC;CACA,OAAO,MAAM,KAAK,IAAI,WAAW,MAAM,CAAC,CAAC,SAAS,GAAG,EAAE,IAAI,SACzD,KAAK,SAAS,EAAE,CAAC,CAAC,SAAS,GAAG,GAAG,CACnC,CAAC,CAAC,KAAK,EAAE;AACX;;AAGA,SAAgB,YAAY,OAAqC;CAC/D,aAAa;AACf;;;;;;;AAQA,SAAgB,iBAAiB,KAAsB;CACrD,MAAM,EAAE,UAAU,aAAa,IAAI,IAAI,GAAG;CAC1C,IAAI,aAAa,SACf,OAAO;CAIT,MAAM,OAAO,SAAS,SAAS,GAAG,IAAI,SAAS,MAAM,GAAG,EAAE,IAAI;CAC9D,OAAO,EACL,SAAS,eACT,KAAK,SAAS,YAAY,KAC1B,SAAS,WACT,wBAAwB,KAAK,IAAI;AAErC"}

package/dist/cache/index.d.mts

@@ -1,5 +1,5 @@
 import { a as Middleware, i as MaybePromise, n as CacheStore, r as CrudEvent, t as CacheEntry } from "../interfaces-s73cVfIF.mjs";
-import { a as EventsConfig, c as subscribeEvents, d as cachePolicyFromManifest, f as tanstackCachePolicy, i as EventHubOptions, l as CachePolicy, n as EventHandlers, o as SubscribeEventsOptions, r as EventHub, s as getEventHub, t as EventConnection, u as ManifestCacheHints } from "../events-Bp__8_4V.mjs";
+import { a as EventsConfig, c as subscribeEvents, d as cachePolicyFromManifest, f as tanstackCachePolicy, i as EventHubOptions, l as CachePolicy, n as EventHandlers, o as SubscribeEventsOptions, r as EventHub, s as getEventHub, t as EventConnection, u as ManifestCacheHints } from "../events-DdT0AkNE.mjs";
 //#region src/cache/middleware.d.ts
 /**
  * A store may clear several prefixes in one pass (one walk, one transaction);
@@ -98,17 +98,36 @@ interface IndexedDbStoreOptions {
   /** Database name; default `craftainer-crud-cache`. */
   readonly name?: string;
   readonly defaultTtlMs?: number;
+  /**
+   * Upper bound on stored entries, a positive integer; default unbounded.
+   * When a `set` leaves more than this many, the entries with the earliest
+   * `expiresAt` are deleted until the cap holds (a just-written entry with a
+   * short ttl can be among them). The cap is per database and per store
+   * instance: two instances on one `name` with different caps each enforce
+   * their own on their writes.
+   */
+  readonly maxEntries?: number;
   /** Epoch milliseconds; injectable for tests. */
   readonly now?: () => number;
 }
 export declare class IndexedDbStore implements CacheStore {
   private readonly name;
   private readonly defaultTtlMs;
+  private readonly maxEntries;
   private readonly now;
   private opening;
   constructor(options?: IndexedDbStoreOptions);
   private open;
-  /** Run `work` on the database; a failure drops the handle (so a later call retries) and yields `fallback`. */
+  private openAndSweep;
+  /** Deletes every entry that has expired (`expiresAt <= now`). */
+  private sweep;
+  /**
+   * Run `work` on the database; a failure yields `fallback`. The handle is
+   * shared by every in-flight call, so it is dropped (and closed) only when it
+   * is itself unusable: it never opened, or it was closed under us
+   * (`InvalidStateError`). Any other failure belongs to one operation (an
+   * uncloneable value, a quota error) and leaves the handle to the others.
+   */
   private run;
   get(key: string): Promise<CacheEntry | undefined>;
   set(key: string, entry: CacheEntry, ttlMs?: number): Promise<void>;

package/dist/cache/index.mjs

@@ -1,5 +1,5 @@
-import { n as cacheScope, t as ANON } from "../auth-DwtNEKrw.mjs";
-import { a as tanstackCachePolicy, i as cachePolicyFromManifest, n as subscribeEvents, r as resetOnce, t as getEventHub } from "../events-DD5dodtF.mjs";
+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";
 //#region src/cache/entry.ts
 const statuses = /* @__PURE__ */ new WeakMap();
 /**
@@ -242,7 +242,7 @@ function createCache(options) {
 	let globalGeneration = 0;
 	const generation = (resource) => (generations.get(resource ?? "") ?? 0) + globalGeneration;
 	const bump = (resource) => {
-		generations.set(resource, generation(resource) + 1);
+		generations.set(resource, (generations.get(resource) ?? 0) + 1);
 	};
 	/**
 	* Whether an entry of `kind` may be served without the network right now:
@@ -442,20 +442,28 @@ function createCache(options) {
 			ttlMs: retentionMs(fresh, stale)
 		}];
 	};
+	/**
+	* The store changes a write calls for. `response` is `undefined` when the
+	* request threw: like a `5xx`, the outcome is unknown (the server may have
+	* applied the write before the failure), so it clears what a success would
+	* have, minus the write-through, and for a bulk op the whole resource (the
+	* ids are unknown). Other failures changed nothing.
+	*/
 	const writeOps = (state, response, body) => {
 		const { op, recordId } = state.ctx;
 		const resource = state.ctx.resource;
-		const { status } = response;
+		const status = response?.status;
 		if (status === 412) return recordId === void 0 ? [] : clears([recordPrefix(resource, recordId)]);
-		if (status < 200 || status >= 300) return [];
+		const ok = status !== void 0 && status >= 200 && status < 300;
+		if (!ok && status !== void 0 && status < 500) return [];
 		const collections = collectionPrefixes(resource);
 		if (CREATES.has(op)) return clears(collections);
 		if (recordId !== void 0 && (RECORD_WRITES.has(op) || op === "update")) return [...clears([
 			...collections,
 			revisionsPrefix(resource, recordId),
 			recordPrefix(resource, recordId)
-		]), ...op === "update" ? writeThrough(state, response, body, resource, recordId) : []];
-		if (BULK_OPS.has(op) || op === "restore") {
+		]), ...op === "update" && response !== void 0 && ok ? writeThrough(state, response, body, resource, recordId) : []];
+		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)])]);
 		}
@@ -479,6 +487,11 @@ function createCache(options) {
 			result: response,
 			ops: writeOps(state, response, body)
 		} : readPlan(state, response, body);
+		await applyOps(state, ops);
+		return result;
+	};
+	/** Apply `ops`, guarding against an invalidation that lands meanwhile. */
+	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);
@@ -486,7 +499,6 @@ function createCache(options) {
 			type: "delete",
 			key: op.key
 		});
-		return result;
 	};
 	const schedule = (state, next) => {
 		const key = state.key;
@@ -498,10 +510,10 @@ function createCache(options) {
 				const signal = background.signal;
 				const headers = new Headers(state.ctx.request.headers);
 				if (entry.etag !== void 0) headers.set("if-none-match", entry.etag);
-				const request = new Request(state.ctx.request.url, {
-					method: "GET",
+				const request = new Request(state.ctx.request, {
 					headers,
-					signal
+					signal,
+					cache: "no-store"
 				});
 				const fresh = {
 					...state,
@@ -523,7 +535,17 @@ function createCache(options) {
 	const middleware = async (ctx, next) => {
 		const state = await begin(ctx);
 		if (state === void 0) return next(ctx);
-		if (state.kind === void 0) return finish(state, await next(ctx));
+		if (state.kind === void 0) {
+			const unsent = ctx.request.signal.aborted;
+			let response;
+			try {
+				response = await next(ctx);
+			} catch (error) {
+				if (!unsent) await safe(() => applyOps(state, writeOps(state, void 0, void 0)));
+				throw error;
+			}
+			return finish(state, response);
+		}
 		state.entry = await safe(() => store.get(state.key));
 		const decision = decide(state, state.entry);
 		const entry = state.entry;
@@ -853,41 +875,102 @@ replaceTraps((oldTraps) => ({
 //#endregion
 //#region src/cache/idb.ts
 /**
-* IndexedDB cache store (one object store, out-of-line string keys).
+* IndexedDB cache store (one object store, out-of-line string keys, an
+* `expiresAt` index).
+*
+* Database version 2 adds the `expiresAt` index; upgrading from version 1
+* keeps every entry (the index is built over the stored values). Expired
+* entries are swept once when the database is opened, and `maxEntries` evicts
+* the entries closest to expiry on `set`.
 *
 * Every call is wrapped: a blocked database, private mode or a missing
 * `indexedDB` is a miss (or a no-op), never a failed request. `clear(prefix)`
 * is one `IDBKeyRange.bound(prefix, prefix + "\uffff")` delete.
 */
 const STORE = "entries";
+const BY_EXPIRY = "expiresAt";
+const VERSION = 2;
+/**
+* Observes `tx.done` up front: when an operation throws, the aborted
+* transaction's `done` rejects with nobody left to await it, which would be
+* an unhandled rejection.
+*/
+function guarded(tx) {
+	tx.done.catch(() => void 0);
+	return tx;
+}
+function isInvalidState(error) {
+	return typeof error === "object" && error !== null && error.name === "InvalidStateError";
+}
 var IndexedDbStore = class {
 	name;
 	defaultTtlMs;
+	maxEntries;
 	now;
 	opening;
 	constructor(options = {}) {
 		this.name = options.name ?? "craftainer-crud-cache";
 		if (this.name === "") throw new RangeError("IndexedDbStore: name must not be empty");
 		this.defaultTtlMs = options.defaultTtlMs ?? 36e5;
+		if (options.maxEntries !== void 0 && !(Number.isInteger(options.maxEntries) && options.maxEntries >= 1)) throw new RangeError("IndexedDbStore: maxEntries must be an integer >= 1");
+		this.maxEntries = options.maxEntries;
 		this.now = options.now ?? Date.now;
 	}
 	open() {
-		this.opening ??= openDB(this.name, 1, { upgrade(db) {
-			db.createObjectStore(STORE);
-		} });
+		if (this.opening === void 0) {
+			const opening = this.openAndSweep(() => {
+				if (this.opening === opening) this.opening = void 0;
+			});
+			this.opening = opening;
+		}
 		return this.opening;
 	}
-	/** Run `work` on the database; a failure drops the handle (so a later call retries) and yields `fallback`. */
+	async openAndSweep(onDropped) {
+		const db = await openDB(this.name, VERSION, {
+			blocking() {
+				db.close();
+				onDropped();
+			},
+			terminated: onDropped,
+			upgrade(upgrading, oldVersion, _newVersion, tx) {
+				if (oldVersion < 1) upgrading.createObjectStore(STORE);
+				tx.objectStore(STORE).createIndex(BY_EXPIRY, BY_EXPIRY);
+			}
+		});
+		try {
+			await this.sweep(db);
+		} catch {}
+		return db;
+	}
+	/** Deletes every entry that has expired (`expiresAt <= now`). */
+	async sweep(db) {
+		const tx = guarded(db.transaction(STORE, "readwrite"));
+		let cursor = await tx.store.index(BY_EXPIRY).openCursor(IDBKeyRange.upperBound(this.now()));
+		while (cursor !== null) {
+			await cursor.delete();
+			cursor = await cursor.continue();
+		}
+		await tx.done;
+	}
+	/**
+	* Run `work` on the database; a failure yields `fallback`. The handle is
+	* shared by every in-flight call, so it is dropped (and closed) only when it
+	* is itself unusable: it never opened, or it was closed under us
+	* (`InvalidStateError`). Any other failure belongs to one operation (an
+	* uncloneable value, a quota error) and leaves the handle to the others.
+	*/
 	async run(fallback, work) {
 		let used;
+		let db;
 		try {
 			used = this.open();
-			return await work(await used);
-		} catch {
-			if (this.opening === used) this.opening = void 0;
-			try {
-				(await used)?.close();
-			} catch {}
+			db = await used;
+			return await work(db);
+		} catch (error) {
+			if (db === void 0 || isInvalidState(error)) {
+				if (this.opening === used) this.opening = void 0;
+				db?.close();
+			}
 			return fallback;
 		}
 	}
@@ -908,7 +991,18 @@ var IndexedDbStore = class {
 				expiresAt: this.now() + (ttlMs ?? this.defaultTtlMs),
 				entry
 			};
-			await db.put(STORE, stored, key);
+			const tx = guarded(db.transaction(STORE, "readwrite"));
+			await tx.store.put(stored, key);
+			if (this.maxEntries !== void 0) {
+				let excess = await tx.store.count() - this.maxEntries;
+				let cursor = excess > 0 ? await tx.store.index(BY_EXPIRY).openCursor() : null;
+				while (cursor !== null && excess > 0) {
+					await cursor.delete();
+					excess -= 1;
+					cursor = await cursor.continue();
+				}
+			}
+			await tx.done;
 		});
 	}
 	delete(key) {