@metreeca/keep 0.10.0 → 0.11.0

package/dist/clients/batching.d.ts

@@ -1,61 +1,58 @@
 /**
  * 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.
+ * Lets a connector serve many concurrent store requests with few backend round-trips. Requests of the same kind are
+ * coalesced into a single batch, and the connector supplies one batch {@link Handler} per kind. The resulting
+ * {@link StoreClient} adds conditional CRUD semantics on top, so handlers apply each request unconditionally.
  *
- * Four request types partition the work, each with its own handler:
+ * Four request kinds 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.
+ *  - **`detail`** — materialises each {@link Detail} resource against its `model`; multi-valued members reached
+ *    by the model may be handed to the `select` handler through {@link Broker.select}
+ *  - **`select`** — materialises each {@link Select} collection against its `query`; element resources reached
+ *    by the query may be handed to the `detail` handler through {@link Broker.detail}
+ *  - **`modify`** — creates, updates, or deletes each {@link Modify} target, or links it to a collection
+ *
+ * Retrieval is driven by the requested `model` and `query`, not by the stored graph. A `detail` handler issues a
+ * `select` for each multi-valued member its model reaches, and a `select` handler issues a `detail` for each element
+ * resource its query reaches. Each request thus descends exactly as deep as its `model` or `query` nests, however
+ * deep the underlying graph runs.
+ *
+ * > [!IMPORTANT]
+ * > Handlers run concurrently and exchange nested requests through the {@link Broker}. A handler must not assume any
+ * > ordering between handlers, and must await every nested request it issues before settling the request that
+ * > depends on it.
  *
  * @module
  */
 import type { Property, ResourceShape } from "@metreeca/blue/resource";
-import type { Lazy } from "@metreeca/core";
+import { type Match } from "@metreeca/blue/value";
+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 { Query, Slot, Template } from "@metreeca/qest/model";
+import type { Reference, Resource, Value } from "@metreeca/qest/state";
 import type { StoreClient } from "../index.js";
 /**
  * Requests accepted by {@link Broker}.
  */
-export type Request = Detect | Lookup | Select | Modify;
+export type Request = Detect | Detail | 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 Detail} resolves to the materialised resource, typed by its shape and model
+ *  - a {@link Select} resolves to the {@link Value | values} its collection holds, untyped since its shape is
+ *    carried as a value rather than as a type parameter
  *  - 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;
