@bandeira-tech/b3nd-save 0.8.1

package/esm/memory/store.js

@@ -0,0 +1,300 @@
+/**
+ * MemoryStore — in-memory reference implementation of `EntityStore`.
+ *
+ * One flat `Map<uri, EntityRecord>` per provisioned entity, keyed by
+ * the entity's name. `BYTES_ENTITY` is just another entity here — its
+ * records sit in the same map as any custom entity.
+ *
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure: it walks the schema's fields,
+ * picks the first recognised `TYPE_TAGS` entry per field as the
+ * canonical tag, and returns the operational handle (declared field
+ * set, bytes-field set, signature for collision detection, support
+ * report). `provisionEntity(meta)` allocates the bucket and stores
+ * the meta's signature so future collisions can be detected.
+ * `entityStatus(meta)` returns `"live"` only when the cached
+ * signature matches `meta` exactly — a same-name-different-shape
+ * schema reports `"unprovisioned"`, where "shape" includes the
+ * canonical type tag of each field (so changing `["string"]` to
+ * `["bigint"]` on an existing field name is a collision, mirroring
+ * what SQL backends catch via column-type introspection).
+ *
+ * Writes/reads/deletes consume the meta directly: there is no
+ * per-call cache lookup gate. If `meta`'s bucket does not exist on
+ * this store, `write` and `delete` surface the medium's natural
+ * "not provisioned" storage failure per entry; `read` returns misses.
+ *
+ * ## Validation
+ *
+ * A record under `meta` may only contain keys declared in
+ * `meta.declared`. Extra keys produce a per-entry
+ * `StoreWriteResult` failure. The store does not coerce.
+ *
+ * `payload: ReadableStream` (and any other field whose type tag is
+ * `"bytes"`) is collected to `Uint8Array` via `toBytes` before the
+ * record lands in the bucket. That coercion runs for every entity
+ * that declares a bytes field; nothing about it is bytes-entity-
+ * specific.
+ */
+import { parseUrl } from "../url.js";
+import { storageFailure } from "../errors.js";
+import { toBytes } from "../payload.js";
+import { TYPE_TAGS, } from "../entity.js";
+const STORE_NAME = "MemoryStore";
+const KNOWN_TAGS = new Set(Object.values(TYPE_TAGS));
+export class MemoryStore {
+    buckets = new Map();
+    // ── Lifecycle ────────────────────────────────────────────────────
+    entitySupport(schema) {
+        const supported = [];
+        const unsupported = [];
+        const bytesFields = new Set();
+        // Per-field canonical tag — the first recognised TYPE_TAGS entry in
+        // declaration order, matching how SQL backends pick a column type.
+        // Two schemas that resolve to different canonical tags for the same
+        // field name carry incompatible expectations and must collide.
+        const canonical = new Map();
+        for (const field of schema.fields) {
+            const first = field.type.find((t) => KNOWN_TAGS.has(t));
+            if (first === undefined) {
+                unsupported.push({
+                    name: field.name,
+                    reason: field.type.length === 0
+                        ? "field declares no type tags"
+                        : `no recognised tag in [${field.type.join(", ")}]`,
+                });
+                continue;
+            }
+            supported.push(field.name);
+            canonical.set(field.name, first);
+            if (first === TYPE_TAGS.BYTES)
+                bytesFields.add(field.name);
+        }
+        const support = {
+            entity: schema.name,
+            supported,
+            unsupported,
+        };
+        return {
+            support,
+            declared: new Set(supported),
+            bytesFields,
+            signature: computeSignature(schema.name, canonical),
+        };
+    }
+    // deno-lint-ignore require-await
+    async entityStatus(meta) {
+        const bucket = this.buckets.get(meta.support.entity);
+        if (!bucket)
+            return "unprovisioned";
+        return bucket.signature === meta.signature ? "live" : "unprovisioned";
+    }
+    // deno-lint-ignore require-await
+    async provisionEntity(meta) {
+        const existing = this.buckets.get(meta.support.entity);
+        if (existing) {
+            if (existing.signature !== meta.signature) {
+                throw new Error(`${STORE_NAME}: entity '${meta.support.entity}' is already ` +
+                    `provisioned with a different shape`);
+            }
+            return;
+        }
+        this.buckets.set(meta.support.entity, {
+            signature: meta.signature,
+            records: new Map(),
+        });
+    }
+    // ── Write ────────────────────────────────────────────────────────
+    async write(meta, entries) {
+        const bucket = this.buckets.get(meta.support.entity);
+        const results = [];
+        for (const { uri, record } of entries) {
+            if (!bucket) {
+                results.push({
+                    success: false,
+                    ...storageFailure(new Error(`${STORE_NAME}: entity '${meta.support.entity}' is not provisioned`), "Entity not provisioned", uri),
+                });
+                continue;
+            }
+            const extras = Object.keys(record).filter((k) => !meta.declared.has(k));
+            if (extras.length > 0) {
+                results.push({
+                    success: false,
+                    ...storageFailure(new Error(`record contains keys not declared in schema '${meta.support.entity}': ${extras.join(", ")}`), "Schema mismatch", uri),
+                });
+                continue;
+            }
+            try {
+                const normalised = needsBytesNormalisation(record, meta.bytesFields)
+                    ? await normaliseBytesFields(record, meta.bytesFields)
+                    : { ...record };
+                bucket.records.set(uri, normalised);
+                results.push({ success: true });
+            }
+            catch (err) {
+                results.push({
+                    success: false,
+                    ...storageFailure(err, "Write failed", uri),
+                });
+            }
+        }
+        return results;
+    }
+    // ── Read ─────────────────────────────────────────────────────────
+    // deno-lint-ignore require-await
+    async read(meta, urls) {
+        const bucket = this.buckets.get(meta.support.entity);
+        return urls.map((url) => {
+            const parsed = parseUrl(url);
+            switch (parsed.fn) {
+                case "read":
+                    return [url, bucket?.records.get(parsed.uri)];
+                case "ls":
+                    return [url, this._list(bucket?.records, parsed)];
+                case "count":
+                    return [url, this._count(bucket?.records, parsed)];
+                default:
+                    throw new Error(`${STORE_NAME}: unsupported fn '${parsed.fn}'`);
+            }
+        });
+    }
+    _walk(bucket, uri) {
+        if (!bucket)
+            return [];
+        const prefix = uri.endsWith("/") ? uri : `${uri}/`;
+        const out = [];
+        for (const [k, rec] of bucket) {
+            if (!k.startsWith(prefix))
+                continue;
+            const rest = k.slice(prefix.length);
+            if (rest.length === 0 || rest.includes("/"))
+                continue;
+            out.push([k, rec]);
+        }
+        return out;
+    }
+    _list(bucket, parsed) {
+        const { params } = parsed;
+        if (params.pattern !== undefined) {
+            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+        }
+        if (params.sortBy !== undefined && params.sortBy !== "uri") {
+            throw new Error(`${STORE_NAME}: unsupported sortBy: ${params.sortBy}`);
+        }
+        const format = params.format ?? "full";
+        if (format !== "full" && format !== "uris") {
+            throw new Error(`${STORE_NAME}: unsupported format: ${format}`);
+        }
+        let entries = this._walk(bucket, parsed.uri);
+        if (params.sortBy === "uri") {
+            const dir = params.sortOrder === "desc" ? -1 : 1;
+            entries = [...entries].sort(([a], [b]) => a.localeCompare(b) * dir);
+        }
+        if (params.limit !== undefined) {
+            const page = params.page ?? 1;
+            const start = (page - 1) * params.limit;
+            entries = entries.slice(start, start + params.limit);
+        }
+        if (format === "uris")
+            return entries.map(([uri]) => uri);
+        return entries;
+    }
+    _count(bucket, parsed) {
+        if (parsed.params.pattern !== undefined) {
+            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+        }
+        return this._walk(bucket, parsed.uri).length;
+    }
+    // ── Delete ───────────────────────────────────────────────────────
+    delete(meta, uris) {
+        const bucket = this.buckets.get(meta.support.entity);
+        const results = [];
+        for (const uri of uris) {
+            if (!bucket) {
+                results.push({
+                    success: false,
+                    ...storageFailure(new Error(`${STORE_NAME}: entity '${meta.support.entity}' is not provisioned`), "Entity not provisioned", uri),
+                });
+                continue;
+            }
+            try {
+                bucket.records.delete(uri);
+                results.push({ success: true });
+            }
+            catch (err) {
+                results.push({
+                    success: false,
+                    ...storageFailure(err, "Delete failed", uri),
+                });
+            }
+        }
+        return Promise.resolve(results);
+    }
+    // ── Status / capabilities ────────────────────────────────────────
+    status() {
+        return Promise.resolve({
+            status: "healthy",
+            schema: [...this.buckets.keys()].map((n) => `entity:${n}`),
+            fns: ["read", "ls", "count"],
+        });
+    }
+    capabilities() {
+        return { atomicBatch: false };
+    }
+}
+/**
+ * Canonical signature for collision detection. Two metas produced
+ * from semantically-identical schemas (same name, same set of
+ * supported fields, same canonical type tag per field) yield the same
+ * string; any shape difference — including a field whose tag changed
+ * from `"string"` to `"bigint"` — yields a different one.
+ *
+ * Matches the granularity SQL backends get for free via column-type
+ * introspection: a tag swap on an existing field is a collision even
+ * though the field name is unchanged.
+ */
+function computeSignature(name, canonical) {
+    const fields = [...canonical.entries()]
+        .sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify({ name, fields });
+}
+/**
+ * Quick predicate: does the record have a `ReadableStream` (or a
+ * non-bytes value that needs to be rejected) on any of its bytes
+ * fields? Lets the write hot path skip the async normalisation step
+ * when every value is already a `Uint8Array`.
+ */
+function needsBytesNormalisation(record, bytesFields) {
+    for (const name of bytesFields) {
+        const v = record[name];
+        if (v === undefined || v === null)
+            continue;
+        if (v instanceof Uint8Array)
+            continue;
+        return true;
+    }
+    return false;
+}
+/**
+ * Collect any `ReadableStream` values on `bytes`-tagged fields into
+ * `Uint8Array` and return a shallow-copied record. Non-stream values
+ * pass through; this is the same coercion every backend with a
+ * non-streaming write path performs, generalised across fields.
+ */
+async function normaliseBytesFields(record, bytesFields) {
+    const out = { ...record };
+    for (const name of bytesFields) {
+        const v = out[name];
+        if (v === undefined || v === null)
+            continue;
+        if (v instanceof Uint8Array)
+            continue;
+        if (v instanceof ReadableStream) {
+            out[name] = await toBytes(v);
+            continue;
+        }
+        throw new Error(`field '${name}' must be Uint8Array or ReadableStream, got ${typeof v}`);
+    }
+    return out;
+}

