starlight-server 0.0.1

package/dist/router/match.js

@@ -0,0 +1,172 @@
+/**
+ * 匹配路由路径
+ *
+ * 支持的格式：
+ * 1. /abc/ abc/ /abc => 这几种形式等价
+ * 2. /abc/:foo/bar => 命名参数（foo）
+ * 3. /abc/:foo?/bar => 可选命名参数（foo）
+ * 4. /abc/* => 后续路径（任意长度，* 只能出现在路由最后面，匹配结果不含开头的“/”）
+ *
+ * 路由不区分大小写
+ */
+import escapeRegExp from 'lodash/escapeRegExp.js';
+/**
+ * 标准化路径
+ * 标准化后，相同的两个路径一定也是相同的字符串（例如 /Abc/Def 和 abc/def/ 都会变成 abc/def）。
+ *
+ * - 移除首尾和重复的 '/'，完成后有 path 有这几种可能的格式： ''、'abc'、'abc/def'
+ * - 统一改为小写
+ */
+export function normalizePath(path) {
+    if (path.startsWith('/'))
+        path = path.slice(1);
+    if (path.endsWith('/'))
+        path = path.slice(0, -1);
+    path = path.replace(/\/+/g, '/');
+    return path.toLowerCase();
+}
+/**
+ * 解析路由路径定义
+ * '/abc/:foo?/*' => [{ type: 'text', text: 'abc' }, { type: 'named', name: 'foo', optional: true }, { type: 'rest' }]
+ */
+function parseRoutePath(routePath) {
+    const normalizedPath = normalizePath(routePath);
+    const nodes = [];
+    const pathParts = normalizedPath.split('/');
+    for (const [i, part] of pathParts.entries()) {
+        if (part.startsWith(':') && part !== ':' && part !== ':?') {
+            const optional = part.endsWith('?');
+            const name = optional ? part.slice(1, -1) : part.slice(1);
+            if (name === '*')
+                throw new Error('route path parameter name cannot be "*"');
+            nodes.push({ type: PathNodeType.Named, name, optional });
+        }
+        else if (part === '*' && i === pathParts.length - 1) {
+            nodes.push({ type: PathNodeType.Rest });
+        }
+        else {
+            nodes.push({ type: PathNodeType.Text, text: part });
+        }
+    }
+    return nodes;
+}
+var PathNodeType;
+(function (PathNodeType) {
+    /** 纯文本 */
+    PathNodeType["Text"] = "text";
+    /** 命名参数 */
+    PathNodeType["Named"] = "named";
+    /** 后续路径 */
+    PathNodeType["Rest"] = "rest";
+})(PathNodeType || (PathNodeType = {}));
+/**
+ * 把路由定义转换成正则表达式
+ *
+ * Nodes                      | Path          | RegExp
+ * -------------------------- | ------------- | ----------------------------
+ * []                         |               | ^$
+ * ['abc']                    | abc           | ^abc$
+ * ['abc', named:foo, 'xyz']  | abc/:foo/xyz  | ^abc/([^/]+?)/xyz$
+ * ['abc', named:foo?, 'xyz'] | abc/:foo?/xyz | ^abc(?:/([^/]+?))?/xyz$
+ * ['abc', named:foo?, rest]  | abc/:foo?/*   | ^abc(?:/([^/]+?))?(?:/(.+))?$
+ *
+ * ^(?:/(.+))?$
+ */
+function parsedPathToRegExp(parsedPath) {
+    const regexpParts = [];
+    for (const node of parsedPath) {
+        const prefix = node === parsedPath[0] ? '' : '/';
+        if (node.type === PathNodeType.Text) {
+            regexpParts.push(prefix + escapeRegExp(node.text));
+        }
+        else if (node.type === PathNodeType.Named) {
+            regexpParts.push(node.optional ? `(?:${prefix}([^/]+?))?` : `${prefix}([^/]+?)`);
+        }
+        else {
+            regexpParts.push(`(?:${prefix}(.+))?`);
+        }
+    }
+    return new RegExp('^' + regexpParts.join('') + '$', 'i');
+}
+/**
+ * 比较两个路径的优先级（两个路由都能匹配路径时，优先级更高的生效）
+ *
+ * pathA 优先：-1
+ * pathB 优先：1
+ *
+ * 规则：
+ * 1. 挨个 node 比对
+ * 2. 先匹配各节点的类型，text > named > named optional > rest
+ * 3. 节点类型都一致，节点数量多的优先级更高
+ * 4. 节点类型、数量都一样，后出现的覆盖先出现的
+ */
+function pathSorter(pathA, pathB) {
+    const typePriorities = [PathNodeType.Text, PathNodeType.Named, PathNodeType.Rest];
+    const length = Math.max(pathA.length, pathB.length);
+    for (let i = 0; i < length; i++) {
+        const a = pathA[i];
+        const b = pathB[i];
+        // 若 nodes 长度不一样，长的优先
+        if (a === undefined)
+            return -1;
+        else if (b === undefined)
+            return 1;
+        // node 类型不一样，按类型排序
+        const aTypePriority = typePriorities.indexOf(a.type);
+        const bTypePriority = typePriorities.indexOf(b.type);
+        if (aTypePriority !== bTypePriority)
+            return aTypePriority - bTypePriority;
+        // 若都是 named 类型但 optional 不同
+        if (a.type === PathNodeType.Named &&
+            b.type === PathNodeType.Named &&
+            a.optional !== b.optional) {
+            return a.optional ? 1 : -1;
+        }
+    }
+    // 长度、类型都一样，后出现的优先
+    return 1;
+}
+/**
+ * 返回匹配的路由及匹配上的路径参数
+ */
+export function matchRoutes(requestPath, routes) {
+    if (!parsedCache.has(routes)) {
+        // 解析路由路径并按优先级排序
+        const parsedRoutes = routes
+            .map(route => {
+            const parsedPath = parseRoutePath(route.path);
+            const regexp = parsedPathToRegExp(parsedPath);
+            return { parsedPath, regexp, route };
+        })
+            .sort((a, b) => pathSorter(a.parsedPath, b.parsedPath));
+        parsedCache.set(routes, parsedRoutes);
+    }
+    requestPath = normalizePath(requestPath);
+    const parsedRoutes = parsedCache.get(routes);
+    return parsedRoutes
+        .map(({ parsedPath, regexp, route }) => {
+        const match = regexp.exec(requestPath);
+        if (!match)
+            return null;
+        const pathParameters = matchPathParameters(parsedPath, [...match].slice(1));
+        return { route, pathParameters };
+    })
+        .filter((matched) => matched !== null);
+}
+const parsedCache = new WeakMap();
+/**
+ * 把匹配到的路径参数映射成键值对
+ * 没匹配到的内容（optional named node / rest node）值为 undefined
+ */
+function matchPathParameters(parsedPath, parameterNames) {
+    const parameters = {};
+    for (const node of parsedPath) {
+        if (node.type === PathNodeType.Text)
+            continue;
+        else if (node.type === PathNodeType.Named)
+            parameters[node.name] = parameterNames.shift();
+        else
+            parameters['*'] = parameterNames.shift();
+    }
+    return parameters;
+}

