@saacms/storage-libsql 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @saacms/storage-libsql — public surface.
+ *
+ * libSQL (Turso / embedded SQLite) implementation of the saacms
+ * `RowStorageAdapter` interface. Mirrors `@saacms/storage-d1`'s structure
+ * exactly; only the driver call-shape differs (libSQL `execute({sql,args})`
+ * vs D1 `prepare().bind().all()/run()`).
+ *
+ * The host app supplies a real `createClient({url, authToken})` instance from
+ * `@libsql/client`; it satisfies `LibsqlClientLike` structurally — no runtime
+ * dep on `@libsql/client` is required here.
+ */
+export { libsqlAdapter, snakeToCamel, RowStorageError } from "./libsql-adapter.ts";
+export type { LibsqlAdapterOpts, LibsqlClientLike, FilterOpValue, RowStorageAdapter, ListOpts, ListResult, } from "./libsql-adapter.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAClF,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,QAAQ,EACR,UAAU,GACX,MAAM,qBAAqB,CAAA"}

package/dist/index.js

@@ -0,0 +1,175 @@
+// src/libsql-adapter.ts
+import { camelToSnakeCase, UniqueConstraintError, RowStorageError } from "@saacms/core";
+function snakeToCamel(name) {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+function keysToSnake(row) {
+  const out = {};
+  for (const [k, v] of Object.entries(row))
+    out[camelToSnakeCase(k)] = v;
+  return out;
+}
+function rowToCamel(row) {
+  const out = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (v !== null)
+      out[snakeToCamel(k)] = v;
+  }
+  return out;
+}
+var IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+function assertSafeIdent(name) {
+  if (typeof name !== "string" || !IDENT_RE.test(name)) {
+    throw new RowStorageError("MISCONFIGURED", `unsafe identifier: ${JSON.stringify(name)}`);
+  }
+}
+function quoteIdent(name) {
+  return `"${name}"`;
+}
+var FILTER_OP_SQL = {
+  eq: "=",
+  ne: "<>",
+  gt: ">",
+  gte: ">=",
+  lt: "<",
+  lte: "<="
+};
+function isFilterOpValue(v) {
+  if (typeof v !== "object" || v === null)
+    return false;
+  const candidate = v;
+  const op = candidate["op"];
+  return typeof op === "string" && op in FILTER_OP_SQL && "value" in candidate;
+}
+function isUniqueViolation(cause) {
+  if (cause == null)
+    return false;
+  const msg = (cause instanceof Error ? cause.message : String(cause)).toLowerCase();
+  return msg.includes("unique constraint failed");
+}
+var DEFAULT_LIMIT = 50;
+var MAX_LIMIT = 1000;
+function libsqlAdapter(opts) {
+  const { client } = opts;
+  return {
+    async getById(table, id) {
+      assertSafeIdent(table);
+      const sql = `SELECT * FROM ${quoteIdent(table)} WHERE id = ? LIMIT 1`;
+      try {
+        const result = await client.execute({ sql, args: [id] });
+        const row = result.rows[0] ?? null;
+        return row ? rowToCamel(row) : null;
+      } catch (cause) {
+        throw new RowStorageError("QUERY_FAILED", `libsqlAdapter.getById failed for table "${table}"`, cause);
+      }
+    },
+    async list(table, listOpts) {
+      assertSafeIdent(table);
+      const whereClauses = [];
+      const args = [];
+      if (listOpts?.where) {
+        for (const [col, val] of Object.entries(listOpts.where)) {
+          const snakeCol = camelToSnakeCase(col);
+          assertSafeIdent(snakeCol);
+          if (isFilterOpValue(val)) {
+            whereClauses.push(`${quoteIdent(snakeCol)} ${FILTER_OP_SQL[val.op]} ?`);
+            args.push(val.value);
+          } else {
+            whereClauses.push(`${quoteIdent(snakeCol)} = ?`);
+            args.push(val);
+          }
+        }
+      }
+      if (listOpts?.cursor !== undefined) {
+        whereClauses.push(`id > ?`);
+        args.push(listOpts.cursor);
+      }
+      let orderBy = `ORDER BY id ASC`;
+      if (listOpts?.orderBy && listOpts.orderBy.length > 0) {
+        const parts = [];
+        for (const { col, dir } of listOpts.orderBy) {
+          const snakeCol = camelToSnakeCase(col);
+          assertSafeIdent(snakeCol);
+          parts.push(`${quoteIdent(snakeCol)} ${dir === "desc" ? "DESC" : "ASC"}`);
+        }
+        orderBy = `ORDER BY ${parts.join(", ")}`;
+      }
+      const rawLimit = listOpts?.limit ?? DEFAULT_LIMIT;
+      const limit = Math.max(1, Math.min(MAX_LIMIT, rawLimit | 0));
+      const whereSql = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
+      const sql = `SELECT * FROM ${quoteIdent(table)} ${whereSql} ${orderBy} LIMIT ?`.replace(/\s+/g, " ").trim();
+      args.push(limit);
+      try {
+        const result = await client.execute({ sql, args });
+        const rows = result.rows.map((r) => rowToCamel(r));
+        const nextCursorVal = rows.length === limit ? rows[rows.length - 1]?.id ?? null : null;
+        return {
+          rows,
+          nextCursor: nextCursorVal === null ? null : String(nextCursorVal)
+        };
+      } catch (cause) {
+        throw new RowStorageError("QUERY_FAILED", `libsqlAdapter.list failed for table "${table}"`, cause);
+      }
+    },
+    async insert(table, row) {
+      assertSafeIdent(table);
+      const snakeRow = keysToSnake(row);
+      const entries = Object.entries(snakeRow);
+      const hasId = "id" in snakeRow;
+      const id = hasId ? String(snakeRow.id) : crypto.randomUUID();
+      const finalEntries = hasId ? entries : [["id", id], ...entries];
+      const cols = [];
+      const args = [];
+      for (const [k, v] of finalEntries) {
+        assertSafeIdent(k);
+        cols.push(quoteIdent(k));
+        args.push(v);
+      }
+      const placeholders = cols.map(() => "?").join(", ");
+      const sql = `INSERT INTO ${quoteIdent(table)} (${cols.join(", ")}) VALUES (${placeholders})`;
+      try {
+        await client.execute({ sql, args });
+        return { id };
+      } catch (cause) {
+        if (isUniqueViolation(cause))
+          throw new UniqueConstraintError(table, cause);
+        throw new RowStorageError("INSERT_FAILED", `libsqlAdapter.insert failed for table "${table}"`, cause);
+      }
+    },
+    async update(table, id, patch) {
+      assertSafeIdent(table);
+      const snakePatch = keysToSnake(patch);
+      snakePatch["updated_at"] = new Date().toISOString();
+      const sets = [];
+      const args = [];
+      for (const [k, v] of Object.entries(snakePatch)) {
+        assertSafeIdent(k);
+        sets.push(`${quoteIdent(k)} = ?`);
+        args.push(v);
+      }
+      args.push(id);
+      const sql = `UPDATE ${quoteIdent(table)} SET ${sets.join(", ")} WHERE id = ?`;
+      try {
+        await client.execute({ sql, args });
+      } catch (cause) {
+        if (isUniqueViolation(cause))
+          throw new UniqueConstraintError(table, cause);
+        throw new RowStorageError("UPDATE_FAILED", `libsqlAdapter.update failed for table "${table}"`, cause);
+      }
+    },
+    async delete(table, id) {
+      assertSafeIdent(table);
+      const sql = `DELETE FROM ${quoteIdent(table)} WHERE id = ?`;
+      try {
+        await client.execute({ sql, args: [id] });
+      } catch (cause) {
+        throw new RowStorageError("DELETE_FAILED", `libsqlAdapter.delete failed for table "${table}"`, cause);
+      }
+    }
+  };
+}
+export {
+  snakeToCamel,
+  libsqlAdapter,
+  RowStorageError
+};

