@palbase/backend 23.0.0 → 24.0.0

package/dist/index.cjs

@@ -57,26 +57,35 @@ __export(src_exports, {
   Req: () => Req,
   RequestId: () => RequestId,
   Secrets: () => Secrets,
+  Signal: () => Signal,
+  Sse: () => Sse,
+  SseOut: () => SseOut,
   Storage: () => Storage,
   TooManyRequests: () => TooManyRequests,
   TraceId: () => TraceId,
   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,
@@ -97,6 +106,8 @@ __export(src_exports, {
   makeTypedDB: () => makeTypedDB,
   now: () => now,
   numeric: () => numeric,
+  onShutdown: () => onShutdown,
+  onStart: () => onStart,
   openai: () => openai,
   ownerOnly: () => ownerOnly,
   policy: () => policy,
@@ -354,7 +365,20 @@ var TxPlanBuilder = class {
         }
         return this.push({ op: "insert", table: name, values: encoded }, `${name}.insert()`);
       },
-      insertMany: (rows) => {
+      upsert: (values, options) => {
+        const encoded = encodeMap(values, false);
+        if (Object.keys(encoded).length === 0) {
+          throw new TxPlanError(`${name}.upsert() needs at least one column`);
+        }
+        if (options.onConflict.length === 0) {
+          throw new TxPlanError(`${name}.upsert() needs at least one onConflict column`);
+        }
+        return this.push(
+          { op: "upsert", table: name, values: encoded, onConflict: options.onConflict },
+          `${name}.upsert()`
+        );
+      },
+      insertMany: (rows, opts) => {
         if (rows.length === 0) {
           return new TxRowsImpl(this, SKIPPED_OP, `${name}.insertMany()`);
         }
@@ -365,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);
@@ -542,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) {
@@ -564,10 +650,12 @@ function makeTablesAccessor(ops) {
           update: (id, data) => ops().update(name, id, data),
           delete: (id) => ops().delete(name, id),
           findById: (id) => ops().findById(name, id),
-          findMany: (query) => ops().findMany(name, query),
+          findMany: (query, opts) => ops().findMany(name, query, opts),
+          upsert: (data, opts) => ops().upsert(name, data, opts),
           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)
         };
       }
@@ -584,13 +672,21 @@ function makeTypedSurface(raw2) {
     update: (table, id, data) => raw2.update(table, id, data),
     delete: (table, id) => raw2.delete(table, id),
     findById: (table, id) => raw2.findById(table, id),
-    findMany: (table, query) => raw2.findMany(table, query),
+    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, {
+    // 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: (fn) => raw2.attempt(fn),
     tables: makeTablesAccessor(() => reco),
     transaction(fn) {
       const builder = new TxPlanBuilder();
@@ -1573,6 +1669,9 @@ function buildModuleClients(cfg) {
 }
 
 // src/db/policy.ts
+function quote(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
 var PolicyBuilder = class {
   _def;
   constructor(name) {
@@ -1608,6 +1707,41 @@ var PolicyBuilder = class {
     this._def.using = sqlExpr;
     return this;
   }
+  /**
+   * "Rows of THIS table whose owner the caller is a member of" — the membership
+   * pattern, written so it cannot recurse.
+   *
+   * THE TRAP IT EXISTS FOR. Written by hand, membership policies point at each
+   * other: `channels` is visible to members, so its policy reads
+   * `channel_members`; `channel_members` is visible to members, so its policy
+   * reads `channels`. Postgres refuses the pair at query time with `infinite
+   * recursion detected in policy for relation ...`, and the error names the
+   * relation but not the cycle. The way out is asymmetry — the MEMBERSHIP table
+   * is protected by `user_id = auth.uid()` and nothing else, and every other
+   * table subqueries INTO it. That shape was in the platform's own schema and
+   * written down nowhere; a customer recovered it by reading that schema.
+   *
+   * `(select auth.uid())` rather than a bare call: the scalar subquery is
+   * evaluated ONCE per statement instead of per row.
+   *
+   * @example
+   * // channels: visible to members. The membership table gets the simple one.
+   * policy("member_read").for("select").to("authenticated")
+   *   .memberOf("channel_members", "channel_id")
+   * // → id IN (SELECT "channel_id" FROM "channel_members"
+   * //          WHERE "user_id" = (select auth.uid()))
+   */
+  memberOf(membershipTable, foreignKey, options = {}) {
+    if (this._def.using !== null) {
+      throw new Error(
+        `policy(${this._def.name}).memberOf(): this policy already has a using() expression. Write one or the other \u2014 memberOf IS the using expression.`
+      );
+    }
+    const column = options.column ?? "id";
+    const userColumn = options.userColumn ?? "user_id";
+    this._def.using = `${quote(column)} IN (SELECT ${quote(foreignKey)} FROM ${quote(membershipTable)} WHERE ${quote(userColumn)} = (select auth.uid()))`;
+    return this;
+  }
   /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
   withCheck(sqlExpr) {
     this._def.withCheck = sqlExpr;
@@ -2033,6 +2167,21 @@ var ColumnBuilder = class _ColumnBuilder {
     this._def.defaultNow = true;
     return new _ColumnBuilder(this._def.type, this._def);
   }
+  /**
+   * The DATABASE assigns this column's value — a trigger, a rule, an identity.
+   *
+   * The column becomes optional on INSERT (the author has nothing to send) while
+   * the DDL stays free of a DEFAULT this schema would not honour. It is NOT
+   * `default()`: that declares a value the schema promises to write.
+   *
+   * Naming: deliberately not `generated()`. Postgres has GENERATED columns and
+   * they are a different thing; borrowing the word would send a reader — or a
+   * model writing a schema — to the wrong feature.
+   */
+  dbAssigned() {
+    this._def.dbAssigned = true;
+    return new _ColumnBuilder(this._def.type, this._def);
+  }
   /** Add a foreign key reference. */
   /**
    * Declares that this column used to be called `previous`.
@@ -2115,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");
@@ -2180,10 +2351,18 @@ var openai = {
 function makeTypedTable(name, raw2) {
   return {
     insert: (data) => raw2.insert(name, data),
+    upsert: (data, opts) => raw2.upsert(name, data, opts),
     update: (id, data) => raw2.update(name, id, data),
     delete: (id) => raw2.delete(name, id),
     findById: (id) => raw2.findById(name, id),
-    findMany: (query) => raw2.findMany(name, query)
+    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) {
@@ -2505,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);
@@ -2546,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) {
@@ -2648,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) {
@@ -2666,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";
   }
 };
@@ -2709,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"),
@@ -2750,6 +2949,29 @@ function validateUploadConfigShape(c) {
   }
 }
 
+// src/decorators/sse.ts
+function Sse(subpath = "", config) {
+  const { auth, rateLimit, ...sseConfig } = config;
+  const options = {
+    sseConfig,
+    ...auth !== void 0 ? { auth } : {},
+    ...rateLimit !== void 0 ? { rateLimit } : {}
+  };
+  return function(target, propertyKey) {
+    recordRoute(target, String(propertyKey), "POST", subpath, options);
+  };
+}
+function SseOut() {
+  return function(target, propertyKey, parameterIndex) {
+    recordParam(target, String(propertyKey), { index: parameterIndex, kind: "sseOut" });
+  };
+}
+function Signal() {
+  return function(target, propertyKey, parameterIndex) {
+    recordParam(target, String(propertyKey), { index: parameterIndex, kind: "signal" });
+  };
+}
+
 // src/decorators/params.ts
 function makeParamDecorator(kind, extra) {
   return function(target, propertyKey, parameterIndex) {
@@ -2878,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);
@@ -2905,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];
@@ -3107,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");
@@ -3156,26 +3407,35 @@ var import_zod2 = require("zod");
   Req,
   RequestId,
   Secrets,
+  Signal,
+  Sse,
+  SseOut,
   Storage,
   TooManyRequests,
   TraceId,
   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,
@@ -3196,6 +3456,8 @@ var import_zod2 = require("zod");
   makeTypedDB,
   now,
   numeric,
+  onShutdown,
+  onStart,
   openai,
   ownerOnly,
   policy,