@ultimabase/rest 0.0.0-stage → 0.1.1

package/dist/openapi-models.js

@@ -0,0 +1,280 @@
+// A model's part of the document (D-144): its row, as GraphQL's type, its
+// pages, its `select` and `include`, and its six routes.
+import { isNode, jsonSchemaOf, readable, readableVirtuals, } from '@ultimabase/http/internal';
+import { entryOf, system } from './entries.js';
+import { dataOf, orderByOf, uniqueOf, valueOf, whereOf, } from './openapi-inputs.js';
+import { outputOf } from './openapi-functions.js';
+import { arrayOf, describe, described, failed, hoisted, json, objectOf, orNull, } from './openapi.js';
+const upper = (name) => name.charAt(0).toUpperCase() + name.slice(1);
+const text = { type: 'string' };
+const flag = { type: 'boolean' };
+/** `PageInfo`, `PostEdge` and a connection of its edges. */
+function connectionOf(doc, name, target) {
+    const { components } = doc;
+    return components.ref(name, () => {
+        const pageInfo = components.ref('PageInfo', () => objectOf({
+            hasNextPage: flag,
+            hasPreviousPage: flag,
+            startCursor: orNull(text),
+            endCursor: orNull(text),
+        }, ['hasNextPage', 'hasPreviousPage', 'startCursor', 'endCursor']));
+        const edge = components.ref(`${target}Edge`, () => objectOf({ cursor: text, node: rowOf(doc, target) }, ['cursor', 'node']));
+        return objectOf({
+            edges: arrayOf(edge),
+            pageInfo,
+            totalCount: { type: 'integer', minimum: 0 },
+        }, ['edges', 'pageInfo']);
+    });
+}
+/**
+ * `Post`: its default fields, which a row always holds without `select`,
+ * and its relations, which `include` adds. A field with a read rule may be
+ * `null`, a `one` relation always may (D-44).
+ */
+export function rowOf(doc, model) {
+    return doc.components.ref(model, () => {
+        const entry = entryOf(doc.api, model);
+        const date = { type: 'string', format: 'date-time' };
+        const fields = {
+            id: text,
+            createdAt: date,
+            updatedAt: date,
+        };
+        const required = [...system];
+        for (const field of readable(entry)) {
+            const ruled = entry.exposed.readRules[field.name] === 'rule';
+            if (field.kind === 'scalar') {
+                const value = valueOf(doc, entry, field, 'output');
+                const empty = ruled || (field.optional && !field.list);
+                fields[field.name] = empty ? orNull(value) : value;
+                required.push(field.name);
+            }
+            else if (field.kind === 'one') {
+                fields[field.name] = orNull(rowOf(doc, field.target));
+            }
+            else {
+                const many = doc.api.pagination === 'connection'
+                    ? connectionOf(doc, `${model}${upper(field.name)}Connection`, field.target)
+                    : arrayOf(rowOf(doc, field.target));
+                fields[field.name] = ruled ? orNull(many) : many;
+            }
+        }
+        // A virtual, computed: in the default row without an input (D-151).
+        for (const virtual of readableVirtuals(entry)) {
+            const { name } = virtual;
+            const owner = `${model}.${name}`;
+            const value = {
+                ...outputOf(doc, virtual.output, owner, `${model}${upper(name)}Output`),
+                readOnly: true,
+            };
+            const ruled = entry.exposed.readRules[name] === 'rule';
+            fields[name] = describe(ruled ? orNull(value) : value, virtual.description);
+            if (virtual.default)
+                required.push(name);
+        }
+        const { description, descriptions } = entry.exposed;
+        return describe(objectOf(described(fields, descriptions), required), description);
+    });
+}
+/** A list's page arguments, within the model's `maxTake`. */
+function pageOf(doc, entry) {
+    const rows = { type: 'integer', minimum: 0, maximum: entry.maxTake };
+    return doc.api.pagination === 'list'
+        ? { take: rows, skip: { type: 'integer', minimum: 0 } }
+        : { first: rows, after: text, last: rows, before: text };
+}
+/** `PostSelect`, `PostInclude`, a relation's arguments (D-129). */
+function fieldsOf(doc, model, select) {
+    const name = `${model}${select ? 'Select' : 'Include'}`;
+    return doc.components.ref(name, () => {
+        const entry = entryOf(doc.api, model);
+        const fields = {};
+        if (select)
+            for (const key of system)
+                fields[key] = flag;
+        for (const field of readable(entry)) {
+            if (field.kind === 'scalar') {
+                if (select)
+                    fields[field.name] = flag;
+                continue;
+            }
+            const args = field.kind === 'one'
+                ? argsOf(doc, field.target)
+                : listArgsOf(doc, field.target);
+            fields[field.name] = { anyOf: [flag, args] };
+        }
+        for (const virtual of readableVirtuals(entry)) {
+            fields[virtual.name] = virtualArgsOf(doc, model, virtual);
+        }
+        return objectOf(fields);
+    });
+}
+const either = { not: { required: ['select', 'include'] } };
+/**
+ * A virtual in `select` and `include` (D-151): `true` unless its input
+ * needs a property, its input, and a model's `select` or `include`.
+ */
+function virtualArgsOf(doc, model, virtual) {
+    const { name, input, output } = virtual;
+    const owner = `${model}.${name}`;
+    const base = `${model}${upper(name)}`;
+    const node = input === undefined
+        ? undefined
+        : hoisted(doc.components, jsonSchemaOf(input, 'input', `${owner}: input`), 'input', owner, `${base}Input`);
+    const listed = node?.['required'];
+    const required = Array.isArray(listed)
+        ? listed.filter((key) => typeof key === 'string')
+        : [];
+    const needed = required.length > 0;
+    const or = (schema) => (needed ? schema : { anyOf: [flag, schema] });
+    if (output.kind !== 'model')
+        return node === undefined ? flag : or(node);
+    const properties = node?.['properties'];
+    return or(doc.components.ref(`${base}Args`, () => ({
+        ...objectOf({
+            ...(isNode(properties) ? properties : {}),
+            select: fieldsOf(doc, output.name, true),
+            include: fieldsOf(doc, output.name, false),
+        }, required),
+        ...either,
+    })));
+}
+/** `PostArgs`: a `one` relation's `select` or `include`. */
+function argsOf(doc, model) {
+    return doc.components.ref(`${model}Args`, () => ({
+        ...objectOf({
+            select: fieldsOf(doc, model, true),
+            include: fieldsOf(doc, model, false),
+        }),
+        ...either,
+    }));
+}
+/** `PostListArgs`: a `many` relation's, its page and filter too. */
+function listArgsOf(doc, model) {
+    return doc.components.ref(`${model}ListArgs`, () => {
+        const entry = entryOf(doc.api, model);
+        const counts = doc.api.pagination === 'connection';
+        return {
+            ...objectOf({
+                select: fieldsOf(doc, model, true),
+                include: fieldsOf(doc, model, false),
+                where: whereOf(doc, model),
+                orderBy: ordering(doc, model),
+                ...pageOf(doc, entry),
+                ...(counts && { totalCount: flag }),
+            }),
+            ...either,
+        };
+    });
+}
+const ordering = (doc, model) => {
+    const order = orderByOf(doc, model);
+    return { anyOf: [order, arrayOf(order)] };
+};
+/** A query parameter: JSON, or a string or a number as is. */
+const param = (name, schema, description) => {
+    const plain = schema['type'] === 'string' || schema['type'] === 'integer';
+    return {
+        name,
+        in: 'query',
+        ...(description !== undefined && { description }),
+        ...(plain || schema === flag ? { schema } : { content: json(schema) }),
+    };
+};
+function fieldParams(doc, model) {
+    return [
+        param('select', fieldsOf(doc, model, true), 'The fields to return, and only those; not with include.'),
+        param('include', fieldsOf(doc, model, false), 'The relations to add to the default fields.'),
+    ];
+}
+const answer = (description, schema) => ({
+    description,
+    content: json(schema),
+});
+const body = (schema) => ({
+    required: true,
+    content: json(schema),
+});
+/** `/posts` and `/posts/{id}`, as REST serves them (D-129, D-142). */
+export function modelPaths(doc, entry) {
+    const { components } = doc;
+    const model = entry.model.name;
+    const own = (id) => components.operation(id, model, 'plural');
+    const tags = [model];
+    const row = rowOf(doc, model);
+    const counts = doc.api.pagination === 'connection';
+    const list = counts
+        ? connectionOf(doc, `${model}Connection`, model)
+        : arrayOf(row);
+    const pages = Object.entries(pageOf(doc, entry)).map(([name, schema]) => param(name, schema));
+    const one = model.charAt(0).toLowerCase() + model.slice(1);
+    const id = {
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: text,
+    };
+    return {
+        [`/${entry.plural}`]: {
+            get: {
+                operationId: own(entry.plural),
+                tags,
+                parameters: [
+                    param('where', whereOf(doc, model)),
+                    param('orderBy', ordering(doc, model)),
+                    ...fieldParams(doc, model),
+                    ...pages,
+                    ...(counts ? [param('totalCount', flag)] : []),
+                ],
+                responses: { 200: answer(`The ${model} rows.`, list), ...failed },
+            },
+            post: {
+                operationId: own(`create${model}`),
+                tags,
+                parameters: fieldParams(doc, model),
+                requestBody: body(dataOf(doc, model, true)),
+                responses: { 201: answer(`The ${model} created.`, row), ...failed },
+            },
+            put: {
+                operationId: own(`upsert${model}`),
+                tags,
+                description: `Updates the ${model} where matches, or creates it.`,
+                parameters: fieldParams(doc, model),
+                requestBody: body(objectOf({
+                    where: uniqueOf(doc, model),
+                    create: dataOf(doc, model, true),
+                    update: dataOf(doc, model, false),
+                }, ['where', 'create', 'update'])),
+                responses: {
+                    200: answer(`The ${model} updated.`, row),
+                    201: answer(`The ${model} created.`, row),
+                    ...failed,
+                },
+            },
+        },
+        [`/${entry.plural}/{id}`]: {
+            parameters: [id],
+            get: {
+                operationId: own(one),
+                tags,
+                parameters: fieldParams(doc, model),
+                responses: { 200: answer(`The ${model}.`, row), ...failed },
+            },
+            patch: {
+                operationId: own(`update${model}`),
+                tags,
+                parameters: fieldParams(doc, model),
+                requestBody: body(dataOf(doc, model, false)),
+                responses: { 200: answer(`The ${model} updated.`, row), ...failed },
+            },
+            delete: {
+                operationId: own(`delete${model}`),
+                tags,
+                responses: {
+                    200: answer(`The ${model} as it was, without relations.`, row),
+                    ...failed,
+                },
+            },
+        },
+    };
+}

