@palbase/backend 2.0.2 → 4.0.0

package/dist/index.cjs

@@ -20,22 +20,52 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  BadRequest: () => BadRequest,
+  Body: () => Body,
   Cache: () => Cache,
+  Client: () => Client,
+  Conflict: () => Conflict,
+  Controller: () => Controller,
   Database: () => Database,
+  Delete: () => Delete,
   Documents: () => Documents,
+  EXTENSION_DEPENDENCIES: () => EXTENSION_DEPENDENCIES,
   Flags: () => Flags,
+  Forbidden: () => Forbidden,
+  Get: () => Get,
+  Headers: () => Headers,
   HttpError: () => HttpError,
   Log: () => Log,
+  NotFound: () => NotFound,
   Notifications: () => Notifications,
+  OptionalUser: () => OptionalUser,
+  PALBASE_EXTENSIONS: () => PALBASE_EXTENSIONS,
+  PalError: () => PalError,
+  Param: () => Param,
+  Patch: () => Patch,
+  PolicyBuilder: () => PolicyBuilder,
+  Post: () => Post,
+  Put: () => Put,
+  Query: () => Query,
   Queue: () => Queue,
+  Req: () => Req,
+  RequestId: () => RequestId,
+  Resource: () => Resource,
+  Returns: () => Returns,
   Storage: () => Storage,
+  TooManyRequests: () => TooManyRequests,
+  TraceId: () => TraceId,
+  Unauthorized: () => Unauthorized,
+  User: () => User,
   __getRuntime: () => __getRuntime,
+  __registerResource: () => __registerResource,
   __requestALS: () => __requestALS,
+  __runResourceBoot: () => __runResourceBoot,
   __runWithRuntime: () => __runWithRuntime,
   __setRuntime: () => __setRuntime,
+  __shutdownResources: () => __shutdownResources,
   auth: () => auth,
   boolean: () => boolean,
-  defineEndpoint: () => defineEndpoint,
   defineJob: () => defineJob,
   defineMiddleware: () => defineMiddleware,
   defineSchema: () => defineSchema,
@@ -44,55 +74,21 @@ __export(src_exports, {
   documents: () => documents,
   enumType: () => enumType,
   integer: () => integer,
+  isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
+  makeEnvDts: () => makeEnvDts,
   makeTypedDB: () => makeTypedDB,
+  policy: () => policy,
   storage: () => storage,
-  table: () => table,
   text: () => text,
   timestamp: () => timestamp,
-  typedDatabase: () => typedDatabase,
   uuid: () => uuid,
   z: () => import_zod.z
 });
 module.exports = __toCommonJS(src_exports);
 
-// src/endpoint.ts
-function defineEndpoint(config) {
-  return config;
-}
-
 // src/runtime.ts
 var import_node_async_hooks = require("async_hooks");
-
-// src/db/typed-db.ts
-function makeTypedTable(name, raw) {
-  return {
-    insert: (data) => raw.insert(name, data),
-    update: (id, data) => raw.update(name, id, data),
-    delete: (id) => raw.delete(name, id),
-    findById: (id) => raw.findById(name, id),
-    findMany: (query) => raw.findMany(name, query)
-  };
-}
-function makeTypedDB(schema, raw) {
-  function buildTables(client) {
-    const tables = {};
-    for (const key of Object.keys(schema.tables)) {
-      const tableDef = schema.tables[key];
-      if (tableDef !== void 0) {
-        tables[key] = makeTypedTable(tableDef.name, client);
-      }
-    }
-    return tables;
-  }
-  const result = {
-    tables: buildTables(raw),
-    transaction: (fn) => raw.transaction((rawTx) => fn({ tables: buildTables(rawTx) }))
-  };
-  return result;
-}
-
-// src/runtime.ts
 var __requestALS = new import_node_async_hooks.AsyncLocalStorage();
 var runtime = null;
 function __setRuntime(services) {
@@ -121,7 +117,54 @@ function makeServiceProxy(key) {
   };
   return new Proxy({}, handler);
 }
