starlight-server 0.0.1

package/dist/http/request.d.ts

@@ -0,0 +1,25 @@
+/// <reference types="node" resolution-mode="require"/>
+import type http from 'node:http';
+import { type Logger } from '@anjianshi/utils';
+import { RequestBody, type BodyOptions } from './body/index.js';
+import { type NodeRequest } from './types.js';
+/**
+ * 对 Node.js 请求内容的二次封装
+ * - 提供经过整理的请求信息
+ * - 自带 body 解析（实现了 “body 大小限制” 和 “JSON、form-data 等格式的内容解析”）
+ *
+ * Secondary encapsulation of the Node.js Request object
+ * - Organized request information
+ * - Comes with body parsing (implements 'body size limit' and 'content parsing for formats such as JSON and form-data').
+ */
+export declare class Request {
+    readonly nodeRequest: NodeRequest;
+    protected readonly logger: Logger;
+    readonly method: string;
+    readonly host: string;
+    readonly path: string;
+    readonly query: URLSearchParams;
+    readonly headers: http.IncomingHttpHeaders;
+    readonly body: RequestBody;
+    constructor(nodeRequest: NodeRequest, logger: Logger, bodyOptions: BodyOptions);
+}

package/dist/http/request.js

@@ -0,0 +1,40 @@
+import { RequestBody } from './body/index.js';
+import { HTTPError } from './types.js';
+/**
+ * 对 Node.js 请求内容的二次封装
+ * - 提供经过整理的请求信息
+ * - 自带 body 解析（实现了 “body 大小限制” 和 “JSON、form-data 等格式的内容解析”）
+ *
+ * Secondary encapsulation of the Node.js Request object
+ * - Organized request information
+ * - Comes with body parsing (implements 'body size limit' and 'content parsing for formats such as JSON and form-data').
+ */
+export class Request {
+    nodeRequest;
+    logger;
+    method;
+    host;
+    path;
+    query;
+    headers;
+    body;
+    constructor(nodeRequest, logger, bodyOptions) {
+        this.nodeRequest = nodeRequest;
+        this.logger = logger;
+        if (nodeRequest.method === undefined)
+            throw new HTTPError(405);
+        this.method = nodeRequest.method;
+        try {
+            const url = new URL(nodeRequest.url ?? '', `http://${nodeRequest.headers.host ?? ''}`);
+            this.host = url.host;
+            this.path = url.pathname;
+            this.query = url.searchParams;
+        }
+        catch (e) {
+            this.logger.warn('parse url failed', e);
+            throw new HTTPError(400, 'url invalid');
+        }
+        this.headers = nodeRequest.headers;
+        this.body = new RequestBody(nodeRequest, bodyOptions);
+    }
+}

package/dist/http/response.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" resolution-mode="require"/>
+import { type Logger } from '@anjianshi/utils';
+import { type NodeResponse } from './types.js';
+/**
+ * 封装响应内容输出函数
+ * Encapsulate functions for outputting response content.
+ */
+export declare class ResponseUtils {
+    readonly nodeResponse: NodeResponse;
+    readonly logger: Logger;
+    constructor(nodeResponse: NodeResponse, logger: Logger);
+    header(name: string, value: string): void;
+    headers(...items: [string, string][]): void;
+    /**
+     * Output CORS Headers
+     */
+    cors(allowOrigin?: string, allowHeaders?: string): void;
+    text(content: string | Buffer): void;
+    /**
+     * Output JSON
+     */
+    json(data: unknown): void;
+    /**
+     * 原样输出文件内容，并带上文件类型对应的 MIME Type
+     * Output the file content and include the MIME Type corresponding to the file type.
+     */
+    file(content: Buffer | string, path: string): void;
+    /**
+     * Output HTTP Error
+     */
+    error(error: unknown): void;
+}

package/dist/http/response.js