package/dist/openapi.d.ts

@@ -0,0 +1,47 @@
+import type { Node } from '@ultimabase/http/internal';
+import type { Api } from './entries.ts';
+import type { Routed } from './functions.ts';
+export type Schema = Node;
+export declare const refTo: (name: string) => Schema;
+/** `schema` or `null`; any value already takes `null`. */
+export declare const orNull: (schema: Schema) => Schema;
+export declare const arrayOf: (items: Schema) => Schema;
+/** `schema` with its `description`, when it has one (D-150). */
+export declare const describe: (schema: Schema, description: string | undefined) => Schema;
+/** Each property with its field's `description` (D-150). */
+export declare const described: (properties: {
+    readonly [key: string]: Schema;
+}, descriptions: {
+    readonly [field: string]: string;
+}) => {
+    readonly [key: string]: Schema;
+};
+/** An object of these properties, and no other. */
+export declare const objectOf: (properties: {
+    readonly [key: string]: Schema;
+}, required?: readonly string[]) => Schema;
+/** A JSON value under `name`, as a parameter or a body holds it. */
+export declare const json: (schema: Schema) => Schema;
+/** The answer of each failed request (D-106). */
+export declare const failed: Schema;
+/** The document's named schemas, each name of one shape. */
+export declare class Components {
+    #private;
+    readonly schemas: {
+        [name: string]: Schema;
+    };
+    /** The schema REST names `name`, built on its first use. */
+    ref(name: string, build: () => Schema): Schema;
+    /** A schema a JSON Schema names, its id `name`. */
+    shared(name: string, schema: Schema, owner: string): Schema;
+    /** An operation's id, which no other operation has. */
+    operation(id: string, owner: string, setting: 'plural' | 'name'): string;
+}
+/**
+ * A JSON Schema with its `$defs` among the components, named by their ids,
+ * `Input`-suffixed on the input side as in GraphQL; `#` is `root`'s own.
+ */
+export declare function hoisted(components: Components, node: Node, side: 'input' | 'output', owner: string, root: string): Schema;
+/** The document `GET {path}/openapi.json` answers. */
+export declare function openapiOf(api: Api, functions: readonly Routed[], base: string, version: string): Schema;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,2BAA2B,CAAA;AAGrD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,cAAc,CAAA;AACvC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAI5C,MAAM,MAAM,MAAM,GAAG,IAAI,CAAA;AAEzB,eAAO,MAAM,KAAK,SAAU,MAAM,KAAG,MAEnC,CAAA;AAEF,0DAA0D;AAC1D,eAAO,MAAM,MAAM,WAAY,MAAM,KAAG,MAGC,CAAA;AAEzC,eAAO,MAAM,OAAO,UAAW,MAAM,KAAG,MAAoC,CAAA;AAE5E,gEAAgE;AAChE,eAAO,MAAM,QAAQ,WACZ,MAAM,eACD,MAAM,GAAG,SAAS,KAC7B,MAA2E,CAAA;AAE9E,4DAA4D;AAC5D,eAAO,MAAM,SAAS,eACT;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,gBAChC;IAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,KAChD;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAMjC,CAAA;AAEF,mDAAmD;AACnD,eAAO,MAAM,QAAQ,eACR;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,aACpC,SAAS,MAAM,EAAE,KACzB,MAKD,CAAA;AAEF,oEAAoE;AACpE,eAAO,MAAM,IAAI,WAAY,MAAM,KAAG,MAEpC,CAAA;AAEF,iDAAiD;AACjD,eAAO,MAAM,MAAM,EAAE,MAKpB,CAAA;AAoBD,4DAA4D;AAC5D,qBAAa,UAAU;;IACtB,QAAQ,CAAC,OAAO,EAAE;QAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAK;IAIjD,4DAA4D;IAC5D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,MAAM,GAAG,MAAM,CAW7C;IAED,mDAAmD;IACnD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAoB1D;IAED,uDAAuD;IACvD,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CASvE;CACD;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACtB,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,OAAO,GAAG,QAAQ,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACV,MAAM,CA4BR;AAED,sDAAsD;AACtD,wBAAgB,SAAS,CACxB,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,SAAS,MAAM,EAAE,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACb,MAAM,CAgBR"}

