@yumerijs/core 3.0.2 → 3.0.4

package/dist/context.d.ts

@@ -24,6 +24,8 @@ export declare class Context {
     private i18ns;
     private affects;
     private services;
+    private timers;
+    private disposed;
     component: Components;
     renderer?: IRenderer;
     module: any;
@@ -47,6 +49,58 @@ export declare class Context {
      * @param callback 销毁回调
      */
     affect(callback: () => void | Promise<void>): void;
+    /**
+     * 注册重复定时器（Node 原生 setInterval 的包装）
+     *
+     * 参数与行为和原生 setInterval 完全一致，额外保证插件卸载后不留副作用：
+     * - 定时器句柄会被 Context 记录，插件卸载（dispose）时统一清理，
+     *   不会留下继续运行、拖住事件循环的“幽灵定时器”
+     * - 卸载后即使还有已经排队的 tick，包装层也会拦截，不再调用插件回调
+     * - 回调中的同步异常与 async 回调的 Promise 拒绝会被捕获并写入日志，
+     *   不会变成 uncaughtException / unhandledRejection 影响整个进程
+     *
+     * @param callback 定时执行的回调
+     * @param ms 间隔毫秒数
+     * @param args 原样透传给回调的额外参数
+     * @returns 定时器句柄，可用 ctx.clearInterval 或原生 clearInterval 取消；
+     *          若 Context 已卸载则返回 undefined（此时不会创建定时器）
+     */
+    setInterval(callback: (...args: any[]) => any, ms?: number, ...args: any[]): NodeJS.Timeout | undefined;
+    /**
+     * 注册一次性定时器（Node 原生 setTimeout 的包装）
+     *
+     * 行为与原生 setTimeout 一致，卸载保证同 setInterval：
+     * 卸载时清理尚未触发的句柄，已排队但尚未执行的回调同样会被拦截。
+     *
+     * @param callback 延时执行的回调
+     * @param ms 延时毫秒数
+     * @param args 原样透传给回调的额外参数
+     * @returns 定时器句柄，可用 ctx.clearTimeout 或原生 clearTimeout 取消；
+     *          若 Context 已卸载则返回 undefined（此时不会创建定时器）
+     */
+    setTimeout(callback: (...args: any[]) => any, ms?: number, ...args: any[]): NodeJS.Timeout | undefined;
+    /**
+     * 取消由 setInterval 创建的定时器（Node 原生 clearInterval 的包装）
+     * @param timer 定时器句柄
+     */
+    clearInterval(timer?: NodeJS.Timeout | number | null): void;
+    /**
+     * 取消由 setTimeout 创建的定时器（Node 原生 clearTimeout 的包装）
+     * @param timer 定时器句柄
+     */
+    clearTimeout(timer?: NodeJS.Timeout | number | null): void;
+    /**
+     * 校验回调参数并确认 Context 尚未卸载
+     * @param kind 定时器类型，仅用于日志
+     * @param callback 用户回调
+     */
+    private prepareTimer;
+    /**
+     * 调用插件定时器回调，并捕获同步异常与 async 拒绝
+     * @param callback 用户回调
+     * @param args 透传给回调的参数
+     */
+    private invokeTimerCallback;
     /**
      * 注册路由
      * @param path 路由路径

package/dist/context.js

@@ -1,5 +1,5 @@
-import { Route } from './route.js';
 import path from 'path';
+import { setInterval as nodeSetInterval, clearInterval as nodeClearInterval, setTimeout as nodeSetTimeout, clearTimeout as nodeClearTimeout } from 'timers';
 /**
  * 插件上下文对象
  * 每个插件一个 Context，用于管理插件注册的命令、路由、事件、组件和中间件
@@ -16,6 +16,8 @@ export class Context {
     i18ns = [];
     affects = [];
     services = [];
+    timers = new Set();
+    disposed = false;
     component;
     renderer;
     module;
@@ -51,6 +53,113 @@ export class Context {
             return;
         this.affects.push(callback);
     }
+    /**
+     * 注册重复定时器（Node 原生 setInterval 的包装）
+     *
+     * 参数与行为和原生 setInterval 完全一致，额外保证插件卸载后不留副作用：
+     * - 定时器句柄会被 Context 记录，插件卸载（dispose）时统一清理，
+     *   不会留下继续运行、拖住事件循环的“幽灵定时器”
+     * - 卸载后即使还有已经排队的 tick，包装层也会拦截，不再调用插件回调
+     * - 回调中的同步异常与 async 回调的 Promise 拒绝会被捕获并写入日志，
+     *   不会变成 uncaughtException / unhandledRejection 影响整个进程
+     *
+     * @param callback 定时执行的回调
+     * @param ms 间隔毫秒数
+     * @param args 原样透传给回调的额外参数
+     * @returns 定时器句柄，可用 ctx.clearInterval 或原生 clearInterval 取消；
+     *          若 Context 已卸载则返回 undefined（此时不会创建定时器）
+     */
+    setInterval(callback, ms, ...args) {
+        if (!this.prepareTimer('interval', callback))
+            return undefined;
+        const timer = nodeSetInterval(() => {
+            // 兜底：卸载后可能仍有已经排队的 tick，直接丢弃
+            if (this.disposed)
+                return;
+            this.invokeTimerCallback(callback, args);
+        }, ms);
+        this.timers.add(timer);
+        return timer;
+    }
+    /**
+     * 注册一次性定时器（Node 原生 setTimeout 的包装）
+     *
+     * 行为与原生 setTimeout 一致，卸载保证同 setInterval：
+     * 卸载时清理尚未触发的句柄，已排队但尚未执行的回调同样会被拦截。
+     *
+     * @param callback 延时执行的回调
+     * @param ms 延时毫秒数
+     * @param args 原样透传给回调的额外参数
+     * @returns 定时器句柄，可用 ctx.clearTimeout 或原生 clearTimeout 取消；
+     *          若 Context 已卸载则返回 undefined（此时不会创建定时器）
+     */
+    setTimeout(callback, ms, ...args) {
+        if (!this.prepareTimer('timeout', callback))
+            return undefined;
+        const timer = nodeSetTimeout(() => {
+            // 触发过的句柄不必再被追踪，先摘掉再执行回调
+            this.timers.delete(timer);
+            if (this.disposed)
+                return;
+            this.invokeTimerCallback(callback, args);
+        }, ms);
+        this.timers.add(timer);
+        return timer;
+    }
+    /**
+     * 取消由 setInterval 创建的定时器（Node 原生 clearInterval 的包装）
+     * @param timer 定时器句柄
+     */
+    clearInterval(timer) {
+        if (timer === undefined || timer === null)
+            return;
+        this.timers.delete(timer);
+        nodeClearInterval(timer);
+    }
+    /**
+     * 取消由 setTimeout 创建的定时器（Node 原生 clearTimeout 的包装）
+     * @param timer 定时器句柄
+     */
+    clearTimeout(timer) {
+        if (timer === undefined || timer === null)
+            return;
+        this.timers.delete(timer);
+        nodeClearTimeout(timer);
+    }
+    /**
+     * 校验回调参数并确认 Context 尚未卸载
+     * @param kind 定时器类型，仅用于日志
+     * @param callback 用户回调
+     */
+    prepareTimer(kind, callback) {
+        if (typeof callback !== 'function') {
+            throw new TypeError('The "callback" argument must be of type function.');
+        }
+        if (this.disposed) {
+            this.core.logger.warn(`Plugin "${this.pluginname}" attempt to create a ${kind} after its context was disposed, ignored.`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * 调用插件定时器回调，并捕获同步异常与 async 拒绝
+     * @param callback 用户回调
+     * @param args 透传给回调的参数
+     */
+    invokeTimerCallback(callback, args) {
+        try {
+            const result = callback(...args);
+            // 兼容 async 回调，避免未处理的 Promise 拒绝
+            if (result && typeof result.then === 'function') {
+                Promise.resolve(result).catch((error) => {
+                    this.core.logger.error(`Unhandled rejection in timer callback of plugin "${this.pluginname}":`, error);
+                });
+            }
+        }
+        catch (error) {
+            this.core.logger.error(`Unhandled error in timer callback of plugin "${this.pluginname}":`, error);
+        }
+    }
     /**
      * 注册路由
      * @param path 路由路径
@@ -63,8 +172,9 @@ export class Context {
             ? 'root'
             : path.posix.join(this.childpath, routepath);
         if (this.core.routes[realpath]) {
-            this.core.logger.warn(`Plugin "${this.pluginname}" attempt to register route "${path}", but it has already been registered.`);
-            return new Route(realpath, this);
+            // Reuse the registered route so the same path can be split across
+            // multiple declarations, e.g. one GET handler and one POST handler.
+            return this.core.routes[realpath];
         }
         this.routes.push(realpath);
         return this.core.route(realpath, this);
@@ -238,6 +348,11 @@ export class Context {
      * 卸载插件时清理注册的所有资源
      */
     async dispose() {
+        // 先把自己标记为已卸载并停掉所有定时器（Node 里 clearTimeout/clearInterval 可互换）：
+        // 这样后续拆卸过程中即使有已排队的 tick 也不会再触发插件回调
+        this.disposed = true;
+        this.timers.forEach((timer) => nodeClearTimeout(timer));
+        this.timers.clear();
         // 删除组件
         this.components.forEach((name) => delete this.core.components[name]);
         // 删除服务

package/dist/core.js

@@ -228,6 +228,10 @@ export class Core {
             const route = this.routes[routePath];
             const result = route.match(pathname, session.client?.headers?.host);
             if (result) {
+                const method = session.client?.req?.method ?? 'GET';
+                if (!route.hasHandler(method)) {
+                    continue;
+                }
                 try {
                     this.emit('request:start', {
                         path: pathname,
@@ -254,7 +258,7 @@ export class Core {
                         }
                         else {
                             const start = Date.now();
-                            await route.executeHandler(session, queryParams, result.pathParams, result.hostParams);
+                            await route.executeHandler(session, queryParams, result.pathParams, result.hostParams, method);
                             this.emit('route:end', {
                                 path: pathname,
                                 route: routePath,

package/dist/route.d.ts

@@ -8,6 +8,7 @@ import { Middleware } from './middleware.js';
 import { WebSocketServer } from 'ws';
 import { Context } from './context.js';
 export type RouteHandler = (session: Session, queryParams: URLSearchParams, ...pathParams: string[]) => Promise<void> | void;
+type RouteMethod = string | string[];
 /**
  * Route class using segment-based matching (no fragile capture-group-index mapping).
  * Behavior matches the SimpleRouter in the webpage:
@@ -20,7 +21,9 @@ export declare class Route {
     path: string;
     private segments;
     private paramsInfo;
-    private handler;
+    private handlers;
+    private pendingActionMethods;
+    private methodsConfigured;
     middlewares: Middleware[];
     allowedMethods: string[];
     ws: WebSocketServer | null;
@@ -38,6 +41,7 @@ export declare class Route {
      * @returns this
      */
     action(handler: RouteHandler): this;
+    action(method: RouteMethod, handler: RouteHandler): this;
     /**
      * 设置允许的host
      * @param host host列表
@@ -67,7 +71,8 @@ export declare class Route {
      * @param params 查询参数
      * @param pathParams 路由参数
      */
-    executeHandler(session: Session, params: URLSearchParams, pathParams: string[], hostParams: Record<string, string>): Promise<void>;
+    executeHandler(session: Session, params: URLSearchParams, pathParams: string[], hostParams: Record<string, string>, method?: string): Promise<void>;
+    hasHandler(method: string): boolean;
     /**
      * 设置可用方法
      * @param methods 可用方法
@@ -80,3 +85,4 @@ export declare class Route {
       */
     wsOn(event: string, handler: (...args: any[]) => void): this;
 }
+export {};

package/dist/route.js

@@ -225,7 +225,9 @@ export class Route {
     path;
     segments;
     paramsInfo;
-    handler = null;
+    handlers = {};
+    pendingActionMethods = null;
+    methodsConfigured = false;
     middlewares = [];
     allowedMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD'];
     ws = null;
@@ -243,13 +245,17 @@ export class Route {
         this.segments = segments;
         this.paramsInfo = params;
     }
-    /**
-     * 设置路由处理器
-     * @param handler 路由处理器
-     * @returns this
-     */
-    action(handler) {
-        this.handler = handler;
+    action(methodOrHandler, maybeHandler) {
+        const handler = typeof methodOrHandler === 'function' ? methodOrHandler : maybeHandler;
+        if (!handler)
+            return this;
+        const methods = typeof methodOrHandler === 'function'
+            ? (this.pendingActionMethods ?? this.allowedMethods)
+            : (Array.isArray(methodOrHandler) ? methodOrHandler : [methodOrHandler]);
+        for (const method of methods) {
+            this.handlers[method.toUpperCase()] = handler;
+        }
+        this.pendingActionMethods = null;
         return this;
     }
     /**
@@ -459,18 +465,27 @@ export class Route {
      * @param params 查询参数
      * @param pathParams 路由参数
      */
-    async executeHandler(session, params, pathParams, hostParams) {
-        if (this.handler) {
-            await this.handler(session, params, ...pathParams, ...Object.values(hostParams));
+    async executeHandler(session, params, pathParams, hostParams, method) {
+        const handler = this.handlers[(method || session.client?.req?.method || 'GET').toUpperCase()];
+        if (handler) {
+            await handler(session, params, ...pathParams, ...Object.values(hostParams));
         }
     }
+    hasHandler(method) {
+        return !!this.handlers[method.toUpperCase()];
+    }
     /**
      * 设置可用方法
      * @param methods 可用方法
      * @returns this
      */
     methods(...methods) {
-        this.allowedMethods = methods;
+        const normalized = methods.map(method => method.toUpperCase());
+        this.allowedMethods = this.methodsConfigured
+            ? [...new Set([...this.allowedMethods, ...normalized])]
+            : normalized;
+        this.methodsConfigured = true;
+        this.pendingActionMethods = normalized;
         return this;
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yumerijs/core",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Core module for yumeri",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",