yedra 0.20.11 → 0.20.13

package/dist/src/routing/log.js

@@ -0,0 +1,30 @@
+export class Log {
+    /**
+     * Output a debug message.
+     * @param args - The message.
+     */
+    debug(...args) {
+        console.debug(...args);
+    }
+    /**
+     * Output an informational message.
+     * @param args - The message.
+     */
+    info(...args) {
+        console.info(...args);
+    }
+    /**
+     * Output a warning message.
+     * @param args - The message.
+     */
+    warning(...args) {
+        console.warn(...args);
+    }
+    /**
+     * Output an error message.
+     * @param args - The message.
+     */
+    error(...args) {
+        console.error(...args);
+    }
+}

package/dist/src/routing/path.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Represents an HTTP API path. Provides methods for concatenating paths and
+ * extracting path parameters from strings.
+ */
+export declare class Path {
+    private readonly expected;
+    /**
+     * Creates a new path. The path must start with `/`. Every part of the path
+     * must match /^(:?[a-z0-9]+\??)|\*$/. It can either be a specific word, e.g.
+     * `template`, or a parameter which starts with `:`, e.g. `:id`. If the
+     * parameter should be optional, add a `?`, e.g. `:id?`. The last part of the
+     * path can also be `*`, which matches any number of arbitrary segments.
+     * @param path - The path parameter.
+     */
+    constructor(path: string);
+    /**
+     * Prepends this path with another path.
+     * @param prefix - The prefix to prepend.
+     * @returns The prefixed path.
+     */
+    withPrefix(prefix: string): Path;
+    /**
+     * Returns the path as a string. The segments are joined with `/`, and the
+     * result is can be converted to a `Path` again.
+     * @returns The path as a string.
+     */
+    toString(): string;
+    /**
+     * Match this API path to a string. If the string matches the path, this
+     * returns a record mapping the path parameters (e.g. `:id`) to the values
+     * found in the actual string. Otherwise, it returns
+     * undefined.
+     * @param path - The string path to match.
+     */
+    match(path: string): {
+        params: Record<string, string>;
+        score: number;
+    } | undefined;
+    /**
+     * Remove `:` and `?` from a parameter path segment.
+     * @param param - The path segment.
+     */
+    private static normalizeParam;
+}

package/dist/src/routing/path.js

