@browserlessapi/inferlo 0.7.0 → 0.8.0

package/dist/postgres-js.d.ts

@@ -0,0 +1,39 @@
+/** The part of a postgres.js `sql` instance or reserved connection Inferlo's queries use. */
+export interface PostgresJsQueryable {
+    unsafe(query: string, parameters?: any[]): PromiseLike<unknown[] & {
+        count?: number | null;
+    }>;
+}
+/** The parts of a postgres.js `sql` instance Inferlo uses: queries, and reserve() for transactions. */
+export interface PostgresJsSql extends PostgresJsQueryable {
+    reserve(): Promise<PostgresJsQueryable & {
+        release(): void;
+    }>;
+}
+/**
+ * What `db.$pgClient()` returns with postgresJsPool(): `sql` is the pool's instance, or inside db.$transaction
+ * the transaction's reserved connection: `tx.$pgClient<PostgresJsClient<ReservedSql>>()` with
+ * `import type { ReservedSql } from "postgres"`.
+ */
+export interface PostgresJsClient<S = PostgresJsQueryable> {
+    /** postgres.js on the pool, or inside db.$transaction the transaction's reserved connection: `await sql\`...\``. */
+    readonly sql: S;
+    query(text: string, params?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+        rowCount: number | null;
+    }>;
+}
+/** The pool that postgres({ pool }) takes. */
+export interface PostgresJsPool<S = PostgresJsSql> extends PostgresJsClient<S> {
+    connect(): Promise<PostgresJsClient & {
+        release(): void;
+    }>;
+    /** Does nothing: the app created `sql` and ends it with `await sql.end()` after `app.close()`. */
+    end(): Promise<void>;
+}
+/**
+ * A postgres.js `sql` instance as the pool of Inferlo's Postgres adapter: `postgres({ pool: postgresJsPool(sql) })`.
+ * Inferlo's queries and transactions use postgres.js's connections; `tx.$pgClient<PostgresJsClient>()` gives the
+ * transaction's connection as `sql`.
+ */
+export declare function postgresJsPool<S extends PostgresJsSql>(sql: S): PostgresJsPool<S>;

package/dist/postgres-js.js

@@ -0,0 +1,71 @@
+/**
+ * postgres.js (the `postgres` package) as the connection pool of Inferlo's Postgres adapter, so an app that uses
+ * postgres.js keeps one pool and writes postgres.js queries and Inferlo models in one transaction.
+ *
+ *   import postgresJs from "postgres";
+ *   import { postgres } from "@browserlessapi/inferlo/postgres";
+ *   import { postgresJsPool } from "@browserlessapi/inferlo/postgres-js";
+ *
+ *   export const sql = postgresJs(process.env.DATABASE_URL!, { max: 10 });
+ *   createApp({ db: postgres({ pool: postgresJsPool(sql) }), ... });
+ *
+ *   db.$transaction(async (tx) => {
+ *     const { sql } = await tx.$pgClient<PostgresJsClient>(); // the transaction's connection
+ *     await sql`insert into crm_contacts ${sql({ email })}`;
+ *     await tx.contact_notes.insert({ ... });
+ *   });
+ *
+ * postgres.js is an optional peer dependency (3.4 and later); this entry point never imports it, it only uses the
+ * `sql` instance it is given. No runtime dependencies.
+ */
+import { InferloError } from "./errors.js";
+/** postgres.js errors name the table and constraint differently from pg; Inferlo's errors read pg's names. */
+function asPgError(error) {
+    if (error && typeof error === "object") {
+        const e = error;
+        if (e.table === undefined && typeof e.table_name === "string")
+            e.table = e.table_name;
+        if (e.constraint === undefined && typeof e.constraint_name === "string")
+            e.constraint = e.constraint_name;
+    }
+    return error;
+}
+function client(sql) {
+    return {
+        sql,
+        async query(text, params = []) {
+            try {
+                // Inferlo builds each statement from model definitions and sends every value as a parameter.
+                const result = await sql.unsafe(text, params);
+                return { rows: [...result], rowCount: typeof result.count === "number" ? result.count : null };
+            }
+            catch (error) {
+                throw asPgError(error);
+            }
+        },
+    };
+}
+/**
+ * A postgres.js `sql` instance as the pool of Inferlo's Postgres adapter: `postgres({ pool: postgresJsPool(sql) })`.
+ * Inferlo's queries and transactions use postgres.js's connections; `tx.$pgClient<PostgresJsClient>()` gives the
+ * transaction's connection as `sql`.
+ */
+export function postgresJsPool(sql) {
+    const given = sql;
+    const parts = given;
+    if (typeof given !== "function" || typeof parts.unsafe !== "function" || typeof parts.reserve !== "function") {
+        throw new InferloError("IL4029", "postgresJsPool(sql) needs a postgres.js sql instance (3.4 or later).", {
+            fix: 'Create it with postgres.js and pass it: import postgresJs from "postgres"; const sql = postgresJs(process.env.DATABASE_URL); postgres({ pool: postgresJsPool(sql) }).',
+        });
+    }
+    return {
+        ...client(sql),
+        async connect() {
+            // A reserved connection: postgres.js keeps it for this transaction until release().
+            const reserved = await sql.reserve();
+            return { ...client(reserved), release: () => reserved.release() };
+        },
+        async end() { },
+    };
+}
+//# sourceMappingURL=postgres-js.js.map

