@browserlessapi/inferlo 0.0.0-stage → 0.4.0

package/dist/errors.js

@@ -0,0 +1,99 @@
+/**
+ * Every error Inferlo raises has a stable code, a plain cause, a suggested fix and a docs link.
+ * Error codes never change meaning once released, so AI models and humans can rely on them.
+ */
+export const DOCS_BASE = "https://github.com/BrowserlessAPI/Inferlo/blob/main/docs/errors.md";
+export function docsUrl(code) {
+    return `${DOCS_BASE}#${code.toLowerCase()}`;
+}
+export class InferloError extends Error {
+    code;
+    status;
+    fix;
+    details;
+    expose;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = `InferloError[${code}]`;
+        this.code = code;
+        this.status = options.status ?? 500;
+        this.fix = options.fix;
+        this.details = options.details;
+        this.expose = options.expose ?? this.status < 500;
+    }
+    get docs() {
+        return docsUrl(this.code);
+    }
+    toJSON() {
+        const error = { code: this.code, message: this.expose ? this.message : "Internal server error" };
+        if (this.expose && this.fix)
+            error.fix = this.fix;
+        if (this.expose && this.details !== undefined)
+            error.details = this.details;
+        error.docs = this.docs;
+        return { error };
+    }
+    /** Multi-line text for terminals and logs. */
+    format() {
+        const lines = [`${this.code}  ${this.message}`];
+        if (this.fix)
+            lines.push(`Fix:    ${this.fix}`);
+        lines.push(`Docs:   ${this.docs}`);
+        return lines.join("\n");
+    }
+}
+/** Throw from a handler to return an HTTP error with your own code and message. */
+export function httpError(status, message, options = {}) {
+    return new InferloError(options.code ?? `HTTP${status}`, message, { status, fix: options.fix, details: options.details, expose: true });
+}
+export function notFound(message = "Not found", details) {
+    return new InferloError("IL4001", message, { status: 404, details });
+}
+export function forbidden(message = "You do not have permission to do this.") {
+    return new InferloError("IL3002", message, { status: 403 });
+}
+export function badRequest(message, details) {
+    return new InferloError("HTTP400", message, { status: 400, details });
+}
+/** Closest candidate by edit distance, used for "did you mean" hints. */
+export function suggest(input, candidates) {
+    let best;
+    let bestScore = Infinity;
+    const lower = input.toLowerCase();
+    for (const candidate of candidates) {
+        const c = candidate.toLowerCase();
+        let score = distance(lower, c);
+        if (c.startsWith(lower) || lower.startsWith(c))
+            score = Math.min(score, 1);
+        if (score < bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    if (best === undefined)
+        return undefined;
+    const limit = Math.max(2, Math.floor(input.length / 3));
+    return bestScore <= limit ? best : undefined;
+}
+function distance(a, b) {
+    if (a === b)
+        return 0;
+    const prev = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        let diag = prev[0];
+        prev[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const above = prev[j];
+            prev[j] = Math.min(above + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+            diag = above;
+        }
+    }
+    return prev[b.length];
+}
+export function didYouMean(input, candidates) {
+    const match = suggest(input, candidates);
+    return match ? ` Did you mean "${match}"?` : "";
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Inferlo: the TypeScript backend framework with built-in AI model support.
+ * https://github.com/BrowserlessAPI/Inferlo
+ */
+export { createApp } from "./app.ts";
+export type { App, AppConfig, AuthConfig, CorsConfig, Middleware, MiddlewareContext, RequestOptions, RouteSource, Logger } from "./app.ts";
+export { route, isRoute } from "./route.ts";
+export type { Register, Context, RouteDef, RouteOptions, Auth, Method, ToolOptions, AppUser, AppDb } from "./route.ts";
+export { t, Schema, ObjectSchema, ArraySchema, RefSchema, ValidationError, toJSONSchema } from "./schema.ts";
+export type { Infer, InferInput, Issue, JSONSchema, ParseResult, Shape, AnySchema } from "./schema.ts";
+export { model, Model, columnName } from "./model.ts";
+export type { Row, CreateInput, UpdateInput, AnyModel } from "./model.ts";
+export { memory } from "./db/memory.ts";
+export { createDb, Table } from "./db/table.ts";
+export type { Db, Where, OrderBy, FindManyOptions, FindOptions, Include, Relations, ReverseRelations, WithInclude } from "./db/table.ts";
+export type { Adapter, Condition, Query, DbRecord } from "./db/types.ts";
+export { planMigration, applyMigrations } from "./db/migrate.ts";
+export type { ApplyMigrationsOptions, Migration, MigrationPlan, MigrationSnapshot, MigrationSnapshotColumn, MigrationSnapshotV1, PlanMigrationOptions, } from "./db/migrate.ts";
+export { createAI, cosineSimilarity, extractJson, openai, openaiCompatible, anthropic, gemini, ollama, mockProvider, ProviderError } from "./ai/index.ts";
+export type { AI, AIConfig, GenerateOptions, GenerateResult, StreamResult, Usage, Pricing, Provider, ProviderRequest, ProviderResponse, Image, ImageMediaType, Message, MockReply, Step, ToolCall, ToolCallResult, ToolSpec, } from "./ai/index.ts";
+export type { RateLimit, RateLimitConfig } from "./rate-limit.ts";
+export { job, isJob, retryDelayMs } from "./jobs.ts";
+export { cron, isCron } from "./cron.ts";
+export type { CronDef } from "./cron.ts";
+export type { JobDef, JobOptions, JobContext, JobInput, JobRecord, JobStatus, JobSource, JobQueueConfig, Jobs, AppJobs, EnqueueOptions, RunResult, Worker } from "./jobs.ts";
+export { bearer, hashToken, createToken, hashPassword, verifyPassword, safeEqual } from "./auth.ts";
+export { env, setEnv } from "./env.ts";
+export { InferloError, httpError, notFound, forbidden, badRequest, docsUrl } from "./errors.ts";
+export { serve } from "./serve.ts";
+export { INFERLO_VERSION } from "./describe.ts";
+export type { AppDescription } from "./describe.ts";

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * Inferlo: the TypeScript backend framework with built-in AI model support.
+ * https://github.com/BrowserlessAPI/Inferlo
+ */
+export { createApp } from "./app.js";
+export { route, isRoute } from "./route.js";
+export { t, Schema, ObjectSchema, ArraySchema, RefSchema, ValidationError, toJSONSchema } from "./schema.js";
+export { model, Model, columnName } from "./model.js";
+export { memory } from "./db/memory.js";
+export { createDb, Table } from "./db/table.js";
+export { planMigration, applyMigrations } from "./db/migrate.js";
+export { createAI, cosineSimilarity, extractJson, openai, openaiCompatible, anthropic, gemini, ollama, mockProvider, ProviderError } from "./ai/index.js";
+export { job, isJob, retryDelayMs } from "./jobs.js";
+export { cron, isCron } from "./cron.js";
+export { bearer, hashToken, createToken, hashPassword, verifyPassword, safeEqual } from "./auth.js";
+export { env, setEnv } from "./env.js";
+export { InferloError, httpError, notFound, forbidden, badRequest, docsUrl } from "./errors.js";
+export { serve } from "./serve.js";
+export { INFERLO_VERSION } from "./describe.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGrC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5C,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG7G,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGtD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAWjE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAuB1J,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGzC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACpG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/jobs.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Background jobs: work that runs after the request, with retries.
+ *
+ *   export const sendWelcome = job("send-welcome", { input: t.object({ userId: t.uuid() }) })
+ *     .handle(async ({ input, db }) => { ... })
+ *
+ *   createApp({ jobs: [jobs] })                          // import * as jobs from "./jobs.ts"
+ *   await ctx.jobs.enqueue(sendWelcome, { userId })      // in a route handler, validated
+ *
+ * Jobs are plain values like routes. The queue is kept by a JobStore; app.jobs.start() runs due
+ * jobs in this process, app.jobs.runDue() runs them once (tests).
+ */
+import type { AI } from "./ai/index.ts";
+import { type CronDef } from "./cron.ts";
+import type { Adapter } from "./db/types.ts";
+import type { AppDb } from "./route.ts";
+import { type AnySchema, type Infer, type InferInput } from "./schema.ts";
+export interface JobOptions<I extends AnySchema> {
+    /** Schema of the job's input. Checked when the job is enqueued and again when it runs. */
+    input: I;
+    /** Extra attempts after a failure, with growing delays (10s, 20s, 40s, ... up to 1 hour). Default 3. */
+    retries?: number;
+    /** One line shown in describe. */
+    summary?: string;
+}
+export interface JobContext<Input> {
+    /** The validated input. */
+    input: Input;
+    db: AppDb;
+    ai: AI;
+    /** Enqueue follow-up jobs. */
+    jobs: Jobs;
+    /** Job id. */
+    id: string;
+    /** 1 on the first run, 2 on the first retry, and so on. */
+    attempt: number;
+}
+export interface JobDef<Input = any, Output = any> {
+    readonly kind: "inferlo.job";
+    readonly name: string;
+    readonly options: JobOptions<AnySchema>;
+    readonly handler: (ctx: JobContext<Output>) => unknown;
+    /** Type only: what enqueue accepts. */
+    readonly $input?: Input;
+}
+/** What enqueue accepts for a job. */
+export type JobInput<J> = J extends JobDef<infer I, any> ? I : never;
+export interface EnqueueOptions {
+    /** Run no earlier than this time. Default: now. */
+    runAt?: Date;
+}
+export type JobStatus = "pending" | "running" | "done" | "failed";
+export interface JobRecord {
+    id: string;
+    name: string;
+    /** The input as stored (JSON). */
+    input: unknown;
+    status: JobStatus;
+    /** Runs started so far. */
+    attempts: number;
+    /** 1 + retries. */
+    maxAttempts: number;
+    /** When the job runs next (pending) or last ran. */
+    runAt: Date;
+    /** Message of the last failure. */
+    lastError?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Jobs {
+    /** Validate the input and queue the job. Returns the queued record. */
+    enqueue<J extends JobDef>(job: J, input: JobInput<J>, options?: EnqueueOptions): Promise<JobRecord>;
+}
+export interface JobQueueConfig {
+    /**
+     * Where queued jobs are kept. "memory" (default): in this process, for development and tests.
+     * "database": in the inferlo_jobs table of the app's Postgres database, shared by every instance.
+     */
+    store?: "memory" | "database";
+}
+/** Where queued jobs are kept. */
+export interface JobStore {
+    /** Add a record. A record whose id is already stored is ignored (cron ticks use fixed ids). */
+    add(record: JobRecord): Promise<void>;
+    /** Mark up to limit pending jobs named in names with runAt <= now as running (attempts + 1) and return them, oldest first. */
+    claim(now: Date, limit: number, names: readonly string[]): Promise<JobRecord[]>;
+    update(id: string, patch: Partial<Pick<JobRecord, "status" | "runAt" | "lastError">>): Promise<void>;
+    get(id: string): Promise<JobRecord | null>;
+    /** Record that a running job is still alive (database store), so it is not picked up again as stuck. */
+    touch?(id: string): Promise<void>;
+}
+export interface RunResult {
+    /** Jobs that finished. */
+    done: number;
+    /** Jobs that failed and will run again later. */
+    retried: number;
+    /** Jobs that failed for the last time. */
+    failed: number;
+}
+export interface Worker {
+    /** Stop polling and wait for running jobs to finish. */
+    stop(): Promise<void>;
+}
+/** app.jobs: enqueue, inspect and run jobs. */
+export interface AppJobs extends Jobs {
+    /** The registered jobs. */
+    readonly list: readonly JobDef[];
+    /** The registered crons: cron(schedule, job) values in createApp({ jobs }). */
+    readonly crons: readonly CronDef[];
+    /** Where queued jobs are kept (createApp({ jobQueue: { store } })). */
+    readonly queue: "memory" | "database";
+    /** A queued job by id, or null. */
+    get(id: string): Promise<JobRecord | null>;
+    /** Run every job that is due now (or at options.now), one after another, including follow-ups they enqueue, then return. For tests and scripts. */
+    runDue(options?: {
+        now?: Date;
+    }): Promise<RunResult>;
+    /** Run due jobs in this process every pollMs (default 1000) until stop() is called. Also queues each cron's job at every tick after the start. */
+    start(options?: {
+        pollMs?: number;
+    }): Worker;
+}
+/** Delay before retry n (1-based): 10s, 20s, 40s, ... at most one hour. */
+export declare function retryDelayMs(attempt: number): number;
+export declare class JobBuilder<I extends AnySchema> {
+    readonly name: string;
+    readonly options: JobOptions<I>;
+    constructor(name: string, options: JobOptions<I>);
+    /** The job's work. Throw to fail the attempt; it is retried until retries run out. */
+    handle(handler: (ctx: JobContext<Infer<I>>) => unknown): JobDef<InferInput<I>, Infer<I>>;
+}
+/** Define a background job: job("send-email", { input: t.object({ to: t.email() }) }).handle(fn). */
+export declare function job<I extends AnySchema>(name: string, options: JobOptions<I>): JobBuilder<I>;
+export declare function isJob(value: unknown): value is JobDef;
+/** Anything that contains jobs: a job, a cron, an array, or a module (import * as jobs from "./jobs.ts"). */
+export type JobSource = JobDef | CronDef | readonly JobSource[] | {
+    readonly [name: string]: unknown;
+};
+/** The jobs and crons in createApp({ jobs }). A cron's job is registered with it. */
+export declare function collectJobs(sources: readonly JobSource[] | undefined): JobDef[];
+export declare function collectCrons(sources: readonly JobSource[] | undefined): CronDef[];
+/** Jobs kept in this process. They are lost when it stops, so use it for development and tests. */
+export declare function memoryJobStore(): JobStore;
+/** A running job whose worker has not reported for this long is treated as stuck (its process stopped) and run again. */
+export declare const STALE_AFTER_MS: number;
+/** How often a worker reports that a running job is still alive. */
+export declare const HEARTBEAT_MS = 30000;
+export declare const STOPPED_MESSAGE = "The worker stopped while running this job (the process exited or lost its database connection).";
+/**
+ * Jobs in the inferlo_jobs table (created on first use), shared by every instance. Due jobs are
+ * claimed with FOR UPDATE SKIP LOCKED, so each one runs in one place. A running job whose worker
+ * stopped reporting (see STALE_AFTER_MS) is claimed again, or marked failed if it has no attempts left.
+ */
+export declare function databaseJobStore(adapter: Adapter, options?: {
+    staleAfterMs?: number;
+}): JobStore;
+/** Pick the job store for createApp({ jobQueue }). Raises IL6011 for an unknown store, IL6012 for "database" without Postgres. */
+export declare function jobStoreFor(config: JobQueueConfig | undefined, adapter: Adapter): JobStore;
+export interface JobRuntime {
+    db: AppDb;
+    ai: AI;
+    store: JobStore;
+    /** Name of the store, shown as app.jobs.queue. Default "memory". */
+    queue?: "memory" | "database";
+    /** How often a running job is reported alive to stores that support it. Default HEARTBEAT_MS. */
+    heartbeatMs?: number;
+    logger: {
+        info(message: string, data?: unknown): void;
+        error(message: string, data?: unknown): void;
+    };
+}
+/** app.jobs plus what the framework tests reach directly. */
+export interface InternalJobs extends AppJobs {
+    /** Queue the job of each cron's latest tick in (from, to]. */
+    queueCrons(from: Date, to: Date): Promise<void>;
+}
+export declare function createJobs(list: readonly JobDef[], runtime: JobRuntime, crons?: readonly CronDef[]): InternalJobs;