@bandeira-tech/b3nd-save 0.8.1

package/esm/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Local Store types for b3nd-save.
+ *
+ * The `Store` abstraction is internal to this package. `SaveClient`
+ * wraps a `Store` (or `EntityStore`) and exposes a
+ * `ProtocolInterfaceNode` to the rest of b3nd — outside the client,
+ * nothing else in the framework sees a `Store`.
+ *
+ * Stores are opaque byte storage: payloads are bytes in, bytes out.
+ * The payload type is the `Uint8Array | ReadableStream<Uint8Array>`
+ * union so callers and backends can avoid materializing large
+ * payloads when both sides know how to stream — same shape `fetch`
+ * already uses for request/response bodies. Backends that have no
+ * native streaming path collect the stream to bytes on write and
+ * return `Uint8Array` on read. Backends with native streaming
+ * (filesystem, S3, IPFS) keep streams end-to-end.
+ *
+ * Cross-cutting types (`Output`, `ProtocolInterfaceNode`,
+ * `DeleteResult`, `StatusResult`) still come from b3nd-core.
+ */
+import type { B3ndError, DeleteResult, Output, StatusResult } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.22.0/src/types/types.js";
+/**
+ * Payload type accepted by `write` and produced by `read`.
+ *
+ * A backend may accept either shape on write and is free to return
+ * either shape on read — pick whichever avoids buffering when
+ * possible. Callers that always want bytes can collect with
+ * `new Response(payload).bytes()` or the equivalent helper.
+ */
+export type StorePayload = Uint8Array | ReadableStream<Uint8Array>;
+/**
+ * Entry for a batch write operation.
+ *
+ * @example
+ * ```typescript
+ * await store.write([
+ *   { uri: "mutable://users/alice", payload: new TextEncoder().encode("alice") },
+ * ]);
+ * ```
+ */
+export interface StoreEntry {
+    uri: string;
+    payload: StorePayload;
+}
+/**
+ * Per-entry result of a write operation.
+ *
+ * `errorDetail` mirrors `DeleteResult.errorDetail` — callers that want
+ * to react to specific failure modes (e.g. `STORAGE_ERROR` from the
+ * underlying driver vs. a programmer error from the store layer)
+ * should switch on `errorDetail.code` rather than parsing `error`.
+ * The `error` string remains for human-readable logs.
+ */
+export interface StoreWriteResult {
+    success: boolean;
+    error?: string;
+    errorDetail?: B3ndError;
+}
+/**
+ * Optional capability reporting for a Store.
+ *
+ * Backends declare what they can do so clients can make informed
+ * decisions (e.g., wrap deletes + writes in a transaction when
+ * `atomicBatch` is true).
+ */
+export interface StoreCapabilities {
+    /** Whether write + delete within a single call can be made atomic. */
+    atomicBatch?: boolean;
+}
+/**
+ * Store — the batch-native byte-storage abstraction.
+ *
+ * Every operation takes arrays and returns per-item results. Each
+ * backend optimizes for its technology (Postgres → multi-row INSERT,
+ * S3 → parallel PutObject, etc.).
+ *
+ * The Store knows nothing about protocols, envelopes, message
+ * semantics, or content shape. Read returns `Output<StorePayload>`
+ * for `fn=read` and `fn=ls&format=full`; `fn=ls&format=uris` returns
+ * `string[]`, `fn=count` returns `number`.
+ *
+ * @example
+ * ```typescript
+ * import { MemoryStore } from "@bandeira-tech/b3nd-save/memory";
+ * const store = new MemoryStore();
+ *
+ * await store.write([
+ *   { uri: "mutable://app/config", payload: new TextEncoder().encode("dark") },
+ * ]);
+ * const [[uri, payload]] = await store.read(["mutable://app/config"]);
+ * const bytes = await new Response(payload as StorePayload).bytes();
+ * ```
+ */
+export interface Store {
+    write(entries: StoreEntry[]): Promise<StoreWriteResult[]>;
+    read<T = StorePayload>(urls: string[]): Promise<Output<T>[]>;
+    delete(uris: string[]): Promise<DeleteResult[]>;
+    status(): Promise<StatusResult>;
+    capabilities?(): StoreCapabilities;
+}
+//# sourceMappingURL=types.d.ts.map

package/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,kEAAkE,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;AAEnE;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,YAAY,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,SAAS,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,KAAK;IACpB,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAC1D,IAAI,CAAC,CAAC,GAAG,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC7D,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAChD,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IAChC,YAAY,CAAC,IAAI,iBAAiB,CAAC;CACpC"}

package/esm/types.js