-var Database = makeServiceProxy("Database");
+function makeTablesAccessor(ops) {
+  const tablesProxy = new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop !== "string") return void 0;
+        const name = prop;
+        return {
+          insert: (data) => ops().insert(name, data),
+          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)
+        };
+      }
+    }
+  );
+  return tablesProxy;
+}
+var rawDatabase = makeServiceProxy("Database");
+function makeTypedSurface(raw) {
+  const ops = {
+    query: (sql, params) => raw.query(sql, params),
+    insert: (table, data) => raw.insert(table, data),
+    update: (table, id, data) => raw.update(table, id, data),
+    delete: (table, id) => raw.delete(table, id),
+    findById: (table, id) => raw.findById(table, id),
+    findMany: (table, query) => raw.findMany(table, query)
+  };
+  return Object.assign(ops, {
+    tables: makeTablesAccessor(() => raw),
+    transaction(fn) {
+      return raw.transaction((rawTx) => fn({ tables: makeTablesAccessor(() => rawTx) }));
+    }
+  });
+}
+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");
 var Storage = makeServiceProxy("Storage");
 var Cache = makeServiceProxy("Cache");
@@ -129,26 +172,119 @@ var Queue = makeServiceProxy("Queue");
 var Log = makeServiceProxy("Log");
 var Notifications = makeServiceProxy("Notifications");
 var Flags = makeServiceProxy("Flags");
