@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/sqlite/columns.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TYPE_TAGS → SQLite column type mapping for native entity tables.
+ *
+ * SQLite uses type affinity rather than strict types — a single field
+ * picks the first recognized canonical tag in declaration order and
+ * resolves to an affinity that matches Postgres's storage semantics
+ * as closely as the medium allows.
+ */
+import { type EntityField } from "../entity.js";
+export interface ColumnPlan {
+    /** Field/column name. */
+    name: string;
+    /** SQLite SQL type (affinity). */
+    sqlType: string;
+    /** The recognized canonical tag — drives adapt-for-write/read. */
+    tag: string;
+}
+export interface ColumnPlanResult {
+    columns: ColumnPlan[];
+    unsupported: {
+        name: string;
+        reason: string;
+    }[];
+}
+/**
+ * Resolve a schema's fields into SQLite column plans.
+ *
+ * Skips fields whose tags are all outside `TYPE_TAGS`; reports them
+ * via `unsupported`. Rejects invalid field names up front so we never
+ * emit unsafe SQL identifiers.
+ */
+export declare function planColumns(fields: EntityField[]): ColumnPlanResult;
+//# sourceMappingURL=columns.d.ts.map

package/esm/sqlite/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["../../src/sqlite/columns.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAa,MAAM,cAAc,CAAC;AAc3D,MAAM,WAAW,UAAU;IACzB,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,gBAAgB,CA0BnE"}

package/esm/sqlite/columns.js

@@ -0,0 +1,51 @@
+/**
+ * TYPE_TAGS → SQLite column type mapping for native entity tables.
+ *
+ * SQLite uses type affinity rather than strict types — a single field
+ * picks the first recognized canonical tag in declaration order and
+ * resolves to an affinity that matches Postgres's storage semantics
+ * as closely as the medium allows.
+ */
+import { TYPE_TAGS } from "../entity.js";
+const SQL_TYPE = {
+    [TYPE_TAGS.STRING]: "TEXT",
+    [TYPE_TAGS.NUMBER]: "REAL",
+    [TYPE_TAGS.BIGINT]: "INTEGER",
+    [TYPE_TAGS.BOOLEAN]: "INTEGER",
+    [TYPE_TAGS.BYTES]: "BLOB",
+    [TYPE_TAGS.TIMESTAMP]: "TEXT",
+    [TYPE_TAGS.JSON]: "TEXT",
+};
+const FIELD_NAME = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+/**
+ * Resolve a schema's fields into SQLite column plans.
+ *
+ * Skips fields whose tags are all outside `TYPE_TAGS`; reports them
+ * via `unsupported`. Rejects invalid field names up front so we never
+ * emit unsafe SQL identifiers.
+ */
+export function planColumns(fields) {
+    const columns = [];
+    const unsupported = [];
+    for (const field of fields) {
+        if (!FIELD_NAME.test(field.name)) {
+            unsupported.push({
+                name: field.name,
+                reason: `field name must match ${FIELD_NAME.source}; got '${field.name}'`,
+            });
+            continue;
+        }
+        const tag = field.type.find((t) => SQL_TYPE[t] !== undefined);
+        if (!tag) {
+            unsupported.push({
+                name: field.name,
+                reason: field.type.length === 0
+                    ? "field declares no type tags"
+                    : `no recognised tag in [${field.type.join(", ")}]`,
+            });
+            continue;
+        }
+        columns.push({ name: field.name, sqlType: SQL_TYPE[tag], tag });
+    }
+    return { columns, unsupported };
+}

package/esm/sqlite/store.d.ts

@@ -1,42 +1,90 @@
 /**
- * SqliteStore — SQLite implementation of Store.
+ * SqliteStore — SQLite implementation of `EntityStore`.
  *
- * Pure mechanical byte storage with no protocol awareness. Pushes
- * fn=ls/fn=count down to SQL using the shallow-direct-leaves
- * predicate: `uri LIKE ? || '%' AND uri NOT LIKE ? || '%/%'`.
+ * One layout for every schema: `{prefix}_{entity}_data` with `uri TEXT
+ * PRIMARY KEY` and one column per supported field, typed by the
+ * canonical `TYPE_TAGS` it carries (see `./columns.ts`). `BYTES_ENTITY`
+ * is just an entity with one `payload BLOB` column — no legacy
+ * special case.
  *
- * Uses an injected synchronous SqliteExecutor; results are wrapped in
- * Promise.resolve() to satisfy the async Store interface. `payload`
- * is a BLOB; the store does not inspect or transform its contents.
+ * ## Lifecycle
+ *
+ * `entitySupport(schema)` is pure — it runs `planColumns` and returns
+ * a `SqliteEntityMeta` with the target table name, column plans,
+ * bytes-column set, and the support report. No IO.
+ *
+ * `provisionEntity(meta)` runs `CREATE TABLE IF NOT EXISTS` and then
+ * verifies the live shape matches the meta (catches same-name-
+ * different-shape collisions). `entityStatus(meta)` performs the same
+ * check in isolation via `PRAGMA table_info`.
+ *
+ * Writes/reads/deletes consume the meta directly: no per-call cache
+ * gate. Operations against a not-yet-provisioned meta surface
+ * SQLite's natural failure per entry.
+ *
+ * `fn=ls` / `fn=count` push down to SQL — the shallow-direct-leaves
+ * predicate (`uri LIKE prefix || '%' AND uri NOT LIKE prefix || '%/%'`)
+ * is enforced in the WHERE clause against the entity's table.
+ *
+ * `fn=find` (v2 spec §3.5; foundation PR #82) reuses the same `_ls`
+ * SQL composition with a single branch: under `fn=find` the shallow
+ * safety predicate (`AND uri NOT LIKE prefix || '%/%'`) is DROPPED so
+ * the LIKE prefix walk crosses `/` and matches the whole subtree.
+ * The prefix bind is still a two-arg `[prefix, globToSqlLike(pattern)]`
+ * pair — never concatenated into the pattern body, so room/segment
+ * names containing literal `%`/`_` cannot break out of the parameter
+ * (LIKE-injection safety via `ESCAPE '\'`). `pushDownFind: true` is
+ * advertised so dispatch trusts the backend's deep walk.
+ *
+ * Writes are wrapped in a transaction (`capabilities.atomicBatch =
+ * true`). Stream-shaped values on `BLOB` columns are collected to
+ * `Uint8Array` *before* the transaction opens.
  */
