@palbase/backend 33.0.2 → 34.1.0

package/dist/{registry-DSTThhKf.d.cts → registry-BkIVHPzB.d.cts}

@@ -1,4 +1,4 @@
-import { A as AuthSpec, R as RateLimitConfig } from './index-DB_nW-AV.cjs';
+import { D as DatabaseBudget, A as AuthSpec, R as RateLimitConfig } from './endpoint-DqhUP7RT.cjs';
 import { ZodTypeAny } from 'zod';
 import { PalbaseBucketName } from './stack.cjs';
 
@@ -200,6 +200,8 @@ declare function Signal(): ParameterDecorator;
 type HttpMethodUpper = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
 /** Route-level options accepted by the method decorators (`@Get`/`@Post`/…). */
 interface RouteOptions {
+    /** Enforced before statements and COMMIT; include retries and service queries. */
+    databaseBudget?: DatabaseBudget;
     /** OVERRIDES the controller-level default auth for this one route. */
     auth?: AuthSpec;
     /** Per-route rate limit. */

package/dist/{registry-JjF5lcj4.d.ts → registry-CvGLR5j1.d.ts}

@@ -1,4 +1,4 @@
-import { A as AuthSpec, R as RateLimitConfig } from './index-DMZG3kpo.js';
+import { D as DatabaseBudget, A as AuthSpec, R as RateLimitConfig } from './endpoint-BXPdsTA5.js';
 import { ZodTypeAny } from 'zod';
 import { PalbaseBucketName } from './stack.js';
 
@@ -200,6 +200,8 @@ declare function Signal(): ParameterDecorator;
 type HttpMethodUpper = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "QUERY";
 /** Route-level options accepted by the method decorators (`@Get`/`@Post`/…). */
 interface RouteOptions {
+    /** Enforced before statements and COMMIT; include retries and service queries. */
+    databaseBudget?: DatabaseBudget;
     /** OVERRIDES the controller-level default auth for this one route. */
     auth?: AuthSpec;
     /** Per-route rate limit. */

package/dist/test/index.cjs

@@ -1458,6 +1458,18 @@ function isolated() {
 }
 __name(isolated, "isolated");
 
+// src/db/bulk.ts
+function validateInsertManyOptions(opts) {
+  if (!opts) return;
+  if (opts.returning !== void 0 && typeof opts.returning !== "boolean") throw new Error("insertMany returning must be a boolean");
+  if (opts.action !== void 0 && opts.action !== "ignore" && opts.action !== "update") throw new Error("insertMany action must be ignore or update");
+  if (opts.onConflict !== void 0 && (!Array.isArray(opts.onConflict) || opts.onConflict.some((c) => typeof c !== "string" || c.length === 0))) {
+    throw new Error("insertMany onConflict must be an array of column names");
+  }
+  if (opts.action !== void 0 && !opts.onConflict?.length) throw new Error("insertMany action requires nonempty onConflict columns");
+}
+__name(validateInsertManyOptions, "validateInsertManyOptions");
+
 // src/db/input-guards.ts
 var REF_BRAND = /* @__PURE__ */ Symbol.for("palbase.db.ref");
 function brandRef(v, kind) {
@@ -2279,6 +2291,14 @@ function createMockDB() {
   }
   __name(resolveInsertValues, "resolveInsertValues");
   const ops = {
+    diagnostics: /* @__PURE__ */ __name(() => null, "diagnostics"),
+    readQuery: /* @__PURE__ */ __name((query) => ops.findMany(query.table, query.where, query.options), "readQuery"),
+    compileQuery() {
+      throw new Error("MockDB cannot compile PostgreSQL query plans; use the real engine to inspect SQL");
+    },
+    async explainQuery() {
+      throw new Error("MockDB cannot EXPLAIN PostgreSQL plans; use a PostgreSQL integration test");
+    },
     // The bulk ops and count run against the SAME in-memory store the direct
     // ops write to, so a test that writes three rows and counts them gets 3 —
     // a mock that answered 0 would make the surface look broken in exactly the
@@ -2416,8 +2436,10 @@ function createMockDB() {
         return out;
       });
     },
-    async insertMany(table, rows) {
-      if (rows.length === 0) return [];
+    insertMany: /* @__PURE__ */ __name(async function(table, rows, opts) {
+      validateInsertManyOptions(opts);
+      if (opts?.onConflict?.length) throw new Error("fakeDatabase insertMany cannot enforce PostgreSQL unique constraints; use an integration test for onConflict");
+      if (rows.length === 0) return opts?.returning === false ? 0 : [];
       const cols = Object.keys(rows[0]);
       for (let i = 1; i < rows.length; i++) {
         const missing = cols.filter((c) => !(c in rows[i]));
@@ -2439,8 +2461,8 @@ function createMockDB() {
         track(tracked.inserted, table, record);
         out.push(record);
       }
-      return out;
-    },
+      return opts?.returning === false ? out.length : out;
+    }, "insertMany"),
     /**
     * `claim` — motorla PARİTE (FR-033).
     *
@@ -2562,6 +2584,9 @@ function createMockDB() {
         id
       ]);
     },
+    async findUnique() {
+      throw new Error("MockDB.findUnique cannot verify declared PostgreSQL unique constraints; use a PostgreSQL integration test");
+    },
     async findById(table, id) {
       const rows = store.get(table) ?? [];
       return rows.find((r) => r["id"] === id) ?? null;
@@ -2570,6 +2595,9 @@ function createMockDB() {
     // equality, an object is an operator set. A fake that understood less would
     // pass a service test that the live database then fails — which is the one
     // thing a stand-in must never do.
+    async page() {
+      throw new Error("fakeDatabase cannot reproduce PostgreSQL cursor ordering, collations or RLS; use a PostgreSQL integration test or inject an explicit page response");
+    },
     async findMany(table, query, opts) {
       assertUsableFilter("findMany", table, query);
       refuseFragment("findMany", table, query);
@@ -2764,6 +2792,13 @@ function createMockDB() {
   __name(applyOp, "applyOp");
   const client = {
     ...ops,
+    async command(plan, options) {
+      if (options?.mode === "compiled") throw new Error("fakeDatabase does not run the PostgreSQL command executor; verify compiled mode against PostgreSQL");
+      return client.txPlan(plan);
+    },
+    async atomic() {
+      throw new Error("fakeDatabase cannot verify physical transaction isolation, COMMIT or retry; test $atomic against PostgreSQL or inject a transaction test double explicitly");
+    },
     // No real savepoint in memory: the fake runs the callback against the SAME
     // store. An assertion about rollback here would be asserting the fake.
     attempt: /* @__PURE__ */ __name((fn) => fn(ops), "attempt"),
@@ -2860,68 +2895,21 @@ __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");
+// src/db/transaction-options.ts
+function retryBudget(value) {
+  const n = value ?? 0;
+  if (!Number.isInteger(n) || n < 0 || n > 10) {
+    throw new Error("transaction retry must be an integer between 0 and 10");
   }
-  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";
+  return n;
 }
-__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(retryBudget, "retryBudget");
+function assertPlanRetry(options) {
+  if (retryBudget(options?.retry) !== 0) {
+    throw new Error("Database.$transaction is a savepoint plan on the request transaction and cannot retry its snapshot or COMMIT. Use Database.$atomic(async tx => { ... }, { retry, isolation }) and put all decision reads and writes inside that callback.");
   }
 }
-__name(withRetry, "withRetry");
+__name(assertPlanRetry, "assertPlanRetry");
 
 // src/db/schema-json.ts
 function qualifiedTableKey(schemaName, tableName) {
@@ -2991,6 +2979,14 @@ function makeTableProxy(ops, prefix) {
         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"),
+        findUnique: /* @__PURE__ */ __name((q) => ops().findUnique(name, q.where, {
+          select: q.select,
+          with: q.with
+        }), "findUnique"),
+        page: /* @__PURE__ */ __name((q) => {
+          const { where, ...opts } = q ?? {};
+          return ops().page(name, where, opts);
+        }, "page"),
         findMany: /* @__PURE__ */ __name((q) => {
           const { where, ...opts } = q ?? {};
           return ops().findMany(name, where, opts);
@@ -3028,10 +3024,16 @@ function makeTypedSurface(raw) {
   const reco = raw;
   const ops = {
     $query: /* @__PURE__ */ __name((sql, params) => raw.query(sql, params), "$query"),
+    $diagnostics: /* @__PURE__ */ __name(() => raw.diagnostics(), "$diagnostics"),
+    $readQuery: /* @__PURE__ */ __name((query) => raw.readQuery(query), "$readQuery"),
+    $compileQuery: /* @__PURE__ */ __name((query) => raw.compileQuery(query), "$compileQuery"),
+    $explainQuery: /* @__PURE__ */ __name((query) => raw.explainQuery(query), "$explainQuery"),
     $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"),
+    $findUnique: /* @__PURE__ */ __name((table, where, opts) => raw.findUnique(table, where, opts), "$findUnique"),
+    $page: /* @__PURE__ */ __name((table, query, opts) => raw.page(table, query, opts), "$page"),
     $findMany: /* @__PURE__ */ __name((table, query, opts) => raw.findMany(table, query, opts), "$findMany"),
     $put: /* @__PURE__ */ __name((table, data, opts) => raw.put(table, data, opts), "$put"),
     // `opts` İLETİLİR. Düşürüldüğü sürece `Database.$updateMany(t, w, s,
@@ -3054,14 +3056,49 @@ function makeTypedSurface(raw) {
     $supersede: /* @__PURE__ */ __name((table, id, row) => raw.supersede(table, id, row), "$supersede")
   };
   const base = Object.assign(ops, {
+    $atomic(fn, options) {
+      if (typeof raw.atomic !== "function") {
+        throw new Error("This Database handle cannot open a root transaction; nested $atomic is not supported");
+      }
+      const parent = __requestALS.getStore();
+      let runtime2;
+      try {
+        runtime2 = __getRuntime();
+      } catch {
+      }
+      return raw.atomic(async (tx) => {
+        const typed = makeTypedSurface(tx);
+        const invoke = /* @__PURE__ */ __name(() => fn(typed), "invoke");
+        if (!runtime2) return invoke();
+        const refuse = /* @__PURE__ */ __name(() => {
+          throw new Error("Database.$atomic owns one transaction and identity; nested roots and $asService are not allowed");
+        }, "refuse");
+        const ambient = Object.assign({}, tx, {
+          atomic: refuse,
+          asService: refuse
+        });
+        return __requestALS.run({
+          ...parent,
+          runtime: {
+            ...runtime2,
+            Database: ambient
+          }
+        }, invoke);
+      }, options);
+    },
     // 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 ?? {});
+      assertPlanRetry(opts);
+      const builder = new TxPlanBuilder();
+      return runTxPlan(raw, makeTxPlanHandle(builder), builder, fn);
+    },
+    $command(fn, options) {
+      const builder = new TxPlanBuilder();
+      return runTxPlan({
+        txPlan: /* @__PURE__ */ __name((plan) => raw.command(plan, options), "txPlan")
+      }, makeTxPlanHandle(builder), builder, fn);
     }
   });
   return new Proxy(base, {