@palbase/backend 0.9.0 → 1.0.0

package/dist/chunk-7N5ICXCB.js

@@ -0,0 +1,88 @@
+// 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 runtime = null;
+function __setRuntime(services) {
+  runtime = services;
+}
+function __getRuntime() {
+  if (runtime === null) {
+    throw new Error(
+      "Palbase services accessed outside a request scope. The Database/Documents/\u2026 singletons are only available inside an endpoint handler (or after the runtime has called __setRuntime)."
+    );
+  }
+  return runtime;
+}
+function makeServiceProxy(key) {
+  const handler = {
+    get(_target, prop, receiver) {
+      const client = __getRuntime()[key];
+      const value = Reflect.get(client, prop, receiver);
+      return typeof value === "function" ? value.bind(client) : value;
+    }
+  };
+  return new Proxy({}, handler);
+}
+var Database = makeServiceProxy("Database");
+var Documents = makeServiceProxy("Documents");
+var Storage = makeServiceProxy("Storage");
+var Cache = makeServiceProxy("Cache");
+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: (table, data) => Database.insert(table, data),
+    update: (table, id, data) => Database.update(table, id, data),
+    delete: (table, id) => Database.delete(table, id),
+    findById: (table, id) => Database.findById(table, id),
+    findMany: (table, q) => Database.findMany(table, q),
+    transaction: (fn) => Database.transaction(fn)
+  };
+  return Object.assign(rawOps, typed);
+}
+
+export {
+  makeTypedDB,
+  __setRuntime,
+  __getRuntime,
+  Database,
+  Documents,
+  Storage,
+  Cache,
+  Queue,
+  Log,
+  Notifications,
+  Flags,
+  typedDatabase
+};
+//# sourceMappingURL=chunk-7N5ICXCB.js.map

