@bandeira-tech/b3nd-save 0.8.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 B3nd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/esm/_dnt.shims.d.ts

@@ -0,0 +1,2 @@
+export declare const dntGlobalThis: Omit<typeof globalThis, never>;
+//# sourceMappingURL=_dnt.shims.d.ts.map

package/esm/_dnt.shims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dnt.shims.d.ts","sourceRoot":"","sources":["../src/_dnt.shims.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,gCAA2C,CAAC"}

package/esm/_dnt.shims.js

@@ -0,0 +1,57 @@
+const dntGlobals = {};
+export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
+function createMergeProxy(baseObj, extObj) {
+    return new Proxy(baseObj, {
+        get(_target, prop, _receiver) {
+            if (prop in extObj) {
+                return extObj[prop];
+            }
+            else {
+                return baseObj[prop];
+            }
+        },
+        set(_target, prop, value) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            baseObj[prop] = value;
+            return true;
+        },
+        deleteProperty(_target, prop) {
+            let success = false;
+            if (prop in extObj) {
+                delete extObj[prop];
+                success = true;
+            }
+            if (prop in baseObj) {
+                delete baseObj[prop];
+                success = true;
+            }
+            return success;
+        },
+        ownKeys(_target) {
+            const baseKeys = Reflect.ownKeys(baseObj);
+            const extKeys = Reflect.ownKeys(extObj);
+            const extKeysSet = new Set(extKeys);
+            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
+        },
+        defineProperty(_target, prop, desc) {
+            if (prop in extObj) {
+                delete extObj[prop];
+            }
+            Reflect.defineProperty(baseObj, prop, desc);
+            return true;
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+            if (prop in extObj) {
+                return Reflect.getOwnPropertyDescriptor(extObj, prop);
+            }
+            else {
+                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
+            }
+        },
+        has(_target, prop) {
+            return prop in extObj || prop in baseObj;
+        },
+    });
+}

package/esm/byte-entity-shim.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Byte-only EntityStore shim — shared transition helper.
+ *
+ * Wraps a backend's byte-shaped private operations (`_writeBytes`,
+ * `_readBytes`, `_deleteBytes`) behind the `EntityStore` interface
+ * while only `BYTES_ENTITY` is supported. The meta returned by
+ * {@link bytesOnlyEntitySupport} carries the source schema so the
+ * shim can detect any non-BYTES schema at op time and surface a
+ * per-entry failure (or reject on `read`, which has no per-entry
+ * error channel).
+ *
+ * Future per-backend PRs add native layouts for custom schemas; this
+ * file goes away (or shrinks) once every backend can route any
+ * schema natively.
+ */
+import type { DeleteResult, Output } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import { type EntityMeta, type EntityRecord, type EntitySchema } from "./entity.js";
+import type { StoreEntry, StoreWriteResult } from "./types.js";
+export declare function isBytesEntity(schema: EntitySchema): boolean;
+/** EntityMeta produced by bytes-only backends. */
+export interface BytesOnlyEntityMeta extends EntityMeta {
+    readonly schema: EntitySchema;
+    readonly isBytes: boolean;
+}
+/** Compile a schema into the bytes-only meta. Pure. */
+export declare function bytesOnlyEntitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
+/**
+ * Route a schema-aware write through the backend's byte path when
+ * `meta` is for BYTES_ENTITY; otherwise return per-entry failures.
+ */
+export declare function bytesOnlyWrite(meta: BytesOnlyEntityMeta, storeName: string, entries: {
+    uri: string;
+    record: EntityRecord;
+}[], writeBytes: (entries: StoreEntry[]) => Promise<StoreWriteResult[]>): Promise<StoreWriteResult[]>;
+/**
+ * Route a schema-aware read through the backend's byte path when
+ * `meta` is for BYTES_ENTITY; otherwise reject. Read results are
+ * re-wrapped as `{ payload: bytes }` records to match the `EntityStore`
+ * read contract.
+ */
+export declare function bytesOnlyRead<T = EntityRecord | undefined>(meta: BytesOnlyEntityMeta, storeName: string, urls: string[], readBytes: (urls: string[]) => Promise<Output<unknown>[]>): Promise<Output<T>[]>;
+/**
+ * Route a schema-aware delete through the backend's byte path when
+ * `meta` is for BYTES_ENTITY; otherwise return per-entry failures.
+ */
+export declare function bytesOnlyDelete(meta: BytesOnlyEntityMeta, storeName: string, uris: string[], deleteBytes: (uris: string[]) => Promise<DeleteResult[]>): Promise<DeleteResult[]>;
+//# sourceMappingURL=byte-entity-shim.d.ts.map

