typespeed 2.4.11 → 2.5.0

package/CHANGELOG.md

@@ -2,9 +2,14 @@
 
 typespeed 版本演进记录。本文件 2026-09-06 从 git 历史反推建立；git 最早提交 2022-09-18（ch01）。
 
-## 2.4.x（当前 2.4.10）
+## 2.5.x
 
-- **2.4.10**：升级 jsonwebtoken 和 mysql2 库（2024-05-07，当前 HEAD）
+- **2.5.0**：装饰器双轨——支持 TC39 标准装饰器（Stage 2.7），legacy 装饰器零破坏。单份源码运行时双签名感知（`isStd` 判据），覆盖 core/route/database 三族 + 入口 `app`/`value`；新增方法级 `@bind` 装饰器（route 参数名→来源、database 占位符→索引，替代标准模式删除的参数装饰器）；`@autoware`/`@resource`/`@bean` 支持显式 token（标准模式无 `design:type`）；类型声明宽松化；新增标准模式示例 `introduction/decorator-next/` + `isStd` 单测（2026-09-07）
+
+## 2.4.x
+
+- **2.4.11**：README 四入口、CI 修复（action 升 v4、node 22）、CHANGELOG 建立、getRootPath 兼容 Node22/mocha（2026-09-06）
+- **2.4.10**：升级 jsonwebtoken 和 mysql2 库（2024-05-07）
 - **2.4.9**：修复 SocketIO、MQ、Redis 等对象获取不准确问题（2024-04-22）
 - **2.4.8**：修复 socket.io 未从 bean 工厂获取装饰类的问题；修复 select 返回值不为 null 的问题（2024-04-22）
 - **2.4.7**：logx 日志模块（2024-04-21）

package/app/src/test-bind.class.ts

@@ -0,0 +1,41 @@
+import { component, getMapping, bind, resource, autoware, bean, insert } from "../../src/typespeed";
+import UserModel from "./user-model.class";
+
+class TestBean {
+    name = "test-bean";
+}
+
+@component
+export default class TestBind {
+
+    @bean(TestBean)
+    getBeanInstance() { return new TestBean(); }
+
+    @autoware(TestBean)
+    private autowired: TestBean;
+
+    @resource(UserModel, "user")
+    private userModel: UserModel;
+
+    @getMapping("/bind/param/:id")
+    @bind({ id: "reqParam", name: "reqQuery" })
+    async bindParam(id: string, name: string) {
+        return { id, name };
+    }
+
+    @getMapping("/bind/token")
+    async bindToken(req, res) {
+        res.send(this.autowired.name + "|" + (this.userModel ? "model-ok" : "model-null"));
+    }
+
+    @getMapping("/bind/db")
+    async bindDb(req, res) {
+        const id = req.query.id || 1;
+        const newId = await this.addRowByBind("bind name " + id, id);
+        res.send("bind insert: " + newId);
+    }
+
+    @insert("Insert into `user` (id, name) values (#{id}, #{name})")
+    @bind({ name: 0, id: 1 })
+    private async addRowByBind(newName: string, id: number) { }
+}

package/dist/bind.decorator.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBindMapping = exports.bind = void 0;
+const decorator_utils_1 = require("./decorator-utils");
+/**
+ * 方法级参数绑定注册表：key = `[className, methodName]`，value = 绑定声明。
+ * 标准装饰器删除了参数装饰器，@bind 是方法级替代（legacy 模式同样可用）。
+ * 按 value 类型区分两种语义：
+ *   - database 场景：{ SQL占位符名: 参数索引 }（值为 number）
+ *   - route 场景：{ 参数名: 请求来源 }（值为 string，如 "reqParam" / "reqBody" / "reqQuery"）
+ */
+const bindParamMap = new Map();
+/**
+ * @bind 方法级参数绑定装饰器。
+ *
+ * database 散参绑定（对象传参已是主路径，@bind 作散参补充）：
+ * ```
+ * @insert("Insert into `user` (id, name) values (#{id}, #{name})")
+ * @bind({ name: 0, id: 1 })
+ * async addRow(newName: string, id: number) { }
+ * ```
+ *
+ * route 参数绑定（替代 req/res/reqBody/reqParam/reqQuery/reqForm 参数装饰器）：
+ * ```
+ * @getMapping("/user/:id")
+ * @bind({ id: "reqParam", body: "reqBody", q: "reqQuery" })
+ * async getUser(id: string, body: any, q: string) { }
+ * ```
+ */
+function bind(mapping) {
+    return function (...args) {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            const methodName = String(ctx.name);
+            ctx.addInitializer(function () {
+                bindParamMap.set([this.constructor.name, methodName].toString(), mapping);
+            });
+            return;
+        }
+        const target = args[0];
+        const propertyKey = args[1];
+        bindParamMap.set([target.constructor.name, propertyKey].toString(), mapping);
+    };
+}
+exports.bind = bind;
+/** 读取某方法上的 @bind 声明（route/database 内部使用） */
+function getBindMapping(className, methodName) {
+    return bindParamMap.get([className, methodName].toString());
+}
+exports.getBindMapping = getBindMapping;