-function typedDatabase(schema) {
-  const typed = makeTypedDB(schema, Database);
-  const rawOps = {
-    query: (sql, params) => Database.query(sql, params),
-    insert: (table2, data) => Database.insert(table2, data),
-    update: (table2, id, data) => Database.update(table2, id, data),
-    delete: (table2, id) => Database.delete(table2, id),
-    findById: (table2, id) => Database.findById(table2, id),
-    findMany: (table2, q) => Database.findMany(table2, q),
-    transaction: (fn) => Database.transaction(fn)
-  };
-  return Object.assign(rawOps, typed);
+
+// src/db/policy.ts
+var PolicyBuilder = class {
+  _def;
+  constructor(name) {
+    this._def = {
+      name,
+      command: "all",
+      roles: ["authenticated"],
+      using: null,
+      withCheck: null,
+      permissive: true
+    };
+  }
+  /** Restrict the policy to a single SQL command (default `"all"`). */
+  for(command) {
+    this._def.command = command;
+    return this;
+  }
+  /**
+   * Set the DB roles the policy applies to (the `TO` clause), replacing any
+   * previously-set roles. Call with no arguments to target PUBLIC (all roles).
+   *
+   * @example
+   * policy("p").to("authenticated")
+   * policy("p").to("authenticated", "service_role")
+   * policy("p").to() // PUBLIC
+   */
+  to(...roles) {
+    this._def.roles = roles;
+    return this;
+  }
+  /** Set the `USING (...)` row-visibility expression (raw SQL). */
+  using(sqlExpr) {
+    this._def.using = sqlExpr;
+    return this;
+  }
+  /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
+  withCheck(sqlExpr) {
+    this._def.withCheck = sqlExpr;
+    return this;
+  }
+  /** Set the policy mode: `"permissive"` (default, OR-combined) or
+   * `"restrictive"` (AND-combined). */
+  as(mode) {
+    this._def.permissive = mode === "permissive";
+    return this;
+  }
+};
+function policy(name) {
+  return new PolicyBuilder(name);
 }
 
 // src/db/schema.ts
-function table(name, columns) {
-  return { name, columns };
+function toPolicyDef(p) {
+  return p instanceof PolicyBuilder ? p._def : p;
+}
+function defineSchema(input) {
+  const tables = {};
+  for (const name of Object.keys(input.tables)) {
+    const table = input.tables[name];
+    if (table === void 0) continue;
+    const policies = (table.policies ?? []).map(toPolicyDef);
+    const rls = table.rls === true || policies.length > 0;
+    tables[name] = {
+      name,
+      columns: table.columns,
+      rls,
+      policies
+    };
+  }
+  const extensions = [...new Set(input.extensions ?? [])];
+  return { tables, extensions };
 }
-function defineSchema(tables) {
-  return { tables };
+
+// src/db/extensions.ts
+var PALBASE_EXTENSIONS = [
+  // Search & text
+  "vector",
+  // pgvector: AI embeddings + vector similarity search (semantic search / RAG).
+  // NB: the Postgres extension is named "vector", not "pgvector" — declare "vector".
+  "pg_trgm",
+  // trigram fuzzy / typo-tolerant text search
+  "unaccent",
+  // accent-insensitive text search
+  "citext",
+  // case-insensitive text type
+  // Geospatial / location
+  "postgis",
+  // geospatial types + queries (maps, "near me")
+  "cube",
+  // multi-dimensional cubes (dependency of earthdistance)
+  "earthdistance",
+  // great-circle distance (needs cube)
+  // Data types & structures
+  "hstore",
+  // key/value pairs in a single column
+  "ltree",
+  // hierarchical tree-structured labels
+  // Scheduling
+  "pg_cron",
+  // schedule jobs inside the database
+  // Crypto / ids (also installed by default; listable for explicitness)
+  "pgcrypto",
+  // cryptographic functions (hashing, encryption)
+  "uuid-ossp"
+  // UUID generation functions
+];
+var EXTENSION_DEPENDENCIES = {
+  earthdistance: ["cube"]
+};
+function isPalbaseExtension(name) {
+  return PALBASE_EXTENSIONS.includes(name);
 }
 
 // src/db/columns.ts
@@ -192,8 +328,8 @@ var ColumnBuilder = class _ColumnBuilder {
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /** Add a foreign key reference. */
-  references(table2, column) {
-    this._def.references = { table: table2, column };
+  references(table, column) {
+    this._def.references = { table, column };
     return new _ColumnBuilder(this._def.type, this._def);
   }
   /** Set the ON DELETE action for a foreign key reference. */
@@ -227,6 +363,244 @@ function enumType(name, values) {
   return builder;
 }
 
+// src/db/typed-db.ts
+function makeTypedTable(name, raw) {
+  return {
+    insert: (data) => raw.insert(name, data),
+    update: (id, data) => raw.update(name, id, data),
+    delete: (id) => raw.delete(name, id),
+    findById: (id) => raw.findById(name, id),
+    findMany: (query) => raw.findMany(name, query)
+  };
+}
+function makeTypedDB(schema, raw) {
+  function buildTables(client) {
+    const tables = {};
+    for (const key of Object.keys(schema.tables)) {
+      const tableDef = schema.tables[key];
+      if (tableDef !== void 0) {
+        tables[key] = makeTypedTable(tableDef.name, client);
+      }
+    }
+    return tables;
+  }
+  const result = {
+    tables: buildTables(raw),
+    transaction: (fn) => raw.transaction((rawTx) => fn({ tables: buildTables(rawTx) }))
+  };
+  return result;
+}
+
+// src/db/env-gen.ts
+function baseTsType(def) {
+  switch (def.type) {
+    case "uuid":
+    case "text":
+    case "timestamp":
+      return "string";
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "jsonb":
+      return "unknown";
+    case "enum": {
+      const values = def.enumValues ?? [];
+      if (values.length === 0) return "string";
+      return values.map((v) => JSON.stringify(v)).join(" | ");
+    }
+    default:
+      return "unknown";
+  }
+}
+function rowType(def) {
+  const base = baseTsType(def);
+  return def.nullable ? `${base} | null` : base;
+}
+function optionalOnInsert(def) {
+  return def.nullable === true || def.defaultRandom === true || def.defaultNow === true || def.defaultValue !== void 0;
+}
+function tableBlock(table, indent) {
+  const cols = Object.entries(table.columns);
+  const rowLines = cols.map(([col, builder]) => {
+    return `${indent}    ${col}: ${rowType(builder._def)};`;
+  });
+  const insertLines = cols.map(([col, builder]) => {
+    const def = builder._def;
+    const opt = optionalOnInsert(def) ? "?" : "";
+    return `${indent}    ${col}${opt}: ${rowType(def)};`;
+  });
+  return [
+    `${indent}${table.name}: {`,
+    `${indent}  row: {`,
+    ...rowLines,
+    `${indent}  };`,
+    `${indent}  insert: {`,
+    ...insertLines,
+    `${indent}  };`,
+    `${indent}};`
+  ].join("\n");
+}
+function makeEnvDts(schema) {
+  const tableNames = Object.keys(schema.tables);
+  const blocks = tableNames.map((name) => tableBlock(schema.tables[name], "    "));
+  const body = blocks.length > 0 ? `
+${blocks.join("\n")}
+  ` : "";
+  return `// AUTO-GENERATED by @palbase/backend \u2014 DO NOT EDIT.
+// Regenerated from db/schema.ts on every \`palbase serve\` / deploy.
+// Augments the @palbase/backend/env \`Tables\` interface so \`Database.tables.*\`
+// is typed with no import and no generic.
+
+declare module "@palbase/backend/env" {
+  interface Tables {${body}}
+}
+
+export {};
+`;
+}
+
+// src/decorators/controller.ts
+var CONTROLLER_META = /* @__PURE__ */ Symbol.for("palbase.backend.controllerMeta");
+function Controller(basePath, options = {}) {
+  return function(ctor) {
+    const carrier = ctor;
+    const meta = {
+      __palbase: "controller",
+      basePath,
+      ...options.auth !== void 0 ? { defaultAuth: options.auth } : {}
+    };
+    Object.defineProperty(carrier, CONTROLLER_META, {
+      value: meta,
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+    Object.defineProperty(carrier, "__palbase", {
+      value: "controller",
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+    return ctor;
+  };
+}
+
+// src/decorators/registry.ts
+var ROUTES = /* @__PURE__ */ Symbol.for("palbase.backend.routes");
+var PARAM_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.paramBuffer");
+function carrierOf(target) {
+  const ctor = typeof target === "function" ? target : target.constructor ?? target;
+  return ctor;
+}
+function ownRoutes(carrier) {
+  if (!Object.prototype.hasOwnProperty.call(carrier, ROUTES)) {
+    carrier[ROUTES] = [];
+  }
+  return carrier[ROUTES];
+}
+function ownParamBuffer(carrier) {
+  if (!Object.prototype.hasOwnProperty.call(carrier, PARAM_BUFFER)) {
+    carrier[PARAM_BUFFER] = {};
+  }
+  return carrier[PARAM_BUFFER];
+}
+function recordRoute(target, fnName, method, subpath, options) {
+  const carrier = carrierOf(target);
+  const routes = ownRoutes(carrier);
+  const buffer = ownParamBuffer(carrier);
+  const params = (buffer[fnName] ?? []).slice().sort((a, b) => a.index - b.index);
+  routes.push({ method, subpath, fnName, options, params });
+}
+function recordParam(target, fnName, meta) {
+  const carrier = carrierOf(target);
+  const buffer = ownParamBuffer(carrier);
+  (buffer[fnName] ??= []).push(meta);
+  const routes = carrier[ROUTES];
+  if (routes) {
+    const route = routes.find((r) => r.fnName === fnName);
+    if (route) {
+      route.params.push(meta);
+      route.params.sort((a, b) => a.index - b.index);
+    }
+  }
+}
+var RETURN_BUFFER = /* @__PURE__ */ Symbol.for("palbase.backend.returnBuffer");
+function recordReturn(target, fnName, schema) {
+  const carrier = carrierOf(target);
+  const routes = carrier[ROUTES];
+  const route = routes?.find((r) => r.fnName === fnName);
+  if (route) {
+    route.returnSchema = schema;
+    return;
+  }
+  if (!Object.prototype.hasOwnProperty.call(carrier, RETURN_BUFFER)) {
+    carrier[RETURN_BUFFER] = {};
+  }
+  carrier[RETURN_BUFFER][fnName] = schema;
+}
+
+// src/decorators/methods.ts
+function makeMethodDecorator(method) {
+  return function(subpath, options = {}) {
+    return function(target, propertyKey) {
+      recordRoute(target, String(propertyKey), method, subpath, options);
+    };
+  };
+}
+var Get = makeMethodDecorator("GET");
+var Post = makeMethodDecorator("POST");
+var Put = makeMethodDecorator("PUT");
+var Patch = makeMethodDecorator("PATCH");
+var Delete = makeMethodDecorator("DELETE");
+function Returns(schema) {
+  return function(target, propertyKey) {
+    recordReturn(target, String(propertyKey), schema);
+  };
+}
+
+// src/decorators/params.ts
+function makeParamDecorator(kind, extra) {
+  return function(target, propertyKey, parameterIndex) {
+    recordParam(target, String(propertyKey), {
+      index: parameterIndex,
+      kind,
+      ...extra?.schema !== void 0 ? { schema: extra.schema } : {},
+      ...extra?.name !== void 0 ? { name: extra.name } : {}
+    });
+  };
+}
+function Body(schema) {
+  return makeParamDecorator("body", { schema });
+}
+function Query(schema) {
+  return makeParamDecorator("query", { schema });
+}
+function Headers(schema) {
+  return makeParamDecorator("headers", schema !== void 0 ? { schema } : void 0);
+}
+function Param(name) {
+  return makeParamDecorator("param", { name });
+}
+function User() {
+  return makeParamDecorator("user");
+}
+function OptionalUser() {
+  return makeParamDecorator("optionalUser");
+}
+function Client() {
+  return makeParamDecorator("client");
+}
+function RequestId() {
+  return makeParamDecorator("requestId");
+}
+function TraceId() {
+  return makeParamDecorator("traceId");
+}
+function Req() {
+  return makeParamDecorator("req");
+}
+
 // src/middleware.ts
 function defineMiddleware(fn) {
   return fn;
@@ -269,6 +643,52 @@ var HttpError = class extends Error {
     return result;
   }
 };
+var PalError = class extends HttpError {
+  constructor(status, code, description, data) {
+    super(status, code, description, data);
+    this.name = "PalError";
+  }
+};
+var NamedHttpError = class extends HttpError {
+  constructor(status, defaultCode, name, message, code, data) {
+    super(status, code ?? defaultCode, message ?? defaultMessage(name), data);
+    this.name = name;
+  }
+};
+function defaultMessage(name) {
+  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+  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);
+  }
+};
+var Unauthorized = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(401, "unauthorized", "Unauthorized", message, code, data);
+  }
+};
+var Forbidden = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(403, "forbidden", "Forbidden", message, code, data);
+  }
+};
+var NotFound = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(404, "not_found", "NotFound", message, code, data);
+  }
+};
+var Conflict = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(409, "conflict", "Conflict", message, code, data);
+  }
+};
+var TooManyRequests = class extends NamedHttpError {
+  constructor(message, code, data) {
+    super(429, "too_many_requests", "TooManyRequests", message, code, data);
+  }
+};
 
 // src/worker.ts
 var VALID_WORKER_NAME = /^[a-zA-Z0-9_-]+$/;