package/esm/byte-entity-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-entity-shim.d.ts","sourceRoot":"","sources":["../src/byte-entity-shim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,kEAAkE,CAAC;AAE7G,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAgB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE7E,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAE3D;AAED,kDAAkD;AAClD,MAAM,WAAW,mBAAoB,SAAQ,UAAU;IACrD,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAiBD,uDAAuD;AACvD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,YAAY,GACnB,mBAAmB,CAMrB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,mBAAmB,EACzB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,EAAE,EAChD,UAAU,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,OAAO,CAAC,gBAAgB,EAAE,CAAC,GACjE,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiD7B;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC9D,IAAI,EAAE,mBAAmB,EACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EAAE,EACd,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,GACxD,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAQtB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,mBAAmB,EACzB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,GACvD,OAAO,CAAC,YAAY,EAAE,CAAC,CAczB"}

package/esm/byte-entity-shim.js

@@ -0,0 +1,138 @@
+/**
+ * Byte-only EntityStore shim — shared transition helper.
+ *
+ * Wraps a backend's byte-shaped private operations (`_writeBytes`,
+ * `_readBytes`, `_deleteBytes`) behind the `EntityStore` interface
+ * while only `BYTES_ENTITY` is supported. The meta returned by
+ * {@link bytesOnlyEntitySupport} carries the source schema so the
+ * shim can detect any non-BYTES schema at op time and surface a
+ * per-entry failure (or reject on `read`, which has no per-entry
+ * error channel).
+ *
+ * Future per-backend PRs add native layouts for custom schemas; this
+ * file goes away (or shrinks) once every backend can route any
+ * schema natively.
+ */
+import { storageFailure } from "./errors.js";
+import { BYTES_ENTITY, } from "./entity.js";
+export function isBytesEntity(schema) {
+    return schema.name === BYTES_ENTITY.name;
+}
+/** EntitySupport for a backend that currently only honors BYTES_ENTITY. */
+function bytesOnlySupport(schema) {
+    if (isBytesEntity(schema)) {
+        return { entity: schema.name, supported: ["payload"], unsupported: [] };
+    }
+    return {
+        entity: schema.name,
+        supported: [],
+        unsupported: schema.fields.map((f) => ({
+            name: f.name,
+            reason: "backend currently routes BYTES_ENTITY only",
+        })),
+    };
+}
+/** Compile a schema into the bytes-only meta. Pure. */
+export function bytesOnlyEntitySupport(schema) {
+    return {
+        support: bytesOnlySupport(schema),
+        schema,
+        isBytes: isBytesEntity(schema),
+    };
+}
+/**
+ * Route a schema-aware write through the backend's byte path when
+ * `meta` is for BYTES_ENTITY; otherwise return per-entry failures.
+ */
+export async function bytesOnlyWrite(meta, storeName, entries, writeBytes) {
+    if (!meta.isBytes) {
+        return entries.map((e) => ({
+            success: false,
+            ...storageFailure(new Error(`${storeName}: schema '${meta.schema.name}' not supported (BYTES_ENTITY only)`), "Unsupported schema", e.uri),
+        }));
+    }
+    const byteEntries = [];
+    const failures = [];
+    for (let i = 0; i < entries.length; i++) {
+        const { uri, record } = entries[i];
+        const payload = record.payload;
+        if (!(payload instanceof Uint8Array) && !(payload instanceof ReadableStream)) {
+            failures.push({
+                index: i,
+                result: {
+                    success: false,
+                    ...storageFailure(new Error(`${storeName}: BYTES_ENTITY record.payload must be Uint8Array or ReadableStream`), "Invalid record", uri),
+                },
+            });
+            continue;
+        }
+        byteEntries.push({ uri, payload: payload });
+    }
+    if (failures.length === entries.length)
+        return failures.map((f) => f.result);
+    const okResults = await writeBytes(byteEntries);
+    // Re-interleave failures with the successful write results in input order.
+    const out = new Array(entries.length);
+    let ok = 0;
+    let fail = 0;
+    for (let i = 0; i < entries.length; i++) {
+        if (failures[fail]?.index === i)
+            out[i] = failures[fail++].result;
+        else
+            out[i] = okResults[ok++];
+    }
+    return out;
+}
+/**
+ * Route a schema-aware read through the backend's byte path when
+ * `meta` is for BYTES_ENTITY; otherwise reject. Read results are
+ * re-wrapped as `{ payload: bytes }` records to match the `EntityStore`
+ * read contract.
+ */
+export async function bytesOnlyRead(meta, storeName, urls, readBytes) {
+    if (!meta.isBytes) {
+        throw new Error(`${storeName}: schema '${meta.schema.name}' not supported (BYTES_ENTITY only)`);
+    }
+    const rows = await readBytes(urls);
+    return rows.map(([uri, value]) => [uri, wrapAsRecord(value)]);
+}
+/**
+ * Route a schema-aware delete through the backend's byte path when
+ * `meta` is for BYTES_ENTITY; otherwise return per-entry failures.
+ */
+export function bytesOnlyDelete(meta, storeName, uris, deleteBytes) {
+    if (!meta.isBytes) {
+        return Promise.resolve(uris.map((uri) => ({
+            success: false,
+            ...storageFailure(new Error(`${storeName}: schema '${meta.schema.name}' not supported (BYTES_ENTITY only)`), "Unsupported schema", uri),
+        })));
+    }
+    return deleteBytes(uris);
+}
+/**
+ * Wrap a byte read result back into a record-shaped payload.
+ *
+ * - Point read miss (`undefined`) → `undefined`.
+ * - Point read bytes → `{ payload: bytes }`.
+ * - `fn=ls&format=full` children (`Output<bytes>[]`) → each child's
+ *    bytes payload wrapped the same way.
+ * - `fn=ls&format=uris` (`string[]`) and `fn=count` (`number`) pass
+ *    through unchanged.
+ */
+function wrapAsRecord(value) {
+    if (value === undefined || value === null)
+        return value;
+    if (value instanceof Uint8Array || value instanceof ReadableStream) {
+        return { payload: value };
+    }
+    if (Array.isArray(value)) {
+        return value.map((row) => {
+            if (Array.isArray(row) && row.length === 2) {
+                const [u, v] = row;
+                return [u, wrapAsRecord(v)];
+            }
+            return row;
+        });
+    }
+    return value;
+}