@@ -0,0 +1,66 @@
+import { path2MIMEType } from './mime-types.js';
+import { HTTPError } from './types.js';
+/**
+ * 封装响应内容输出函数
+ * Encapsulate functions for outputting response content.
+ */
+export class ResponseUtils {
+    nodeResponse;
+    logger;
+    constructor(nodeResponse, logger) {
+        this.nodeResponse = nodeResponse;
+        this.logger = logger;
+    }
+    header(name, value) {
+        this.nodeResponse.setHeader(name, value);
+    }
+    headers(...items) {
+        items.forEach(([name, value]) => this.header(name, value));
+    }
+    /**
+     * Output CORS Headers
+     */
+    cors(allowOrigin = '*', allowHeaders = '*') {
+        this.headers(['Access-Control-Allow-Origin', allowOrigin], ['Access-Control-Allow-Headers', allowHeaders]);
+    }
+    text(content) {
+        this.nodeResponse.end(content);
+    }
+    /**
+     * Output JSON
+     */
+    json(data) {
+        try {
+            const json = JSON.stringify(data);
+            this.header('Content-Type', 'application/json; charset=UTF-8');
+            this.nodeResponse.end(json);
+        }
+        catch (e) {
+            throw new HTTPError(500, 'Invalid JSON Response');
+        }
+    }
+    /**
+     * 原样输出文件内容，并带上文件类型对应的 MIME Type
+     * Output the file content and include the MIME Type corresponding to the file type.
+     */
+    file(content, path) {
+        const mimeType = path2MIMEType(path);
+        if (mimeType !== null)
+            this.header('Content-Type', mimeType);
+        this.nodeResponse.end(content);
+    }
+    /**
+     * Output HTTP Error
+     */
+    error(error) {
+        if (error instanceof HTTPError) {
+            this.nodeResponse.statusCode = error.status; // eslint-disable-line require-atomic-updates
+            this.nodeResponse.end(error.message);
+        }
+        else {
+            this.logger.error(error);
+            this.nodeResponse.statusCode = 500; // eslint-disable-line require-atomic-updates
+            this.nodeResponse.end(new HTTPError(500).message);
+        }
+    }
+}

package/dist/http/server.d.ts

@@ -0,0 +1,31 @@
+import { type Logger } from '@anjianshi/utils';
+import { type BodyOptions } from './body/index.js';
+import { Request } from './request.js';
+import { ResponseUtils } from './response.js';
+export type RequestHandler = (request: Request, response: ResponseUtils) => unknown;
+/**
+ * 二次封装 Node.js HTTP Server，实现了更完善的 request 和 response 处理
+ * Secondary encapsulation of the Node.js HTTP Server, with more complete request and response handling.
+ *
+ * 功能点：
+ * - 经过整理的 request 信息，且自带 body 解析
+ * - 快速输出指定格式的响应内容
+ * - 自带异常处理
+ *   - 任意处抛出 HTTPError，可以指定 HTTP Status 结束请求
+ *   - 抛出其他 Error，则以 Status 500 结束请求
+ *
+ * Features:
+ * - Organized request information, and built-in body parsing
+ * - Quickly output response content in a specified format
+ * - Built-in exception handling
+ *   - Throw HTTPError anywhere, and end the request with the specified HTTP Status
+ *   - If another Error is thrown, end the request with Status 500
+ *
+ * Usage：
+ * startHTTPServer(handler, options)
+ */
+export declare function startHTTPServer(options: BodyOptions & {
+    handler?: RequestHandler;
+    logger: Logger;
+    port: number;
+}): void;

package/dist/http/server.js

@@ -0,0 +1,52 @@
+import http from 'node:http';
+import { LogLevel } from '@anjianshi/utils';
+import { Request } from './request.js';
+import { ResponseUtils } from './response.js';
+/**
+ * 二次封装 Node.js HTTP Server，实现了更完善的 request 和 response 处理
+ * Secondary encapsulation of the Node.js HTTP Server, with more complete request and response handling.
+ *
+ * 功能点：
+ * - 经过整理的 request 信息，且自带 body 解析
+ * - 快速输出指定格式的响应内容
+ * - 自带异常处理
+ *   - 任意处抛出 HTTPError，可以指定 HTTP Status 结束请求
+ *   - 抛出其他 Error，则以 Status 500 结束请求
+ *
+ * Features:
+ * - Organized request information, and built-in body parsing
+ * - Quickly output response content in a specified format
+ * - Built-in exception handling
+ *   - Throw HTTPError anywhere, and end the request with the specified HTTP Status
+ *   - If another Error is thrown, end the request with Status 500
+ *
+ * Usage：
+ * startHTTPServer(handler, options)
+ */
+export function startHTTPServer(options) {
+    const { handler = placeholderHandler, logger, port, ...bodyOptions } = options;
+    async function handleRequest(nodeRequest, nodeResponse) {
+        const logStart = Date.now();
+        const logMethod = nodeRequest.method ?? 'UNKNOWN';
+        const logUrl = nodeRequest.url ?? '';
+        logger.info('<--', logMethod, logUrl);
+        const response = new ResponseUtils(nodeResponse, logger);
+        try {
+            const request = new Request(nodeRequest, logger, bodyOptions);
+            await handler(request, response);
+        }
+        catch (error) {
+            response.error(error);
+        }
+        const logUsage = Date.now() - logStart;
+        const logStatus = nodeResponse.statusCode;
+        const logLevel = logStatus >= 400 ? LogLevel.Warning : LogLevel.Info;
+        logger.log(logLevel, ['-->', logMethod, logUrl, logStatus, `${logUsage}ms`]);
+    }
+    const server = http.createServer(handleRequest);
+    logger.info('Listening', port);
+    server.listen(port);
+}
+function placeholderHandler(request, response) {
+    response.json({ message: 'Hello World, from starlight.' });
+}