package/dist/router/parameters.d.ts

@@ -0,0 +1,51 @@
+import { type Request } from '../http/index.js';
+import { type Route } from './router.js';
+/**
+ * ----------------------------------------
+ * 类型定义
+ * ----------------------------------------
+ */
+/**
+ * 请求参数定义
+ */
+export interface Parameter {
+    /** 字段名 */
+    name: string;
+    /** 文字描述  */
+    describe?: string;
+    type: ParameterDataType;
+    /** 默认值，应与 type 匹配。若指定，则不再需要 required 规则。 */
+    defaults?: unknown;
+    /** 是否允许为 undefined  */
+    required?: boolean;
+    /** 是否允许为 null */
+    nullable?: boolean;
+    /** 验证规则，会传给 type 对应的 validator */
+    validate?: Record<string, unknown>;
+}
+export type BasicDataType = 'string' | 'number' | 'boolean';
+type BasicParameter = Pick<Parameter, 'type' | 'validate' | 'required' | 'nullable' | 'defaults'>;
+/**
+ * 请求参数的数据类型定义
+ */
+export type ParameterDataType = BasicDataType | {
+    array: BasicParameter;
+} | {
+    record: BasicParameter;
+} | {
+    object: Record<string, BasicParameter>;
+};
+/**
+ * ----------------------------------------
+ * 与请求内容对接
+ * ----------------------------------------
+ */
+/**
+ * 验证 query 内容
+ */
+export declare function parseQuery<T>(route: Route, request: Request): T;
+/**
+ * 验证 body 内容
+ */
+export declare function parseJSONBody<T>(route: Route, request: Request): Promise<T>;
+export {};