package/dist/postgres-js.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-js.js","sourceRoot":"","sources":["../src/postgres-js.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA+B3C,8GAA8G;AAC9G,SAAS,SAAS,CAAC,KAAc;IAC/B,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,KAAmG,CAAC;QAC9G,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;YAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,UAAU,CAAC;QACtF,IAAI,CAAC,CAAC,UAAU,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,eAAe,KAAK,QAAQ;YAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,eAAe,CAAC;IAC5G,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,MAAM,CAAgC,GAAM;IACnD,OAAO;QACL,GAAG;QACH,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,EAAE;YAC3B,IAAI,CAAC;gBACH,6FAA6F;gBAC7F,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBAC9C,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,MAAM,CAA8B,EAAE,QAAQ,EAAE,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAC9H,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAA0B,GAAM;IAC5D,MAAM,KAAK,GAAY,GAAG,CAAC;IAC3B,MAAM,KAAK,GAAG,KAAgD,CAAC;IAC/D,IAAI,OAAO,KAAK,KAAK,UAAU,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QAC7G,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,sEAAsE,EAAE;YACvG,GAAG,EAAE,uKAAuK;SAC7K,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,GAAG,MAAM,CAAC,GAAG,CAAC;QACd,KAAK,CAAC,OAAO;YACX,oFAAoF;YACpF,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;YACrC,OAAO,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC;QACpE,CAAC;QACD,KAAK,CAAC,GAAG,KAAI,CAAC;KACf,CAAC;AACJ,CAAC"}

package/dist/redis-sockets.d.ts

@@ -0,0 +1,24 @@
+import type { RedisClient } from "./redis.ts";
+import type { SocketRelay } from "./sockets.ts";
+/**
+ * A second, connected Redis client for receiving broadcasts: a client in subscriber mode cannot send other
+ * commands, so it cannot be the createApp({ redis }) client. With the redis package: await redis.duplicate().connect().
+ * For ioredis, pass { subscribe: async (channel, listener) => { sub.on("message", (c, m) => c === channel && listener(m)); await sub.subscribe(channel); }, unsubscribe: (channel) => sub.unsubscribe(channel) }.
+ */
+export interface RedisSubscriber {
+    subscribe(channel: string, listener: (message: string, channel: string) => void): Promise<unknown>;
+    unsubscribe(channel: string): Promise<unknown>;
+}
+export interface SocketsConfig {
+    /**
+     * How broadcasts reach the sockets of other instances. Default: none, sockets.broadcast reaches the sockets of this
+     * process only. "redis": Redis Pub/Sub in the Redis of createApp({ redis }) (needs name and subscriber), so a
+     * broadcast from any instance or from inferlo worker reaches every instance's sockets in the room.
+     */
+    transport?: "redis";
+    /** With transport "redis": a second connected Redis client that receives broadcasts (await redis.duplicate().connect()). */
+    subscriber?: RedisSubscriber;
+}
+/** Checks createApp({ sockets }) at startup and returns the subscriber for transport "redis". Raises IL6036. */
+export declare function checkSocketsConfig(config: unknown, redis: RedisClient | undefined, name: string | undefined): RedisSubscriber | undefined;
+export declare function redisSocketRelay(client: RedisClient, subscriber: RedisSubscriber, channel: string, onError: (message: string, error?: unknown) => void): SocketRelay;

