@browserlessapi/inferlo 0.5.0 → 0.7.0

package/dist/tracing.d.ts

@@ -0,0 +1,122 @@
+/**
+ * OpenTelemetry tracing, with no dependency: pass the OpenTelemetry API you already use.
+ *
+ *   import * as otel from "@opentelemetry/api";
+ *   createApp({ tracing: { api: otel } })
+ *
+ * Every request gets a server span ("GET /tickets/:id") that continues the caller's trace (W3C traceparent, through
+ * the propagator your OpenTelemetry SDK registers), runs the handler inside it so spans you or instrumentations
+ * start nest under it, and puts traceId and spanId on the request's log entries. AI calls get client spans with the
+ * model, tokens and cost (also with createAI({ tracing }) on its own), and database queries made while a request
+ * or job is traced get client spans with the table and operation. Without an SDK, the API's no-op tracer is used
+ * and nothing is recorded.
+ */
+import type { Adapter } from "./db/types.ts";
+/** The parts of a span Inferlo uses (an @opentelemetry/api Span). */
+export interface OtelSpan {
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+        traceFlags: number;
+    };
+    setAttribute(key: string, value: string | number | boolean): unknown;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): unknown;
+    recordException(exception: unknown): void;
+    updateName(name: string): unknown;
+    end(): void;
+    isRecording(): boolean;
+}
+/** The parts of @opentelemetry/api Inferlo uses: import * as otel from "@opentelemetry/api", then { api: otel }. */
+export interface OtelApi {
+    trace: {
+        getTracer(name: string, version?: string): {
+            startSpan(name: string, options?: {
+                kind?: number;
+                attributes?: Record<string, string | number | boolean>;
+            }, context?: unknown): OtelSpan;
+        };
+        setSpan(context: unknown, span: OtelSpan): unknown;
+        /** The span of a context. Database spans are only started inside one (a request or a job). */
+        getSpan?(context: unknown): OtelSpan | undefined;
+    };
+    context: {
+        active(): unknown;
+        with<T>(context: unknown, fn: () => T): T;
+    };
+    propagation: {
+        extract(context: unknown, carrier: unknown, getter?: unknown): unknown;
+        /** Writes the trace of a context into a carrier (traceparent), so a queued job continues it. */
+        inject?(context: unknown, carrier: unknown, setter?: unknown): void;
+    };
+    SpanKind: {
+        SERVER: number;
+        CLIENT?: number;
+        CONSUMER?: number;
+    };
+    SpanStatusCode: {
+        ERROR: number;
+    };
+}
+export interface TracingConfig {
+    /** The OpenTelemetry API: import * as otel from "@opentelemetry/api", then createApp({ tracing: { api: otel } }). */
+    api: OtelApi;
+    /** The tracer name. Default: the app's name (createApp), or "inferlo" (createAI on its own). */
+    tracerName?: string;
+}
+type Attributes = Record<string, string | number | boolean>;
+export interface RequestTracing {
+    /** Starts the server span of a request and runs fn inside it. */
+    run<T>(req: Request, url: URL, fn: (span: OtelSpan) => Promise<T>): Promise<T>;
+}
+/** Checks a tracing option (createApp or createAI) and returns it, or undefined without tracing. */
+export declare function checkTracing(option: unknown, where: "createApp" | "createAI" | "serviceClient"): TracingConfig | undefined;
+/** Checks createApp({ tracing }) and returns the request tracer, or undefined without tracing. */
+export declare function requestTracing(option: unknown, appName: string, appVersion: string): RequestTracing | undefined;
+/** Client spans for calls Inferlo makes: AI models and the database. */
+export interface ClientTracing {
+    /** Starts a client span under the active one. The caller ends it (with end or fail). */
+    start(name: string, attributes: Attributes): OtelSpan;
+    /** Runs fn inside a client span that is active while fn runs, and ends it; errors are recorded on it. */
+    run<T>(name: string, attributes: Attributes, fn: (span: OtelSpan) => Promise<T>): Promise<T>;
+    /** Records an error on a span and ends it. errorType overrides error.type (by default the error's code or name). */
+    fail(span: OtelSpan, error: unknown, errorType?: string): void;
+    /** Runs fn with span as the active span. */
+    within<T>(span: OtelSpan, fn: () => T): T;
+    /** Writes the trace context of span (W3C traceparent, through the registered propagator) into headers. */
+    inject(span: OtelSpan, headers: Record<string, string>): void;
+    /** True while a span (a request's or a job's) is active. */
+    inSpan(): boolean;
+}
+export declare function clientTracing(config: TracingConfig, defaultName: string, version?: string): ClientTracing;
+/**
+ * Wraps a database adapter so its queries get client spans ("SELECT tickets") while a request or job is traced.
+ * Queries outside a trace (startup, the job worker polling for work) are not traced. Values are never recorded,
+ * only the parameterised SQL of raw queries.
+ */
+export declare function traceAdapter(adapter: Adapter, tracing: ClientTracing): Adapter;
+/** traceId and spanId for log entries, when the span belongs to a real trace. */
+export declare function traceFields(span: OtelSpan | undefined): {
+    traceId?: string;
+    spanId?: string;
+};
+/** The trace a queued job carries from where it was enqueued (W3C trace context). */
+export interface JobTraceContext {
+    traceparent?: string;
+    tracestate?: string;
+}
+export interface JobTracing {
+    /** The trace of the active span, to store with a job that is enqueued now. Empty outside a trace. */
+    capture(): JobTraceContext;
+    /** Runs one attempt of a job in a span that continues the trace it was enqueued in (cron jobs start a new trace). */
+    run<T extends string>(job: {
+        id: string;
+        name: string;
+        attempts: number;
+        trace?: JobTraceContext;
+    }, fn: (fail: (error: unknown) => void) => Promise<T>): Promise<T>;
+}
+export declare function jobTracing(config: TracingConfig, defaultName: string, version?: string): JobTracing;
+export {};

