@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/json-fields.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared TYPE_TAGS planning + JSON record encoding used by backends
+ * that store custom-entity records as JSON-encoded bytes.
+ *
+ * The fs / s3 / ipfs / localstorage / elasticsearch backends all
+ * serialise records the same way:
+ *
+ * - bytes      → base64 string
+ * - bigint     → decimal string
+ * - timestamp  → ISO-8601 string
+ * - everything else passes through unchanged (`number`, `boolean`,
+ *   `string`, `json` objects).
+ *
+ * Centralising the encoder/decoder here keeps the round-trip
+ * guarantee — write on one JSON-encoding backend, read on another,
+ * get the same `EntityRecord` shape back. Mongo (BSON-native) and
+ * IndexedDB (structured-clone-native) preserve the typed values
+ * without JSON encoding, so they don't use this module.
+ *
+ * `computeSignature` is the canonical collision-detection signature
+ * over `{name, [field, tag] ...}` — two metas with identical names
+ * + identical per-field canonical tags hash to the same string;
+ * any shape difference (including a tag swap on an existing field
+ * name) yields a different one. Matches the granularity SQL backends
+ * get for free via column-type introspection.
+ */
+import { type EntityField, type EntityRecord } from "./entity.js";
+export interface FieldPlan {
+    name: string;
+    tag: string;
+}
+export interface FieldPlanResult {
+    fields: FieldPlan[];
+    unsupported: {
+        name: string;
+        reason: string;
+    }[];
+}
+/**
+ * Walk a schema's fields, picking the first recognised TYPE_TAGS
+ * entry per field as the canonical tag. Fields with no recognised
+ * tag (or an invalid field name) are reported under `unsupported`.
+ */
+export declare function planFields(fields: EntityField[]): FieldPlanResult;
+/**
+ * Encode a record into a JSON-serialisable shape using the per-field
+ * canonical tag. Bytes → base64; bigint → string; timestamp →
+ * ISO-8601; everything else passes through unchanged.
+ */
+export declare function encodeRecord(fields: readonly FieldPlan[], record: EntityRecord): Record<string, unknown>;
+/** Inverse of `encodeRecord` — restores `Uint8Array`/`BigInt`/`Date`. */
+export declare function decodeRecord(fields: readonly FieldPlan[], source: Record<string, unknown>): EntityRecord;
+/**
+ * Canonical signature over `{name, [field, tag] ...}` used by the
+ * provisioning bookkeeping to detect same-name different-shape
+ * collisions. Identical to Memory's signature scheme — a field whose
+ * canonical tag flips counts as a collision even though the field
+ * name is unchanged.
+ */
+export declare function computeSignature(name: string, fields: readonly FieldPlan[]): string;
+//# sourceMappingURL=json-fields.d.ts.map

package/esm/json-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-fields.d.ts","sourceRoot":"","sources":["../src/json-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAa,MAAM,aAAa,CAAC;AAK7E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,eAAe,CAyBjE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,MAAM,EAAE,YAAY,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkBzB;AAED,yEAAyE;AACzE,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,SAAS,EAAE,EAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,YAAY,CAcd;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,SAAS,EAAE,GAC3B,MAAM,CAKR"}

package/esm/json-fields.js

