@browserlessapi/inferlo 0.3.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@browserlessapi/inferlo",
-  "version": "0.3.0",
-  "description": "The TypeScript backend framework with built-in AI model support: Anthropic, OpenAI, Gemini, Ollama and OpenAI-compatible models, plus routing, database, validation, auth and MCP in one package.",
+  "version": "0.5.0",
+  "description": "The enterprise-ready TypeScript backend framework, with AI models built in: routing, validation, PostgreSQL and migrations, auth, rate limiting, jobs, OpenAPI and MCP, plus Anthropic, OpenAI, Gemini, Ollama and OpenAI-compatible models.",
   "type": "module",
   "license": "MIT",
   "author": "BrowserlessAPI",
@@ -35,6 +35,42 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./adonisjs": {
+      "types": "./dist/adonisjs.d.ts",
+      "default": "./dist/adonisjs.js"
+    },
+    "./ai": {
+      "types": "./dist/ai/public.d.ts",
+      "default": "./dist/ai/public.js"
+    },
+    "./elysia": {
+      "types": "./dist/elysia.d.ts",
+      "default": "./dist/elysia.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "default": "./dist/express.js"
+    },
+    "./fastify": {
+      "types": "./dist/fastify.d.ts",
+      "default": "./dist/fastify.js"
+    },
+    "./hono": {
+      "types": "./dist/hono.d.ts",
+      "default": "./dist/hono.js"
+    },
+    "./nestjs": {
+      "types": "./dist/nestjs.d.ts",
+      "default": "./dist/nestjs.js"
+    },
+    "./tsed": {
+      "types": "./dist/tsed.d.ts",
+      "default": "./dist/tsed.js"
+    },
+    "./trpc": {
+      "types": "./dist/trpc.d.ts",
+      "default": "./dist/trpc.js"
+    },
     "./postgres": {
       "types": "./dist/db/postgres.d.ts",
       "default": "./dist/db/postgres.js"
@@ -57,7 +93,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/cli/main.js",
     "prepare": "npm run build",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/helpdesk",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p examples/helpdesk && tsc --noEmit -p examples/with-hono && tsc --noEmit -p examples/with-express && tsc --noEmit -p examples/with-fastify && tsc --noEmit -p examples/with-elysia && tsc --noEmit -p examples/with-nestjs && tsc --noEmit -p examples/with-trpc && tsc --noEmit -p examples/with-adonisjs && tsc --noEmit -p examples/with-tsed",
     "test": "node --test --test-reporter=spec \"test/**/*.test.ts\" \"examples/*/test/*.test.ts\"",
     "test:bun": "bun test test/",
     "llms": "node scripts/build-llms.ts",
@@ -73,9 +109,27 @@
     }
   },
   "devDependencies": {
+    "@adonisjs/core": "^6.21.0",
+    "@nestjs/common": "^12.3.3",
+    "@nestjs/core": "^12.3.3",
+    "@nestjs/platform-express": "^12.3.3",
+    "@trpc/server": "^11.24.0",
+    "@tsed/core": "^8.45.0",
+    "@tsed/di": "^8.45.0",
+    "@tsed/platform-express": "^8.45.0",
+    "@tsed/platform-http": "^8.45.0",
+    "@tsed/platform-params": "^8.45.0",
+    "@tsed/schema": "^8.45.0",
+    "@types/express": "^5.0.6",
     "@types/node": "^22.18.0",
     "@types/pg": "^8.15.0",
+    "elysia": "^1.4.30",
+    "express": "^5.3.0",
+    "fastify": "^5.12.8",
+    "hono": "^4.13.16",
     "pg": "^8.16.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/templates/app/AGENTS.md

@@ -22,6 +22,7 @@ Do not finish until `inferlo check` passes.
 |---|---|
 | `src/models.ts` | Every model (`model("table_name", { ... })`) and the `models` array |
 | `src/routes/<feature>.ts` | Routes for one feature, each one an exported `const` |
+| `src/config.ts` | `settings`: every environment variable, validated at startup with `config({ schema, secrets })` |
 | `src/app.ts` | `createApp({ models, routes, db, auth, ai })`. Import route modules with `import * as x` |
 | `src/server.ts` | Starts the server. Keep it small |
 | `test/<feature>.test.ts` | Tests using `app.request(path, { method, json, as: user })` |
@@ -32,14 +33,19 @@ Do not finish until `inferlo check` passes.
 2. **Routes are private by default.** A route without `auth` needs a signed-in user. Use `auth: "public"` only for routes anyone may call, and `auth: "<role>"` for role checks.
 3. **Validate every input with a schema.** `body`, `query` and `params` options. Reuse model schemas: `Ticket.pick("title", "body")`, `Ticket.omit("ownerId")`, `.partial()` for PATCH.
 4. **Check ownership.** Fetch with `db.x.get(id)` (throws 404) and compare `ownerId` to `user.id`; throw `notFound()` when it does not match, so other users' ids are not revealed.
-5. **Never write raw SQL with string concatenation.** Use the table methods. If you really need SQL, use `db.$sql(text, params)` with `$1` placeholders.
-6. **Model ids, timestamps:** every model already has `id`, `createdAt`, `updatedAt`. Never define them or send them as input.
-7. **New field?** Add it to the model in `src/models.ts`, then run `npx inferlo db push` in development, or `npx inferlo db migrate <name>` to write a migration file for production (applied with `npx inferlo db migrate --apply`). Use `.optional()` or `.default()` for new fields on existing tables. Never edit `migrations/snapshot.json`, and never edit a migration file that has been applied (`--apply` warns with IL4018 and does not run the change): put changes in a new migration. Removing a model or field needs `npx inferlo db migrate <name> --allow-drop` (it deletes that data); never use it for a rename. Changing a field's default or making it required or optional needs `--allow-change`; give a newly required field a `.default()` so existing NULL rows get a value.
-8. **New resource?** `npx inferlo add resource <plural_name>` generates the model and CRUD routes. Then edit them.
-9. **AI calls** use aliases from `src/app.ts` (`model: "fast"`), never hard-coded provider model ids in routes. Use `output: schema` for structured data and `for: user.id` so usage is tracked per user.
-10. **Errors:** throw `notFound()`, `forbidden()`, `badRequest()` or `httpError(status, message)`. Every Inferlo error has a code (KRxxxx), a fix and a docs link: read the fix before changing code.
-11. **Imports:** relative imports end in `.ts` (`import { Note } from "../models.ts"`).
-12. **Expose to AI agents:** add `tool: true` to a route to make it an MCP tool at `/mcp`. Same auth applies.
+5. **Related rows:** a `t.ref` field named `<name>Id` is a relation: `db.notes.findMany({ include: { owner: true } })` adds `note.owner` with one extra query, and `db.users.findMany({ include: { notes: true } })` adds `user.notes` (the rows that point to each user). Never load related rows in a loop. For lists clients page through, use `db.notes.paginate({ where, orderBy: { createdAt: "desc" }, cursor: query.cursor, limit: query.limit })`, which returns `{ items, nextCursor }`.
+6. **Never write raw SQL with string concatenation.** Use the table methods. If you really need SQL, use `db.$sql(text, params)` with `$1` placeholders.
+7. **Model ids, timestamps:** every model already has `id`, `createdAt`, `updatedAt`. Never define them or send them as input.
+8. **New field?** Add it to the model in `src/models.ts`, then run `npx inferlo db push` in development, or `npx inferlo db migrate <name>` to write a migration file for production (applied with `npx inferlo db migrate --apply`). Use `.optional()` or `.default()` for new fields on existing tables. Never edit `migrations/snapshot.json`, and never edit a migration file that has been applied (`--apply` warns with IL4018 and does not run the change): put changes in a new migration. Removing a model or field needs `npx inferlo db migrate <name> --allow-drop` (it deletes that data); never use it for a rename. Changing a field's type or default, making it required or optional, or changing an enum's values needs `--allow-change`; give a newly required field a `.default()` so existing NULL rows get a value, and before removing an enum value add an `UPDATE` in the new migration file (before its `ADD CONSTRAINT`) that moves rows off it (IL4021).
+9. **New resource?** `npx inferlo add resource <plural_name>` generates the model and CRUD routes. Then edit them.
+10. **AI calls** use aliases from `src/app.ts` (`model: "fast"`), never hard-coded provider model ids in routes. Use `output: schema` for structured data and `for: user.id` so usage is tracked per user. To let the model act, pass routes as tools: `ai.generate({ prompt, tools: [createNote, getNote], for: user.id })`. Each tool call runs as the current user with that route's auth and validation. For work that is not a route (an external API, a calculation), make a function tool: `tool("getWeather", { description, input: t.object({ ... }) }).handle(async ({ input }) => ...)`. To send images: `ai.generate({ prompt, images: [{ url }] })` or `[{ base64, mediaType: "image/png" }]`. Give routes that call AI models, send email or check passwords a `rateLimit: { max, per, by }` (IL2005 is the 429 it returns).
+11. **Errors:** throw `notFound()`, `forbidden()`, `badRequest()` or `httpError(status, message)`. Every Inferlo error has a code (ILxxxx), a fix and a docs link: read the fix before changing code.
+12. **Imports:** relative imports end in `.ts` (`import { Note } from "../models.ts"`).
+13. **Configuration:** read environment variables only through `settings` from `src/config.ts`. A new variable is a new field in its `t.object({ ... })` schema (`.default(...)` or `.optional()` unless the app cannot start without it), and API keys, passwords and connection URLs go in `secrets` so they are never logged. Never read `process.env` in routes.
+14. **Expose to AI agents:** add `tool: true` to a route to make it an MCP tool at `/mcp`. Same auth applies.
+15. **Slow work after the response** (email, slow AI calls) is a background job: `export const x = job("send-email", { input: t.object({ ... }) }).handle(async ({ input, db, ai }) => { ... })` in `src/jobs.ts`, registered with `createApp({ jobs: [jobs] })`, queued with `await ctx.jobs.enqueue(x, { ... })`. Pass ids in the input, not rows. In tests, run queued jobs with `await app.jobs.runDue()`. Jobs run in the server process (`app.jobs.start()` in `src/server.ts`); with `createApp({ jobQueue: { store: "database" } })` they are kept in Postgres and `npm run worker` (`inferlo worker`) runs them in separate processes. Scheduled work is a cron next to its job: `export const nightly = cron("0 3 * * *", cleanupJob)` (UTC; the job's input must be `t.object({})`).
+16. **Security headers and health:** every response already gets security headers (CSP, HSTS over HTTPS, nosniff, frame and referrer policies) and `GET /health` and `GET /ready` are built in (`health: true` in `src/app.ts`). Change a header with `createApp({ secureHeaders: { "Content-Security-Policy": "..." } })` instead of setting it in every route, never turn them all off without a proxy that adds them, and never add your own `/health` route. On SIGTERM, `src/server.ts` calls `app.close()`, which finishes in-flight requests and jobs first. Prometheus metrics (`GET /metrics`: requests, jobs, AI calls, tokens and cost) are served when `METRICS_TOKEN` is set; never add your own `/metrics` route.
+17. **Replacing a route:** do not delete a route clients use. Add the new one and mark the old one `deprecated: { since: "YYYY-MM-DD", sunset: "YYYY-MM-DD", link: "https://..." }` in its options; it then sends the standard Deprecation and Sunset headers and is marked in OpenAPI and MCP. Remove it after the sunset date.
 
 ## Testing
 

package/templates/app/README.md

@@ -11,4 +11,6 @@ npx inferlo describe   # routes, models and auth at a glance
 
 Set `DATABASE_URL` in `.env` to use PostgreSQL, then run `npx inferlo db push`.
 
+Background jobs run in the server process. To run them in separate processes too, set `jobQueue: { store: "database" }` in `src/app.ts` (needs PostgreSQL) and start workers with `npm run worker`.
+
 AI coding agents: read `AGENTS.md`.

package/templates/app/_env.example

@@ -3,3 +3,5 @@ DATABASE_URL=
 PORT=3000
 ANTHROPIC_API_KEY=
 OPENAI_API_KEY=
+# Set to a random secret of 16+ characters to serve Prometheus metrics at GET /metrics.
+# METRICS_TOKEN=

package/templates/app/package.json.tpl

@@ -10,6 +10,7 @@
   "scripts": {
     "dev": "inferlo dev",
     "start": "node src/server.ts",
+    "worker": "inferlo worker",
     "check": "inferlo check",
     "describe": "inferlo describe",
     "db:push": "inferlo db push",

package/templates/app/src/app.ts

@@ -1,18 +1,25 @@
-import { anthropic, bearer, createApp, env, hashToken, memory, openai } from "@browserlessapi/inferlo";
+import { anthropic, bearer, createApp, hashToken, memory, openai } from "@browserlessapi/inferlo";
 import { postgres } from "@browserlessapi/inferlo/postgres";
+import { settings } from "./config.ts";
 import { models } from "./models.ts";
-import * as health from "./routes/health.ts";
 import * as notes from "./routes/notes.ts";
 
-const databaseUrl = env("DATABASE_URL", { optional: true });
-
 export const app = createApp({
   name: "{{name}}",
   version: "0.1.0",
   models,
   // inferlo:routes
-  routes: [health, notes],
-  db: databaseUrl ? postgres({ url: databaseUrl }) : memory(),
+  routes: [notes],
+  // GET /health (liveness) and GET /ready (readiness: database and AI configuration).
+  health: true,
+  // Config secrets never appear in logs (provider keys, tokens and passwords in URLs are hidden too).
+  redact: [settings],
+  // One log line per request with its id (also in the X-Request-Id header), status and duration.
+  // Use format: "json" for one JSON object per line when a log collector reads the output.
+  logging: { requests: true },
+  // Prometheus metrics at GET /metrics (requests, jobs, AI calls, tokens and cost) when METRICS_TOKEN is set.
+  metrics: settings.METRICS_TOKEN ? { token: settings.METRICS_TOKEN } : false,
+  db: settings.DATABASE_URL ? postgres({ url: settings.DATABASE_URL }) : memory(),
 
   // Requests send "Authorization: Bearer <api key>". Keys are stored as SHA-256 hashes.
   auth: bearer(async (token, { db }) => {
@@ -24,8 +31,8 @@ export const app = createApp({
 
   ai: {
     providers: {
-      anthropic: anthropic({ apiKey: env("ANTHROPIC_API_KEY", { default: "" }) }),
-      openai: openai({ apiKey: env("OPENAI_API_KEY", { default: "" }) }),
+      anthropic: anthropic({ apiKey: settings.ANTHROPIC_API_KEY }),
+      openai: openai({ apiKey: settings.OPENAI_API_KEY }),
     },
     // Aliases keep model ids in one place. A list means: try in order.
     models: {

package/templates/app/src/config.ts

@@ -0,0 +1,17 @@
+import { config, t } from "@browserlessapi/inferlo";
+
+// Every environment variable the app reads, validated once at startup (IL7003 lists what is wrong).
+// Values come from the environment (inferlo dev reads .env), then from `environments`, then defaults.
+// Secrets are redacted when settings are logged or serialised.
+export const settings = config({
+  schema: t.object({
+    // Leave empty to use the in-memory database (data resets on restart).
+    DATABASE_URL: t.string().optional(),
+    PORT: t.int().min(1).max(65535).default(3000),
+    ANTHROPIC_API_KEY: t.string().default(""),
+    OPENAI_API_KEY: t.string().default(""),
+    // Set to serve Prometheus metrics at GET /metrics (scrapers send it as a bearer token).
+    METRICS_TOKEN: t.string().min(16).optional(),
+  }),
+  secrets: ["DATABASE_URL", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", "METRICS_TOKEN"],
+});

package/templates/app/src/routes/notes.ts

@@ -47,7 +47,7 @@ export const deleteNote = route
 const Summary = t.object({ summary: t.string().max(300).describe("One or two sentences") });
 
 export const summarizeNote = route
-  .post("/notes/:id/summary", { params: IdParams, summary: "Summarize a note with AI" })
+  .post("/notes/:id/summary", { params: IdParams, summary: "Summarize a note with AI", rateLimit: { max: 20, per: "hour" } })
   .handle(async ({ params, user, db, ai }) => {
     const note = await db.notes.get(params.id);
     if (note.ownerId !== user.id) throw notFound();

package/templates/app/src/server.ts

@@ -1,5 +1,6 @@
-import { createToken, env, hashToken } from "@browserlessapi/inferlo";
+import { createToken, hashToken } from "@browserlessapi/inferlo";
 import { app } from "./app.ts";
+import { settings } from "./config.ts";
 
 await app.db.$sync();
 
@@ -9,8 +10,17 @@ if (app.db.$adapter.dialect === "memory") {
   const token = createToken("dev");
   await app.db.api_keys.insert({ userId: user.id, hash: await hashToken(token) });
   console.log(`Dev API key: ${token}`);
-  console.log(`Try: curl -H "Authorization: Bearer ${token}" http://localhost:${env("PORT", { default: "3000" })}/notes`);
+  console.log(`Try: curl -H "Authorization: Bearer ${token}" http://localhost:${settings.PORT}/notes`);
 }
 
-const server = await app.listen(env.int("PORT", { default: 3000 }));
+const server = await app.listen(settings.PORT);
 console.log(`{{name}} running on http://localhost:${server.port}`);
+
+// Background jobs run in this process. With jobQueue: { store: "database" } in src/app.ts they can
+// also run in separate processes: npm run worker.
+app.jobs.start();
+
+// Graceful shutdown: /ready answers 503 at once so the load balancer stops sending traffic, requests are
+// still served for 5 seconds, then in-flight requests and the running job finish and the server and the
+// database close.
+process.on("SIGTERM", () => void app.close({ delayMs: 5000 }));

package/templates/app/src/routes/health.ts

@@ -1,3 +0,0 @@
-import { route } from "@browserlessapi/inferlo";
-
-export const health = route.get("/health", { auth: "public", summary: "Health check" }).handle(() => ({ ok: true }));