@palbase/backend 30.0.0 → 32.0.0

package/dist/test/index.cjs

@@ -25,7 +25,8 @@ __export(test_exports, {
   api: () => api,
   createTestApi: () => createTestApi,
   fakeDatabase: () => fakeDatabase,
-  isolated: () => isolated
+  isolated: () => isolated,
+  withServices: () => withServices
 });
 module.exports = __toCommonJS(test_exports);
 
@@ -53,8 +54,8 @@ var encoder = new TextEncoder();
 var hasher = null;
 async function digester() {
   if (hasher) return hasher;
-  const runtime = globalThis;
-  const nodeish = runtime.process?.versions?.node !== void 0 || runtime.process?.versions?.bun !== void 0;
+  const runtime2 = globalThis;
+  const nodeish = runtime2.process?.versions?.node !== void 0 || runtime2.process?.versions?.bun !== void 0;
   if (nodeish) {
     try {
       const mod = await import(
@@ -350,6 +351,14 @@ __name(isolated, "isolated");
 
 // src/db/input-guards.ts
 var REF_BRAND = /* @__PURE__ */ Symbol.for("palbase.db.ref");
+function brandRef(v, kind) {
+  Object.defineProperty(v, REF_BRAND, {
+    value: kind,
+    enumerable: false
+  });
+  return v;
+}
+__name(brandRef, "brandRef");
 function brandOf(v) {
   if (typeof v !== "object" || v === null) return void 0;
   return Object.hasOwn(v, REF_BRAND) ? v[REF_BRAND] : void 0;
@@ -569,12 +578,130 @@ function makeRowHandle(op) {
   });
 }
 __name(makeRowHandle, "makeRowHandle");
+function refDescriptor(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const d = v[REF];
+  return isRefDescriptor(d) ? d : null;
+}
+__name(refDescriptor, "refDescriptor");
+function isRefDescriptor(d) {
+  return typeof d === "object" && d !== null && typeof d.op === "number" && typeof d.field === "string";
+}
+__name(isRefDescriptor, "isRefDescriptor");
+function rowOpIndex(v) {
+  if (typeof v !== "object" || v === null) return null;
+  const op = v[ROW];
+  return typeof op === "number" ? op : null;
+}
+__name(rowOpIndex, "rowOpIndex");
 function exprOf(v) {
   if (typeof v !== "object" || v === null) return null;
   const e = v[EXPR];
   return typeof e === "object" && e !== null ? e : null;
 }
 __name(exprOf, "exprOf");
+function isRowsHandle(v) {
+  return typeof v === "object" && v !== null && v[ROWS] !== void 0;
+}
+__name(isRowsHandle, "isRowsHandle");
+function encodeValue(value, column, allowColumnExpr) {
+  const ref = refDescriptor(value);
+  if (ref) return brandRef({
+    $ref: {
+      op: ref.op,
+      field: ref.field
+    }
+  }, "ref");
+  if (isNowExpr(value)) return {
+    $expr: {
+      fn: "now"
+    }
+  };
+  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;
+}
+__name(encodeValue, "encodeValue");
+function encodeFilterValue(value, column) {
+  const ref = refDescriptor(value);
+  if (ref) return brandRef({
+    $ref: {
+      op: ref.op,
+      field: ref.field
+    }
+  }, "ref");
+  const expr = exprOf(value);
+  if (expr) {
+    throw new TxPlanError(`\`${column}\`: ${expr.fn}() bir YAZMA ifadesi, kar\u015F\u0131la\u015Ft\u0131rma de\u011Fil \u2014 filtrede kullan\u0131lamaz. Kolonu bir de\u011Ferle ya da col() ile kar\u015F\u0131la\u015Ft\u0131r\u0131n.`);
+  }
+  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.`);
+  }
+  if (Array.isArray(value)) return value.map((v) => encodeFilterValue(v, column));
+  if (value !== null && typeof value === "object" && !(value instanceof Date) && !isColRef(value) && !isSqlFragment(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = encodeFilterValue(v, column);
+    }
+    return out;
+  }
+  return value;
+}
+__name(encodeFilterValue, "encodeFilterValue");
+function encodeFilterMap(map) {
+  const out = {};
+  for (const key of Object.keys(map).sort()) {
+    const value = map[key];
+    if (value === void 0) continue;
+    out[key] = encodeFilterValue(value, key);
+  }
+  return out;
+}
+__name(encodeFilterMap, "encodeFilterMap");
+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);
+  }
+}
+__name(assertNoNestedHandles, "assertNoNestedHandles");
+function encodeMap(map, allowColumnExpr) {
+  const out = {};
+  for (const key of Object.keys(map).sort()) {
+    const value = map[key];
+    if (value === void 0) {
+      throw new TxPlanError(`${key} de\u011Feri undefined \u2014 bu bir yazma de\u011Feri de\u011Fil. Anahtar duruyor ama de\u011Feri yok, yani kolon sessizce YAZILMAZDI (istek g\xF6vdesinden gelen bir alan\u0131n eksik olmas\u0131 bu \u015Fekilde g\xF6r\xFCn\xFCr). Kolon varsay\u0131lan\u0131n\u0131 istiyorsan\u0131z anahtar\u0131 hi\xE7 koymay\u0131n; NULL yazmak istiyorsan\u0131z a\xE7\u0131k\xE7a null yaz\u0131n.`);
+    }
+    out[key] = encodeValue(value, key, allowColumnExpr);
+  }
+  return out;
+}
+__name(encodeMap, "encodeMap");
 var SKIPPED_OP = -1;
 var TxRowsImpl = class TxRowsImpl2 {
   static {
@@ -631,6 +758,225 @@ function assertGuardCount(n, fn) {
   }
 }
 __name(assertGuardCount, "assertGuardCount");
+var MAX_OPS = 1e3;
+var MAX_ROWS = 5e3;
+var TxPlanBuilder = class {
+  static {
+    __name(this, "TxPlanBuilder");
+  }
+  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: /* @__PURE__ */ __name((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()`);
+      }, "insert"),
+      put: /* @__PURE__ */ __name((values, options) => {
+        const encoded = encodeMap(values, false);
+        if (Object.keys(encoded).length === 0) {
+          throw new TxPlanError(`${name}.put() needs at least one column`);
+        }
+        if (options.onConflict.length === 0) {
+          throw new TxPlanError(`${name}.put() needs at least one onConflict column`);
+        }
+        return this.push({
+          op: "upsert",
+          table: name,
+          values: encoded,
+          onConflict: options.onConflict
+        }, `${name}.upsert()`);
+      }, "put"),
+      insertMany: /* @__PURE__ */ __name((rows, opts) => {
+        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);
+        if (opts !== void 0 && opts.onConflict.length === 0) {
+          throw new TxPlanError(`${name}.insertMany() was given a conflict action with no onConflict columns. Postgres matches a collision on columns, so name them.`);
+        }
+        return this.push({
+          op: "insertMany",
+          table: name,
+          rows: encoded,
+          // Omitted entirely when no options were given, so the op a plain
+          // insertMany produces is byte-identical to the one it produced
+          // before this option existed.
+          ...opts !== void 0 ? {
+            onConflict: opts.onConflict,
+            action: opts.action ?? "ignore"
+          } : {}
+        }, `${name}.insertMany()`);
+      }, "insertMany"),
+      updateWhere: /* @__PURE__ */ __name((where, set) => {
+        const encodedWhere = encodeFilterMap(where);
+        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()`);
+      }, "updateWhere"),
+      deleteWhere: /* @__PURE__ */ __name((where) => {
+        const encodedWhere = encodeFilterMap(where);
+        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()`);
+      }, "deleteWhere"),
+      select: /* @__PURE__ */ __name((where, options) => {
+        const op = {
+          op: "select",
+          table: name
+        };
+        const encodedWhere = encodeFilterMap(where ?? {});
+        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()`);
+      }, "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\`.)`);
+    }
+  }
+}
+__name(assertUniformRows, "assertUniformRows");
+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;
+}
+__name(materializeResult, "materializeResult");
+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;
+}
+__name(rowOf, "rowOf");
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+__name(isPlainObject, "isPlainObject");
+async function runTxPlan(transport, handle, builder, fn) {
+  const returned = fn(handle);
+  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);
+}
+__name(runTxPlan, "runTxPlan");
+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;
+}
+__name(translateRejection, "translateRejection");
 
 // src/__tests__/helpers/mock-db.ts
 function refuseFragment(caller, table, where) {
@@ -925,7 +1271,7 @@ function createMockDB() {
           const vals = bucket.map((r) => r[c]).filter((v) => v !== null && v !== void 0);
           (out["avg"] ??= {})[c] = vals.length === 0 ? null : String(Number(vals.reduce((a, v) => addDecimal(a, v, 1), "0")) / vals.length);
         }
-        for (const [fn, pick] of [
+        for (const [fn, pick2] of [
           [
             "min",
             -1
@@ -937,7 +1283,7 @@ function createMockDB() {
         ]) {
           for (const c of q[fn] ?? []) {
             const vals = bucket.map((r) => r[c]).filter((v) => v !== null && v !== void 0);
-            (out[fn] ??= {})[c] = vals.length === 0 ? null : vals.reduce((a, v) => cmp(v, a, pick === 1 ? "gt" : "lt") ? v : a);
+            (out[fn] ??= {})[c] = vals.length === 0 ? null : vals.reduce((a, v) => cmp(v, a, pick2 === 1 ? "gt" : "lt") ? v : a);
           }
         }
         if (q.count === true) out["count"] = bucket.length;
@@ -1086,16 +1432,12 @@ function createMockDB() {
         applied[k] = v;
       }
       assertNoExpressionHandles("update", table, Object.keys(applied), applied);
-      const updated = idx >= 0 ? {
+      if (idx < 0) return null;
+      const updated = {
         ...rows[idx],
         ...applied
-      } : {
-        id,
-        ...applied
       };
-      if (idx >= 0) {
-        rows[idx] = updated;
-      }
+      rows[idx] = updated;
       track(tracked.updated, table, updated);
       return updated;
     },
@@ -1120,6 +1462,9 @@ function createMockDB() {
     async findMany(table, query, opts) {
       assertUsableFilter("findMany", table, query);
       refuseFragment("findMany", table, query);
+      if (opts?.with !== void 0 && Object.keys(opts.with).length > 0) {
+        throw new Error(`findMany(${table}): fakeDatabase \`with\` desteklemiyor \u2014 ili\u015Fki grafi\u011Fi yabanc\u0131 anahtarlardan T\xDCRET\u0130L\u0130YOR ve fake \u015Femay\u0131 okumuyor. \u0130li\u015Fkili sat\u0131rlar\u0131 \xF6l\xE7en bir test ger\xE7ek motoru kullanmal\u0131; fake ile \xF6l\xE7mek istiyorsan\u0131z ilgili sat\u0131rlar\u0131 \`seed\` ile ayr\u0131 koyup ayr\u0131 sorgulay\u0131n.`);
+      }
       const rows = store.get(table) ?? [];
       let out = query ? rows.filter((row) => rowMatchesFilter("findMany", table, row, query)) : [
         ...rows
@@ -1401,6 +1746,315 @@ function txRejection(status, code, extra) {
 }
 __name(txRejection, "txRejection");
 
+// src/runtime.ts
+var import_node_async_hooks = require("async_hooks");
+
+// src/errors.ts
+var HTTP_ERROR_BRAND = /* @__PURE__ */ Symbol.for("palbase.backend.httpError");
+var HttpError = class extends Error {
+  static {
+    __name(this, "HttpError");
+  }
+  status;
+  error;
+  errorDescription;
+  data;
+  /** See {@link HTTP_ERROR_BRAND} — how the engine recognises this across SDK copies. */
+  [HTTP_ERROR_BRAND] = true;
+  constructor(status, error, errorDescription, data) {
+    super(errorDescription);
+    this.name = "HttpError";
+    this.status = status;
+    this.error = error;
+    this.errorDescription = errorDescription;
+    if (data !== void 0) {
+      this.data = data;
+    }
+  }
+  /**
+  * Serialize to the standard Palbase error response format.
+  * The `requestId` is injected by the runtime layer from the request context.
+  * When called without arguments (e.g. JSON.stringify), request_id is omitted.
+  * When `data` is set, it is appended as a strict-superset field.
+  */
+  toJSON(requestId) {
+    const result = {
+      error: this.error,
+      error_description: this.errorDescription,
+      status: this.status
+    };
+    if (requestId) {
+      result.request_id = requestId;
+    }
+    if (this.data !== void 0) {
+      result.data = this.data;
+    }
+    return result;
+  }
+};
+function isRetryable(e) {
+  return typeof e === "object" && e !== null && e.retryable === true && typeof e.sqlstate === "string";
+}
+__name(isRetryable, "isRetryable");
+
+// src/db/typed-db.ts
+async function withRetry(fn, opts = {}) {
+  const budget = opts.retry ?? 0;
+  let attempt = 0;
+  for (; ; ) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (attempt >= budget || !isRetryable(e)) throw e;
+      attempt += 1;
+    }
+  }
+}
+__name(withRetry, "withRetry");
+
+// src/db/schema-json.ts
+function qualifiedTableKey(schemaName, tableName) {
+  return schemaName === "" || schemaName === "public" ? tableName : `${schemaName}.${tableName}`;
+}
+__name(qualifiedTableKey, "qualifiedTableKey");
+
+// src/runtime.ts
+var REQUEST_ALS = /* @__PURE__ */ Symbol.for("palbase.backend.requestALS");
+var __requestALS = (() => {
+  const g = globalThis;
+  return g[REQUEST_ALS] ??= new import_node_async_hooks.AsyncLocalStorage();
+})();
+var runtime = null;
+function __getRuntime() {
+  const scoped = __requestALS.getStore();
+  if (scoped) return scoped.runtime;
+  if (runtime === null) {
+    throw new Error("Palbase services accessed outside a request scope. The Database/Documents/\u2026 singletons are only available inside an endpoint handler (or after the runtime has called __runWithRuntime / __setRuntime).");
+  }
+  return runtime;
+}
+__name(__getRuntime, "__getRuntime");
+function makeServiceProxy(key) {
+  const handler = {
+    get(_target, prop, receiver) {
+      const client = __getRuntime()[key];
+      const value = Reflect.get(client, prop, receiver);
+      return typeof value === "function" ? value.bind(client) : value;
+    }
+  };
+  return new Proxy({}, handler);
+}
+__name(makeServiceProxy, "makeServiceProxy");
+function makeTableProxy(ops, prefix) {
+  return new Proxy({}, {
+    get(_t, prop) {
+      if (typeof prop !== "string") return void 0;
+      const name = `${prefix}${prop}`;
+      return {
+        insert: /* @__PURE__ */ __name((data) => ops().insert(name, data), "insert"),
+        // DÖRDÜNCÜ FİİL, aynı gerekçeyle: tip söz veriyor, ops katmanı
+        // uyguluyor, ve bir handler'ın gerçekten dokunduğu yer BURASI.
+        // `runtime-table-verbs` kapısı bunu adıyla saydı.
+        aggregate: /* @__PURE__ */ __name((q) => ops().aggregate(name, q), "aggregate"),
+        insertMany: /* @__PURE__ */ __name((rows, opts) => ops().insertMany(name, rows, opts), "insertMany"),
+        update: /* @__PURE__ */ __name((q) => ops().update(name, q.where.id, q.set), "update"),
+        delete: /* @__PURE__ */ __name((id) => ops().delete(name, id), "delete"),
+        findById: /* @__PURE__ */ __name((id) => ops().findById(name, id), "findById"),
+        findMany: /* @__PURE__ */ __name((q) => {
+          const { where, ...opts } = q ?? {};
+          return ops().findMany(name, where, opts);
+        }, "findMany"),
+        put: /* @__PURE__ */ __name((q) => ops().put(name, q.data, {
+          onConflict: q.onConflict
+        }), "put"),
+        // THREE VERBS THE TYPE PROMISED AND THIS PROXY DID NOT EMIT.
+        //
+        // `EnvTypedTableBase` declares `updateMany`, `deleteMany` and `count`
+        // (typed-db.ts) and the ops layer implements all three — only this
+        // proxy, which is what a handler actually touches, left them out. So
+        // the type said the verb exists, autocomplete offered it, and the call
+        // answered `undefined is not a function`.
+        //
+        // Older than this run, but the run rewrote this proxy for
+        // `Database.schema(name).tables.*` and would have carried the gap onto
+        // the new surface too.
+        updateMany: /* @__PURE__ */ __name((q) => ops().updateMany(name, q.where, q.set), "updateMany"),
+        deleteMany: /* @__PURE__ */ __name((q) => ops().deleteMany(name, q.where), "deleteMany"),
+        count: /* @__PURE__ */ __name((q) => ops().count(name, q?.where), "count"),
+        search: /* @__PURE__ */ __name((params) => ops().search(name, params), "search"),
+        similar: /* @__PURE__ */ __name((id, params) => ops().similar(name, id, params), "similar"),
+        recommend: /* @__PURE__ */ __name((params) => ops().recommend(name, params), "recommend"),
+        facets: /* @__PURE__ */ __name((params) => ops().facets(name, params), "facets"),
+        supersede: /* @__PURE__ */ __name((id, row) => ops().supersede(name, id, row), "supersede"),
+        claim: /* @__PURE__ */ __name((unique, extra) => ops().claim(name, unique, extra), "claim")
+      };
+    }
+  });
+}
+__name(makeTableProxy, "makeTableProxy");
+var rawDatabase = makeServiceProxy("Database");
+function makeTypedSurface(raw) {
+  const reco = raw;
+  const ops = {
+    $query: /* @__PURE__ */ __name((sql, params) => raw.query(sql, params), "$query"),
+    $insert: /* @__PURE__ */ __name((table, data) => raw.insert(table, data), "$insert"),
+    $update: /* @__PURE__ */ __name((table, id, data) => raw.update(table, id, data), "$update"),
+    $delete: /* @__PURE__ */ __name((table, id) => raw.delete(table, id), "$delete"),
+    $findById: /* @__PURE__ */ __name((table, id) => raw.findById(table, id), "$findById"),
+    $findMany: /* @__PURE__ */ __name((table, query, opts) => raw.findMany(table, query, opts), "$findMany"),
+    $put: /* @__PURE__ */ __name((table, data, opts) => raw.put(table, data, opts), "$put"),
+    $updateMany: /* @__PURE__ */ __name((table, where, set) => raw.updateMany(table, where, set), "$updateMany"),
+    $deleteMany: /* @__PURE__ */ __name((table, where) => raw.deleteMany(table, where), "$deleteMany"),
+    $count: /* @__PURE__ */ __name((table, where) => raw.count(table, where), "$count"),
+    $search: /* @__PURE__ */ __name((table, params) => raw.search(table, params), "$search"),
+    $similar: /* @__PURE__ */ __name((table, id, params) => reco.similar(table, id, params), "$similar"),
+    $recommend: /* @__PURE__ */ __name((table, params) => reco.recommend(table, params), "$recommend"),
+    $facets: /* @__PURE__ */ __name((table, params) => reco.facets(table, params), "$facets"),
+    $claim: /* @__PURE__ */ __name((table, unique, extra) => reco.claim(table, unique, extra), "$claim"),
+    $lockRows: /* @__PURE__ */ __name((table, ids) => reco.lockRows(table, ids), "$lockRows"),
+    $advisoryXactLock: /* @__PURE__ */ __name((key) => reco.advisoryXactLock(key), "$advisoryXactLock"),
+    $aggregate: /* @__PURE__ */ __name((table, q) => raw.aggregate(table, q), "$aggregate"),
+    $insertMany: /* @__PURE__ */ __name((table, rows, opts) => raw.insertMany(table, rows, opts), "$insertMany"),
+    $supersede: /* @__PURE__ */ __name((table, id, row) => raw.supersede(table, id, row), "$supersede")
+  };
+  const base = Object.assign(ops, {
+    // Both surfaces get it: a savepoint on the service transaction is as useful
+    // as one on the request's, and each is bound to its own connection.
+    $attempt: /* @__PURE__ */ __name((fn) => raw.attempt(fn), "$attempt"),
+    $transaction(fn, opts) {
+      return withRetry(() => {
+        const builder = new TxPlanBuilder();
+        return runTxPlan(raw, makeTxPlanHandle(builder), builder, fn);
+      }, opts ?? {});
+    }
+  });
+  return new Proxy(base, {
+    get(target, prop, receiver) {
+      if (prop === "tables") return makeTableProxy(() => reco, "");
+      if (typeof prop === "string" && !prop.startsWith("$") && !(prop in target)) {
+        return makeTableProxy(() => reco, qualifiedTableKey(prop, ""));
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+}
+__name(makeTypedSurface, "makeTypedSurface");
+function makeTxTablesAccessor(builder, prefix = "") {
+  const tablesProxy = new Proxy({}, {
+    get(_t, prop) {
+      if (typeof prop !== "string") return void 0;
+      return builder.table(prefix + prop);
+    }
+  });
+  return tablesProxy;
+}
+__name(makeTxTablesAccessor, "makeTxTablesAccessor");
+function makeTxPlanHandle(builder) {
+  const publicTables = makeTxTablesAccessor(builder);
+  return new Proxy({}, {
+    get(_t, prop) {
+      if (typeof prop !== "string") return void 0;
+      if (prop === "tables") return publicTables;
+      return makeTxTablesAccessor(builder, qualifiedTableKey(prop, ""));
+    }
+  });
+}
+__name(makeTxPlanHandle, "makeTxPlanHandle");
+var Database = Object.assign(makeTypedSurface(rawDatabase), {
+  /**
+  * Lazily resolve the runtime's service-role sibling on each call. We do NOT
+  * cache it: `rawDatabase.asService()` reads the CURRENT request scope through
+  * the runtime proxy, and the per-request runtime injects a service client
+  * bound to that request's identity headers — caching would leak one request's
+  * sibling into another concurrent request.
+  */
+  $asService() {
+    return makeTypedSurface(rawDatabase.asService());
+  }
+});
+var Documents = makeServiceProxy("Documents");
+function makeBucketsAccessor(storage) {
+  return new Proxy({}, {
+    get(_t, prop) {
+      if (typeof prop !== "string") return void 0;
+      return storage().bucket(prop);
+    }
+  });
+}
+__name(makeBucketsAccessor, "makeBucketsAccessor");
+var rawStorage = makeServiceProxy("Storage");
+var Storage = Object.assign({
+  // FORWARDED explicitly, not assigned onto the service proxy.
+  //
+  // `Object.assign(rawStorage, {buckets})` writes onto the proxy's TARGET, and
+  // the proxy's only trap is `get`, which forwards every read to the module
+  // client — so the property landed somewhere nothing reads and
+  // `Storage.buckets.docs` was `undefined` in a deployed handler. It
+  // typechecked, every test passed, and the live call answered
+  // "TypeError: undefined is not an object". `Database` never had the bug
+  // because it builds a plain surface the same way this now does.
+  bucket: /* @__PURE__ */ __name((name) => rawStorage.bucket(name), "bucket")
+}, {
+  buckets: makeBucketsAccessor(() => rawStorage)
+});
+var Cache = makeServiceProxy("Cache");
+var Secrets = makeServiceProxy("Secrets");
+var Auth = makeServiceProxy("Auth");
+var Log = makeServiceProxy("Log");
+var Notifications = makeServiceProxy("Notifications");
+var rawFlags = makeServiceProxy("Flags");
+var Flags = Object.assign({
+  isEnabled(flagName, context) {
+    return rawFlags.isEnabled(flagName, context);
+  },
+  getVariant(flagName, context) {
+    return rawFlags.getVariant(flagName, context);
+  },
+  getAll(context) {
+    return rawFlags.getAll(context);
+  },
+  /**
+   * Resolve a flag's value, with an optional fallback.
+   *
+   * FORWARDED as of 2026-08-15. This surface is written out by hand, method
+   * by method, and `get` was missing from it — so the client implemented it,
+   * thirty assertions covered it, and `Flags.get("x")` was `undefined` in a
+   * deployed handler. Exactly the shape of the `Storage.buckets` defect found
+   * the same day: a hand-maintained forwarding list is a list somebody has to
+   * remember to update.
+   */
+  get(flagName, defaultOrContext, maybeContext) {
+    return rawFlags.get(flagName, defaultOrContext, maybeContext);
+  },
+  setOverride(key, value) {
+    return rawFlags.setOverride(key, value);
+  }
+}, {
+  /**
+   * Lazily resolve the runtime's cross-user sibling on each call. We do NOT
+   * cache it: `rawFlags.asService()` reads the CURRENT request scope through
+   * the runtime proxy, so caching would leak one request's sibling into
+   * another concurrent request. Mirrors `Database.asService()`.
+   */
+  $asService() {
+    return rawFlags.asService();
+  },
+  /**
+   * The name this member carried before 31.0.0.
+   *
+   * It does NOT work silently. A retired member that quietly keeps returning
+   * is how a rename becomes a mystery: the old call site goes on compiling,
+   * the new name never spreads, and the two live side by side until somebody
+   * greps for one and misses half the codebase. `Database` made this split
+   * first (`$asService`), and this JSDoc promised "exactly like
+   * Database.$asService()" while the promise went unkept.
+   */
+  asService() {
+    throw new Error("Flags.asService() was renamed to Flags.$asService() in 31.0.0 \u2014 system members carry the `$` prefix, like Database.$asService().");
+  }
+});
+var Realtime = makeServiceProxy("Realtime");
+
 // src/test/fake-db.ts
 function fakeDatabase() {
   const mock = createMockDB();
@@ -1415,7 +2069,8 @@ function fakeDatabase() {
     }, "query")
   });
   return {
-    db,
+    db: makeTypedSurface(db),
+    raw: db,
     queries,
     seed: /* @__PURE__ */ __name((table, rows) => mock.seed(table, rows), "seed"),
     inserted: /* @__PURE__ */ __name((table) => mock.inserted(table), "inserted"),
@@ -1424,12 +2079,46 @@ function fakeDatabase() {
   };
 }
 __name(fakeDatabase, "fakeDatabase");
+
+// src/test/with-services.ts
+function absent(name) {
+  return new Proxy({}, {
+    get(_target, prop) {
+      throw new Error(`${String(name)}.${String(prop)} was read, but this test did not provide ${String(name)}. Pass it: withServices({ ${String(name)}: \u2026 }, () => \u2026)`);
+    }
+  });
+}
+__name(absent, "absent");
+function pick(services, key) {
+  return services[key] ?? absent(key);
+}
+__name(pick, "pick");
+function withServices(services, fn) {
+  const filled = {
+    Database: pick(services, "Database"),
+    Auth: pick(services, "Auth"),
+    Secrets: pick(services, "Secrets"),
+    Documents: pick(services, "Documents"),
+    Storage: pick(services, "Storage"),
+    Cache: pick(services, "Cache"),
+    Log: pick(services, "Log"),
+    Notifications: pick(services, "Notifications"),
+    Flags: pick(services, "Flags"),
+    Realtime: pick(services, "Realtime")
+  };
+  return __requestALS.run({
+    runtime: filled,
+    userId: null
+  }, fn);
+}
+__name(withServices, "withServices");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TestApiError,
   api,
   createTestApi,
   fakeDatabase,
-  isolated
+  isolated,
+  withServices
 });
 //# sourceMappingURL=index.cjs.map