@tyno/tyno 2.1.3

package/src/response/sse.ts

@@ -0,0 +1,54 @@
+type WaitResolver = (value: { done: boolean; value?: string }) => void;
+
+export class SSEStream {
+    private _queue: string[] = [];
+    private _waitResolver: WaitResolver | null = null;
+    private _ended = false;
+    private _error: Error | null = null;
+
+    send(data: unknown): void {
+        if (this._ended) return;
+        const payload = typeof data === 'string' ? data : JSON.stringify(data);
+        if (this._waitResolver) {
+            this._waitResolver({ done: false, value: payload });
+            this._waitResolver = null;
+        } else {
+            this._queue.push(payload);
+        }
+    }
+
+    end(): void {
+        if (this._ended) return;
+        this._ended = true;
+        if (this._waitResolver) {
+            this._waitResolver({ done: true });
+            this._waitResolver = null;
+        }
+    }
+
+    error(err: Error): void {
+        this._error = err;
+        this.end();
+    }
+
+    [Symbol.asyncIterator](): AsyncIterator<string> {
+        const self = this;
+        return {
+            async next(): Promise<IteratorResult<string>> {
+                if (self._ended && self._queue.length === 0) {
+                    return { done: true, value: undefined as unknown as string };
+                }
+                if (self._queue.length > 0) {
+                    return { done: false, value: self._queue.shift()! };
+                }
+                return new Promise<IteratorResult<string>>((resolve) => {
+                    self._waitResolver = (val) => {
+                        resolve(val.done
+                            ? { done: true, value: undefined as unknown as string }
+                            : { done: false, value: val.value! });
+                    };
+                });
+            }
+        };
+    }
+}

package/src/response.ts