package/dist/tracing.js

@@ -0,0 +1,210 @@
+import { InferloError } from "./errors.js";
+/** CLIENT and CONSUMER in @opentelemetry/api's SpanKind (the same in every 1.x release). */
+const CLIENT_KIND = 2;
+const CONSUMER_KIND = 4;
+/** Reads incoming trace headers (traceparent, tracestate, baggage) for the propagator. */
+const headerGetter = {
+    get(carrier, key) {
+        return carrier.get(key) ?? undefined;
+    },
+    keys(carrier) {
+        return [...carrier.keys()];
+    },
+};
+const INVALID_TRACE = "00000000000000000000000000000000";
+/** Checks a tracing option (createApp or createAI) and returns it, or undefined without tracing. */
+export function checkTracing(option, where) {
+    if (option === undefined || option === false)
+        return undefined;
+    const config = option;
+    const api = config?.api;
+    const valid = config !== null &&
+        typeof config === "object" &&
+        typeof api?.trace?.getTracer === "function" &&
+        typeof api.trace.setSpan === "function" &&
+        typeof api.context?.with === "function" &&
+        typeof api.context.active === "function" &&
+        typeof api.propagation?.extract === "function" &&
+        typeof api.SpanKind?.SERVER === "number" &&
+        typeof api.SpanStatusCode?.ERROR === "number" &&
+        (config.tracerName === undefined || (typeof config.tracerName === "string" && config.tracerName.length > 0));
+    if (!valid) {
+        throw new InferloError("IL6030", "Invalid tracing options: tracing needs { api } with the OpenTelemetry API.", {
+            fix: `Install @opentelemetry/api (and an OpenTelemetry SDK that exports the spans), then: import * as otel from "@opentelemetry/api"; ${where}({ tracing: { api: otel } }).`,
+        });
+    }
+    return config;
+}
+/** Checks createApp({ tracing }) and returns the request tracer, or undefined without tracing. */
+export function requestTracing(option, appName, appVersion) {
+    const config = checkTracing(option, "createApp");
+    if (!config)
+        return undefined;
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? appName, appVersion);
+    return {
+        run(req, url, fn) {
+            const method = req.method.toUpperCase();
+            const parent = api.propagation.extract(api.context.active(), req.headers, headerGetter);
+            const attributes = {
+                "http.request.method": method,
+                "url.path": url.pathname,
+                "url.scheme": url.protocol.replace(/:$/, ""),
+                "server.address": url.hostname,
+            };
+            if (url.port)
+                attributes["server.port"] = Number(url.port);
+            const agent = req.headers.get("user-agent");
+            if (agent)
+                attributes["user_agent.original"] = agent;
+            const span = tracer.startSpan(method, { kind: api.SpanKind.SERVER, attributes }, parent);
+            return api.context.with(api.trace.setSpan(parent, span), () => fn(span));
+        },
+    };
+}
+export function clientTracing(config, defaultName, version) {
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? defaultName, version);
+    const kind = api.SpanKind.CLIENT ?? CLIENT_KIND;
+    const fail = (span, error, errorType) => {
+        span.recordException(error instanceof Error ? error : String(error));
+        const code = error?.code;
+        if (errorType)
+            span.setAttribute("error.type", errorType);
+        else if (typeof code === "string")
+            span.setAttribute("error.type", code);
+        else
+            span.setAttribute("error.type", error instanceof Error ? error.name : "Error");
+        span.setStatus({ code: api.SpanStatusCode.ERROR });
+        span.end();
+    };
+    const start = (name, attributes) => tracer.startSpan(name, { kind, attributes }, api.context.active());
+    return {
+        start,
+        fail,
+        within: (span, fn) => api.context.with(api.trace.setSpan(api.context.active(), span), fn),
+        inject(span, headers) {
+            api.propagation.inject?.(api.trace.setSpan(api.context.active(), span), headers);
+        },
+        async run(name, attributes, fn) {
+            const span = start(name, attributes);
+            let result;
+            try {
+                result = await api.context.with(api.trace.setSpan(api.context.active(), span), () => fn(span));
+            }
+            catch (error) {
+                fail(span, error);
+                throw error;
+            }
+            span.end();
+            return result;
+        },
+        inSpan() {
+            if (!api.trace.getSpan)
+                return true;
+            const active = api.trace.getSpan(api.context.active());
+            return active !== undefined && active.spanContext().traceId !== INVALID_TRACE;
+        },
+    };
+}
+const SQL_OPERATION = /^\s*([a-z]+)/i;
+/**
+ * Wraps a database adapter so its queries get client spans ("SELECT tickets") while a request or job is traced.
+ * Queries outside a trace (startup, the job worker polling for work) are not traced. Values are never recorded,
+ * only the parameterised SQL of raw queries.
+ */
+export function traceAdapter(adapter, tracing) {
+    const system = adapter.dialect === "postgres" ? "postgresql" : adapter.dialect;
+    const traced = (operation, table, query, fn) => {
+        if (!tracing.inSpan())
+            return fn();
+        const attributes = { "db.system.name": system, "db.operation.name": operation };
+        if (table)
+            attributes["db.collection.name"] = table;
+        if (query)
+            attributes["db.query.text"] = query;
+        return tracing.run(table ? `${operation} ${table}` : operation, attributes, fn);
+    };
+    const wrapped = {
+        ...adapter,
+        insert: (model, row) => traced("INSERT", model.name, undefined, () => adapter.insert(model, row)),
+        select: (model, query) => traced("SELECT", model.name, undefined, () => adapter.select(model, query)),
+        update: (model, where, patch) => traced("UPDATE", model.name, undefined, () => adapter.update(model, where, patch)),
+        delete: (model, where) => traced("DELETE", model.name, undefined, () => adapter.delete(model, where)),
+        count: (model, where) => traced("COUNT", model.name, undefined, () => adapter.count(model, where)),
+    };
+    if (adapter.transaction)
+        wrapped.transaction = (fn) => adapter.transaction((tx) => fn(traceAdapter(tx, tracing)));
+    if (adapter.sql) {
+        wrapped.sql = (text, params) => traced((SQL_OPERATION.exec(text)?.[1] ?? "SQL").toUpperCase(), undefined, text, () => adapter.sql(text, params));
+    }
+    return wrapped;
+}
+/** traceId and spanId for log entries, when the span belongs to a real trace. */
+export function traceFields(span) {
+    const context = span?.spanContext();
+    if (!context || context.traceId === INVALID_TRACE)
+        return {};
+    return { traceId: context.traceId, spanId: context.spanId };
+}
+const carrierGetter = {
+    get(carrier, key) {
+        return key === "traceparent" || key === "tracestate" ? carrier[key] : undefined;
+    },
+    keys(carrier) {
+        return Object.keys(carrier);
+    },
+};
+const TRACEPARENT = /^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/;
+export function jobTracing(config, defaultName, version) {
+    const api = config.api;
+    const tracer = api.trace.getTracer(config.tracerName ?? defaultName, version);
+    const kind = api.SpanKind.CONSUMER ?? CONSUMER_KIND;
+    return {
+        capture() {
+            if (!api.propagation.inject)
+                return {};
+            const carrier = {};
+            api.propagation.inject(api.context.active(), carrier);
+            const trace = {};
+            if (typeof carrier.traceparent === "string" && TRACEPARENT.test(carrier.traceparent)) {
+                trace.traceparent = carrier.traceparent;
+                if (typeof carrier.tracestate === "string" && carrier.tracestate.length <= 512)
+                    trace.tracestate = carrier.tracestate;
+            }
+            return trace;
+        },
+        async run(job, fn) {
+            const parent = job.trace?.traceparent ? api.propagation.extract(api.context.active(), job.trace, carrierGetter) : api.context.active();
+            const span = tracer.startSpan(`process ${job.name}`, {
+                kind,
+                attributes: {
+                    "messaging.system": "inferlo",
+                    "messaging.operation.type": "process",
+                    "messaging.destination.name": job.name,
+                    "messaging.message.id": job.id,
+                    "inferlo.job.attempt": job.attempts,
+                },
+            }, parent);
+            const fail = (error) => {
+                span.recordException(error instanceof Error ? error : String(error));
+                const code = error?.code;
+                span.setAttribute("error.type", typeof code === "string" ? code : error instanceof Error ? error.name : "Error");
+                span.setStatus({ code: api.SpanStatusCode.ERROR });
+            };
+            try {
+                const outcome = await api.context.with(api.trace.setSpan(parent, span), () => fn(fail));
+                span.setAttribute("inferlo.job.outcome", outcome);
+                return outcome;
+            }
+            catch (error) {
+                fail(error);
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        },
+    };
+}
+//# sourceMappingURL=tracing.js.map

package/dist/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -10,17 +10,22 @@ Key rules: routes are private unless `auth: "public"`; validate input with `t.*`
 - [Configuration](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/config.md): config({ schema, secrets, environments }), typed settings validated at startup, secrets redacted
 - [Schemas](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/schema.md): t.* types, modifiers, validation, JSON Schema
 - [Models and database](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/database.md): model(), queries, adapters, db push, transactions
-- [Routes](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/routes.md): options, handler context, return values, errors, middleware, deprecated routes (Deprecation and Sunset headers)
-- [Auth](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/auth.md): auth.resolve, roles, bearer API keys, passwords
+- [Routes](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/routes.md): options, handler context, return values, errors, middleware, deprecated routes (Deprecation and Sunset headers), API versions with apiVersion("v1", routes) and an OpenAPI document per version
+- [Auth](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/auth.md): auth.resolve, roles, permissions() with can() and authorize() and the route permission option, bearer API keys, passwords
 - [AI](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/ai.md): providers, aliases and fallback, structured output, streaming, embeddings, usage and budgets
+- [Modules](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/modules.md): module("billing", { imports, models, routes, jobs, provides }) splits a large app into feature modules with explicit dependencies, createApp({ modules }), checked at startup and shown in describe
 - [MCP, OpenAPI and describe](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/mcp.md)
 - [CLI](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/cli.md)
 - [Testing](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/testing.md)
-- [Use with other frameworks](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/integrations.md): the AI module in any framework, toNodeHandler and fromNodeRequest to mount an app in Express, Fastify, NestJS or node:http, inferloAI() middleware for Hono (c.var.ai), Express (req.ai), Elysia (ai) and tRPC (ctx.ai), inferloPlugin for Fastify (request.ai, app under a prefix), InferloModule for NestJS, an AdonisJS provider (ctx.ai, config/ai.ts), InferloAI and inferloAI() for Ts.ED injection, trpcTools() for tRPC procedures as AI tools
+- [Use with other frameworks](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/integrations.md): the AI module in any framework, toNodeHandler and fromNodeRequest to mount an app in Express, Fastify, NestJS or node:http (fallthrough: true passes unmatched requests to the host), inferloAI() middleware for Hono (c.var.ai), Express (req.ai), Koa (ctx.ai), Elysia (ai) and tRPC (ctx.ai), toKoaMiddleware() to mount an app in Koa, inferloPlugin for Fastify (request.ai, app under a prefix), InferloModule for NestJS, an AdonisJS provider (ctx.ai, config/ai.ts), InferloAI and inferloAI() for Ts.ED injection, trpcTools() for tRPC procedures as AI tools, toNextHandlers() for Next.js App Router route handlers, an Encore.ts raw endpoint serving the app with toNodeHandler(app, { prefix }) and createAI in Encore services
 - [Migrate from Express](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/migrate-from-express.md): move an Express app to Inferlo route by route at the same URLs, with a concept mapping table, shared auth and tests
+- [Migrate from NestJS](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/migrate-from-nestjs.md): move a NestJS app to Inferlo route by route at the same URLs with toNodeHandler(app, { fallthrough: true }), Nest modules, providers, guards, pipes and DTOs mapped to Inferlo modules, plain functions, auth and schemas
+- [Migrate from Hono](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/migrate-from-hono.md): move a Hono app to Inferlo route by route at the same URLs with hono.all("*", (c) => inferlo.fetch(c.req.raw)), Hono validators, middleware, sub-apps and basePath mapped to Inferlo schemas, createApp options, modules and apiVersion
+- [Migrate from Koa](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/migrate-from-koa.md): move a Koa app to Inferlo route by route at the same URLs with toKoaMiddleware(app, { fallthrough: true }) before the Koa router, @koa/router routes, ctx.throw, body parsers and Koa middleware mapped to Inferlo routes, schemas, errors and createApp options
 - [Security](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/security.md): secure defaults and security headers (createApp({ secureHeaders }))
 - [Observability](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/observability.md): request ids (X-Request-Id, ctx.requestId), request logs and JSON logs with createApp({ logging: { format: "json", requests: true } }), your own logger, Prometheus metrics with createApp({ metrics: { token } })
 - [Deployment](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/deploy.md): Node, Bun, Deno, edge, health and readiness endpoints, graceful shutdown with app.close()
+- [Performance](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/performance.md): reproducible throughput and latency benchmark against Fastify, Hono, Express and NestJS (npm run bench:perf) and the latest results
 - [Support policy](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/support.md): semantic versioning, which versions get fixes, LTS after 1.0, deprecation rules and supported runtime, database and framework versions
 - [Error codes](https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/errors.md): every ILxxxx code with its fix
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserlessapi/inferlo",
-  "version": "0.5.0",
+  "version": "0.7.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",
@@ -43,6 +43,14 @@
       "types": "./dist/ai/public.d.ts",
       "default": "./dist/ai/public.js"
     },
