@craftainer/crud-sdk 0.3.0 → 0.5.0

package/README.md

@@ -51,8 +51,32 @@ 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
+  origin than `baseUrl`'s (an absolute URL or a protocol-relative `//host`)
+  is refused with a `ManifestError`. For a split-origin deployment, list the
+  extra origins: `createClient({ baseUrl, allowedOrigins: ["https://files.example"] })`
+  (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 })`,
@@ -102,7 +126,11 @@ crud-sdk-codegen --manifest ./manifest.json --out src/crud-types.ts
 Writes `<Name><Version>Read|Create|Update` (and `Draft`) interfaces per
 resource from the manifest's JSON Schemas. `--manifest` is a manifest URL, a
 server origin (discovers through the api-catalog) or a file; the optional
-peer `json-schema-to-typescript` must be installed.
+peer `json-schema-to-typescript` must be installed. The header names the
+source without credentials, query or fragment. Two resources whose names
+map to the same type name (`hero-x` and `hero_x`, same version), or a name
+that is not a valid identifier (a leading digit), fail with a `CrudError`
+naming them.
 
 ## Caching / TanStack
 
@@ -117,10 +145,37 @@ objects, snake_case members).
 - Every read revalidates (`If-None-Match`, `304` rebuilt from the store).
   `max_age`/`stale_while_revalidate` freshness applies only while the
   resource's SSE stream is connected, never with `cache.revalidate_only`.
+  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.
@@ -168,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 SubscribeEventsOptions, c as CachePolicy, d as tanstackCachePolicy, i as EventsConfig, l as ManifestCacheHints, n as EventHub, o as getEventHub, r as EventHubOptions, s as subscribeEvents, t as EventHandlers, u as cachePolicyFromManifest } from "../events-DpSWzSN9.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>;
@@ -157,10 +176,13 @@ export declare function eventPrefixes(resource: string, action: string, recordId
 /**
  * Subscribe `cache` to `hub` for the manifest resource `resource`. Events
  * clear the spec's prefixes, a reconnect clears the resource, and fresh hits
- * are allowed only while the stream is connected. Returns the unsubscribe
- * (it also closes the freshness gate).
+ * are allowed only while the stream is connected. The cache is cleared once
+ * per connection, whenever it subscribes: a subscription that joins an already
+ * connected hub (or during the handshake) clears the resource first, unless
+ * the cache was already cleared on that connection, and only then opens the
+ * gate. Returns the unsubscribe (it also closes the freshness gate).
  */
 export declare function invalidateOnEvents(cache: Cache, hub: EventHub, resource: string): () => void;
 //#endregion
-export { type Cache, type CacheEntry, type CacheKind, type CacheOptions, type CachePolicy, type CacheStatus, type CacheStore, type CacheStoreMany, type CrudEvent, type EventHandlers, type EventHub, type EventHubOptions, type EventsConfig, type IndexedDbStoreOptions, type KeyParts, type ManifestCacheHints, type MemoryStoreOptions, type SubscribeEventsOptions, cachePolicyFromManifest, getEventHub, subscribeEvents, tanstackCachePolicy };
+export { type Cache, type CacheEntry, type CacheKind, type CacheOptions, type CachePolicy, type CacheStatus, type CacheStore, type CacheStoreMany, type CrudEvent, type EventConnection, type EventHandlers, type EventHub, type EventHubOptions, type EventsConfig, type IndexedDbStoreOptions, type KeyParts, type ManifestCacheHints, type MemoryStoreOptions, type SubscribeEventsOptions, cachePolicyFromManifest, getEventHub, subscribeEvents, tanstackCachePolicy };
 //# sourceMappingURL=index.d.mts.map

package/dist/cache/index.mjs

@@ -1,5 +1,5 @@
-import { n as cacheScope, t as ANON } from "../auth-DwtNEKrw.mjs";
-import { i as tanstackCachePolicy, n as subscribeEvents, r as cachePolicyFromManifest, t as getEventHub } from "../events-Cqj9Rbon.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) {
@@ -940,8 +1034,11 @@ const connected = /* @__PURE__ */ new WeakMap();
 /**
 * Subscribe `cache` to `hub` for the manifest resource `resource`. Events
 * clear the spec's prefixes, a reconnect clears the resource, and fresh hits
-* are allowed only while the stream is connected. Returns the unsubscribe
-* (it also closes the freshness gate).
+* are allowed only while the stream is connected. The cache is cleared once
+* per connection, whenever it subscribes: a subscription that joins an already
+* connected hub (or during the handshake) clears the resource first, unless
+* the cache was already cleared on that connection, and only then opens the
+* gate. Returns the unsubscribe (it also closes the freshness gate).
 */
 function invalidateOnEvents(cache, hub, resource) {
 	const byResource = connected.get(cache) ?? /* @__PURE__ */ new Map();
@@ -949,6 +1046,8 @@ function invalidateOnEvents(cache, hub, resource) {
 	const live = byResource.get(resource) ?? /* @__PURE__ */ new Set();
 	byResource.set(resource, live);
 	const self = {};
+	let latest = 0;
+	const reset = (connection) => resetOnce(connection, cache, resource, () => cache.clearResource(resource));
 	const mark = (up) => {
 		if (up) live.add(self);
 		else live.delete(self);
@@ -956,10 +1055,19 @@ function invalidateOnEvents(cache, hub, resource) {
 	};
 	const unsubscribe = hub.subscribe({
 		onEvent: (event) => cache.invalidateEvent(resource, event.action, event.recordId),
-		onReset: () => cache.clearResource(resource),
-		onStatus: mark
+		onReset: (connection) => connection === void 0 ? cache.clearResource(resource) : reset(connection),
+		onStatus: async (up, connection) => {
+			latest += 1;
+			const mine = latest;
+			if (up && connection !== void 0) {
+				await reset(connection);
+				if (mine !== latest) return;
+			}
+			mark(up);
+		}
 	});
 	return () => {
+		latest += 1;
 		try {
 			unsubscribe();
 		} finally {