package/dist/core.decorator.js

@@ -4,10 +4,19 @@ exports.schedule = exports.getComponent = exports.getBean = exports.autoware = e
 require("reflect-metadata");
 const cron = require("cron");
 const log_factory_class_1 = require("./factory/log-factory.class");
+const decorator_utils_1 = require("./decorator-utils");
 const resourceObjects = new Map();
 const beanMapper = new Map();
 const objectMapper = new Map();
-function component(constructorFunction) {
+function component(...args) {
+    if ((0, decorator_utils_1.isStd)(args)) {
+        const [ctor, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+        ctx.addInitializer(function () {
+            objectMapper.set(this.name, new this());
+        });
+        return;
+    }
+    const constructorFunction = args[0];
     objectMapper.set(constructorFunction.name, new constructorFunction());
 }
 exports.component = component;
@@ -15,45 +24,114 @@ function getComponent(constructorFunction) {
     return objectMapper.get(constructorFunction.name);
 }
 exports.getComponent = getComponent;
-function bean(target, propertyKey) {
-    let returnType = Reflect.getMetadata("design:returntype", target, propertyKey);
-    //const targetObject = new target.constructor();
-    beanMapper.set(returnType.name, {
-        "target": target, "propertyKey": propertyKey,
-        "factory": target[propertyKey]()
-    });
+function bean(...args) {
+    if (args.length >= 2) {
+        // 直接装饰器形式：@bean（无 token，走 legacy design:returntype）
+        return beanWithToken(undefined)(...args);
+    }
+    // 工厂形式：@bean(Token)（显式返回类型 token，标准模式必需）
+    return beanWithToken(args[0]);
 }
 exports.bean = bean;
+function beanWithToken(token) {
+    return function (...args) {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            const key = String(ctx.name);
+            ctx.addInitializer(function () {
+                beanMapper.set(token ? token.name : key, {
+                    "target": this, "propertyKey": key,
+                    "factory": this[key]()
+                });
+            });
+            return;
+        }
+        const target = args[0];
+        const propertyKey = args[1];
+        let returnType = token || Reflect.getMetadata("design:returntype", target, propertyKey);
+        beanMapper.set(returnType.name, {
+            "target": target, "propertyKey": propertyKey,
+            "factory": target[propertyKey]()
+        });
+    };
+}
 function getBean(mappingClass) {
     const bean = beanMapper.get(mappingClass.name);
     return bean["factory"];
 }
 exports.getBean = getBean;
-function autoware(target, propertyKey) {
-    const type = Reflect.getMetadata("design:type", target, propertyKey);
-    Object.defineProperty(target, propertyKey, {
-        get: () => {
-            const targetObject = beanMapper.get(type.name);
-            if (targetObject === undefined) {
-                const resourceKey = [target.constructor.name, propertyKey, type.name].toString();
-                if (!resourceObjects[resourceKey]) {
-                    resourceObjects[resourceKey] = new type();
+function autoware(...args) {
+    if (args.length >= 2) {
+        // 直接装饰器形式：@autoware（无 token，走 legacy design:type）
+        return autowareWithToken(undefined)(...args);
+    }
+    // 工厂形式：@autoware(Token)（显式 token，标准模式必需）
+    return autowareWithToken(args[0]);
+}
+exports.autoware = autoware;
+function autowareWithToken(token) {
+    return function (...args) {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            // 标准 field 装饰器：标准模式无 design:type，有 token 才能注入。
+            return (initialValue) => {
+                if (!token)
+                    return initialValue;
+                const bean = beanMapper.get(token.name);
+                if (bean !== undefined)
+                    return bean["factory"];
+                return new token();
+            };
+        }
+        const target = args[0];
+        const propertyKey = args[1];
+        const type = token || Reflect.getMetadata("design:type", target, propertyKey);
+        Object.defineProperty(target, propertyKey, {
+            get: () => {
+                const targetObject = beanMapper.get(type.name);
+                if (targetObject === undefined) {
+                    const resourceKey = [target.constructor.name, propertyKey, type.name].toString();
+                    if (!resourceObjects[resourceKey]) {
+                        resourceObjects[resourceKey] = new type();
+                    }
+                    return resourceObjects[resourceKey];
                 }
-                return resourceObjects[resourceKey];
+                return targetObject["factory"];
             }
-            return targetObject["factory"];
-        }
-    });
+        });
+    };
+}
+/**
+ * 解析 @resource(...args) 的首参：若首参是 Function（类/token），作为显式 token，
+ * 其余作为构造参数；否则全部作为构造参数（legacy 行为，如 @resource("user")）。
+ */
+function extractTokenAndArgs(args) {
+    if (args.length > 0 && typeof args[0] === "function") {
+        return [args[0], args.slice(1)];
+    }
+    return [undefined, args];
 }
-exports.autoware = autoware;
 function resource(...args) {
-    return (target, propertyKey) => {
-        const type = Reflect.getMetadata("design:type", target, propertyKey);
+    const [token, initArgs] = extractTokenAndArgs(args);
+    return (...decoratorArgs) => {
+        if ((0, decorator_utils_1.isStd)(decoratorArgs)) {
+            // 标准 field 装饰器：标准模式无 design:type，需显式 token。
+            return (initialValue) => {
+                if (!token)
+                    return initialValue;
+                const bean = beanMapper.get(token.name);
+                if (bean !== undefined)
+                    return bean["factory"];
+                return new token(...initArgs);
+            };
+        }
+        const target = decoratorArgs[0];
+        const propertyKey = decoratorArgs[1];
+        const type = token || Reflect.getMetadata("design:type", target, propertyKey);
         Object.defineProperty(target, propertyKey, {
             get: () => {
                 const resourceKey = [target.constructor.name, propertyKey, type.name].toString();
                 if (!resourceObjects[resourceKey]) {
-                    resourceObjects[resourceKey] = new type(...args);
+                    resourceObjects[resourceKey] = new type(...initArgs);
                 }
                 return resourceObjects[resourceKey];
             }
@@ -93,7 +171,16 @@ function error(message, ...optionalParams) {
 }
 exports.error = error;
 function schedule(cronTime) {
-    return (target, propertyKey) => {
+    return (...args) => {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            ctx.addInitializer(function () {
+                new cron.CronJob(cronTime, this[String(ctx.name)]).start();
+            });
+            return;
+        }
+        const target = args[0];
+        const propertyKey = args[1];
         new cron.CronJob(cronTime, target[propertyKey]).start();
     };
 }

package/dist/database.decorator.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Model = exports.cache = exports.resultType = exports.param = exports.select = exports.remove = exports.update = exports.insert = void 0;
 const core_decorator_1 = require("./core.decorator");
+const decorator_utils_1 = require("./decorator-utils");
+const bind_decorator_1 = require("./bind.decorator");
 const cache_factory_class_1 = require("./factory/cache-factory.class");
 const data_source_factory_class_1 = require("./factory/data-source-factory.class");
 const paramMetadataKey = Symbol('param');
@@ -10,9 +12,24 @@ const cacheDefindMap = new Map();
 const tableVersionMap = new Map();
 let cacheBean;
 function insert(sql) {
-    return (target, propertyKey, descriptor) => {
-        descriptor.value = async (...args) => {
-            const result = await queryForExecute(sql, args, target, propertyKey);
+    return (...args) => {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            const propertyKey = String(ctx.name);
+            return async function (...callArgs) {
+                const result = await queryForExecute(sql, callArgs, this, propertyKey);
+                if (cacheBean && result.affectedRows > 0) {
+                    const [tableName, tableVersion] = getTableAndVersion("insert", sql);
+                    tableVersionMap.set(tableName, tableVersion + 1);
+                }
+                return result.insertId;
+            };
+        }
+        const target = args[0];
+        const propertyKey = args[1];
+        const descriptor = args[2];
+        descriptor.value = async (...callArgs) => {
+            const result = await queryForExecute(sql, callArgs, target, propertyKey);
             if (cacheBean && result.affectedRows > 0) {
                 const [tableName, tableVersion] = getTableAndVersion("insert", sql);
                 tableVersionMap.set(tableName, tableVersion + 1);
@@ -23,9 +40,24 @@ function insert(sql) {
 }
 exports.insert = insert;
 function update(sql) {
-    return (target, propertyKey, descriptor) => {
-        descriptor.value = async (...args) => {
-            const result = await queryForExecute(sql, args, target, propertyKey);
+    return (...args) => {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            const propertyKey = String(ctx.name);
+            return async function (...callArgs) {
+                const result = await queryForExecute(sql, callArgs, this, propertyKey);
+                if (cacheBean && result.affectedRows > 0) {
+                    const [tableName, tableVersion] = getTableAndVersion("update", sql);
+                    tableVersionMap.set(tableName, tableVersion + 1);
+                }
+                return result.affectedRows;
+            };
+        }
+        const target = args[0];
+        const propertyKey = args[1];
+        const descriptor = args[2];
+        descriptor.value = async (...callArgs) => {
+            const result = await queryForExecute(sql, callArgs, target, propertyKey);
             if (cacheBean && result.affectedRows > 0) {
                 const [tableName, tableVersion] = getTableAndVersion("update", sql);
                 tableVersionMap.set(tableName, tableVersion + 1);
@@ -36,9 +68,24 @@ function update(sql) {
 }
 exports.update = update;
 function remove(sql) {
-    return (target, propertyKey, descriptor) => {
-        descriptor.value = async (...args) => {
-            const result = await queryForExecute(sql, args, target, propertyKey);
+    return (...args) => {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            const propertyKey = String(ctx.name);
+            return async function (...callArgs) {
+                const result = await queryForExecute(sql, callArgs, this, propertyKey);
+                if (cacheBean && result.affectedRows > 0) {
+                    const [tableName, tableVersion] = getTableAndVersion("delete", sql);
+                    tableVersionMap.set(tableName, tableVersion + 1);
+                }
+                return result.affectedRows;
+            };
+        }
+        const target = args[0];
+        const propertyKey = args[1];
+        const descriptor = args[2];
+        descriptor.value = async (...callArgs) => {
+            const result = await queryForExecute(sql, callArgs, target, propertyKey);
             if (cacheBean && result.affectedRows > 0) {
                 const [tableName, tableVersion] = getTableAndVersion("delete", sql);
                 tableVersionMap.set(tableName, tableVersion + 1);
@@ -49,9 +96,35 @@ function remove(sql) {
 }
 exports.remove = remove;
 function select(sql) {
-    return (target, propertyKey, descriptor) => {
-        descriptor.value = async (...args) => {
-            const [newSql, sqlValues] = convertSQLParams(sql, target, propertyKey, args);
+    return (...args) => {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            const propertyKey = String(ctx.name);
+            return async function (...callArgs) {
+                const [newSql, sqlValues] = convertSQLParams(sql, this, propertyKey, callArgs);
+                const resultType = resultTypeMap.get([this.constructor.name, propertyKey].toString());
+                if (cacheBean && cacheDefindMap.has([this.constructor.name, propertyKey].toString())) {
+                    const [tableName, tableVersion] = getTableAndVersion("select", newSql);
+                    const cacheKey = JSON.stringify([tableName, tableVersion, newSql, sqlValues]);
+                    if (cacheBean.get(cacheKey)) {
+                        return cacheBean.get(cacheKey);
+                    }
+                    else {
+                        const rows = await actionQuery(newSql, sqlValues, resultType);
+                        cacheBean.set(cacheKey, rows, cacheDefindMap.get([this.constructor.name, propertyKey].toString()));
+                        return rows;
+                    }
+                }
+                else {
+                    return await actionQuery(newSql, sqlValues, resultType);
+                }
+            };
+        }
+        const target = args[0];
+        const propertyKey = args[1];
+        const descriptor = args[2];
+        descriptor.value = async (...callArgs) => {
+            const [newSql, sqlValues] = convertSQLParams(sql, target, propertyKey, callArgs);
             const resultType = resultTypeMap.get([target.constructor.name, propertyKey].toString());
             if (cacheBean && cacheDefindMap.has([target.constructor.name, propertyKey].toString())) {
                 const [tableName, tableVersion] = getTableAndVersion("select", newSql);
@@ -73,7 +146,16 @@ function select(sql) {
 }
 exports.select = select;
 function resultType(dataClass) {
-    return function (target, propertyKey) {
+    return function (...args) {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            ctx.addInitializer(function () {
+                resultTypeMap.set([this.constructor.name, String(ctx.name)].toString(), dataClass);
+            });
+            return;
+        }
+        const target = args[0];
+        const propertyKey = args[1];
         resultTypeMap.set([target.constructor.name, propertyKey].toString(), dataClass);
         //never return
     };
@@ -125,8 +207,17 @@ function convertSQLParams(decoratorSQL, target, propertyKey, args) {
             argsVal = new Map(Object.getOwnPropertyNames(args[0]).map((valName) => [valName, args[0][valName]]));
         }
         else {
-            const existingParameters = Reflect.getOwnMetadata(paramMetadataKey, target, propertyKey);
-            argsVal = new Map(existingParameters.map(([argName, argIdx]) => [argName, args[argIdx]]));
+            // 优先 @param（legacy reflect-metadata），否则回退 @bind（方法级声明，标准模式）
+            let existingParameters = Reflect.getOwnMetadata(paramMetadataKey, target, propertyKey);
+            if (!existingParameters) {
+                const bindMapping = (0, bind_decorator_1.getBindMapping)(target.constructor.name, propertyKey);
+                if (bindMapping) {
+                    existingParameters = Object.entries(bindMapping)
+                        .filter(([, value]) => typeof value === "number")
+                        .map(([name, value]) => [name, value]);
+                }
+            }
+            argsVal = new Map((existingParameters || []).map(([argName, argIdx]) => [argName, args[argIdx]]));
         }
         const regExp = /#{(\w+)}/;
         let match;
@@ -139,7 +230,22 @@ function convertSQLParams(decoratorSQL, target, propertyKey, args) {
     return [decoratorSQL, queryValues];
 }
 function cache(ttl) {
-    return function (target, propertyKey) {
+    return function (...args) {
+        if ((0, decorator_utils_1.isStd)(args)) {
+            const [, ctx] = (0, decorator_utils_1.getStdArgs)(args);
+            ctx.addInitializer(function () {
+                cacheDefindMap.set([this.constructor.name, String(ctx.name)].toString(), ttl);
+                if (cacheBean == null) {
+                    const cacheFactory = (0, core_decorator_1.getBean)(cache_factory_class_1.default);
+                    if (cacheFactory || cacheFactory["factory"]) {
+                        cacheBean = cacheFactory["factory"];
+                    }
+                }
+            });
+            return;
+        }
+        const target = args[0];
+        const propertyKey = args[1];
         cacheDefindMap.set([target.constructor.name, propertyKey].toString(), ttl);
         if (cacheBean == null) {
             const cacheFactory = (0, core_decorator_1.getBean)(cache_factory_class_1.default);

package/dist/decorator-utils.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * 装饰器双签名感知工具。
+ *
+ * typespeed 2.5.x 起，装饰器同时支持两套运行时签名：
+ *   - legacy（experimentalDecorators: true，2.4.x 现状）：
+ *       类装饰器 (ctor)；方法/属性装饰器 (target, key)；带 descriptor 的方法 (target, key, descriptor)；参数 (target, key, index)
+ *   - 标准（TC39 装饰器提案，当前 Stage 2.7，experimentalDecorators: false）：
+ *       统一 (value, context)，context 恒为带 kind 字段的对象
+ *
+ * 装饰器函数本质是普通函数，运行时收到什么签名由「调用方（用户代码）」的编译模式决定，
+ * 因此库可以单份源码、运行时按签名形态分流：legacy 分支逻辑与 2.4.x 逐字一致，标准分支为新增。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStdArgs = exports.isStd = void 0;
+/**
+ * 判断装饰器收到的运行时参数是否为标准装饰器签名 (value, context)。
+ *
+ * 判据（与 `2.5.x-新版装饰器使用方案.md` 一致）：
+ *   参数个数 === 2 且第二个参数是「带 string 类型 kind 字段」的对象。
+ *
+ * 为什么这个判据可靠：
+ *   - legacy 类装饰器只有 1 参 → 不满足 length === 2
+ *   - legacy 方法/属性装饰器第二参是 string 的 key → 不是对象
+ *   - legacy 带 descriptor 的方法 / 参数装饰器是 3 参 → 不满足 length === 2
+ *   - 标准模式第二参恒是带 kind 的对象 → 命中
+ */
+function isStd(args) {
+    return args.length === 2
+        && typeof args[1] === "object"
+        && args[1] !== null
+        && typeof args[1].kind === "string";
+}
+exports.isStd = isStd;
+/**
+ * 从标准装饰器参数中解出 (value, context)。
+ * 仅应在 isStd(args) 为 true 时调用。
+ */
+function getStdArgs(args) {
+    return [args[0], args[1]];
+}
+exports.getStdArgs = getStdArgs;