@palbase/backend 23.1.0 → 24.0.0

package/dist/index.cjs

@@ -66,20 +66,26 @@ __export(src_exports, {
   TxPlanError: () => TxPlanError,
   TxRefError: () => TxRefError,
   Unauthorized: () => Unauthorized,
+  UniqueViolation: () => UniqueViolation,
   Upload: () => Upload,
   UploadedObject: () => UploadedObject,
   User: () => User,
   Webhook: () => Webhook,
   __getRuntime: () => __getRuntime,
   __requestALS: () => __requestALS,
+  __resetDefaultAuth: () => __resetDefaultAuth,
+  __resetLifecycleHooks: () => __resetLifecycleHooks,
   __resetRegisteredControllers: () => __resetRegisteredControllers,
+  __runStartHooks: () => __runStartHooks,
   __runWithRuntime: () => __runWithRuntime,
   __setRuntime: () => __setRuntime,
+  assertZeroArgConstructor: () => assertZeroArgConstructor,
   bigint: () => bigint,
   boolean: () => boolean,
   buildModuleClients: () => buildModuleClients,
   dec: () => dec,
   defineChannels: () => defineChannels,
+  defineDefaultAuth: () => defineDefaultAuth,
   defineError: () => defineError,
   defineMiddleware: () => defineMiddleware,
   defineSchema: () => defineSchema,
@@ -100,6 +106,8 @@ __export(src_exports, {
   makeTypedDB: () => makeTypedDB,
   now: () => now,
   numeric: () => numeric,
+  onShutdown: () => onShutdown,
+  onStart: () => onStart,
   openai: () => openai,
   ownerOnly: () => ownerOnly,
   policy: () => policy,
@@ -370,7 +378,7 @@ var TxPlanBuilder = class {
           `${name}.upsert()`
         );
       },
-      insertMany: (rows) => {
+      insertMany: (rows, opts) => {
         if (rows.length === 0) {
           return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
         }
@@ -381,7 +389,23 @@ var TxPlanBuilder = class {
         }
         const encoded = rows.map((row) => encodeMap(row, false));
         assertUniformRows(encoded, name);
-        return this.push({ op: "insertMany", table: name, rows: encoded }, `${name}.insertMany()`);
+        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()`
+        );
       },
       updateWhere: (where, set) => {
         const encodedWhere = encodeMap(where, false);
@@ -558,6 +582,52 @@ function __getRuntime() {
   }
   return runtime;
 }
+var LIFECYCLE = /* @__PURE__ */ Symbol.for("palbase.backend.lifecycleHooks");
+function declaredLifecycle() {
+  const g = globalThis;
+  return g[LIFECYCLE] ??= { start: [], shutdown: [] };
+}
+function onStart(name, hook) {
+  declaredLifecycle().start.push({ name, run: hook });
+}
+function onShutdown(name, hook) {
+  declaredLifecycle().shutdown.push({ name, run: hook });
+}
+function reason(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function drain(hooks) {
+  for (const h of [...hooks].reverse()) {
+    try {
+      await h.run();
+    } catch (err) {
+      console.error(`[palbase] shutdown hook "${h.name}" failed: ${reason(err)}`, err);
+    }
+  }
+}
+async function __runStartHooks() {
+  const slot = declaredLifecycle();
+  const start = slot.start.splice(0);
+  const shutdown = slot.shutdown.splice(0);
+  for (const h of start) {
+    try {
+      await h.run();
+    } catch (err) {
+      await drain(shutdown);
+      throw new Error(`[palbase] start hook "${h.name}" failed: ${reason(err)}`, { cause: err });
+    }
+  }
+  let drained = false;
+  return async () => {
+    if (drained) return;
+    drained = true;
+    await drain(shutdown);
+  };
+}
+function __resetLifecycleHooks() {
+  const g = globalThis;
+  delete g[LIFECYCLE];
+}
 function makeServiceProxy(key) {
   const handler = {
     get(_target, prop, receiver) {
@@ -585,6 +655,7 @@ function makeTablesAccessor(ops) {
           search: (params) => ops().search(name, params),
           similar: (id, params) => ops().similar(name, id, params),
           recommend: (params) => ops().recommend(name, params),
+          facets: (params) => ops().facets(name, params),
           supersede: (id, row) => ops().supersede(name, id, row)
         };
       }
@@ -603,9 +674,13 @@ function makeTypedSurface(raw2) {
     findById: (table, id) => raw2.findById(table, id),
     findMany: (table, query, opts) => raw2.findMany(table, query, opts),
     upsert: (table, data, opts) => raw2.upsert(table, data, opts),
+    updateMany: (table, where, set) => raw2.updateMany(table, where, set),
+    deleteMany: (table, where) => raw2.deleteMany(table, where),
+    count: (table, where) => raw2.count(table, where),
     search: (table, params) => raw2.search(table, params),
     similar: (table, id, params) => reco.similar(table, id, params),
     recommend: (table, params) => reco.recommend(table, params),
+    facets: (table, params) => reco.facets(table, params),
     supersede: (table, id, row) => raw2.supersede(table, id, row)
   };
   return Object.assign(ops, {
@@ -2189,6 +2264,28 @@ var ColumnBuilder = class _ColumnBuilder {
     this._def.unique = true;
     return new _ColumnBuilder(this._def.type, this._def);
   }
+  /**
+   * Declare how this column's value is projected in and out of the process.
+   *
+   * The DDL does not move: `numeric` stays `numeric`, and the driver still hands
+   * back what Postgres sent. What changes is the type the row surface exposes —
+   * it becomes `Target`:
+   *
+   *   amount: numeric().transform<number>({ fromDb: Number, toDb: String })
+   *
+   * `numeric` surfacing as `string` is CORRECT (a JS number cannot hold
+   * arbitrary precision), and that is exactly why this exists: application code
+   * that does arithmetic on the column otherwise rewrites the same
+   * `Number(row.amount)` / `String(x)` pair in every controller that touches it,
+   * and each rewrite is a place the two directions can drift apart.
+   *
+   * A transform is a PROJECTION, never a constraint: it lives only in this
+   * process, so it can neither validate nor migrate what is stored.
+   */
+  transform(fns) {
+    this._def.transform = fns;
+    return new _ColumnBuilder(this._def.type, this._def);
+  }
 };
 function uuid() {
   return new ColumnBuilder("uuid");
@@ -2258,7 +2355,14 @@ function makeTypedTable(name, raw2) {
     update: (id, data) => raw2.update(name, id, data),
     delete: (id) => raw2.delete(name, id),
     findById: (id) => raw2.findById(name, id),
-    findMany: (query, opts) => raw2.findMany(name, query, opts)
+    findMany: (query, opts) => raw2.findMany(name, query, opts),
+    updateMany: (where, set) => raw2.updateMany(
+      name,
+      where,
+      set
+    ),
+    deleteMany: (where) => raw2.deleteMany(name, where),
+    count: (where) => raw2.count(name, where)
   };
 }
 function makeTypedDB(schema, raw2) {
@@ -2580,6 +2684,16 @@ function getRegisteredControllers() {
 function __resetRegisteredControllers() {
   registry().length = 0;
 }
+var APP_DEFAULT_AUTH = /* @__PURE__ */ Symbol.for("palbase.backend.appDefaultAuth");
+function appAuthSlot() {
+  return globalThis;
+}
+function defineDefaultAuth(auth) {
+  appAuthSlot()[APP_DEFAULT_AUTH] = auth;
+}
+function __resetDefaultAuth() {
+  delete appAuthSlot()[APP_DEFAULT_AUTH];
+}
 var RESERVED_FIRST_SEGMENT = "webhooks";
 function assertNotReserved(path, subject) {
   const [first] = path.split("/").filter(Boolean);
@@ -2621,6 +2735,14 @@ function Controller(basePath, options = {}) {
     return ctor;
   };
 }
+function assertZeroArgConstructor(Ctrl, kind) {
+  const arity = Ctrl.length ?? 0;
+  if (arity === 0) return;
+  const name = Ctrl.name ?? "<anonymous>";
+  throw new Error(
+    `${kind} ${name} declares a constructor with ${arity} parameter(s). A ${kind} is constructed by the runtime with a zero-argument constructor \u2014 there is no injector to supply them, so every parameter would arrive as undefined. Hold the dependency as a module-level singleton the ${kind} imports (\`const repo = makeRepo()\` beside the class), and construct the service directly in tests (e.g. \`new TodoService(fakeDatabase().db)\`).`
+  );
+}
 
 // src/decorators/methods.ts
 function makeMethodDecorator(method) {
@@ -2723,6 +2845,7 @@ function getWebhookConfig(ctor) {
   if (entries.length === 0) {
     throw new Error("@Webhook requires at least one @On handler");
   }
+  assertZeroArgConstructor(ctor, "webhook class");
   const instance = new ctor();
   const events = /* @__PURE__ */ Object.create(null);
   for (const entry of entries) {
@@ -2741,8 +2864,8 @@ function getWebhookConfig(ctor) {
 
 // src/decorators/hook.ts
 var Deny = class extends Error {
-  constructor(reason) {
-    super(reason);
+  constructor(reason2) {
+    super(reason2);
     this.name = "Deny";
   }
 };
@@ -2784,6 +2907,7 @@ function getHookConfig(ctor) {
       `${ctor.name ?? "a hook class"} carries no handler \u2014 a hook file must declare at least one @Hook (blocking) or @On (listener) method`
     );
   }
+  assertZeroArgConstructor(ctor, "hook class");
   const instance = new ctor();
   return {
     blocking: bind(instance, blockingEntries, "@Hook"),
@@ -2976,6 +3100,29 @@ var Conflict = class extends NamedHttpError {
     super(409, "conflict", "Conflict", message, code, data);
   }
 };
+var UniqueViolation = class extends Conflict {
+  /**
+   * Whether `e` is a unique violation — REGARDLESS of which copy of this SDK
+   * constructed it.
+   *
+   * Use this instead of `instanceof`. Measured on a live stack: a controller
+   * bundle INLINES its own copy of `@palbase/backend`, and the engine that
+   * raises this error is the runtime's copy. Two copies, two class identities,
+   * and `e instanceof UniqueViolation` is false in the one place a caller
+   * writes it — a check that reads as correct and silently never matches.
+   */
+  static is(e) {
+    return typeof e === "object" && e !== null && e.name === "UniqueViolation" && typeof e.constraint === "string";
+  }
+  /** The unique constraint the statement violated, as Postgres named it.
+   * `""` when the driver did not say which — see `engine/db.ts`. */
+  constraint;
+  constructor(constraint, message, code, data) {
+    super(message ?? "Unique constraint violated", code ?? "unique_violation", data);
+    this.name = "UniqueViolation";
+    this.constraint = constraint;
+  }
+};
 var TooManyRequests = class extends NamedHttpError {
   constructor(data, message) {
     super(429, "too_many_requests", "TooManyRequests", message, void 0, data);
@@ -3003,6 +3150,11 @@ function getErrorRegistry() {
       ["forbidden", 403, "Forbidden"],
       ["not_found", 404, "NotFound"],
       ["conflict", 409, "Conflict"],
+      // The engine's own 23505 conversion (engine/db.ts) throws this, and an
+      // author may too. Registered like every other built-in so the spec
+      // emitter resolves it — an unregistered code is SKIPPED silently there
+      // (openapi/convert.ts) and would degrade to the client's `.other` case.
+      ["unique_violation", 409, "UniqueViolation"],
       ["too_many_requests", 429, "TooManyRequests"]
     ]) {
       const dataSchema = BUILTIN_DATA_SCHEMAS[code];
@@ -3205,6 +3357,7 @@ function getJobConfig(ctor) {
   if (retry > MAX_RETRY) {
     throw new Error(`@Job \`retry\` exceeds the ceiling of ${MAX_RETRY}`);
   }
+  assertZeroArgConstructor(ctor, "job class");
   const instance = new ctor();
   if (typeof instance.run !== "function") {
     throw new Error("@Job class must declare an async run() method");
@@ -3263,20 +3416,26 @@ var import_zod2 = require("zod");
   TxPlanError,
   TxRefError,
   Unauthorized,
+  UniqueViolation,
   Upload,
   UploadedObject,
   User,
   Webhook,
   __getRuntime,
   __requestALS,
+  __resetDefaultAuth,
+  __resetLifecycleHooks,
   __resetRegisteredControllers,
+  __runStartHooks,
   __runWithRuntime,
   __setRuntime,
+  assertZeroArgConstructor,
   bigint,
   boolean,
   buildModuleClients,
   dec,
   defineChannels,
+  defineDefaultAuth,
   defineError,
   defineMiddleware,
   defineSchema,
@@ -3297,6 +3456,8 @@ var import_zod2 = require("zod");
   makeTypedDB,
   now,
   numeric,
+  onShutdown,
+  onStart,
   openai,
   ownerOnly,
   policy,