@@ -0,0 +1,21 @@
+/**
+ * Local Store types for b3nd-save.
+ *
+ * The `Store` abstraction is internal to this package. `SaveClient`
+ * wraps a `Store` (or `EntityStore`) and exposes a
+ * `ProtocolInterfaceNode` to the rest of b3nd — outside the client,
+ * nothing else in the framework sees a `Store`.
+ *
+ * Stores are opaque byte storage: payloads are bytes in, bytes out.
+ * The payload type is the `Uint8Array | ReadableStream<Uint8Array>`
+ * union so callers and backends can avoid materializing large
+ * payloads when both sides know how to stream — same shape `fetch`
+ * already uses for request/response bodies. Backends that have no
+ * native streaming path collect the stream to bytes on write and
+ * return `Uint8Array` on read. Backends with native streaming
+ * (filesystem, S3, IPFS) keep streams end-to-end.
+ *
+ * Cross-cutting types (`Output`, `ProtocolInterfaceNode`,
+ * `DeleteResult`, `StatusResult`) still come from b3nd-core.
+ */
+export {};

package/esm/url.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @module
+ * Save-layer locator grammar — parsing and constructing the urls that
+ * stores in this package implement.
+ *
+ * This is **save's contract with its callers**, not a framework-wide
+ * standard. b3nd-core treats locators opaquely; it is each client's
+ * choice what grammar it accepts. Stores shipped by `@bandeira-tech/b3nd-save`
+ * (memory, postgres, mongo, sqlite, fs, ipfs, s3, elasticsearch,
+ * localstorage, indexeddb) honor the grammar defined here.
+ *
+ * A **url** = a uri (the canonical resource identifier) plus a query
+ * string of read parameters. The uri is the routing identity used for
+ * storage keys and observe-match keys. The query string carries
+ * request-time-only directives that shape the response without
+ * changing identity.
+ *
+ * Grammar:
+ *
+ *     <uri>[?fn=<fn>][&<param>=<value>...][&x-<ns>.<key>=<value>...]
+ *
+ * Reserved `fn` values:
+ * - `read`   — point read (default for non-trailing-slash uris)
+ * - `ls`     — list under a prefix (default when uri ends with `/`)
+ * - `count`  — count of entries under a prefix
+ * - `x-*.*`  — provider-defined extension functions
+ *
+ * Standard params (meaningful only for some fns; stores ignore the rest):
+ * `limit`, `page`, `cursor`, `sortBy`, `sortOrder`, `pattern`, `format`.
+ *
+ * Anything matching `x-<ns>.<key>` lands in the `ext` map and is passed
+ * opaquely to the executing store. Callers inspect ext entries by
+ * their flat string key (e.g. `ext["x-feed.cursor"]`).
+ */
+/**
+ * Standard read parameters. All are optional; stores interpret the
+ * subset that makes sense for the requested fn and throw on the rest.
+ */
+export interface ReadParams {
+    limit?: number;
+    page?: number;
+    cursor?: string;
+    sortBy?: string;
+    sortOrder?: string;
+    pattern?: string;
+    format?: string;
+}
+/**
+ * A parsed url decomposed into routing identity (`uri`), function
+ * (`fn`), standard read parameters (`params`), and the `x-*` extension
+ * bag (`ext`), plus the structural fields shared with WHATWG URL
+ * (`protocol`, `hostname`, `path`, `program`).
+ */
+export interface ParsedUrl {
+    /** Scheme without trailing `://` (e.g. `"mutable"`, `"b3nd"`). */
+    protocol: string;
+    /** Authority segment after `protocol://` (may be empty). */
+    hostname: string;
+    /** Everything after `protocol://<hostname>`. Empty or starts with `/`. */
+    path: string;
+    /** `protocol://hostname` — the routing root above the path. */
+    program: string;
+    /** Full routing identity: `program` + `path`. Query is stripped. */
+    uri: string;
+    /** Reserved fn (`read`/`ls`/`count`) or `x-<ns>.<name>` extension. */
+    fn: string;
+    /** Standard read params (numeric ones coerced). */
+    params: ReadParams;
+    /** Bag of `x-*` extension query params (every key starts with `x-`). */
+    ext: Record<string, string>;
+}
+/**
+ * Parse a url into its structural fields, function, params, and extensions.
+ *
+ * Splitting rule: first `://` separates protocol from the rest; the first
+ * `/` in the rest separates hostname from path. Embedded `://` in the path
+ * (e.g. `b3nd://count/mutable://users/`) stays inside `path` — no
+ * special-casing.
+ *
+ * Defaults:
+ * - `fn=read` for uris without a trailing slash
+ * - `fn=ls` for uris with a trailing slash
+ *
+ * Numeric params (`limit`, `page`) are coerced; throws on NaN.
+ */
+export declare function parseUrl(url: string): ParsedUrl;
+/**
+ * Serialize a parsed url back to its string form. Authoritative input is
+ * `uri`; structural fields (`protocol`/`hostname`/`path`/`program`) are
+ * ignored on serialization since `uri` already contains them.
+ *
+ * Omits `fn=` when it matches the trailing-slash default. Throws if any
+ * `ext` key does not start with `x-`.
+ */
+export declare function buildUrl(parsed: {
+    uri: string;
+    fn?: string;
+    params?: ReadParams;
+    ext?: Record<string, string>;
+}): string;
+/**
+ * Canonical-uri portion of a save url. The query string is
+ * request-time-only and never participates in routing or storage
+ * keying. Cheap helper for stores and callers that need the bare uri
+ * without paying for full parse.
+ */
+export declare function uriOf(url: string): string;
+//# sourceMappingURL=url.d.ts.map

