@ultimabase/rest 0.0.0-stage → 0.1.1

package/dist/functions.js

@@ -0,0 +1,156 @@
+import { clientOf, validate } from '@ultimabase/http';
+import { isNode, jsonSchemaOf, rowOf } from '@ultimabase/http/internal';
+import { Refused } from 'ultimabase';
+import { checkName, entryOf } from './entries.js';
+import { defaultShape, defaultVirtuals, shaped } from './fields.js';
+import { acceptsNull, isText, resolved } from './json-schema.js';
+import { anyBody } from './models.js';
+import { liveValue, wantsEvents } from './live.js';
+import { paramsOf } from './params.js';
+const none = { json: [], text: [] };
+/**
+ * A GET's parameters: an object input's keys, as GraphQL's arguments, or
+ * one `input`; a string as is, any other value as JSON.
+ */
+export function getParams(root) {
+    if (root === undefined)
+        return { accepted: none, flat: false };
+    const object = resolved(root, root);
+    const { properties } = object;
+    if (object['type'] === 'object' && isNode(properties)) {
+        const keys = Object.entries(properties);
+        const text = (node) => isNode(node) && isText(node, root);
+        return {
+            accepted: {
+                json: keys.filter(([, node]) => !text(node)).map(([key]) => key),
+                text: keys.filter(([, node]) => text(node)).map(([key]) => key),
+            },
+            flat: true,
+        };
+    }
+    const as = isText(root, root) ? 'text' : 'json';
+    return { accepted: { ...none, [as]: ['input'] }, flat: false };
+}
+const nonNull = (where) => new TypeError(`Cannot return null for non-nullable field ${where}.`);
+/** A value as GraphQL returns a function's output, a model's row its scalars. */
+function outputOf(api, output, value, where, pending) {
+    if (output.kind === 'schema')
+        return value ?? null;
+    if (value === null || value === undefined) {
+        if (output.form === 'nullable')
+            return null;
+        throw nonNull(where);
+    }
+    if (output.form === 'list') {
+        const items = Array.isArray(value) ? value : [];
+        const item = { ...output, form: 'one' };
+        return items.map((each) => outputOf(api, item, each, where, pending));
+    }
+    if (output.kind === 'model') {
+        const row = rowOf(value);
+        if (row === undefined) {
+            throw new TypeError(`A ${output.name} was returned without its id.`);
+        }
+        const entry = entryOf(api, output.name);
+        const copy = shaped(row, defaultShape(entry));
+        if (defaultVirtuals(entry).length > 0) {
+            pending.set(entry, [...(pending.get(entry) ?? []), { id: row.id, copy }]);
+        }
+        return copy;
+    }
+    const given = isNode(value) ? value : {};
+    const { type } = output;
+    return Object.fromEntries([...type.fields].map(([name, field]) => [
+        name,
+        outputOf(api, field, given[name], `${type.name}.${name}`, pending),
+    ]));
+}
+/** The default virtuals of a function's rows, read by id as the caller (D-151). */
+async function withVirtuals(pending, as) {
+    for (const [entry, rows] of pending) {
+        const names = defaultVirtuals(entry);
+        const ids = [...new Set(rows.map(({ id }) => id))];
+        const found = await entry.exposed.queries.findMany({
+            where: { id: { in: ids } },
+            take: ids.length,
+            select: Object.fromEntries([
+                ['id', true],
+                ...names.map((name) => [name, true]),
+            ]),
+        }, { as });
+        const byId = new Map(found.map((row) => [row.id, row]));
+        for (const { id, copy } of rows) {
+            // A row the caller cannot read has none (D-109).
+            for (const name of names)
+                copy[name] = byId.get(id)?.[name] ?? null;
+        }
+    }
+}
+/** Each routed function under `${base}/functions` (D-109, D-113). */
+export function functionRoutes(app, api, functions, base, live) {
+    const routed = [];
+    const owners = new Map();
+    for (const fn of functions) {
+        if (fn.with === false)
+            continue;
+        // A plugin's function is named with its plugin (D-113).
+        const owner = fn.plugin === undefined ? fn.name : `${fn.plugin}.${fn.name}`;
+        const name = checkName(fn.with?.name ?? fn.name, owner);
+        const other = owners.get(name);
+        if (other !== undefined) {
+            throw new Refused(`${owner}: the route functions/${name} is ${other}'s; set .with({ rest: { name } }).`);
+        }
+        owners.set(name, owner);
+        // GraphQL types both sides from their exports, and refuses without (D-45).
+        const { input, output } = fn;
+        const root = input === undefined
+            ? undefined
+            : jsonSchemaOf(input, 'input', `${owner}: input`);
+        routed.push({ fn, owner, name, input: root });
+        const nullable = output?.kind === 'schema'
+            ? acceptsNull(jsonSchemaOf(output.schema, 'output', `${owner}: output`))
+            : output?.form === 'nullable';
+        const answer = async (as, client, sent) => {
+            const value = await fn.run(sent, { as }, client);
+            if (output === undefined)
+                return true;
+            if (value === undefined && !nullable) {
+                throw new TypeError(`${fn.name} returned undefined; make its output .nullable() and return null.`);
+            }
+            const pending = new Map();
+            const answered = outputOf(api, output, value, fn.name, pending);
+            await withVirtuals(pending, as);
+            return answered;
+        };
+        const path = `${base}/functions/${name}`;
+        if (fn.query) {
+            const { accepted, flat } = getParams(root);
+            app.get(path, async (c) => {
+                const params = paramsOf(c.req.url, accepted);
+                const { client, sent } = clientOf(c);
+                const given = flat ? params : params['input'];
+                if (wantsEvents(c.req.raw)) {
+                    const compute = async (as) => answer(as, client, given);
+                    return sent(await liveValue(live, owner, c.req.raw, compute));
+                }
+                return sent(c.json(await answer(c.var.caller, client, given)));
+            });
+        }
+        else if (input === undefined) {
+            app.post(path, async (c) => {
+                paramsOf(c.req.url, none);
+                const { client, sent } = clientOf(c);
+                return sent(c.json(await answer(c.var.caller, client, undefined)));
+            });
+        }
+        else {
+            app.post(path, validate('json', anyBody), async (c) => {
+                paramsOf(c.req.url, none);
+                const { client, sent } = clientOf(c);
+                const body = c.req.valid('json');
+                return sent(c.json(await answer(c.var.caller, client, body)));
+            });
+        }
+    }
+    return routed;
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import type { Http } from '@ultimabase/http';
+import type { Realtime } from '@ultimabase/realtime';
+import type { PluginOf, PluginTypes, UseOf } from 'ultimabase';
+import type { RestWith } from './entries.ts';
+import type { RestFunctionWith } from './functions.ts';
+export type { RestWith } from './entries.ts';
+export type { RestFunctionWith } from './functions.ts';
+/** What `restPlugin` takes: `graphqlPlugin`'s options, by name (D-129). */
+export interface RestOptions {
+    /** `/api` by default. */
+    readonly path?: string;
+    /** Relay connections, or `take` and `skip` lists. */
+    readonly pagination?: 'connection' | 'list';
+    /** The rows a list returns when none is asked for; 100 by default (D-55). */
+    readonly take?: number;
+    /** The rows a caller other than Master may ask for; 100 by default. */
+    readonly maxTake?: number;
+    /** The deepest a request of a caller other than Master nests; 10 by default. */
+    readonly maxDepth?: number;
+    /**
+     * The most rows a request of a caller other than Master may return, each
+     * list times the lists above it; 20 000 by default.
+     */
+    readonly maxRows?: number;
+}
+/** The REST plugin's types (D-57). */
+export interface Rest extends PluginTypes {
+    readonly name: 'rest';
+    readonly appOptions: RestOptions;
+    readonly requires: Http;
+    readonly optional: Realtime;
+    readonly with: RestWith;
+    readonly functionWith: RestFunctionWith;
+}
+/** The application's REST API, served by `httpPlugin` (D-129). */
+export declare const restPlugin: PluginOf<Rest>;
+/** A model's `.with({ rest })`, from its `use` (D-129). */
+export declare const rest: UseOf<Rest>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAA;AAEpD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAG9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAE5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAKtD,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEtD,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC3B,yBAAyB;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,qDAAqD;IACrD,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,GAAG,MAAM,CAAA;IAC3C,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,uEAAuE;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,sCAAsC;AACtC,MAAM,WAAW,IAAK,SAAQ,WAAW;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAA;IAChC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAA;CACvC;AAqDD,kEAAkE;AAClE,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAiB,CAAA;AAEvD,2DAA2D;AAC3D,eAAO,MAAM,IAAI,EAAE,KAAK,CAAC,IAAI,CAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,62 @@
+import { httpPlugin, routes } from '@ultimabase/http';
+import { realtimePlugin } from '@ultimabase/realtime';
+import { definePlugin } from 'ultimabase';
+import manifest from '../package.json' with { type: 'json' };
+import { entriesOf } from './entries.js';
+import { functionRoutes } from './functions.js';
+import { modelRoutes } from './models.js';
+import { openapiOf } from './openapi.js';
+const baseOf = (options) => (options.path ?? '/api').replace(/\/+$/, '');
+// What ends each running application's event streams, by its plugin's context.
+const streams = new WeakMap();
+const plugin = definePlugin({
+    name: 'rest',
+    manifest,
+    requires: { http: httpPlugin },
+    optional: { realtime: realtimePlugin },
+    api: (context) => {
+        const { plugins, models, functions, options, logger } = context;
+        const { realtime } = plugins;
+        const ends = new Set();
+        streams.set(context, ends);
+        const live = realtime && {
+            realtime,
+            streams: ends,
+            kept: new Map(),
+            open: new Map(),
+            logger,
+        };
+        const api = {
+            entries: entriesOf(models, options),
+            pagination: options.pagination ?? 'connection',
+            take: options.take ?? 100,
+            maxDepth: options.maxDepth ?? 10,
+            maxRows: options.maxRows ?? 20_000,
+        };
+        const base = baseOf(options);
+        const app = routes();
+        const routed = functionRoutes(app, api, functions, base, live);
+        for (const entry of api.entries.values()) {
+            if (entry.visible)
+                modelRoutes(app, api, entry, base, live);
+        }
+        // Built at startup, so a name clash refuses to start (D-144).
+        const document = openapiOf(api, routed, base, manifest.version);
+        app.get(`${base}/openapi.json`, (c) => c.json(document));
+        plugins.http.mount(app);
+    },
+    start: ({ plugins, options, logger }) => {
+        if (process.env['NODE_ENV'] === 'production')
+            return;
+        logger.info(`REST on ${plugins.http.url()}${baseOf(options)}.`);
+    },
+    // Before the HTTP plugin's stop, which waits for the streams to end.
+    stop: (context) => {
+        for (const end of streams.get(context) ?? [])
+            end();
+    },
+});
+/** The application's REST API, served by `httpPlugin` (D-129). */
+export const restPlugin = plugin.plugin;
+/** A model's `.with({ rest })`, from its `use` (D-129). */
+export const rest = plugin.use;

package/dist/json-schema.d.ts

@@ -0,0 +1,8 @@
+import type { Node } from '@ultimabase/http/internal';
+/** The node a `$ref` names among the root's `$defs`, or the node itself. */
+export declare function resolved(node: Node, root: Node): Node;
+/** A value only ever a string, which a query parameter holds as is. */
+export declare function isText(node: Node, root: Node): boolean;
+/** A node that accepts `null`, as GraphQL types a nullable output. */
+export declare function acceptsNull(node: Node): boolean;
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../src/json-schema.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAA;AAGrD,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CAMrD;AAED,uEAAuE;AACvE,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,GAAG,OAAO,CAwBtD;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAO/C"}

package/dist/json-schema.js

@@ -0,0 +1,44 @@
+import { isNode } from '@ultimabase/http/internal';
+/** The node a `$ref` names among the root's `$defs`, or the node itself. */
+export function resolved(node, root) {
+    const ref = node['$ref'];
+    if (typeof ref !== 'string' || !ref.startsWith('#/$defs/'))
+        return node;
+    const defs = isNode(root['$defs']) ? root['$defs'] : {};
+    const found = defs[ref.slice(8)];
+    return isNode(found) ? found : node;
+}
+/** A value only ever a string, which a query parameter holds as is. */
+export function isText(node, root) {
+    const own = resolved(node, root);
+    const { type } = own;
+    if (type === 'string')
+        return true;
+    // `['string', 'null']`, a nullable string.
+    if (Array.isArray(type)) {
+        return (type.includes('string') &&
+            type.every((each) => each === 'string' || each === 'null'));
+    }
+    if (typeof own['const'] === 'string')
+        return true;
+    const values = own['enum'];
+    if (Array.isArray(values)) {
+        return (values.length > 0 && values.every((value) => typeof value === 'string'));
+    }
+    const variants = own['anyOf'] ?? own['oneOf'];
+    if (!Array.isArray(variants))
+        return false;
+    const kept = variants
+        .filter(isNode)
+        .filter((each) => resolved(each, root)['type'] !== 'null');
+    return kept.length > 0 && kept.every((each) => isText(each, root));
+}
+/** A node that accepts `null`, as GraphQL types a nullable output. */
+export function acceptsNull(node) {
+    const variants = node['anyOf'] ?? node['oneOf'];
+    if (Array.isArray(variants)) {
+        return variants.some((each) => isNode(each) && each['type'] === 'null');
+    }
+    const { type } = node;
+    return Array.isArray(type) ? type.includes('null') : type === 'null';
+}

package/dist/limits.d.ts

@@ -0,0 +1,6 @@
+import type { Caller } from 'ultimabase';
+import type { Api } from './entries.ts';
+import type { Shape } from './fields.ts';
+/** Refuses a request above the limits; `rows` absent checks its depth only. */
+export declare function bounded(api: Api, caller: Caller, shape: Shape, rows?: number): void;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAGxC,+EAA+E;AAC/E,wBAAgB,OAAO,CACtB,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,IAAI,CAAC,EAAE,MAAM,GACX,IAAI,CAaN"}

package/dist/limits.js

@@ -0,0 +1,17 @@
+// The limits of a request of a caller other than Master (D-107): how deep it
+// nests and, unless it is live (D-154), how many rows it may return.
+import { badInput } from '@ultimabase/http/internal';
+import { depthOf, rowsBelow } from './fields.js';
+/** Refuses a request above the limits; `rows` absent checks its depth only. */
+export function bounded(api, caller, shape, rows) {
+    if (caller.kind === 'master')
+        return;
+    const depth = depthOf(shape);
+    if (depth > api.maxDepth) {
+        throw badInput(`The request is nested ${depth} levels deep, its orderBy included; the most is ${api.maxDepth}.`);
+    }
+    if (rows === undefined || rows + rowsBelow(shape, rows) <= api.maxRows)
+        return;
+    const fewer = api.pagination === 'list' ? 'take' : 'first or last';
+    throw badInput(`The request asks for more than ${api.maxRows.toLocaleString('en-US')} rows. Ask for fewer with ${fewer}.`);
+}

package/dist/live.d.ts

@@ -0,0 +1,15 @@
+import type { Caller } from 'ultimabase';
+import type { Api, Entry } from './entries.ts';
+import type { Live } from './streams.ts';
+/** Whether `request` asks for a stream of events. */
+export declare const wantsEvents: (request: Request) => boolean;
+/** `GET /api/posts` with `Accept: text/event-stream`: a live window. */
+export declare function liveList(api: Api, live: Live | undefined, entry: Entry, caller: Caller, request: Request): Promise<Response>;
+/** `GET /api/posts/:id` with `Accept: text/event-stream`: a live row. */
+export declare function liveRow(api: Api, live: Live | undefined, entry: Entry, caller: Caller, request: Request, id: string): Promise<Response>;
+/**
+ * `GET /api/functions/:name` with `Accept: text/event-stream`: the result
+ * `compute` gives as the subscriber, again each time it changes.
+ */
+export declare function liveValue(live: Live | undefined, owner: string, request: Request, compute: (caller: Caller) => Promise<unknown>): Promise<Response>;
+//# sourceMappingURL=live.d.ts.map

package/dist/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../src/live.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAe,MAAM,YAAY,CAAA;AAErD,OAAO,KAAK,EAAE,GAAG,EAAQ,KAAK,EAAE,MAAM,cAAc,CAAA;AAKpD,OAAO,KAAK,EAAE,IAAI,EAAe,MAAM,cAAc,CAAA;AAGrD,qDAAqD;AACrD,eAAO,MAAM,WAAW,YAAa,OAAO,KAAG,OACqB,CAAA;AA0EpE,wEAAwE;AACxE,wBAAsB,QAAQ,CAC7B,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,IAAI,GAAG,SAAS,EACtB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,QAAQ,CAAC,CAyDnB;AAED,yEAAyE;AACzE,wBAAsB,OAAO,CAC5B,GAAG,EAAE,GAAG,EACR,IAAI,EAAE,IAAI,GAAG,SAAS,EACtB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,EAAE,EAAE,MAAM,GACR,OAAO,CAAC,QAAQ,CAAC,CAgBnB;AAiBD;;;GAGG;AACH,wBAAsB,SAAS,CAC9B,IAAI,EAAE,IAAI,GAAG,SAAS,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,QAAQ,CAAC,CAanB"}

package/dist/live.js

@@ -0,0 +1,168 @@
+// A live model's list and row over Server-Sent Events (D-154): the read's
+// JSON as `event: data`, then what changed as `event: live`, the JSON GraphQL
+// sends under `extensions.live`; in page mode, `event: data` each time. A
+// list first sends the token that resumes it, as `event: resume`. A live
+// function sends its whole result as `event: data` each time it changes.
+import { randomUUID } from 'node:crypto';
+import { applied, badInput, connection, run } from '@ultimabase/http/internal';
+import { PublicError } from 'ultimabase';
+import { readerOf, shaped } from './fields.js';
+import { bounded } from './limits.js';
+import { paramsOf } from './params.js';
+import { streamed } from './streams.js';
+/** Whether `request` asks for a stream of events. */
+export const wantsEvents = (request) => (request.headers.get('accept') ?? '').includes('text/event-stream');
+/** The engine, unless `entry`'s model is not live. */
+function liveOf(live, entry) {
+    const { name } = entry.model;
+    if (live !== undefined && live.realtime.live(name))
+        return live;
+    throw badInput(`${name} is not live: list realtime() in its use.`);
+}
+const fromTop = { size: undefined, backward: false };
+const paging = new Set(['take', 'skip', 'cursor']);
+/** What a live list's messages write, with what it sent so far. */
+function listWriter(events, connected, page, counted, shape) {
+    const node = (row) => shaped(row, shape);
+    let window = [];
+    let hasMore = false;
+    let count;
+    let pageInfo = '';
+    const infoOf = () => {
+        const { pageInfo: info } = connection(window, fromTop, () => null);
+        return { ...info, hasNextPage: hasMore };
+    };
+    const data = (revision) => {
+        const info = infoOf();
+        pageInfo = JSON.stringify(info);
+        const { edges } = connection(window, fromTop, node);
+        const body = connected
+            ? { edges, pageInfo: info, ...(counted && { totalCount: count }) }
+            : window.map(node);
+        events.send('data', body, revision);
+    };
+    return (message) => {
+        const { revision } = message;
+        hasMore = message.hasMore ?? hasMore;
+        count = message.totalCount ?? count;
+        if (message.kind === 'reset' || page) {
+            window =
+                message.kind === 'reset'
+                    ? message.rows
+                    : applied(window, message.changes, (row) => row);
+            return data(revision);
+        }
+        const { changes } = message;
+        window = applied(window, changes, ({ id }) => ({ id }));
+        const live = {
+            revision,
+            changes: changes.map((change) => {
+                if ('remove' in change)
+                    return change;
+                const [edge] = connection([change.upsert], fromTop, node).edges;
+                return {
+                    upsert: connected ? edge : node(change.upsert),
+                    after: change.after,
+                };
+            }),
+        };
+        if (counted && message.totalCount !== undefined) {
+            live['totalCount'] = message.totalCount;
+        }
+        const info = infoOf();
+        if (connected && JSON.stringify(info) !== pageInfo) {
+            pageInfo = JSON.stringify(info);
+            live['pageInfo'] = info;
+        }
+        events.send('live', live, revision);
+    };
+}
+/** `GET /api/posts` with `Accept: text/event-stream`: a live window. */
+export async function liveList(api, live, entry, caller, request) {
+    const followed = liveOf(live, entry);
+    const connected = api.pagination === 'connection';
+    const arg = connected ? 'first' : 'take';
+    const params = paramsOf(request.url, {
+        json: [
+            'where',
+            'orderBy',
+            'select',
+            'include',
+            arg,
+            ...(connected ? ['totalCount'] : []),
+        ],
+        text: ['mode', 'resume'],
+    });
+    const { totalCount, mode, resume, ...args } = params;
+    if (totalCount !== undefined && typeof totalCount !== 'boolean') {
+        throw badInput('totalCount must be true or false.');
+    }
+    if (mode !== undefined && mode !== 'page') {
+        throw badInput('mode must be page.');
+    }
+    const { name } = entry.model;
+    const read = await run(async () => readerOf(api, caller.kind === 'master').list(entry, args, ''));
+    const asked = args[arg];
+    const rows = typeof asked === 'number' ? asked : entry.take;
+    const page = mode === 'page';
+    if (page && rows > entry.maxTake) {
+        throw badInput(`${arg} is at most ${entry.maxTake} on ${name} in page mode.`);
+    }
+    // A live list is bounded by maxLive, not by maxRows (D-154).
+    bounded(api, caller, read.shape);
+    // The window starts at the top of its order and holds `first` rows.
+    const listed = {
+        ...Object.fromEntries(Object.entries(read.read).filter(([key]) => !paging.has(key))),
+        first: rows,
+        totalCount: totalCount === true,
+    };
+    return streamed(followed, request, read.shape, async (viewer, send) => viewer.list(name, listed, send), {
+        write: (events) => listWriter(events, connected, page, totalCount === true, read.shape),
+        signature: JSON.stringify([name, page, { ...listed, first: undefined }]),
+        first: rows,
+        resume: typeof resume === 'string' ? resume : undefined,
+    });
+}
+/** `GET /api/posts/:id` with `Accept: text/event-stream`: a live row. */
+export async function liveRow(api, live, entry, caller, request, id) {
+    const followed = liveOf(live, entry);
+    const params = paramsOf(request.url, {
+        json: ['select', 'include'],
+        // A live row is not resumed: it starts afresh.
+        text: ['resume'],
+    });
+    const { resume: _, ...fields } = params;
+    const read = await run(async () => readerOf(api, caller.kind === 'master').fields(entry, fields, ''));
+    bounded(api, caller, read.shape);
+    const args = { ...read.read, where: { id } };
+    return streamed(followed, request, read.shape, async (viewer, send) => viewer.row(entry.model.name, args, send));
+}
+/** A live function's error as its client gets it: public as is, else masked and logged. */
+function failure(error, logger) {
+    if (error instanceof PublicError) {
+        const { code, message, details } = error;
+        return details === undefined
+            ? { code, message }
+            : { code, message, details };
+    }
+    const correlationId = randomUUID();
+    logger.error({ correlationId, err: error }, 'A live function failed.');
+    return { code: 'INTERNAL', message: 'Internal error.', correlationId };
+}
+const noShape = { fields: [] };
+/**
+ * `GET /api/functions/:name` with `Accept: text/event-stream`: the result
+ * `compute` gives as the subscriber, again each time it changes.
+ */
+export async function liveValue(live, owner, request, compute) {
+    if (live === undefined || !live.realtime.liveFunction(owner)) {
+        throw badInput(`${owner} is not live: list realtime() in its use.`);
+    }
+    const { logger } = live;
+    return streamed(live, request, noShape, async (viewer, send) => viewer.value(owner, compute, (message) => {
+        if (message.kind !== 'closed' || message.error === undefined) {
+            return send(message);
+        }
+        send({ kind: 'closed', error: failure(message.error, logger) });
+    }));
+}

package/dist/models.d.ts

@@ -0,0 +1,8 @@
+import type { Routes, StandardSchema } from '@ultimabase/http';
+import type { Api, Entry } from './entries.ts';
+import type { Live } from './streams.ts';
+/** Any JSON body: the kernel checks the data (D-129). */
+export declare const anyBody: StandardSchema;
+/** Each route of a visible model, under `base`; its reads live with `live`. */
+export declare function modelRoutes(app: Routes, api: Api, entry: Entry, base: string, live: Live | undefined): void;
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAK9D,OAAO,KAAK,EAAE,GAAG,EAAQ,KAAK,EAAE,MAAM,cAAc,CAAA;AAIpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAMxC,yDAAyD;AACzD,eAAO,MAAM,OAAO,EAAE,cAErB,CAAA;AA4ED,+EAA+E;AAC/E,wBAAgB,WAAW,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,GAAG,SAAS,GACpB,IAAI,CA2EN"}