@@ -0,0 +1,177 @@
+import { lookupMime } from './mime.ts';
+import { requestStore } from './context.ts';
+import type { CookieOptions, Headers, ResponseBody } from './types.ts';
+
+const PENDING_KEY = '_tyno_response_pending';
+
+function getPending(): { headers: Record<string, string | number | string[]>; cookies: string[] } {
+    const req = requestStore.getStore();
+    if (!req) throw new Error('No active request context');
+    const data = (req as unknown as Record<string, unknown>);
+    if (!data[PENDING_KEY]) {
+        data[PENDING_KEY] = { headers: {}, cookies: [] };
+    }
+    return data[PENDING_KEY] as { headers: Record<string, string | number | string[]>; cookies: string[] };
+}
+
+/**
+ * 可构造且可链式修改的响应对象，支持流式 body (Stream / AsyncIterator) 与 Cookie。
+ * 内部所有 Content-Type 键统一使用 'Content-Type'（Pascal-Case）。
+ */
+export class Response {
+    status: number;
+    headers: Headers;
+    body: ResponseBody;
+    /** Set-Cookie 值列表 */
+    _cookies: string[];
+
+    constructor(status: number = 200, headers: Headers = {}, body: ResponseBody = null) {
+        this.status = status;
+        this.headers = { ...headers };
+        this.body = body;
+        this._cookies = [];
+    }
+
+    // ==================== 链式修改 ====================
+
+    /** 设置响应头（链式） */
+    set(name: string, value: string | number | string[]): this {
+        this.headers[name] = value;
+        return this;
+    }
+
+    /** set 的别名 */
+    setHeader(name: string, value: string | number | string[]): this {
+        return this.set(name, value);
+    }
+
+    /** 获取响应头（大小写不敏感） */
+    get(name: string): string | undefined {
+        if (name in this.headers) return this.headers[name] as string;
+        const lower = name.toLowerCase();
+        for (const k in this.headers) {
+            if (k.toLowerCase() === lower) return this.headers[k] as string;
+        }
+        return undefined;
+    }
+
+    /** 设置 Content-Type（支持简写如 'json'、'html'），统一使用 'Content-Type' 键 */
+    type(type: string): this {
+        this.headers['Content-Type'] = type.includes('/') ? type : lookupMime(type);
+        return this;
+    }
+
+    /** 设置状态码（链式） */
+    setStatus(status: number): this {
+        this.status = status;
+        return this;
+    }
+
+    // ==================== Cookie ====================
+
+    /** 设置 Cookie，值自动 encodeURIComponent */
+    setCookie(name: string, value: string, options: CookieOptions = {}): this {
+        const parts = [`${name}=${encodeURIComponent(value)}`];
+        if (options.maxAge != null) parts.push(`Max-Age=${options.maxAge}`);
+        if (options.expires) {
+            const exp = options.expires instanceof Date ? options.expires.toUTCString() : options.expires;
+            parts.push(`Expires=${exp}`);
+        }
+        if (options.path) parts.push(`Path=${options.path}`);
+        if (options.domain) parts.push(`Domain=${options.domain}`);
+        if (options.secure) parts.push('Secure');
+        if (options.httpOnly) parts.push('HttpOnly');
+        if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);
+        this._cookies.push(parts.join('; '));
+        return this;
+    }
+
+    /** 清除 Cookie（设置立即过期） */
+    clearCookie(name: string, options: CookieOptions = {}): this {
+        return this.setCookie(name, '', { ...options, maxAge: 0, expires: new Date(0) });
+    }
+
+    // ==================== 便利方法 ====================
+
+    /** 附加为文件下载 */
+    attachment(filename?: string): this {
+        this.headers['Content-Disposition'] = filename
+            ? `attachment; filename="${filename}"`
+            : 'attachment';
+        return this;
+    }
+
+    // ==================== 静态工厂 ====================
+
+    /** 快速创建 JSON 响应 */
+    static json(data: unknown, status: number = 200): Response {
+        return new Response(
+            status,
+            { 'Content-Type': 'application/json; charset=utf-8' },
+            JSON.stringify(data)
+        );
+    }
+
+    /** 快速创建纯文本响应 */
+    static text(data: string | Buffer, status: number = 200): Response {
+        const body = typeof data === 'string' ? data : String(data);
+        return new Response(
+            status,
+            { 'Content-Type': 'text/plain; charset=utf-8' },
+            body
+        );
+    }
+
+    /** 快速创建无内容响应 */
+    static empty(status: number = 204): Response {
+        return new Response(status, {}, null);
+    }
+
+    /** 快速创建重定向 */
+    static redirect(url: string, status: number = 302): Response {
+        return new Response(status, { Location: url }, null);
+    }
+
+    /** 快速创建图片响应 */
+    static image(data: Buffer | string, type: string = 'png', status: number = 200): Response {
+        const mime = type.includes('/') ? type : (lookupMime(type) || `image/${type}`);
+        return new Response(status, { 'Content-Type': mime }, data);
+    }
+
+    // ==================== 静态门面方法（预设 header / cookie） ====================
+
+    /** 预设响应头，最终响应已设置同名 header 时跳过 */
+    static header(name: string, value: string | number | string[]): void {
+        getPending().headers[name] = value;
+    }
+
+    /** 预设 Cookie，始终追加到最终响应 */
+    static setCookie(name: string, value: string, options: CookieOptions = {}): void {
+        const parts = [`${name}=${encodeURIComponent(value)}`];
+        if (options.maxAge != null) parts.push(`Max-Age=${options.maxAge}`);
+        if (options.expires) {
+            const exp = options.expires instanceof Date ? options.expires.toUTCString() : options.expires;
+            parts.push(`Expires=${exp}`);
+        }
+        if (options.path) parts.push(`Path=${options.path}`);
+        if (options.domain) parts.push(`Domain=${options.domain}`);
+        if (options.secure) parts.push('Secure');
+        if (options.httpOnly) parts.push('HttpOnly');
+        if (options.sameSite) parts.push(`SameSite=${options.sameSite}`);
+        getPending().cookies.push(parts.join('; '));
+    }
+
+    /** @internal 获取 pending 数据，供 mergeResponseFacade 读取 */
+    static _getPending(): { headers: Record<string, string | number | string[]>; cookies: string[] } | null {
+        const req = requestStore.getStore();
+        if (!req) return null;
+        const data = (req as unknown as Record<string, unknown>);
+        const key = '_tyno_response_pending';
+        const pending = data[key] as { headers: Record<string, string | number | string[]>; cookies: string[] } | undefined;
+        if (pending && (Object.keys(pending.headers).length > 0 || pending.cookies.length > 0)) {
+            delete data[key];
+            return pending;
+        }
+        return null;
+    }
+}

