@saacms/storage-d1 0.1.0

package/dist/d1-adapter.d.ts

@@ -0,0 +1,86 @@
+/**
+ * D1 row-storage adapter — implements the saacms `RowStorageAdapter`
+ * interface over a Cloudflare Workers `D1Database` binding.
+ *
+ * Per ADR 0024 D1 is the only row-store adapter shipped at v1.0; postgres /
+ * sqlite-local follow in v1.x.
+ *
+ * Workers API reference:
+ *   https://developers.cloudflare.com/d1/build-with-d1/d1-client-api/
+ *
+ * Interface defined locally for now; will move to `@saacms/core` when the
+ * Storage bounded context surface lands (ADR 0020).
+ *
+ * Anti-corruption boundary (ADR 0020): callers always speak **camelCase**
+ * domain keys; the physical D1/SQLite schema is conventional **snake_case**
+ * (ADR 0005 — the DB is a mechanical projection of the Schema). This adapter
+ * is the only place the two conventions meet — it maps camelCase→snake_case
+ * on every write/query path and snake_case→camelCase on every read path,
+ * reusing `@saacms/core`'s canonical `camelToSnakeCase` so the convention has
+ * a single source of truth (no re-implemented 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).
+ */
+/** Inverse of `camelToSnakeCase`: `updated_at` → `updatedAt`, `id` → `id`. */
+export declare function snakeToCamel(name: string): string;
+export interface RowStorageAdapter {
+    getById<T>(table: string, id: string): Promise<T | null>;
+    list<T>(table: string, opts?: ListOpts): Promise<ListResult<T>>;
+    insert<T>(table: string, row: T): Promise<{
+        id: string;
+    }>;
+    update<T>(table: string, id: string, patch: Partial<T>): Promise<void>;
+    delete(table: string, id: string): Promise<void>;
+}
+export interface ListOpts {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly where?: Readonly<Record<string, unknown>>;
+    readonly orderBy?: ReadonlyArray<{
+        readonly col: string;
+        readonly dir: "asc" | "desc";
+    }>;
+}
+export interface ListResult<T> {
+    readonly rows: ReadonlyArray<T>;
+    readonly nextCursor: string | null;
+}
+export declare class RowStorageError extends Error {
+    readonly code: "NOT_FOUND" | "INSERT_FAILED" | "UPDATE_FAILED" | "DELETE_FAILED" | "QUERY_FAILED" | "NOT_IMPLEMENTED" | "MISCONFIGURED";
+    readonly cause?: unknown | undefined;
+    readonly name = "RowStorageError";
+    constructor(code: "NOT_FOUND" | "INSERT_FAILED" | "UPDATE_FAILED" | "DELETE_FAILED" | "QUERY_FAILED" | "NOT_IMPLEMENTED" | "MISCONFIGURED", message: string, cause?: unknown | undefined);
+}
+/** Subset of `D1Database` used by this adapter. Mirrors @cloudflare/workers-types shape. */
+export interface D1DatabaseLike {
+    prepare(query: string): D1PreparedStatementLike;
+    batch<T = unknown>(statements: D1PreparedStatementLike[]): Promise<D1ResultLike<T>[]>;
+}
+export interface D1PreparedStatementLike {
+    bind(...values: unknown[]): D1PreparedStatementLike;
+    first<T = unknown>(): Promise<T | null>;
+    all<T = unknown>(): Promise<D1ResultLike<T>>;
+    run(): Promise<D1ResultLike<unknown>>;
+}
+export interface D1ResultLike<T = unknown> {
+    readonly results?: T[];
+    readonly success: boolean;
+    readonly meta?: {
+        readonly last_row_id?: number;
+        readonly changes?: number;
+    };
+}
+export interface D1AdapterOpts {
+    /** The Workers `D1Database` binding; supplied by the host. */
+    readonly db: D1DatabaseLike;
+}
+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 d1Adapter(opts: D1AdapterOpts): RowStorageAdapter;
+export {};
+//# sourceMappingURL=d1-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"d1-adapter.d.ts","sourceRoot":"","sources":["../src/d1-adapter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @saacms/storage-d1 — public surface.
+ *
+ * Cloudflare D1 (SQLite at the edge) implementation of the saacms
+ * `RowStorageAdapter` interface. Per ADR 0024 D1 is the only row-store
+ * adapter shipped at v1.0; postgres / sqlite-local follow in v1.x.
+ *
+ * v1 alpha status: scaffold. Real implementation lands via the
+ * `agentFleet dispatch A` task.
+ */
+export { d1Adapter } from "./d1-adapter.ts";
+export type { D1AdapterOpts, RowStorageAdapter, RowStorageError, ListOpts, ListResult, } from "./d1-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;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,UAAU,GACX,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,183 @@
+// src/d1-adapter.ts
+import { camelToSnakeCase, UniqueConstraintError } 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;
+}
+
+class RowStorageError extends Error {
+  code;
+  cause;
+  name = "RowStorageError";
+  constructor(code, message, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+  }
+}
+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 IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+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 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 DEFAULT_LIMIT = 50;
+var MAX_LIMIT = 1000;
+function d1Adapter(opts) {
+  const { db } = opts;
+  return {
+    async getById(table, id) {
+      assertSafeIdent(table);
+      const sql = `SELECT * FROM ${quoteIdent(table)} WHERE id = ? LIMIT 1`;
+      try {
+        const row = await db.prepare(sql).bind(id).first();
+        return row ? rowToCamel(row) : null;
+      } catch (cause) {
+        throw new RowStorageError("QUERY_FAILED", `d1Adapter.getById failed for table "${table}"`, cause);
+      }
+    },
+    async list(table, listOpts) {
+      assertSafeIdent(table);
+      const whereClauses = [];
+      const binds = [];
+      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]} ?`);
+            binds.push(val.value);
+          } else {
+            whereClauses.push(`${quoteIdent(snakeCol)} = ?`);
+            binds.push(val);
+          }
+        }
+      }
+      if (listOpts?.cursor !== undefined) {
+        whereClauses.push(`id > ?`);
+        binds.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();
+      binds.push(limit);
+      try {
+        const result = await db.prepare(sql).bind(...binds).all();
+        const rows = (result.results ?? []).map((r) => rowToCamel(r));
+        const nextCursor = rows.length === limit ? rows[rows.length - 1]?.id ?? null : null;
+        return {
+          rows,
+          nextCursor: nextCursor === null ? null : String(nextCursor)
+        };
+      } catch (cause) {
+        throw new RowStorageError("QUERY_FAILED", `d1Adapter.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 binds = [];
+      for (const [k, v] of finalEntries) {
+        assertSafeIdent(k);
+        cols.push(quoteIdent(k));
+        binds.push(v);
+      }
+      const placeholders = cols.map(() => "?").join(", ");
+      const sql = `INSERT INTO ${quoteIdent(table)} (${cols.join(", ")}) VALUES (${placeholders})`;
+      try {
+        await db.prepare(sql).bind(...binds).run();
+        return { id };
+      } catch (cause) {
+        if (isUniqueViolation(cause))
+          throw new UniqueConstraintError(table, cause);
+        throw new RowStorageError("INSERT_FAILED", `d1Adapter.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 binds = [];
+      for (const [k, v] of Object.entries(snakePatch)) {
+        assertSafeIdent(k);
+        sets.push(`${quoteIdent(k)} = ?`);
+        binds.push(v);
+      }
+      binds.push(id);
+      const sql = `UPDATE ${quoteIdent(table)} SET ${sets.join(", ")} WHERE id = ?`;
+      try {
+        await db.prepare(sql).bind(...binds).run();
+      } catch (cause) {
+        if (isUniqueViolation(cause))
+          throw new UniqueConstraintError(table, cause);
+        throw new RowStorageError("UPDATE_FAILED", `d1Adapter.update failed for table "${table}"`, cause);
+      }
+    },
+    async delete(table, id) {
+      assertSafeIdent(table);
+      const sql = `DELETE FROM ${quoteIdent(table)} WHERE id = ?`;
+      try {
+        await db.prepare(sql).bind(id).run();
+      } catch (cause) {
+        throw new RowStorageError("DELETE_FAILED", `d1Adapter.delete failed for table "${table}"`, cause);
+      }
+    }
+  };
+}
+export {
+  d1Adapter
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@saacms/storage-d1",
+  "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:*",
+    "@cloudflare/workers-types": "^4.20240925.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "effect": "^3.10.0",
+    "typescript": "^5.7.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}