@yumerijs/core 3.0.3 → 3.0.5

package/dist/config.d.ts

@@ -1,14 +1,17 @@
+import type { I18n } from './i18n.js';
 export declare function fallback<T>(schema: Schema<T>, config: T): T;
 export declare class Schema<T = any> {
     _type?: T;
     type: string;
     isRequired?: boolean;
     description?: string;
+    /** 说明文字对应的 i18n key，由 key() 设置 */
+    i18nKey?: string;
     defaultValue?: any;
     properties?: Record<string, Schema<any>>;
     items?: Schema<any>;
     enum?: T[];
-    constructor(definition: Omit<Schema<T>, '_type' | 'required' | 'default'> & {
+    constructor(definition: Omit<Schema<T>, '_type' | 'required' | 'default' | 'key'> & {
         enum?: T[];
     });
     static string(description?: string): Schema<string>;
@@ -23,8 +26,31 @@ export declare class Schema<T = any> {
     }, description?: string): Schema<T & U>;
     static enum<L extends string | number>(values: L[], description?: string): Schema<L>;
     required(this: this): this;
+    /**
+     * 绑定说明文字的 i18n key
+     *
+     * 绑定后该配置项的说明文字会按请求语言从内置 I18n 里解析；
+     * key 未注册或没命中任何语言时，仍然显示 description 原文，
+     * 所以不接入 i18n 的插件不受影响。
+     *
+     * @param name 翻译 key，建议用 `插件名.config.配置项` 形式的命名空间避免全局撞车
+     */
+    key(name: string): this;
     default(this: this, value: T): this;
 }
+/**
+ * 解析 schema 说明文字要显示的文本
+ *
+ * 没绑定 i18n key、或 key 没有命中任何语言时一律退回 description 原文，
+ * 因此插件的显示效果在未接入 i18n 时与之前完全一致。
+ * 绑定了 key 的配置项可以不写 description，此时直接使用译文；
+ * 译文和原文都没有时返回 undefined，由调用方回落到字段名。
+ *
+ * @param schema schema 节点
+ * @param i18n i18n 实例，未初始化时按原文处理
+ * @param langs 语言优先级列表，通常是 session.request.languages
+ */
+export declare function resolveDescription(schema: Schema<any>, i18n?: I18n, langs?: string[]): string | undefined;
 export { Schema as ConfigSchema };
 export interface Config {
     [key: string]: any;

package/dist/config.js

@@ -30,6 +30,8 @@ export class Schema {
     type;
     isRequired;
     description;
+    /** 说明文字对应的 i18n key，由 key() 设置 */
+    i18nKey;
     defaultValue;
     properties;
     items;
@@ -38,6 +40,7 @@ export class Schema {
         this.type = definition.type;
         this.isRequired = definition.isRequired;
         this.description = definition.description;
+        this.i18nKey = definition.i18nKey;
         this.defaultValue = definition.defaultValue;
         this.properties = definition.properties;
         this.items = definition.items;
@@ -70,9 +73,46 @@ export class Schema {
         this.isRequired = true;
         return this;
     }
+    /**
+     * 绑定说明文字的 i18n key
+     *
+     * 绑定后该配置项的说明文字会按请求语言从内置 I18n 里解析；
+     * key 未注册或没命中任何语言时，仍然显示 description 原文，
+     * 所以不接入 i18n 的插件不受影响。
+     *
+     * @param name 翻译 key，建议用 `插件名.config.配置项` 形式的命名空间避免全局撞车
+     */
+    key(name) {
+        this.i18nKey = name;
+        return this;
+    }
     default(value) {
         this.defaultValue = value;
         return this;
     }
 }
+/**
+ * 解析 schema 说明文字要显示的文本
+ *
+ * 没绑定 i18n key、或 key 没有命中任何语言时一律退回 description 原文，
+ * 因此插件的显示效果在未接入 i18n 时与之前完全一致。
+ * 绑定了 key 的配置项可以不写 description，此时直接使用译文；
+ * 译文和原文都没有时返回 undefined，由调用方回落到字段名。
+ *
+ * @param schema schema 节点
+ * @param i18n i18n 实例，未初始化时按原文处理
+ * @param langs 语言优先级列表，通常是 session.request.languages
+ */
+export function resolveDescription(schema, i18n, langs) {
+    if (!schema)
+        return undefined;
+    const key = schema.i18nKey;
+    if (key && i18n) {
+        const translated = i18n.get(key, langs);
+        // I18n.get 在没命中任何语言时会原样返回 key，借此判断是否真的翻译到了
+        if (translated !== key)
+            return translated;
+    }
+    return schema.description;
+}
 export { Schema as ConfigSchema };

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,4 +1,5 @@
 import path from 'path';
+import { setInterval as nodeSetInterval, clearInterval as nodeClearInterval, setTimeout as nodeSetTimeout, clearTimeout as nodeClearTimeout } from 'timers';
 /**
  * 插件上下文对象
  * 每个插件一个 Context，用于管理插件注册的命令、路由、事件、组件和中间件
@@ -15,6 +16,8 @@ export class Context {
     i18ns = [];
     affects = [];
     services = [];
+    timers = new Set();
+    disposed = false;
     component;
     renderer;
     module;
@@ -50,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 路由路径
@@ -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.d.ts

@@ -39,6 +39,33 @@ export interface CoreOptions {
     skipcheckUpdates?: boolean;
 }
 export declare const coreConfigSchema: Schema<CoreOptions>;
+/** 核心配置项的内置文案，随 i18n 实例初始化自动注册 */
+export declare const coreI18n: {
+    'core.config.port': {
+        zh: string;
+        en: string;
+    };
+    'core.config.host': {
+        zh: string;
+        en: string;
+    };
+    'core.config.enableCors': {
+        zh: string;
+        en: string;
+    };
+    'core.config.enableWs': {
+        zh: string;
+        en: string;
+    };
+    'core.config.lang': {
+        zh: string;
+        en: string;
+    };
+    'core.config.skipcheckUpdates': {
+        zh: string;
+        en: string;
+    };
+};
 export declare const enum PluginStatus {
     ENABLED = "enabled",
     DISABLED = "disabled",
@@ -58,11 +85,22 @@ export declare class Core {
     hooks: Record<string, Hook>;
     coreConfig: CoreOptions;
     server: CoreServer;
-    i18n: I18n;
+    private _i18n?;
     loader: any;
     storage: SessionStorageProcessor;
     renderers: Map<string, IRenderer>;
     pluginRenderers: Map<string, string>;
+    /**
+     * i18n 实例
+     *
+     * 未赋值时按 core 配置的 lang 惰性创建，赋值时自动注册核心内置文案，
+     * 这样无论 i18n 是被 loader 创建还是被直接使用 core 的场景创建，
+     * coreConfigSchema 的说明文字都能被翻译到。
+     */
+    get i18n(): I18n;
+    set i18n(value: I18n);
+    /** 设置 i18n 实例并注册核心内置文案 */
+    setI18n(i18n: I18n): void;
     constructor(loader?: any, coreConfig?: CoreOptions, loggersetCore?: boolean, splash?: boolean);
     private checkUpdate;
     addRenderer(renderer: IRenderer): void;

package/dist/core.js

@@ -4,6 +4,7 @@ import { Logger } from './logger.js';
 import { Route } from './route.js';
 import { Hook } from './hook.js';
 import { Server as CoreServer } from './server.js';
+import { I18n } from './i18n.js';
 import { SessionStorageProcessor } from './storage.js';
 import * as fs from 'fs';
 import semver from 'semver';
@@ -51,13 +52,22 @@ export function resolvePluginModule(module, context, config) {
     return plugin;
 }
 export const coreConfigSchema = Schema.object({
-    port: Schema.number('监听端口').default(14510),
-    host: Schema.string('监听地址').default('0.0.0.0'),
-    enableCors: Schema.boolean('启用跨域').default(false),
-    enableWs: Schema.boolean('启用 WebSocket').default(false),
-    lang: Schema.array(Schema.string(), '语言列表').default(['zh', 'en']),
-    skipcheckUpdates: Schema.boolean('启动时检查更新').default(false)
+    port: Schema.number('监听端口').key('core.config.port').default(14510),
+    host: Schema.string('监听地址').key('core.config.host').default('0.0.0.0'),
+    enableCors: Schema.boolean('启用跨域').key('core.config.enableCors').default(false),
+    enableWs: Schema.boolean('启用 WebSocket').key('core.config.enableWs').default(false),
+    lang: Schema.array(Schema.string(), '语言列表').key('core.config.lang').default(['zh', 'en']),
+    skipcheckUpdates: Schema.boolean('启动时检查更新').key('core.config.skipcheckUpdates').default(false)
 });
+/** 核心配置项的内置文案，随 i18n 实例初始化自动注册 */
+export const coreI18n = {
+    'core.config.port': { zh: '监听端口', en: 'Listening port' },
+    'core.config.host': { zh: '监听地址', en: 'Listening address' },
+    'core.config.enableCors': { zh: '启用跨域', en: 'Enable CORS' },
+    'core.config.enableWs': { zh: '启用 WebSocket', en: 'Enable WebSocket' },
+    'core.config.lang': { zh: '语言列表', en: 'Language list' },
+    'core.config.skipcheckUpdates': { zh: '启动时检查更新', en: 'Check for updates on startup' }
+};
 export class Core {
     emitter = new EventEmitter();
     components = {};
@@ -68,11 +78,32 @@ export class Core {
     hooks = {};
     coreConfig;
     server;
-    i18n;
+    _i18n;
     loader;
     storage = new SessionStorageProcessor();
     renderers = new Map();
     pluginRenderers = new Map(); // Stores which plugin uses which renderer
+    /**
+     * i18n 实例
+     *
+     * 未赋值时按 core 配置的 lang 惰性创建，赋值时自动注册核心内置文案，
+     * 这样无论 i18n 是被 loader 创建还是被直接使用 core 的场景创建，
+     * coreConfigSchema 的说明文字都能被翻译到。
+     */
+    get i18n() {
+        if (!this._i18n) {
+            this.setI18n(new I18n(this.coreConfig?.lang || ['zh', 'en']));
+        }
+        return this._i18n;
+    }
+    set i18n(value) {
+        this.setI18n(value);
+    }
+    /** 设置 i18n 实例并注册核心内置文案 */
+    setI18n(i18n) {
+        this._i18n = i18n;
+        i18n.register(coreI18n);
+    }
     constructor(loader, coreConfig = {}, loggersetCore = true, splash = true) {
         this.coreConfig = fallback(coreConfigSchema, coreConfig);
         this.loader = loader;

package/dist/i18n.d.ts

@@ -10,6 +10,11 @@ export declare class I18n {
     constructor(fallback?: string[]);
     register(key: string | Record<string, any>, lang?: Record<string, string>): void;
     setFallback(fallback: string[]): void;
+    /**
+     * 判断一个值是否是语言表，即 `{ zh: '...', en: '...' }` 这种值全为字符串的对象。
+     * 这里不硬编码具体语言码，因为 fallback 列表可由 coreConfig.lang 配置。
+     */
+    private isLocaleMap;
     private flattenAndRegister;
     isRegistered(key: string): boolean;
     delete(key: string): void;

package/dist/i18n.js

@@ -22,17 +22,27 @@ export class I18n {
     setFallback(fallback) {
         this.fallback = fallback;
     }
+    /**
+     * 判断一个值是否是语言表，即 `{ zh: '...', en: '...' }` 这种值全为字符串的对象。
+     * 这里不硬编码具体语言码，因为 fallback 列表可由 coreConfig.lang 配置。
+     */
+    isLocaleMap(value) {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return false;
+        const values = Object.values(value);
+        return values.length > 0 && values.every(v => typeof v === 'string');
+    }
     flattenAndRegister(obj, prefix = '') {
         for (const [k, v] of Object.entries(obj)) {
             const fullKey = prefix ? `${prefix}.${k}` : k;
-            if (typeof v === 'object' && !('zh' in v || 'en' in v)) {
-                this.flattenAndRegister(v, fullKey);
-            }
-            else if (typeof v === 'object') {
+            if (this.isLocaleMap(v)) {
                 if (!this.data[fullKey])
                     this.data[fullKey] = {};
                 Object.assign(this.data[fullKey], v);
             }
+            else if (v && typeof v === 'object') {
+                this.flattenAndRegister(v, fullKey);
+            }
         }
     }
     isRegistered(key) {

package/package.json

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