package/dist/http/types.d.ts

@@ -0,0 +1,26 @@
+/// <reference types="node" resolution-mode="require"/>
+/**
+ * 重新定义 HTTP 请求相关类型
+ * Redefine HTTP request-related types.
+ */
+import type http from 'node:http';
+/**
+ * Node.js 原生的请求对象
+ * Node.js native request object
+ */
+export type NodeRequest = http.IncomingMessage;
+/**
+ * Node.js 原生的响应对象
+ * Node.js native response object
+ */
+export type NodeResponse = http.ServerResponse & {
+    req: http.IncomingMessage;
+};
+/**
+ * 带有 HTTP Status 的错误对象
+ * Error object with HTTP Status
+ */
+export declare class HTTPError extends Error {
+    readonly status: number;
+    constructor(status: number, message?: string);
+}

package/dist/http/types.js

@@ -0,0 +1,12 @@
+import { HTTPStatusMap } from './http-status.js';
+/**
+ * 带有 HTTP Status 的错误对象
+ * Error object with HTTP Status
+ */
+export class HTTPError extends Error {
+    status;
+    constructor(status, message) {
+        super(message ?? HTTPStatusMap.get(status) ?? status.toString());
+        this.status = status;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './http/index.js';
+export * from './router/index.js';
+export * from './logging.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './http/index.js';
+export * from './router/index.js';
+export * from './logging.js';
+// export * from './swagger/index.js'

package/dist/logging.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 实现日志记录
+ */
+import { Logger } from '@anjianshi/utils';
+import { type FileHandlerOptions } from '@anjianshi/utils/env-node/logging.js';
+export type { FileHandlerOptions };
+export interface LoggingOptions {
+    /**
+     * 指定日志等级（debug info warn err）
+     * Specify log level.
+     */
+    level?: string;
+    /**
+     * 文件日志参数
+     * File log options
+     */
+    file?: Partial<FileHandlerOptions>;
+    /**
+     * 是否把 debug 库的日志引入进来；可通过字符串指定匹配规则
+     * Whether to import logs from 'debug' library; can specify matching rules through strings
+     */
+    debugLib?: boolean | string;
+}
+export declare function getLogger(options?: LoggingOptions): Logger;

package/dist/logging.js

@@ -0,0 +1,30 @@
+/**
+ * 实现日志记录
+ */
+import { truthy, Logger, LogLevel, adaptDebugLib } from '@anjianshi/utils';
+import { ConsoleHandler, FileHandler, } from '@anjianshi/utils/env-node/logging.js';
+import debug from 'debug';
+const levelMap = {
+    debug: LogLevel.Debug,
+    info: LogLevel.Info,
+    warn: LogLevel.Warning,
+    warning: LogLevel.Warning,
+    err: LogLevel.Error,
+    error: LogLevel.Error,
+};
+export function getLogger(options = {}) {
+    const logger = new Logger();
+    logger.addHandler(new ConsoleHandler());
+    if (options.level !== undefined) {
+        const level = levelMap[options.level.toLowerCase()];
+        if (level !== undefined)
+            logger.setLevel(level);
+    }
+    if (options.file) {
+        logger.addHandler(new FileHandler(options.file));
+    }
+    if (truthy(options.debugLib)) {
+        void adaptDebugLib(debug, options.debugLib === true ? '*' : options.debugLib, logger);
+    }
+    return logger;
+}

package/dist/router/cors.d.ts

@@ -0,0 +1,24 @@
+import { type Request, type ResponseUtils } from '../http/index.js';
+/**
+ * CORS 配置
+ *
+ * - false: 不处理跨域
+ * - true: 支持且不设限（等同于 { allowOrigin: '*', allowHeaders: '*', exposeHeaders: '*' }）
+ * - { allowOrigin, allowHeaders, exposeHeaders }: 手动配置
+ *
+ * allowHeaders 仅对 Preflight 请求有效
+ * exposeHeaders 仅对非 Preflight 请求有效
+ */
+export type CORSOptions = boolean | {
+    allowOrigin?: string;
+    allowHeaders?: string;
+    exposeHeaders?: string;
+};
+/**
+ * 若当前请求是 CORS Preflight 请求，返回实际请求的 method，否则返回 null
+ */
+export declare function getMethodFromCORSPreflight(request: Request): string | null;
+/**
+ * 输出 CORS 相关 headers
+ */
+export declare function outputCORSHeaders(response: ResponseUtils, cors: CORSOptions, isPreflight: boolean): void;

package/dist/router/cors.js

@@ -0,0 +1,35 @@
+/**
+ * 若当前请求是 CORS Preflight 请求，返回实际请求的 method，否则返回 null
+ */
+export function getMethodFromCORSPreflight(request) {
+    if (request.method === 'OPTIONS' &&
+        request.headers['Access-Control-Request-Methods'] !== undefined) {
+        const rawMethod = request.headers['Access-Control-Request-Methods'];
+        return Array.isArray(rawMethod) ? rawMethod[0] : rawMethod;
+    }
+    return null;
+}
+/**
+ * 输出 CORS 相关 headers
+ */
+export function outputCORSHeaders(response, cors, isPreflight) {
+    if (cors === true) {
+        response.headers(['Access-Control-Allow-Origin', '*']);
+        if (isPreflight)
+            response.headers(['Access-Control-Allow-Headers', '*']);
+        else
+            response.headers(['Access-Control-Expose-Headers', '*']);
+    }
+    else if (cors !== false) {
+        if (cors.allowOrigin !== undefined)
+            response.header('Access-Control-Allow-Origin', cors.allowOrigin);
+        if (isPreflight && cors.allowHeaders !== undefined)
+            response.header('Access-Control-Allow-Headers', cors.allowHeaders);
+        if (!isPreflight && cors.exposeHeaders !== undefined)
+            response.header('Access-Control-Expose-Headers', cors.exposeHeaders);
+    }
+    else {
+        // 若指定为“不处理跨域”，则不输出 headers，浏览器会默认服务端不允许跨域请求
+        // （后续 route handler 仍有机会自行设置 CORS headers）
+    }
+}

package/dist/router/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 实现路由注册
+ * Implement route registration
+ *
+ * Usage:
+ * const router = new DefaultRouter()
+ * router.register('GET', '/hello/:name', async ({ request, response }: { request: Request, response: ResponseUtils }, params: { name: string }) => {
+ *   response.json({ hello: params.name })
+ * })
+ * startHTTPServer({
+ *   handler: router.handle
+ *   ...
+ * })
+ *
+ * Usage With Custom Context:
+ * interface MyContext extends BaseContext {
+ *   foo: () => void
+ * }
+ * class MyRouter extends BaseRouter<MyContext> {
+ *   executeWithContext(baseContext: BaseContext, route: Route<MyContext>, params: PathParamaters) {
+ *     function foo() { console.log('bar') }
+ *     const context = { ...baseContext, foo }
+ *     route.handle(context)
+ *   }
+ * }
+ * const router = new MyRouter()
+ * router.register('GET', '/foobar', async ({ request, response, foo }) => {
+ *   foo()
+ *   response.json({})
+ * })
+ * startHTTPServer({
+ *   handler: router.handle
+ *   ...
+ * })
+ */
+export * from './router.js';
+export { type PathParameters } from './match.js';
+export type { BasicDataType, Parameter, ParameterDataType } from './parameters.js';

package/dist/router/index.js

@@ -0,0 +1,36 @@
+/**
+ * 实现路由注册
+ * Implement route registration
+ *
+ * Usage:
+ * const router = new DefaultRouter()
+ * router.register('GET', '/hello/:name', async ({ request, response }: { request: Request, response: ResponseUtils }, params: { name: string }) => {
+ *   response.json({ hello: params.name })
+ * })
+ * startHTTPServer({
+ *   handler: router.handle
+ *   ...
+ * })
+ *
+ * Usage With Custom Context:
+ * interface MyContext extends BaseContext {
+ *   foo: () => void
+ * }
+ * class MyRouter extends BaseRouter<MyContext> {
+ *   executeWithContext(baseContext: BaseContext, route: Route<MyContext>, params: PathParamaters) {
+ *     function foo() { console.log('bar') }
+ *     const context = { ...baseContext, foo }
+ *     route.handle(context)
+ *   }
+ * }
+ * const router = new MyRouter()
+ * router.register('GET', '/foobar', async ({ request, response, foo }) => {
+ *   foo()
+ *   response.json({})
+ * })
+ * startHTTPServer({
+ *   handler: router.handle
+ *   ...
+ * })
+ */
+export * from './router.js';

package/dist/router/match.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 标准化路径
+ * 标准化后，相同的两个路径一定也是相同的字符串（例如 /Abc/Def 和 abc/def/ 都会变成 abc/def）。
+ *
+ * - 移除首尾和重复的 '/'，完成后有 path 有这几种可能的格式： ''、'abc'、'abc/def'
+ * - 统一改为小写
+ */
+export declare function normalizePath(path: string): string;
+/**
+ * 返回匹配的路由及匹配上的路径参数
+ */
+export declare function matchRoutes<R extends BasicRoute>(requestPath: string, routes: R[]): RouteMatch<R>[];
+export type BasicRoute = {
+    path: string;
+};
+export interface RouteMatch<R> {
+    route: R;
+    pathParameters: PathParameters;
+}
+export type PathParameters = {
+    [name: string]: string | undefined;
+    '*'?: string;
+};