@@ -0,0 +1,110 @@
+/**
+ * Represents an HTTP API path. Provides methods for concatenating paths and
+ * extracting path parameters from strings.
+ */
+export class Path {
+    /**
+     * Creates a new path. The path must start with `/`. Every part of the path
+     * must match /^(:?[a-z0-9]+\??)|\*$/. It can either be a specific word, e.g.
+     * `template`, or a parameter which starts with `:`, e.g. `:id`. If the
+     * parameter should be optional, add a `?`, e.g. `:id?`. The last part of the
+     * path can also be `*`, which matches any number of arbitrary segments.
+     * @param path - The path parameter.
+     */
+    constructor(path) {
+        if (!path.startsWith('/')) {
+            throw new Error(`API path ${path} is invalid: Must start with '/'.`);
+        }
+        this.expected = path
+            .substring(1)
+            .split('/')
+            .filter((segment) => segment !== '');
+        const invalidSegment = this.expected.find((part) => part.match(/^((:?[A-Za-z0-9\-.]+\??)|\*)$/) === null);
+        if (invalidSegment) {
+            throw new Error(`API path ${path} is invalid: Segment ${invalidSegment} does not match regex /^((:?[A-Za-z0-9-.]+\\??)|\\*)$/.`);
+        }
+        const wildcard = this.expected.indexOf('*');
+        if (wildcard !== -1 && wildcard !== this.expected.length - 1) {
+            throw new Error(`API path ${path} is invalid: * must be the last path segment.`);
+        }
+        const firstOptional = this.expected.findIndex((part) => part.endsWith('?'));
+        if (firstOptional !== -1 &&
+            !this.expected.slice(firstOptional).every((part) => part.endsWith('?'))) {
+            throw new Error(`API path ${path} is invalid: Optional segment cannot be followed by non-optional segment.`);
+        }
+    }
+    /**
+     * Prepends this path with another path.
+     * @param prefix - The prefix to prepend.
+     * @returns The prefixed path.
+     */
+    withPrefix(prefix) {
+        return new Path(`${prefix}/${this.expected.join('/')}`);
+    }
+    /**
+     * Returns the path as a string. The segments are joined with `/`, and the
+     * result is can be converted to a `Path` again.
+     * @returns The path as a string.
+     */
+    toString() {
+        return `/${this.expected.map((segment) => (segment.startsWith(':') ? `{${segment.substring(1)}}` : segment)).join('/')}`;
+    }
+    /**
+     * Match this API path to a string. If the string matches the path, this
+     * returns a record mapping the path parameters (e.g. `:id`) to the values
+     * found in the actual string. Otherwise, it returns
+     * undefined.
+     * @param path - The string path to match.
+     */
+    match(path) {
+        const params = {};
+        const actual = path
+            .substring(1)
+            .split('/')
+            .filter((segment) => segment !== '');
+        if (this.expected.length < actual.length && !this.expected.includes('*')) {
+            // path cannot be longer than expected, unless it contains a wildcard
+            return undefined;
+        }
+        for (let i = 0; i < actual.length; ++i) {
+            if (this.expected[i] === '*') {
+                // wildcard, parsing successful
+                return { params, score: Number.POSITIVE_INFINITY };
+            }
+            if (this.expected[i].startsWith(':')) {
+                // parameter, accept anything
+                params[Path.normalizeParam(this.expected[i])] = actual[i];
+            }
+            else if (Path.normalizeParam(this.expected[i]) !== actual[i].toLowerCase()) {
+                // not a parameter, and the values don't match
+                return undefined;
+            }
+        }
+        if (actual.length < this.expected.length &&
+            !this.expected[actual.length].endsWith('?') &&
+            this.expected[actual.length] !== '*') {
+            // path is incomplete
+            return undefined;
+        }
+        return {
+            params,
+            score: this.expected.includes('*')
+                ? Number.POSITIVE_INFINITY
+                : Object.keys(params).length,
+        };
+    }
+    /**
+     * Remove `:` and `?` from a parameter path segment.
+     * @param param - The path segment.
+     */
+    static normalizeParam(param) {
+        let result = param;
+        if (result.startsWith(':')) {
+            result = result.substring(1);
+        }
+        if (result.endsWith('?')) {
+            result = result.substring(0, result.length - 1);
+        }
+        return result;
+    }
+}

package/dist/src/routing/rest.d.ts

