@riddl/core 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 All Peep Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapters.d.ts

@@ -0,0 +1,7 @@
+import type { Handler } from "./types";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import express, { type Router, Application } from "express";
+export declare const mountApi: (app: Application, prefix: string, apiHandler: Handler) => express.Application;
+export declare const setResponse: (res: ServerResponse, response: Response) => Promise<void>;
+export declare const rawAdapter: (apiHandler: Handler) => (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+export declare const expressAdapter: (apiHandler: Handler) => Router;

package/dist/adapters.js

@@ -0,0 +1,73 @@
+import express from "express";
+import { toFetchRequest } from "./utils.js";
+import * as set_cookie_parser from "set-cookie-parser";
+export const mountApi = (app, prefix, apiHandler) => app.use(prefix, expressAdapter(apiHandler));
+export const setResponse = async (res, response) => {
+    for (const [key, value] of response.headers) {
+        try {
+            res.setHeader(key, key === 'set-cookie'
+                ? set_cookie_parser.splitCookiesString(response.headers.get(key))
+                : value);
+        }
+        catch (error) {
+            res.getHeaderNames().forEach((name) => res.removeHeader(name));
+            res.writeHead(500).end(String(error));
+            return;
+        }
+    }
+    res.writeHead(response.status);
+    if (!response.body) {
+        res.end();
+        return;
+    }
+    if (response.body.locked) {
+        res.end('Fatal error: Response body is locked. ' +
+            "This can happen when the response was already read (for example through 'response.json()' or 'response.text()').");
+        return;
+    }
+    const reader = response.body.getReader();
+    if (res.destroyed) {
+        void reader.cancel();
+        return;
+    }
+    const cancel = (error) => {
+        res.off('close', cancel);
+        res.off('error', cancel);
+        // If the reader has already been interrupted with an error earlier,
+        // then it will appear here, it is useless, but it needs to be catch.
+        reader.cancel(error).catch(() => { });
+        if (error)
+            res.destroy(error);
+    };
+    res.on('close', cancel);
+    res.on('error', cancel);
+    void next();
+    async function next() {
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (!res.write(value)) {
+                    res.once('drain', next);
+                    return;
+                }
+            }
+            res.end();
+        }
+        catch (error) {
+            cancel(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+};
+export const rawAdapter = (apiHandler) => (async (req, res) => {
+    const response = await apiHandler(toFetchRequest(req));
+    res.statusCode = response.status;
+    res.setHeader("Content-Type", "application/json");
+    res.setHeader("Content-Length", "0");
+    response.headers.forEach((value, key) => {
+        res.setHeader(key, value);
+    });
+    await setResponse(res, response);
+});
+export const expressAdapter = (apiHandler) => express.Router().use(rawAdapter(apiHandler));

package/dist/api.d.ts

@@ -0,0 +1,2 @@
+import type { APIOptions, API } from "./types";
+export declare const api: ({ routeModuleMap, config, base, cors, registry, }: APIOptions) => Promise<API>;

package/dist/api.js

@@ -0,0 +1,128 @@
+import { OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+import { json, recursiveAwait } from "./utils.js";
+import { CORS_DEFAULT, METHOD } from "./constants.js";
+import { log } from "./log.js";
+import { parseBody, parseOutput, parseParam, parseQuery } from "./validation.js";
+import { parseRouteId } from "./parser.js";
+import { buildRouter } from "./routing.js";
+import { openapiHandler, registerRoutes } from "./openapi.js";
+import { error } from "./errors.js";
+export const api = async ({ routeModuleMap, config, base = "/api", cors = true, registry = new OpenAPIRegistry(), }) => {
+    const { routes, middlewares } = await Object.entries(routeModuleMap)
+        .reduce(async (accPromise, [path, module]) => {
+        var _a, _b, _c;
+        const acc = await accPromise;
+        const parts = path.split("/");
+        const last = parts[parts.length - 1].split(".")[0];
+        parts[parts.length - 1] = last;
+        const id = parts.slice(0, -1).join("/");
+        if (METHOD.test(last)) {
+            const method = last.toUpperCase();
+            const endpoint = (await module()).apiEndpoint;
+            acc.routes[id] = {
+                matcher: parseRouteId(id),
+                handlers: {
+                    ...((_c = (_b = (_a = acc.routes) === null || _a === void 0 ? void 0 : _a[id]) === null || _b === void 0 ? void 0 : _b.handlers) !== null && _c !== void 0 ? _c : {}),
+                    [method]: endpoint,
+                }
+            };
+        }
+        if (last === "middleware") {
+            acc.middlewares[id] = (await module());
+        }
+        return acc;
+    }, Promise.resolve({ routes: {}, middlewares: {} }));
+    log("routes: %O", routes);
+    log("middlewares: %O", middlewares);
+    log("config: %O", config);
+    log("base: %s", base);
+    registerRoutes({ routes, registry, base });
+    const router = buildRouter(routes, middlewares);
+    const effectiveCorsSettings = cors ? typeof cors === "object" ? cors : CORS_DEFAULT : undefined;
+    const handler = async (request) => {
+        var _a, _b, _c;
+        try {
+            log("request: %O", request);
+            const event = {
+                request,
+                url: new URL(request.url),
+                context: {},
+            };
+            const { id, params, routeWithMiddlewares } = (_a = router(event.url.pathname)) !== null && _a !== void 0 ? _a : {};
+            if (!id || !params || !routeWithMiddlewares) {
+                throw error(404, "Route not found");
+            }
+            log("route id: %s", id);
+            // handle OPTIONS
+            if (request.method.toUpperCase() === "OPTIONS") {
+                return new Response(null, {
+                    headers: (_b = effectiveCorsSettings) !== null && _b !== void 0 ? _b : {}
+                });
+            }
+            const endpoint = routeWithMiddlewares.handlers[request.method.toUpperCase()];
+            if (!(endpoint === null || endpoint === void 0 ? void 0 : endpoint.handle)) {
+                throw error(405, "Method not allowed");
+            }
+            const param = await parseParam(params !== null && params !== void 0 ? params : {}, endpoint);
+            const query = await parseQuery(request, endpoint);
+            const body = await parseBody(request, endpoint);
+            log("handler: %O", endpoint.handle);
+            const output = await endpoint.handle({ body, query, param, event });
+            log("output: %O", output);
+            if (output instanceof Response) {
+                if (effectiveCorsSettings) {
+                    for (const [key, value] of Object.entries(effectiveCorsSettings)) {
+                        output.headers.set(key, value);
+                    }
+                }
+                return output;
+            }
+            // ReadableStream for Server-Sent Events
+            if (output instanceof ReadableStream) {
+                const res = new Response(output, {
+                    headers: {
+                        "Content-Type": "text/event-stream",
+                        "Cache-Control": "no-cache",
+                        Connection: "keep-alive",
+                        ...(effectiveCorsSettings !== null && effectiveCorsSettings !== void 0 ? effectiveCorsSettings : {}),
+                    },
+                });
+                return res;
+            }
+            if (output instanceof ArrayBuffer) {
+                const res = new Response(output, {
+                    headers: {
+                        "Content-Type": "application/octet-stream",
+                        ...(effectiveCorsSettings !== null && effectiveCorsSettings !== void 0 ? effectiveCorsSettings : {}),
+                    },
+                });
+                return res;
+            }
+            else {
+                const out = await recursiveAwait(await parseOutput(output, endpoint));
+                const res = json(out, {
+                    headers: (_c = effectiveCorsSettings) !== null && _c !== void 0 ? _c : {},
+                });
+                return res;
+            }
+        }
+        catch (e) {
+            if ('__HTTP_ERROR__' in e) {
+                return json(e, {
+                    status: e.status,
+                });
+            }
+            log("internal error: %O", e);
+            return json({ message: 'Internal server error', status: 500 }, {
+                status: 500,
+            });
+        }
+    };
+    return {
+        handler,
+        openapi: {
+            registry,
+            handler: openapiHandler(registry, config),
+        },
+    };
+};

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const METHOD: RegExp;
+export declare const CORS_DEFAULT: {
+    readonly "Access-Control-Allow-Origin": "*";
+    readonly "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS";
+    readonly "Access-Control-Allow-Headers": "Content-Type, Authorization";
+};

package/dist/constants.js

@@ -0,0 +1,6 @@
+export const METHOD = /^(GET|POST|PUT|DELETE|PATCH|OPTIONS)$/i;
+export const CORS_DEFAULT = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, PATCH, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Authorization",
+};

package/dist/endpoint.d.ts

@@ -0,0 +1,4 @@
+import type { EndpointHandler, EndpointSpecification, APIEndpoint, ParamType, QueryType, InputType, OutputType, StreamType, ErrorType } from "./types";
+export declare const endpoint: <P extends ParamType, Q extends QueryType, I extends InputType, O extends OutputType, S extends StreamType, E extends ErrorType>(data?: EndpointSpecification<P, Q, I, O, S, E>) => {
+    handler: (handle: EndpointHandler<P, Q, I, O>) => APIEndpoint<P, Q, I, O, S, E>;
+};

package/dist/endpoint.js

@@ -0,0 +1,3 @@
+export const endpoint = (data = {}) => ({
+    handler: (handle) => ({ ...data, handle }),
+});

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare const error: (status: number, message: string, key?: string) => {
+    __HTTP_ERROR__: boolean;
+    status: number;
+    message: string;
+    key: string | undefined;
+};

package/dist/errors.js

@@ -0,0 +1,6 @@
+export const error = (status, message, key) => ({
+    __HTTP_ERROR__: true,
+    status,
+    message,
+    key,
+});

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./api";
+export * from "./openapi";
+export * from "./zod";
+export * from "./adapters";
+export * from "./types";
+export * from "./endpoint";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./api.js";
+export * from "./openapi.js";
+export * from "./zod.js";
+export * from "./adapters.js";
+export * from "./types.js";
+export * from "./endpoint.js";

package/dist/log.d.ts

@@ -0,0 +1,2 @@
+import debug from "debug";
+export declare const log: debug.Debugger;

package/dist/log.js

@@ -0,0 +1,2 @@
+import debug from "debug";
+export const log = debug("riddl");

package/dist/middlewares.js

@@ -0,0 +1 @@
+"use strict";

package/dist/openapi.d.ts

@@ -0,0 +1,4 @@
+import { OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+import type { OpenAPIOptions, OpenAPIObjectConfig } from "./types";
+export declare const registerRoutes: ({ routes, registry, base, }: OpenAPIOptions) => void;
+export declare const openapiHandler: (registry: OpenAPIRegistry, config: OpenAPIObjectConfig) => (request: Request) => Promise<Response>;

package/dist/openapi.js

@@ -0,0 +1,113 @@
+import { OpenApiGeneratorV3, } from "@asteasolutions/zod-to-openapi";
+import { z } from "./zod.js";
+const openApiPath = (id, base) => id.split("/")
+    .slice(0, -1)
+    .join("/")
+    .replace(/^\./, base)
+    .replace(/\[(\.{3})?(.+?)\]/g, "{$2}")
+    .replace(/\(.+\)\//g, "");
+export const registerRoutes = ({ routes, registry, base = "/api", }) => {
+    for (const [id, { handlers }] of Object.entries(routes)) {
+        Object.entries(handlers).forEach(([methodString, module]) => {
+            var _a;
+            const modifier = module.Modifier || ((r) => r);
+            const query = module.Query || z.object({});
+            const params = module.Param || z.object({});
+            const body = module.Input || undefined;
+            const path = openApiPath(id, base);
+            const method = methodString.toLowerCase();
+            registry.registerPath(modifier({
+                method,
+                path,
+                request: {
+                    params,
+                    query,
+                    body: body
+                        ? {
+                            description: "",
+                            content: {
+                                "application/json": {
+                                    schema: body,
+                                },
+                                "application/x-www-form-urlencoded": {
+                                    schema: body,
+                                },
+                                "multipart/form-data": {
+                                    schema: body,
+                                },
+                            },
+                        }
+                        : undefined,
+                },
+                responses: {
+                    ...(module.Output
+                        ? {
+                            "200": {
+                                description: "",
+                                content: {
+                                    "application/json": {
+                                        schema: module.Output,
+                                    },
+                                },
+                            },
+                        }
+                        : undefined),
+                    ...(module.Stream
+                        ? {
+                            "200": {
+                                description: "",
+                                content: {
+                                    "text/event-stream": {
+                                        schema: module.Stream,
+                                    },
+                                },
+                            },
+                        }
+                        : undefined),
+                    ...(query || module.Param || body
+                        ? {
+                            "400": {
+                                description: "Invalid input (path parameters, query string, or body)",
+                                content: {
+                                    "application/json": {
+                                        schema: z.object({
+                                            message: z.string(),
+                                        }),
+                                    },
+                                },
+                            },
+                        }
+                        : undefined),
+                    ...((_a = Object.fromEntries((module.Error ? Object.entries(module.Error) : []).map(([status, error]) => [
+                        status,
+                        {
+                            description: error.message,
+                        },
+                    ]))) !== null && _a !== void 0 ? _a : {}),
+                },
+            }));
+        });
+    }
+};
+export const openapiHandler = (registry, config) => {
+    let document = undefined;
+    return async (request) => {
+        if (!document) {
+            const url = new URL(request.url).origin;
+            const generator = new OpenApiGeneratorV3(registry.definitions);
+            document = generator.generateDocument({
+                servers: [
+                    {
+                        url,
+                    },
+                ],
+                ...config,
+            });
+        }
+        return new Response(JSON.stringify(document), {
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+    };
+};

package/dist/parser.d.ts

@@ -0,0 +1,29 @@
+import type { RouteParam } from "./types";
+export declare const parseRouteId: (id: string) => {
+    pattern: RegExp;
+    params: RouteParam[];
+};
+/**
+ * Removes optional params from a route ID.
+ */
+export declare const removeOptionalParams: (id: string) => string;
+/**
+ * Splits a route id into its segments, removing segments that
+ * don't affect the path (i.e. groups). The root route is represented by `/`
+ * and will be returned as `['']`.
+ */
+export declare const getRouteSegments: (route: string) => string[];
+/**
+ * Populate a route ID with params to resolve a pathname.
+ * @example
+ * ```js
+ * resolveRoute(
+ *   `/blog/[slug]/[...somethingElse]`,
+ *   {
+ *     slug: 'hello-world',
+ *     somethingElse: 'something/else'
+ *   }
+ * ); // `/blog/hello-world/something/else`
+ * ```
+ */
+export declare const resolveRoute: (id: string, params: Record<string, string | undefined>) => string;

package/dist/parser.js

@@ -0,0 +1,143 @@
+const paramPattern = /^(\[)?(\.\.\.)?(\w+)(?:=(\w+))?(\])?$/;
+export const parseRouteId = (id) => {
+    const params = [];
+    const pattern = id === '/'
+        ? /^\/$/
+        : new RegExp(`^${getRouteSegments(id)
+            .map((segment) => {
+            // special case — /[...rest]/ could contain zero segments
+            const restMatch = /^\[\.\.\.(\w+)(?:=(\w+))?\]$/.exec(segment);
+            if (restMatch) {
+                params.push({
+                    name: restMatch[1],
+                    matcher: restMatch[2],
+                    optional: false,
+                    rest: true,
+                    chained: true
+                });
+                return '(?:/([^]*))?';
+            }
+            // special case — /[[optional]]/ could contain zero segments
+            const optionalMatch = /^\[\[(\w+)(?:=(\w+))?\]\]$/.exec(segment);
+            if (optionalMatch) {
+                params.push({
+                    name: optionalMatch[1],
+                    matcher: optionalMatch[2],
+                    optional: true,
+                    rest: false,
+                    chained: true
+                });
+                return '(?:/([^/]+))?';
+            }
+            if (!segment) {
+                return;
+            }
+            const parts = segment.split(/\[(.+?)\](?!\])/);
+            const result = parts
+                .map((content, i) => {
+                if (i % 2) {
+                    if (content.startsWith('x+')) {
+                        return escape(String.fromCharCode(parseInt(content.slice(2), 16)));
+                    }
+                    if (content.startsWith('u+')) {
+                        return escape(String.fromCharCode(...content
+                            .slice(2)
+                            .split('-')
+                            .map((code) => parseInt(code, 16))));
+                    }
+                    const match = (paramPattern.exec(content));
+                    if (!match) {
+                        throw new Error(`Invalid param: ${content}. Params and matcher names can only have underscores and alphanumeric characters.`);
+                    }
+                    const [, isOptional, isRest, name, matcher] = match;
+                    // It's assumed that the following invalid route id cases are already checked
+                    // - unbalanced brackets
+                    // - optional param following rest param
+                    params.push({
+                        name,
+                        matcher,
+                        optional: !!isOptional,
+                        rest: !!isRest,
+                        chained: isRest ? i === 1 && parts[0] === '' : false
+                    });
+                    return isRest ? '([^]*?)' : isOptional ? '([^/]*)?' : '([^/]+?)';
+                }
+                return escape(content);
+            })
+                .join('');
+            return '/' + result;
+        })
+            .join('')}/?$`);
+    return { pattern, params };
+};
+const optionalParamRegex = /\/\[\[\w+?(?:=\w+)?\]\]/;
+/**
+ * Removes optional params from a route ID.
+ */
+export const removeOptionalParams = (id) => {
+    return id.replace(optionalParamRegex, '');
+};
+/**
+ * Returns `false` for `(group)` segments
+ */
+function affectsPath(segment) {
+    return segment !== '' && !/^\([^)]+\)$/.test(segment);
+}
+/**
+ * Splits a route id into its segments, removing segments that
+ * don't affect the path (i.e. groups). The root route is represented by `/`
+ * and will be returned as `['']`.
+ */
+export const getRouteSegments = (route) => {
+    return route.slice(1).split('/').filter(affectsPath);
+};
+const escape = (str) => {
+    return (str
+        .normalize()
+        // escape [ and ] before escaping other characters, since they are used in the replacements
+        .replace(/[[\]]/g, '\\$&')
+        // replace %, /, ? and # with their encoded versions because decode_pathname leaves them untouched
+        .replace(/%/g, '%25')
+        .replace(/\//g, '%2[Ff]')
+        .replace(/\?/g, '%3[Ff]')
+        .replace(/#/g, '%23')
+        // escape characters that have special meaning in regex
+        .replace(/[.*+?^${}()|\\]/g, '\\$&'));
+};
+const basicParamPattern = /\[(\[)?(\.\.\.)?(\w+?)(?:=(\w+))?\]\]?/g;
+/**
+ * Populate a route ID with params to resolve a pathname.
+ * @example
+ * ```js
+ * resolveRoute(
+ *   `/blog/[slug]/[...somethingElse]`,
+ *   {
+ *     slug: 'hello-world',
+ *     somethingElse: 'something/else'
+ *   }
+ * ); // `/blog/hello-world/something/else`
+ * ```
+ */
+export const resolveRoute = (id, params) => {
+    const segments = getRouteSegments(id);
+    const hasIdTrailingSlash = id != '/' && id.endsWith('/');
+    return ('/' +
+        segments
+            .map((segment) => segment.replace(basicParamPattern, (_, optional, rest, name) => {
+            const paramValue = params[name];
+            // This is nested so TS correctly narrows the type
+            if (!paramValue) {
+                if (optional)
+                    return '';
+                if (rest && paramValue !== undefined)
+                    return '';
+                throw new Error(`Missing parameter '${name}' in route ${id}`);
+            }
+            if (paramValue.startsWith('/') || paramValue.endsWith('/'))
+                throw new Error(`Parameter '${name}' in route ${id} cannot start or end with a slash -- this would cause an invalid route like foo//bar`);
+            return paramValue;
+        }))
+            .filter(Boolean)
+            .join('/') +
+        (hasIdTrailingSlash ? '/' : ''));
+};

package/dist/routing.d.ts

@@ -0,0 +1,14 @@
+import type { MiddlewareMap, RouteModuleMap, RouteParam } from "./types";
+export declare const buildRouter: (routesMap: RouteModuleMap, middlewaresMap: MiddlewareMap) => (path: string) => {
+    id: string;
+    params: Record<string, string> | undefined;
+    routeWithMiddlewares: {
+        middlewares: import("./types").Middleware[];
+        matcher: {
+            pattern: RegExp;
+            params: RouteParam[];
+        };
+        handlers: Record<import("./types").Method, import("./types").GenericApiEndpoint>;
+        id: string;
+    };
+} | undefined;

package/dist/routing.js

@@ -0,0 +1,78 @@
+const exec = (match, params, matchers) => {
+    const result = {};
+    const values = match.slice(1);
+    const valuesNeedingMatch = values.filter((value) => value !== undefined);
+    let buffered = 0;
+    for (let i = 0; i < params.length; i += 1) {
+        const param = params[i];
+        let value = values[i - buffered];
+        // in the `[[a=b]]/.../[...rest]` case, if one or more optional parameters
+        // weren't matched, roll the skipped values into the rest
+        if (param.chained && param.rest && buffered) {
+            value = values
+                .slice(i - buffered, i + 1)
+                .filter((s) => s)
+                .join('/');
+            buffered = 0;
+        }
+        // if `value` is undefined, it means this is an optional or rest parameter
+        if (value === undefined) {
+            if (param.rest) {
+                // We need to allow the matcher to run so that it can decide if this optional rest param should be allowed to match
+                value = '';
+            }
+            else {
+                continue;
+            }
+        }
+        if (!param.matcher || matchers[param.matcher](value)) {
+            result[param.name] = value;
+            // Now that the params match, reset the buffer if the next param isn't the [...rest]
+            // and the next value is defined, otherwise the buffer will cause us to skip values
+            const nextParam = params[i + 1];
+            const nextValue = values[i + 1];
+            if (nextParam && !nextParam.rest && nextParam.optional && nextValue && param.chained) {
+                buffered = 0;
+            }
+            // There are no more params and no more values, but all non-empty values have been matched
+            if (!nextParam &&
+                !nextValue &&
+                Object.keys(result).length === valuesNeedingMatch.length) {
+                buffered = 0;
+            }
+            continue;
+        }
+        // in the `/[[a=b]]/...` case, if the value didn't satisfy the matcher,
+        // keep track of the number of skipped optional parameters and continue
+        if (param.optional && param.chained) {
+            buffered++;
+            continue;
+        }
+        // otherwise, if the matcher returns `false`, the route did not match
+        return;
+    }
+    if (buffered)
+        return;
+    return result;
+};
+const routeSorter = (a, b) => {
+    return a.id.length - b.id.length;
+};
+export const buildRouter = (routesMap, middlewaresMap) => {
+    const middlewareEntries = Object.entries(middlewaresMap).sort((a, b) => a[0].length - b[0].length);
+    const routesWithMiddlewaresList = Object.entries(routesMap).map(([id, route]) => ({
+        id,
+        ...route,
+        middlewares: middlewareEntries.filter(([middlewareId]) => id.startsWith(middlewareId)).map(([_, middleware]) => middleware),
+    })).sort(routeSorter);
+    return (path) => {
+        for (const route of routesWithMiddlewaresList) {
+            const { pattern } = route.matcher;
+            const matches = pattern.exec(path);
+            if (matches) {
+                return { id: route.id, params: exec(matches, route.matcher.params, {}), routeWithMiddlewares: route };
+            }
+        }
+        return undefined;
+    };
+};

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+import type { RouteConfig, OpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+import type { OpenAPIObjectConfig } from "@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator";
+import type { z } from "./zod";
+export type { OpenAPIObject } from "openapi3-ts/oas30";
+export type { OpenAPIObjectConfig } from "@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator";
+export type Method = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS";
+export interface HttpError {
+    status: number;
+    key?: string;
+    message?: string;
+    properties?: Record<string, string>;
+}
+export interface RouteParam {
+    name: string;
+    matcher: string;
+    optional: boolean;
+    rest: boolean;
+    chained: boolean;
+}
+export type Middleware = {
+    pre: (event: RequestEvent) => Promise<RequestEvent>;
+    post: (event: RequestEvent) => Promise<RequestEvent>;
+};
+export interface ApiRoute {
+    matcher: {
+        pattern: RegExp;
+        params: RouteParam[];
+    };
+    handlers: Record<Method, GenericApiEndpoint>;
+}
+export interface ApiRouteWithMiddlewares extends ApiRoute {
+    middlewares: Middleware[];
+}
+export type RouteModuleMap = Record<string, {
+    matcher: {
+        pattern: RegExp;
+        params: RouteParam[];
+    };
+    handlers: Record<Method, GenericApiEndpoint>;
+}>;
+export type RouteWithMiddlewaresMap = Record<string, ApiRouteWithMiddlewares>;
+export type MiddlewareMap = Record<string, Middleware>;
+export type MatcherMap = Record<string, {
+    pattern: RegExp;
+    params: RouteParam[];
+}>;
+export interface APIContext {
+    routes: RouteWithMiddlewaresMap;
+    matchers: MatcherMap;
+}
+/**
+ * Modify route config after parsing input-output shapes.
+ * Useful for adding custom tags, etc.
+ *
+ * @param r Route config
+ * @returns Modified route config
+ * @example
+ * ```ts
+ * export const Modifier: RouteModifier = (r) => {
+ *     r.tags = ["Tag"];
+ *     r.operationId = "customOperationId";
+ *     r.security = [{ bearerAuth: [] }];
+ *     return r;
+ * };
+ * ```
+ */
+export type EndpointModifier = (r: RouteConfig) => RouteConfig;
+export interface CORS {
+    "Access-Control-Allow-Origin": string;
+    "Access-Control-Allow-Methods": string;
+    "Access-Control-Allow-Headers": string;
+}
+export interface APIOptions {
+    routeModuleMap: Record<string, () => Promise<unknown>>;
+    config: OpenAPIObjectConfig;
+    base?: string;
+    cors?: boolean | CORS;
+    registry?: OpenAPIRegistry;
+}
+export interface OpenAPIOptions {
+    base?: string;
+    routes: RouteModuleMap;
+    registry: OpenAPIRegistry;
+}
+export interface EndpointHandler<P, Q, I, O> {
+    ({ body, query, param, event }: {
+        body: z.infer<I>;
+        query: z.infer<Q>;
+        param: z.infer<P>;
+        event: RequestEvent;
+    }): Promise<z.input<O>>;
+}
+export type ParamType = z.ZodObject;
+export type QueryType = z.ZodObject;
+export type InputType = z.ZodType;
+export type OutputType = z.ZodType;
+export type StreamType = z.ZodType;
+export type ErrorType = Record<string, HttpError>;
+export interface EndpointSpecification<P extends ParamType, Q extends QueryType, I extends InputType, O extends OutputType, S extends StreamType, E extends ErrorType> {
+    Param?: P;
+    Query?: Q;
+    Input?: I;
+    Output?: O;
+    Stream?: S;
+    Error?: E;
+    Modifier?: EndpointModifier;
+}
+export interface APIEndpoint<P extends ParamType = z.ZodObject<Record<never, never>>, Q extends QueryType = z.ZodObject<Record<never, never>>, I extends InputType = z.ZodObject<Record<never, never>>, O extends OutputType = z.ZodObject<Record<never, never>>, S extends StreamType = z.ZodObject<Record<never, never>>, E extends ErrorType = Record<string, HttpError>> extends EndpointSpecification<P, Q, I, O, S, E> {
+    /**
+     * Handler
+     */
+    handle?: EndpointHandler<P, Q, I, O>;
+}
+export interface EndpointBuilder<P extends ParamType, Q extends QueryType, I extends InputType, O extends OutputType, S extends StreamType, E extends ErrorType> {
+    (spec: EndpointSpecification<P, Q, I, O, S, E>): ({
+        handler: () => APIEndpoint<P, Q, I, O, S, E>;
+    });
+}
+export interface EndpointStreamSetter<P extends ParamType, Q extends QueryType, I extends InputType, O extends OutputType, S extends StreamType, E extends ErrorType> {
+    (data: APIEndpoint<P, Q, I, O, S, E>): EndpointBuilder<P, Q, I, O, S, E>;
+}
+export type GenericApiEndpoint = APIEndpoint<ParamType, QueryType, InputType, OutputType, StreamType, ErrorType>;
+export interface GenericApiEndpointModule {
+    apiEndpoint: GenericApiEndpoint;
+}
+declare global {
+    namespace Riddl {
+        interface RequestContext {
+        }
+    }
+}
+export interface RequestEvent {
+    request: Request;
+    url: URL;
+    context: Riddl.RequestContext;
+}
+export interface Handler {
+    (request: Request): Promise<Response>;
+}
+export interface API {
+    handler: Handler;
+    openapi: {
+        registry: OpenAPIRegistry;
+        handler: Handler;
+    };
+}
+export type ParamMatcher = (param: string) => boolean;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage } from "http";
+import type { Request as ExpressRequest } from "express";
+export declare const recursiveAwait: (obj: unknown) => unknown;
+export declare const validateRouteId: (id: string) => void;
+export declare const toFetchRequest: (req: IncomingMessage | ExpressRequest) => Request;
+export declare function json(data: unknown, init?: ResponseInit): Response;

package/dist/utils.js

@@ -0,0 +1,135 @@
+const textEncoder = new TextEncoder();
+export const recursiveAwait = (obj) => {
+    if (obj instanceof Promise) {
+        return obj.then(recursiveAwait);
+    }
+    else if (obj instanceof Array) {
+        return Promise.all(obj.map(recursiveAwait));
+    }
+    else if (obj instanceof Object) {
+        const keys = Object.keys(obj);
+        const values = Object.values(obj);
+        return Promise.all(values.map(recursiveAwait)).then((values) => {
+            const returns = {};
+            for (let i = 0; i < keys.length; i++) {
+                returns[keys[i]] = values[i];
+            }
+            return returns;
+        });
+    }
+    else {
+        return obj;
+    }
+};
+const countOccurrences = (needle, haystack) => {
+    let count = 0;
+    for (let i = 0; i < haystack.length; i += 1) {
+        if (haystack[i] === needle)
+            count += 1;
+    }
+    return count;
+};
+export const validateRouteId = (id) => {
+    if (/\]\[/.test(id)) {
+        throw new Error(`Invalid route ${id} — parameters must be separated`);
+    }
+    if (countOccurrences('[', id) !== countOccurrences(']', id)) {
+        throw new Error(`Invalid route ${id} — brackets are unbalanced`);
+    }
+    if (/\[\.\.\.\w+\]\/\[\[/.test(id)) {
+        throw new Error(`Invalid route ${id} — an [[optional]] route segment cannot follow a [...rest] route segment`);
+    }
+    if (/\[\[\.\.\./.test(id)) {
+        throw new Error(`Invalid route ${id} — a rest route segment is always optional, remove the outer square brackets`);
+    }
+};
+const isNodeReadable = (value) => !!value && typeof value.pipe === "function";
+const isBodyInit = (value) => {
+    if (typeof value === "string")
+        return true;
+    if (value instanceof ArrayBuffer)
+        return true;
+    if (ArrayBuffer.isView(value))
+        return true;
+    if (typeof Blob !== "undefined" && value instanceof Blob)
+        return true;
+    if (typeof FormData !== "undefined" && value instanceof FormData)
+        return true;
+    if (value instanceof URLSearchParams)
+        return true;
+    if (typeof ReadableStream !== "undefined" && value instanceof ReadableStream)
+        return true;
+    if (isNodeReadable(value))
+        return true;
+    return false;
+};
+const coerceBody = (body, headers) => {
+    if (body == null)
+        return undefined;
+    if (isBodyInit(body))
+        return body;
+    const json = JSON.stringify(body);
+    if (!headers.has("content-type")) {
+        headers.set("content-type", "application/json; charset=utf-8");
+    }
+    return json;
+};
+const getRequestUrl = (req) => {
+    var _a;
+    const rawUrl = "originalUrl" in req ? req.originalUrl || req.url || "/" : req.url || "/";
+    if (/^https?:\/\//i.test(rawUrl))
+        return new URL(rawUrl);
+    if ("protocol" in req) {
+        return new URL(rawUrl, `${req.protocol}://${req.get("host")}`);
+    }
+    const host = (_a = req.headers.host) !== null && _a !== void 0 ? _a : "localhost";
+    const forwardedProto = req.headers["x-forwarded-proto"];
+    const proto = Array.isArray(forwardedProto)
+        ? forwardedProto[0]
+        : forwardedProto;
+    const protocol = (proto === null || proto === void 0 ? void 0 : proto.split(",")[0].trim()) || "http";
+    return new URL(rawUrl, `${protocol}://${host}`);
+};
+export const toFetchRequest = (req) => {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (Array.isArray(value))
+            headers.append(key, value.join(","));
+        else if (value != null)
+            headers.set(key, value);
+    }
+    const method = req.method || "GET";
+    const expressReq = req;
+    const parsedBody = "body" in expressReq ? expressReq.body : undefined;
+    const rawBody = "rawBody" in expressReq ? expressReq.rawBody : undefined;
+    let body;
+    if (method !== "GET" && method !== "HEAD") {
+        body = coerceBody(rawBody !== null && rawBody !== void 0 ? rawBody : parsedBody, headers);
+        if (body === undefined && isNodeReadable(req) && !req.readableEnded) {
+            body = req;
+        }
+    }
+    const init = {
+        method,
+        headers,
+        body: body,
+    };
+    if (isNodeReadable(body)) {
+        init.duplex = "half"; // required when body is a stream
+    }
+    return new Request(getRequestUrl(req).toString(), init);
+};
+export function json(data, init) {
+    const body = JSON.stringify(data);
+    const headers = new Headers(init === null || init === void 0 ? void 0 : init.headers);
+    if (!headers.has('content-length')) {
+        headers.set('content-length', textEncoder.encode(body).byteLength.toString());
+    }
+    if (!headers.has('content-type')) {
+        headers.set('content-type', 'application/json');
+    }
+    return new Response(body, {
+        ...init,
+        headers,
+    });
+}

package/dist/validation.d.ts

@@ -0,0 +1,5 @@
+import { GenericApiEndpoint } from "./types";
+export declare const parseBody: (req: Request, module: GenericApiEndpoint) => Promise<unknown>;
+export declare const parseQuery: (request: Request, module: GenericApiEndpoint) => Promise<Record<string, string | string[]>>;
+export declare const parseParam: (params: Record<string, string>, module: GenericApiEndpoint) => Promise<Record<string, string | never>>;
+export declare const parseOutput: (out: unknown, module: GenericApiEndpoint) => Promise<Record<string, unknown> | unknown[]>;

package/dist/validation.js

@@ -0,0 +1,130 @@
+import { fromZodError } from "zod-validation-error";
+import { log } from "./log.js";
+import { z } from "./zod.js";
+import { error } from "./errors.js";
+const parseJsonBody = async (req) => {
+    var _a;
+    const clonedRequest = req.clone();
+    if ((_a = clonedRequest.headers.get("content-type")) === null || _a === void 0 ? void 0 : _a.startsWith("application/json")) {
+        try {
+            const json = await clonedRequest.json();
+            if (typeof json === "object") {
+                return json;
+            }
+        }
+        catch {
+            throw error(400, "Invalid JSON body");
+        }
+    }
+};
+export const parseBody = async (req, module) => {
+    var _a, _b, _c, _d, _e, _f;
+    let body = {};
+    // GET, HEAD, DELETE, OPTIONS have no body
+    const method = req.method.toUpperCase();
+    if (["GET", "HEAD", "DELETE", "OPTIONS"].includes(method)) {
+        return body;
+    }
+    const clonedRequest = req.clone();
+    // JSON body
+    if ((_a = clonedRequest.headers.get("content-type")) === null || _a === void 0 ? void 0 : _a.startsWith("application/json")) {
+        body = clonedRequest.json().catch(() => { throw error(400, "Invalid JSON body"); });
+    }
+    // Form body
+    else if (((_b = clonedRequest.headers
+        .get("content-type")) === null || _b === void 0 ? void 0 : _b.startsWith("application/x-www-form-urlencoded")) ||
+        ((_c = clonedRequest.headers.get("content-type")) === null || _c === void 0 ? void 0 : _c.startsWith("multipart/form-data"))) {
+        const formBody = {};
+        const form = await clonedRequest.formData();
+        for (const [key, value] of form.entries()) {
+            if (formBody[key]) {
+                const existing = formBody[key];
+                if (Array.isArray(existing)) {
+                    existing.push(value);
+                }
+                else {
+                    formBody[key] = [existing, value];
+                }
+            }
+            else {
+                formBody[key] = value;
+            }
+        }
+        body = formBody;
+    }
+    // Text body
+    else if ((_d = clonedRequest.headers.get("content-type")) === null || _d === void 0 ? void 0 : _d.startsWith("text/plain")) {
+        body = { text: await clonedRequest.text() };
+    }
+    // Binary body
+    else if ((_e = clonedRequest.headers.get("content-type")) === null || _e === void 0 ? void 0 : _e.startsWith("application/octet-stream")) {
+        const buffer = await clonedRequest.arrayBuffer();
+        body = { buffer };
+    }
+    log("body: %O", body);
+    const validator = (_f = module.Input) !== null && _f !== void 0 ? _f : z.object({});
+    const validation = validator.safeParse(body);
+    if (!validation.success) {
+        throw error(400, `Invalid body.\n${fromZodError(validation.error).message}`);
+    }
+    else {
+        body = validation.data;
+    }
+    return body;
+};
+export const parseQuery = async (request, module) => {
+    var _a;
+    let query = {};
+    for (const [key, value] of new URL(request.url).searchParams.entries()) {
+        if (query[key]) {
+            const existing = query[key];
+            if (Array.isArray(existing)) {
+                existing.push(value);
+            }
+            else {
+                query[key] = [existing, value];
+            }
+        }
+        else {
+            query[key] = value;
+        }
+    }
+    log("query: %O", query);
+    const validator = (_a = module.Query) !== null && _a !== void 0 ? _a : z.object({});
+    const validation = validator.safeParse(query);
+    if (!validation.success) {
+        throw error(400, `Invalid query.\n${fromZodError(validation.error).message}`);
+    }
+    else {
+        query = validation.data;
+    }
+    return query;
+};
+export const parseParam = async (params, module) => {
+    var _a;
+    log("param: %O", params);
+    const validator = (_a = module.Param) !== null && _a !== void 0 ? _a : z.object({});
+    const validation = validator.safeParse(params);
+    if (!validation.success) {
+        throw error(400, `Invalid param.\n${fromZodError(validation.error).message}`);
+    }
+    else {
+        return validation.data;
+    }
+};
+export const parseOutput = async (out, module) => {
+    var _a;
+    let output = Array.isArray(out)
+        ? out
+        : out && typeof out === "object" ? out : {};
+    const validator = (_a = module.Output) !== null && _a !== void 0 ? _a : z.object({});
+    const validation = await validator.spa(output);
+    if (!validation.success) {
+        log.extend("error")("output: %O failed validation: %O", output, validation.error);
+        throw error(500, "Output validation failed. Please report this error to the developer.");
+    }
+    else {
+        output = validation.data;
+    }
+    return output;
+};

package/dist/zod.d.ts

@@ -0,0 +1,2 @@
+import { z } from "zod";
+export { z };

package/dist/zod.js

@@ -0,0 +1,4 @@
+import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";
+import { z } from "zod";
+extendZodWithOpenApi(z);
+export { z };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@riddl/core",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.4.0",
+    "debug": "^4.4.0",
+    "express": "^5.2.1",
+    "set-cookie-parser": "^3.0.1",
+    "sse.js": "^2.5.0",
+    "zod": "^4.3.6",
+    "zod-validation-error": "^5.0.0"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./dist/*/index.js"
+  },
+  "files": [
+    "/dist"
+  ],
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/express": "^5.0.6",
+    "@types/set-cookie-parser": "^2.4.10",
+    "@typescript-eslint/eslint-plugin": "^8.19.0",
+    "@typescript-eslint/parser": "^8.19.0",
+    "concurrently": "^9.1.2",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^9.1.0",
+    "openapi3-ts": "^4.5.0",
+    "prettier": "^3.4.2",
+    "tsc-alias": "^1.8.10",
+    "type-fest": "^4.31.0",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "lint": "prettier --check . && eslint .",
+    "format": "prettier --write .",
+    "clean": "rm -f tsconfig.tsbuildinfo dist",
+    "build": "tsc && tsc-alias",
+    "build:watch": "tsc && tsc-alias && (concurrently \"tsc -w\" \"tsc-alias -w\")"
+  }
+}