@metreeca/keep 0.10.0 → 0.11.0

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/stores/caching.d.ts

@@ -1,36 +1,33 @@
-import type { Reference } from "@metreeca/qest/resource";
+import type { Reference } from "@metreeca/qest/state";
 import type { Store } from "../index.js";
 /**
  * Creates a caching store backed by a delegate.
  *
- * Serves repeated retrievals from an in-memory cache, sparing the delegate a round-trip whenever a prior retrieval
- * can be reused; this cuts latency and backend load for read-heavy workloads, while writes and eviction keep cached
+ * Serves repeated retrievals from an in-memory cache, sparing the delegate a round-trip whenever a prior result can
+ * be reused. This cuts latency and backend load for read-heavy workloads, while writes and eviction keep cached
  * results coherent and bounded.
  *
- * Retrievals are memoised under an `(entry, model, locale, limit)` key, where the model is canonicalised bottom-up so
- * templates differing only in property or element order (including arrays of objects) share a cache entry, widening
- * the set of requests a single cached result can serve.
+ * Results are cached by `entry`, `model`, and the `locale` and `limit` of the {@link Store.lookup lookup} retrieval scope.
+ * Templates differing only in member or element order share a cached result.
  *
  * > [!IMPORTANT]
- * > `shape` is deliberately excluded from the cache key: the retrieval result must be a pure function of
- * > `(entry, model, locale, limit)`, with `shape` supplying only structural metadata that does not affect the
- * > returned payload.
+ * > `shape` is not part of the cache key. A retrieval result MUST depend only on `entry`, `model`, `locale` and
+ * > `limit`, with `shape` supplying structural metadata that does not affect the returned payload.
  *
  * > [!IMPORTANT]
- * > `opts.locale` is part of the cache key because it selects which localised content a retrieval returns. Unlike
- * > the model, the locale priority list is order-significant — `["en", "it"]` and `["it", "en"]` key separately —
- * > since order encodes language-negotiation preference. An omitted or empty locale list collapses to a single key,
- * > distinct from any explicit list.
+ * > The scope `locale` is part of the cache key, because it selects which localised content a retrieval returns.
+ * > Unlike the model, the locale priority list is order-significant: `["en", "it"]` and `["it", "en"]` are cached
+ * > separately. An omitted and an empty locale list share a single cached result, distinct from any explicit list.
  *
  * > [!IMPORTANT]
- * > `opts.limit` is part of the cache key because it caps each selection's `#` and so changes the returned payload,
- * > with an omitted or `0` limit collapsing to a single unbounded key. `opts.plain`/`opts.depth` are excluded: they
- * > only accept or reject a model, never altering a successful payload.
+ * > The scope `limit` is part of the cache key, because it caps the page size of each collection and so changes the
+ * > returned payload. An omitted and a `0` limit share a single cached result. The scope `plain` and `depth` are not
+ * > part of the key: they only accept or reject a model, and never alter a successful payload.
  *
  * The cache offers three observable guarantees:
  *
  * - **coalescing** — concurrent retrievals for the same key resolve from a single delegate fetch, and a failed
- *   retrieval is never cached, so a later retrieval re-fetches;
+ *   retrieval or one finding no resource is never cached, so a later retrieval re-fetches;
  * - **read-after-write coherence** — a retrieval never returns content staler than the latest write made through this
  *   store: {@link Store.create create}, {@link Store.update update}, {@link Store.delete delete},
  *   {@link Store.insert insert} and {@link Store.remove remove} invalidate matching entries, and a
@@ -80,9 +77,9 @@ export declare function createCachingStore(store: Store, { size, ttl, match }?:
     /**
      * Predicate deciding which cached records an invalidation event discards.
      *
-     * Invoked by both invalidation paths — pre-commit writes on the wrapper and reactive mutation events from the
-     * delegate — with the mutated resource's identifier and the identifier carried on each cached record. Return
-     * true to evict the record.
+     * Invoked for writes made through the wrapper and for mutation events signalled by the delegate. It receives the
+     * identifier of the mutated resource and the identifier of each cached record, and returns `true` if the record
+     * is to be evicted.
      *
      * @param entry - Identifier of the mutated resource
      * @param cache - Identifier associated with a cached record

package/dist/stores/caching.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"caching.d.ts","sourceRoot":"","sources":["../../src/stores/caching.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,EAEhD,IAAQ,EACR,GAAO,EACP,KAAkB,EAElB,GAAE;IAEF;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC;CAE5D,GAAG,KAAK,CAyUb"}
+{"version":3,"file":"caching.d.ts","sourceRoot":"","sources":["../../src/stores/caching.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAGzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,EAEhD,IAAQ,EACR,GAAO,EACP,KAAkB,EAElB,GAAE;IAEF;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC;CAE5D,GAAG,KAAK,CA0Vb"}

package/dist/stores/caching.js

@@ -16,46 +16,42 @@
 /**
  * Caching store wrapper.
  *
- * Provides {@link createCachingStore}, which wraps a {@link Store} with an in-memory cache
- * supporting LRU and TTL-based eviction, in-flight request sharing, an in-flight write bypass that prevents
- * pre-commit values from being cached, and coherent invalidation driven by both the wrapper's own write
- * operations and the delegate's mutation events.
+ * Speeds up read-heavy workloads by serving repeated retrievals from an in-memory cache. The cache stays bounded
+ * by size and age, shares concurrent identical retrievals, and stays coherent with writes made through the store, by
+ * other clients, or signalled by the backend.
  *
  * @module
  */
 import { isArray, isObject } from "@metreeca/core";
