@palbase/backend 3.0.0 → 4.0.0

package/dist/index.cjs

@@ -20,16 +20,43 @@ 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,
@@ -39,8 +66,6 @@ __export(src_exports, {
   __shutdownResources: () => __shutdownResources,
   auth: () => auth,
   boolean: () => boolean,
-  defineController: () => defineController,
-  defineHandler: () => defineHandler,
   defineJob: () => defineJob,
   defineMiddleware: () => defineMiddleware,
   defineSchema: () => defineSchema,
@@ -49,10 +74,11 @@ __export(src_exports, {
   documents: () => documents,
   enumType: () => enumType,
   integer: () => integer,
+  isPalbaseExtension: () => isPalbaseExtension,
   jsonb: () => jsonb,
   makeEnvDts: () => makeEnvDts,
   makeTypedDB: () => makeTypedDB,
-  route: () => route,
+  policy: () => policy,
   storage: () => storage,
   text: () => text,
   timestamp: () => timestamp,
@@ -111,27 +137,34 @@ function makeTablesAccessor(ops) {
   return tablesProxy;
 }
 var rawDatabase = makeServiceProxy("Database");
-var Database = Object.assign(
-  // Spread the raw ops onto a fresh object so the added `tables`/typed
-  // `transaction` members live alongside them. Each op still forwards through
-  // the request-scoped runtime Proxy.
-  {
-    query: (sql, params) => rawDatabase.query(sql, params),
-    insert: (table, data) => rawDatabase.insert(table, data),
-    update: (table, id, data) => rawDatabase.update(table, id, data),
-    delete: (table, id) => rawDatabase.delete(table, id),
-    findById: (table, id) => rawDatabase.findById(table, id),
-    findMany: (table, query) => rawDatabase.findMany(table, query)
-  },
-  {
-    tables: makeTablesAccessor(() => rawDatabase),
+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 rawDatabase.transaction(
-        (rawTx) => fn({ tables: makeTablesAccessor(() => rawTx) })
-      );
+      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");
@@ -140,13 +173,118 @@ var Log = makeServiceProxy("Log");
 var Notifications = makeServiceProxy("Notifications");
 var Flags = makeServiceProxy("Flags");
 
+// 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 toPolicyDef(p) {
+  return p instanceof PolicyBuilder ? p._def : p;
+}
 function defineSchema(input) {
   const tables = {};
   for (const name of Object.keys(input.tables)) {
-    tables[name] = { name, columns: input.tables[name] };
+    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
+    };
   }
-  return { tables };
+  const extensions = [...new Set(input.extensions ?? [])];
+  return { tables, extensions };
+}
+
+// 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
@@ -322,26 +460,145 @@ export {};
 `;
 }
 
-// src/handler.ts
-function defineHandler(config) {
-  return { __palbase: "handler", ...config };
+// 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/controller.ts
-function makeRoute(method) {
-  return function(path, handler) {
-    return { __palbase: "route", method, path, handler };
+// 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 route = {
-  get: makeRoute("GET"),
-  post: makeRoute("POST"),
-  put: makeRoute("PUT"),
-  patch: makeRoute("PATCH"),
-  delete: makeRoute("DELETE")
-};
-function defineController(basePath, routes) {
-  return { __palbase: "controller", basePath, routes };
+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
@@ -386,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_-]+$/;
@@ -688,16 +991,43 @@ 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,
@@ -707,8 +1037,6 @@ var import_zod = require("zod");
   __shutdownResources,
   auth,
   boolean,
-  defineController,
-  defineHandler,
   defineJob,
   defineMiddleware,
   defineSchema,
@@ -717,10 +1045,11 @@ var import_zod = require("zod");
   documents,
   enumType,
   integer,
+  isPalbaseExtension,
   jsonb,
   makeEnvDts,
   makeTypedDB,
-  route,
+  policy,
   storage,
   text,
   timestamp,