@@ -0,0 +1,103 @@
+import type { Readable } from 'node:stream';
+import type { SecurityScheme } from '../util/security.js';
+import type { BodyType, Typeof, TypeofAccepts } from '../validation/body.js';
+import { NoneBody } from '../validation/none.js';
+import { type ObjectSchema } from '../validation/object.js';
+import type { Schema } from '../validation/schema.js';
+type ReqObject<Params, Query, Headers, Body> = {
+    url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    params: Params;
+    query: Query;
+    headers: Headers;
+    rawHeaders: Record<string, string>;
+    body: Body;
+};
+type ResObject<Body> = Promise<{
+    status?: number;
+    body: Body;
+    headers?: Record<string, string | undefined>;
+}> | {
+    status?: number;
+    body: Body;
+    headers?: Record<string, string | undefined>;
+};
+type EndpointOptions<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Req extends BodyType<unknown, unknown>, Res extends BodyType<unknown, unknown>> = {
+    category: string;
+    summary: string;
+    description?: string;
+    /**
+     * List of security schemes that apply to this endpoint.
+     */
+    security?: SecurityScheme[];
+    /**
+     * Whether this endpoint should be excluded from the documentation.
+     * Default is false.
+     */
+    hidden?: boolean;
+    params: Params;
+    query: Query;
+    headers: Headers;
+    req: Req;
+    res: Res;
+    do: (req: ReqObject<Typeof<ObjectSchema<Params>>, Typeof<ObjectSchema<Query>>, Typeof<ObjectSchema<Headers>>, Typeof<Req>>) => ResObject<TypeofAccepts<Res>>;
+};
+export declare abstract class RestEndpoint {
+    abstract get method(): 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    abstract handle(req: {
+        url: string;
+        body: Readable;
+        params: Record<string, string>;
+        query: Record<string, string>;
+        headers: Record<string, string>;
+    }): Promise<{
+        status?: number;
+        body: unknown;
+        headers?: Record<string, string | undefined>;
+    }>;
+    abstract isHidden(): boolean;
+    abstract documentation(path: string, securitySchemes: Set<SecurityScheme>): object;
+}
+/**
+ * This class implements all REST endpoints in yedra. Its parent class,
+ * `RestEndpoint`, is not abstract because there are multiple implementations,
+ * but so that we can hide all the generic parameters of this class.
+ */
+declare class ConcreteRestEndpoint<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Req extends BodyType<unknown, unknown>, Res extends BodyType<unknown, unknown>> extends RestEndpoint {
+    private _method;
+    private options;
+    private paramsSchema;
+    private querySchema;
+    private headersSchema;
+    constructor(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', options: EndpointOptions<Params, Query, Headers, Req, Res>);
+    get method(): 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    handle(req: {
+        url: string;
+        body: Readable;
+        params: Record<string, string>;
+        query: Record<string, string>;
+        headers: Record<string, string>;
+    }): Promise<{
+        status?: number;
+        body: unknown;
+        headers?: Record<string, string | undefined>;
+    }>;
+    isHidden(): boolean;
+    documentation(path: string, securitySchemes: Set<SecurityScheme>): object;
+}
+export declare class Get<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Res extends BodyType<unknown, unknown>> extends ConcreteRestEndpoint<Params, Query, Headers, NoneBody, Res> {
+    constructor(options: Omit<EndpointOptions<Params, Query, Headers, NoneBody, Res>, 'req'>);
+}
+export declare class Post<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Req extends BodyType<unknown, unknown>, Res extends BodyType<unknown, unknown>> extends ConcreteRestEndpoint<Params, Query, Headers, Req, Res> {
+    constructor(options: EndpointOptions<Params, Query, Headers, Req, Res>);
+}
+export declare class Put<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Req extends BodyType<unknown, unknown>, Res extends BodyType<unknown, unknown>> extends ConcreteRestEndpoint<Params, Query, Headers, Req, Res> {
+    constructor(options: EndpointOptions<Params, Query, Headers, Req, Res>);
+}
+export declare class Patch<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Req extends BodyType<unknown, unknown>, Res extends BodyType<unknown, unknown>> extends ConcreteRestEndpoint<Params, Query, Headers, Req, Res> {
+    constructor(options: EndpointOptions<Params, Query, Headers, Req, Res>);
+}
+export declare class Delete<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>, Res extends BodyType<unknown, unknown>> extends ConcreteRestEndpoint<Params, Query, Headers, NoneBody, Res> {
+    constructor(options: Omit<EndpointOptions<Params, Query, Headers, NoneBody, Res>, 'req'>);
+}
+export {};

package/dist/src/routing/rest.js

@@ -0,0 +1,181 @@
+import { paramDocs } from '../util/docs.js';
+import { Issue, ValidationError } from '../validation/error.js';
+import { NoneBody, none } from '../validation/none.js';
+import { laxObject, object } from '../validation/object.js';
+import { BadRequestError } from './errors.js';
+export class RestEndpoint {
+}
+/**
+ * This class implements all REST endpoints in yedra. Its parent class,
+ * `RestEndpoint`, is not abstract because there are multiple implementations,
+ * but so that we can hide all the generic parameters of this class.
+ */
+class ConcreteRestEndpoint extends RestEndpoint {
+    constructor(method, options) {
+        super();
+        this._method = method;
+        this.options = options;
+        this.paramsSchema = object(options.params);
+        // queries can sometimes include other elements for application-unrelated reasons
+        this.querySchema = laxObject(options.query);
+        // headers need to be lax, since there are lots of them
+        this.headersSchema = laxObject(options.headers);
+    }
+    get method() {
+        return this._method;
+    }
+    async handle(req) {
+        let parsedBody;
+        let parsedParams;
+        let parsedQuery;
+        let parsedHeaders;
+        const issues = [];
+        try {
+            const result = await this.options.req.deserialize(req.body, req.headers['content-type'] ?? 'application/octet-stream');
+            parsedBody = result;
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                issues.push(new Issue(['body'], error.message));
+            }
+            else if (error instanceof ValidationError) {
+                issues.push(...error.withPrefix('body'));
+            }
+            else {
+                throw error;
+            }
+        }
+        try {
+            parsedParams = this.paramsSchema.parse(req.params);
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                issues.push(...error.withPrefix('params'));
+            }
+            else {
+                throw error;
+            }
+        }
+        try {
+            parsedQuery = this.querySchema.parse(req.query);
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                issues.push(...error.withPrefix('query'));
+            }
+            else {
+                throw error;
+            }
+        }
+        try {
+            parsedHeaders = this.headersSchema.parse(req.headers);
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                issues.push(...error.withPrefix('headers'));
+            }
+            else {
+                throw error;
+            }
+        }
+        if (issues.length > 0) {
+            const error = new ValidationError(issues);
+            throw new BadRequestError(error.format());
+        }
+        return await this.options.do({
+            url: req.url,
+            method: this._method,
+            // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
+            params: parsedParams,
+            // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
+            query: parsedQuery,
+            // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
+            headers: parsedHeaders,
+            rawHeaders: req.headers,
+            // biome-ignore lint/style/noNonNullAssertion: this is required to convince TypeScript that this is initialized
+            body: parsedBody,
+        });
+    }
+    isHidden() {
+        return this.options.hidden ?? false;
+    }
+    documentation(path, securitySchemes) {
+        const security = this.options.security ?? [];
+        for (const scheme of security) {
+            // add all our security schemes to the global list of schemes
+            securitySchemes.add(scheme);
+        }
+        const parameters = [
+            ...paramDocs(this.options.params, 'path', security),
+            ...paramDocs(this.options.query, 'query', security),
+            ...paramDocs(this.options.headers, 'header', security),
+        ];
+        return {
+            tags: [this.options.category],
+            summary: this.options.summary,
+            description: this.options.description,
+            operationId: `${path.substring(1).replaceAll('/', '_')}_${this.method.toLowerCase()}`,
+            security: security.map((security) => ({ [security.name]: [] })),
+            parameters,
+            requestBody: this.options.req instanceof NoneBody
+                ? undefined
+                : {
+                    required: true,
+                    content: this.options.req.bodyDocs(),
+                },
+            responses: {
+                '200': {
+                    description: 'Success',
+                    content: this.options.res.bodyDocs(),
+                },
+                '400': {
+                    description: 'Bad Request',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    status: {
+                                        type: 'number',
+                                    },
+                                    errorMessage: {
+                                        type: 'string',
+                                    },
+                                    code: {
+                                        type: 'string',
+                                    },
+                                },
+                                required: ['status', 'errorMessage'],
+                            },
+                        },
+                    },
+                },
+            },
+        };
+    }
+}
+export class Get extends ConcreteRestEndpoint {
+    constructor(options) {
+        super('GET', { req: none(), ...options });
+    }
+}
+export class Post extends ConcreteRestEndpoint {
+    constructor(options) {
+        super('POST', options);
+    }
+}
+export class Put extends ConcreteRestEndpoint {
+    constructor(options) {
+        super('PUT', options);
+    }
+}
+export class Patch extends ConcreteRestEndpoint {
+    constructor(options) {
+        super('PATCH', options);
+    }
+}
+export class Delete extends ConcreteRestEndpoint {
+    constructor(options) {
+        super('DELETE', { req: none(), ...options });
+    }
+}