package/src/router/index.ts

@@ -0,0 +1,290 @@
+import { compose } from '../compose.ts';
+import { Response } from '../response.ts';
+import TrieNode, { type ParamNode } from './node.ts';
+import { parsePath, type PathSegment } from './parse-path.ts';
+import type { AnyMiddleware, TynoRequest, NextFunction } from '../types.ts';
+
+interface MatchResult {
+    params: Record<string, string>;
+    handlers: AnyMiddleware[];
+}
+
+export interface RouterOptions {
+    prefix?: string;
+}
+
+export class Router {
+    prefix: string;
+    middlewares: AnyMiddleware[] = [];
+    root: TrieNode = new TrieNode();
+    private _fallbackHandler: AnyMiddleware | null = null;
+
+    constructor(opts: RouterOptions = {}) {
+        this.prefix = opts.prefix || '';
+    }
+
+    all(path: string, ...handlers: AnyMiddleware[]): this {
+        this._addRoute('*', path, handlers);
+        return this;
+    }
+    get(path: string, ...handlers: AnyMiddleware[]): this {
+        this._addRoute('get', path, handlers);
+        return this;
+    }
+    head(path: string, ...handlers: AnyMiddleware[]): this {
+        this._addRoute('head', path, handlers);
+        return this;
+    }
+    post(path: string, ...handlers: AnyMiddleware[]): this {
+        this._addRoute('post', path, handlers);
+        return this;
+    }
+    put(path: string, ...handlers: AnyMiddleware[]): this {
+        this._addRoute('put', path, handlers);
+        return this;
+    }
+    delete(path: string, ...handlers: AnyMiddleware[]): this {
+        this._addRoute('delete', path, handlers);
+        return this;
+    }
+    patch(path: string, ...handlers: AnyMiddleware[]): this {
+        this._addRoute('patch', path, handlers);
+        return this;
+    }
+
+    /**
+     * 注册路由级中间件。支持单个函数或函数数组，按注册顺序依次执行。
+     * `middleware()` 是同名别名。
+     *
+     * @example
+     * router.use(logger);
+     * router.use([auth, adminCheck]);
+     */
+    use(fn: AnyMiddleware | AnyMiddleware[]): this {
+        if (Array.isArray(fn)) {
+            for (const f of fn) this.middlewares.push(f);
+        } else {
+            this.middlewares.push(fn);
+        }
+        return this;
+    }
+
+    /** `use()` 的别名 */
+    middleware(fn: AnyMiddleware | AnyMiddleware[]): this {
+        return this.use(fn);
+    }
+
+    /**
+     * 路由分组：在指定前缀下批量注册路由（直接合并 trie，前缀加入段）。
+     *
+     * @example
+     * router.group('/admin', (r) => {
+     *     r.get('/dashboard', () => 'Admin Dashboard');
+     *     r.get('/users', () => 'User List');
+     * });
+     */
+    group(prefix: string, fn: (router: Router) => void): this {
+        const sub = new Router({ prefix: '' });
+        fn(sub);
+        // 合并子路由中间件
+        for (const mw of sub.middlewares) {
+            this.middlewares.push(mw);
+        }
+        // 解析前缀为段
+        const prefixSegments = prefix.split('/').filter(Boolean);
+        // 合并子路由 trie，前缀段作为父节点
+        for (const [seg, child] of sub.root.children) {
+            const fullSegments = [...prefixSegments, seg];
+            this._mergeTrieWithPrefix(child, fullSegments);
+        }
+        // 合并通配符
+        if (sub.root.wildcardNode) {
+            this._mergeTrieWithPrefix(sub.root.wildcardNode, [...prefixSegments, '*']);
+        }
+        // 合并根节点 handlers（无路径的请求，如仅 /admin）
+        for (const [method, handlers] of sub.root.handlers) {
+            // 在 prefix 段的叶子节点注册
+            this._addRouteAtPrefix(prefixSegments, method, handlers);
+        }
+        return this;
+    }
+
+    /** 在指定路径段末尾注册 route */
+    private _addRouteAtPrefix(segments: string[], method: string, handlers: AnyMiddleware[]): void {
+        let node = this.root;
+        for (const seg of segments) {
+            if (!node.children.has(seg)) {
+                node.children.set(seg, new TrieNode());
+            }
+            node = node.children.get(seg)!;
+        }
+        node.handlers.set(method, handlers);
+    }
+
+    /** 将子 trie 节点递归合并到当前 trie，前缀段已解析 */
+    private _mergeTrieWithPrefix(src: TrieNode, prefixSegments: string[]): void {
+        // 合并 handlers
+        for (const [method, handlers] of src.handlers) {
+            this._addRouteAtPrefix(prefixSegments, method, handlers);
+        }
+        // 合并静态子节点
+        for (const [seg, child] of src.children) {
+            this._mergeTrieWithPrefix(child, [...prefixSegments, seg]);
+        }
+        // 合并参数节点
+        if (src.paramNode) {
+            let node = this.root;
+            for (const seg of prefixSegments) {
+                if (!node.children.has(seg)) node.children.set(seg, new TrieNode());
+                node = node.children.get(seg)!;
+            }
+            if (node.paramNode) {
+                if (node.paramNode.name !== src.paramNode.name) {
+                    throw new Error(`Param conflict: ${src.paramNode.name} vs ${node.paramNode.name}`);
+                }
+                this._mergeTrieWithPrefix(src.paramNode.node, []);  // recurse into param
+            } else {
+                node.paramNode = {
+                    name: src.paramNode.name,
+                    pattern: src.paramNode.pattern,
+                    regex: src.paramNode.regex,
+                    node: new TrieNode()
+                };
+                // copy handlers from param node
+                for (const [m, h] of src.paramNode.node.handlers) {
+                    node.paramNode.node.handlers.set(m, h);
+                }
+                node.paramNode.node.children = new Map(src.paramNode.node.children);
+                if (src.paramNode.node.wildcardNode) {
+                    node.paramNode.node.wildcardNode = new TrieNode();
+                    for (const [m, h] of src.paramNode.node.wildcardNode.handlers) {
+                        node.paramNode.node.wildcardNode.handlers.set(m, h);
+                    }
+                }
+            }
+        }
+        // 合并通配符节点
+        if (src.wildcardNode) {
+            let node = this.root;
+            for (const seg of prefixSegments) {
+                if (!node.children.has(seg)) node.children.set(seg, new TrieNode());
+                node = node.children.get(seg)!;
+            }
+            if (!node.wildcardNode) node.wildcardNode = new TrieNode();
+            for (const [m, h] of src.wildcardNode.handlers) {
+                node.wildcardNode.handlers.set(m, h);
+            }
+        }
+    }
+
+    /**
+     * 设置 fallback 处理器：当所有路由都不匹配时调用。
+     *
+     * @example
+     * router.fallback((req) => Response.json({ error: 'Not Found' }, 404));
+     */
+    fallback(handler: AnyMiddleware): this {
+        this._fallbackHandler = handler;
+        return this;
+    }
+
+    routes(): AnyMiddleware {
+        const self = this;
+        return async (req: TynoRequest, next?: NextFunction): Promise<unknown> => {
+            let pathToMatch: string = req.path;
+            if (self.prefix) {
+                if (!pathToMatch.startsWith(self.prefix)) {
+                    if (next) return next();
+                    return new Response(404, {}, 'Not Found');
+                }
+                pathToMatch = pathToMatch.slice(self.prefix.length) || '/';
+            }
+
+            const matchResult = self._match(pathToMatch, req.method.toLowerCase());
+            if (matchResult) {
+                req.params = matchResult.params;
+                const stack = [...self.middlewares, ...matchResult.handlers];
+                return compose(req, stack);
+            }
+
+            // 未匹配：优先 fallback，其次 next，最后 404
+            if (self._fallbackHandler) {
+                return (self._fallbackHandler as (req: TynoRequest) => unknown)(req);
+            }
+            if (next) return next();
+            return new Response(404, {}, 'Not Found');
+        };
+    }
+
+    private _addRoute(method: string, path: string, handlers: AnyMiddleware[]): void {
+        const segments = parsePath(path);
+        let node = this.root;
+        for (const seg of segments) {
+            if (typeof seg === 'string') {
+                if (!node.children.has(seg)) node.children.set(seg, new TrieNode());
+                node = node.children.get(seg)!;
+            } else if (seg.type === 'param') {
+                if (!node.paramNode) {
+                    const paramNode: ParamNode = {
+                        name: seg.name,
+                        pattern: seg.pattern,
+                        regex: seg.pattern ? new RegExp('^' + seg.pattern + '$') : null,
+                        node: new TrieNode()
+                    };
+                    node.paramNode = paramNode;
+                } else {
+                    if (node.paramNode.name !== seg.name)
+                        throw new Error(`Param conflict: cannot use ${seg.name}, already defined as ${node.paramNode.name}`);
+                    if (node.paramNode.pattern !== seg.pattern)
+                        throw new Error(`Pattern conflict for param ${seg.name}: different regex`);
+                }
+                node = node.paramNode.node;
+            } else if (seg.type === 'wildcard') {
+                if (!node.wildcardNode) node.wildcardNode = new TrieNode();
+                node = node.wildcardNode;
+                break;
+            }
+        }
+        const methodKey = method.toLowerCase();
+        node.handlers.set(methodKey, handlers);
+    }
+
+    private _match(path: string, method: string): MatchResult | null {
+        const segments = path.split('/').filter(Boolean);
+        const result = this._matchNode(this.root, segments, 0, {}, method);
+        return result ? { params: result.params, handlers: result.handlers } : null;
+    }
+
+    private _matchNode(node: TrieNode, segments: string[], idx: number, params: Record<string, string>, method: string): MatchResult | null {
+        if (idx === segments.length) return this._getHandlers(node, method, params);
+
+        const current = segments[idx];
+        if (node.children.has(current)) {
+            const match = this._matchNode(node.children.get(current)!, segments, idx + 1, params, method);
+            if (match) return match;
+        }
+        if (node.paramNode) {
+            const { name, regex, node: paramNode } = node.paramNode;
+            if (regex) {
+                if (regex.test(current)) {
+                    const match = this._matchNode(paramNode, segments, idx + 1, { ...params, [name]: current }, method);
+                    if (match) return match;
+                }
+            } else {
+                const match = this._matchNode(paramNode, segments, idx + 1, { ...params, [name]: current }, method);
+                if (match) return match;
+            }
+        }
+        if (node.wildcardNode) {
+            const wildValue = segments.slice(idx).join('/');
+            return this._getHandlers(node.wildcardNode, method, { ...params, '*': wildValue });
+        }
+        return null;
+    }
+
+    private _getHandlers(node: TrieNode, method: string, params: Record<string, string>): MatchResult | null {
+        const handlers = node.handlers.get(method) || node.handlers.get('*');
+        if (handlers) return { params, handlers };
+        return null;
+    }
+}