package/esm/clients/mod.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Store → `ProtocolInterfaceNode` adapter.
+ *
+ * `SaveClient` is the single client this package exposes. It takes a
+ * `SaveMapper` (wire payload → `EntityRecord`), the target
+ * `EntitySchema`, and the backing store — read as "receive payloads
+ * X, map as Y, store on S". All three are explicit; the client does
+ * not invent defaults.
+ *
+ * Built-in mappers `mapToBytes` and `passThroughRecord` cover the
+ * common cases (opaque bytes via `BYTES_ENTITY`, already-shaped
+ * records via a custom schema).
+ */
+export { mapToBytes, passThroughRecord, SaveClient, type SaveMapper, } from "./save-client.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/clients/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/clients/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC"}

package/esm/clients/mod.js

@@ -0,0 +1,14 @@
+/**
+ * Store → `ProtocolInterfaceNode` adapter.
+ *
+ * `SaveClient` is the single client this package exposes. It takes a
+ * `SaveMapper` (wire payload → `EntityRecord`), the target
+ * `EntitySchema`, and the backing store — read as "receive payloads
+ * X, map as Y, store on S". All three are explicit; the client does
+ * not invent defaults.
+ *
+ * Built-in mappers `mapToBytes` and `passThroughRecord` cover the
+ * common cases (opaque bytes via `BYTES_ENTITY`, already-shaped
+ * records via a custom schema).
+ */
+export { mapToBytes, passThroughRecord, SaveClient, } from "./save-client.js";