+export type Response<R extends Request> = R extends Select ? readonly Value[] : R extends Detail<infer T, infer S> ? Match<S, 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.
+ * Carries the `entry` to probe, and resolves to whether that entry exists in the store.
  */
 export type Detect = {
     readonly entry: Reference;
@@ -63,28 +60,28 @@ export type Detect = {
 /**
  * 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.
+ * Carries a single resource (`entry` of `shape`), the `model` to materialise it against, and the `locale` priority
+ * for coalescing its localised content (QEST §6.2). Resolves to the materialised resource.
  *
- * @typeParam T The resource model selecting the result shape
+ * @typeParam T The resource model selecting the members of the result
+ * @typeParam S The shape describing the resource
  */
-export type Lookup<T extends Template = Template> = {
+export type Detail<T extends Template = Template, S extends Lazy<ResourceShape> = Lazy<ResourceShape>> = {
     readonly entry: Reference;
-    readonly shape: Lazy<ResourceShape>;
+    readonly shape: S;
     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.
+ * Carries a single multi-valued property (`field` on `entry` of `shape`), the `query` describing its values, and the
+ * `locale` priority for coalescing its localised content (QEST §6.2). Resolves to the materialised collection: items
+ * for a template query, rows for a projection.
  *
- * @typeParam T The collection query selecting the result shape
+ * @typeParam T The collection query selecting the form of the result
  */
-export type Select<T extends Query = Query> = {
+export type Select<T extends Query<Slot> = Query<Slot>> = {
     readonly entry: Reference;
     readonly shape: Lazy<ResourceShape>;
     readonly field: Property;
@@ -94,25 +91,29 @@ export type Select<T extends Query = Query> = {
 /**
  * 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}.
+ * Carries the `entry` to mutate (of `shape`) and the target `state` to persist. A present `state` creates or updates
+ * the entry, and an omitted `state` deletes it. A request carrying a `link` instead adds `item` to the collection
+ * held by `entry` under `property`, leaving the rest of the entry unchanged. Resolves to the {@link Reference} of the
+ * mutated entry.
  */
 export type Modify = {
     readonly entry: Reference;
     readonly shape: Lazy<ResourceShape>;
     readonly state?: Resource;
+    readonly link?: {
+        readonly property: Property;
+        readonly item: Reference;
+    };
 };
 /**
  * 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.
+ * Supplied by the connector to {@link createBatchingStore}, one per request type. A handler receives every request of
+ * its type accumulated since the previous batch, together with a {@link Broker} for issuing nested requests. It
+ * settles each {@link Deferred} in the batch with its result or error. The returned promise must resolve only once
+ * every request in the batch 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.
+ * Batches are never empty, so handlers need not guard against an empty one.
  *
  * @typeParam R The request variant handled
  */
@@ -122,12 +123,11 @@ export type Handler<R extends Request> = {
 /**
  * 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.
+ * Each batch a {@link Handler} receives is an array of `Deferred` entries. For each entry, the handler reads the
+ * `request` and settles it, calling `resolve` with its result (typed by {@link Response | Response<R>}) or `reject`
+ * with an error.
  *
- * @typeParam R The queued request variant: a {@link Detect} probe, a {@link Lookup} resource fetch,
+ * @typeParam R The queued request variant: a {@link Detect} probe, a {@link Detail} resource fetch,
  *     a {@link Select} collection fetch, or a {@link Modify} mutation
  */
 export type Deferred<R extends Request> = {
@@ -138,10 +138,9 @@ export type Deferred<R extends Request> = {
 /**
  * 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.
+ * Routes each request (detection, detail, selection, modification) to the handler for its type. Each call queues the
+ * request for the next batch and returns a promise that settles with its result. Handlers receive a broker to hand
+ * nested work to a sibling handler.
  */
 export type Broker = {
     /**
@@ -154,18 +153,17 @@ export type Broker = {
      */
     detect(request: Detect): Promise<boolean>;
     /**
-     * Enqueue a {@link Lookup} request.
+     * Enqueue a {@link Detail} 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
+     * @returns A promise resolving to the resource materialised against the request's `model`, settled once the
+     *     owning batch and any nested requests needed to assemble it have resolved
      */
-    lookup<T extends Template>(request: Lookup<T>): Promise<Instance<T>>;
+    detail<S extends Lazy<ResourceShape>, T extends Template>(request: Detail<T, S>): Promise<Match<S, T>>;
     /**
      * Enqueue a {@link Select} request.
      *
@@ -174,21 +172,20 @@ export type Broker = {
      *
      * @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
+     * @returns A promise resolving to the values the collection holds as the request's `query` narrows them,
+     *     items for a template and rows for a projection, settled once the owning batch and any nested requests
+     *     needed to assemble them have resolved
      */
-    select<T extends Query>(request: Select<T>): Promise<Instance<T>>;
+    select<T extends Query<Slot>>(request: Select<T>): Promise<readonly Value[]>;
     /**
      * 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.
+     * Mutates unconditionally, with no existence precondition. A present `state` upserts the entry, creating it if
+     * absent. An omitted `state` deletes the entry, and is a no-op if the entry is absent.
      *
-     * @param request The entry and target state to persist
+     * @param request The entry and target state to persist, or the collection link to add
      *
-     * @returns A promise resolving to the mutated entry's {@link Reference}, settled once the owning
+     * @returns A promise resolving to the {@link Reference} of the mutated entry, settled once the owning
      * batch has completed
      */
     modify(request: Modify): Promise<Reference>;
@@ -196,27 +193,25 @@ export type Broker = {
 /**
  * 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.
+ * Coalesces concurrent {@link StoreClient} calls into batches, each served by the matching `handlers` entry. The
+ * client adds conditional CRUD semantics on top of the handlers: `create`, `update` and `delete` probe for existence
+ * through the `detect` handler before handing the mutation to `modify`. `create` mints the identifier of the new
+ * resource, if its state names none, and links it to the collecting resource.
  *
- * 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.
+ * The `modify` handler receives only requests whose `state` carries no `id` other than their `entry`. A request
+ * failing this check is rejected on its own, and the rest of the batch still applies. If the `modify` handler throws,
+ * the error rejects every request in its batch.
  *
- * @param handlers The batch handlers, one per request type, dispatching detect, lookup, select, and
- *     modify requests
+ * @param handlers The batch handlers, one per request type
  *
- * @returns An immutable {@link StoreClient} that batches its requests through the broker
+ * @returns An immutable {@link StoreClient} serving its requests in batches through `handlers`
  *
- * @throws {RangeError} If a create or update `state` carries an `id` that differs from its `entry`
+ * @throws {@link !RangeError RangeError} If an update or insert `state` carries an `id` that differs from its `entry`,
+ *     or if a create `state` member filling an identifier slot is not a single path segment
  */
 export declare function createBatchingStore(handlers: {
     detect: Handler<Detect>;
-    lookup: Handler<Lookup>;
+    detail: Handler<Detail>;
     select: Handler<Select>;
     modify: Handler<Modify>;
 }): StoreClient;

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

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

package/dist/clients/batching.js

@@ -13,37 +13,36 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { eager } from "@metreeca/blue/value";
-import { immutable } from "@metreeca/core/structures";
-import { createBroker } from "./batching.core.js";
+import { blueprint, collection } from "@metreeca/blue/value";
+import { isString } from "@metreeca/core";
+import { immutable } from "@metreeca/core/values";
+import { createBroker, mint } from "./batching.core.js";
 ////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 /**
  * 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.
+ * Coalesces concurrent {@link StoreClient} calls into batches, each served by the matching `handlers` entry. The
+ * client adds conditional CRUD semantics on top of the handlers: `create`, `update` and `delete` probe for existence
+ * through the `detect` handler before handing the mutation to `modify`. `create` mints the identifier of the new
+ * resource, if its state names none, and links it to the collecting resource.
  *
- * 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.
+ * The `modify` handler receives only requests whose `state` carries no `id` other than their `entry`. A request
+ * failing this check is rejected on its own, and the rest of the batch still applies. If the `modify` handler throws,
+ * the error rejects every request in its batch.
  *
- * @param handlers The batch handlers, one per request type, dispatching detect, lookup, select, and
- *     modify requests
+ * @param handlers The batch handlers, one per request type
  *
- * @returns An immutable {@link StoreClient} that batches its requests through the broker
+ * @returns An immutable {@link StoreClient} serving its requests in batches through `handlers`
  *
- * @throws {RangeError} If a create or update `state` carries an `id` that differs from its `entry`
+ * @throws {@link !RangeError RangeError} If an update or insert `state` carries an `id` that differs from its `entry`,
+ *     or if a create `state` member filling an identifier slot is not a single path segment
  */
 export function createBatchingStore(handlers) {
     const broker = createBroker({
         ...handlers,
         async modify(batch, broker) {
             const items = batch.filter(({ request: { entry, state }, reject }) => {
-                // reject each request whose state id contradicts its entry (§4.1) on its own, so the
+                // reject each request whose state id contradicts its entry on its own, so the
                 // rest of the batch still applies and the check stays out of storage-specific handlers
                 const matching = state?.id === undefined || state.id === entry;
                 if (!matching) {
@@ -65,25 +64,30 @@ export function createBatchingStore(handlers) {
     });
     return immutable({
         async lookup({ entry, shape, model }, { locale = ["und"] } = {}) {
-            // virtual resources have no stored state of their own: their members are derived from
-            // selection constraints rather than from stored content, so the existence probe is skipped.
-            return eager(shape).virtual || await broker.detect({ entry })
-                ? broker.lookup({ entry, shape, model, locale })
+            return await broker.detect({ entry })
+                ? broker.detail({ entry, shape, model, locale })
                 : undefined;
         },
-        async create({ entry, shape, state }) {
-            // the entry identifies the target: a state carrying a different id contradicts it (§4.1)
-            if (state.id !== undefined && state.id !== entry) {
-                throw new RangeError(`mismatched state id <${String(state.id)}> for entry <${entry}>`);
-            }
-            return await broker.detect({ entry })
-                ? undefined
-                : broker.modify({ entry, shape, state });
+        async create({ entry, shape, model, state }) {
+            // the new resource is stored under the identifier its state names, or under one minted for it off the
+            // blueprint of the collection; either way it is the resource probed for existence and written, not the
+            // collection
+            const target = collection(shape, model);
+            const plan = blueprint(shape, model);
+            const { id } = state;
+            const child = isString(id) ? id : mint(entry, plan, state);
+            // a collection a plain property holds is linked to its new member; one exposed through
+            // a foreign property is a view over the member's own link and reaches it on its own
+            return await broker.detect({ entry: child }) ? undefined
+                : broker.modify({ entry: child, shape: plan, state }).then(created => target.foreign
+                    ? created
+                    : broker.modify({ entry, shape, link: { property: target, item: created } }).then(() => created));
         },
         async update({ entry, shape, state }) {
-            // the entry identifies the target: a state carrying a different id contradicts it (§4.1)
-            if (state.id !== undefined && state.id !== entry) {
-                throw new RangeError(`mismatched state id <${String(state.id)}> for entry <${entry}>`);
+            // the entry identifies the target: a state carrying a different id contradicts it
+            const { id } = state;
+            if (id !== undefined && id !== entry) {
+                throw new RangeError(`mismatched state id <${String(id)}> for entry <${entry}>`);
             }
             return await broker.detect({ entry })
                 ? broker.modify({ entry, shape, state })

package/dist/clients/batching.js.map

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

package/dist/clients/validating.d.ts

@@ -2,37 +2,40 @@ import type { StoreClient } from "../index.js";
 /**
  * Creates a validating store backed by a delegate.
  *
- * Each method validates the relevant inputs against the supplied shape before delegating to `store`:
+ * Each method validates its inputs against the supplied shape before forwarding the request to `store`:
  *
- * - `entry` is checked for absolute-IRI form (no query string, no fragment) — failures rejected as `RangeError`
- * - `state.id`, when present, is checked for equality with `entry` — mismatches rejected as `RangeError`, since
- *   the entry identifies the target and a contradicting payload identity is a caller error
- * - `model` is validated as a {@link @metreeca/blue!validate | template} for
- *   {@link StoreClient.lookup lookup}, with the `lookup` `plain`/`depth`/`limit` opts forwarded as
- *   query-complexity caps
- * - `state` is validated as a resource for {@link StoreClient.create create}/
- *   {@link StoreClient.update update}/{@link StoreClient.insert insert}; `create` and
- * `update` always cap captive expansion at depth `0` (inline captive batches rejected), while `insert` honours its
- * `depth` opt
- *   (omitted leaves expansion unbounded)
+ * - `entry` must be an absolute IRI with no query string and no fragment; otherwise the request is rejected with a
+ *   {@link !RangeError RangeError}
+ * - `model` is validated as a {@link @metreeca/blue!validate | template} for {@link StoreClient.lookup lookup},
+ *   within the query-complexity bounds (`plain`, `depth`, `limit`) of the caller's
+ *   {@link StoreScope | retrieval scope}, and as a collection slice for {@link StoreClient.create create}
+ * - `state.id`, if present, must be nested under `entry` for {@link StoreClient.create create}, and equal to `entry`
+ *   for {@link StoreClient.update update} and {@link StoreClient.insert insert}; otherwise the request is rejected
+ *   with a {@link !RangeError RangeError}
+ * - `state` is validated as a resource with captive expansion capped at depth `0`, so inline captive batches are
+ *   rejected; {@link StoreClient.create create} validates it against the shape of the collected resources, and
+ *   {@link StoreClient.update update} and {@link StoreClient.insert insert} against the supplied shape
  *
- * The `trusted` opt controls whether {@link StoreClient.lookup lookup} responses are re-validated
- * against the shape narrowed by the caller's `model` template before surfacing. Defaults to `false`
- * — connectors whose backing source isn't trusted to deliver shape-conforming data (for example, a
- * remote REST endpoint) get the safe default. Local stores that compute results themselves should
- * pass `trusted: true` to skip the redundant pass.
+ * The `trusted` option controls whether {@link StoreClient.lookup lookup} responses are re-validated against the
+ * shape, as narrowed by the caller's `model`. It defaults to `false`, the safe choice for connectors whose source may
+ * deliver non-conforming data, such as a remote REST endpoint. Local stores that compute results themselves can pass
+ * `trusted: true` to skip the redundant check.
  *
- * Validation failures surface as {@link @metreeca/core!TraceError | TraceError} or `RangeError` rejections per the
- * unified {@link Store} error channel.
+ * Validation failures surface as {@link @metreeca/core!TraceError | TraceError} or {@link !RangeError RangeError}
+ * rejections, in line with the unified {@link Store} error channel.
  *
- * @param store - Inner StoreClient to delegate to after validation
+ * @param store - Inner StoreClient receiving the validated requests
  * @param options - Optional validation options
- * @param options.trusted - When `true`, skips re-validation of the {@link StoreClient.lookup lookup}
- *     response against the shape narrowed by the caller's `model`; defaults to `false`
  *
  * @returns An immutable {@link StoreClient} wrapping `store` with input validation
  */
 export declare function createValidatingStore(store: StoreClient, { trusted }?: {
+    /**
+     * Whether to skip re-validation of {@link StoreClient.lookup lookup} responses against the shape, as narrowed by
+     * the caller's `model`.
+     *
+     * @defaultValue `false`, treating the wrapped store as untrusted
+     */
     readonly trusted?: boolean;
 }): StoreClient;
 //# sourceMappingURL=validating.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validating.d.ts","sourceRoot":"","sources":["../../src/clients/validating.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAS,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,EAEzD,OAAe,EAEf,GAAE;IAEF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAErB,GAAG,WAAW,CA+GnB"}
+{"version":3,"file":"validating.d.ts","sourceRoot":"","sources":["../../src/clients/validating.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAS,WAAW,EAAc,MAAM,aAAa,CAAC;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,EAAE,EAEzD,OAAe,EAEf,GAAE;IAEF;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAErB,GAAG,WAAW,CAkJnB"}