-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";
+import { type ColumnPlan } from "./columns.js";
 import type { SqliteExecutor } from "./mod.js";
-export declare class SqliteStore implements EntityStore<BytesOnlyEntityMeta> {
-    private readonly tableName;
+/**
+ * SqliteStore-specific entity handle.
+ *
+ * `tableName` is the prefixed-and-suffixed target table; `columns`
+ * are the planned user columns (without the always-present `uri`,
+ * `created_at`, `updated_at`); `declared` is the set of user column
+ * names for the per-write extras check; `bytesColumns` drives stream
+ * normalisation; `jsonColumns`/`tsColumns`/`booleanColumns` drive
+ * the per-tag adapt-for-write/read coercions.
+ */
+export interface SqliteEntityMeta extends EntityMeta {
+    readonly tableName: string;
+    readonly columns: readonly ColumnPlan[];
+    readonly declared: ReadonlySet<string>;
+    readonly bytesColumns: ReadonlySet<string>;
+}
+export declare class SqliteStore implements EntityStore<SqliteEntityMeta> {
+    private readonly tablePrefix;
     private readonly executor;
-    private readonly provisioned;
     constructor(tablePrefix: string, executor: SqliteExecutor);
-    entitySupport(schema: EntitySchema): BytesOnlyEntityMeta;
-    entityStatus(meta: BytesOnlyEntityMeta): Promise<"live" | "unprovisioned">;
-    provisionEntity(meta: BytesOnlyEntityMeta): Promise<void>;
-    write(meta: BytesOnlyEntityMeta, entries: {
+    entitySupport(schema: EntitySchema): SqliteEntityMeta;
+    entityStatus(meta: SqliteEntityMeta): Promise<"live" | "unprovisioned">;
+    provisionEntity(meta: SqliteEntityMeta): Promise<void>;
+    write(meta: SqliteEntityMeta, 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: SqliteEntityMeta, urls: string[]): Promise<Output<T>[]>;
+    delete(meta: SqliteEntityMeta, uris: string[]): Promise<DeleteResult[]>;
+    status(): Promise<StatusResult>;
+    capabilities(): StoreCapabilities;
     private _readOne;
     private _ls;
     private _count;
-    private _deleteBytes;
-    status(): Promise<StatusResult>;
-    private schemaUris;
-    capabilities(): StoreCapabilities;
+    /**
+     * Enumerate every `{tablePrefix}_*_data` table currently in the
+     * database. Used by `status()` to advertise the entities a peer can
+     * talk to without per-entity bookkeeping.
+     */
+    private _listProvisionedEntities;
 }
 //# sourceMappingURL=store.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sqlite/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,cAAc,EAAE,MAAM,UAAU,CAAC;AAW/C,qBAAa,WAAY,YAAW,WAAW,CAAC,mBAAmB,CAAC;IAClE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAK1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc;IAUzD,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,mBAAmB;IAIxD,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IAI1E,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IASzD,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;IAqCzB,OAAO,CAAC,UAAU;IAQlB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,GAAG;IA2BX,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,YAAY;IAwBpB,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAoB/B,OAAO,CAAC,UAAU;IAIlB,YAAY,IAAI,iBAAiB;CAGlC"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sqlite/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,YAAY,EACb,MAAM,mEAAmE,CAAC;AAO3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EACL,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EAGlB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,KAAK,UAAU,EAAe,MAAM,cAAc,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAI/C;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC5C;AAoCD,qBAAa,WAAY,YAAW,WAAW,CAAC,gBAAgB,CAAC;IAC/D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;gBAE9B,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc;IAezD,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB;IAmB/C,YAAY,CAChB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC;IA0B9B,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BtD,KAAK,CACT,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,EAAE,GAC/C,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAuE9B,IAAI,CAAC,CAAC,GAAG,YAAY,GAAG,SAAS,EAC/B,IAAI,EAAE,gBAAgB,EACtB,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;IAevB,MAAM,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAsBvE,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IAoB/B,YAAY,IAAI,iBAAiB;IAMjC,OAAO,CAAC,QAAQ;IA4BhB,OAAO,CAAC,GAAG;IA0EX,OAAO,CAAC,MAAM;IA0Bd;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;CAejC"}