package/dist/redis-sockets.js

@@ -0,0 +1,75 @@
+/**
+ * WebSocket broadcasts across instances over Redis Pub/Sub:
+ * createApp({ name: "boards", redis, sockets: { transport: "redis", subscriber: await redis.duplicate().connect() } }).
+ *
+ * Every broadcast is sent to the sockets of this process and published on one channel per app,
+ * inferlo:<app name>:sockets, as JSON { o: instance id, k: room key (with the tenant), d: message text }. Each
+ * instance with open sockets subscribes to the channel (on its first WebSocket connection) and sends what other
+ * instances published to its own sockets in that room. Pub/Sub keeps nothing: an instance that is not subscribed
+ * when a broadcast is published does not get it, as with sockets that join a room after a broadcast.
+ */
+import { InferloError } from "./errors.js";
+const FIX = 'Use createApp({ name: "boards", redis, sockets: { transport: "redis", subscriber: await redis.duplicate().connect() } }), with redis = await createClient({ url: process.env.REDIS_URL }).connect().';
+function invalid(message) {
+    return new InferloError("IL6036", message, { fix: FIX });
+}
+/** Checks createApp({ sockets }) at startup and returns the subscriber for transport "redis". Raises IL6036. */
+export function checkSocketsConfig(config, redis, name) {
+    if (config === undefined)
+        return undefined;
+    if (typeof config !== "object" || config === null || Array.isArray(config))
+        throw invalid("createApp({ sockets }) must be an object.");
+    const { transport, subscriber } = config;
+    const unknown = Object.keys(config).filter((key) => key !== "transport" && key !== "subscriber");
+    if (unknown.length)
+        throw invalid(`Unknown sockets option ${unknown.map((key) => `"${key}"`).join(", ")}.`);
+    if (transport === undefined) {
+        if (subscriber !== undefined)
+            throw invalid('sockets.subscriber is only used with transport "redis".');
+        return undefined;
+    }
+    if (transport !== "redis")
+        throw invalid(`Invalid sockets transport ${JSON.stringify(transport)}: the only transport is "redis".`);
+    if (!redis)
+        throw invalid('sockets transport "redis" needs a Redis client, but createApp has no redis option.');
+    // Instances find each other by the channel named after the app, so apps sharing one Redis must have names.
+    if (!name)
+        throw invalid('sockets transport "redis" needs createApp({ name }): the instances of an app share one channel, named after the app.');
+    if (typeof subscriber !== "object" || subscriber === null || typeof subscriber.subscribe !== "function" || typeof subscriber.unsubscribe !== "function") {
+        throw invalid('sockets transport "redis" needs a subscriber: a second connected Redis client with subscribe and unsubscribe.');
+    }
+    if (subscriber === redis)
+        throw invalid("sockets.subscriber must be a second Redis client, not the createApp({ redis }) client: a subscribed client cannot send other commands.");
+    return subscriber;
+}
+export function redisSocketRelay(client, subscriber, channel, onError) {
+    const instance = crypto.randomUUID();
+    let listener;
+    return {
+        async publish(key, text) {
+            await client.sendCommand(["PUBLISH", channel, JSON.stringify({ o: instance, k: key, d: text })]);
+        },
+        async start(deliver) {
+            listener = (message) => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(String(message));
+                }
+                catch (error) {
+                    return onError(`ignored a message on ${channel} that is not JSON`, error);
+                }
+                if (parsed.o === instance)
+                    return;
+                if (typeof parsed.k !== "string" || typeof parsed.d !== "string")
+                    return onError(`ignored a message on ${channel} without a room and data`);
+                deliver(parsed.k, parsed.d);
+            };
+            await subscriber.subscribe(channel, (message) => listener?.(message));
+        },
+        async stop() {
+            listener = undefined;
+            await subscriber.unsubscribe(channel);
+        },
+    };
+}
+//# sourceMappingURL=redis-sockets.js.map