+    "./astro": {
+      "types": "./dist/astro.d.ts",
+      "default": "./dist/astro.js"
+    },
+    "./azure": {
+      "types": "./dist/azure.d.ts",
+      "default": "./dist/azure.js"
+    },
     "./elysia": {
       "types": "./dist/elysia.d.ts",
       "default": "./dist/elysia.js"
@@ -55,14 +63,42 @@
       "types": "./dist/fastify.d.ts",
       "default": "./dist/fastify.js"
     },
+    "./h3": {
+      "types": "./dist/h3.d.ts",
+      "default": "./dist/h3.js"
+    },
+    "./hapi": {
+      "types": "./dist/hapi.d.ts",
+      "default": "./dist/hapi.js"
+    },
     "./hono": {
       "types": "./dist/hono.d.ts",
       "default": "./dist/hono.js"
     },
+    "./lambda": {
+      "types": "./dist/lambda.d.ts",
+      "default": "./dist/lambda.js"
+    },
+    "./koa": {
+      "types": "./dist/koa.d.ts",
+      "default": "./dist/koa.js"
+    },
+    "./nextjs": {
+      "types": "./dist/nextjs.d.ts",
+      "default": "./dist/nextjs.js"
+    },
     "./nestjs": {
       "types": "./dist/nestjs.d.ts",
       "default": "./dist/nestjs.js"
     },
