@ai-matrx/data 0.22.33 → 0.23.0

package/bin/matrx-data.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * matrx-data — @ai-matrx/data's build-time CLI.
+ *
+ *   matrx-data emit     [--out <dir>] [--check]      live database → the database description (read-only)
+ *   matrx-data generate --from <dir> --out <dir> [--schemas a,b]   description → typed doors in THIS app
+ *
+ * The package ships the runtime and this CLI; each app generates its own doors
+ * locally (Prisma's model), so a new column never waits on a package release.
+ */
+import path from "node:path";
+
+const [command, ...rest] = process.argv.slice(2);
+const flag = (name) => {
+  const i = rest.indexOf(name);
+  return i >= 0 ? rest[i + 1] : undefined;
+};
+
+async function main() {
+  if (command === "emit") {
+    const { emit } = await import("./emit.mjs");
+    return emit({ out: path.resolve(flag("--out") ?? "db-contract"), check: rest.includes("--check") });
+  }
+  if (command === "generate") {
+    const { generate } = await import("./generate.mjs");
+    const from = flag("--from");
+    const out = flag("--out");
+    if (!from || !out) {
+      console.error("matrx-data generate: --from <description dir> and --out <dir> are required");
+      return 2;
+    }
+    return generate({
+      from: path.resolve(from),
+      out: path.resolve(out),
+      schemas: flag("--schemas")?.split(",").map((s) => s.trim()).filter(Boolean),
+      check: rest.includes("--check"),
+      importFrom: flag("--import-from") ?? "@ai-matrx/data/db",
+    });
+  }
+  console.error("usage: matrx-data emit [--out <dir>] [--check] | matrx-data generate --from <dir> --out <dir> [--schemas a,b] [--check]");
+  return 2;
+}
+
+main().then((code) => process.exit(code ?? 0), (err) => {
+  console.error(`matrx-data ${command ?? ""}: ${err?.message ?? err}`);
+  process.exit(1);
+});

package/dist/db.cjs

@@ -7,11 +7,11 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
+var __copyProps = (to, from2, except, desc) => {
+  if (from2 && typeof from2 === "object" || typeof from2 === "function") {
+    for (let key of __getOwnPropNames(from2))
       if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+        __defProp(to, key, { get: () => from2[key], enumerable: !(desc = __getOwnPropDesc(from2, key)) || desc.enumerable });
   }
   return to;
 };
@@ -24,35 +24,52 @@ __export(db_exports, {
   DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE: () => DEFAULT_ACTIVE_ORG_COOKIE_MAX_AGE,
   DEFAULT_ACTIVE_ORG_COOKIE_NAME: () => DEFAULT_ACTIVE_ORG_COOKIE_NAME,
   DEFAULT_AUTH_COOKIE_NAME: () => DEFAULT_AUTH_COOKIE_NAME,
+  DatabaseError: () => DatabaseError,
+  DoorRefusedError: () => DoorRefusedError,
   IncompleteReadError: () => IncompleteReadError,
   RecordUnavailableError: () => RecordUnavailableError,
   SessionUnavailableError: () => SessionUnavailableError,
   WriteDidNotLandError: () => WriteDidNotLandError,
   WriteRefusedError: () => WriteRefusedError,
+  archive: () => archive,
   asJsonObject: () => asJsonObject,
+  assertDoor: () => assertDoor,
   assertWriteLanded: () => assertWriteLanded,
+  call: () => call,
+  changesOf: () => changesOf,
+  count: () => count,
   createActiveOrgCookie: () => createActiveOrgCookie,
   createAuthCookie: () => createAuthCookie,
+  createDb: () => createDb,
   createOAuthRefreshFetch: () => createOAuthRefreshFetch,
+  createServiceDb: () => createServiceDb,
   createSessionRetry: () => createSessionRetry,
   decodeActiveOrgSelection: () => decodeActiveOrgSelection,
   decodeOAuthRefreshClaims: () => decodeOAuthRefreshClaims,
   describeWriteFailure: () => describeWriteFailure,
   encodeActiveOrgSelection: () => encodeActiveOrgSelection,
   guardedUpdate: () => guardedUpdate,
+  insert: () => insert,
   isMissingSessionError: () => isMissingSessionError,
   isRecordUnavailableError: () => isRecordUnavailableError,
+  listAll: () => listAll,
   mergeJsonColumn: () => mergeJsonColumn,
+  page: () => page,
   parseCookieHeader: () => parseCookieHeader,
   personSentence: () => personSentence,
+  read: () => read,
   readAllRows: () => readAllRows,
   readAllRowsRest: () => readAllRowsRest,
   recordUnavailableMessage: () => recordUnavailableMessage,
+  remove: () => remove,
+  restore: () => restore,
   serverMessageFromBody: () => serverMessageFromBody,
+  tableByName: () => tableByName,
   tryReadAllRows: () => tryReadAllRows,
   tryReadAllRowsRest: () => tryReadAllRowsRest,
   tryWriteOne: () => tryWriteOne,
   uniqueChannelTopic: () => import_realtime.uniqueChannelTopic,
+  update: () => update,
   writeFailureStatus: () => writeFailureStatus,
   writeOne: () => writeOne,
   writeOneRow: () => writeOneRow
@@ -127,18 +144,18 @@ async function readAllRows(query, opts) {
   const maxRows = opts.maxRows ?? DEFAULT_MAX_ROWS;
   const rows = [];
   let total = null;
-  for (let from = 0; ; from += pageSize) {
-    const res = await query({ from, to: from + pageSize - 1 });
+  for (let from2 = 0; ; from2 += pageSize) {
+    const res = await query({ from: from2, to: from2 + pageSize - 1 });
     if (res.error) {
       throw new Error(
         `readAllRows(${opts.label}): query failed \u2014 ${res.error.message}`
       );
     }
-    const page = res.data ?? [];
-    rows.push(...page);
+    const page2 = res.data ?? [];
+    rows.push(...page2);
     if (typeof res.count === "number") total = res.count;
     if (total === null) {
-      if (page.length < pageSize) return rows;
+      if (page2.length < pageSize) return rows;
       throw new IncompleteReadError(
         opts.label,
         rows.length,
@@ -147,7 +164,7 @@ async function readAllRows(query, opts) {
       );
     }
     if (rows.length >= total) break;
-    if (page.length === 0) {
+    if (page2.length === 0) {
       throw new IncompleteReadError(
         opts.label,
         rows.length,
@@ -190,7 +207,7 @@ async function readAllRowsRest(opts) {
   const endpoint = `${opts.url.replace(/\/$/, "")}/rest/v1/${opts.path}`;
   const rows = [];
   let total = null;
-  for (let from = 0; ; from += pageSize) {
+  for (let from2 = 0; ; from2 += pageSize) {
     const res = await fetch(endpoint, {
       headers: {
         apikey: opts.key,
@@ -201,7 +218,7 @@ async function readAllRowsRest(opts) {
         // no total, which is unverifiable and therefore refused below. This is
         // the REST twin of supabase-js's `{ count: "exact" }`.
         Prefer: "count=exact",
-        Range: `${from}-${from + pageSize - 1}`,
+        Range: `${from2}-${from2 + pageSize - 1}`,
         "Range-Unit": "items"
       }
     });
@@ -210,12 +227,12 @@ async function readAllRowsRest(opts) {
         `readAllRowsRest(${opts.label}): HTTP ${res.status} \u2014 ${await res.text()}`
       );
     }
-    const page = await res.json();
-    rows.push(...page);
+    const page2 = await res.json();
+    rows.push(...page2);
     const totalPart = res.headers.get("content-range")?.split("/")[1];
     if (totalPart && totalPart !== "*") total = Number(totalPart);
     if (total === null) {
-      if (page.length < pageSize) return rows;
+      if (page2.length < pageSize) return rows;
       throw new IncompleteReadError(
         opts.label,
         rows.length,
@@ -224,7 +241,7 @@ async function readAllRowsRest(opts) {
       );
     }
     if (rows.length >= total) break;
-    if (page.length === 0) {
+    if (page2.length === 0) {
       throw new IncompleteReadError(
         opts.label,
         rows.length,
@@ -360,9 +377,9 @@ function belongsToStorageKey(name, storageKey) {
   if (!name.startsWith(`${storageKey}.`)) return false;
   return /^(0|[1-9][0-9]*)$/.test(name.slice(storageKey.length + 1));
 }
-function renamedCookie(cookie, from, to) {
-  if (cookie.name === from) return { ...cookie, name: to };
-  const prefix = `${from}.`;
+function renamedCookie(cookie, from2, to) {
+  if (cookie.name === from2) return { ...cookie, name: to };
+  const prefix = `${from2}.`;
   if (!cookie.name.startsWith(prefix)) return null;
   const chunk = cookie.name.slice(prefix.length);
   if (!/^(0|[1-9][0-9]*)$/.test(chunk)) return null;
@@ -955,4 +972,208 @@ function recordUnavailableMessage(entity, reason) {
 function isRecordUnavailableError(value) {
   return value instanceof RecordUnavailableError;
 }
+
+// src/db/doors.ts
+function credentialsOf(client) {
+  return {
+    async get() {
+      if (!client.auth) return null;
+      const { data } = await client.auth.getSession();
+      return data.session ? { kind: "user", accessToken: data.session.access_token } : null;
+    },
+    onChange(cb) {
+      if (!client.auth) return () => {
+      };
+      const { data } = client.auth.onAuthStateChange(() => cb());
+      return () => data.subscription.unsubscribe();
+    }
+  };
+}
+function createDb(options) {
+  const { client, organization } = options;
+  return {
+    client,
+    role: "user",
+    activeOrganization: () => organization?.() ?? null,
+    credentials: credentialsOf(client)
+  };
+}
+function createServiceDb(options) {
+  if (typeof globalThis.window !== "undefined") {
+    throw new DoorRefusedError("createServiceDb", "the service role never runs in a browser");
+  }
+  return { client: options.client, role: "service", activeOrganization: () => null, credentials: credentialsOf(options.client) };
+}
+var DoorRefusedError = class extends Error {
+  constructor(door, reason) {
+    super(`${door}: ${reason}`);
+    this.door = door;
+    this.reason = reason;
+    this.name = "DoorRefusedError";
+  }
+  door;
+  reason;
+};
+var DatabaseError = class extends Error {
+  constructor(door, cause) {
+    super(`${door}: ${cause.message}${cause.code ? ` (${cause.code})` : ""}`);
+    this.door = door;
+    this.cause = cause;
+    this.name = "DatabaseError";
+  }
+  door;
+  cause;
+};
+var CLIENT_DOORS = {
+  entity: ["read", "insert", "update", "remove", "archive"],
+  detail: ["read", "insert", "update", "remove", "archive"],
+  ledger: ["read", "insert"],
+  reference: ["read"],
+  system: ["read"],
+  restricted: [],
+  deprecated: []
+};
+var qualified = (t) => `${t.schema}.${t.name}`;
+function assertDoor(db, table, op) {
+  const door = `${op} ${qualified(table)}`;
+  if (table.type === "deprecated") throw new DoorRefusedError(door, "the table is deprecated \u2014 no door opens on it");
+  if (table.kind !== "table" && op !== "read") throw new DoorRefusedError(door, `a ${table.kind.replace("_", " ")} is read-only`);
+  if (db.role === "service") return;
+  if (table.type && !CLIENT_DOORS[table.type].includes(op))
+    throw new DoorRefusedError(door, `a ${table.type} table opens only ${CLIENT_DOORS[table.type].join(", ") || "service"} doors to a client`);
+  if (op !== "read" && table.readOnly) throw new DoorRefusedError(door, "the table is read-only to clients (client_read_only)");
+  if (op === "remove" && table.deletesRefused) throw new DoorRefusedError(door, "clients may not delete from this table (client_deletes_refused)");
+}
+function check(door, res) {
+  if (res.error) throw new DatabaseError(door, res.error);
+  return res.data;
+}
+var from = (db, t) => db.client.schema(t.schema).from(t.name);
+function byPk(q, t, id) {
+  if (t.pk.length === 1) return q.eq(t.pk[0], id);
+  const key = id;
+  return t.pk.reduce((acc, col) => acc.eq(col, key[col]), q);
+}
+async function read(db, table, id, columns = "*") {
+  assertDoor(db, table, "read");
+  return check(`read ${qualified(table)}`, await byPk(from(db, table).select(columns), table, id).maybeSingle());
+}
+async function listAll(db, table, where, opts = {}) {
+  assertDoor(db, table, "read");
+  const order = opts.orderBy ?? table.pk[0] ?? "id";
+  return readAllRows(
+    ({ from: lo, to: hi }) => {
+      let q = from(db, table).select(opts.columns ?? "*", { count: "exact" });
+      if (where) q = where(q);
+      return q.order(order, { ascending: true }).range(lo, hi);
+    },
+    {
+      label: `listAll ${qualified(table)}`,
+      ...opts.pageSize !== void 0 ? { pageSize: opts.pageSize } : {},
+      ...opts.maxRows !== void 0 ? { maxRows: opts.maxRows } : {}
+    }
+  );
+}
+async function page(db, table, window2) {
+  assertDoor(db, table, "read");
+  let q = from(db, table).select(window2.columns ?? "*", { count: "exact" });
+  if (window2.where) q = window2.where(q);
+  const res = await q.order(window2.orderBy ?? table.pk[0] ?? "id", { ascending: window2.ascending ?? true }).range(window2.from, window2.to);
+  return { rows: check(`page ${qualified(table)}`, res) ?? [], total: res.count ?? null };
+}
+async function count(db, table, where) {
+  assertDoor(db, table, "read");
+  let q = from(db, table).select("*", { count: "exact", head: true });
+  if (where) q = where(q);
+  const res = await q;
+  check(`count ${qualified(table)}`, res);
+  return res.count ?? 0;
+}
+function withOrganization(db, table, values) {
+  const door = `insert ${qualified(table)}`;
+  const org = table.org;
+  if (org.rule === "parent" && values[org.via] != null) {
+    return values;
+  }
+  if (org.rule === "binding" || org.rule === "parent") {
+    if (values.organization_id != null) return values;
+    const active = db.activeOrganization();
+    if (!active) {
+      throw new DoorRefusedError(
+        door,
+        db.role === "service" ? "a service insert names its organization_id" : "no organization: pass organization_id or bind createDb({ organization })"
+      );
+    }
+    return { ...values, organization_id: active };
+  }
+  return values;
+}
+async function insert(db, table, values) {
+  assertDoor(db, table, "insert");
+  const many = Array.isArray(values);
+  const rows = (many ? values : [values]).map((v) => withOrganization(db, table, v));
+  const res = await from(db, table).insert(rows).select("*");
+  const stored = check(`insert ${qualified(table)}`, res);
+  return many ? stored : stored[0];
+}
+async function update(db, table, id, patch, guard) {
+  assertDoor(db, table, "update");
+  const door = `update ${qualified(table)}`;
+  const values = patch;
+  if (db.role === "user") {
+    const blocked = table.readOnlyColumns.filter((c) => c in values);
+    if (blocked.length) throw new DoorRefusedError(door, `read-only to clients: ${blocked.join(", ")}`);
+  }
+  if (table.versioned && guard && "expectedVersion" in guard) {
+    return guardedUpdate({
+      expectedVersion: guard.expectedVersion,
+      applyUpdate: ({ expectedVersion, nextVersion }) => byPk(from(db, table).update({ ...values, version: nextVersion }), table, id).eq("version", expectedVersion).select("*").maybeSingle(),
+      fetchCurrent: () => byPk(from(db, table).select("*"), table, id).maybeSingle()
+    });
+  }
+  if (table.versioned && !(guard && "overwrite" in guard && guard.overwrite)) {
+    throw new DoorRefusedError(door, "a versioned table takes { expectedVersion } or { overwrite: true }");
+  }
+  const row = check(door, await byPk(from(db, table).update(values), table, id).select("*").maybeSingle());
+  return row ? { status: "saved", row } : { status: "not_found" };
+}
+async function remove(db, table, id) {
+  assertDoor(db, table, "remove");
+  const door = `remove ${qualified(table)}`;
+  if (table.softDelete) {
+    const row = check(door, await byPk(from(db, table).update({ deleted_at: (/* @__PURE__ */ new Date()).toISOString() }), table, id).select("*").maybeSingle());
+    return row ? "soft_deleted" : "not_found";
+  }
+  if (table.archive) throw new DoorRefusedError(door, "this table archives instead of deleting \u2014 use archive()");
+  const rows = check(door, await byPk(from(db, table).delete(), table, id).select("*"));
+  return rows && rows.length ? "deleted" : "not_found";
+}
+async function archive(db, table, id, opts = {}) {
+  assertDoor(db, table, "archive");
+  const door = `${opts.restore ? "restore" : "archive"} ${qualified(table)}`;
+  let values;
+  if (table.archive === "archived_at") values = { archived_at: opts.restore ? null : (/* @__PURE__ */ new Date()).toISOString() };
+  else if (table.archive === "is_archived") values = { is_archived: !opts.restore };
+  else if (table.softDelete && opts.restore) values = { deleted_at: null };
+  else throw new DoorRefusedError(door, "the table has no archive column");
+  return check(door, await byPk(from(db, table).update(values), table, id).select("*").maybeSingle());
+}
+var restore = (db, table, id) => archive(db, table, id, { restore: true });
+async function call(db, fn, args) {
+  const door = `call ${fn.schema}.${fn.name}`;
+  const role = db.role === "service" ? "service_role" : "authenticated";
+  if (!fn.roles.includes(role) && !(role === "authenticated" && fn.roles.includes("anon"))) {
+    throw new DoorRefusedError(door, `not executable by ${role} (executable by: ${fn.roles.join(", ") || "nobody"})`);
+  }
+  return check(door, await db.client.schema(fn.schema).rpc(fn.name, args));
+}
+function tableByName(index, name) {
+  const t = index[name];
+  if (!t) throw new DoorRefusedError(`tableByName ${name}`, "no such table in the database description (schema-qualify it: schema.table)");
+  return t;
+}
+function changesOf(table) {
+  if (!table.realtime) throw new DoorRefusedError(`changesOf ${qualified(table)}`, "the table is not in the supabase_realtime publication");
+  return { schema: table.schema, table: table.name };
+}
 //# sourceMappingURL=db.cjs.map