package/dist/redis-sockets.js.map

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

package/dist/route.d.ts

@@ -9,15 +9,17 @@
  * Secure by default: routes require a signed-in user unless you set auth: "public".
  */
 import type { Deprecation } from "./deprecation.ts";
-import type { AI } from "./ai/index.ts";
+import type { AI, StreamResult, Usage } from "./ai/index.ts";
 import type { Db } from "./db/table.ts";
 import type { Events } from "./events.ts";
 import type { Jobs } from "./jobs.ts";
 import type { AnyModel } from "./model.ts";
 import type { Audit } from "./audit.ts";
 import type { Cache, RouteCache } from "./cache.ts";
+import type { Storage } from "./storage.ts";
 import type { PermissionInput, Permissions } from "./permissions.ts";
 import type { RateLimit } from "./rate-limit.ts";
+import type { Sockets } from "./sockets.ts";
 import type { AnySchema, Infer, InferInput, ObjectSchema } from "./schema.ts";
 /**
  * Register your app's models and user type once, so every handler is fully typed:
@@ -64,7 +66,7 @@ export interface RouteOptions<B extends AnySchema | undefined, Q extends ObjectS
      * resource, call access.authorize(name, { user, ticket }) in the handler instead. Typed from Register's permissions.
      */
     permission?: AppPermission;
-    /** Request body schema (JSON or form). */
+    /** Request body schema: JSON, a URL-encoded form, or multipart/form-data when it has t.file() fields. */
     body?: B;
     /** Query string schema. Strings are converted to numbers and booleans automatically. */
     query?: Q;
@@ -117,6 +119,10 @@ export interface Context<Body, Query, Params, User> {
     events: Events;
     /** The app cache: await cache.getOrSet(key, { ttlMs: 60_000, tags: ["tickets"] }, compute), cache.invalidate("tickets"). */
     cache: Cache;
+    /** Files (createApp({ storage })): await storage.put(`avatars/${user.id}.png`, body.avatar), storage.get(key), storage.delete(key). */
+    storage: Storage;
+    /** Send to WebSocket rooms: await sockets.broadcast(`project:${id}`, data), to the user's tenant's room with a tenant. */
+    sockets: Sockets;
     req: Request;
     url: URL;
     headers: Headers;
@@ -162,6 +168,8 @@ export interface RouteDef {
     name?: string;
     /** API version ("v1") when the route comes from apiVersion("v1", routes). */
     readonly version?: string;
+    /** Set for WebSocket routes from route.ws(): the handler runs once per message instead of once per request. */
+    readonly websocket?: true;
 }
 export declare class RouteBuilder<Path extends string, B extends AnySchema | undefined, Q extends ObjectSchema<any> | undefined, P extends ObjectSchema<any> | undefined, A> {
     readonly method: Method;
@@ -174,6 +182,92 @@ export declare class RouteBuilder<Path extends string, B extends AnySchema | und
         readonly $input: RouteInput<Path, B, Q, P>;
     };
 }