package/dist/router/parameters.js

@@ -0,0 +1,118 @@
+/**
+ * 实现通过 query / body parameters 的解析和验证
+ */
+import { success } from '@anjianshi/utils';
+import { HTTPError } from '../http/index.js';
+import * as validators from '../validators/index.js';
+/**
+ * ----------------------------------------
+ * 基础功能实现
+ * ----------------------------------------
+ */
+/**
+ * 基于 parameter 定义验证、格式化数据
+ */
+function validateParameters(parameters, rawData) {
+    const result = {};
+    for (const parameter of parameters) {
+        const validator = getValidatorOfParameter(parameter);
+        const validateRes = validator.validate(parameter.name, rawData[parameter.name]);
+        if (validateRes.success)
+            result[parameter.name] = validateRes.data;
+        else
+            return validateRes;
+    }
+    return success(result);
+}
+/**
+ * 获取指定 parameter 的 validator
+ */
+function getValidatorOfParameter(parameter) {
+    if (!validatorCache.has(parameter)) {
+        const validatorConstructor = getValidatorConstructor(parameter.type);
+        const options = {
+            null: parameter.nullable,
+            void: typeof parameter.required === 'boolean' ? parameter.required : undefined,
+            defaults: parameter.defaults,
+            ...(parameter.validate ?? {}),
+        };
+        const validator = validatorConstructor(options);
+        validatorCache.set(parameter, validator);
+    }
+    return validatorCache.get(parameter);
+}
+const validatorCache = new WeakMap();
+/**
+ * 取得与参数类型对应的 validator constructor
+ */
+function getValidatorConstructor(type) {
+    if (typeof type === 'string')
+        return validators[type];
+    if ('array' in type) {
+        const itemValidator = getValidatorOfParameter(type.array);
+        return validators.array.bind(null, itemValidator);
+    }
+    if ('record' in type) {
+        const itemValidator = getValidatorOfParameter(type.record);
+        return validators.object.bind(null, itemValidator);
+    }
+    const struct = {};
+    for (const [key, innerParameter] of Object.entries(type.object)) {
+        struct[key] = getValidatorOfParameter(innerParameter);
+    }
+    return validators.object.bind(null, struct);
+}
+/**
+ * ----------------------------------------
+ * 与请求内容对接
+ * ----------------------------------------
+ */
+/**
+ * 验证 query 内容
+ */
+export function parseQuery(route, request) {
+    if (!route.query)
+        throw new HTTPError(500, 'Call parseQuery() need query parameter definition.');
+    const values = {};
+    for (const parameter of route.query) {
+        values[parameter.name] = getQueryParameterValue(request, parameter);
+    }
+    const res = validateParameters(route.query, values);
+    if (res.success)
+        return res.data;
+    throw new HTTPError(400, res.error);
+}
+function getQueryParameterValue(request, parameter) {
+    // array
+    if (typeof parameter.type === 'object' && 'array' in parameter.type) {
+        return request.query.getAll(parameter.name + '[]');
+    }
+    // undefined
+    const raw = request.query.get(parameter.name);
+    if (raw === null || raw === '')
+        return undefined;
+    // basic type
+    if (typeof parameter.type === 'string')
+        return raw;
+    // object
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new HTTPError(400, `Invalid JSON value for query parameter "${parameter.name}".`);
+    }
+}
+/**
+ * 验证 body 内容
+ */
+export async function parseJSONBody(route, request) {
+    if (!route.body)
+        throw new HTTPError(500, 'call parseJSONBody() need body parameter definition.');
+    const body = await request.body.json();
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new HTTPError(400, 'Invalid JSON body, should be an object.');
+    const res = validateParameters(route.body, body);
+    if (res.success)
+        return res.data;
+    throw new HTTPError(400, res.error);
+}