package/dist/src/routing/websocket.d.ts

@@ -0,0 +1,60 @@
+import type { URL } from 'node:url';
+import type { WebSocket as NodeWebSocket } from 'ws';
+import type { Typeof } from '../validation/body.js';
+import { type ObjectSchema } from '../validation/object.js';
+import type { Schema } from '../validation/schema.js';
+type MessageCb = (message: Buffer) => Promise<void> | void;
+type CloseCb = (code: number | undefined, reason: string | undefined) => Promise<void> | void;
+declare class YedraWebSocket {
+    private ws;
+    private messageQueue;
+    private messageHandlers;
+    private closeHandlers;
+    constructor(ws: NodeWebSocket);
+    set onmessage(cb: MessageCb);
+    set onclose(cb: CloseCb);
+    /**
+     * Send binary data over the WebSocket connection;
+     * @param message - The message that will be sent.
+     */
+    send(message: Uint8Array<ArrayBufferLike> | string): void;
+    /**
+     * Closes the WebSocket.
+     * @param code - The close code. Must be one of:
+     * - 1000: normal closure
+     * - 1009: message too big
+     * - 1011: server encountered error
+     * - 1012: server restarting
+     * - 1013: server too busy or rate-limiting
+     * - 4000-4999: reserved for applications
+     * @param reason - The reason the WebSocket was closed.
+     */
+    close(code?: number, reason?: string): void;
+}
+export type { YedraWebSocket };
+type WebSocketOptions<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>> = {
+    category: string;
+    summary: string;
+    description?: string;
+    params: Params;
+    query: Query;
+    headers: Headers;
+    do: (ws: YedraWebSocket, req: {
+        url: string;
+        params: Typeof<ObjectSchema<Params>>;
+        query: Typeof<ObjectSchema<Query>>;
+        headers: Typeof<ObjectSchema<Headers>>;
+    }) => Promise<void> | void;
+};
+export declare abstract class WsEndpoint {
+    abstract handle(url: URL, params: Record<string, string>, headers: Record<string, string>, ws: NodeWebSocket): Promise<void>;
+}
+export declare class Ws<Params extends Record<string, Schema<unknown>>, Query extends Record<string, Schema<unknown>>, Headers extends Record<string, Schema<unknown>>> extends WsEndpoint {
+    private options;
+    private paramsSchema;
+    private querySchema;
+    private headersSchema;
+    constructor(options: WebSocketOptions<Params, Query, Headers>);
+    handle(url: URL, params: Record<string, string>, headers: Record<string, string>, ws: NodeWebSocket): Promise<void>;
+    documentation(): object;
+}