package/dist/libsql-adapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * libSQL row-storage adapter — implements the saacms `RowStorageAdapter`
+ * interface over a libSQL client (Turso / embedded SQLite).
+ *
+ * `LibsqlClientLike` is a structural interface — the minimal subset of
+ * `@libsql/client`'s `Client` this adapter uses. No runtime dependency on
+ * `@libsql/client` is required; the host app supplies a real
+ * `createClient({url,authToken})` instance and it slots in structurally.
+ *
+ * Real @libsql/client shape (v0.14+/v1.x) — confirmed from published TypeScript
+ * declarations at github.com/tursodatabase/libsql-client-ts:
+ *
+ *   interface Client {
+ *     execute(stmt: string | { sql: string; args?: InValue[] | Record<string, InValue> }): Promise<ResultSet>
+ *   }
+ *   interface ResultSet { columns: string[]; rows: Row[]; rowsAffected: number; ... }
+ *   interface Row { [key: string]: Value; [key: number]: Value }
+ *   type Value = null | string | number | bigint | ArrayBuffer | Uint8Array
+ *
+ * Structural compatibility: `Row` has `[key: string]: Value` and Value ⊆
+ * unknown, so `Row[]` is assignable to `Array<Record<string, unknown>>` ✓.
+ * TypeScript's bivariant method checking (method shorthand, not property-arrow)
+ * means a real Client (execute param: string | InStatementObject) is assignable
+ * to LibsqlClientLike (execute param: { sql, args? }) without a compile dep ✓.
+ *
+ * Anti-corruption boundary (ADR 0020): callers speak camelCase domain keys;
+ * the physical SQLite/Turso schema is snake_case (ADR 0005). This adapter is
+ * the only place the two conventions meet — camelCase→snake_case on every
+ * write/query path, snake_case→camelCase on every read path.
+ * `camelToSnakeCase` is imported from @saacms/core (single source of truth —
+ * never re-implement the regex). Server-injected timestamp columns
+ * (`created_at`/`updated_at`) surface to callers as `createdAt`/`updatedAt`,
+ * restoring the weak-ETag field the runtime reads (ADR 0021 §6 / RFC 9110).
+ */
+import { RowStorageError } from "@saacms/core";
+import type { RowStorageAdapter, ListOpts, ListResult } from "@saacms/core";
+export { RowStorageError };
+export type { RowStorageAdapter, ListOpts, ListResult };
+/** Inverse of `camelToSnakeCase`: `updated_at` → `updatedAt`, `id` → `id`. */
+export declare function snakeToCamel(name: string): string;
+/**
+ * Minimal structural subset of `@libsql/client`'s `Client` that this adapter
+ * uses. No runtime dependency on `@libsql/client` — the host provides a real
+ * instance and it slots in structurally (see module-level comment).
+ */
+export interface LibsqlClientLike {
+    execute(stmt: {
+        sql: string;
+        args?: unknown[];
+    }): Promise<{
+        rows: Array<Record<string, unknown>>;
+        rowsAffected: number;
+    }>;
+}
+export interface LibsqlAdapterOpts {
+    readonly client: LibsqlClientLike;
+}
+type FilterOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte";
+/** Discriminated operator filter produced by list-route and consumed here. */
+export interface FilterOpValue {
+    readonly op: FilterOp;
+    readonly value: unknown;
+}
+export declare function libsqlAdapter(opts: LibsqlAdapterOpts): RowStorageAdapter;
+//# sourceMappingURL=libsql-adapter.d.ts.map

package/dist/libsql-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"libsql-adapter.d.ts","sourceRoot":"","sources":["../src/libsql-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAA2C,eAAe,EAAE,MAAM,cAAc,CAAA;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAI3E,OAAO,EAAE,eAAe,EAAE,CAAA;AAC1B,YAAY,EAAE,iBAAiB,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAA;AAavD,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AA6BD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,IAAI,EAAE;QACZ,GAAG,EAAE,MAAM,CAAA;QACX,IAAI,CAAC,EAAE,OAAO,EAAE,CAAA;KACjB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC5E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAA;CAClC;AAsCD,KAAK,QAAQ,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAA;AAEzD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CACxB;AAwCD,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,CAuKxE"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@saacms/storage-libsql",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "typecheck": "tsc --build --noEmit",
+    "prepack": "cp package.json package.json.pack-bak && bun run ../../scripts/prepack-pkg.ts",
+    "postpack": "mv package.json.pack-bak package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@saacms/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@saacms/storage-d1": "workspace:*",
+    "@types/bun": "latest",
+    "effect": "^3.10.0",
+    "typescript": "^5.7.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}