package/dist/router/router.d.ts

@@ -0,0 +1,127 @@
+import { type RequiredFields } from '@anjianshi/utils';
+import { type Request, type ResponseUtils } from '../http/index.js';
+import { type CORSOptions } from './cors.js';
+import { type PathParameters, type RouteMatch } from './match.js';
+import { type BasicDataType, type Parameter } from './parameters.js';
+/**
+ * -----------------------------------------
+ * 类型定义
+ * -----------------------------------------
+ */
+/**
+ * 请求上下文（由 Router 生成并传给请求处理函数）
+ */
+export interface BaseContext {
+    request: Request;
+    response: ResponseUtils;
+    parseQuery: <T>() => T;
+    parseBody: <T>() => Promise<T>;
+}
+/**
+ * 请求处理函数
+ */
+export type RouteHandler<Ctx extends BaseContext = BaseContext, PathP extends PathParameters = PathParameters> = (context: Ctx, pathParameters: PathP) => unknown;
+/**
+ * 路由定义
+ *
+ * 相比 RawRoute：
+ * - 有默认值的字段均填充了默认值
+ * - method 一定为全大写
+ */
+export type Route<Ctx extends BaseContext = BaseContext, PathP extends PathParameters = PathParameters> = RequiredFields<RawRoute<Ctx, PathP>, 'describe' | 'category' | 'method'>;
+export interface RawRoute<Ctx extends BaseContext = BaseContext, PathP extends PathParameters = PathParameters> {
+    /** 接口路径。支持变量（/abc/:xxx/def），详见 src/router/match.ts */
+    path: string;
+    /** 接口描述  */
+    describe?: string;
+    /** 接口类别 */
+    category?: string;
+    /** 接口 HTTP Method，有 body 定义的默认为 POST，否则默认为 GET */
+    method?: string;
+    /** Query String 定义  */
+    query?: Parameter[];
+    /** JSON Request Body 定义 */
+    body?: Parameter[];
+    /**
+     * JSON 返回内容定义（返回的不是 JSON 时（如纯文本、二进制文件），不定义此项）
+     * - 若指定的是 ResponseDataType[]，代表有多种可能返回的类型。例如 ['string' | 'null'] 可能返回字符串也可能返回 null
+     */
+    response?: ResponseDataType | ResponseDataType[];
+    /**
+     * 指定此接口的 CORS 配置
+     * 不指定则由 router.getCORSOptions() 提供
+     */
+    cors?: CORSOptions;
+    handler: RouteHandler<Ctx, PathP>;
+}
+/**
+ * JSON 响应内容的类型定义
+ * { array: ResponseDataType[] } 代表数组元素有多种可能的类型
+ */
+export type ResponseDataType = BasicDataType | 'null' | {
+    array: ResponseDataType | ResponseDataType[];
+} | {
+    object: ResponseObjectItemType[];
+} | {
+    ref: string;
+    summary?: string;
+    description?: string;
+};
+/**
+ * JSON object 相应内容的字段定义
+ */
+export interface ResponseObjectItemType {
+    /** 字段名 */
+    name: string;
+    /** 文字描述  */
+    describe?: string;
+    /** 值类型。ResponseDataType[] 代表有多种可能的类型 */
+    type: ResponseDataType | ResponseDataType[];
+}
+/**
+ * -----------------------------------------
+ * Router 类
+ * -----------------------------------------
+ */
+export declare abstract class Router<Ctx extends BaseContext = BaseContext> {
+    /**
+     * 路由列表
+     */
+    readonly routes: Route<Ctx>[];
+    /**
+     * 注册路由
+     */
+    register<P = Record<string, never>>(method: string, path: string, handler: RouteHandler<Ctx, PathParameters & P>): void;
+    register<P extends Record<string, string>>(raw: RawRoute<Ctx, PathParameters & P>): void;
+    /**
+     * 响应请求
+     */
+    readonly handle: (request: Request, response: ResponseUtils) => Promise<void>;
+    /**
+     * 匹配路由，成功返回路由对象，失败抛出 HTTPError，提前结束处理返回 null
+     */
+    protected match(request: Request, response: ResponseUtils): RouteMatch<Route<Ctx, PathParameters>> | null;
+    /**
+     * 为未指定 CORS 配置的 route 提供默认配置
+     */
+    getCORSOptions(request: Request, routeMatch: RouteMatch<Route<Ctx>>): boolean;
+    /**
+     * 完善 context 对象并执行 route
+     * 注意：handler 在很多时候都是异步的，要用 await 等待执行完成
+     */
+    protected abstract executeWithContext(baseContext: BaseContext, route: Route<Ctx>, pathParameters: PathParameters): void | Promise<void>;
+    /**
+     * response 定义中可引用的数据类型
+     */
+    readonly responseReferences: Record<string, ResponseDataType>;
+    /**
+     * 注册 response 定义中引用的数据类型
+     */
+    registerResponseReference(id: string, type: ResponseDataType): void;
+}
+/**
+ * 默认的 Router 实现
+ */
+export declare class DefaultRouter extends Router {
+    executeWithContext(baseContext: BaseContext, route: Route, pathParameters: PathParameters): Promise<void>;
+}