package/dist/src/routing/websocket.js

@@ -0,0 +1,132 @@
+import { paramDocs } from '../util/docs.js';
+import { ValidationError } from '../validation/error.js';
+import { laxObject, object } from '../validation/object.js';
+import { BadRequestError } from './errors.js';
+class YedraWebSocket {
+    constructor(ws) {
+        this.messageQueue = [];
+        this.messageHandlers = [];
+        this.closeHandlers = [];
+        this.ws = ws;
+        ws.on('message', (data) => {
+            for (const cb of this.messageHandlers) {
+                cb(data);
+            }
+            if (this.messageHandlers.length === 0) {
+                // there are no message handlers registered yet,
+                // add the message to the queue
+                this.messageQueue.push(data);
+            }
+        });
+        ws.on('close', (code, reason) => {
+            for (const cb of this.closeHandlers) {
+                cb(code, reason);
+            }
+        });
+    }
+    set onmessage(cb) {
+        this.messageHandlers.push(cb);
+        // if there are queued messages, process them now
+        const messages = this.messageQueue;
+        this.messageQueue = [];
+        for (const message of messages) {
+            cb(message);
+        }
+    }
+    set onclose(cb) {
+        this.closeHandlers.push(cb);
+    }
+    /**
+     * Send binary data over the WebSocket connection;
+     * @param message - The message that will be sent.
+     */
+    send(message) {
+        this.ws.send(message);
+    }
+    /**
+     * Closes the WebSocket.
+     * @param code - The close code. Must be one of:
+     * - 1000: normal closure
+     * - 1009: message too big
+     * - 1011: server encountered error
+     * - 1012: server restarting
+     * - 1013: server too busy or rate-limiting
+     * - 4000-4999: reserved for applications
+     * @param reason - The reason the WebSocket was closed.
+     */
+    close(code, reason) {
+        this.ws.close(code, reason);
+    }
+}
+export class WsEndpoint {
+}
+export class Ws extends WsEndpoint {
+    constructor(options) {
+        super();
+        this.options = options;
+        this.paramsSchema = object(options.params);
+        this.querySchema = object(options.query);
+        this.headersSchema = laxObject(options.headers);
+    }
+    async handle(url, params, headers, ws) {
+        let parsedParams;
+        let parsedQuery;
+        let parsedHeaders;
+        try {
+            parsedParams = this.paramsSchema.parse(params);
+            parsedQuery = this.querySchema.parse(Object.fromEntries(url.searchParams));
+            parsedHeaders = this.headersSchema.parse(headers);
+        }
+        catch (error) {
+            if (error instanceof ValidationError) {
+                throw new BadRequestError(error.format());
+            }
+            throw error;
+        }
+        await this.options.do(new YedraWebSocket(ws), {
+            url: url.pathname,
+            params: parsedParams,
+            query: parsedQuery,
+            headers: parsedHeaders,
+        });
+        return undefined;
+    }
+    documentation() {
+        const parameters = [
+            ...paramDocs(this.options.params, 'path', []),
+            ...paramDocs(this.options.query, 'query', []),
+            ...paramDocs(this.options.headers, 'header', []),
+        ];
+        return {
+            tags: [this.options.category],
+            summary: this.options.summary,
+            description: this.options.description,
+            parameters,
+            responses: {
+                '101': {
+                    description: 'Switching to WebSocket',
+                },
+                '400': {
+                    description: 'Upgrading to WebSocket failed',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: {
+                                    status: {
+                                        type: 'number',
+                                        example: 400,
+                                    },
+                                    errorMessage: {
+                                        type: 'string',
+                                        example: 'Upgrading to WebSocket failed.',
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+    }
+}

package/dist/src/schema-lib.d.ts

@@ -0,0 +1,17 @@
+export { BodyType, type Typeof } from './validation/body.js';
+export { boolean } from './validation/boolean.js';
+export { date } from './validation/date.js';
+export { _enum as enum } from './validation/enum.js';
+export { ValidationError } from './validation/error.js';
+export { integer } from './validation/integer.js';
+export { lazy, LazySchema } from './validation/lazy.js';
+export { array } from './validation/modifiable.js';
+export { _null as null } from './validation/null.js';
+export { number } from './validation/number.js';
+export { laxObject, object } from './validation/object.js';
+export { record } from './validation/record.js';
+export { Schema } from './validation/schema.js';
+export { string } from './validation/string.js';
+export { union } from './validation/union.js';
+export { unknown } from './validation/unknown.js';
+export { uuid } from './validation/uuid.js';