@palbase/backend 6.0.0 → 8.0.0

package/dist/index.cjs

@@ -52,6 +52,7 @@ __export(src_exports, {
   Query: () => Query,
   Queue: () => Queue,
   RESERVED_SECRET_PREFIX: () => RESERVED_SECRET_PREFIX,
+  Realtime: () => Realtime,
   Req: () => Req,
   RequestId: () => RequestId,
   Resource: () => Resource,
@@ -72,6 +73,7 @@ __export(src_exports, {
   boolean: () => boolean,
   bucket: () => bucket,
   buildProvider: () => buildProvider,
+  defineError: () => defineError,
   defineFlags: () => defineFlags,
   defineJob: () => defineJob,
   defineMiddleware: () => defineMiddleware,
@@ -83,6 +85,7 @@ __export(src_exports, {
   documents: () => documents,
   enumType: () => enumType,
   flag: () => flag,
+  getErrorRegistry: () => getErrorRegistry,
   integer: () => integer,
   isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
@@ -90,12 +93,13 @@ __export(src_exports, {
   makeTypedDB: () => makeTypedDB,
   parseFileSizeLimit: () => parseFileSizeLimit,
   policy: () => policy,
+  recordThrows: () => recordThrows,
   reservedSecretKey: () => reservedSecretKey,
   storage: () => storage,
   text: () => text,
   timestamp: () => timestamp,
   uuid: () => uuid,
-  z: () => import_zod.z
+  z: () => import_zod2.z
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -211,6 +215,7 @@ var Flags = Object.assign(
     }
   }
 );
+var Realtime = makeServiceProxy("Realtime");
 
 // src/db/policy.ts
 var PolicyBuilder = class {
@@ -800,6 +805,7 @@ function Controller(basePath, options = {}) {
 var ROUTES = /* @__PURE__ */ Symbol.for("palbase.backend.routes");
 var PARAM_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.paramBuffer");
 var RETURN_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.returnBuffer");
+var THROWS_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.throwsBuffer");
 function carrierOf(target) {
   const ctor = typeof target === "function" ? target : target.constructor ?? target;
   return ctor;
@@ -826,6 +832,10 @@ function recordRoute(target, fnName, method, subpath, options) {
   if (returnBuffer && returnBuffer[fnName] !== void 0) {
     route.returnSchema = returnBuffer[fnName];
   }
+  const throwsBuffer = carrier[THROWS_BUFFER];
+  if (throwsBuffer && throwsBuffer[fnName] !== void 0) {
+    route.throws = throwsBuffer[fnName];
+  }
   routes.push(route);
 }
 function recordParam(target, fnName, meta) {
@@ -841,6 +851,20 @@ function recordParam(target, fnName, meta) {
     }
   }
 }
+function recordThrows(target, fnName, throws) {
+  const carrier = carrierOf(target);
+  const routes = carrier[ROUTES];
+  const route = routes?.find((r) => r.fnName === fnName);
+  if (route) {
+    route.throws = throws;
+    return;
+  }
+  if (!Object.prototype.hasOwnProperty.call(carrier, THROWS_BUFFER)) {
+    carrier[THROWS_BUFFER] = {};
+  }
+  const throwsBuffer = carrier[THROWS_BUFFER];
+  if (throwsBuffer) throwsBuffer[fnName] = throws;
+}
 
 // src/decorators/methods.ts
 function makeMethodDecorator(method) {
@@ -957,8 +981,8 @@ function defaultMessage(name) {
   return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
 }
 var BadRequest = class extends NamedHttpError {
-  constructor(message, code, data) {
-    super(400, "bad_request", "BadRequest", message, code, data);
+  constructor(data, message) {
+    super(400, "bad_request", "BadRequest", message, void 0, data);
   }
 };
 var Unauthorized = class extends NamedHttpError {
@@ -982,11 +1006,115 @@ var Conflict = class extends NamedHttpError {
   }
 };
 var TooManyRequests = class extends NamedHttpError {
-  constructor(message, code, data) {
-    super(429, "too_many_requests", "TooManyRequests", message, code, data);
+  constructor(data, message) {
+    super(429, "too_many_requests", "TooManyRequests", message, void 0, data);
   }
 };
 
+// src/error-registry.ts
+var import_zod_to_openapi = require("@asteasolutions/zod-to-openapi");
+var import_zod = require("zod");
+(0, import_zod_to_openapi.extendZodWithOpenApi)(import_zod.z);
+var ERROR_REGISTRY = /* @__PURE__ */ Symbol.for("palbase.backend.errorRegistry");
+var BUILTIN_DATA_SCHEMAS = {
+  bad_request: import_zod.z.object({
+    fields: import_zod.z.array(import_zod.z.object({ field: import_zod.z.string(), message: import_zod.z.string() }))
+  }),
+  too_many_requests: import_zod.z.object({ retryAfter: import_zod.z.number().int() })
+};
+function getErrorRegistry() {
+  const g = globalThis;
+  if (!g[ERROR_REGISTRY]) {
+    const m = /* @__PURE__ */ new Map();
+    for (const [code, status, className] of [
+      ["bad_request", 400, "BadRequest"],
+      ["unauthorized", 401, "Unauthorized"],
+      ["forbidden", 403, "Forbidden"],
+      ["not_found", 404, "NotFound"],
+      ["conflict", 409, "Conflict"],
+      ["too_many_requests", 429, "TooManyRequests"]
+    ]) {
+      const dataSchema = BUILTIN_DATA_SCHEMAS[code];
+      m.set(code, {
+        code,
+        status,
+        className,
+        builtin: true,
+        ...dataSchema ? { dataSchema, dataDigest: digestOf(code, dataSchema) } : {}
+      });
+    }
+    g[ERROR_REGISTRY] = m;
+  }
+  return g[ERROR_REGISTRY];
+}
+function defineError(code, status, dataSchema) {
+  if (!Number.isInteger(status) || status < 400 || status > 599) {
+    throw new Error(
+      `defineError: status for "${code}" must be a 4xx/5xx integer, got ${status} \u2014 error responses must not clobber success responses in the project spec.`
+    );
+  }
+  const registry2 = getErrorRegistry();
+  const existing = registry2.get(code);
+  const className = defaultClassName(code);
+  const dataDigest = dataSchema ? digestOf(code, dataSchema) : void 0;
+  if (existing) {
+    const sameShape = existing.status === status && !existing.builtin && existing.dataDigest === dataDigest;
+    if (!sameShape) {
+      throw new Error(
+        `defineError: duplicate error code "${code}" with a different shape (existing: status ${existing.status}${existing.builtin ? ", built-in" : ""}${existing.status === status && !existing.builtin ? ", different data schema" : ""}). Error codes are project-unique.`
+      );
+    }
+  }
+  const makeWithData = (schema) => class extends HttpError {
+    static code = code;
+    static status = status;
+    constructor(data, message) {
+      super(status, code, message ?? humanize(code), schema.parse(data));
+      this.name = className;
+    }
+  };
+  const makeWithoutData = () => class extends HttpError {
+    static code = code;
+    static status = status;
+    constructor(message) {
+      super(status, code, message ?? humanize(code));
+      this.name = className;
+    }
+  };
+  const cls = dataSchema ? makeWithData(dataSchema) : makeWithoutData();
+  Object.defineProperty(cls, "name", { value: className });
+  registry2.set(code, {
+    code,
+    status,
+    className,
+    builtin: false,
+    ...dataSchema ? { dataSchema } : {},
+    ...dataDigest !== void 0 ? { dataDigest } : {}
+  });
+  return cls;
+}
+function digestOf(code, dataSchema) {
+  const TMP_REF = "__PalbaseErrorDataDigest";
+  const tmpRegistry = new import_zod_to_openapi.OpenAPIRegistry();
+  tmpRegistry.register(TMP_REF, import_zod.z.object({ data: dataSchema }).openapi(TMP_REF));
+  const generated = new import_zod_to_openapi.OpenApiGeneratorV31(tmpRegistry.definitions).generateComponents();
+  const out = generated.components?.schemas?.[TMP_REF];
+  const digest = JSON.stringify(out ?? null);
+  if (digest.includes('"$ref"')) {
+    throw new Error(
+      `defineError: dataSchema for "${code}" carries .openapi(refId) metadata \u2014 it would emit dangling $ref pointers in the project spec. Use a plain zod schema (z.object({...})) without .openapi(...).`
+    );
+  }
+  return digest;
+}
+function defaultClassName(code) {
+  return code.split("_").map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+}
+function humanize(code) {
+  const s = code.replace(/_/g, " ");
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
 // src/worker.ts
 var VALID_WORKER_NAME = /^[a-zA-Z0-9_-]+$/;
 var WORKER_DEFAULTS = {
@@ -1285,7 +1413,7 @@ var documents = {
 };
 
 // src/index.ts
-var import_zod = require("zod");
+var import_zod2 = require("zod");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BadRequest,
@@ -1320,6 +1448,7 @@ var import_zod = require("zod");
   Query,
   Queue,
   RESERVED_SECRET_PREFIX,
+  Realtime,
   Req,
   RequestId,
   Resource,
@@ -1340,6 +1469,7 @@ var import_zod = require("zod");
   boolean,
   bucket,
   buildProvider,
+  defineError,
   defineFlags,
   defineJob,
   defineMiddleware,
@@ -1351,6 +1481,7 @@ var import_zod = require("zod");
   documents,
   enumType,
   flag,
+  getErrorRegistry,
   integer,
   isPalbaseExtension,
   jsonb,
@@ -1358,6 +1489,7 @@ var import_zod = require("zod");
   makeTypedDB,
   parseFileSizeLimit,
   policy,
+  recordThrows,
   reservedSecretKey,
   storage,
   text,