package/dist/openapi.js

@@ -0,0 +1,150 @@
+import { isNode } from '@ultimabase/http/internal';
+import { Refused } from 'ultimabase';
+import { functionPaths } from './openapi-functions.js';
+import { modelPaths } from './openapi-models.js';
+export const refTo = (name) => ({
+    $ref: `#/components/schemas/${name}`,
+});
+/** `schema` or `null`; any value already takes `null`. */
+export const orNull = (schema) => Object.keys(schema).length === 0
+    ? schema
+    : { anyOf: [schema, { type: 'null' }] };
+export const arrayOf = (items) => ({ type: 'array', items });
+/** `schema` with its `description`, when it has one (D-150). */
+export const describe = (schema, description) => (description === undefined ? schema : { ...schema, description });
+/** Each property with its field's `description` (D-150). */
+export const described = (properties, descriptions) => Object.fromEntries(Object.entries(properties).map(([key, schema]) => [
+    key,
+    describe(schema, descriptions[key]),
+]));
+/** An object of these properties, and no other. */
+export const objectOf = (properties, required = []) => ({
+    type: 'object',
+    properties,
+    ...(required.length > 0 && { required }),
+    additionalProperties: false,
+});
+/** A JSON value under `name`, as a parameter or a body holds it. */
+export const json = (schema) => ({
+    'application/json': { schema },
+});
+/** The answer of each failed request (D-106). */
+export const failed = {
+    default: {
+        description: 'The request failed.',
+        content: json(refTo('Error')),
+    },
+};
+const errorSchema = {
+    type: 'object',
+    properties: {
+        code: { type: 'string' },
+        message: { type: 'string' },
+        details: {},
+        correlationId: { type: 'string' },
+    },
+    required: ['code', 'message'],
+};
+const rest = 'REST';
+const clash = (owner, name) => new Refused(`${owner}: REST names a schema ${name}; give yours another name.`);
+/** The document's named schemas, each name of one shape. */
+export class Components {
+    schemas = {};
+    #known = new Map();
+    #operations = new Map();
+    /** The schema REST names `name`, built on its first use. */
+    ref(name, build) {
+        const known = this.#known.get(name);
+        if (known !== undefined && known.owner !== rest)
+            throw clash(known.owner, name);
+        if (known === undefined) {
+            this.#known.set(name, { owner: rest, key: undefined });
+            // Set first: a schema may refer to itself.
+            this.schemas[name] = {};
+            this.schemas[name] = build();
+        }
+        return refTo(name);
+    }
+    /** A schema a JSON Schema names, its id `name`. */
+    shared(name, schema, owner) {
+        if (!/^[\w.-]+$/.test(name)) {
+            throw new Refused(`${owner}: ${name} is not a schema name, which takes letters, digits, '.', '-' and '_'.`);
+        }
+        // One shape whatever it says of itself: its first description stays.
+        const { description: _, ...shape } = schema;
+        const key = JSON.stringify(shape);
+        const known = this.#known.get(name);
+        if (known?.owner === rest)
+            throw clash(owner, name);
+        if (known === undefined) {
+            this.#known.set(name, { owner, key });
+            this.schemas[name] = schema;
+        }
+        else if (known.key !== key) {
+            throw new Refused(`${known.owner} and ${owner} give the schema ${name} two shapes; name each once.`);
+        }
+        return refTo(name);
+    }
+    /** An operation's id, which no other operation has. */
+    operation(id, owner, setting) {
+        const other = this.#operations.get(id);
+        if (other !== undefined) {
+            throw new Refused(`${owner}: the operation ${id} is ${other}'s; set .with({ rest: { ${setting} } }).`);
+        }
+        this.#operations.set(id, owner);
+        return id;
+    }
+}
+/**
+ * A JSON Schema with its `$defs` among the components, named by their ids,
+ * `Input`-suffixed on the input side as in GraphQL; `#` is `root`'s own.
+ */
+export function hoisted(components, node, side, owner, root) {
+    const suffix = side === 'input' ? 'Input' : '';
+    let recursive = false;
+    const rewrite = (value) => {
+        if (Array.isArray(value))
+            return value.map(rewrite);
+        if (!isNode(value))
+            return value;
+        const ref = value['$ref'];
+        if (ref === '#') {
+            recursive = true;
+            return { ...value, $ref: refTo(root)['$ref'] };
+        }
+        if (typeof ref === 'string' && ref.startsWith('#/$defs/')) {
+            return { ...value, $ref: refTo(`${ref.slice(8)}${suffix}`)['$ref'] };
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, rewrite(inner)]));
+    };
+    const { $defs: defs, $schema: _, ...own } = node;
+    if (isNode(defs)) {
+        for (const [id, def] of Object.entries(defs)) {
+            const schema = rewrite(def);
+            if (isNode(schema))
+                components.shared(`${id}${suffix}`, schema, owner);
+        }
+    }
+    const schema = rewrite(own);
+    const result = isNode(schema) ? schema : {};
+    return recursive ? components.shared(root, result, owner) : result;
+}
+/** The document `GET {path}/openapi.json` answers. */
+export function openapiOf(api, functions, base, version) {
+    const components = new Components();
+    components.ref('Error', () => errorSchema);
+    const doc = { components, api };
+    const paths = {};
+    for (const entry of api.entries.values()) {
+        if (entry.visible)
+            Object.assign(paths, modelPaths(doc, entry));
+    }
+    Object.assign(paths, functionPaths(doc, functions));
+    return {
+        openapi: '3.1.0',
+        info: { title: 'UltimaBase REST API', version },
+        servers: [{ url: base === '' ? '/' : base }],
+        paths,
+        components: { schemas: components.schemas },
+    };
+}

