@palbase/backend 25.1.0 → 27.0.0

package/docs/migrations.md

@@ -95,7 +95,7 @@ one, `palbase push` is what moves an Environment's. Until then the declaration i
 ahead of the tables.
 
 The TYPES move separately again. `palbase build` regenerates `palbase-env.d.ts`
-from `db/*.ts`, which is what types `Database.tables.<name>` in your
+from `db/*.ts`, which is what types `Database.public.<name>` in your
 services — so after a schema edit, run it. (There is no second command for this:
 `build` regenerates everything derived, because one verb to remember is one verb
 to forget.) Typed and applied are independent, and knowing which one you are
@@ -168,7 +168,7 @@ existing data gets there.
 Add `rls: true` + `policies: [policy(...)]` to a table in `db/*.ts`; the
 generated migration emits the `ENABLE ROW LEVEL SECURITY` + `CREATE POLICY` DDL.
 See [schema.md](./schema.md) for the column builders, the policy DSL, and typed
-`Database.tables.*` access.
+`Database.public.*` access.
 
 ### Hand-writing a policy
 

package/docs/schema.md

@@ -4,7 +4,7 @@ Declare your tables under `db/`, **one file per schema**: `db/public.ts` is the
 schema Palbase expects to find, `db/billing.ts` declares a second one. Each file
 default-exports a `defineSchema("<name>", { tables })` call. That drives
 [migrations](./migrations.md) (additive changes auto-apply on deploy; type
-changes need an explicit migration) and makes `Database.tables.*` typed
+changes need an explicit migration) and makes `Database.public.*` typed
 everywhere — by default, with no import and no generic.
 
 > Coming from a single `db/schema.ts` with tables declared inline? That layout is
@@ -411,14 +411,14 @@ and an index is not one.
 ## Typed DB access — by default
 
 You do **not** wire anything per endpoint. Saving a file under `db/` regenerates
-`palbase-env.d.ts`, which types `Database.tables.<name>` everywhere — no import
+`palbase-env.d.ts`, which types `Database.public.<name>` everywhere — no import
 of the schema, no generic, no cast:
 
 ```ts
 // services/room.service.ts — the layer that touches the database.
 import { Database } from "@palbase/backend";
 
-type RoomsTable = typeof Database.tables.rooms;   // typed from your db/*.ts
+type RoomsTable = typeof Database.public.rooms;   // typed from your db/*.ts
 
 export class RoomService {
   private readonly rooms: RoomsTable;
@@ -431,13 +431,22 @@ export class RoomService {
   }
 }
 
-export const roomService = new RoomService(Database.tables.rooms);
+```
+
+```ts
+// rooms.module.ts
+import { Module, type Token } from "@palbase/backend";
+import { RoomsController } from "./controllers/rooms.controller.ts";
+import { RoomService } from "./services/room.service.ts";
+
+@Module({ controllers: [RoomsController as Token], providers: [RoomService as Token] })
+export class RoomsModule {}
 ```
 
 ```ts
 // controllers/rooms.controller.ts — HTTP only; no `Database` import here.
 import { Controller, Post, Body, z } from "@palbase/backend";
-import { roomService } from "../services/room.service.js";
+import { RoomService } from "../services/room.service.js";
 
 const CreateRoomBody = z.object({ name: z.string() });
 const RoomOut = z.object({ id: z.string(), name: z.string() });
@@ -453,12 +462,12 @@ export default class RoomsController {
 }
 ```
 
-`Database.tables.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
-`findById(id)`, `findMany(query?)`. `Database.transaction(fn)` yields a `tx`
+`Database.public.<name>` exposes `insert`, `update(id, data)`, `delete(id)`,
+`findById(id)`, `findMany(query?)`. `Database.$transaction(fn)` yields a `tx`
 whose `tx.tables.<name>` is typed from the same schema, but carries plan
 operations (`insert`/`insertMany`/`updateWhere`/`deleteWhere`/`select`) rather
 than awaited calls — see [database.md](./database.md#transactions). The raw
-string-keyed ops (`Database.insert("rooms", …)`, `Database.query(…)`) are still
+string-keyed ops (`Database.$insert("rooms", …)`, `Database.$query(…)`) are still
 available for dynamic table names and read-only SQL.
 
 If you want a row type explicitly, import it from the generated env module:
@@ -579,10 +588,10 @@ export const todos = defineTable("todos", {
 export default defineSchema("public", { tables: [todos] });
 ```
 