-import { immutable } from "@metreeca/core/structures";
+import { immutable } from "@metreeca/core/values";
 /**
  * Creates a caching store backed by a delegate.
  *
- * Serves repeated retrievals from an in-memory cache, sparing the delegate a round-trip whenever a prior retrieval
- * can be reused; this cuts latency and backend load for read-heavy workloads, while writes and eviction keep cached
+ * Serves repeated retrievals from an in-memory cache, sparing the delegate a round-trip whenever a prior result can
+ * be reused. This cuts latency and backend load for read-heavy workloads, while writes and eviction keep cached
  * results coherent and bounded.
  *
- * Retrievals are memoised under an `(entry, model, locale, limit)` key, where the model is canonicalised bottom-up so
- * templates differing only in property or element order (including arrays of objects) share a cache entry, widening
- * the set of requests a single cached result can serve.
+ * Results are cached by `entry`, `model`, and the `locale` and `limit` of the {@link Store.lookup lookup} retrieval scope.
+ * Templates differing only in member or element order share a cached result.
  *
  * > [!IMPORTANT]
- * > `shape` is deliberately excluded from the cache key: the retrieval result must be a pure function of
- * > `(entry, model, locale, limit)`, with `shape` supplying only structural metadata that does not affect the
- * > returned payload.
+ * > `shape` is not part of the cache key. A retrieval result MUST depend only on `entry`, `model`, `locale` and
+ * > `limit`, with `shape` supplying structural metadata that does not affect the returned payload.
  *
  * > [!IMPORTANT]
- * > `opts.locale` is part of the cache key because it selects which localised content a retrieval returns. Unlike
- * > the model, the locale priority list is order-significant — `["en", "it"]` and `["it", "en"]` key separately —
- * > since order encodes language-negotiation preference. An omitted or empty locale list collapses to a single key,
- * > distinct from any explicit list.
+ * > The scope `locale` is part of the cache key, because it selects which localised content a retrieval returns.
+ * > Unlike the model, the locale priority list is order-significant: `["en", "it"]` and `["it", "en"]` are cached
+ * > separately. An omitted and an empty locale list share a single cached result, distinct from any explicit list.
  *
  * > [!IMPORTANT]
- * > `opts.limit` is part of the cache key because it caps each selection's `#` and so changes the returned payload,
- * > with an omitted or `0` limit collapsing to a single unbounded key. `opts.plain`/`opts.depth` are excluded: they
- * > only accept or reject a model, never altering a successful payload.
+ * > The scope `limit` is part of the cache key, because it caps the page size of each collection and so changes the
+ * > returned payload. An omitted and a `0` limit share a single cached result. The scope `plain` and `depth` are not
+ * > part of the key: they only accept or reject a model, and never alter a successful payload.
  *
  * The cache offers three observable guarantees:
  *
  * - **coalescing** — concurrent retrievals for the same key resolve from a single delegate fetch, and a failed
- *   retrieval is never cached, so a later retrieval re-fetches;
+ *   retrieval or one finding no resource is never cached, so a later retrieval re-fetches;
  * - **read-after-write coherence** — a retrieval never returns content staler than the latest write made through this
  *   store: {@link Store.create create}, {@link Store.update update}, {@link Store.delete delete},
  *   {@link Store.insert insert} and {@link Store.remove remove} invalidate matching entries, and a
@@ -88,8 +84,8 @@ export function createCachingStore(store, { size = 0, ttl = 0, match = () => tru
     // moving it to the tail, so `cache.keys().next().value` is always the least-recently-used key.
     const cache = new Map();
     // Tracks entries with at least one in-flight wrapper-initiated write. Reads of these entries bypass the
-    // cache entirely — they still query the delegate, but their result is not stored. This closes the window
-    // between a lookup resolving with a pre-commit value and the reactive observer firing on commit, during
+    // cache entirely: they still query the delegate, but their result is not stored. This closes the window
+    // between a lookup call resolving with a pre-commit value and the reactive observer firing on commit, during
     // which the cache would otherwise hold a stale-but-fresh-looking record.
     const writing = new Map();
     // Reactive invalidation: subscribe to the delegate's mutation events and drop matching records on commit.
@@ -103,8 +99,8 @@ export function createCachingStore(store, { size = 0, ttl = 0, match = () => tru
         lookup({ entry, shape, model }, opts) {
             return memoise(entry, model, opts, () => store.lookup({ entry, shape, model }, opts));
         },
-        create({ entry, shape, state }) {
-            return write(entry, () => store.create({ entry, shape, state }));
+        create({ entry, shape, model, state }) {
+            return write(entry, () => store.create({ entry, shape, model, state }));
         },
         update({ entry, shape, state }) {
             return write(entry, () => store.update({ entry, shape, state }));
@@ -112,8 +108,8 @@ export function createCachingStore(store, { size = 0, ttl = 0, match = () => tru
         delete({ entry, shape }) {
             return write(entry, () => store.delete({ entry, shape }));
         },
-        insert({ entry, shape, state }, opts) {
-            return write(entry, () => store.insert({ entry, shape, state }, opts));
+        insert({ entry, shape, state }) {
+            return write(entry, () => store.insert({ entry, shape, state }));
         },
         remove({ entry, shape }) {
             return write(entry, () => store.remove({ entry, shape }));
@@ -139,57 +135,70 @@ export function createCachingStore(store, { size = 0, ttl = 0, match = () => tru
      * - **fresh hit** — returns the memoised promise and re-inserts the record to bump its LRU position;
      * - **miss / TTL-expired** — runs `miss()`, stores the pending promise under the canonicalised key so
      *   concurrent callers share the in-flight request, and enforces TTL/size bounds via {@link purge}; a
-     *   rejected fetch evicts its record only if an intervening invalidation has not already replaced it.
+     *   fetch resolving to an absent resource or rejecting evicts its record only if an intervening invalidation
+     *   has not already replaced it.
      *
-     * @param entry - Resource identifier; paired with the canonicalised model and varying opts to form the cache key
-     * @param model - Retrieval template, canonicalised so that equivalent templates in different orderings share a key
-     * @param vary  - Retrieval opts whose values vary the returned payload, folded into the key: `locale`
+     * @typeParam V - The retrieved payload, opaque to the cache
+     *
+     * @param entry - Resource identifier; paired with the canonicalised model and varying scope members to form the
+     *     cache key
+     * @param model - Retrieval model, canonicalised so that equivalent models in different orderings share a key
+     * @param vary  - Retrieval scope members whose values vary the returned payload, folded into the key: `locale`
      *   order-significantly (an omitted or empty list collapsing to a single key) and `limit` because it caps each
-     *   selection's `#` pagination bound (an omitted or `0` unbounded value collapsing to a single key)
+     *   collection's `#` pagination bound (an omitted or `0` unbounded value collapsing to a single key)
      * @param miss  - Fetcher invoked on cache miss, on TTL expiration, or while the entry has an in-flight write
      *
      * @returns The memoised, freshly-fetched, or bypass-fetched promise
      */
     function memoise(entry, model, vary = {}, miss) {
         // Bypass the cache while a write to this entry is in flight: still query the delegate so the caller
-        // gets a value, but do not store the result — it is liable to be the pre-commit snapshot that the
+        // gets a value, but do not store the result: it is liable to be the pre-commit snapshot that the
         // reactive observer would invalidate moments later
         if (writing.has(entry)) {
             return miss();
         }
         else {
-            // Cache key layout: `<entry>\x00<canonical-model>\x00<locale>\x00<limit>`. `canonical` walks the model
-            // bottom-up, sorting object keys and (already-canonical) array elements, so templates differing only in
-            // ordering share a key. The locale segment is serialised verbatim (order preserved, since the priority
+            // Cache key layout: `<entry>\x00<canonical-model>\x00<locale>\x00<limit>`. `canonical` walks the
+            // model bottom-up, sorting object keys and (already-canonical) array elements, so models differing only
+            // in ordering share a key. The locale segment is serialised verbatim (order preserved, since the priority
             // list is order-significant) with omitted and empty lists collapsing to `[]`. The limit segment is
-            // keyed because it caps each selection's `#` and so changes the payload, with omitted and `0` (both
-            // unbounded) collapsing to `0`. `\x00` is safe as a separator — IRIs cannot contain it and JSON always
+            // keyed because it caps each collection's `#` and so changes the payload, with omitted and `0` (both
+            // unbounded) collapsing to `0`. `\x00` is safe as a separator: IRIs cannot contain it and JSON always
             // escapes it inside string payloads.
-            const key = `${entry}\x00${canonical(model)}\x00${JSON.stringify(vary.locale ?? [])}\x00${vary.limit ?? 0}`;
+            const key = [entry, canonical(model), JSON.stringify(vary.locale ?? []), vary.limit ?? 0].join("\x00");
             const cached = cache.get(key);
             if (cached && !expired(cached.created)) {
                 // hit: re-insert to move the entry to the tail of the Map's iteration order (the LRU position),
-                // and return the memoised promise; the cast reflects the type-erased `Promise<unknown>` storage
-                // that lets records with different template types share one Map
+                // and return the memoised promise; ;(cast) the type-erased `Promise<unknown>` storage lets records
+                // with different payload types share one Map
                 cache.delete(key);
                 cache.set(key, cached);
                 return cached.value;
             }
             else {
                 // miss (or TTL-expired): drop any stale record, run the fetcher, and memoise the pending promise
-                // under the same key so concurrent callers share the in-flight request; a failure evicts its own
-                // record through the catch handler so transient errors are not retained
+                // under the same key so concurrent callers share the in-flight request; an absent resource or a
+                // failure evicts its own record once settled, so neither a missing resource nor a transient error
+                // is retained
                 if (cached) {
                     cache.delete(key);
                 }
-                const value = miss().catch(error => {
-                    // identity-check: only evict if this promise is still the cached one —
-                    // avoids dropping a newer record installed after an intervening invalidate
-                    if (cache.get(key)?.value === value) {
-                        cache.delete(key);
+                const value = miss().then(resource => {
+                    if (resource === undefined) {
+                        evict();
                     }
+                    return resource;
+                }, error => {
+                    evict();
                     throw error;
                 });
+                // identity-check: only evict if this promise is still the cached one, avoiding dropping a newer
+                // record installed after an intervening invalidate
+                function evict() {
+                    if (cache.get(key)?.value === value) {
+                        cache.delete(key);
+                    }
+                }
                 cache.set(key, {
                     entry,
                     value,
@@ -203,7 +212,7 @@ export function createCachingStore(store, { size = 0, ttl = 0, match = () => tru
     /**
      * Serialises a value to a canonical JSON-like string.
      *
-     * Children are canonicalised first, then sorted by their already-canonical string form — so arrays of
+     * Children are canonicalised first, then sorted by their already-canonical string form, so arrays of
      * objects are ordered by structural content rather than by the `"[object Object]"` placeholder that
      * `Array.prototype.sort` would otherwise impose. The output collapses values differing only in property
      * or element order to the same string.
@@ -288,7 +297,7 @@ export function createCachingStore(store, { size = 0, ttl = 0, match = () => tru
      * Runs two sweeps: first, when `ttl > 0`, drops every record older than `ttl` milliseconds; second, when
      * `size > 0` and the cache is overfull, drops the head slice of the Map (least-recently-used first) in
      * a single batch sized to the exact overflow. Invoked after every miss so expired siblings and overfill
-     * are cleaned up incrementally — the cache has no background sweeper.
+     * are cleaned up incrementally, as the cache has no background sweeper.
      */
     function purge() {
         if (ttl > 0) {
@@ -300,7 +309,7 @@ export function createCachingStore(store, { size = 0, ttl = 0, match = () => tru
             }
         }
         // LRU sweep: when over the size bound, take the head slice of Map keys (insertion order = LRU first)
-        // and drop them — `cache.size - size` is the exact overflow, so no loop condition needs re-checking
+        // and drop them: `cache.size - size` is the exact overflow, so no loop condition needs re-checking
         if (size > 0 && cache.size > size) {
             Array.from(cache.keys())
                 .slice(0, cache.size - size)

package/dist/stores/caching.js.map

@@ -1 +1 @@
-{"version":3,"file":"caching.js","sourceRoot":"","sources":["../../src/stores/caching.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAMtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAY,EAAE,EAEhD,IAAI,GAAG,CAAC,EACR,GAAG,GAAG,CAAC,EACP,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,KAwCf,EAAE;IAEL,uGAAuG;IACvG,+FAA+F;IAE/F,MAAM,KAAK,GAAG,IAAI,GAAG,EAMjB,CAAC;IAEL,wGAAwG;IACxG,yGAAyG;IACzG,wGAAwG;IACxG,yEAAyE;IAEzE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAqB,CAAC;IAG7C,0GAA0G;IAC1G,4GAA4G;IAC5G,yGAAyG;IACzG,oCAAoC;IAEpC,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE;QAE7C,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAE5C,CAAC,CAAC,CAAC;IAGH,OAAO,SAAS,CAAQ;QAEvB,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI;YAEnC,OAAO,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;QAEvF,CAAC;QAGD,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;YAE7B,OAAO,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAElE,CAAC;QAED,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE;YAE7B,OAAO,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAElE,CAAC;QAED,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE;YAEtB,OAAO,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAE3D,CAAC;QAGD,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI;YAEnC,OAAO,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;QAExE,CAAC;QAED,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE;YAEtB,OAAO,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;QAE3D,CAAC;QAGD,OAAO,CAAC,QAAQ,EAAE,SAAS;YAE1B,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAE3C,CAAC;QAED,OAAO,CAAC,IAAI;YAEX,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,gEAAgE;QAE7F,CAAC;QAED,KAAK;YAEJ,WAAW,EAAE,CAAC;YAEd,OAAO,KAAK,CAAC,KAAK,EAAE,CAAC;QAEtB,CAAC;KAED,CAAC,CAAC;IAGH;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,OAAO,CACf,KAAgB,EAChB,KAAQ,EACR,OAAsE,EAAE,EACxE,IAA4C;QAG5C,oGAAoG;QACpG,kGAAkG;QAClG,mDAAmD;QAEnD,IAAK,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAG,CAAC;YAE1B,OAAO,IAAI,EAAE,CAAC;QAEf,CAAC;aAAM,CAAC;YAEP,uGAAuG;YACvG,wGAAwG;YACxG,uGAAuG;YACvG,mGAAmG;YACnG,oGAAoG;YACpG,uGAAuG;YACvG,qCAAqC;YAErC,MAAM,GAAG,GAAG,GAAG,KAAK,OAAO,SAAS,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAAC,OAAO,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YAE5G,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAE9B,IAAK,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAG,CAAC;gBAE1C,gGAAgG;gBAChG,gGAAgG;gBAChG,gEAAgE;gBAEhE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAClB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;gBAEvB,OAAO,MAAM,CAAC,KAAyC,CAAC;YAEzD,CAAC;iBAAM,CAAC;gBAEP,iGAAiG;gBACjG,iGAAiG;gBACjG,wEAAwE;gBAExE,IAAK,MAAM,EAAG,CAAC;oBACd,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACnB,CAAC;gBAED,MAAM,KAAK,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;oBAElC,uEAAuE;oBACvE,2EAA2E;oBAE3E,IAAK,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,KAAK,EAAG,CAAC;wBACvC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBACnB,CAAC;oBAED,MAAM,KAAK,CAAC;gBAEb,CAAC,CAAC,CAAC;gBAEH,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;oBAEd,KAAK;oBACL,KAAK;oBACL,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;iBAEnB,CAAC,CAAC;gBAEH,KAAK,EAAE,CAAC;gBAER,OAAO,KAAK,CAAC;YAEd,CAAC;QAEF,CAAC;IAEF,CAAC;IAGD;;;;;;;;;;;OAWG;IACH,SAAS,SAAS,CAAC,KAAc;QAEhC,IAAK,OAAO,CAAC,KAAK,CAAC,EAAG,CAAC;YAEtB,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAErD,CAAC;aAAM,IAAK,QAAQ,CAAC,KAAK,CAAC,EAAG,CAAC;YAE9B,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QAE3G,CAAC;aAAM,CAAC;YAEP,mGAAmG;YACnG,qGAAqG;YACrG,wCAAwC;YAExC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAElE,CAAC;IACF,CAAC;IAED;;;;;;;;;;;OAWG;IACH,SAAS,OAAO,CAAC,OAAe,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;QAEzD,OAAO,GAAG,GAAG,CAAC,IAAI,GAAG,GAAC,OAAO,GAAG,GAAG,CAAC;IAErC,CAAC;IAED;;;;;;;;;;;OAWG;IACH,SAAS,KAAK,CAAI,KAAgB,EAAE,EAAoB;QAEvD,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAC,CAAC,CAAC,CAAC;QAEhD,UAAU,CAAC,KAAK,CAAC,CAAC;QAElB,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAExB,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAC,CAAC,CAAC;YAE1C,IAAK,KAAK,IAAI,CAAC,EAAG,CAAC;gBAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAAC,CAAC;iBAAM,CAAC;gBAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAAC,CAAC;QAEjF,CAAC,CAAC,CAAC;IAEJ,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,UAAU,CAAC,KAAgB;QAEnC,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACnC,IAAK,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAG,CAAC;gBAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAAC,CAAC;QACzD,CAAC;IAEF,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,KAAK;QAEb,IAAK,GAAG,GAAG,CAAC,EAAG,CAAC;YAEf,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAEvB,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;gBACnC,IAAK,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,EAAG,CAAC;oBAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAAC,CAAC;YAC3D,CAAC;QAEF,CAAC;QAED,qGAAqG;QACrG,oGAAoG;QAEpG,IAAK,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,GAAG,IAAI,EAAG,CAAC;YAErC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;iBACtB,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,GAAC,IAAI,CAAC;iBACzB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAErC,CAAC;IAEF,CAAC;AAEF,CAAC"}
+{"version":3,"file":"caching.js","sourceRoot":"","sources":["../../src/stores/caching.ts"],"names":[],"mappings":"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"}

package/dist/stores/managing.d.ts

@@ -1,55 +1,57 @@
-import type { Store, StoreClient } from "../index.js";
+import type { Store } from "../index.js";
 /**
- * Manages mutation events, transactional execution, and lifecycle for a bare {@link StoreClient},
+ * Manages mutation events, transactional execution, and lifecycle for a connector's {@link StoreClient},
  * exposing it as a full {@link Store}.
  *
- * This lets a connector implement only the {@link StoreClient} data surface and obtain
- * mutation events, transactional execution, and lifecycle for free: supply nothing and the wrapper provides working
- * defaults, or hand it backend primitives through `management` to back any of `execute`, `observe`, or `close`.
+ * A connector can implement only the {@link StoreClient} data surface and still offer the full {@link Store}
+ * contract. The connector supplies its transaction primitive through `management.execute`, which hands the
+ * connector's {@link StoreClient} to every data call. The option is required, since only the connector knows what
+ * atomicity its backend can provide. Backend primitives supplied through `management` may also back `observe` or
+ * `close`, and the wrapper fills in whatever is missing.
  *
- * Each standalone mutation call and each {@link Store.execute execute} call accumulates its own
- * batch of mutation signals and delivers a single filtered event to each matching registered
- * {@link StoreObserver observer} when the call resolves; if it rejects, pending signals are discarded
- * and no observers are notified. Both synchronous throws and asynchronous rejections from observers
- * are caught and silently ignored so that one faulty observer cannot break delivery to others.
+ * Each standalone mutation call and each {@link Store.execute execute} call delivers a single filtered event to each
+ * matching {@link StoreObserver observer} once the call resolves. If the call rejects, its pending events are
+ * discarded and no observer is notified. Synchronous throws and asynchronous rejections from observers are caught and
+ * silently ignored, so one faulty observer cannot break delivery to others.
  *
- * Any of the {@link Store} management methods may be supplied through `management` to delegate to an inner
- * implementation; the wrapper fills in whatever is missing.
- *
- * All errors — `RangeError`, {@link @metreeca/core!TraceError | TraceError},
- * {@link @metreeca/http!Problem | Problem} —
- * propagate as promise rejections per the unified {@link Store} error channel.
+ * All errors, including {@link !RangeError RangeError}, {@link @metreeca/core!TraceError | TraceError} and
+ * {@link @metreeca/http!Problem | Problem}, propagate as promise rejections, in line with the unified {@link Store}
+ * error channel.
  *
  * > [!IMPORTANT]
- * > **Transaction Isolation** — `None` by default: the built-in `execute` is a deferred identity that applies each
- * > call directly, with no write buffering and no rollback. When an `execute` opt is supplied through `management`,
- * > the level is determined by that wrapper (typically a backend transaction primitive).
+ * > **Transaction Isolation** — Determined by the supplied `execute` option, typically through a backend
+ * > transaction primitive: the wrapper adds neither isolation nor atomicity of its own.
  *
  * > [!IMPORTANT]
  * > **Mutation Events** — emits in-process observer events: each standalone mutation and each
  * > {@link Store.execute execute} call delivers a single filtered batch to matching {@link StoreObserver observer}s
- * > on resolve, and none on rejection. Cross-client signals reach local observers only when a backend-bridging
- * > `observe` opt is supplied through `management`.
- *
- * @param store - Inner StoreClient to delegate data calls to
- * @param management - Subset of {@link Store} management methods to delegate to; the wrapper fills in whatever is
- *     missing
- * @param management.execute - Wraps every standalone StoreClient call and the body of {@link Store.execute execute},
- *     typically a backend transaction primitive (for example, `graph.execute` for a SPARQL connector) responsible for
- *     atomic commit and rollback. The wrapper StoreClient passed to the user task does NOT re-enter the opt; it relies
- *     on the outer wrap so cross-call isolation works as expected. The task receives a per-call `scope` StoreClient,
- *     and every delegated call within the wrap routes through `scope` (mirroring the {@link Store.execute} contract),
- *     letting the wrapper install per-call state such as a freshly-bound graph buffer without leaking it across
- *     concurrent invocations. Defaults to a deferred identity (`task => Promise.resolve().then(() => task(store))`);
- *     user-supplied wrappers MUST pass a per-call `scope` StoreClient to `task` and MUST convert synchronous throws
- *     from `task` into promise rejections to preserve the unified Store error channel; the `lookup` path delegates
- *     directly to the wrapper and provides no additional guard
- * @param management.observe - Registers each observer with the delegate as well as locally, combining the two
- *     unsubscribe handles so a single detach call releases both; this is how storage-level events (mutations from
- *     other clients sharing the backend) reach the wrapper's local observers. Absent by default
- * @param management.close - Exposed verbatim on the returned store. Defaults to a resolved no-op
- *
- * @returns An immutable {@link Store} composing `store` with the supplied `management` opts
+ * > on resolve, and none on rejection. Mutations made by other clients reach local observers only if a
+ * > backend-bridging `observe` option is supplied through `management`.
+ *
+ * @param management - {@link Store} management methods backed by the connector: `execute` is required, and the
+ *     wrapper fills in whatever else is missing
+ * @param management.execute - Transaction wrapper applied to every standalone StoreClient call and to the body of
+ *     each {@link Store.execute execute} call, typically a backend transaction primitive (for example,
+ *     `graph.execute` for a SPARQL connector) responsible for atomic commit and rollback. A backend with no
+ *     transaction primitive supplies a wrapper applying the task directly to its StoreClient, and declares on its
+ *     factory that a failing task neither rolls back nor isolates its mutations. The option MUST call each task it
+ *     receives with a `scope` StoreClient dedicated to that call, so per-call state, such as a freshly bound graph
+ *     buffer, never leaks across concurrent invocations; every data call within the transaction is routed through
+ *     `scope`. Calls made by a user task inside {@link Store.execute execute} do not open further transactions: they
+ *     share the outer one. The option MUST convert synchronous throws from the task into promise rejections, to
+ *     preserve the unified Store error channel: lookups are routed through it with no additional guard
+ * @param management.observe - Backend registration for storage-level events, such as mutations made by other clients
+ *     sharing the backend. Each observer is registered both with this option and locally, and a single detach call
+ *     releases both registrations. The resource filter always arrives as an array of references, or as `undefined`
+ *     for an unfiltered registration, so the option never has to handle bare references or single-pass iterables.
+ *     Absent by default
+ * @param management.close - Exposed as is on the returned store. Defaults to a resolved no-op
+ *
+ * @returns An immutable {@link Store} serving data calls through the supplied `management` opts
  */
-export declare function createManagingStore(store: StoreClient, { observe, execute, close }?: Partial<Store>): Store;
+export declare function createManagingStore({ observe, execute, close }: {
+    readonly observe?: Store["observe"];
+    readonly execute: Store["execute"];
+    readonly close?: Store["close"];
+}): Store;
 //# sourceMappingURL=managing.d.ts.map

package/dist/stores/managing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"managing.d.ts","sourceRoot":"","sources":["../../src/stores/managing.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAiB,MAAM,aAAa,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,EAEvD,OAAO,EACP,OAAwG,EACxG,KAA+B,EAE/B,GAAE,OAAO,CAAC,KAAK,CAAM,GAAG,KAAK,CA2H7B"}
+{"version":3,"file":"managing.d.ts","sourceRoot":"","sources":["../../src/stores/managing.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,KAAK,EAA8B,MAAM,aAAa,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,mBAAmB,CAAC,EAEnC,OAAO,EACP,OAAO,EAEP,KAA+B,EAE/B,EAAE;IAEF,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IACnC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IAElC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;CAE/B,GAAG,KAAK,CA2HR"}