package/dist/params.d.ts

@@ -0,0 +1,11 @@
+import type { Args } from './entries.ts';
+/** What a route reads from its query string. */
+export type Accepted = {
+    /** Parameters written as JSON. */
+    readonly json: readonly string[];
+    /** Parameters written as is. */
+    readonly text: readonly string[];
+};
+/** The parameters of a request, each once and each one the route takes. */
+export declare function paramsOf(url: string, accepted: Accepted): Args;
+//# sourceMappingURL=params.d.ts.map

package/dist/params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"params.d.ts","sourceRoot":"","sources":["../src/params.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AAExC,gDAAgD;AAChD,MAAM,MAAM,QAAQ,GAAG;IACtB,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC,CAAA;AAUD,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAgB9D"}

package/dist/params.js

@@ -0,0 +1,27 @@
+// Query parameters (D-129): each the JSON of the GraphQL argument of its
+// name, a string argument as is.
+import { badInput } from '@ultimabase/http/internal';
+function parsed(name, value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch (error) {
+        throw badInput(`The query parameter ${name} is not JSON.`, error);
+    }
+}
+/** The parameters of a request, each once and each one the route takes. */
+export function paramsOf(url, accepted) {
+    const params = {};
+    const taken = [...accepted.json, ...accepted.text];
+    for (const [name, value] of new URL(url).searchParams) {
+        if (Object.hasOwn(params, name)) {
+            throw badInput(`The query parameter ${name} is given twice.`);
+        }
+        if (!taken.includes(name)) {
+            const takes = taken.length === 0 ? 'none' : taken.join(', ');
+            throw badInput(`Unknown query parameter '${name}'; this route takes ${takes}.`);
+        }
+        params[name] = accepted.text.includes(name) ? value : parsed(name, value);
+    }
+    return params;
+}