-With this in place, `await Database.tables.todos.findMany({})` returns only the
+With this in place, `await Database.public.todos.findMany({})` returns only the
 calling user's rows — no `WHERE owner = …` needed in the handler. To read or
 write across all users (e.g. an admin job), use the explicit bypass:
-`Database.asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
+`Database.$asService()` (see [database.md](./database.md#bypassing-rls--databaseasservice)).
 
 ### How policies are applied
 

package/docs/services.md

@@ -45,7 +45,7 @@ await Cache.del("k");
 // Stampede-safe read-through: concurrent callers wait on ONE execution of fn
 // and share its result, however many of them there are.
 const profile = await Cache.getOrSet("user:42", 300, async () => {
-  return Database.findById("users", "42");
+  return Database.$findById("users", "42");
 });
 ```
 
@@ -153,7 +153,7 @@ export default class CheckoutController {
 
 ### Overriding a flag — current user vs cross-user
 
-Writes mirror the `Database` / `Database.asService()` model:
+Writes mirror the `Database` / `Database.$asService()` model:
 
 - `Flags.setOverride(key, value)` (default) writes an override for the **current
   request user** — no `userId` argument, no admin power. It errors on an
@@ -161,7 +161,7 @@ Writes mirror the `Database` / `Database.asService()` model:
 - `Flags.asService()` returns the cross-user admin surface
   (`setOverrideForUser`, `setOverridesForUser`, `clearOverrideForUser`,
   `clearAllOverridesForUser`, `batchSetOverrides`) for writing overrides for an
-  **arbitrary** user. Explicit and greppable, just like `Database.asService()`.
+  **arbitrary** user. Explicit and greppable, just like `Database.$asService()`.
 
 ```ts
 // Current request user — no userId needed:
@@ -230,47 +230,137 @@ A controller's job is HTTP — validate a body through a named schema, name the
 whose, in what order is the service's. A controller that reaches for `Database`
 has moved the logic into the layer that is hardest to test.
 
-**2. The dependency arrives through the CONSTRUCTOR, and the module exports one
-wired instance.** There is no DI container and no decorator — the last line of
-the file is the wiring:
+**2. A dependency arrives through the CONSTRUCTOR, and the container supplies
+it.** Mark the class `@Injectable()` and name what it needs as ordinary
+constructor parameters:
 
 ```ts
 // services/note.service.ts
-import { Database } from "@palbase/backend";
+import { Database, Injectable } from "@palbase/backend";
 
-type NotesTable = typeof Database.tables.notes;
+type NotesTable = typeof Database.public.notes;
 
+@Injectable()
 export class NoteService {
-  private readonly notes: NotesTable;
-
-  // Assigned in the BODY. A parameter property (`constructor(private notes: …)`)
-  // is refused by Node's type-stripping test runner, for the whole file.
-  constructor(notes: NotesTable) {
-    this.notes = notes;
-  }
+  private readonly notes: NotesTable = Database.public.notes;
 
   list(userId: string) {
-    return this.notes.findMany({ user_id: userId });
+    return this.notes.findMany({ where: { user_id: userId } });
   }
 }
+```
 
-export const noteService = new NoteService(Database.tables.notes);
+```ts
+// services/report.service.ts — a service that depends on another service
+import { Injectable } from "@palbase/backend";
+import { NoteService } from "./note.service.ts";
+
+@Injectable()
+export class ReportService {
+  constructor(private readonly notes: NoteService) {}
+
+  async count(userId: string): Promise<number> {
+    return (await this.notes.list(userId)).length;
+  }
+}
 ```
 
+A controller asks the same way, and nothing wires it by hand:
+
 ```ts
 // controllers/notes.controller.ts
-import { noteService } from "../services/note.service";
+import { Controller, Get } from "@palbase/backend";
+import { NoteService } from "../services/note.service.ts";
+
+@Controller("/notes")
+export class NotesController {
+  constructor(private readonly notes: NoteService) {}
+
+  @Get("") list(): Promise<Note[]> { return this.notes.list(currentUserId()); }
+}
+```
+
+There is **no `inject()`, no `@Inject`, and no token registry**. A dependency is
+named by its parameter's TYPE and by nothing else — which is also why an
+`interface` cannot be one: an interface does not exist at runtime, so there is
+nothing to hand over. Use a class, or an `abstract class` when you want the
+abstraction:
+
+```ts
+export abstract class Clock {
+  abstract now(): number;
+}
+
+@Injectable()
+export class SystemClock extends Clock {
+  now(): number { return Date.now(); }
+}
 ```
 
-**3. That module-level singleton is the only way to hold a dependency.**
-Controllers, hooks, jobs and webhooks are all constructed by the runtime with
-**no arguments**. A class that declares a constructor parameter is refused at
-build with the class named — there is no injector to fill it, so the field would
-otherwise be `undefined` in production. Import the singleton instead.
+The abstraction is the TOKEN; the implementation is the PROVIDER. `SystemClock`
+goes in a module's `providers` and `Clock` goes in nobody's: the container
+resolves an abstraction to the single owned class that `extends` it. Listing
+`Clock` itself is refused — `new Clock()` succeeds in JavaScript and hands back
+an object missing every abstract member, and that object would be injected.
+
+**3. ONE module says what exists, who owns it, and what it may reach.** A class
+that no module lists does not exist: it is refused at build, by name, and it
+never reaches the route table, the dispatcher or the OpenAPI document.
+
+```ts
+// notes.module.ts — beside the domain it owns, not in a directory we name
+import { Module, type Token } from "@palbase/backend";
+import { NotesController } from "./controllers/notes.controller.ts";
+import { NoteService } from "./services/note.service.ts";
+import { ReportService } from "./services/report.service.ts";
+
+@Module({
+  controllers: [NotesController as Token],   // the entry points this module owns
+  providers: [NoteService as Token, ReportService as Token],  // what it owns
+  exports: [NoteService as Token],           // what OTHER modules may reach
+  imports: [],                               // whose exports THIS module may reach
+})
+export class NotesModule {}
+```
+
+The four lists answer four different questions, and nothing else answers them:
+
+| list | question |
+|---|---|
+| `providers` | which classes does this module OWN |
+| `controllers` | which entry points does it own |
+| `exports` | which of its own classes may another module reach |
+| `imports` | whose exports may this module reach |
+
+`ReportService` is NOT exported above, so no other module can depend on it —
+and the build says so by name if one tries. That is the whole boundary: a
+module's internals stay internal until it says otherwise.
+
+There is no root module and nothing to mount one into. A small project writes
+one module file; a large one writes a module per domain and the boundaries are
+enforced at build rather than by convention.
+
+**A constructor stays pure wiring.** It runs while the app is coming up, it is
+synchronous, and it must not do I/O. Real work at startup belongs in `onStart`,
+which is awaited before the first request is served — a connection opened in a
+constructor fails somewhere nobody is watching, and one opened in `onStart`
+fails at boot with the error in front of the operator.
+
+Rule 2 is also what makes rule 1 pay off. A test can build the graph with a
+stand-in in place of any part of it, however deep:
+
+```ts
+import { isolated } from "@palbase/backend/test";
+
+const frozen = new (class extends Clock { now() { return 0; } })();
+const report = isolated().with(Clock, frozen).get(ReportService);
+```
 
-Rule 2 is also what makes rule 1 pay off: because the service is handed its
-table rather than reaching for the singleton, a test constructs it with a
-stand-in and never needs a database.
+`isolated()` rebuilds the graph with the overrides in place and touches no
+process-wide state, so the next test in the same file does not meet whatever
+this one substituted. Or construct the class yourself — `new ReportService(new
+NoteService())` is ordinary TypeScript, and the container is not required for it
+to work.
 
 ```ts
 // services/note.service.test.ts — `npm test`, no database

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palbase/backend",
-  "version": "25.1.0",
+  "version": "27.0.0",
   "description": "Palbase Backend SDK — class controllers (@Controller/@Get/@Post + @Body/@QueryParams/@Param), error classes, schema DSL",
   "license": "MIT",
   "repository": {
@@ -103,21 +103,25 @@
     "emit:openapi-fixture": "tsx scripts/emit-openapi-fixture.mjs",
     "check:api": "node scripts/api-surface.mjs",
     "api:update": "node scripts/api-surface.mjs --update",
-    "build:stager": "mkdir -p stager && cp src/stager/*.js src/stager/package.json stager/"
+    "build:stager": "mkdir -p stager && for f in src/stager/*.js; do case \"$f\" in *.test.js) ;; *) cp \"$f\" stager/ ;; esac; done && cp src/stager/package.json stager/"
   },
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^7.3.4",
+    "reflect-metadata": "^0.2.2",
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@palbase/core": "workspace:^",
+    "@swc/core": "^1.16.1",
     "@types/node": "^25.5.2",
+    "bun-types": "^1.4.0",
     "fast-glob": "^3.3.3",
     "openapi3-ts": "^4.5.0",
     "tsup": "^8.0.0",
     "tsx": "^4.22.4",
     "typescript": "^5.7.0",
-    "vitest": "^3.0.0",
-    "@palbase/core": "workspace:^"
+    "unplugin-swc": "^1.5.11",
+    "vitest": "^3.0.0"
   },
   "publishConfig": {
     "access": "public"

package/stager/generics.js

@@ -0,0 +1,205 @@
+'use strict';
+
+/**
+ * Refuses constructor parameters the container cannot resolve HONESTLY, at the
+ * only place they are still visible: the source.
+ *
+ * Two shapes qualify, and both were MEASURED rather than assumed:
+ *
+ *   Repo<A>   `emitDecoratorMetadata` erases the type arguments — `Repo<A>` and
+ *             `Repo<B>` both arrive as `Repo`. The container would hand the same
+ *             instance to both and nothing at runtime could tell that was wrong.
+ *
+ *   A | null  The two transpilers this project depends on DISAGREE. Bun narrows
+ *             it to `A`, SWC emits `Object`. The container accepts the first and
+ *             refuses the second — so the SDK's own tests would certify a
+ *             behaviour the tenant does not get. Cut at the root instead: reject
+ *             the shape, and the disagreement can never be reached.
+ *
+ * WHY A TREE WALK AND NOT THE STAGING LOOP. The stager is handed
+ * `<project>/controllers` (stack_bundle.go) and stages that directory alone.
+ * Bolting this check to that loop would leave every service unexamined — and a
+ * service is where an injectable class normally lives. So the check reads every
+ * source file.
+ *
+ * WHICH CLASSES IT SPEAKS ABOUT — and this was narrowed after a real project
+ * was refused for a class nothing injects. `GooglePlacesError extends Error`,
+ * constructed by hand with `new GooglePlacesError("HTTP", …)`, was rejected for
+ * a union parameter it is entitled to have. The rule is not "every class": it is
+ * every class the container can CONSTRUCT, and that set is decided by a
+ * mechanism, not by a naming convention. `emitDecoratorMetadata` writes
+ * `design:paramtypes` onto a class only when the class carries a class
+ * decorator. Without it there are no emitted parameter types, so the container
+ * cannot inject the class and the Bun/SWC disagreement is unreachable. A
+ * decorated class is therefore exactly the set at risk — and reading the
+ * decorator's PRESENCE rather than its NAME keeps the check honest when
+ * `import { Injectable as Inj }` renames it.
+ *
+ * A class listed in a module's `providers` without a decorator is not a hole:
+ * the container refuses it on its own, naming the missing metadata.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+let tsapi = null;
+
+function ts() {
+  if (tsapi) return tsapi;
+  let mod;
+  try {
+    mod = require('typescript');
+  } catch (e) {
+    throw new Error(
+      'generics: the `typescript` package could not be loaded (' +
+        e.message +
+        '). It is the parser this check reads your constructors with.',
+    );
+  }
+  // Same guard return_types.js carries, for the same reason: TypeScript 7 is the
+  // Go-native compiler and its CommonJS entry exports version metadata only, so
+  // `ts.ScriptTarget.Latest` would throw "Cannot read properties of undefined"
+  // and tell the reader nothing.
+  if (typeof mod.createSourceFile !== 'function' || !mod.ScriptTarget) {
+    throw new Error(
+      'generics: the resolved `typescript` (v' +
+        (mod.version || 'unknown') +
+        ') has no compiler API — TypeScript 7 ships the Go-native compiler, whose ' +
+        'CommonJS build exposes version metadata only.',
+    );
+  }
+  tsapi = mod;
+  return tsapi;
+}
+
+function messageFor(relPath, owner, index, typeText, kind) {
+  const why =
+    kind === 'generic'
+      ? 'Generic dependencies cannot be injected: decorator metadata erases the type ' +
+        'arguments, so Repo<A> and Repo<B> resolve to the SAME instance and nothing at ' +
+        'runtime can tell that apart.'
+      : 'Union and intersection dependencies cannot be injected: transpilers DISAGREE on ' +
+        'them. Measured — Bun emits the class for `A | null`, SWC emits Object. The same ' +
+        'code would behave one way in tests and another in production.';
+
+  const fixes =
+    kind === 'generic'
+      ? '  - depend on a concrete non-generic class\n' +
+        '  - or name the specialisation: class UserRepo extends Repo<User> {}'
+      : '  - depend on exactly one class\n' +
+        '  - if the dependency is genuinely optional, give it a null-object implementation';
+
+  return (
+    relPath +
+    ': ' +
+    owner +
+    ' constructor, parameter ' +
+    index +
+    ' is typed `' +
+    typeText +
+    '`.\n' +
+    why +
+    '\n\nPotential solutions:\n' +
+    fixes
+  );
+}
+
+/** Checks ONE file's source. Throws on the first violation, naming it. */
+function assertNoGenericDeps(source, relPath) {
+  const t = ts();
+  const sf = t.createSourceFile(relPath, source, t.ScriptTarget.Latest, true);
+
+  /**
+   * Does this class carry a class decorator? That is the emitter's own
+   * condition for writing `design:paramtypes`, so it is the condition for the
+   * container being able to construct the class at all.
+   */
+  const isDecorated = (cls) => {
+    if (!cls) return false;
+    const decorators =
+      typeof t.canHaveDecorators === 'function' && t.canHaveDecorators(cls)
+        ? t.getDecorators(cls)
+        : cls.decorators;
+    return Array.isArray(decorators) && decorators.length > 0;
+  };
+
+  const visit = (node) => {
+    if (t.isConstructorDeclaration(node) && isDecorated(node.parent)) {
+      const owner =
+        node.parent && node.parent.name && node.parent.name.text
+          ? node.parent.name.text
+          : '<anonymous>';
+      node.parameters.forEach((p, i) => {
+        const ty = p.type;
+        if (!ty) return;
+        const isGeneric =
+          t.isTypeReferenceNode(ty) && ty.typeArguments && ty.typeArguments.length > 0;
+        const isUnion = t.isUnionTypeNode(ty) || t.isIntersectionTypeNode(ty);
+        if (isGeneric || isUnion) {
+          throw new Error(
+            messageFor(relPath, owner, i, ty.getText(sf), isGeneric ? 'generic' : 'union'),
+          );
+        }
+      });
+    }
+    t.forEachChild(node, visit);
+  };
+
+  t.forEachChild(sf, visit);
+}
+
+/**
+ * Directories that are never a tenant's source.
+ *
+ * `.palbase-staged-controllers` and `.palbase` hold machine-written copies of
+ * code that was already checked; walking them would report the same violation
+ * twice, from a path the author does not recognise.
+ */
+const SKIP = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  '.git',
+  '.palbase',
+  '.palbase-staged-controllers',
+  '.palbase-build-controllers',
+]);
+
+function sources(dir, root, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') && entry.name !== '.') {
+      if (SKIP.has(entry.name)) continue;
+    }
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP.has(entry.name)) continue;
+      sources(full, root, out);
+    } else if (/\.(c?ts|tsx)$/i.test(entry.name) && !/\.d\.ts$/i.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Checks every source file under `projectRoot`.
+ *
+ * Returns HOW MANY files were examined, deliberately. A walk whose filter is
+ * wrong finds nothing and reports success — the count is what separates
+ * "checked and clean" from "never looked", and the caller prints it.
+ */
+function assertNoGenericDepsInTree(projectRoot) {
+  const files = sources(projectRoot, projectRoot, []);
+  for (const file of files) {
+    assertNoGenericDeps(fs.readFileSync(file, 'utf8'), path.relative(projectRoot, file));
+  }
+  return files.length;
+}
+
+module.exports = { assertNoGenericDeps, assertNoGenericDepsInTree };

package/stager/stage.js

@@ -19,12 +19,33 @@
 const fs = require("node:fs");
 const path = require("node:path");
 
+const generics = require("./generics.js");
 const returnTypes = require("./return_types.js");
 const throwAnalysis = require("./throw_analysis.js");
 
+/**
+ * Directories a staged copy must never contain.
+ *
+ * The stager used to be handed `controllers/` and nothing else. It is now handed
+ * the PROJECT ROOT, because a module file imports its controllers by relative
+ * path — staging only `controllers/` produced a tree whose module files still
+ * pointed at the UN-staged sources, so the injected return types were bypassed
+ * and every response schema went back to `{}`.
+ *
+ * Copying the root means skipping what is not source: node_modules is large and
+ * resolves from above the staged tree anyway, and `.palbase*` holds build output
+ * including previous staging runs.
+ */
+const SKIP = new Set(["node_modules", "dist", "build", ".git", ".palbase"]);
+
 function walk(dir) {
   const out = [];
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    // Skipped by NAME, not by type: `node_modules` is often a SYMLINK (pnpm, and
+    // any workspace that links a local package), and `isDirectory()` is false
+    // for one — so a type-gated check walked straight into it and tried to
+    // `copyFileSync` a symlinked directory. Measured: ENOTSUP, copyfile.
+    if (SKIP.has(entry.name) || entry.name.startsWith(".palbase")) continue;
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) out.push(...walk(full));
     else out.push(full);
@@ -38,6 +59,16 @@ function walk(dir) {
  * tree and must still resolve.
  */
 function stageControllers(srcDir, stageDir, projectRoot) {
+  // Refuse unresolvable constructor shapes BEFORE staging, and over the whole
+  // project — not inside the loop below.
+  //
+  // The loop only ever sees `controllers/`: stack_bundle.go invokes this script
+  // as `stage.js <dir>/controllers <stageDir> <dir>`. A check bolted to it would
+  // leave every service unexamined, and a service is where an injectable class
+  // normally lives. `projectRoot` is the third argument precisely so a check
+  // can be wider than the staging copy.
+  const examined = generics.assertNoGenericDepsInTree(projectRoot);
+
   let injected = 0;
   for (const file of walk(srcDir)) {
     const rel = path.relative(srcDir, file);
@@ -62,7 +93,7 @@ function stageControllers(srcDir, stageDir, projectRoot) {
       fs.copyFileSync(file, dest);
     }
   }
-  return injected;
+  return { injected, examined };
 }
 
 module.exports = { stageControllers };
@@ -73,6 +104,11 @@ if (require.main === module) {
     console.error("usage: stage.js <controllers-dir> <staging-dir> <project-root>");
     process.exit(2);
   }
-  const injected = stageControllers(srcDir, stageDir, projectRoot);
-  console.log(`typed ${injected} controller file(s) from their return types`);
+  const { injected, examined } = stageControllers(srcDir, stageDir, projectRoot);
+  // The examined count is printed on purpose: a walk whose filter is wrong finds
+  // nothing and reports success. `checked 0 source file(s)` is a visible fault.
+  console.log(
+    `checked ${examined} source file(s) for unresolvable constructor shapes; ` +
+      `typed ${injected} controller file(s) from their return types`,
+  );
 }