+    "./react-router": {
+      "types": "./dist/react-router.d.ts",
+      "default": "./dist/react-router.js"
+    },
+    "./sveltekit": {
+      "types": "./dist/sveltekit.d.ts",
+      "default": "./dist/sveltekit.js"
+    },
     "./tsed": {
       "types": "./dist/tsed.d.ts",
       "default": "./dist/tsed.js"
@@ -78,6 +114,10 @@
     "./testing": {
       "types": "./dist/testing.d.ts",
       "default": "./dist/testing.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "default": "./dist/langchain.js"
     }
   },
   "bin": {
@@ -93,26 +133,45 @@
   "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 && 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",
+    "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 && tsc --noEmit -p examples/with-encore && tsc --noEmit -p examples/with-koa && tsc --noEmit -p examples/with-nextjs && tsc --noEmit -p examples/with-nitro && tsc --noEmit -p examples/with-sveltekit && tsc --noEmit -p examples/with-react-router && tsc --noEmit -p examples/with-lambda && tsc --noEmit -p examples/with-hapi && tsc --noEmit -p examples/with-azure && tsc --noEmit -p examples/with-cloud-run-functions && tsc --noEmit -p examples/with-cloudflare-workers && tsc --noEmit -p examples/with-vercel && tsc --noEmit -p examples/with-netlify && tsc --noEmit -p examples/with-astro && tsc --noEmit -p examples/with-drizzle",
     "test": "node --test --test-reporter=spec \"test/**/*.test.ts\" \"examples/*/test/*.test.ts\"",
     "test:bun": "bun test test/",
+    "test:deno": "deno test -A --no-check --ignore=test/tsed.test.ts test/ && deno test -A --no-check --ignore=examples/with-tsed examples/ && deno test -A --no-check --unsafe-proto test/tsed.test.ts examples/with-tsed/",
     "llms": "node scripts/build-llms.ts",
     "check": "npm run typecheck && npm test && node scripts/build-llms.ts --check",
-    "bench": "node bench/run.ts"
+    "bench": "node bench/run.ts",
+    "bench:perf": "node bench/perf/run.ts",
+    "bench:perf:check": "node bench/perf/check.ts"
   },
   "peerDependencies": {
+    "@langchain/core": ">=0.3.0",
+    "@opentelemetry/api": ">=1.3.0",
     "pg": ">=8"
   },
   "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     }
   },
   "devDependencies": {
     "@adonisjs/core": "^6.21.0",
+    "@ai-sdk/openai-compatible": "^3.0.85",
+    "@azure/functions": "^4.17.0",
+    "@google-cloud/functions-framework": "^5.0.5",
+    "@hapi/hapi": "^21.4.13",
+    "@hono/node-server": "^2.1.6",
+    "@langchain/core": "^1.3.5",
     "@nestjs/common": "^12.3.3",
     "@nestjs/core": "^12.3.3",
     "@nestjs/platform-express": "^12.3.3",
+    "@opentelemetry/api": "^1.10.0",
+    "@sveltejs/kit": "^2.70.3",
     "@trpc/server": "^11.24.0",
     "@tsed/core": "^8.45.0",
     "@tsed/di": "^8.45.0",
@@ -120,17 +179,32 @@
     "@tsed/platform-http": "^8.45.0",
     "@tsed/platform-params": "^8.45.0",
     "@tsed/schema": "^8.45.0",
+    "@types/autocannon": "^7.12.7",
     "@types/express": "^5.0.6",
+    "@types/koa": "^3.0.3",
     "@types/node": "^22.18.0",
     "@types/pg": "^8.15.0",
+    "ai": "^7.0.163",
+    "astro": "^7.4.7",
+    "autocannon": "^8.0.0",
+    "drizzle-orm": "^0.45.4",
     "elysia": "^1.4.30",
+    "encore.dev": "^1.58.8",
     "express": "^5.3.0",
     "fastify": "^5.12.8",
+    "h3": "^2.0.8",
     "hono": "^4.13.16",
+    "koa": "^3.3.0",
+    "miniflare": "^4.20260730.0",
+    "next": "^16.4.5",
     "pg": "^8.16.0",
+    "react": "^19.3.1",
+    "react-router": "^8.5.1",
+    "redis": "^6.3.1",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "zod": "^4.6.7"
   },
   "publishConfig": {
     "access": "public"

package/templates/app/AGENTS.md

@@ -30,22 +30,26 @@ Do not finish until `inferlo check` passes.
 ## Rules
 
 1. **One way to do each thing.** Routes: `route.get/post/put/patch/delete(path, options).handle(fn)`. Validation: `t.*` schemas. Database: `db.<table>.<method>`. AI: `ai.generate` / `ai.stream` / `ai.embed`.
-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.
+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. Browser sign-in uses cookie sessions: `export const session = sessions({ secret: settings.SESSION_SECRET, user: ({ userId }, { db }) => ... })`, `createApp({ auth: session })`, `await session.signIn(ctx, user.id)` in the login route and `session.signOut(ctx)` in logout; browsers send the CSRF token in `X-CSRF-Token` or a `_csrf` form field on POST, PUT, PATCH and DELETE (403 IL3005 without it).
 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.
+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. When more than one rule decides access (owners, admins, teams), define named permissions once in `src/permissions.ts` with `export const access = permissions({ "notes.update": ({ user, note }) => note.ownerId === user.id || (user.roles ?? []).includes("admin") })`, pass `permissions: access` to `createApp`, and call `await access.authorize("notes.update", { user, note })` in routes and jobs (403 IL3004 when denied). Permissions that need only the user go on the route: `{ permission: "reports.view" }`; add `permissions: typeof access` to `Register` (with `import type`) so permission names are type-checked. When changes must be on record (who changed what), add `AuditLog` to the models and call `await audit("notes.update", { model: "notes", before: note, after: updated })` after the change, in routes and jobs (jobs pass `userId`).
 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.
+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. Code that takes a pg client (Drizzle, plain `pg`) gets it from `db.$pgClient()`, and inside `db.$transaction(async (tx) => ...)` from `tx.$pgClient()`, so it runs in the same transaction.
 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).
