@metreeca/keep 0.9.0 → 0.10.0

package/dist/{states/index.js → index.js}

@@ -1,4 +1,3 @@
-export {};
 /*
  * Copyright © 2025-2026 Metreeca srl
  *
@@ -14,4 +13,5 @@ export {};
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+export {};
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/stores/caching.d.ts

@@ -0,0 +1,96 @@
+import type { Reference } from "@metreeca/qest/resource";
+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
+ * 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.
+ *
+ * > [!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.
+ *
+ * > [!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.
+ *
+ * > [!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 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;
+ * - **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
+ *   retrieval overlapping an in-progress write to the same entry is served from the delegate without being cached;
+ * - **commit coherence** — writes committed through {@link Store.execute execute}, by other clients sharing the
+ *   delegate, or signalled by the backend invalidate matching entries on commit, for as long as the store stays open
+ *   ({@link Store.close close} ends further invalidation).
+ *
+ * The configurable `match` predicate selects which cached entries a write invalidates.
+ *
+ * > [!IMPORTANT]
+ * > **Transaction Isolation** — Inherited from the wrapped {@link Store}.
+ *
+ * > [!IMPORTANT]
+ * > **Mutation Events** — Inherited from the wrapped {@link Store}.
+ *
+ * @param store - The delegate store to cache
+ * @param options - Cache configuration options
+ *
+ * @returns An immutable store with caching behaviour
+ *
+ * @example
+ * ```typescript
+ * const cache = createCachingStore(restStore, { size: 1_000, ttl: 60_000 });
+ * const product = await cache.lookup({ entry, shape, model });
+ * ```
+ */
+export declare function createCachingStore(store: Store, { size, ttl, match }?: {
+    /**
+     * Maximum number of records to cache.
+     *
+     * When the cache exceeds this bound, the least-recently-used record is evicted after each miss.
+     *
+     * @defaultValue 0 (unlimited)
+     */
+    readonly size?: number;
+    /**
+     * Maximum record age in milliseconds.
+     *
+     * Records older than this value are treated as misses on the next retrieval and evicted when a sibling miss
+     * triggers the TTL sweep. Expiration is checked on every hit, so a stale record is never returned even if the
+     * sweep hasn't run yet.
+     *
+     * @defaultValue 0 (no expiration)
+     */
+    readonly ttl?: number;
+    /**
+     * 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.
+     *
+     * @param entry - Identifier of the mutated resource
+     * @param cache - Identifier associated with a cached record
+     *
+     * @returns true if the record should be evicted; false otherwise
+     *
+     * @defaultValue `() => true` (every mutation clears the cache)
+     */
+    readonly match?: (entry: Reference, cache: Reference) => boolean;
+}): Store;
+//# sourceMappingURL=caching.d.ts.map

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

@@ -0,0 +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"}

package/dist/stores/caching.js