+export interface SocketRouteOptions<M extends AnySchema | undefined, Q extends ObjectSchema<any> | undefined, P extends ObjectSchema<any> | undefined> {
+    /** Who may connect. Default "user" (signed in), checked once when the socket opens. */
+    auth?: Auth;
+    /** A permission from createApp({ permissions }) the user must have to connect (checked with { user }). */
+    permission?: AppPermission;
+    /** Schema of each message (JSON text). A message that does not match gets an IL1001 error message back. */
+    message?: M;
+    /** Query string schema of the connection URL. */
+    query?: Q;
+    /** Path parameter schema. Without it, path params are strings. */
+    params?: P;
+    /**
+     * Limit connections and messages per user, tenant or IP: { max: 30, per: "minute", by: "user" }. Opening the
+     * socket and every message count. A refused connection answers 429; a message over the limit gets an IL2005 error message.
+     */
+    rateLimit?: RateLimit;
+    /** One line shown in describe. */
+    summary?: string;
+    description?: string;
+    tags?: string[];
+}
+/** The open connection, in a WebSocket handler. */
+export interface Socket {
+    /** A random id for this connection. */
+    readonly id: string;
+    /** Send a message to this client, as JSON. Does nothing once the socket is closed. */
+    send(data: unknown): void;
+    /** Close the connection: code 1000 (normal) by default. */
+    close(code?: number, reason?: string): void;
+    /**
+     * Join a room, so sockets.broadcast(room, data) reaches this client. Rooms are per tenant: with a signed-in user
+     * who has a tenant, the room is that tenant's. A closed socket leaves every room.
+     */
+    join(room: string): void;
+    /** Leave a room joined with socket.join(room). */
+    leave(room: string): void;
+    /**
+     * Stream a model's answer to this client: await socket.stream(ai.stream({ model: "fast", prompt })) sends
+     * { type: "text", text } for each chunk as it arrives, then { type: "done", usage }, and resolves with the full
+     * text and usage. Streams from ctx.ai stop when the socket closes (ctx.signal).
+     */
+    stream(result: StreamResult): Promise<{
+        text: string;
+        usage: Usage;
+    }>;
+}
+export interface SocketContext<Message, Query, Params, User> {
+    /** This message, validated against the route's message schema. */
+    message: Message;
+    query: Query;
+    params: Params;
+    /** The user who opened the socket (null only on public routes with no session). */
+    user: User;
+    socket: Socket;
+    db: AppDb;
+    ai: AI;
+    jobs: Jobs;
+    events: Events;
+    cache: Cache;
+    /** Files (createApp({ storage })), the same as ctx.storage in routes. */
+    storage: Storage;
+    /** Send to WebSocket rooms, this client's included when it joined: await sockets.broadcast(room, data). */
+    sockets: Sockets;
+    /** Write an audit log entry with the user and this connection's request id. */
+    audit: Audit;
+    /** Aborted when the socket closes. ctx.ai calls use it automatically. */
+    signal: AbortSignal;
+    /** The id of the request that opened the socket, also in its log entries. */
+    requestId: string;
+    /** URL and headers of the request that opened the socket. */
+    url: URL;
+    headers: Headers;
+}
+export declare class SocketRouteBuilder<Path extends string, M extends AnySchema | undefined, Q extends ObjectSchema<any> | undefined, P extends ObjectSchema<any> | undefined, A> {
+    readonly path: Path;
+    readonly options: SocketRouteOptions<M, Q, P>;
+    constructor(path: Path, options: SocketRouteOptions<M, Q, P>);
+    /**
+     * The message handler, run for each message in the order they arrive. Return data to send it back as JSON, or
+     * nothing; call ctx.socket.send(data) to send more. A thrown error is sent back as an error message (the socket stays open).
+     */
+    handle<R>(handler: Handler<SocketContext<M extends AnySchema ? Infer<M> : unknown, Q extends AnySchema ? Infer<Q> : Record<string, string | undefined>, P extends AnySchema ? Infer<P> : PathParams<Path>, UserFor<A>>, R>): RouteDef & {
+        readonly $message: M extends AnySchema ? InferInput<M> : unknown;
+        readonly $reply: Awaited<R>;
+    };
+}
 export declare const route: {
     get: <const Path extends string, B extends AnySchema | undefined = undefined, Q extends ObjectSchema<any> | undefined = undefined, P extends ObjectSchema<any> | undefined = undefined, const A extends Auth = "user">(path: Path, options?: RouteOptions<B, Q, P> & {
         auth?: A;
@@ -190,6 +284,13 @@ export declare const route: {
     delete: <const Path extends string, B extends AnySchema | undefined = undefined, Q extends ObjectSchema<any> | undefined = undefined, P extends ObjectSchema<any> | undefined = undefined, const A extends Auth = "user">(path: Path, options?: RouteOptions<B, Q, P> & {
         auth?: A;
     }) => RouteBuilder<Path, B, Q, P, A>;
+    /**
+     * A WebSocket route: route.ws("/chat", { message: t.object({ text: t.string() }) }).handle(({ message, user, socket }) => ...).
+     * Same auth, permissions and rate limits as HTTP routes; each JSON message is validated and handled in order.
+     */
+    ws: <const Path extends string, M extends AnySchema | undefined = undefined, Q extends ObjectSchema<any> | undefined = undefined, P extends ObjectSchema<any> | undefined = undefined, const A extends Auth = "user">(path: Path, options?: SocketRouteOptions<M, Q, P> & {
+        auth?: A;
+    }) => SocketRouteBuilder<Path, M, Q, P, A>;
 };
 export declare function isRoute(value: unknown): value is RouteDef;
 /** The routes in route sources: routes, arrays and modules (import * as tickets), named after their exports. */

package/dist/route.js

@@ -15,12 +15,39 @@ export class RouteBuilder {
 function builder(method) {
     return (path, options = {}) => new RouteBuilder(method, path, options);
 }
+export class SocketRouteBuilder {
+    path;
+    options;
+    constructor(path, options) {
+        this.path = path;
+        this.options = options;
+    }
+    /**
+     * The message handler, run for each message in the order they arrive. Return data to send it back as JSON, or
+     * nothing; call ctx.socket.send(data) to send more. A thrown error is sent back as an error message (the socket stays open).
+     */
+    handle(handler) {
+        return {
+            kind: "inferlo.route",
+            method: "GET",
+            path: this.path,
+            options: this.options,
+            handler: handler,
+            websocket: true,
+        };
+    }
+}
 export const route = {
     get: builder("GET"),
     post: builder("POST"),
     put: builder("PUT"),
     patch: builder("PATCH"),
     delete: builder("DELETE"),
+    /**
+     * A WebSocket route: route.ws("/chat", { message: t.object({ text: t.string() }) }).handle(({ message, user, socket }) => ...).
+     * Same auth, permissions and rate limits as HTTP routes; each JSON message is validated and handled in order.
+     */
+    ws: (path, options = {}) => new SocketRouteBuilder(path, options),
 };
 export function isRoute(value) {
     return typeof value === "object" && value !== null && value.kind === "inferlo.route";

package/dist/route.js.map

@@ -1 +1 @@
-{"version":3,"file":"route.js","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"AA2KA,MAAM,OAAO,YAAY;IACd,MAAM,CAAS;IACf,IAAI,CAAO;IACX,OAAO,CAAwB;IAExC,YAAY,MAAc,EAAE,IAAU,EAAE,OAA8B;QACpE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,qFAAqF;IACrF,MAAM,CACJ,OAQC;QAED,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAuC,EAG5I,CAAC;IACJ,CAAC;CACF;AAED,SAAS,OAAO,CAAC,MAAc;IAC7B,OAAO,CAOL,IAAU,EACV,UAAgD,EAAE,EAClD,EAAE,CAAC,IAAI,YAAY,CAAmB,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC;CAC1B,CAAC;AAEF,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAAkB,CAAC,IAAI,KAAK,eAAe,CAAC;AACrG,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAW,CAAC;IAChC,MAAM,KAAK,GAAG,CAAC,MAAe,EAAE,IAAa,EAAE,EAAE;QAC/C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,OAAO;QACtE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjB,IAAI,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACpB,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAC9D,OAAO;QACT,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,KAAK,MAAM,IAAI,IAAI,MAAM;gBAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACvC,OAAO;QACT,CAAC;QACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,KAAK,CAAC,KAAK,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACnJ,CAAC,CAAC;IACF,KAAK,CAAC,OAAO,CAAC,CAAC;IACf,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -6,7 +6,7 @@
  *   type User = Infer<typeof User>
  */
 import { InferloError } from "./errors.ts";
-export type Kind = "string" | "text" | "email" | "url" | "uuid" | "ref" | "number" | "int" | "boolean" | "date" | "enum" | "literal" | "json" | "array" | "object" | "any";
+export type Kind = "string" | "text" | "email" | "url" | "uuid" | "ref" | "number" | "int" | "boolean" | "date" | "enum" | "literal" | "json" | "array" | "object" | "file" | "any";
 export interface Def {
     kind: Kind;
     optional: boolean;
@@ -17,6 +17,8 @@ export interface Def {
     max?: number;
     pattern?: RegExp;
     values?: readonly (string | number | boolean)[];
+    /** t.file(): accepted media types ("image/png", "image/*"); empty means any type. */
+    fileTypes?: readonly string[];
     item?: AnySchema;
     shape?: Shape;
     unknownKeys?: "strict" | "strip";
@@ -159,6 +161,24 @@ export declare const t: {
         onDelete?: "restrict" | "cascade" | "set null";
     }) => RefSchema<Table, string, string>;
     any: () => Schema<unknown, unknown>;
+    /**
+     * An uploaded file in a multipart/form-data body: body: t.object({ avatar: t.file({ maxBytes: 2_000_000, types: ["image/png", "image/jpeg"] }) }).
+     * The handler gets a web File. maxBytes defaults to 10 MiB; types defaults to any type. Only in route bodies.
+     */
+    file: (options?: FileOptions) => Schema<File, File>;
 };
+/** Options of t.file(). */
+export interface FileOptions {
+    /** Largest accepted file in bytes. Default 10 MiB (10485760). */
+    maxBytes?: number;
+    /** Accepted media types, exact ("image/png") or by family ("image/*"). Default: any type. */
+    types?: readonly string[];
+}
+/** Default t.file() limit: 10 MiB. */
+export declare const DEFAULT_FILE_MAX_BYTES: number;
+/** Whether a media type ("image/png; x=1") is one of the accepted types (exact or "image/*"). */
+export declare function fileTypeAccepted(type: string, accepted: readonly string[]): boolean;
+/** Whether a schema has a t.file() anywhere in it. */
+export declare function containsFile(schema: AnySchema): boolean;
 export declare function toJSONSchema(schema: AnySchema): JSONSchema;
 export {};

package/dist/schema.js

@@ -179,7 +179,58 @@ export const t = {
     /** Id of a row in another model's table: t.ref("users"). */
     ref: (table, options = {}) => new RefSchema(base("ref", { refTable: table, onDelete: options.onDelete ?? "restrict" })),
     any: () => new Schema(base("any", { optional: true })),
+    /**
+     * An uploaded file in a multipart/form-data body: body: t.object({ avatar: t.file({ maxBytes: 2_000_000, types: ["image/png", "image/jpeg"] }) }).
+     * The handler gets a web File. maxBytes defaults to 10 MiB; types defaults to any type. Only in route bodies.
+     */
+    file: (options = {}) => new Schema(fileDef(options)),
 };
+/** Default t.file() limit: 10 MiB. */
+export const DEFAULT_FILE_MAX_BYTES = 10 * 1024 * 1024;
+const MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/([a-z0-9][a-z0-9!#$&^_.+-]*|\*)$/;
+function fileDef(options) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new InferloError("IL1004", "t.file() takes an options object.", { fix: 't.file({ maxBytes: 2_000_000, types: ["image/png", "image/jpeg"] }), or t.file() for any file up to 10 MiB.' });
+    }
+    for (const key of Object.keys(options)) {
+        if (key !== "maxBytes" && key !== "types") {
+            throw new InferloError("IL1004", `Unknown t.file() option "${key}".${didYouMean(key, ["maxBytes", "types"])}`, { fix: "t.file() takes maxBytes and types." });
+        }
+    }
+    const maxBytes = options.maxBytes ?? DEFAULT_FILE_MAX_BYTES;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new InferloError("IL1004", `t.file({ maxBytes }) must be a whole number of bytes above 0, got ${String(options.maxBytes)}.`, { fix: "Use t.file({ maxBytes: 5 * 1024 * 1024 }) for 5 MiB." });
+    }
+    const types = options.types ?? [];
+    if (!Array.isArray(types) || types.some((type) => typeof type !== "string" || !MEDIA_TYPE.test(type.toLowerCase()))) {
+        throw new InferloError("IL1004", `t.file({ types }) must be a list of media types such as "image/png" or "image/*", got ${JSON.stringify(options.types)}.`, { fix: 'Use t.file({ types: ["image/png", "image/jpeg"] }), or leave types out to accept any type.' });
+    }
+    return base("file", { max: maxBytes, fileTypes: types.map((type) => type.toLowerCase()) });
+}
+/** Whether a media type ("image/png; x=1") is one of the accepted types (exact or "image/*"). */
+export function fileTypeAccepted(type, accepted) {
+    if (!accepted.length)
+        return true;
+    const actual = type.split(";")[0].trim().toLowerCase();
+    return accepted.some((a) => (a.endsWith("/*") ? actual.startsWith(a.slice(0, -1)) : actual === a));
+}
+/** Whether a schema has a t.file() anywhere in it. */
+export function containsFile(schema) {
+    // Not a schema at all (a mistake reported by the caller's own checks): no files.
+    const def = schema?.def;
+    if (!def || typeof def !== "object")
+        return false;
+    if (def.kind === "file")
+        return true;
+    if (def.kind === "array")
+        return def.item !== undefined && containsFile(def.item);
+    if (def.kind === "object")
+        return Object.values(def.shape ?? {}).some(containsFile);
+    return false;
+}
+function isFile(value) {
+    return typeof Blob !== "undefined" && value instanceof Blob;
+}
 // ---------------------------------------------------------------------------------------------
 // Validation
 // ---------------------------------------------------------------------------------------------
@@ -236,6 +287,18 @@ function check(schema, raw, path, issues, options) {
         case "any":
         case "json":
             return value;
+        case "file": {
+            if (!isFile(value))
+                return fail("invalid_type", `Expected a file, got ${describeType(value)}. Send the body as multipart/form-data.`);
+            if (def.max !== undefined && value.size > def.max)
+                return fail("file_too_large", `File is ${value.size} bytes, at most ${def.max} bytes are accepted.`);
+            if (def.min !== undefined && value.size < def.min)
+                return fail("file_too_small", `File must be at least ${def.min} bytes.`);
+            const types = def.fileTypes ?? [];
+            if (!fileTypeAccepted(value.type, types))
+                return fail("file_type", `File type ${JSON.stringify(value.type || "unknown")} is not accepted. Expected ${types.join(", ")}.`);
+            return value;
+        }
         case "string":
         case "text":
         case "email":
@@ -418,6 +481,13 @@ export function toJSONSchema(schema) {
                 out.required = required;
             break;
         }
+        case "file":
+            // OpenAPI 3.1 file in a multipart body; the accepted types go in the request body's encoding.
+            out = { type: "string", format: "binary" };
+            if (def.fileTypes?.length === 1)
+                out.contentMediaType = def.fileTypes[0];
+            out["x-inferlo-max-bytes"] = def.max;
+            break;
         case "json":
         case "any":
             out = {};