+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. A provider without a built-in adapter (Mistral, Bedrock, Azure, Vertex, Groq, ...) is added through its Vercel AI SDK package: `providers: { mistral: aiSdk(createMistral({ apiKey: settings.MISTRAL_API_KEY })) }`, then aliases name `"mistral:<model id>"`. When the app uses LangChain agents, give them Inferlo's model and tools: `toLangChainModel(ai, { model: "fast", for: user.id })` and `toLangChainTools([getWeather, createNote], { ai })` from `@browserlessapi/inferlo/langchain`, never a second set of provider keys. 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). Streaming to a chat UI built with the Vercel AI SDK (`useChat`): `route.post("/chat", { body: uiChatBody }).handle(({ body, ai, user }) => ai.stream({ model: "fast", messages: fromUIMessages(body.messages), for: user.id }).toResponse({ format: "ai-sdk" }))`.
 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({})`).
+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 (or with `createApp({ redis, jobQueue: { store: "redis" } })` in Redis) 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({})`). When other parts of the app react to something that happened, publish an event instead of enqueuing each job: `export const orderPaid = event("order.paid", { payload: t.object({ ... }) })` in `src/events.ts`, jobs subscribed with `on(orderPaid, sendReceipt)` (the job's input is `orderPaid.payload`) in `src/jobs.ts`, and `await ctx.events.publish(orderPaid, { ... })` after the change is saved. To send events to other services, give each service a `name` and set `createApp({ name, redis, events: { transport: "redis" } })`; subscribers use the same `on(event, job)`.
 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.
+17. **Large apps: feature modules.** When the app grows to several features, group each feature's models, routes and jobs in `src/<feature>/module.ts` with `export const billing = module("billing", { imports: [users], models: [...], routes: [routes], jobs: [jobs], provides: { createInvoice } })` and register it with `createApp({ modules: [users, billing] })`. A module that uses another module's models or `provides` lists it in `imports` (IL6023 and IL6024 tell you when one is missing). Call other modules only through their `provides`; never import their internal files. Keep every model in `Register` in `src/models.ts`.
+18. **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. For a breaking change to many routes, publish a new API version instead: `createApp({ routes: [apiVersion("v1", [notesV1]), apiVersion("v2", [notes])] })` serves them under `/v1` and `/v2`, each with its own OpenAPI document (`/v1/openapi.json`); write route paths without the version prefix.
+19. **Caching:** for results that are slow or expensive to compute, use the built-in cache instead of a module-level `Map`: `` return cache.getOrSet(`notes:stats:${user.id}`, { ttlMs: 60_000, tags: ["notes"] }, () => computeStats(db, user.id)) `` in routes and jobs (`ctx.cache`), and `await cache.invalidate("notes")` after notes change. `ttlMs` is required; put the user id in the key of anything that differs per user; values come back as JSON (dates as strings). To cache a whole GET route instead, add the route option `cache: { ttlMs: 60_000, tags: ["notes"] }` (one response per user by default; `by: "public"` only for data that is the same for everyone) and invalidate the tag where the data changes. With several instances, use `createApp({ cache: { store: "database" } })`.
+20. **Calling another Inferlo service:** `const tickets = serviceClient({ baseUrl: settings.TICKETS_URL, token: settings.TICKETS_TOKEN })`, then in a handler `await tickets.call(getTicket, { params: { id }, ctx })` with the other service's route imported, so the call is typed. Catch `ServiceCallError` and check `error.remoteStatus` for answers you expect (404). Never build these URLs with `fetch` by hand. When the app uses `tracing: { api: otel }`, pass the same `tracing` to `serviceClient` so calls join the trace.
+21. **Data of many organisations (multi-tenant):** give the signed-in user a `tenantId` (the organisation's id) and make tables whose rows belong to one organisation tenant-scoped: `model("projects", { ... }, { tenant: true })`. `ctx.db` then filters every query by and stamps every insert with the user's tenant, so never add `tenantId` to a `where`, a body schema or an insert. Jobs queued (or events published) by a request run for the request's tenant: their `ctx.db` is scoped the same way, so do not pass the tenant id in the job input. In scripts use `app.db.$tenant(tenantId).projects`, and `app.jobs.enqueue(job, input, { tenantId })`. For limits and caches shared by an organisation use `rateLimit: { max, per, by: "tenant" }` and `cache: { ttlMs, by: "tenant" }`; `ctx.audit` records the tenant itself.
 
 ## Testing