package/esm/clients/save-client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * SaveClient — unified ProtocolInterfaceNode adapter over an EntityStore.
+ *
+ * Construction shape:
+ *
+ *     new SaveClient(mapper, entity, store)
+ *
+ * Reads on the rig: "receive payloads X, map as Y into entity E,
+ * store on S". All three are explicit; the client does not invent
+ * defaults.
+ *
+ * - **mapper** — a {@link SaveMapper}: freeform projection from the
+ *   wire payload `TIn` to an `EntityRecord` matching `entity`. Runs
+ *   per write entry; throwing produces a per-entry `ReceiveResult`
+ *   failure. {@link mapToBytes} and {@link passThroughRecord} cover
+ *   the common cases.
+ * - **entity** — the {@link EntitySchema} this client routes. Use
+ *   {@link BYTES_ENTITY} for opaque-bytes wires.
+ * - **store** — any {@link EntityStore}. Every backend in this
+ *   package implements it.
+ *
+ * ## Lifecycle
+ *
+ * SaveClient is pure: it computes its `EntityMeta` once at
+ * construction (via `store.entitySupport(target)`, which is a pure
+ * function) and reuses it on every `receive`/`read`/`delete`. There
+ * is no lifecycle method on the client — provisioning the underlying
+ * store is the **caller's** job, handled out of band (app boot for
+ * production, test setup for tests):
+ *
+ *     await store.provisionEntity(store.entitySupport(target));
+ *     const client = new SaveClient(mapper, target, store);
+ *
+ * If the caller skips provisioning, the backend surfaces its natural
+ * failure on first IO (storage error for write/delete, throw or miss
+ * for read) — same as calling any other `EntityStore` method against
+ * an unprovisioned entity.
+ *
+ * Wire shape: a `receive` message is `Output<TIn | null>` —
+ * `[uri, payload]` where `payload === null` is the delete-by-convention.
+ * Reads come back as the stored records (or raw bytes when `entity`
+ * is `BYTES_ENTITY`); the mapper is receive-only.
+ *
+ * A `SaveClient` is a one-shot, isolated thing: each one routes one
+ * entity, and routing a different entity means constructing a
+ * different client.
+ */
+import type { Output, ProtocolInterfaceNode, ReceiveResult, StatusResult } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import { ObserveEmitter } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.js";
+import type { EntityStore } from "../entity-store.js";
+import { type EntityMeta, type EntityRecord, type EntitySchema } from "../entity.js";
+import type { StorePayload } from "../types.js";
+/**
+ * Freeform projection from wire payload → `EntityRecord` for the
+ * target schema. Runs per write entry inside `SaveClient.receive`.
+ * Throwing produces a `ReceiveResult` failure for that entry; the
+ * rest of the batch is unaffected.
+ */
+export type SaveMapper<TIn = unknown> = (uri: string, payload: TIn) => EntityRecord | Promise<EntityRecord>;
+/**
+ * Built-in mapper that wraps a byte payload as a `BYTES_ENTITY`
+ * record (`{ payload: bytes }`). Use with `target: BYTES_ENTITY` when
+ * the wire is already opaque bytes.
+ */
+export declare const mapToBytes: SaveMapper<StorePayload>;
+/**
+ * Built-in mapper that passes the wire payload through as-is,
+ * assuming it already matches the target schema. Use when the
+ * protocol upstream has already produced a valid `EntityRecord`.
+ */
+export declare const passThroughRecord: SaveMapper<EntityRecord>;
+export declare class SaveClient<TIn = unknown> extends ObserveEmitter implements ProtocolInterfaceNode {
+    readonly mapper: SaveMapper<TIn>;
+    readonly target: EntitySchema;
+    readonly store: EntityStore;
+    /**
+     * The store-compiled meta for `target`. Derived once at construction
+     * via `store.entitySupport(target)` (pure). Exposed so callers can
+     * inspect `meta.support` to see which fields the medium accepted.
+     */
+    readonly meta: EntityMeta;
+    constructor(mapper: SaveMapper<TIn>, target: EntitySchema, store: EntityStore);
+    receive(msgs: Output<TIn | null>[]): Promise<ReceiveResult[]>;
+    read<T = EntityRecord | StorePayload | undefined>(urls: string[]): Promise<Output<T>[]>;
+    status(): Promise<StatusResult>;
+}
+//# sourceMappingURL=save-client.d.ts.map

package/esm/clients/save-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-client.d.ts","sourceRoot":"","sources":["../../src/clients/save-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,qBAAqB,EACrB,aAAa,EACb,YAAY,EACb,MAAM,mEAAmE,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,uDAAuD,CAAC;AACvF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,UAAU,CAAC,GAAG,GAAG,OAAO,IAAI,CACtC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,GAAG,KACT,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,UAAU,CAAC,YAAY,CAE9C,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAAU,CAAC,YAAY,CAC9C,CAAC;AAiCV,qBAAa,UAAU,CAAC,GAAG,GAAG,OAAO,CAAE,SAAQ,cAC7C,YAAW,qBAAqB;IAChC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;gBAGxB,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EACvB,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,WAAW;IASd,OAAO,CACX,IAAI,EAAE,MAAM,CAAC,GAAG,GAAG,IAAI,CAAC,EAAE,GACzB,OAAO,CAAC,aAAa,EAAE,CAAC;IA8DrB,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,YAAY,GAAG,SAAS,EACpD,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAUvB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;CAGhC"}

