@metreeca/keep 0.9.0 → 0.10.0

package/README.md

@@ -2,9 +2,13 @@
 
 [![npm](https://img.shields.io/npm/v/@metreeca/keep)](https://www.npmjs.com/package/@metreeca/keep)
 
-{TBD: one-line description}
+Core model-driven storage API for the [@metreeca/keep](https://github.com/metreeca/keep) linked data storage framework.
 
-{TBD: value proposition and key capabilities}
+Defines the backend-agnostic `StoreClient` and `Store` interfaces for persisting and retrieving linked data resources as
+shape-validated states and query projections. Resource shapes are defined using
+[@metreeca/blue](https://github.com/metreeca/blue); resource states and retrieval templates follow the data and query
+models defined by [@metreeca/qest](https://github.com/metreeca/qest). Actual storage is delegated to backend
+[connector packages](https://github.com/metreeca/keep#installation).
 
 # Installation
 
@@ -12,37 +16,230 @@
 npm install @metreeca/keep
 ```
 
-> [!WARNING]
->
-> TypeScript consumers must use `"moduleResolution": "nodenext"/"node16"/"bundler"` in `tsconfig.json`.
-> The legacy `"node"` resolver is not supported.
-
 # Usage
 
 > [!NOTE]
 >
-> This section introduces essential concepts; for complete coverage, see the API reference:
->
-> | Module | Description |
-> |--------|-------------|
-> | {TBD}  | {TBD}       |
+> This section introduces essential concepts; for complete coverage, see the
+> [API reference](https://metreeca.github.io/keep/modules/_metreeca_keep.html).
+
+| Module                                  | Description              |
+|-----------------------------------------|--------------------------|
+| [@metreeca/keep][keep]                  | Model-driven storage API |
+| **Stores**                              |                          |
+| [@metreeca/keep/caching][caching]       | Caching store wrapper    |
+| [@metreeca/keep/managing][managing]     | Managing store wrapper   |
+| **Store Clients**                       |                          |
+| [@metreeca/keep/validating][validating] | Validating store wrapper |
+| [@metreeca/keep/batching][batching]     | Batching store client    |
+
+[keep]: https://metreeca.github.io/keep/modules/_metreeca_keep.html
+
+[validating]: https://metreeca.github.io/keep/modules/_metreeca_keep.validating.html
+
+[batching]: https://metreeca.github.io/keep/modules/_metreeca_keep.batching.html
+
+[caching]: https://metreeca.github.io/keep/modules/_metreeca_keep.caching.html
+
+[managing]: https://metreeca.github.io/keep/modules/_metreeca_keep.managing.html
+
+All store methods accept an `entry` that MUST be an absolute IRI without query string or fragment — non-conforming
+entries reject with `RangeError`. `model` and `state` are validated against the supplied shape; validation failures
+reject with a `TraceError`. Network, storage, and other processing errors reject with a structured `Problem`.
+
+## Retrieving Resources
+
+```typescript
+// single resource retrieval
+
+const product = await store.lookup({
+	entry: "http://example.com/products/1",
+	shape: ProductShape,
+	model: {
+		name: "",
+		price: 0,
+		vendor: {
+			id: "",
+			name: ""
+		}
+	}
+});
+
+// collection retrieval with filtering, ordering, and pagination
+
+const catalog = await store.lookup({
+	entry: "http://example.com/products/",
+	shape: ProductShape,
+	model: {
+		products: [{
+			id: "",
+			name: "",
+			price: 0,
+			">=price": 50,        // price ≥ 50
+			"~name": "widget",    // name contains "widget"
+			"^price": 1,          // sort by price ascending
+			"@": 0,               // offset
+			"#": 25               // limit
+		}]
+	}
+});
+```
 
-{TBD: usage overview and examples}
+## Creating and Updating Resources
+
+```typescript
+await store.create({
+	entry: "http://example.com/products/42", shape: ProductShape, state: {
+		id: "http://example.com/products/42",
+		name: "Widget",
+		price: 29.99,
+		vendor: "http://example.com/vendors/acme"
+	}
+});
+
+await store.update({
+	entry: "http://example.com/products/42", shape: ProductShape, state: {
+		id: "http://example.com/products/42",
+		name: "Widget",
+		price: 39.99,
+		vendor: "http://example.com/vendors/acme"
+	}
+});
+```
 
-# Integrated Ecosystem
+## Deleting Resources
 
-> [!IMPORTANT]
->
-> **@metreeca/keep** defines {TBD}; applications are free to {TBD}.
+```typescript
+await store.delete({ entry: "http://example.com/products/42", shape: ProductShape });
+```
+
+## Loading Data
+
+```typescript
+// unconditionally upsert (create or replace)
+
+await store.insert({
+	entry: "http://example.com/products/42", shape: ProductShape, state: {
+		id: "http://example.com/products/42",
+		name: "Widget",
+		price: 39.99,
+		vendor: "http://example.com/vendors/acme"
+	}
+});
+
+// unconditionally remove (silently succeeds if absent)
+
+await store.remove({ entry: "http://example.com/products/42", shape: ProductShape });
+```
+
+## Observing Mutations
+
+```typescript
+const unsubscribe = store.observe(mutations => {
+	for (const [id, exists] of Object.entries(mutations)) {
+		console.log(exists ? "upserted" : "removed", id);
+	}
+}, "http://example.com/products/");
+
+unsubscribe(); // stop receiving events
+```
+
+The second argument scopes the observer to the given resources and their descendants; omit it to receive all mutations,
+pass an empty array to detach the observer.
+
+## Executing Transactions
+
+```typescript
+await store.execute(async store => {
+	await store.create({ entry: product.id, shape: ProductShape, state: product });
+	await store.update({ entry: inventory.id, shape: InventoryShape, state: inventory });
+});
+```
+
+Cross-backend isolation semantics, concurrency models, and the buffer-and-flush emulation pattern are documented in the
+[Transaction Design](https://metreeca.github.io/keep/documents/_metreeca_keep.Transaction_Design.html) companion
+document.
+
+# Implementing Connectors
+
+A backend connector implements the bare `StoreClient` interface against its native primitives, then wraps it with the
+`createValidatingStore` helper from
+[@metreeca/keep/validating](https://metreeca.github.io/keep/modules/_metreeca_keep.validating.html) for shape-driven
+input validation and `createManagingStore` from
+[@metreeca/keep/managing](https://metreeca.github.io/keep/modules/_metreeca_keep.managing.html) for mutation events,
+transactional execution, and lifecycle:
 
-**@metreeca/keep** is part of an integrated ecosystem for rapid application development:
+```typescript
+import type { StoreClient, Store } from "@metreeca/keep";
+import { createManagingStore } from "@metreeca/keep/managing";
+import { createValidatingStore } from "@metreeca/keep/validating";
+
+function createMyStore(): Store {
+
+	const backend: StoreClient = {
+
+		lookup({ entry, shape, model }) { /* query the backend, return matching data or undefined */ },
+
+		create({ entry, shape, state }) { /* create if absent, return entry or undefined */ },
+		update({ entry, shape, state }) { /* update if present, return entry or undefined */ },
+		delete({ entry, shape }) { /* delete if present, return entry or undefined */ },
+
+		insert({ entry, shape, state }) { /* upsert unconditionally, return entry */ },
+		remove({ entry, shape }) { /* remove unconditionally, return entry */ }
+
+	};
+
+	return createManagingStore(createValidatingStore(backend, { trusted: true }), {
+
+		execute: task => { /* run task within a backend transaction */ },
+		close: () => { /* release connections */ }
+
+	});
+
+}
+```
+
+Pass `trusted: true` to `createValidatingStore` when the backend is trusted to deliver shape-conforming data, so
+`lookup` responses skip the redundant outbound validation pass. Supply `execute` to `createManagingStore` to route every
+standalone call and the entire `execute` task body through the backend's transaction primitive; omit it for
+non-transactional backends and the wrapper degrades to per-call atomicity. `close` defaults to a no-op.
+
+All errors reach the caller as promise rejections through the unified Store error channel — `RangeError` for malformed
+entries, `TraceError` for shape validation failures, `Problem` for network, storage, or other processing failures.
+Connectors MUST preserve this contract: convert backend-specific exceptions into `Problem` rejections and let validation
+rejections propagate untouched.
+
+Each connector MUST document its supported transaction isolation level and mutation event scope per the conventions
+defined in the [Transaction Design](https://metreeca.github.io/keep/documents/_metreeca_keep.Transaction_Design.html)
+companion document.
+
+## Testing
+
+Use [@metreeca/keep-suite](https://github.com/metreeca/keep/tree/main/packages/keep-suite) to run the full conformance
+suite against your connector:
+
+```typescript
+import { testStore } from "@metreeca/keep-suite";
+import { describe } from "vitest";
+
+describe("my-store", () => testStore({
+
+	build: () => createMyStore(), // create a store with schema but no data
+
+	contains: id => { /* true if the resource has any stored data */ },
+	includes: (resource, shape) => { /* true if every fact described by `resource` is present */ },
+	excludes: (resource, shape) => { /* true if every fact described by `resource` is absent */ },
+
+	populate: () => { /* clear and reload the sample dataset */ },
+	generate: (sample, shape) => { /* insert an isolated copy of `sample` with a unique id */ },
+
+	close: () => { /* optional: release store resources after all tests */ }
+
+}));
+```
 
-| Package                     | Description                                                |
-|-----------------------------|------------------------------------------------------------|
-| @metreeca/qest              | Data types for client-driven, queryable REST/JSON APIs     |
-| @metreeca/blue _(upcoming)_ | Shape-based validation for resources, patches, and queries |
-| **@metreeca/keep**          | Shape-driven storage framework with pluggable adapters     |
-| @metreeca/gate _(upcoming)_ | Shape-driven REST/JSON API publishing                      |
+Filter to a subset of sub-suites with the `match` option (for example, `["Retrieve", "PersistCreate"]`); see the
+[API reference](https://metreeca.github.io/keep/modules/_metreeca_keep-suite.html) for the full list.
 
 # Support
 

package/dist/clients/batching.core.d.ts

@@ -0,0 +1,29 @@
+import type { Broker, Detect, Handler, Lookup, Modify, Select } from "./batching.js";
+/**
+ * Creates a batching request {@link Broker}.
+ *
+ * Backs {@link createBatchingStore}: returns a broker that queues each submitted request by type and
+ * drives the queues to completion against the supplied handlers. The first submission kicks a drain
+ * loop that runs all four handlers concurrently, round by round, until every queue is quiescent;
+ * requests issued mid-round, whether forwarded by a handler or freshly submitted, are served on a
+ * later round, so handlers must not assume any ordering between handlers.
+ *
+ * Handler errors poison the run: every still-pending {@link Deferred} is rejected with the
+ * originating error, so callers see a deterministic failure rather than a hang.
+ *
+ * @param handlers The batch handlers, one per request type. Each settles every {@link Deferred} in
+ *     its batch and may issue nested {@link Broker.lookup} / {@link Broker.select} calls while
+ *     processing; its returned promise must settle only after every owned request, including
+ *     transitively nested ones, has settled.
+ *
+ * @returns An immutable {@link Broker} surface for enqueuing requests and receiving their
+ *     materialised results; each call returns a promise that settles when the relevant batch
+ *     completes
+ */
+export declare function createBroker(handlers: {
+    detect: Handler<Detect>;
+    lookup: Handler<Lookup>;
+    select: Handler<Select>;
+    modify: Handler<Modify>;
+}): Broker;
+//# sourceMappingURL=batching.core.d.ts.map

package/dist/clients/batching.core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batching.core.d.ts","sourceRoot":"","sources":["../../src/clients/batching.core.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAY,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAW,MAAM,EAAE,MAAM,eAAe,CAAC;AAExG;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE;IAEtC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACvB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACvB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IACvB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;CAEvB,GAAG,MAAM,CAgIT"}

package/dist/clients/batching.core.js

@@ -0,0 +1,114 @@
+/*
+ * 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.
+ */
+import { immutable } from "@metreeca/core/structures";
+/**
+ * Creates a batching request {@link Broker}.
+ *
+ * Backs {@link createBatchingStore}: returns a broker that queues each submitted request by type and
+ * drives the queues to completion against the supplied handlers. The first submission kicks a drain
+ * loop that runs all four handlers concurrently, round by round, until every queue is quiescent;
+ * requests issued mid-round, whether forwarded by a handler or freshly submitted, are served on a
+ * later round, so handlers must not assume any ordering between handlers.
+ *
+ * Handler errors poison the run: every still-pending {@link Deferred} is rejected with the
+ * originating error, so callers see a deterministic failure rather than a hang.
+ *
+ * @param handlers The batch handlers, one per request type. Each settles every {@link Deferred} in
+ *     its batch and may issue nested {@link Broker.lookup} / {@link Broker.select} calls while
+ *     processing; its returned promise must settle only after every owned request, including
+ *     transitively nested ones, has settled.
+ *
+ * @returns An immutable {@link Broker} surface for enqueuing requests and receiving their
+ *     materialised results; each call returns a promise that settles when the relevant batch
+ *     completes
+ */
+export function createBroker(handlers) {
+    const queues = Object.fromEntries(Object.entries(handlers).map(([key, handler]) => {
+        const items = [];
+        return [key, {
+                items,
+                drain: async () => {
+                    if (items.length > 0) {
+                        const batch = items.slice();
+                        await handler(batch, broker); // ;(cast) erased to the handler's union parameter
+                        items.splice(0, batch.length);
+                    }
+                },
+                purge: error => {
+                    items.forEach(deferred => deferred.reject(error));
+                    items.length = 0;
+                }
+            }];
+    }));
+    // Inner surface handed to the handlers: nested calls enqueue without kicking a drain.
+    const broker = immutable({
+        detect(request) {
+            return new Promise((resolve, reject) => queues.detect.items.push({ request, resolve, reject }));
+        },
+        lookup(request) {
+            return new Promise((resolve, reject) => queues.lookup.items.push({ request, resolve, reject }));
+        },
+        select(request) {
+            return new Promise((resolve, reject) => queues.select.items.push({ request, resolve, reject }));
+        },
+        modify(request) {
+            return new Promise((resolve, reject) => queues.modify.items.push({ request, resolve, reject }));
+        }
+    });
+    // Public surface: every call enqueues through the inner broker and kicks a drain via `process`.
+    return immutable({
+        detect(request) {
+            return process(() => broker.detect(request));
+        },
+        lookup(request) {
+            return process(() => broker.lookup(request));
+        },
+        select(request) {
+            return process(() => broker.select(request));
+        },
+        modify(request) {
+            return process(() => broker.modify(request));
+        }
+    });
+    // Kicks a drain only when every queue is idle: a running drain keeps its snapshot queued, so
+    // "all empty" means "no drain in flight". The kick is a microtask, so a synchronous burst of
+    // submissions coalesces into one drain. The check runs before `submit` enqueues, or it would
+    // always see the request it just pushed.
+    function process(submit) {
+        // a running drain keeps its snapshot in the queues until the round ends, so any non-empty
+        // queue means a drain is already in flight; all-empty is the only "no drain running" state
+        if (Object.values(queues).every(queue => queue.items.length === 0)) {
+            Promise.resolve().then(async () => {
+                // Drain in rounds until every queue is quiescent, all four handlers concurrently per
+                // round. A handler keeps its snapshot in the queue across the `await` (so the idle-check
+                // still sees work and won't kick a second drain) and removes exactly it on success;
+                // anything pushed mid-round is served next round. A throw leaves the snapshot queued to purge.
+                try {
+                    while (Object.values(queues).some(queue => queue.items.length > 0)) {
+                        await Promise.all(Object.values(queues).map(queue => queue.drain()));
+                    }
+                }
+                catch (error) {
+                    // A handler throw poisons the run: purge every queue so pending callers reject
+                    // instead of hanging; already-settled entries no-op.
+                    Object.values(queues).forEach(queue => queue.purge(error));
+                }
+            });
+        }
+        return submit();
+    }
+}
+//# sourceMappingURL=batching.core.js.map

package/dist/clients/batching.core.js.map

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

package/dist/clients/batching.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Batching store client.
+ *
+ * Builds a {@link StoreClient} that coalesces concurrent requests of the same kind into a single
+ * batch, so a connector can serve many requests with one backend round-trip. A connector author
+ * supplies one {@link Handler} per request type to {@link createBatchingStore}; the returned client
+ * routes every call through a {@link Broker} that queues like-typed requests and hands each handler
+ * the whole batch it accumulated.
+ *
+ * Four request types partition the work, each with its own handler:
+ *
+ *  - **`detect`** — probes whether each {@link Detect} entry exists in the store
+ *  - **`lookup`** — materialises each {@link Lookup} against its `model`; multi-valued slots reached
+ *    by the model may be delegated to the `select` handler via {@link Broker.select}
+ *  - **`select`** — materialises each {@link Select} collection (see {@link Query} for the admitted
+ *    forms); element resources reached by the query may be delegated to the `lookup` handler via
+ *    {@link Broker.lookup}
+ *  - **`modify`** — creates, updates, or deletes each {@link Modify} target
+ *
+ * Retrieval is driven by the requested `model` and `query`, not by the stored graph: `lookup` and
+ * `select` hand work back and forth, `lookup` spawning a `select` for each multi-valued slot its
+ * model reaches and `select` spawning a `lookup` for each element resource its query reaches. The
+ * handover recurses through this alternation and bottoms out where the `model` or `query` stops
+ * nesting, so each request descends exactly as deep as it asks for, however deep the underlying
+ * graph runs.
+ *
+ * Handlers run concurrently and forward nested requests to one another through the {@link Broker}, so
+ * a handler must not assume any ordering between handlers, and must await every nested promise it
+ * issues before settling the request that depends on it. Correctness rests on this data dependency
+ * alone, not on handler scheduling.
+ *
+ * @module
+ */
+import type { Property, ResourceShape } from "@metreeca/blue/resource";
+import type { Lazy } from "@metreeca/core";
+import type { Tag } from "@metreeca/core/language";
+import type { Reference, Resource } from "@metreeca/qest/resource";
+import type { Instance, Query, Template } from "@metreeca/qest/template";
+import type { StoreClient } from "../index.js";
+/**
+ * Requests accepted by {@link Broker}.
+ */
+export type Request = Detect | Lookup | Select | Modify;
+/**
+ * Result of running a {@link Request}, narrowed by request variant:
+ *
+ *  - a {@link Detect} resolves to a `boolean` existence flag
+ *  - a {@link Lookup} resolves to its materialised resource {@link Instance}
+ *  - a {@link Select} resolves to its materialised collection {@link Instance}
+ *  - a {@link Modify} resolves to its mutated entry's {@link Reference}
+ *
+ * @typeParam R The request whose result type is selected
+ */
+export type Response<R extends Request> = R extends Select<infer T> ? Instance<T> : R extends Lookup<infer T> ? Instance<T> : R extends Modify ? Reference : R extends Detect ? boolean : never;
+/**
+ * Resource existence request.
+ *
+ * Carries the `entry` to probe; resolves to whether that entry exists in the store.
+ */
+export type Detect = {
+    readonly entry: Reference;
+};
+/**
+ * Resource retrieval request.
+ *
+ * Carries a single resource (`entry` of `shape`), the `model` against which to materialise it, and
+ * the `locale` priority driving language negotiation for its localised content (§6.2). Resolves to
+ * the materialised resource.
+ *
+ * @typeParam T The resource model selecting the result shape
+ */
+export type Lookup<T extends Template = Template> = {
+    readonly entry: Reference;
+    readonly shape: Lazy<ResourceShape>;
+    readonly model: T;
+    readonly locale: readonly Tag[];
+};
+/**
+ * Collection retrieval request.
+ *
+ * Carries a single multi-valued property (`field` on `entry` of `shape`), the `query` describing the
+ * shape of its values (one of the {@link Query} arms), and the `locale` priority driving language
+ * negotiation for its localised content (§6.2). Resolves to the materialised collection.
+ *
+ * @typeParam T The collection query selecting the result shape
+ */
+export type Select<T extends Query = Query> = {
+    readonly entry: Reference;
+    readonly shape: Lazy<ResourceShape>;
+    readonly field: Property;
+    readonly query: T;
+    readonly locale: readonly Tag[];
+};
+/**
+ * Resource mutation request.
+ *
+ * Carries the `entry` to mutate (of `shape`) and the target `state` to persist: a present `state`
+ * creates or updates the entry, an omitted `state` deletes it. Resolves to the mutated entry's
+ * {@link Reference}.
+ */
+export type Modify = {
+    readonly entry: Reference;
+    readonly shape: Lazy<ResourceShape>;
+    readonly state?: Resource;
+};
+/**
+ * Batch handler for a single request type.
+ *
+ * Supplied by the connector author to {@link createBatchingStore}, one per request type. Receives the
+ * whole batch the {@link Broker} has accumulated for this type, together with the broker for issuing
+ * nested requests, and settles each {@link Deferred} in the batch with its result or error. The
+ * returned promise must resolve only once every request the handler owns has settled, including any
+ * nested requests issued through the broker.
+ *
+ * The broker never dispatches an empty batch, so the handler need not guard against one.
+ *
+ * @typeParam R The request variant handled
+ */
+export type Handler<R extends Request> = {
+    (batch: readonly Deferred<R>[], broker: Broker): Promise<void>;
+};
+/**
+ * A queued request paired with its promise-resolution hooks.
+ *
+ * Each batch a {@link Handler} receives is an array of `Deferred` entries. The handler reads each
+ * `request`, then calls `resolve` with its result (typed by {@link Response | Response<R>}) or
+ * `reject` with an error, once the backend round-trip and any nested requests issued through the
+ * {@link Broker} have settled.
+ *
+ * @typeParam R The queued request variant: a {@link Detect} probe, a {@link Lookup} resource fetch,
+ *     a {@link Select} collection fetch, or a {@link Modify} mutation
+ */
+export type Deferred<R extends Request> = {
+    readonly request: R;
+    resolve(value: Response<R>): void;
+    reject(error: unknown): void;
+};
+/**
+ * Request-submission surface over the batching {@link Handler | handlers}.
+ *
+ * Brokers each store request (detection, lookup, selection, modification) to its handler: a call
+ * enqueues the request and returns a promise that settles with the request's result. Held both by
+ * outside callers, as the entry point, and by handlers, to delegate nested work to a sibling
+ * handler.
+ */
+export type Broker = {
+    /**
+     * Enqueue a {@link Detect} request.
+     *
+     * @param request The entry to probe
+     *
+     * @returns A promise resolving to `true` when the request's entry exists in the store; `false`
+     * otherwise
+     */
+    detect(request: Detect): Promise<boolean>;
+    /**
+     * Enqueue a {@link Lookup} request.
+     *
+     * Carries no existence precondition: an entry with no stored state resolves to an empty instance of
+     * the request's `model` rather than rejecting.
+     *
+     * @param request The resource and model to materialise
+     *
+     * @returns A promise resolving to the materialised {@link Instance} of the request's `model` (the
+     * resource value), settled once the owning batch and any nested promises needed to assemble its
+     * value have resolved
+     */
+    lookup<T extends Template>(request: Lookup<T>): Promise<Instance<T>>;
+    /**
+     * Enqueue a {@link Select} request.
+     *
+     * Carries no existence precondition: an entry with no matching members resolves to an empty
+     * collection rather than rejecting.
+     *
+     * @param request The property and query to materialise
+     *
+     * @returns A promise resolving to the materialised {@link Instance} of the request's `query` (one
+     * of the tuple-wrapped {@link Query} arms), settled once the owning batch and any nested promises
+     * needed to assemble its value have resolved
+     */
+    select<T extends Query>(request: Select<T>): Promise<Instance<T>>;
+    /**
+     * Enqueue a {@link Modify} request.
+     *
+     * Mutates unconditionally, with no existence precondition: a present `state` upserts the entry,
+     * creating it when absent; an omitted `state` deletes it leniently, resolving as a no-op when
+     * absent.
+     *
+     * @param request The entry and target state to persist
+     *
+     * @returns A promise resolving to the mutated entry's {@link Reference}, settled once the owning
+     * batch has completed
+     */
+    modify(request: Modify): Promise<Reference>;
+};
+/**
+ * Creates a batching store client backed by a set of request handlers.
+ *
+ * Routes every {@link StoreClient} call through a {@link Broker} that coalesces concurrent requests
+ * into batches and dispatches each batch through the matching `handlers` entry. Adds conditional CRUD
+ * semantics on top of the handlers: existence is probed through the `detect` handler before a create,
+ * update, or delete is delegated to `modify`, sparing each handler that bookkeeping.
+ *
+ * The `modify` handler is additionally wrapped so the batching layer, not the storage handler,
+ * enforces the §4.1 state-`id` constraint: a request whose `state` carries an `id` other than its
+ * `entry` is rejected on its own before dispatch, and a backend failure is settled as a rejection
+ * across the surviving batch rather than surfaced as a handler throw. The wrapped handler thus always
+ * receives a non-empty batch of pre-validated requests to apply unconditionally.
+ *
+ * @param handlers The batch handlers, one per request type, dispatching detect, lookup, select, and
+ *     modify requests
+ *
+ * @returns An immutable {@link StoreClient} that batches its requests through the broker
+ *
+ * @throws {RangeError} If a create or update `state` carries an `id` that differs from its `entry`
+ */
+export declare function createBatchingStore(handlers: {
+    detect: Handler<Detect>;
+    lookup: Handler<Lookup>;
+    select: Handler<Select>;
+    modify: Handler<Modify>;
+}): StoreClient;
+//# sourceMappingURL=batching.d.ts.map

package/dist/clients/batching.d.ts.map

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