package/dist/sse.d.ts

@@ -0,0 +1,17 @@
+/** An open stream of events, and the response that sends it. */
+export type Events = {
+    readonly response: Response;
+    /** Writes one event; `id` is the revision it carries. */
+    readonly send: (event: string, data: unknown, id?: number) => void;
+    /** Whether the client's buffer holds more than it may. */
+    readonly full: () => boolean;
+    /** Runs `then` once the client took what it was sent. */
+    readonly drained: (then: () => void) => void;
+    /** Ends the stream. */
+    readonly end: () => void;
+};
+/** Whether `header` (an `Accept-Encoding`) takes gzip. */
+export declare function acceptsGzip(header: string | null): boolean;
+/** A stream of events to `request`'s client; `closed` runs once it ends. */
+export declare function eventsTo(request: Request, closed: () => void): Events;
+//# sourceMappingURL=sse.d.ts.map

package/dist/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../src/sse.ts"],"names":[],"mappings":"AAYA,gEAAgE;AAChE,MAAM,MAAM,MAAM,GAAG;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;IAClE,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAA;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IAC5C,uBAAuB;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,CAAA;CACxB,CAAA;AAED,0DAA0D;AAC1D,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAQ1D;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,IAAI,GAAG,MAAM,CAyCrE"}

package/dist/sse.js