package/esm/clients/save-client.js

@@ -0,0 +1,174 @@
+/**
+ * SaveClient — unified ProtocolInterfaceNode adapter over an EntityStore.
+ *
+ * Construction shape:
+ *
+ *     new SaveClient(mapper, entity, store)
+ *
+ * Reads on the rig: "receive payloads X, map as Y into entity E,
+ * store on S". All three are explicit; the client does not invent
+ * defaults.
+ *
+ * - **mapper** — a {@link SaveMapper}: freeform projection from the
+ *   wire payload `TIn` to an `EntityRecord` matching `entity`. Runs
+ *   per write entry; throwing produces a per-entry `ReceiveResult`
+ *   failure. {@link mapToBytes} and {@link passThroughRecord} cover
+ *   the common cases.
+ * - **entity** — the {@link EntitySchema} this client routes. Use
+ *   {@link BYTES_ENTITY} for opaque-bytes wires.
+ * - **store** — any {@link EntityStore}. Every backend in this
+ *   package implements it.
+ *
+ * ## Lifecycle
+ *
+ * SaveClient is pure: it computes its `EntityMeta` once at
+ * construction (via `store.entitySupport(target)`, which is a pure
+ * function) and reuses it on every `receive`/`read`/`delete`. There
+ * is no lifecycle method on the client — provisioning the underlying
+ * store is the **caller's** job, handled out of band (app boot for
+ * production, test setup for tests):
+ *
+ *     await store.provisionEntity(store.entitySupport(target));
+ *     const client = new SaveClient(mapper, target, store);
+ *
+ * If the caller skips provisioning, the backend surfaces its natural
+ * failure on first IO (storage error for write/delete, throw or miss
+ * for read) — same as calling any other `EntityStore` method against
+ * an unprovisioned entity.
+ *
+ * Wire shape: a `receive` message is `Output<TIn | null>` —
+ * `[uri, payload]` where `payload === null` is the delete-by-convention.
+ * Reads come back as the stored records (or raw bytes when `entity`
+ * is `BYTES_ENTITY`); the mapper is receive-only.
+ *
+ * A `SaveClient` is a one-shot, isolated thing: each one routes one
+ * entity, and routing a different entity means constructing a
+ * different client.
+ */
+import { ObserveEmitter } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.js";
+import { BYTES_ENTITY, } from "../entity.js";
+/**
+ * Built-in mapper that wraps a byte payload as a `BYTES_ENTITY`
+ * record (`{ payload: bytes }`). Use with `target: BYTES_ENTITY` when
+ * the wire is already opaque bytes.
+ */
+export const mapToBytes = (_uri, payload) => ({
+    payload,
+});
+/**
+ * Built-in mapper that passes the wire payload through as-is,
+ * assuming it already matches the target schema. Use when the
+ * protocol upstream has already produced a valid `EntityRecord`.
+ */
+export const passThroughRecord = (_uri, payload) => payload;
+/**
+ * Unwrap `BYTES_ENTITY` read results back to bytes-on-the-wire.
+ *
+ * The store returns:
+ * - `fn=read`: a single `EntityRecord` (or `undefined` for a miss).
+ * - `fn=ls&format=full`: `Output<EntityRecord | undefined>[]`.
+ * - `fn=ls&format=uris`: `string[]`.
+ * - `fn=count`: `number`.
+ *
+ * Record-shaped payloads carry `{ payload: bytes }`; we surface the
+ * inner bytes. Other shapes pass through unchanged.
+ */
+function unwrapBytes(value) {
+    if (value === undefined || value === null)
+        return value;
+    if (value instanceof Uint8Array)
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((row) => {
+            if (Array.isArray(row) && row.length === 2) {
+                const [childUri, childPayload] = row;
+                return [childUri, unwrapBytes(childPayload)];
+            }
+            return row;
+        });
+    }
+    if (typeof value === "object") {
+        const rec = value;
+        if ("payload" in rec)
+            return rec.payload;
+    }
+    return value;
+}
+export class SaveClient extends ObserveEmitter {
+    mapper;
+    target;
+    store;
+    /**
+     * The store-compiled meta for `target`. Derived once at construction
+     * via `store.entitySupport(target)` (pure). Exposed so callers can
+     * inspect `meta.support` to see which fields the medium accepted.
+     */
+    meta;
+    constructor(mapper, target, store) {
+        super();
+        this.mapper = mapper;
+        this.target = target;
+        this.store = store;
+        this.meta = store.entitySupport(target);
+    }
+    async receive(msgs) {
+        const results = new Array(msgs.length);
+        const writes = [];
+        const deletes = [];
+        for (let i = 0; i < msgs.length; i++) {
+            const [uri, payload] = msgs[i];
+            if (!uri || typeof uri !== "string") {
+                results[i] = { accepted: false, error: "URI is required" };
+                continue;
+            }
+            if (payload === null) {
+                deletes.push({ uri, index: i });
+                continue;
+            }
+            try {
+                const record = await this.mapper(uri, payload);
+                writes.push({ uri, record, wire: payload, index: i });
+            }
+            catch (e) {
+                results[i] = {
+                    accepted: false,
+                    error: e instanceof Error ? e.message : String(e),
+                };
+            }
+        }
+        if (writes.length > 0) {
+            const writeResults = await this.store.write(this.meta, writes.map(({ uri, record }) => ({ uri, record })));
+            for (let j = 0; j < writeResults.length; j++) {
+                const w = writes[j];
+                const r = writeResults[j];
+                results[w.index] = { accepted: r.success, error: r.error };
+                if (r.success)
+                    this._emit(w.uri, w.wire);
+            }
+        }
+        if (deletes.length > 0) {
+            const delResults = await this.store.delete(this.meta, deletes.map((d) => d.uri));
+            const deletedUris = [];
+            for (let j = 0; j < delResults.length; j++) {
+                const d = deletes[j];
+                const r = delResults[j];
+                results[d.index] = { accepted: r.success, error: r.error };
+                if (r.success)
+                    deletedUris.push(d.uri);
+            }
+            if (deletedUris.length > 0)
+                this._emitDeletes(deletedUris);
+        }
+        return results;
+    }
+    async read(urls) {
+        const isBytes = this.target.name === BYTES_ENTITY.name;
+        const rows = await this.store.read(this.meta, urls);
+        if (!isBytes)
+            return rows;
+        return rows.map(([uri, payload]) => [uri, unwrapBytes(payload)]);
+    }
+    status() {
+        return this.store.status();
+    }
+}