@@ -486,6 +906,52 @@ function validateCustomWebhook(config) {
   };
 }
 
+// src/resource.ts
+var Resource = class {
+  /** The env-var names this resource needs. Optional; omit for none. */
+  static secrets;
+};
+function hasSecrets(value) {
+  if (typeof value !== "object" && typeof value !== "function") return false;
+  const secrets = value.secrets;
+  return secrets === void 0 || Array.isArray(secrets);
+}
+var registry = [];
+function __registerResource(resource) {
+  registry.push({ resource, booted: false });
+}
+function declaredSecrets(resource) {
+  const ctor = resource.constructor;
+  return hasSecrets(ctor) ? ctor.secrets ?? [] : [];
+}
+async function __runResourceBoot(envMap) {
+  for (const entry of registry) {
+    if (entry.booted) continue;
+    const secrets = declaredSecrets(entry.resource);
+    const env = {};
+    for (const name of secrets) {
+      const value = envMap[name];
+      if (value === void 0) {
+        throw new Error(
+          `Resource ${entry.resource.constructor.name} requires secret "${name}" but it is not set. Set it with \`palbase secret set ${name} ...\` (or in Studio) and redeploy.`
+        );
+      }
+      env[name] = value;
+    }
+    await entry.resource.init(env);
+    entry.booted = true;
+  }
+}
+async function __shutdownResources() {
+  for (let i = registry.length - 1; i >= 0; i -= 1) {
+    const entry = registry[i];
+    if (entry.booted && entry.resource.shutdown) {
+      await entry.resource.shutdown();
+    }
+  }
+  registry.length = 0;
+}
+
 // src/hooks.ts
 var auth = {
   onUserCreated(handler) {
@@ -525,22 +991,52 @@ var documents = {
 var import_zod = require("zod");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BadRequest,
+  Body,
   Cache,
+  Client,
+  Conflict,
+  Controller,
   Database,
+  Delete,
   Documents,
+  EXTENSION_DEPENDENCIES,
   Flags,
+  Forbidden,
+  Get,
+  Headers,
   HttpError,
   Log,
+  NotFound,
   Notifications,
+  OptionalUser,
+  PALBASE_EXTENSIONS,
+  PalError,
+  Param,
+  Patch,
+  PolicyBuilder,
+  Post,
+  Put,
+  Query,
   Queue,
+  Req,
+  RequestId,
+  Resource,
+  Returns,
   Storage,
+  TooManyRequests,
+  TraceId,
+  Unauthorized,
+  User,
   __getRuntime,
+  __registerResource,
   __requestALS,
+  __runResourceBoot,
   __runWithRuntime,
   __setRuntime,
+  __shutdownResources,
   auth,
   boolean,
-  defineEndpoint,
   defineJob,
   defineMiddleware,
   defineSchema,
@@ -549,13 +1045,14 @@ var import_zod = require("zod");
   documents,
   enumType,
   integer,
+  isPalbaseExtension,
   jsonb,
+  makeEnvDts,
   makeTypedDB,
+  policy,
   storage,
-  table,
   text,
   timestamp,
-  typedDatabase,
   uuid,
   z
 });