@palbase/backend 10.3.0 → 11.0.0

package/dist/index.cjs

@@ -66,6 +66,8 @@ __export(src_exports, {
   TEST_USERS_CONFIG_KIND: () => TEST_USERS_CONFIG_KIND,
   TooManyRequests: () => TooManyRequests,
   TraceId: () => TraceId,
+  TxPlanError: () => TxPlanError,
+  TxRefError: () => TxRefError,
   Unauthorized: () => Unauthorized,
   Upload: () => Upload,
   UploadedObject: () => UploadedObject,
@@ -82,6 +84,7 @@ __export(src_exports, {
   boolean: () => boolean,
   bucket: () => bucket,
   buildProvider: () => buildProvider,
+  dec: () => dec,
   defineEgress: () => defineEgress,
   defineError: () => defineError,
   defineFlags: () => defineFlags,
@@ -99,12 +102,14 @@ __export(src_exports, {
   flag: () => flag,
   getErrorRegistry: () => getErrorRegistry,
   getRoutes: () => getRoutes,
+  inc: () => inc,
   integer: () => integer,
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
   makeEnvDts: () => makeEnvDts,
   makePurchasesDts: () => makePurchasesDts,
   makeTypedDB: () => makeTypedDB,
+  now: () => now,
   numeric: () => numeric,
   parseFileSizeLimit: () => parseFileSizeLimit,
   policy: () => policy,
@@ -124,6 +129,416 @@ module.exports = __toCommonJS(src_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 now() {
+  return makeExpr({ fn: "now" });
+}
+function inc(by) {
+  assertFiniteNumber(by, "inc");
+  return makeExpr({ fn: "inc", by });
+}
+function dec(by) {
+  assertFiniteNumber(by, "dec");
+  return makeExpr({ fn: "dec", by });
+}
+function assertFiniteNumber(by, fn) {
+  if (typeof by !== "number" || !Number.isFinite(by)) {
+    throw new TxPlanError(`${fn}() needs a finite number, got ${String(by)}`);
+  }
+}
+function makeExpr(expr) {
+  return new Proxy(
+    { [EXPR]: expr },
+    {
+      get(target, prop) {
+        if (prop === EXPR) return target[EXPR];
+        if (TRAPPED_PROPS.includes(prop)) {
+          trap(prop, "A plan expression", "Write it into an operation instead.");
+        }
+        return void 0;
+      }
+    }
+  );
+}
+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) {
@@ -184,10 +599,23 @@ function makeTypedSurface(raw2) {
   return Object.assign(ops, {
     tables: makeTablesAccessor(() => raw2),
     transaction(fn) {
-      return raw2.transaction((rawTx) => fn({ tables: makeTablesAccessor(() => rawTx) }));
+      const builder = new TxPlanBuilder();
+      return runTxPlan(raw2, 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
@@ -782,19 +1210,29 @@ function makeTypedTable(name, raw2) {
   };
 }
 function makeTypedDB(schema, raw2) {
-  function buildTables(client) {
-    const tables = {};
-    for (const key of Object.keys(schema.tables)) {
-      const tableDef = schema.tables[key];
-      if (tableDef !== void 0) {
-        tables[key] = makeTypedTable(tableDef.name, client);
-      }
+  const tables = {};
+  for (const key of Object.keys(schema.tables)) {
+    const tableDef = schema.tables[key];
+    if (tableDef !== void 0) {
+      tables[key] = makeTypedTable(tableDef.name, raw2);
     }
-    return tables;
   }
   const result = {
-    tables: buildTables(raw2),
-    transaction: (fn) => raw2.transaction((rawTx) => fn({ tables: buildTables(rawTx) }))
+    tables,
+    transaction(fn) {
+      const builder = new TxPlanBuilder();
+      const planTables = {};
+      for (const key of Object.keys(schema.tables)) {
+        const tableDef = schema.tables[key];
+        if (tableDef !== void 0) planTables[key] = builder.table(tableDef.name);
+      }
+      return runTxPlan(
+        raw2,
+        planTables,
+        builder,
+        fn
+      );
+    }
   };
   return result;
 }
@@ -1133,12 +1571,12 @@ var E164_RE = /^\+[1-9]\d{1,14}$/;
 var OTP_LENGTH = 6;
 var OTP_RE = /^\d{6}$/;
 var MIN_PASSWORD_LENGTH = 8;
-function isPlainObject(value) {
+function isPlainObject2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function normalizeSeed(seed, userName) {
   if (seed === void 0) return {};
-  if (!isPlainObject(seed)) {
+  if (!isPlainObject2(seed)) {
     throw new Error(`testUser ${JSON.stringify(userName)}: seed must be { <table>: [ {...} ] }`);
   }
   const out = {};
@@ -1154,7 +1592,7 @@ function normalizeSeed(seed, userName) {
       );
     }
     for (const row of rows) {
-      if (!isPlainObject(row)) {
+      if (!isPlainObject2(row)) {
         throw new Error(
           `testUser ${JSON.stringify(userName)}: every row in seed.${table} must be an object`
         );
@@ -1165,7 +1603,7 @@ function normalizeSeed(seed, userName) {
   return out;
 }
 function testUser(opts = {}) {
-  if (!isPlainObject(opts)) {
+  if (!isPlainObject2(opts)) {
     throw new Error("testUser() expects { email?, password?, phone?, otp?, seed? }");
   }
   const hasEmail = opts.email !== void 0;
@@ -1215,7 +1653,7 @@ function testUser(opts = {}) {
   return { email, password, phone, otp, seed: normalizeSeed(opts.seed, email ?? "<template>") };
 }
 function defineTestUsers(input) {
-  if (!isPlainObject(input) || !isPlainObject(input.users)) {
+  if (!isPlainObject2(input) || !isPlainObject2(input.users)) {
     throw new Error("defineTestUsers expects { users: { <name>: testUser({...}) } }");
   }
   const users = {};
@@ -2031,6 +2469,8 @@ var import_zod2 = require("zod");
   TEST_USERS_CONFIG_KIND,
   TooManyRequests,
   TraceId,
+  TxPlanError,
+  TxRefError,
   Unauthorized,
   Upload,
   UploadedObject,
@@ -2047,6 +2487,7 @@ var import_zod2 = require("zod");
   boolean,
   bucket,
   buildProvider,
+  dec,
   defineEgress,
   defineError,
   defineFlags,
@@ -2064,12 +2505,14 @@ var import_zod2 = require("zod");
   flag,
   getErrorRegistry,
   getRoutes,
+  inc,
   integer,
   isPalbaseExtension,
   jsonb,
   makeEnvDts,
   makePurchasesDts,
   makeTypedDB,
+  now,
   numeric,
   parseFileSizeLimit,
   policy,