package/esm/deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @module
+ * B3nd Core — framework foundation.
+ *
+ * Everything the framework needs to run a decentralized/distributed
+ * network: types, encoding, clients, Rig, Identity, connection,
+ * hooks, events, reactions, and network primitives.
+ */
+export type { B3ndError, ClientError, CodeHandler, DeleteResult, HealthStatus, Output, Program, ProgramResult, ProtocolInterfaceNode, ReadFn, ReceiveResult, StatusResult, WriteResult, } from "./src/types/types.js";
+export { ErrorCode, Errors } from "./src/types/types.js";
+export { decodeBase64, decodeHex, encodeBase64, encodeHex, } from "./src/encoding/encoding.js";
+export { FunctionalClient } from "./src/functional-client/functional-client.js";
+export type { FunctionalClientConfig } from "./src/functional-client/functional-client.js";
+export { ObserveEmitter } from "./src/observe-emitter/observe-emitter.js";
+export type { ObserveListener } from "./src/observe-emitter/observe-emitter.js";
+export { ConsoleClient } from "./src/client-console/client.js";
+export { Identity } from "./src/rig/identity.js";
+export type { ExportedIdentity } from "./src/rig/identity.js";
+export { Rig } from "./src/rig/rig.js";
+export type { RigConfig, RigInfo, RigRoutes } from "./src/rig/types.js";
+export type { HandleEmitEvent, HandleErrorEvent, OperationEventHandler, OperationEventMap, OperationEventName, OperationHandle, ProcessDoneEvent, ProcessErrorEvent, ReactionErrorEvent, RouteErrorEvent, RouteSuccessEvent, SettledEvent, } from "./src/rig/operation-handle.js";
+export type { AfterHook, BeforeHook, ErrorHookCtx, ErrorPhase, HooksConfig, OnErrorHook, ReadCtx, ReceiveCtx, RigHooks, SendCtx, } from "./src/rig/hooks.js";
+export { resolveHooks, runAfter, runBefore, runOnError, } from "./src/rig/hooks.js";
+export type { EventHandler, RigEvent, RigEventName } from "./src/rig/events.js";
+export { RigEventEmitter } from "./src/rig/events.js";
+export type { Reaction, ReactionHandler } from "./src/rig/reactions.js";
+export { ReactionRegistry } from "./src/rig/reactions.js";
+export { compilePattern, matches } from "./src/match-pattern/match-pattern.js";
+export type { Matcher } from "./src/match-pattern/match-pattern.js";
+export { connection } from "./src/rig/connection.js";
+export type { Connection, ConnectionOptions } from "./src/rig/connection.js";
+export { network } from "./src/network/network.js";
+export { peer } from "./src/network/peer.js";
+export { flood } from "./src/network/policies/flood.js";
+export { pathVector } from "./src/network/policies/path-vector.js";
+export { tellAndRead } from "./src/network/policies/tell-and-read.js";
+export { bestEffort } from "./src/network/decorators.js";
+export type { InboundCtx, NetworkOptions, Peer, PeerDecorator, Policy, StrategyFactory, } from "./src/network/types.js";
+export type { TellAndReadBundle, TellAndReadOptions, } from "./src/network/policies/tell-and-read.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,MAAM,EACN,aAAa,EACb,YAAY,EACZ,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEzD,OAAO,EACL,YAAY,EACZ,SAAS,EACT,YAAY,EACZ,SAAS,GACV,MAAM,4BAA4B,CAAC;AAIpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AAChF,YAAY,EAAE,sBAAsB,EAAE,MAAM,8CAA8C,CAAC;AAI3F,OAAO,EAAE,cAAc,EAAE,MAAM,0CAA0C,CAAC;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAIhF,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAI/D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AACvC,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAExE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,YAAY,GACb,MAAM,+BAA+B,CAAC;AAEvC,YAAY,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,UAAU,EACV,WAAW,EACX,WAAW,EACX,OAAO,EACP,UAAU,EACV,QAAQ,EACR,OAAO,GACR,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,UAAU,GACX,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,sCAAsC,CAAC;AAC/E,YAAY,EAAE,OAAO,EAAE,MAAM,sCAAsC,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAI7E,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,iCAAiC,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AACzD,YAAY,EACV,UAAU,EACV,cAAc,EACd,IAAI,EACJ,aAAa,EACb,MAAM,EACN,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,yCAAyC,CAAC"}