@@ -0,0 +1,311 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 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.
+ *
+ * @module
+ */
+import { isArray, isObject } from "@metreeca/core";
+import { immutable } from "@metreeca/core/structures";
+/**
+ * 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
+ * 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.
+ *
+ * > [!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.
+ *
+ * > [!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.
+ *
+ * > [!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 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;
+ * - **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
+ *   retrieval overlapping an in-progress write to the same entry is served from the delegate without being cached;
+ * - **commit coherence** — writes committed through {@link Store.execute execute}, by other clients sharing the
+ *   delegate, or signalled by the backend invalidate matching entries on commit, for as long as the store stays open
+ *   ({@link Store.close close} ends further invalidation).
+ *
+ * The configurable `match` predicate selects which cached entries a write invalidates.
+ *
+ * > [!IMPORTANT]
+ * > **Transaction Isolation** — Inherited from the wrapped {@link Store}.
+ *
+ * > [!IMPORTANT]
+ * > **Mutation Events** — Inherited from the wrapped {@link Store}.
+ *
+ * @param store - The delegate store to cache
+ * @param options - Cache configuration options
+ *
+ * @returns An immutable store with caching behaviour
+ *
+ * @example
+ * ```typescript
+ * const cache = createCachingStore(restStore, { size: 1_000, ttl: 60_000 });
+ * const product = await cache.lookup({ entry, shape, model });
+ * ```
+ */
+export function createCachingStore(store, { size = 0, ttl = 0, match = () => true } = {}) {
+    // LRU ordering is supplied for free by `Map`'s insertion-order iteration: every hit re-sets the entry,
+    // 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
+    // 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.
+    // Covers writes routed through `execute`, writes from other clients sharing the delegate, and backends that
+    // emit storage-level events. The subscription is released by `close()` so the delegate does not retain a
+    // reference to a discarded wrapper.
+    const unsubscribe = store.observe(mutations => {
+        Object.keys(mutations).forEach(invalidate);
+    });
+    return immutable({
+        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 }));
+        },
+        update({ entry, shape, state }) {
+            return write(entry, () => store.update({ entry, shape, state }));
+        },
+        delete({ entry, shape }) {
+            return write(entry, () => store.delete({ entry, shape }));
+        },
+        insert({ entry, shape, state }, opts) {
+            return write(entry, () => store.insert({ entry, shape, state }, opts));
+        },
+        remove({ entry, shape }) {
+            return write(entry, () => store.remove({ entry, shape }));
+        },
+        observe(observer, resources) {
+            return store.observe(observer, resources);
+        },
+        execute(task) {
+            return store.execute(task); // task mutations invalidate the cache reactively through events
+        },
+        close() {
+            unsubscribe();
+            return store.close();
+        }
+    });
+    /**
+     * Retrieve-with-cache core.
+     *
+     * Three branches:
+     *
+     * - **bypass** — when `entry` has any wrapper-initiated write in flight, runs `miss()` and returns its
+     *   promise without storing it, so a pre-commit snapshot cannot be installed as fresh;
+     * - **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.
+     *
+     * @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`
+     *   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)
+     * @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
+        // 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
+            // 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
+            // escapes it inside string payloads.
+            const key = `${entry}\x00${canonical(model)}\x00${JSON.stringify(vary.locale ?? [])}\x00${vary.limit ?? 0}`;
+            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
+                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
+                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);
+                    }
+                    throw error;
+                });
+                cache.set(key, {
+                    entry,
+                    value,
+                    created: Date.now()
+                });
+                purge();
+                return value;
+            }
+        }
+    }
+    /**
+     * Serialises a value to a canonical JSON-like string.
+     *
+     * 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.
+     *
+     * @param value - Value to serialise
+     *
+     * @returns A canonical string representation of `value`
+     */
+    function canonical(value) {
+        if (isArray(value)) {
+            return `[${value.map(canonical).sort().join(",")}]`;
+        }
+        else if (isObject(value)) {
+            return `{${Object.keys(value).sort().map(k => `${JSON.stringify(k)}:${canonical(value[k])}`).join(",")}}`;
+        }
+        else {
+            // JSON.stringify(undefined) returns undefined, not a string; substitute a distinct sentinel so the
+            // signature holds and `undefined` does not collide with the string literal `"undefined"` (which JSON
+            // would render with surrounding quotes)
+            return value === undefined ? "undefined" : JSON.stringify(value);
+        }
+    }
+    /**
+     * Tests whether a record is older than the configured TTL.
+     *
+     * Returns false when `ttl <= 0`, so the predicate can be reused at both the hit guard and the purge sweep
+     * without duplicating the boundary check. The reference timestamp defaults to `Date.now` but may be
+     * passed in to share a single snapshot across a batch of comparisons.
+     *
+     * @param created - Insertion timestamp (ms) of the record under test
+     * @param now     - Reference timestamp (ms) to compare against; defaults to `Date.now`
+     *
+     * @returns true if `ttl > 0` and `created` is older than `ttl` milliseconds relative to `now`; false otherwise
+     */
+    function expired(created, now = Date.now()) {
+        return ttl > 0 && now - created > ttl;
+    }
+    /**
+     * Run a wrapper-initiated write under in-flight tracking.
+     *
+     * Marks `entry` as having an in-flight write, runs the configured pre-commit invalidation, delegates to
+     * `op`, and clears the marker once the delegate settles. While the marker is set, retrievals of `entry`
+     * bypass the cache so a pre-commit value can never be stored as fresh.
+     *
+     * @param entry - Resource identifier targeted by the write
+     * @param op    - Thunk that delegates the write to the wrapped store and returns its promise
+     *
+     * @returns The promise returned by `op`, settled after the in-flight marker has been cleared
+     */
+    function write(entry, op) {
+        writing.set(entry, (writing.get(entry) ?? 0) + 1);
+        invalidate(entry);
+        return op().finally(() => {
+            const count = (writing.get(entry) ?? 1) - 1;
+            if (count <= 0) {
+                writing.delete(entry);
+            }
+            else {
+                writing.set(entry, count);
+            }
+        });
+    }
+    /**
+     * Drop cached records matching a mutated resource.
+     *
+     * Iterates the cache and removes every record whose stored identifier satisfies the configured {@link match}
+     * predicate against the mutated `entry`. Called from both the pre-commit write path on the wrapper and the
+     * reactive observer attached to the delegate.
+     *
+     * @param entry - Identifier of the mutated resource
+     */
+    function invalidate(entry) {
+        for (const [key, record] of cache) {
+            if (match(entry, record.entry)) {
+                cache.delete(key);
+            }
+        }
+    }
+    /**
+     * Enforce TTL and size bounds.
+     *
+     * 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.
+     */
+    function purge() {
+        if (ttl > 0) {
+            const now = Date.now();
+            for (const [key, record] of cache) {
+                if (expired(record.created, now)) {
+                    cache.delete(key);
+                }
+            }
+        }
+        // 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
+        if (size > 0 && cache.size > size) {
+            Array.from(cache.keys())
+                .slice(0, cache.size - size)
+                .forEach(key => cache.delete(key));
+        }
+    }
+}
+//# sourceMappingURL=caching.js.map