package/esm/mod.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @module
+ * b3nd-save — the data-saving layer for b3nd.
+ *
+ * This root barrel re-exports every public subpath as a namespace.
+ * Use it for convenience or discoverability; for the smallest
+ * footprint, import the subpaths directly (e.g.
+ * `@bandeira-tech/b3nd-save/postgres`).
+ *
+ * Namespaces:
+ *   clients       — EntityStore → ProtocolInterfaceNode adapters
+ *   memory        — In-memory reference backend
+ *   postgres, mongo, sqlite, fs, ipfs, s3, elasticsearch,
+ *   localstorage, indexeddb — EntityStore backend implementations
+ *
+ * The entity surface (`EntityStore`, `EntitySchema`, `BYTES_ENTITY`,
+ * `TYPE_TAGS`, …) is re-exported from the root for convenience.
+ */
+export type { StoreCapabilities, StoreWriteResult } from "./types.js";
+export type { ParsedUrl, ReadParams } from "./url.js";
+export { buildUrl, parseUrl, uriOf } from "./url.js";
+export type { EntityField, EntityMeta, EntityRecord, EntitySchema, EntitySupport, } from "./entity.js";
+export { BYTES_ENTITY, TYPE_TAGS } from "./entity.js";
+export type { EntityStore } from "./entity-store.js";
+export * as clients from "./clients/mod.js";
+export * as memory from "./memory/mod.js";
+export * as postgres from "./postgres/mod.js";
+export * as mongo from "./mongo/mod.js";
+export * as sqlite from "./sqlite/mod.js";
+export * as fs from "./fs/mod.js";
+export * as ipfs from "./ipfs/mod.js";
+export * as s3 from "./s3/mod.js";
+export * as elasticsearch from "./elasticsearch/mod.js";
+export * as localstorage from "./localstorage/mod.js";
+export * as indexeddb from "./indexeddb/mod.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../src/mod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEtE,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAErD,YAAY,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,OAAO,MAAM,kBAAkB,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,QAAQ,MAAM,mBAAmB,CAAC;AAC9C,OAAO,KAAK,KAAK,MAAM,gBAAgB,CAAC;AACxC,OAAO,KAAK,MAAM,MAAM,iBAAiB,CAAC;AAC1C,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,IAAI,MAAM,eAAe,CAAC;AACtC,OAAO,KAAK,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,KAAK,aAAa,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,YAAY,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,SAAS,MAAM,oBAAoB,CAAC"}