package/esm/deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/mod.js

@@ -0,0 +1,31 @@
+/**
+ * @module
+ * B3nd Core — framework foundation.
+ *
+ * Everything the framework needs to run a decentralized/distributed
+ * network: types, encoding, clients, Rig, Identity, connection,
+ * hooks, events, reactions, and network primitives.
+ */
+export { ErrorCode, Errors } from "./src/types/types.js";
+export { decodeBase64, decodeHex, encodeBase64, encodeHex, } from "./src/encoding/encoding.js";
+// ── Protocol clients ──
+export { FunctionalClient } from "./src/functional-client/functional-client.js";
+// ── ObserveEmitter ──
+export { ObserveEmitter } from "./src/observe-emitter/observe-emitter.js";
+// ── Built-in transport clients ──
+export { ConsoleClient } from "./src/client-console/client.js";
+// ── Rig ──
+export { Identity } from "./src/rig/identity.js";
+export { Rig } from "./src/rig/rig.js";
+export { resolveHooks, runAfter, runBefore, runOnError, } from "./src/rig/hooks.js";
+export { RigEventEmitter } from "./src/rig/events.js";
+export { ReactionRegistry } from "./src/rig/reactions.js";
+export { compilePattern, matches } from "./src/match-pattern/match-pattern.js";
+export { connection } from "./src/rig/connection.js";
+// ── Network primitives ──
+export { network } from "./src/network/network.js";
+export { peer } from "./src/network/peer.js";
+export { flood } from "./src/network/policies/flood.js";
+export { pathVector } from "./src/network/policies/path-vector.js";
+export { tellAndRead } from "./src/network/policies/tell-and-read.js";
+export { bestEffort } from "./src/network/decorators.js";