package/dist/router/router.js

@@ -0,0 +1,97 @@
+import { HTTPError } from '../http/index.js';
+import { getMethodFromCORSPreflight, outputCORSHeaders } from './cors.js';
+import { matchRoutes } from './match.js';
+import { parseQuery, parseJSONBody } from './parameters.js';
+/**
+ * -----------------------------------------
+ * Router 类
+ * -----------------------------------------
+ */
+export class Router {
+    /**
+     * 路由列表
+     */
+    routes = [];
+    register(raw, path, handler) {
+        const rawRoute = typeof raw === 'string' ? { method: raw, path: path, handler: handler } : raw;
+        const route = {
+            describe: '',
+            category: '',
+            ...rawRoute,
+            method: (rawRoute.method ?? (rawRoute.body ? 'POST' : 'GET')).toUpperCase(),
+        };
+        this.routes.push(route);
+    }
+    /**
+     * 响应请求
+     */
+    handle = async (request, response) => {
+        const matched = this.match(request, response);
+        if (matched === null)
+            return;
+        const baseContext = getBaseContext(matched.route, request, response);
+        await this.executeWithContext(baseContext, matched.route, matched.pathParameters);
+    };
+    /**
+     * 匹配路由，成功返回路由对象，失败抛出 HTTPError，提前结束处理返回 null
+     */
+    match(request, response) {
+        const matches = matchRoutes(request.path, this.routes);
+        if (!matches.length)
+            throw new HTTPError(404);
+        const methodFromPreflight = getMethodFromCORSPreflight(request);
+        const isPreflight = methodFromPreflight !== null;
+        const method = methodFromPreflight ?? request.method;
+        const methodMatched = matches.find(match => match.route.method === method);
+        if (!methodMatched)
+            throw new HTTPError(405);
+        const corsOptions = methodMatched.route.cors ?? this.getCORSOptions(request, methodMatched);
+        outputCORSHeaders(response, corsOptions, isPreflight);
+        if (isPreflight) {
+            response.nodeResponse.end('');
+            return null;
+        }
+        return methodMatched;
+    }
+    /**
+     * 为未指定 CORS 配置的 route 提供默认配置
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    getCORSOptions(request, routeMatch) {
+        return false;
+    }
+    /**
+     * response 定义中可引用的数据类型
+     */
+    responseReferences = {};
+    /**
+     * 注册 response 定义中引用的数据类型
+     */
+    registerResponseReference(id, type) {
+        this.responseReferences[id] = type;
+    }
+}
+/**
+ * ------------------------
+ * 默认实现
+ * ------------------------
+ */
+/**
+ * 基础 Context 实现
+ */
+function getBaseContext(route, request, response) {
+    return {
+        request,
+        response,
+        parseQuery: () => parseQuery(route, request),
+        parseBody: async () => parseJSONBody(route, request),
+    };
+}
+/**
+ * 默认的 Router 实现
+ */
+export class DefaultRouter extends Router {
+    async executeWithContext(baseContext, route, pathParameters) {
+        await route.handler(baseContext, pathParameters);
+    }
+}

package/dist/swagger/index.d.ts

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