package/esm/mod.js

@@ -0,0 +1,31 @@
+/**
+ * @module
+ * b3nd-save — the data-saving layer for b3nd.
+ *
+ * This root barrel re-exports every public subpath as a namespace.
+ * Use it for convenience or discoverability; for the smallest
+ * footprint, import the subpaths directly (e.g.
+ * `@bandeira-tech/b3nd-save/postgres`).
+ *
+ * Namespaces:
+ *   clients       — EntityStore → ProtocolInterfaceNode adapters
+ *   memory        — In-memory reference backend
+ *   postgres, mongo, sqlite, fs, ipfs, s3, elasticsearch,
+ *   localstorage, indexeddb — EntityStore backend implementations
+ *
+ * The entity surface (`EntityStore`, `EntitySchema`, `BYTES_ENTITY`,
+ * `TYPE_TAGS`, …) is re-exported from the root for convenience.
+ */
+export { buildUrl, parseUrl, uriOf } from "./url.js";
+export { BYTES_ENTITY, TYPE_TAGS } from "./entity.js";
+export * as clients from "./clients/mod.js";
+export * as memory from "./memory/mod.js";
+export * as postgres from "./postgres/mod.js";
+export * as mongo from "./mongo/mod.js";
+export * as sqlite from "./sqlite/mod.js";
+export * as fs from "./fs/mod.js";
+export * as ipfs from "./ipfs/mod.js";
+export * as s3 from "./s3/mod.js";
+export * as elasticsearch from "./elasticsearch/mod.js";
+export * as localstorage from "./localstorage/mod.js";
+export * as indexeddb from "./indexeddb/mod.js";