@@ -0,0 +1,63 @@
+import { PassThrough, Readable } from 'node:stream';
+import { constants, createGzip } from 'node:zlib';
+/** A client's buffer past which its changes are dropped. */
+const maxBuffer = 1024 * 1024;
+/** Between two comments on a quiet stream. */
+const keepAlive = 12_000;
+/** Whether `header` (an `Accept-Encoding`) takes gzip. */
+export function acceptsGzip(header) {
+    for (const part of (header ?? '').split(',')) {
+        const [name = '', ...params] = part.split(';').map((each) => each.trim());
+        if (name.toLowerCase() !== 'gzip')
+            continue;
+        const q = params.find((param) => param.startsWith('q='));
+        return q === undefined || Number(q.slice(2)) > 0;
+    }
+    return false;
+}
+/** A stream of events to `request`'s client; `closed` runs once it ends. */
+export function eventsTo(request, closed) {
+    const gzip = acceptsGzip(request.headers.get('accept-encoding'));
+    const zipped = gzip ? createGzip() : undefined;
+    const stream = zipped ?? new PassThrough();
+    const write = (text) => {
+        if (stream.writableEnded || stream.destroyed)
+            return;
+        stream.write(text);
+        zipped?.flush(constants.Z_SYNC_FLUSH);
+    };
+    const beating = setInterval(() => write(':\n\n'), keepAlive);
+    beating.unref();
+    stream.once('close', () => {
+        clearInterval(beating);
+        closed();
+    });
+    const end = () => {
+        clearInterval(beating);
+        stream.end();
+    };
+    request.signal.addEventListener('abort', () => stream.destroy());
+    const headers = {
+        'content-type': 'text/event-stream; charset=utf-8',
+        'cache-control': 'no-store',
+        // nginx buffers a response unless told not to.
+        'x-accel-buffering': 'no',
+        ...(gzip ? { 'content-encoding': 'gzip', vary: 'Accept-Encoding' } : {}),
+    };
+    const body = Readable.toWeb(stream);
+    return {
+        response: new Response(body, { headers }),
+        send: (event, data, id) => {
+            const line = id === undefined ? '' : `id: ${id}\n`;
+            write(`${line}event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        },
+        full: () => stream.writableLength + stream.readableLength > maxBuffer,
+        drained: (then) => {
+            if (stream.writableNeedDrain)
+                stream.once('drain', then);
+            else
+                then();
+        },
+        end,
+    };
+}