package/src/router/node.ts

@@ -0,0 +1,15 @@
+import type { AnyMiddleware } from '../types.ts';
+
+export interface ParamNode {
+    name: string;
+    pattern: string | null;
+    regex: RegExp | null;
+    node: TrieNode;
+}
+
+export default class TrieNode {
+    children: Map<string, TrieNode> = new Map();
+    paramNode: ParamNode | null = null;
+    wildcardNode: TrieNode | null = null;
+    handlers: Map<string, AnyMiddleware[]> = new Map();
+}

package/src/router/parse-path.ts

@@ -0,0 +1,18 @@
+export type PathSegment = string | { type: 'param'; name: string; pattern: string | null } | { type: 'wildcard' };
+
+export function parsePath(path: string): PathSegment[] {
+    const parts = path.split('/').filter(Boolean);
+    const segments: PathSegment[] = [];
+    for (const part of parts) {
+        if (part === '*') {
+            segments.push({ type: 'wildcard' });
+        } else if (part.startsWith(':')) {
+            const match = part.match(/^:([^()]+)(?:\((.+)\))?$/);
+            if (!match) throw new Error(`Invalid param segment: ${part}`);
+            segments.push({ type: 'param', name: match[1], pattern: match[2] || null });
+        } else {
+            segments.push(part);
+        }
+    }
+    return segments;
+}