package/esm/mongo/mod.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MongoDB backend for b3nd.
+ *
+ * Store implementation backed by MongoDB. Requires an injected
+ * MongoExecutor so the package does not depend on a specific MongoDB
+ * driver.
+ */
+export interface MongoFindManyOptions {
+    sort?: Record<string, 1 | -1>;
+    skip?: number;
+    limit?: number;
+    /** Mongo projection map (1 = include, 0 = exclude). */
+    projection?: Record<string, 0 | 1>;
+}
+export interface MongoExecutor {
+    insertOne(doc: Record<string, unknown>): Promise<{
+        acknowledged?: boolean;
+    }>;
+    updateOne(filter: Record<string, unknown>, update: Record<string, unknown>, options?: Record<string, unknown>): Promise<{
+        matchedCount?: number;
+        modifiedCount?: number;
+        upsertedId?: unknown;
+    }>;
+    findOne(filter: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    findMany(filter: Record<string, unknown>, options?: MongoFindManyOptions): Promise<Record<string, unknown>[]>;
+    countDocuments(filter: Record<string, unknown>): Promise<number>;
+    deleteOne(filter: Record<string, unknown>): Promise<{
+        deletedCount?: number;
+    }>;
+    ping(): Promise<boolean>;
+    transaction?: <T>(fn: (executor: MongoExecutor) => Promise<T>) => Promise<T>;
+    cleanup?: () => Promise<void>;
+}
+export { MongoStore } from "./store.js";
+//# sourceMappingURL=mod.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/mongo/mod.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC7E,SAAS,CACP,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CACR;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,CACxE,CAAC;IACF,OAAO,CACL,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3C,QAAQ,CACN,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACtC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjE,SAAS,CACP,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,WAAW,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/esm/mongo/mod.js

@@ -0,0 +1,8 @@
+/**
+ * MongoDB backend for b3nd.
+ *
+ * Store implementation backed by MongoDB. Requires an injected
+ * MongoExecutor so the package does not depend on a specific MongoDB
+ * driver.
+ */
+export { MongoStore } from "./store.js";

package/esm/mongo/store.d.ts

@@ -0,0 +1,42 @@
+/**
+ * MongoStore — MongoDB implementation of Store.
+ *
+ * Pure mechanical byte storage with no protocol awareness. Uses an
+ * injected MongoExecutor so the package does not depend on a specific
+ * MongoDB driver. Payload is stored as a BSON `Binary` value (the
+ * `mongodb` driver maps `Uint8Array` to it transparently).
+ *
+ * `fn=ls`/`fn=count` push down to a regex prefix query that enforces
+ * the shallow-direct-leaves contract: `^<prefix>[^/]+$`.
+ */
+import type { DeleteResult, Output, StatusResult } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+import { type BytesOnlyEntityMeta } from "../byte-entity-shim.js";
+import type { EntityStore } from "../entity-store.js";
+import type { EntityRecord, EntitySchema } from "../entity.js";
+import type { StoreCapabilities, StoreWriteResult } from "../types.js";
+import type { MongoExecutor } from "./mod.js";
+export declare class MongoStore implements EntityStore<BytesOnlyEntityMeta> {
+    private readonly collectionName;
+    private readonly executor;
+    constructor(collectionName: string, executor: MongoExecutor);
+    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
+    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
+    write(meta: BytesOnlyEntityMeta, entries: {
+        uri: string;
+        record: EntityRecord;
+    }[]): Promise<StoreWriteResult[]>;
+    read<T = EntityRecord | undefined>(meta: BytesOnlyEntityMeta, urls: string[]): Promise<Output<T>[]>;
+    delete(meta: BytesOnlyEntityMeta, uris: string[]): Promise<DeleteResult[]>;
+    private _writeBytes;
+    private _readBytes;
+    private _readOne;
+    /** Build the shallow-direct-leaves regex filter for a prefix. */
+    private _leafFilter;
+    private _ls;
+    private _count;
+    private _deleteBytes;
+    status(): Promise<StatusResult>;
+    capabilities(): StoreCapabilities;
+}
+//# sourceMappingURL=store.d.ts.map

package/esm/mongo/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/mongo/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAC3E,OAAO,EAEL,KAAK,mBAAmB,EAIzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAO/D,OAAO,KAAK,EACV,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAiC9C,qBAAa,UAAW,YAAW,WAAW,CAAC,mBAAmB,CAAC;IACjE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;gBAE7B,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa;IAU3D,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,mBAAmB;IAIxD,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAI1E,eAAe,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,KAAK,CACH,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAS9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IASvB,MAAM,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;YAW5D,WAAW;IA+BzB,OAAO,CAAC,UAAU;YAQJ,QAAQ;IAMtB,iEAAiE;IACjE,OAAO,CAAC,WAAW;YAIL,GAAG;YA2BH,MAAM;YAON,YAAY;IAoBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAyBrC,YAAY,IAAI,iBAAiB;CAGlC"}

package/esm/mongo/store.js

@@ -0,0 +1,185 @@
+/**
+ * MongoStore — MongoDB implementation of Store.
+ *
+ * Pure mechanical byte storage with no protocol awareness. Uses an
+ * injected MongoExecutor so the package does not depend on a specific
+ * MongoDB driver. Payload is stored as a BSON `Binary` value (the
+ * `mongodb` driver maps `Uint8Array` to it transparently).
+ *
+ * `fn=ls`/`fn=count` push down to a regex prefix query that enforces
+ * the shallow-direct-leaves contract: `^<prefix>[^/]+$`.
+ */
+import { bytesOnlyDelete, bytesOnlyEntitySupport, bytesOnlyRead, bytesOnlyWrite, } from "../byte-entity-shim.js";
+import { dispatchRead } from "../dispatch.js";
+import { storageFailure } from "../errors.js";
+import { toBytes } from "../payload.js";
+import { validateReadParams } from "../read.js";
+const STORE_NAME = "MongoStore";
+/** Escape special regex characters for safe use in a RegExp pattern. */
+function escapeRegex(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Normalize a Mongo document field into a `Uint8Array`. The driver may
+ * surface BSON `Binary` (which exposes `.buffer`) or a raw
+ * `Uint8Array` depending on options.
+ */
+function docToBytes(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (value && typeof value === "object" &&
+        "buffer" in value &&
+        value.buffer instanceof Uint8Array) {
+        return value.buffer;
+    }
+    if (value && typeof value === "object" &&
+        "buffer" in value &&
+        value.buffer instanceof ArrayBuffer) {
+        return new Uint8Array(value.buffer);
+    }
+    throw new Error(`MongoStore: unexpected payload type ${typeof value}`);
+}
+export class MongoStore {
+    collectionName;
+    executor;
+    constructor(collectionName, executor) {
+        if (!collectionName)
+            throw new Error("collectionName is required");
+        if (!executor)
+            throw new Error("executor is required");
+        this.collectionName = collectionName;
+        this.executor = executor;
+    }
+    // ── EntityStore surface ──────────────────────────────────────────
+    entitySupport(schema) {
+        return bytesOnlyEntitySupport(schema);
+    }
+    entityStatus(meta) {
+        return Promise.resolve(meta.isBytes ? "live" : "unprovisioned");
+    }
+    provisionEntity(_meta) {
+        return Promise.resolve();
+    }
+    write(meta, entries) {
+        return bytesOnlyWrite(meta, STORE_NAME, entries, (e) => this._writeBytes(e));
+    }
+    read(meta, urls) {
+        return bytesOnlyRead(meta, STORE_NAME, urls, (u) => this._readBytes(u));
+    }
+    delete(meta, uris) {
+        return bytesOnlyDelete(meta, STORE_NAME, uris, (u) => this._deleteBytes(u));
+    }
+    // ── Byte ops (BYTES_ENTITY routing) ──────────────────────────────
+    async _writeBytes(entries) {
+        const results = [];
+        for (const entry of entries) {
+            try {
+                const bytes = await toBytes(entry.payload);
+                await this.executor.updateOne({ uri: entry.uri }, {
+                    $set: {
+                        uri: entry.uri,
+                        payload: bytes,
+                        updatedAt: new Date(),
+                    },
+                }, { upsert: true });
+                results.push({ success: true });
+            }
+            catch (err) {
+                results.push({
+                    success: false,
+                    ...storageFailure(err, "Write failed", entry.uri),
+                });
+            }
+        }
+        return results;
+    }
+    _readBytes(urls) {
+        return dispatchRead(urls, STORE_NAME, {
+            read: (p) => this._readOne(p.uri),
+            ls: (p) => this._ls(p),
+            count: (p) => this._count(p),
+        });
+    }
+    async _readOne(uri) {
+        const doc = await this.executor.findOne({ uri });
+        if (!doc)
+            return undefined;
+        return docToBytes(doc.payload);
+    }
+    /** Build the shallow-direct-leaves regex filter for a prefix. */
+    _leafFilter(prefixUri) {
+        return { uri: { $regex: `^${escapeRegex(prefixUri)}[^/]+$` } };
+    }
+    async _ls(parsed) {
+        validateReadParams(parsed.params, STORE_NAME);
+        const { params } = parsed;
+        const format = params.format ?? "full";
+        const options = {};
+        if (params.sortBy === "uri") {
+            options.sort = { uri: params.sortOrder === "desc" ? -1 : 1 };
+        }
+        if (params.limit !== undefined) {
+            const page = params.page ?? 1;
+            options.limit = params.limit;
+            options.skip = (page - 1) * params.limit;
+        }
+        if (format === "uris") {
+            options.projection = { uri: 1, _id: 0 };
+        }
+        const docs = await this.executor.findMany(this._leafFilter(parsed.uri), options);
+        if (format === "uris")
+            return docs.map((d) => d.uri);
+        return docs.map((d) => [d.uri, docToBytes(d.payload)]);
+    }
+    async _count(parsed) {
+        if (parsed.params.pattern !== undefined) {
+            throw new Error(`${STORE_NAME}: pattern filter not supported`);
+        }
+        return await this.executor.countDocuments(this._leafFilter(parsed.uri));
+    }
+    async _deleteBytes(uris) {
+        const results = [];
+        for (const uri of uris) {
+            try {
+                await this.executor.deleteOne({ uri });
+                results.push({ success: true });
+            }
+            catch (err) {
+                results.push({
+                    success: false,
+                    ...storageFailure(err, "Delete failed", uri),
+                });
+            }
+        }
+        return results;
+    }
+    // ── Status ───────────────────────────────────────────────────────
+    async status() {
+        try {
+            const ok = await this.executor.ping();
+            if (!ok) {
+                return {
+                    status: "unhealthy",
+                    message: "MongoDB ping failed",
+                    fns: ["read", "ls", "count"],
+                };
+            }
+            return {
+                status: "healthy",
+                message: "MongoDB store is operational",
+                fns: ["read", "ls", "count"],
+                details: { collectionName: this.collectionName },
+            };
+        }
+        catch (error) {
+            return {
+                status: "unhealthy",
+                message: error instanceof Error ? error.message : String(error),
+                fns: ["read", "ls", "count"],
+            };
+        }
+    }
+    capabilities() {
+        return { atomicBatch: false };
+    }
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}