@@ -0,0 +1,121 @@
+/**
+ * Shared TYPE_TAGS planning + JSON record encoding used by backends
+ * that store custom-entity records as JSON-encoded bytes.
+ *
+ * The fs / s3 / ipfs / localstorage / elasticsearch backends all
+ * serialise records the same way:
+ *
+ * - bytes      → base64 string
+ * - bigint     → decimal string
+ * - timestamp  → ISO-8601 string
+ * - everything else passes through unchanged (`number`, `boolean`,
+ *   `string`, `json` objects).
+ *
+ * Centralising the encoder/decoder here keeps the round-trip
+ * guarantee — write on one JSON-encoding backend, read on another,
+ * get the same `EntityRecord` shape back. Mongo (BSON-native) and
+ * IndexedDB (structured-clone-native) preserve the typed values
+ * without JSON encoding, so they don't use this module.
+ *
+ * `computeSignature` is the canonical collision-detection signature
+ * over `{name, [field, tag] ...}` — two metas with identical names
+ * + identical per-field canonical tags hash to the same string;
+ * any shape difference (including a tag swap on an existing field
+ * name) yields a different one. Matches the granularity SQL backends
+ * get for free via column-type introspection.
+ */
+import { decodeBase64, encodeBase64 } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/mod.js";
+import { TYPE_TAGS } from "./entity.js";
+import { IDENTIFIER_PATTERN, isValidIdentifier } from "./identifiers.js";
+const KNOWN = new Set(Object.values(TYPE_TAGS));
+/**
+ * Walk a schema's fields, picking the first recognised TYPE_TAGS
+ * entry per field as the canonical tag. Fields with no recognised
+ * tag (or an invalid field name) are reported under `unsupported`.
+ */
+export function planFields(fields) {
+    const out = [];
+    const unsupported = [];
+    for (const f of fields) {
+        if (!isValidIdentifier(f.name)) {
+            unsupported.push({
+                name: f.name,
+                reason: `field name must match ${IDENTIFIER_PATTERN.source}; got '${f.name}'`,
+            });
+            continue;
+        }
+        const tag = f.type.find((t) => KNOWN.has(t));
+        if (!tag) {
+            unsupported.push({
+                name: f.name,
+                reason: f.type.length === 0
+                    ? "field declares no type tags"
+                    : `no recognised tag in [${f.type.join(", ")}]`,
+            });
+            continue;
+        }
+        out.push({ name: f.name, tag });
+    }
+    return { fields: out, unsupported };
+}
+/**
+ * Encode a record into a JSON-serialisable shape using the per-field
+ * canonical tag. Bytes → base64; bigint → string; timestamp →
+ * ISO-8601; everything else passes through unchanged.
+ */
+export function encodeRecord(fields, record) {
+    const out = {};
+    for (const f of fields) {
+        const v = record[f.name];
+        if (v === undefined || v === null) {
+            out[f.name] = null;
+            continue;
+        }
+        if (f.tag === "bytes")
+            out[f.name] = encodeBase64(v);
+        else if (f.tag === "bigint") {
+            out[f.name] = typeof v === "bigint" ? v.toString() : String(v);
+        }
+        else if (f.tag === "timestamp") {
+            out[f.name] = v instanceof Date
+                ? v.toISOString()
+                : new Date(v).toISOString();
+        }
+        else
+            out[f.name] = v;
+    }
+    return out;
+}
+/** Inverse of `encodeRecord` — restores `Uint8Array`/`BigInt`/`Date`. */
+export function decodeRecord(fields, source) {
+    const out = {};
+    for (const f of fields) {
+        const v = source[f.name];
+        if (v === null || v === undefined) {
+            out[f.name] = undefined;
+            continue;
+        }
+        if (f.tag === "bytes")
+            out[f.name] = decodeBase64(v);
+        else if (f.tag === "bigint")
+            out[f.name] = BigInt(v);
+        else if (f.tag === "timestamp")
+            out[f.name] = new Date(v);
+        else
+            out[f.name] = v;
+    }
+    return out;
+}
+/**
+ * Canonical signature over `{name, [field, tag] ...}` used by the
+ * provisioning bookkeeping to detect same-name different-shape
+ * collisions. Identical to Memory's signature scheme — a field whose
+ * canonical tag flips counts as a collision even though the field
+ * name is unchanged.
+ */
+export function computeSignature(name, fields) {
+    const sorted = [...fields]
+        .map((f) => [f.name, f.tag])
+        .sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify({ name, fields: sorted });
+}

package/esm/localstorage/store.d.ts