package/dist/chunk-7N5ICXCB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/db/typed-db.ts","../src/runtime.ts"],"sourcesContent":["/**\n * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.\n *\n * Derives INSERT and full-row TypeScript types from a `defineSchema()` result\n * and wraps the untyped runtime `DBClient` with a typed facade.\n *\n * No value-any. No `as unknown as X`. The two narrow `as` casts in\n * `makeTypedTable` are safe because:\n *  - `data as Record<string, unknown>`: InsertShape<T> maps string keys to\n *    typed values; all value types are subsets of `unknown`, so the cast is\n *    structurally sound.\n *  - `result as RowShape<T>`: The runtime DBClient returns `Record<string,\n *    unknown>` which is the erased form of the typed row; we're narrowing back\n *    to the precise shape that the schema declared.\n * Both casts are narrowing only (not widening) and correctness is guaranteed\n * by the schema the caller provides.\n */\n\nimport type { ColValue, ColIsOptionalOnInsert, ColumnBuilder } from \"./columns.js\";\nimport type { TableDef, SchemaDef } from \"./schema.js\";\nimport type { DBClient, TxClient } from \"../endpoint.js\";\n\n// ---------------------------------------------------------------------------\n// Key discriminators — split a column map into required vs optional keys.\n// ---------------------------------------------------------------------------\n\n/** Keys of C whose columns are required on INSERT (not nullable, no default). */\ntype RequiredKeys<C> = {\n  [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? never : K;\n}[keyof C];\n\n/** Keys of C whose columns are optional on INSERT (nullable or has a default). */\ntype OptionalKeys<C> = {\n  [K in keyof C]: ColIsOptionalOnInsert<C[K]> extends true ? K : never;\n}[keyof C];\n\n// ---------------------------------------------------------------------------\n// Public shape types — exported so callers can reference them directly.\n// ---------------------------------------------------------------------------\n\n/**\n * The TypeScript type for an INSERT payload for table `T`.\n * - Required: columns that are NOT NULL and have no DB-level default.\n * - Optional: columns that are nullable or carry a default.\n *\n * When all columns are optional, `RequiredKeys<C>` resolves to `never` and\n * the first part becomes `{}`, which is a neutral element for `&`.\n */\nexport type InsertShape<T extends TableDef> = {\n  [K in RequiredKeys<T[\"columns\"]>]: ColValue<T[\"columns\"][K]>;\n} & {\n  [K in OptionalKeys<T[\"columns\"]>]?: ColValue<T[\"columns\"][K]>;\n};\n\n/**\n * The TypeScript type for a full row returned by the DB for table `T`.\n * Every column is present; nullable columns resolve to `T | null`.\n */\nexport type RowShape<T extends TableDef> = {\n  [K in keyof T[\"columns\"]]: ColValue<T[\"columns\"][K]>;\n};\n\n// ---------------------------------------------------------------------------\n// TypedTable + TypedDB interfaces.\n// ---------------------------------------------------------------------------\n\n/** A typed table accessor that mirrors the runtime DBClient surface. */\nexport interface TypedTable<T extends TableDef> {\n  insert(data: InsertShape<T>): Promise<RowShape<T>>;\n  update(id: string, data: Partial<InsertShape<T>>): Promise<RowShape<T>>;\n  delete(id: string): Promise<void>;\n  findById(id: string): Promise<RowShape<T> | null>;\n  findMany(query?: Partial<RowShape<T>>): Promise<RowShape<T>[]>;\n}\n\n/** A typed DB facade covering all tables declared in schema `S`. */\nexport interface TypedDB<S extends SchemaDef> {\n  tables: {\n    [K in keyof S[\"tables\"]]: TypedTable<S[\"tables\"][K]>;\n  };\n  transaction<T>(fn: (tx: TypedTx<S>) => Promise<T>): Promise<T>;\n}\n\n/** Transaction-scoped typed facade: same typed tables, no nested transaction. */\nexport interface TypedTx<S extends SchemaDef> {\n  tables: {\n    [K in keyof S[\"tables\"]]: TypedTable<S[\"tables\"][K]>;\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Runtime factory.\n// ---------------------------------------------------------------------------\n\n/**\n * Builds a typed table accessor that delegates every call to `raw` using the\n * runtime table name string. Two narrow `as` casts bridge the mapped-type\n * shapes to/from `Record<string, unknown>` — see module-level doc comment.\n *\n * The `raw` param is typed `TxClient` (the op surface shared by `DBClient` and\n * the transaction-scoped client) because this only ever calls the five\n * insert/update/delete/findById/findMany ops — never `transaction`. This lets\n * the same factory wrap both the top-level db and a tx without any cast.\n */\nfunction makeTypedTable<T extends TableDef<Record<string, ColumnBuilder>>>(\n  name: string,\n  raw: TxClient,\n): TypedTable<T> {\n  return {\n    insert: (data: InsertShape<T>) =>\n      raw.insert(name, data as Record<string, unknown>) as Promise<RowShape<T>>,\n\n    update: (id: string, data: Partial<InsertShape<T>>) =>\n      raw.update(name, id, data as Record<string, unknown>) as Promise<RowShape<T>>,\n\n    delete: (id: string) => raw.delete(name, id),\n\n    findById: (id: string) =>\n      raw.findById(name, id) as Promise<RowShape<T> | null>,\n\n    findMany: (query?: Partial<RowShape<T>>) =>\n      raw.findMany(name, query as Record<string, unknown> | undefined) as Promise<RowShape<T>[]>,\n  };\n}\n\n/**\n * Wraps a raw `DBClient` with the type-safe `TypedDB<S>` facade derived from\n * the provided schema. No behavior change — all calls delegate to `raw` with\n * the table name as a plain string.\n *\n * `buildTables` is the reusable factory that wraps any op-bearing client\n * (`TxClient` — the surface shared by `DBClient` and the transaction-scoped\n * client) into the typed tables map. It is used both for the top-level db\n * (wrapping `raw`) and inside `transaction`, where it wraps the raw `TxClient`\n * the runtime yields so the callback sees the same typed `.tables` API.\n *\n * `transaction` delegates straight to `raw.transaction`; the two narrow\n * `as TypedTx<S>` / `as TypedDB<S>` casts are single structural narrowings\n * from the dynamically-built tables object to the precise mapped type (TS\n * cannot infer through `Object.keys` iteration) — see module-level doc comment.\n */\nexport function makeTypedDB<S extends SchemaDef>(\n  schema: S,\n  raw: DBClient,\n): TypedDB<S> {\n  function buildTables(client: TxClient): Record<string, TypedTable<TableDef>> {\n    const tables = {} as Record<string, TypedTable<TableDef>>;\n    for (const key of Object.keys(schema.tables)) {\n      const tableDef = schema.tables[key];\n      if (tableDef !== undefined) {\n        tables[key] = makeTypedTable(tableDef.name, client);\n      }\n    }\n    return tables;\n  }\n\n  const result = {\n    tables: buildTables(raw),\n    transaction: <T>(fn: (tx: TypedTx<S>) => Promise<T>): Promise<T> =>\n      raw.transaction((rawTx) => fn({ tables: buildTables(rawTx) } as TypedTx<S>)),\n  };\n\n  // Narrow cast: `result.tables` is structurally identical to\n  // TypedDB<S>[\"tables\"] — each key maps to a TypedTable for the matching\n  // TableDef. TS cannot infer the mapped-type result through Object.keys\n  // iteration, so a single `as` bridges the gap.\n  return result as TypedDB<S>;\n}\n","/**\n * runtime.ts — request-scoped service singletons.\n *\n * The backend SDK no longer threads a `ctx` god-object through every handler.\n * Instead, endpoint authors import PascalCase service singletons directly:\n *\n *   import { Database, Documents, Cache } from \"@palbase/backend\";\n *\n *   export default defineEndpoint({\n *     method: \"POST\",\n *     handler: async (req) => {\n *       const row = await Database.insert(\"todos\", { title: req.input.title });\n *       return row;\n *     },\n *   });\n *\n * The singletons are thin Proxies. Every property access forwards to the live\n * client held in a per-process mutable slot, which the runtime sets with\n * {@link __setRuntime} BEFORE invoking the handler and (today) leaves in place\n * for the lifetime of that fresh Node subprocess. Because each `br-<ref>` pod\n * is single-tenant and every request runs in a fresh Node subprocess\n * (node_executor.go), there is no cross-tenant leakage risk.\n *\n * The seam that makes `import { Database } from \"@palbase/backend\"` resolve to\n * the runtime-injected client: `@palbase/backend` is marked esbuild-EXTERNAL\n * when the tenant bundle is built, and the package is installed globally in the\n * pod (NODE_PATH=/usr/local/lib/node_modules). So worker.js's\n * `require('@palbase/backend')` and the bundle's `import` resolve to ONE shared\n * module instance — calling `__setRuntime` on that instance is visible to the\n * singletons the bundle imported.\n */\n\nimport type {\n  DBClient,\n  CacheClient,\n  QueueClient,\n  Logger,\n  PalbaseDocsClient,\n} from \"./endpoint.js\";\nimport type {\n  PalbaseStorageClient,\n  PalbaseNotificationsClient,\n  PalbaseFlagsClient,\n} from \"./clients.js\";\nimport type { SchemaDef } from \"./db/schema.js\";\nimport type { TypedDB } from \"./db/typed-db.js\";\nimport { makeTypedDB } from \"./db/typed-db.js\";\n\n/** The set of live clients the runtime injects per request scope.\n *\n * EXCLUDED on purpose: Realtime, Functions, CMS, Links, Analytics, Auth. They\n * are not exposed as backend handler singletons (auth lives on the client SDK;\n * the rest are out of scope for backend endpoints). */\nexport interface RuntimeServices {\n  Database: DBClient;\n  Documents: PalbaseDocsClient;\n  Storage: PalbaseStorageClient;\n  Cache: CacheClient;\n  Queue: QueueClient;\n  Log: Logger;\n  Notifications: PalbaseNotificationsClient;\n  Flags: PalbaseFlagsClient;\n}\n\n/** Per-process slot holding the live clients for the current request scope. */\nlet runtime: RuntimeServices | null = null;\n\n/** Install the live clients for the current request scope.\n *\n * Called by the Palbase runtime (worker.js / dev-server.js) immediately before\n * invoking a handler. NOT part of the public author-facing API — exported with\n * a `__` prefix so the runtime can reach it across the shared module instance.\n */\nexport function __setRuntime(services: RuntimeServices): void {\n  runtime = services;\n}\n\n/** Read the live clients, throwing if accessed outside a request scope.\n *\n * NOT part of the public author-facing API — exported with a `__` prefix for\n * the runtime and the singleton Proxies. */\nexport function __getRuntime(): RuntimeServices {\n  if (runtime === null) {\n    throw new Error(\n      \"Palbase services accessed outside a request scope. The Database/Documents/… \" +\n        \"singletons are only available inside an endpoint handler (or after the \" +\n        \"runtime has called __setRuntime).\",\n    );\n  }\n  return runtime;\n}\n\n/**\n * Build a Proxy singleton that forwards every property access to the live\n * client named `key` on the current runtime.\n *\n * The single `as RuntimeServices[K]` is the only contained cast in the surface:\n * `Reflect.get` on a typed object returns `unknown` for a `string | symbol`\n * key, but `prop` is constrained to keys of the client interface at the call\n * sites (the exported singletons are typed below), so the forward is sound.\n */\nfunction makeServiceProxy<K extends keyof RuntimeServices>(key: K): RuntimeServices[K] {\n  const handler: ProxyHandler<RuntimeServices[K]> = {\n    get(_target, prop, receiver) {\n      const client = __getRuntime()[key];\n      const value = Reflect.get(client as object, prop, receiver) as unknown;\n      // Bind methods to their owning client so `this` stays correct when the\n      // author destructures or calls `Database.query(...)`.\n      return typeof value === \"function\" ? value.bind(client) : value;\n    },\n  };\n  // The Proxy target is irrelevant (all access goes through `get`); the cast\n  // names the surface type the singleton presents to authors.\n  return new Proxy({} as RuntimeServices[K], handler);\n}\n\n/** The project's own Postgres (pgx, schema `env_<envId>`). Typed CRUD +\n * `query`/`transaction`. For a typed `.tables.<name>` API, wrap with\n * {@link typedDatabase}. */\nexport const Database: DBClient = makeServiceProxy(\"Database\");\n\n/** Firestore-like document client (PalDocs). */\nexport const Documents: PalbaseDocsClient = makeServiceProxy(\"Documents\");\n\n/** Object storage client (buckets, signed URLs). */\nexport const Storage: PalbaseStorageClient = makeServiceProxy(\"Storage\");\n\n/** JSON-typed cache (get/set/incr/getOrSet). */\nexport const Cache: CacheClient = makeServiceProxy(\"Cache\");\n\n/** Background job queue. */\nexport const Queue: QueueClient = makeServiceProxy(\"Queue\");\n\n/** Structured logger. */\nexport const Log: Logger = makeServiceProxy(\"Log\");\n\n/** Push / email / SMS / in-app notifications. */\nexport const Notifications: PalbaseNotificationsClient = makeServiceProxy(\"Notifications\");\n\n/** Feature flags. */\nexport const Flags: PalbaseFlagsClient = makeServiceProxy(\"Flags\");\n\n/**\n * Type the `Database` singleton against a `defineSchema()` result, returning a\n * facade with a typed `.tables.<name>.insert(...)` API alongside the raw\n * `query`/`transaction` ops.\n *\n *   const Db = typedDatabase(schema);\n *   const todo = await Db.tables.todos.insert({ title: \"x\" });\n *\n * This is per-endpoint (not global module augmentation), so one endpoint's\n * tables never leak into another's `Database` type.\n */\nexport function typedDatabase<TSchema extends SchemaDef>(\n  schema: TSchema,\n): TypedDB<TSchema> & DBClient {\n  // makeTypedDB wraps the raw DBClient with the typed `.tables` facade (and a\n  // typed `transaction`). The full `& DBClient` surface also needs the raw ops\n  // (query/insert/update/delete/findById/findMany), which we delegate straight\n  // to the `Database` singleton — every call goes through its runtime Proxy.\n  const typed = makeTypedDB(schema, Database);\n  const rawOps: DBClient = {\n    query: (sql, params) => Database.query(sql, params),\n    insert: (table, data) => Database.insert(table, data),\n    update: (table, id, data) => Database.update(table, id, data),\n    delete: (table, id) => Database.delete(table, id),\n    findById: (table, id) => Database.findById(table, id),\n    findMany: (table, q) => Database.findMany(table, q),\n    transaction: (fn) => Database.transaction(fn),\n  };\n  // typed.transaction (typed-tx) intentionally overrides rawOps.transaction so\n  // the callback sees the typed `.tables` API.\n  return Object.assign(rawOps, typed);\n}\n"],"mappings":";AAwGA,SAAS,eACP,MACA,KACe;AACf,SAAO;AAAA,IACL,QAAQ,CAAC,SACP,IAAI,OAAO,MAAM,IAA+B;AAAA,IAElD,QAAQ,CAAC,IAAY,SACnB,IAAI,OAAO,MAAM,IAAI,IAA+B;AAAA,IAEtD,QAAQ,CAAC,OAAe,IAAI,OAAO,MAAM,EAAE;AAAA,IAE3C,UAAU,CAAC,OACT,IAAI,SAAS,MAAM,EAAE;AAAA,IAEvB,UAAU,CAAC,UACT,IAAI,SAAS,MAAM,KAA4C;AAAA,EACnE;AACF;AAkBO,SAAS,YACd,QACA,KACY;AACZ,WAAS,YAAY,QAAwD;AAC3E,UAAM,SAAS,CAAC;AAChB,eAAW,OAAO,OAAO,KAAK,OAAO,MAAM,GAAG;AAC5C,YAAM,WAAW,OAAO,OAAO,GAAG;AAClC,UAAI,aAAa,QAAW;AAC1B,eAAO,GAAG,IAAI,eAAe,SAAS,MAAM,MAAM;AAAA,MACpD;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,QAAM,SAAS;AAAA,IACb,QAAQ,YAAY,GAAG;AAAA,IACvB,aAAa,CAAI,OACf,IAAI,YAAY,CAAC,UAAU,GAAG,EAAE,QAAQ,YAAY,KAAK,EAAE,CAAe,CAAC;AAAA,EAC/E;AAMA,SAAO;AACT;;;ACtGA,IAAI,UAAkC;AAQ/B,SAAS,aAAa,UAAiC;AAC5D,YAAU;AACZ;AAMO,SAAS,eAAgC;AAC9C,MAAI,YAAY,MAAM;AACpB,UAAM,IAAI;AAAA,MACR;AAAA,IAGF;AAAA,EACF;AACA,SAAO;AACT;AAWA,SAAS,iBAAkD,KAA4B;AACrF,QAAM,UAA4C;AAAA,IAChD,IAAI,SAAS,MAAM,UAAU;AAC3B,YAAM,SAAS,aAAa,EAAE,GAAG;AACjC,YAAM,QAAQ,QAAQ,IAAI,QAAkB,MAAM,QAAQ;AAG1D,aAAO,OAAO,UAAU,aAAa,MAAM,KAAK,MAAM,IAAI;AAAA,IAC5D;AAAA,EACF;AAGA,SAAO,IAAI,MAAM,CAAC,GAAyB,OAAO;AACpD;AAKO,IAAM,WAAqB,iBAAiB,UAAU;AAGtD,IAAM,YAA+B,iBAAiB,WAAW;AAGjE,IAAM,UAAgC,iBAAiB,SAAS;AAGhE,IAAM,QAAqB,iBAAiB,OAAO;AAGnD,IAAM,QAAqB,iBAAiB,OAAO;AAGnD,IAAM,MAAc,iBAAiB,KAAK;AAG1C,IAAM,gBAA4C,iBAAiB,eAAe;AAGlF,IAAM,QAA4B,iBAAiB,OAAO;AAa1D,SAAS,cACd,QAC6B;AAK7B,QAAM,QAAQ,YAAY,QAAQ,QAAQ;AAC1C,QAAM,SAAmB;AAAA,IACvB,OAAO,CAAC,KAAK,WAAW,SAAS,MAAM,KAAK,MAAM;AAAA,IAClD,QAAQ,CAAC,OAAO,SAAS,SAAS,OAAO,OAAO,IAAI;AAAA,IACpD,QAAQ,CAAC,OAAO,IAAI,SAAS,SAAS,OAAO,OAAO,IAAI,IAAI;AAAA,IAC5D,QAAQ,CAAC,OAAO,OAAO,SAAS,OAAO,OAAO,EAAE;AAAA,IAChD,UAAU,CAAC,OAAO,OAAO,SAAS,SAAS,OAAO,EAAE;AAAA,IACpD,UAAU,CAAC,OAAO,MAAM,SAAS,SAAS,OAAO,CAAC;AAAA,IAClD,aAAa,CAAC,OAAO,SAAS,YAAY,EAAE;AAAA,EAC9C;AAGA,SAAO,OAAO,OAAO,QAAQ,KAAK;AACpC;","names":[]}