package/esm/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,MAAM,EAAE,UAAU,CAAC;IACnB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CA8D/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,GAAG,MAAM,CAwBT;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGzC"}

package/esm/url.js

@@ -0,0 +1,151 @@
+/**
+ * @module
+ * Save-layer locator grammar — parsing and constructing the urls that
+ * stores in this package implement.
+ *
+ * This is **save's contract with its callers**, not a framework-wide
+ * standard. b3nd-core treats locators opaquely; it is each client's
+ * choice what grammar it accepts. Stores shipped by `@bandeira-tech/b3nd-save`
+ * (memory, postgres, mongo, sqlite, fs, ipfs, s3, elasticsearch,
+ * localstorage, indexeddb) honor the grammar defined here.
+ *
+ * A **url** = a uri (the canonical resource identifier) plus a query
+ * string of read parameters. The uri is the routing identity used for
+ * storage keys and observe-match keys. The query string carries
+ * request-time-only directives that shape the response without
+ * changing identity.
+ *
+ * Grammar:
+ *
+ *     <uri>[?fn=<fn>][&<param>=<value>...][&x-<ns>.<key>=<value>...]
+ *
+ * Reserved `fn` values:
+ * - `read`   — point read (default for non-trailing-slash uris)
+ * - `ls`     — list under a prefix (default when uri ends with `/`)
+ * - `count`  — count of entries under a prefix
+ * - `x-*.*`  — provider-defined extension functions
+ *
+ * Standard params (meaningful only for some fns; stores ignore the rest):
+ * `limit`, `page`, `cursor`, `sortBy`, `sortOrder`, `pattern`, `format`.
+ *
+ * Anything matching `x-<ns>.<key>` lands in the `ext` map and is passed
+ * opaquely to the executing store. Callers inspect ext entries by
+ * their flat string key (e.g. `ext["x-feed.cursor"]`).
+ */
+/**
+ * Parse a url into its structural fields, function, params, and extensions.
+ *
+ * Splitting rule: first `://` separates protocol from the rest; the first
+ * `/` in the rest separates hostname from path. Embedded `://` in the path
+ * (e.g. `b3nd://count/mutable://users/`) stays inside `path` — no
+ * special-casing.
+ *
+ * Defaults:
+ * - `fn=read` for uris without a trailing slash
+ * - `fn=ls` for uris with a trailing slash
+ *
+ * Numeric params (`limit`, `page`) are coerced; throws on NaN.
+ */
+export function parseUrl(url) {
+    const qIdx = url.indexOf("?");
+    const uri = qIdx < 0 ? url : url.slice(0, qIdx);
+    const query = qIdx < 0 ? "" : url.slice(qIdx + 1);
+    const schemeIdx = uri.indexOf("://");
+    let protocol = "";
+    let hostname = "";
+    let path = "";
+    if (schemeIdx >= 0) {
+        protocol = uri.slice(0, schemeIdx);
+        const rest = uri.slice(schemeIdx + 3);
+        const slash = rest.indexOf("/");
+        if (slash < 0) {
+            hostname = rest;
+            path = "";
+        }
+        else {
+            hostname = rest.slice(0, slash);
+            path = rest.slice(slash);
+        }
+    }
+    else {
+        path = uri;
+    }
+    const program = protocol ? `${protocol}://${hostname}` : "";
+    const sp = new URLSearchParams(query);
+    const explicitFn = sp.get("fn") ?? undefined;
+    const defaultFn = uri.endsWith("/") ? "ls" : "read";
+    const fn = explicitFn ?? defaultFn;
+    const params = {};
+    const ext = {};
+    for (const [key, value] of sp.entries()) {
+        if (key === "fn")
+            continue;
+        if (key.startsWith("x-")) {
+            ext[key] = value;
+            continue;
+        }
+        switch (key) {
+            case "limit":
+            case "page": {
+                const n = Number(value);
+                if (!Number.isFinite(n)) {
+                    throw new Error(`Invalid ${key}: ${value}`);
+                }
+                params[key] = n;
+                break;
+            }
+            case "cursor":
+            case "sortBy":
+            case "sortOrder":
+            case "pattern":
+            case "format":
+                params[key] = value;
+                break;
+            default:
+                throw new Error(`Unknown read param: ${key}`);
+        }
+    }
+    return { protocol, hostname, path, program, uri, fn, params, ext };
+}
+/**
+ * Serialize a parsed url back to its string form. Authoritative input is
+ * `uri`; structural fields (`protocol`/`hostname`/`path`/`program`) are
+ * ignored on serialization since `uri` already contains them.
+ *
+ * Omits `fn=` when it matches the trailing-slash default. Throws if any
+ * `ext` key does not start with `x-`.
+ */
+export function buildUrl(parsed) {
+    const { uri, fn, params, ext } = parsed;
+    const sp = new URLSearchParams();
+    const defaultFn = uri.endsWith("/") ? "ls" : "read";
+    if (fn && fn !== defaultFn)
+        sp.set("fn", fn);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v === undefined)
+                continue;
+            sp.set(k, String(v));
+        }
+    }
+    if (ext) {
+        for (const [k, v] of Object.entries(ext)) {
+            if (!k.startsWith("x-")) {
+                throw new Error(`ext keys must start with 'x-': ${k}`);
+            }
+            sp.set(k, v);
+        }
+    }
+    const qs = sp.toString();
+    return qs ? `${uri}?${qs}` : uri;
+}
+/**
+ * Canonical-uri portion of a save url. The query string is
+ * request-time-only and never participates in routing or storage
+ * keying. Cheap helper for stores and callers that need the bare uri
+ * without paying for full parse.
+ */
+export function uriOf(url) {
+    const qIdx = url.indexOf("?");
+    return qIdx < 0 ? url : url.slice(0, qIdx);
+}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@bandeira-tech/b3nd-save",
+  "version": "0.8.1",
+  "description": "B3nd data-saving layer: Store backends (postgres, mongo, sqlite, fs, ipfs, s3, elasticsearch, localstorage, indexeddb, memory) and Store→ProtocolInterfaceNode clients.",
+  "homepage": "https://github.com/bandeira-tech/b3nd-save#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bandeira-tech/b3nd-save.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/bandeira-tech/b3nd-save/issues"
+  },
+  "module": "./esm/mod.js",
+  "exports": {
+    ".": {
+      "types": "./esm/mod.d.ts",
+      "import": "./esm/mod.js"
+    },
+    "./clients": {
+      "types": "./esm/clients/mod.d.ts",
+      "import": "./esm/clients/mod.js"
+    },
+    "./errors": {
+      "types": "./esm/errors.d.ts",
+      "import": "./esm/errors.js"
+    },
+    "./payload": {
+      "types": "./esm/payload.d.ts",
+      "import": "./esm/payload.js"
+    },
+    "./read": {
+      "types": "./esm/read.d.ts",
+      "import": "./esm/read.js"
+    },
+    "./dispatch": {
+      "types": "./esm/dispatch.d.ts",
+      "import": "./esm/dispatch.js"
+    },
+    "./memory": {
+      "types": "./esm/memory/mod.d.ts",
+      "import": "./esm/memory/mod.js"
+    },
+    "./postgres": {
+      "types": "./esm/postgres/mod.d.ts",
+      "import": "./esm/postgres/mod.js"
+    },
+    "./mongo": {
+      "types": "./esm/mongo/mod.d.ts",
+      "import": "./esm/mongo/mod.js"
+    },
+    "./sqlite": {
+      "types": "./esm/sqlite/mod.d.ts",
+      "import": "./esm/sqlite/mod.js"
+    },
+    "./fs": {
+      "types": "./esm/fs/mod.d.ts",
+      "import": "./esm/fs/mod.js"
+    },
+    "./ipfs": {
+      "types": "./esm/ipfs/mod.d.ts",
+      "import": "./esm/ipfs/mod.js"
+    },
+    "./s3": {
+      "types": "./esm/s3/mod.d.ts",
+      "import": "./esm/s3/mod.js"
+    },
+    "./elasticsearch": {
+      "types": "./esm/elasticsearch/mod.d.ts",
+      "import": "./esm/elasticsearch/mod.js"
+    },
+    "./localstorage": {
+      "types": "./esm/localstorage/mod.d.ts",
+      "import": "./esm/localstorage/mod.js"
+    },
+    "./indexeddb": {
+      "types": "./esm/indexeddb/mod.d.ts",
+      "import": "./esm/indexeddb/mod.js"
+    }
+  },
+  "scripts": {},
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "canonicalize": "2.0.0"
+  },
+  "_generatedBy": "dnt@dev"
+}