@@ -1,45 +1,113 @@
 /**
- * LocalStorageStore — browser localStorage implementation of Store.
+ * LocalStorageStore — browser localStorage implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. Uses
- * `localStorage` as a flat key→string KV. Payload bytes are
- * base64-encoded since `localStorage` values are strings.
+ * One backend, many entities. Layouts:
+ *
+ * - `BYTES_ENTITY` → key `{keyPrefix}{uri}` with a base64-encoded
+ *   payload string. Matches the original bytes-only layout, so
+ *   existing deployments keep working without migration.
+ * - any other schema → key `{keyPrefix}entities/{entityName}/{uri}`
+ *   with a JSON-encoded record string. Per-field canonical tags
+ *   round-trip the JSON boundary (bytes → base64, bigint → string,
+ *   timestamp → ISO-8601 — see `./fields.ts`).
+ *
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it plans the field set and computes
+ * a signature for collision detection. `provisionEntity(meta)` writes a
+ * tiny bookkeeping key (`{keyPrefix}__meta__/entities/{name}`) holding
+ * the signature; subsequent `entityStatus(meta)` reads it back and
+ * compares. Same-name different-shape provisioning throws.
+ *
+ * Writes/reads/deletes consume the meta directly: there is no per-call
+ * cache lookup gate. If `meta`'s bookkeeping is missing on the medium,
+ * `write` and `delete` surface a `"not provisioned"` storage failure
+ * per entry; `read` returns misses.
+ *
+ * ## Read params
+ *
+ * `fn=ls` / `fn=count` are shallow direct-leaves only. localStorage has
+ * no indexable cursor, so `_directLeaves` walks all keys once under the
+ * entity's `keyRoot` and standard params (`limit`/`page`/`sortBy`
+ * `=uri`/`sortOrder`/`format`) are applied in memory via
+ * `applyReadParams` from `../read.ts`.
+ *
+ * `fn=find` (v2 §3.5) walks every key under the entity's `keyRoot`
+ * matching the URI prefix at any depth — `_walkDeep` mirrors
+ * `_directLeaves` minus the `rest.includes("/")` cutoff. With
+ * `pushDownFind: false`, dispatch applies the embedded glob, sort,
+ * cursor, limit, format, and appends the cursor-as-trailing-slot.
+ * localStorage has no engine to leverage for push-down — iteration IS
+ * the work — so the symmetric shape (ls = shallow walk, find = deep
+ * walk; dispatch post-processes both) keeps the code minimal.
+ *
+ * `status().fns` advertises `["read", "ls", "count", "find"]`.
  */
-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 { DeleteResult, Output, StatusResult } from "../deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/src/types/types.js";
 import type { EntityStore } from "../entity-store.js";
-import type { EntityRecord, EntitySchema } from "../entity.js";
+import { type EntityMeta, type EntityRecord, type EntitySchema } from "../entity.js";
 import type { StoreCapabilities, StoreWriteResult } from "../types.js";