package/src/types.ts

@@ -0,0 +1,109 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Response } from './response.ts';
+import type { Request } from './request/index.ts';
+import type { Application } from './application.ts';
+import type { CacheConfig } from './cache/types.ts';
+
+// ==================== Symbol 标记 ====================
+
+/** 标记中间件为错误中间件（优先级高于 fn.length 检测） */
+export const IS_ERROR_MIDDLEWARE: symbol = Symbol.for('tyno.error-middleware');
+
+// ==================== 函数类型 ====================
+
+/** 初始化器：在 listen() 启动服务前自动调用，接收 app 实例 */
+export type InitializerFn = (app: Application) => unknown | Promise<unknown>;
+
+/** next 函数：无参进入下游中间件，传 err 则触发错误中间件 */
+export type NextFunction = (err?: unknown) => Promise<Response>;
+
+/** 中间件请求对象：Request 实例经 Proxy 包裹，支持任意自定义属性 */
+export type TynoRequest = Request & { [key: string]: unknown };
+
+/** 普通中间件：(req, next) => any */
+export type Middleware = (req: TynoRequest, next: NextFunction) => unknown | Promise<unknown>;
+
+/** 终端中间件：(req) => any */
+export type TerminalMiddleware = (req: TynoRequest) => unknown | Promise<unknown>;
+
+/** 错误中间件：(err, req, next) => any */
+export type ErrorMiddleware = (err: unknown, req: TynoRequest, next: NextFunction) => unknown | Promise<unknown>;
+
+/** 所有中间件类型的联合 */
+export type AnyMiddleware = Middleware | TerminalMiddleware | ErrorMiddleware;
+
+// ==================== 数据类型 ====================
+
+/** 响应体类型 */
+export type ResponseBody = string | Buffer | NodeJS.ReadableStream | AsyncIterable<unknown> | null;
+
+/** 响应头类型 */
+export type Headers = Record<string, string | number | string[]>;
+
+/** Cookie 选项 */
+export interface CookieOptions {
+    maxAge?: number;
+    expires?: Date | string;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+
+/** Body 解析选项 */
+export interface BodyOptions {
+    limit?: number | string;
+}
+
+/** Body 解析器配置（传入 Application 构造函数） */
+export interface BodyParserConfig {
+    /** 普通 body（JSON / urlencoded / text）大小限制，默认 '1mb' */
+    limit?: number | string;
+    /** 文件上传总大小限制，默认 '10mb' */
+    uploadLimit?: number | string;
+    /** 文件上传临时目录，默认 os.tmpdir() */
+    uploadDir?: string;
+    /** 是否保留文件扩展名 */
+    keepExtensions?: boolean;
+    /** 文件内存缓冲阈值，超过后写入磁盘（默认 '512kb'） */
+    uploadBufferLimit?: number | string;
+}
+
+/** listen 方法选项 */
+export interface ListenOptions {
+    port: number;
+    tls?: { key: Buffer | string; cert: Buffer | string };
+    gracefulShutdown?: boolean;
+    host?: string;
+}
+
+/** Application 构造选项 */
+export interface ApplicationOptions {
+    /** 调试模式：自动附加开发错误页中间件，显示完整堆栈 */
+    debug?: boolean;
+    /** Body 解析器配置 */
+    body?: BodyParserConfig;
+    /** 缓存配置（驱动类型、TTL、前缀等） */
+    cache?: CacheConfig;
+}
+
+/** inject 测试方法选项 */
+export interface InjectOptions {
+    method?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    body?: string | Buffer | Record<string, unknown>;
+    cookies?: Record<string, string>;
+}
+
+/** inject 测试方法返回值 */
+export interface InjectResult {
+    status: number;
+    headers: Record<string, unknown>;
+    body: string;
+    json<T = unknown>(): T;
+}
+
+/** Application 请求处理回调 */
+export type RequestHandler = (nodeReq: IncomingMessage, nodeRes: ServerResponse) => Promise<void>;