@palbase/backend 10.3.0 → 12.0.0

package/dist/test/index.cjs

@@ -27,6 +27,386 @@ module.exports = __toCommonJS(test_exports);
 
 // src/runtime.ts
 var import_node_async_hooks = require("async_hooks");
+
+// src/db/tx-plan.ts
+var TxRefError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TxRefError";
+  }
+};
+var TxPlanError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TxPlanError";
+  }
+};
+var EXPR = /* @__PURE__ */ Symbol.for("palbase.tx.expr");
+var REF = /* @__PURE__ */ Symbol.for("palbase.tx.ref");
+var ROW = /* @__PURE__ */ Symbol.for("palbase.tx.row");
+var ROWS = /* @__PURE__ */ Symbol.for("palbase.tx.rows");
+var TRAPPED_PROPS = [
+  "then",
+  "valueOf",
+  "toString",
+  "toJSON",
+  Symbol.toPrimitive
+];
+function trap(prop, what, hint) {
+  const name = typeof prop === "symbol" ? prop.description ?? String(prop) : prop;
+  throw new TxRefError(
+    `${what} was used as a value (via \`${name}\`). Nothing in a transaction callback has run yet, so there is no value to read. ${hint}`
+  );
+}
+function makeRef(op, field) {
+  const target = { [REF]: { op, field } };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === REF) return t[REF];
+      if (TRAPPED_PROPS.includes(prop)) {
+        trap(
+          prop,
+          `\`${field}\` of a row this transaction has not written yet`,
+          "Pass it to another operation in the same plan, or return it from the callback and read it after `transaction()` resolves."
+        );
+      }
+      return void 0;
+    }
+  });
+}
+function makeRowHandle(op) {
+  const target = { [ROW]: op };
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === ROW) return t[ROW];
+      if (TRAPPED_PROPS.includes(prop)) {
+        trap(
+          prop,
+          "A row this transaction has not written yet",
+          "Read one of its columns to reference it, or return the row from the callback and read it after `transaction()` resolves."
+        );
+      }
+      if (typeof prop === "symbol") return void 0;
+      return makeRef(op, prop);
+    }
+  });
+}
+function refDescriptor(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const d = v[REF];
+  return isRefDescriptor(d) ? d : null;
+}
+function isRefDescriptor(d) {
+  return typeof d === "object" && d !== null && typeof d.op === "number" && typeof d.field === "string";
+}
+function rowOpIndex(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const op = v[ROW];
+  return typeof op === "number" ? op : null;
+}
+function exprOf(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const e = v[EXPR];
+  return typeof e === "object" && e !== null ? e : null;
+}
+function isRowsHandle(v) {
+  return typeof v === "object" && v !== null && v[ROWS] !== void 0;
+}
+function encodeValue(value, column, allowColumnExpr) {
+  const ref = refDescriptor(value);
+  if (ref) return { $ref: { op: ref.op, field: ref.field } };
+  const expr = exprOf(value);
+  if (expr) {
+    if (expr.fn !== "now" && !allowColumnExpr) {
+      throw new TxPlanError(
+        `\`${column}\`: ${expr.fn}() reads the column's current value, so it is only valid in updateWhere(where, set).`
+      );
+    }
+    return { $expr: expr };
+  }
+  if (rowOpIndex(value) !== null) {
+    throw new TxPlanError(
+      `\`${column}\`: a row handle is not a value. Read the column you meant (e.g. \`row.id\`).`
+    );
+  }
+  if (isRowsHandle(value)) {
+    throw new TxPlanError(
+      `\`${column}\`: an operation result is not a value. Declare an expectation first (\`.expectOne(err)\`) and read a column from the row.`
+    );
+  }
+  assertNoNestedHandles(value, column);
+  return value;
+}
+function assertNoNestedHandles(value, column) {
+  if (typeof value !== "object" || value === null) return;
+  if (value instanceof Date) return;
+  if (refDescriptor(value) || exprOf(value) || rowOpIndex(value) !== null || isRowsHandle(value)) {
+    throw new TxPlanError(
+      `\`${column}\`: a plan handle is nested inside a value. The server would store it as literal JSON, not resolve it. Put the reference directly in the column.`
+    );
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) assertNoNestedHandles(item, column);
+    return;
+  }
+  for (const item of Object.values(value)) {
+    assertNoNestedHandles(item, column);
+  }
+}
+function encodeMap(map, allowColumnExpr) {
+  const out = {};
+  for (const key of Object.keys(map).sort()) {
+    const value = map[key];
+    if (value === void 0) continue;
+    out[key] = encodeValue(value, key, allowColumnExpr);
+  }
+  return out;
+}
+var SKIPPED_OP = -1;
+var TxRowsImpl = class {
+  constructor(builder, opIndex, what) {
+    this.builder = builder;
+    this.opIndex = opIndex;
+    this.what = what;
+  }
+  builder;
+  opIndex;
+  what;
+  // Present so `isRowsHandle` recognises the object; never read for its value.
+  [ROWS] = true;
+  guarded = false;
+  // The type-level `await` guard made real: TS rejects `await rows` at compile
+  // time, and reaching this means someone called `.then(...)` by hand.
+  then() {
+    throw new TxRefError(
+      `${this.what} cannot be awaited: a transaction callback builds a plan, it does not run statements. Remove the \`await\`.`
+    );
+  }
+  expectOne(error) {
+    this.declareGuard("one", 1, error);
+    if (this.opIndex === SKIPPED_OP) throw error;
+    return makeRowHandle(this.opIndex);
+  }
+  expectNone(error) {
+    this.declareGuard("none", 0, error);
+  }
+  expectAtLeast(n, error) {
+    assertGuardCount(n, "expectAtLeast");
+    this.declareGuard("atLeast", n, error);
+    if (this.opIndex === SKIPPED_OP && n > 0) throw error;
+  }
+  expectAtMost(n, error) {
+    assertGuardCount(n, "expectAtMost");
+    this.declareGuard("atMost", n, error);
+  }
+  declareGuard(kind, n, error) {
+    if (!(error instanceof Error)) {
+      throw new TxPlanError(
+        `${this.what}: an expectation needs the Error to throw when it does not hold (e.g. \`.expect\u2026(new Conflict("already accepted"))\`).`
+      );
+    }
+    if (this.guarded) {
+      throw new TxPlanError(
+        `${this.what} already has an expectation. One operation carries one expectation; declare the second one on its own operation.`
+      );
+    }
+    this.guarded = true;
+    if (this.opIndex === SKIPPED_OP) return;
+    this.builder.attachGuard(this.opIndex, kind, n, error);
+  }
+};
+function assertGuardCount(n, fn) {
+  if (!Number.isInteger(n) || n < 0) {
+    throw new TxPlanError(`${fn}(n) needs a non-negative integer, got ${String(n)}`);
+  }
+}
+var MAX_OPS = 1e3;
+var MAX_ROWS = 5e3;
+var TxPlanBuilder = class {
+  ops = [];
+  /** Errors handed to expectations, indexed by the `slot` the server echoes. */
+  slots = [];
+  /** The table surface handed to the callback. Untyped here; the public
+   * `transaction()` signatures put the schema types on top. */
+  table(name) {
+    return {
+      insert: (values) => {
+        const encoded = encodeMap(values, false);
+        if (Object.keys(encoded).length === 0) {
+          throw new TxPlanError(`${name}.insert() needs at least one column`);
+        }
+        return this.push({ op: "insert", table: name, values: encoded }, `${name}.insert()`);
+      },
+      insertMany: (rows) => {
+        if (rows.length === 0) {
+          return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
+        }
+        if (rows.length > MAX_ROWS) {
+          throw new TxPlanError(
+            `${name}.insertMany() has ${rows.length} rows; the limit is ${MAX_ROWS}. Split the write across requests.`
+          );
+        }
+        const encoded = rows.map((row) => encodeMap(row, false));
+        assertUniformRows(encoded, name);
+        return this.push({ op: "insertMany", table: name, rows: encoded }, `${name}.insertMany()`);
+      },
+      updateWhere: (where, set) => {
+        const encodedWhere = encodeMap(where, false);
+        const encodedSet = encodeMap(set, true);
+        if (Object.keys(encodedWhere).length === 0) {
+          throw new TxPlanError(
+            `${name}.updateWhere() needs a filter. An update with no filter rewrites the whole table.`
+          );
+        }
+        if (Object.keys(encodedSet).length === 0) {
+          throw new TxPlanError(`${name}.updateWhere() needs at least one column to set`);
+        }
+        return this.push(
+          { op: "update", table: name, set: encodedSet, where: encodedWhere },
+          `${name}.updateWhere()`
+        );
+      },
+      deleteWhere: (where) => {
+        const encodedWhere = encodeMap(where, false);
+        if (Object.keys(encodedWhere).length === 0) {
+          throw new TxPlanError(
+            `${name}.deleteWhere() needs a filter. A delete with no filter empties the table.`
+          );
+        }
+        return this.push(
+          { op: "delete", table: name, where: encodedWhere },
+          `${name}.deleteWhere()`
+        );
+      },
+      select: (where, options) => {
+        const op = { op: "select", table: name };
+        const encodedWhere = encodeMap(where ?? {}, false);
+        if (Object.keys(encodedWhere).length > 0) op.where = encodedWhere;
+        if (options?.limit !== void 0) {
+          if (!Number.isInteger(options.limit) || options.limit < 0) {
+            throw new TxPlanError(
+              `${name}.select(): limit needs a non-negative integer, got ${String(options.limit)}`
+            );
+          }
+          op.limit = options.limit;
+        }
+        if (options?.lock !== void 0) op.lock = options.lock;
+        return this.push(op, `${name}.select()`);
+      }
+    };
+  }
+  push(op, what) {
+    if (this.ops.length >= MAX_OPS) {
+      throw new TxPlanError(
+        `this transaction has ${MAX_OPS} operations, which is the limit. Use insertMany() for bulk writes, or split the work across requests.`
+      );
+    }
+    const index = this.ops.length;
+    this.ops.push(op);
+    return new TxRowsImpl(this, index, what);
+  }
+  /** Attach an expectation to an op and record its error in the slot table. */
+  attachGuard(opIndex, kind, n, error) {
+    const op = this.ops[opIndex];
+    if (!op) throw new TxPlanError(`internal: expectation on unknown operation ${opIndex}`);
+    const slot = this.slots.length;
+    this.slots.push(error);
+    op.guard = { kind, n, slot };
+  }
+  /** The serialisable plan. Empty when the callback described no writes. */
+  body() {
+    return { ops: this.ops };
+  }
+  /** The error the server's `slot` selects, or `null` when it names one this
+   * plan never declared (a server/client disagreement, not a tenant error). */
+  errorForSlot(slot) {
+    return this.slots[slot] ?? null;
+  }
+};
+function assertUniformRows(rows, table) {
+  const first = rows[0];
+  if (!first) return;
+  const want = Object.keys(first);
+  const wantKey = want.join(",");
+  for (let i = 1; i < rows.length; i++) {
+    const got = Object.keys(rows[i]);
+    if (got.join(",") !== wantKey) {
+      throw new TxPlanError(
+        `${table}.insertMany(): every row must set the same columns. Row 0 sets [${want.join(", ")}] but row ${i} sets [${got.join(", ")}]. (A property set to \`undefined\` counts as absent \u2014 use \`null\`.)`
+      );
+    }
+  }
+}
+function materializeResult(value, results) {
+  const ref = refDescriptor(value);
+  if (ref) {
+    const row = rowOf(results, ref.op, `\`${ref.field}\``);
+    if (!(ref.field in row)) {
+      throw new TxPlanError(
+        `the transaction's operation ${ref.op} returned no column \`${ref.field}\`.`
+      );
+    }
+    return row[ref.field];
+  }
+  const rowOp = rowOpIndex(value);
+  if (rowOp !== null) return rowOf(results, rowOp, "a row");
+  if (isRowsHandle(value)) {
+    throw new TxPlanError(
+      "an operation result cannot be returned from a transaction callback: its row count is not known until the plan runs. Declare an expectation (`.expectOne(err)`) and return the row, or a column of it."
+    );
+  }
+  if (Array.isArray(value)) return value.map((item) => materializeResult(item, results));
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [key, item] of Object.entries(value)) out[key] = materializeResult(item, results);
+    return out;
+  }
+  return value;
+}
+function rowOf(results, opIndex, what) {
+  const result = results[opIndex];
+  if (!result) {
+    throw new TxPlanError(
+      `the transaction returned no result for operation ${opIndex}, so ${what} cannot be read.`
+    );
+  }
+  const row = result.rows[0];
+  if (!row) {
+    throw new TxPlanError(
+      `the transaction's operation ${opIndex} returned no row, so ${what} cannot be read.`
+    );
+  }
+  return row;
+}
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+async function runTxPlan(transport, tables, builder, fn) {
+  const returned = fn({ tables });
+  const body = builder.body();
+  if (body.ops.length === 0) {
+    return materializeResult(returned, []);
+  }
+  let response;
+  try {
+    response = await transport.txPlan(body);
+  } catch (err) {
+    throw translateRejection(err, builder);
+  }
+  return materializeResult(returned, response.results);
+}
+function translateRejection(err, builder) {
+  if (typeof err !== "object" || err === null) return err;
+  const rejection = err;
+  if (rejection.error_code !== "tx_guard_failed" || typeof rejection.slot !== "number") {
+    return err;
+  }
+  return builder.errorForSlot(rejection.slot) ?? err;
+}
+
+// src/runtime.ts
 var __requestALS = new import_node_async_hooks.AsyncLocalStorage();
 var runtime = null;
 function __setRuntime(services) {
@@ -84,10 +464,23 @@ function makeTypedSurface(raw) {
   return Object.assign(ops, {
     tables: makeTablesAccessor(() => raw),
     transaction(fn) {
-      return raw.transaction((rawTx) => fn({ tables: makeTablesAccessor(() => rawTx) }));
+      const builder = new TxPlanBuilder();
+      return runTxPlan(raw, makeTxTablesAccessor(builder), builder, fn);
     }
   });
 }
+function makeTxTablesAccessor(builder) {
+  const tablesProxy = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        return builder.table(prop);
+      }
+    }
+  );
+  return tablesProxy;
+}
 var Database = Object.assign(makeTypedSurface(rawDatabase), {
   /**
    * Lazily resolve the runtime's service-role sibling on each call. We do NOT
@@ -145,16 +538,27 @@ function createMockDB() {
     updated: /* @__PURE__ */ new Map(),
     deleted: /* @__PURE__ */ new Map()
   };
+  function rowsOf(table) {
+    let rows = store.get(table);
+    if (!rows) {
+      rows = [];
+      store.set(table, rows);
+    }
+    return rows;
+  }
+  function track(map, table, row) {
+    const list = map.get(table);
+    if (list) list.push(row);
+    else map.set(table, [row]);
+  }
   const ops = {
     async query(_sql, _params) {
       return [];
     },
     async insert(table, data) {
       const record = { id: crypto.randomUUID(), ...data };
-      if (!store.has(table)) store.set(table, []);
-      store.get(table).push(record);
-      if (!tracked.inserted.has(table)) tracked.inserted.set(table, []);
-      tracked.inserted.get(table).push(record);
+      rowsOf(table).push(record);
+      track(tracked.inserted, table, record);
       return record;
     },
     async update(table, id, data) {
@@ -164,16 +568,16 @@ function createMockDB() {
       if (idx >= 0) {
         rows[idx] = updated;
       }
-      if (!tracked.updated.has(table)) tracked.updated.set(table, []);
-      tracked.updated.get(table).push(updated);
+      track(tracked.updated, table, updated);
       return updated;
     },
     async delete(table, id) {
       const rows = store.get(table) ?? [];
       const idx = rows.findIndex((r) => r["id"] === id);
       if (idx >= 0) rows.splice(idx, 1);
-      if (!tracked.deleted.has(table)) tracked.deleted.set(table, []);
-      tracked.deleted.get(table).push(id);
+      const list = tracked.deleted.get(table);
+      if (list) list.push(id);
+      else tracked.deleted.set(table, [id]);
     },
     async findById(table, id) {
       const rows = store.get(table) ?? [];
@@ -187,11 +591,88 @@ function createMockDB() {
       );
     }
   };
+  async function txPlan(plan) {
+    const snapshot = /* @__PURE__ */ new Map();
+    for (const [table, rows] of store) snapshot.set(table, [...rows]);
+    const trackedSnapshot = {
+      inserted: cloneTracked(tracked.inserted),
+      updated: cloneTracked(tracked.updated),
+      deleted: new Map([...tracked.deleted].map(([k, v]) => [k, [...v]]))
+    };
+    const results = [];
+    try {
+      for (const op of plan.ops) {
+        const result = applyOp(op, results);
+        results.push(result);
+        const failure = guardFailure(op.guard, result.rows.length);
+        if (failure) throw failure;
+      }
+    } catch (err) {
+      store.clear();
+      for (const [table, rows] of snapshot) store.set(table, rows);
+      tracked.inserted = trackedSnapshot.inserted;
+      tracked.updated = trackedSnapshot.updated;
+      tracked.deleted = trackedSnapshot.deleted;
+      throw err;
+    }
+    return { results };
+  }
+  function applyOp(op, results) {
+    switch (op.op) {
+      case "insert": {
+        const record = { id: crypto.randomUUID(), ...resolveMap(op.values ?? {}, results, null) };
+        rowsOf(op.table).push(record);
+        track(tracked.inserted, op.table, record);
+        return { rows: [record], rows_affected: 1 };
+      }
+      case "insertMany": {
+        const written = (op.rows ?? []).map((row) => {
+          const record = { id: crypto.randomUUID(), ...resolveMap(row, results, null) };
+          rowsOf(op.table).push(record);
+          track(tracked.inserted, op.table, record);
+          return record;
+        });
+        return { rows: written, rows_affected: written.length };
+      }
+      case "update": {
+        const rows = rowsOf(op.table);
+        const where = resolveMap(op.where ?? {}, results, null);
+        const written = [];
+        for (let i = 0; i < rows.length; i++) {
+          const row = rows[i];
+          if (!row || !matches(row, where)) continue;
+          const next = { ...row, ...resolveMap(op.set ?? {}, results, row) };
+          rows[i] = next;
+          track(tracked.updated, op.table, next);
+          written.push(next);
+        }
+        return { rows: written, rows_affected: written.length };
+      }
+      case "delete": {
+        const rows = rowsOf(op.table);
+        const where = resolveMap(op.where ?? {}, results, null);
+        const removed = rows.filter((row) => matches(row, where));
+        for (const row of removed) {
+          rows.splice(rows.indexOf(row), 1);
+          const id = row["id"];
+          const list = tracked.deleted.get(op.table);
+          const key = typeof id === "string" ? id : String(id);
+          if (list) list.push(key);
+          else tracked.deleted.set(op.table, [key]);
+        }
+        return { rows: removed, rows_affected: removed.length };
+      }
+      case "select": {
+        const where = resolveMap(op.where ?? {}, results, null);
+        let found = rowsOf(op.table).filter((row) => matches(row, where));
+        if (op.limit !== void 0) found = found.slice(0, op.limit);
+        return { rows: found, rows_affected: found.length };
+      }
+    }
+  }
   const client = {
     ...ops,
-    transaction(fn) {
-      return fn(ops);
-    },
+    txPlan,
     // In tests there is no real DB role; `asService()` returns the same
     // in-memory client so RLS-bypass code paths still hit the same store and
     // tracking maps. The omitted `asService` matches the contract (no
@@ -214,6 +695,58 @@ function createMockDB() {
   };
   return client;
 }
+function cloneTracked(map) {
+  return new Map([...map].map(([k, v]) => [k, [...v]]));
+}
+function resolveValue(value, results, current, column) {
+  if (typeof value !== "object" || value === null) return value;
+  const tagged = value;
+  if (tagged.$ref) {
+    const row = results[tagged.$ref.op]?.rows[0];
+    if (!row) {
+      throw txRejection(409, "tx_ref_unresolved", {
+        message: `operation ${tagged.$ref.op} produced no row to reference`
+      });
+    }
+    return row[tagged.$ref.field];
+  }
+  if (tagged.$expr) {
+    const fn = tagged.$expr["fn"];
+    if (fn === "now") return (/* @__PURE__ */ new Date()).toISOString();
+    const by = Number(tagged.$expr["by"]);
+    const base = Number(current?.[column] ?? 0);
+    return fn === "dec" ? base - by : base + by;
+  }
+  return value;
+}
+function resolveMap(map, results, current) {
+  const out = {};
+  for (const [key, value] of Object.entries(map)) {
+    out[key] = resolveValue(value, results, current, key);
+  }
+  return out;
+}
+function matches(row, where) {
+  return Object.entries(where).every(
+    ([key, value]) => value === null ? row[key] === null || row[key] === void 0 : row[key] === value
+  );
+}
+function guardFailure(guard, count) {
+  if (!guard) return null;
+  const ok = guard.kind === "one" ? count === 1 : guard.kind === "none" ? count === 0 : guard.kind === "atLeast" ? count >= guard.n : count <= guard.n;
+  if (ok) return null;
+  return txRejection(409, "tx_guard_failed", {
+    slot: guard.slot,
+    message: `expected ${guard.kind} ${guard.n} row(s), got ${count}`
+  });
+}
+function txRejection(status, code, extra) {
+  const err = new Error(extra.message);
+  err.status = status;
+  err.error_code = code;
+  if (extra.slot !== void 0) err.slot = extra.slot;
+  return err;
+}
 
 // src/test/context.ts
 function createMockLogger(logs) {