-export declare class LocalStorageStore implements EntityStore<BytesOnlyEntityMeta> {
+import { type FieldPlan } from "../json-fields.js";
+/**
+ * LocalStorageStore-specific entity handle.
+ *
+ * `keyRoot` is the full localStorage prefix under which records live
+ * (e.g. `b3nd:entities/users/`). `isBytes` selects the legacy
+ * base64-bytes value format vs the JSON record format. `fields`,
+ * `declared`, and `bytesFields` drive write-time validation and
+ * encoding; `signature` is used for collision detection in
+ * `entityStatus` / `provisionEntity`.
+ */
+export interface LocalStorageEntityMeta extends EntityMeta {
+    readonly keyRoot: string;
+    readonly isBytes: boolean;
+    readonly fields: readonly FieldPlan[];
+    readonly declared: ReadonlySet<string>;
+    readonly bytesFields: ReadonlySet<string>;
+    readonly signature: string;
+}
+export declare class LocalStorageStore implements EntityStore<LocalStorageEntityMeta> {
     private readonly keyPrefix;
     private readonly storage;
     constructor(config?: {
         keyPrefix?: string;
         storage?: Storage;
     });
-    private getKey;
-    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
-    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
-    provisionEntity(_meta: BytesOnlyEntityMeta): Promise<void>;
-    write(meta: BytesOnlyEntityMeta, entries: {
+    entitySupport(schema: EntitySchema): LocalStorageEntityMeta;
+    entityStatus(meta: LocalStorageEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(meta: LocalStorageEntityMeta): Promise<void>;
+    write(meta: LocalStorageEntityMeta, 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;
+    read<T = EntityRecord | undefined>(meta: LocalStorageEntityMeta, urls: string[]): Promise<Output<T>[]>;
     private _readOne;
     /**
-     * Walk localStorage once, returning `[uri, bytes]` for every entry
-     * whose URI is `prefix + <segment>` with no further `/`. Subtree-only
-     * paths are excluded by the slash check.
+     * Walk localStorage once, returning `Output<EntityRecord>` for every
+     * key under `meta.keyRoot` whose remainder is `uri + <segment>` with
+     * no further `/`. Subtree-only paths are excluded by the slash check.
      */
     private _directLeaves;
+    /**
+     * Walk localStorage once, returning `Output<EntityRecord>` for every
+     * key under `meta.keyRoot` whose remainder starts with `uri` — at
+     * any depth. Powers `fn=find`. Unlike `_directLeaves`, there is no
+     * `/` cutoff: keys with further slashes past the prefix are kept.
+     * Dispatch applies the glob (and sort/cursor/limit/format) on top.
+     */
+    private _walkDeep;
     private _ls;
     private _count;
-    private _deleteBytes;
+    delete(meta: LocalStorageEntityMeta, uris: string[]): Promise<DeleteResult[]>;
     status(): Promise<StatusResult>;
     capabilities(): StoreCapabilities;
+    private _readMetaSignature;
+    /**
+     * Collect any `ReadableStream` values on `bytes`-tagged fields into
+     * `Uint8Array` and return a shallow-copied record. Non-stream values
+     * pass through; matches the normalisation pattern used by Memory and
+     * Postgres.
+     */
+    private _normaliseBytesFields;
 }
 //# sourceMappingURL=store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/localstorage/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;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;AAQ/D,OAAO,KAAK,EACV,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAIrB,qBAAa,iBAAkB,YAAW,WAAW,CAAC,mBAAmB,CAAC;IACxE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEtB,MAAM,GAAE;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;KACd;IAUN,OAAO,CAAC,MAAM;IAMd,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;IAqBzB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,QAAQ;IAMhB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,GAAG;IAQX,OAAO,CAAC,MAAM;IAOd,OAAO,CAAC,YAAY;IAoBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAmB/B,YAAY,IAAI,iBAAiB;CAGlC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/localstorage/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAO3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAIL,KAAK,SAAS,EAEf,MAAM,mBAAmB,CAAC;AAO3B;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAuB,SAAQ,UAAU;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAMD,qBAAa,iBAAkB,YAAW,WAAW,CAAC,sBAAsB,CAAC;IAC3E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAEtB,MAAM,GAAE;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;KACd;IAYN,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,sBAAsB;IA0C3D,YAAY,CACV,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAS9B,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB5D,KAAK,CACT,IAAI,EAAE,sBAAsB,EAC5B,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAqE9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,sBAAsB,EAC5B,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IA6BvB,OAAO,CAAC,QAAQ;IAUhB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAkBrB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,GAAG;IAWX,OAAO,CAAC,MAAM;IASd,MAAM,CACJ,IAAI,EAAE,sBAAsB,EAC5B,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,YAAY,EAAE,CAAC;IA+B1B,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IA0B/B,YAAY,IAAI,iBAAiB;IAMjC,OAAO,CAAC,kBAAkB;IAM1B;;;;;OAKG;YACW,qBAAqB;CAmBpC"}