package/dist/stores/caching.js.map

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

package/dist/stores/managing.d.ts

@@ -0,0 +1,55 @@
+import type { Store, StoreClient } from "../index.js";
+/**
+ * Manages mutation events, transactional execution, and lifecycle for a bare {@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`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * > [!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).
+ *
+ * > [!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
+ */
+export declare function createManagingStore(store: StoreClient, { observe, execute, close }?: Partial<Store>): Store;
+//# sourceMappingURL=managing.d.ts.map

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

@@ -0,0 +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"}

package/dist/stores/managing.js

@@ -0,0 +1,159 @@
+/*
+ * Copyright © 2025-2026 Metreeca srl
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Managing store wrapper.
+ *
+ * Manages mutation events, transactional execution, and lifecycle for a plain {@link StoreClient},
+ * exposing it as a full {@link Store}.
+ *
+ * @module
+ */
+import { isString } from "@metreeca/core";
+import { isNestedIRI } from "@metreeca/core/resource";
+import { immutable } from "@metreeca/core/structures";
+/**
+ * Manages mutation events, transactional execution, and lifecycle for a bare {@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`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * > [!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).
+ *
+ * > [!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
+ */
+export function createManagingStore(store, { observe, execute = (task) => Promise.resolve().then(() => task(store)), close = () => Promise.resolve() } = {}) {
+    const observers = new Map();
+    return immutable({
+        lookup: (specs, opts) => execute(store => store.lookup(specs, opts)),
+        create: specs => notify(({ mutated }) => execute(store => store.create(specs).then(mutated))),
+        update: specs => notify(({ mutated }) => execute(store => store.update(specs).then(mutated))),
+        delete: specs => notify(({ deleted }) => execute(store => store.delete(specs).then(deleted))),
+        insert: (specs, opts) => notify(({ mutated }) => execute(store => store.insert(specs, opts).then(mutated))),
+        remove: specs => notify(({ deleted }) => execute(store => store.remove(specs).then(deleted))),
+        observe(observer, resources) {
+            if (Array.isArray(resources) && resources.length === 0) {
+                return observe?.(observer, []) ?? (() => { });
+            }
+            else {
+                const token = Symbol();
+                const detach = observe?.(observer, resources);
+                observers.set(token, {
+                    observer,
+                    resources: resources === undefined ? undefined
+                        : isString(resources) ? [resources]
+                            : [...resources]
+                });
+                return () => {
+                    try {
+                        detach?.();
+                    }
+                    finally {
+                        observers.delete(token);
+                    }
+                };
+            }
+        },
+        execute(task) {
+            return notify(({ mutated, deleted }) => execute(store => task(immutable({
+                lookup: (specs, opts) => store.lookup(specs, opts),
+                create: specs => store.create(specs).then(mutated),
+                update: specs => store.update(specs).then(mutated),
+                delete: specs => store.delete(specs).then(deleted),
+                insert: (specs, opts) => store.insert(specs, opts).then(mutated),
+                remove: specs => store.remove(specs).then(deleted)
+            }))));
+        },
+        close
+    });
+    async function notify(task) {
+        const mutations = new Map();
+        const value = await task({
+            mutated: entry => {
+                if (entry !== undefined) {
+                    mutations.set(entry, true);
+                }
+                return entry;
+            },
+            deleted: entry => {
+                if (entry !== undefined) {
+                    mutations.set(entry, false);
+                }
+                return entry;
+            }
+        });
+        if (mutations.size > 0) {
+            observers.forEach(({ observer, resources }) => {
+                const event = {};
+                mutations.forEach((exists, id) => {
+                    // `resources` is `undefined` for an unfiltered registration (fires for every mutation)
+                    // and an array — possibly empty — for a filtered one
+                    if (resources === undefined || resources.some(r => isNestedIRI(r, id))) {
+                        event[id] = exists;
+                    }
+                });
+                if (Object.keys(event).length > 0) {
+                    Promise.resolve(event)
+                        .then(observer)
+                        .catch(() => { });
+                }
+            });
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=managing.js.map