package/dist/db/index.d.cts

@@ -1,5 +1,5 @@
-import { S as SchemaDef } from '../schema-zk-a0Dv7.cjs';
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnType, O as OnDeleteAction, T as TableDef, c as boolean, d as defineSchema, e as enumType, i as integer, j as jsonb, t as table, f as text, g as timestamp, u as uuid } from '../schema-zk-a0Dv7.cjs';
+import { S as SchemaDef } from '../schema-BqfEhIC0.cjs';
+export { b as ColumnBuilder, c as ColumnDef, d as ColumnType, O as OnDeleteAction, T as TableDef, e as boolean, f as defineSchema, g as enumType, i as integer, j as jsonb, t as table, h as text, k as timestamp, u as uuid } from '../schema-BqfEhIC0.cjs';
 
 /** Result of migration generation. */
 interface MigrationResult {

package/dist/db/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SchemaDef } from '../schema-zk-a0Dv7.js';
-export { C as ColumnBuilder, a as ColumnDef, b as ColumnType, O as OnDeleteAction, T as TableDef, c as boolean, d as defineSchema, e as enumType, i as integer, j as jsonb, t as table, f as text, g as timestamp, u as uuid } from '../schema-zk-a0Dv7.js';
+import { S as SchemaDef } from '../schema-BqfEhIC0.js';
+export { b as ColumnBuilder, c as ColumnDef, d as ColumnType, O as OnDeleteAction, T as TableDef, e as boolean, f as defineSchema, g as enumType, i as integer, j as jsonb, t as table, h as text, k as timestamp, u as uuid } from '../schema-BqfEhIC0.js';
 
 /** Result of migration generation. */
 interface MigrationResult {