@husky-di/decorator 1.0.0

package/README.md

@@ -0,0 +1,238 @@
+# @husky-di/decorator
+
+`@husky-di/decorator` 是 husky-di 的装饰器支持包，提供了基于 TypeScript 装饰器的依赖注入功能。
+
+## 概述
+
+该包专门为偏好使用装饰器语法的开发者设计，提供了简洁直观的依赖注入方式。**仅支持 TypeScript 装饰器**，不支持 ES 装饰器。
+
+### 为什么仅支持 TypeScript 装饰器？
+
+husky-di 的设计理念是**仅支持构造函数注入**，而 ES 装饰器的规范中**没有设计参数注入器**。
+
+## 安装
+
+```bash
+pnpm add @husky-di/decorator
+```
+
+## 核心装饰器
+
+### @injectable()
+
+标记一个类为可注入，使其能够被依赖注入容器管理。
+
+> 背后的原因是因为只有应用了装饰器，typescript 编译器才会触发元数据的标记。
+
+```typescript
+import { injectable } from "@husky-di/decorator";
+
+@injectable()
+class UserService {
+  constructor() {}
+}
+```
+
+### @inject()
+
+用于构造函数参数注入，支持多种注入选项。
+
+```typescript
+import { inject, injectable } from "@husky-di/decorator";
+
+@injectable()
+class LoggerService {
+  log(message: string) {
+    console.log(message);
+  }
+}
+
+@injectable()
+class UserService {
+  constructor(@inject(LoggerService) private logger: LoggerService) {}
+}
+```
+
+## 注入选项
+
+`@inject()` 装饰器支持多种注入选项：
+
+### 动态注入 (dynamic)
+
+获取服务的动态引用，支持延迟解析：
+
+```typescript
+@injectable()
+class ConfigService {
+  getValue(key: string) {
+    return `config-${key}`;
+  }
+}
+
+@injectable()
+class CacheService {
+  constructor(
+    @inject(ConfigService, { dynamic: true })
+    private configRef: Ref<ConfigService>
+  ) {}
+
+  get(key: string) {
+    const config = this.configRef.current;
+    return `cached-${config.getValue(key)}`;
+  }
+}
+```
+
+### 引用注入 (ref)
+
+获取服务的引用对象：
+
+```typescript
+@injectable()
+class ApiService {
+  constructor(
+    @inject(CacheService, { ref: true })
+    public cacheRef: Ref<CacheService>
+  ) {}
+}
+```
+
+### 可选注入 (optional)
+
+支持可选依赖，当依赖不存在时不会抛出错误：
+
+```typescript
+@injectable()
+class TestService {
+  constructor(
+    @inject(ExistingService, { optional: true })
+    public service: ExistingService
+  ) {}
+}
+```
+
+## 中间件集成
+
+装饰器包提供了 `decoratorMiddleware` 中间件，需要注册到全局中间件中：
+
+```typescript
+import { globalMiddleware } from "@husky-di/core";
+import { decoratorMiddleware } from "@husky-di/decorator";
+
+// 注册装饰器中间件
+globalMiddleware.use(decoratorMiddleware);
+```
+
+## 完整示例
+
+```typescript
+import "reflect-metadata";
+import { createContainer, globalMiddleware } from "@husky-di/core";
+import { decoratorMiddleware, inject, injectable } from "@husky-di/decorator";
+
+// 注册装饰器中间件
+globalMiddleware.use(decoratorMiddleware);
+
+// 创建容器
+const container = createContainer();
+
+// 定义服务
+@injectable()
+class LoggerService {
+  log(message: string) {
+    return `Logged: ${message}`;
+  }
+}
+
+@injectable()
+class DatabaseService {
+  constructor(@inject(LoggerService) private logger: LoggerService) {}
+
+  query(sql: string) {
+    return this.logger.log(`Executing: ${sql}`);
+  }
+}
+
+@injectable()
+class UserService {
+  constructor(
+    @inject(DatabaseService) private db: DatabaseService,
+    @inject(LoggerService) private logger: LoggerService
+  ) {}
+
+  getUser(id: string) {
+    return this.db.query(`SELECT * FROM users WHERE id = ${id}`);
+  }
+}
+
+// 使用服务
+const userService = container.resolve(UserService);
+const result = userService.getUser("123");
+console.log(result); // "Logged: Executing: SELECT * FROM users WHERE id = 123"
+```
+
+## 错误处理
+
+### 常见错误
+
+1. **重复使用 @injectable()**
+
+   ```typescript
+   // ❌ 错误：不能对同一个类使用两次 @injectable()
+   @injectable()
+   @injectable()
+   class TestService {}
+   ```
+
+2. **注入非可注入类**
+
+   ```typescript
+   // ❌ 错误：依赖的类没有使用 @injectable()
+   class NonInjectableService {}
+
+   @injectable()
+   class TestService {
+     constructor(@inject(NonInjectableService) dep: NonInjectableService) {}
+   }
+   ```
+
+3. **循环依赖**
+
+   ```typescript
+   // ❌ 错误：检测到循环依赖
+   @injectable()
+   class ServiceA {
+     constructor(@inject(ServiceB) public serviceB: ServiceB) {}
+   }
+
+   @injectable()
+   class ServiceB {
+     constructor(@inject(ServiceA) public serviceA: ServiceA) {}
+   }
+   ```
+
+## 设计原理
+
+装饰器包使用 TypeScript 的 `reflect-metadata`或其他提供 Reflect API 的库来存储和管理注入元数据：
+
+- `@injectable()` 收集构造函数参数的注入信息
+- `@inject()` 为特定参数位置设置注入配置
+- `decoratorMiddleware` 在实例化时读取元数据并执行注入
+
+## 最佳实践
+
+1. **始终使用 @injectable() 标记可注入类**
+2. **为所有依赖参数使用 @inject() 装饰器**
+3. **合理使用注入选项（dynamic、ref、optional）**
+4. **避免循环依赖，必要时使用 ref 选项**
+5. **在应用启动时注册 decoratorMiddleware**
+
+## 注意事项
+
+- 需要启用 TypeScript 的装饰器支持
+
+> 建议在 tsconfig.json 中启用 `experimentalDecorators` 和 `emitDecoratorMetadata` 选项
+
+- 需要引入 `reflect-metadata` 包或其他提供 Reflect API 的库
+- `@inject()` 仅支持构造函数注入，不支持属性注入 (可以 `@husky-di/core` 中的 `resolve` 方法来实现属性注入)
+- 装饰器中间件需要全局注册，这样才会在每个容器中都生效

package/dist/constants/metadata-key.const.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @overview
+ * @author AEPKILL
+ * @created 2021-10-03 20:55:17
+ */
+export declare const ParamsMetadataKeyConst = "design:paramtypes";
+export declare const InjectionMetadataKeyConst = "husky-di.injection-metadata";
+export declare const InjectionParamsMetadataKeyConst = "husky-di.injection-params-metadata";

package/dist/decorators/inject.decorator.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @overview
+ * @author AEPKILL
+ * @created 2021-10-03 21:08:27
+ */
+import type { ServiceIdentifier } from "@husky-di/core";
+import type { InjectionMetadata } from "../types/injection-metadata.type";
+export type InjectOptions<T> = Omit<InjectionMetadata<T>, "serviceIdentifier">;
+export declare const inject: <T>(serviceIdentifier: ServiceIdentifier<T>, options?: InjectOptions<T>) => ParameterDecorator;

package/dist/decorators/injectable.decorator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @overview
+ * @author AEPKILL
+ * @created 2022-03-11 16:02:58
+ */
+/**
+ * @description
+ * markup a class as a injectable class
+ */
+export declare const injectable: () => ClassDecorator;

package/dist/decorators/tagged.decorator.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @overview
+ * @author AEPKILL
+ * @created 2021-10-03 21:16:18
+ */
+import type { InjectionMetadata } from "../types/injection-metadata.type";
+export declare const tagged: <T>(metadata: InjectionMetadata<T>) => ParameterDecorator;

package/dist/index.cjs

@@ -0,0 +1,99 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    inject: ()=>inject,
+    tagged: ()=>tagged,
+    decoratorMiddleware: ()=>decoratorMiddleware,
+    injectable: ()=>injectable
+});
+const ParamsMetadataKeyConst = "design:paramtypes";
+const InjectionMetadataKeyConst = "husky-di.injection-metadata";
+const tagged = (metadata)=>(target, _propertyKey, parameterIndex)=>{
+        const parametersMetadata = Reflect.getMetadata(InjectionMetadataKeyConst, target) || [];
+        parametersMetadata[parameterIndex] = metadata;
+        Reflect.defineMetadata(InjectionMetadataKeyConst, parametersMetadata, target);
+    };
+const inject = (serviceIdentifier, options)=>tagged({
+        ...options,
+        serviceIdentifier
+    });
+const InjectionMetadataMap = "undefined" == typeof WeakMap ? Map : WeakMap;
+const injectionMetadataMap = new InjectionMetadataMap();
+const injectable = ()=>(target)=>{
+        if (injectionMetadataMap.has(target)) throw new Error(`can't use  "@injectable()" decorate class "${target.name}" twice`);
+        const parametersServiceIdentifiers = Reflect.getMetadata(ParamsMetadataKeyConst, target) || [];
+        const parametersMetadata = Reflect.getMetadata(InjectionMetadataKeyConst, target) || [];
+        const metadata = [];
+        const parametersMetadataLength = Math.max(parametersServiceIdentifiers.length, parametersMetadata.length);
+        for(let index = 0; index < parametersMetadataLength; index++){
+            if (void 0 !== parametersMetadata[index]) {
+                metadata.push(parametersMetadata[index]);
+                continue;
+            }
+            const serviceIdentifier = parametersServiceIdentifiers[index];
+            if ("function" != typeof serviceIdentifier) throw new Error(`only can inject class type in constructor "${target.name}" parameter #${index}`);
+            metadata.push({
+                serviceIdentifier
+            });
+        }
+        injectionMetadataMap.set(target, metadata);
+    };
+const core_namespaceObject = require("@husky-di/core");
+const decoratorMiddleware = {
+    name: Symbol("DecoratorMiddleware"),
+    executor: (params, next)=>{
+        const { registration, resolveRecord } = params;
+        if (registration.type !== core_namespaceObject.RegistrationTypeEnum["class"]) return next(params);
+        const provider = registration.provider;
+        const parametersMetadata = injectionMetadataMap.get(provider);
+        if (!parametersMetadata) throw new core_namespaceObject.ResolveException(`The class ${provider.name} has no injection metadata, please make sure the class is decorated with @Injectable().`, resolveRecord);
+        const parameters = parametersMetadata.map((metadata, index)=>{
+            const { serviceIdentifier, ...options } = metadata;
+            resolveRecord._internalStashCurrent();
+            resolveRecord.addRecordNode({
+                type: core_namespaceObject.ResolveRecordTypeEnum.message,
+                message: `Resolve parameter #${index} of constructor "${provider.name}"`
+            });
+            const instance = (0, core_namespaceObject.resolve)(serviceIdentifier, options);
+            resolveRecord._internalRestoreCurrent();
+            return instance;
+        });
+        return new provider(...parameters);
+    }
+};
+exports.decoratorMiddleware = __webpack_exports__.decoratorMiddleware;
+exports.inject = __webpack_exports__.inject;
+exports.injectable = __webpack_exports__.injectable;
+exports.tagged = __webpack_exports__.tagged;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "decoratorMiddleware",
+    "inject",
+    "injectable",
+    "tagged"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @overview
+ * @author AEPKILL
+ * @created 2025-08-08 21:00:35
+ */
+export * from "./decorators/inject.decorator";
+export * from "./decorators/injectable.decorator";
+export * from "./decorators/tagged.decorator";
+export { decoratorMiddleware } from "./middlewares/decorator.middleware";
+export * from "./types/injection-metadata.type";

package/dist/index.js

@@ -0,0 +1,56 @@
+import { RegistrationTypeEnum, ResolveException, ResolveRecordTypeEnum, resolve } from "@husky-di/core";
+const ParamsMetadataKeyConst = "design:paramtypes";
+const InjectionMetadataKeyConst = "husky-di.injection-metadata";
+const tagged = (metadata)=>(target, _propertyKey, parameterIndex)=>{
+        const parametersMetadata = Reflect.getMetadata(InjectionMetadataKeyConst, target) || [];
+        parametersMetadata[parameterIndex] = metadata;
+        Reflect.defineMetadata(InjectionMetadataKeyConst, parametersMetadata, target);
+    };
+const inject = (serviceIdentifier, options)=>tagged({
+        ...options,
+        serviceIdentifier
+    });
+const InjectionMetadataMap = "undefined" == typeof WeakMap ? Map : WeakMap;
+const injectionMetadataMap = new InjectionMetadataMap();
+const injectable = ()=>(target)=>{
+        if (injectionMetadataMap.has(target)) throw new Error(`can't use  "@injectable()" decorate class "${target.name}" twice`);
+        const parametersServiceIdentifiers = Reflect.getMetadata(ParamsMetadataKeyConst, target) || [];
+        const parametersMetadata = Reflect.getMetadata(InjectionMetadataKeyConst, target) || [];
+        const metadata = [];
+        const parametersMetadataLength = Math.max(parametersServiceIdentifiers.length, parametersMetadata.length);
+        for(let index = 0; index < parametersMetadataLength; index++){
+            if (void 0 !== parametersMetadata[index]) {
+                metadata.push(parametersMetadata[index]);
+                continue;
+            }
+            const serviceIdentifier = parametersServiceIdentifiers[index];
+            if ("function" != typeof serviceIdentifier) throw new Error(`only can inject class type in constructor "${target.name}" parameter #${index}`);
+            metadata.push({
+                serviceIdentifier
+            });
+        }
+        injectionMetadataMap.set(target, metadata);
+    };
+const decoratorMiddleware = {
+    name: Symbol("DecoratorMiddleware"),
+    executor: (params, next)=>{
+        const { registration, resolveRecord } = params;
+        if (registration.type !== RegistrationTypeEnum["class"]) return next(params);
+        const provider = registration.provider;
+        const parametersMetadata = injectionMetadataMap.get(provider);
+        if (!parametersMetadata) throw new ResolveException(`The class ${provider.name} has no injection metadata, please make sure the class is decorated with @Injectable().`, resolveRecord);
+        const parameters = parametersMetadata.map((metadata, index)=>{
+            const { serviceIdentifier, ...options } = metadata;
+            resolveRecord._internalStashCurrent();
+            resolveRecord.addRecordNode({
+                type: ResolveRecordTypeEnum.message,
+                message: `Resolve parameter #${index} of constructor "${provider.name}"`
+            });
+            const instance = resolve(serviceIdentifier, options);
+            resolveRecord._internalRestoreCurrent();
+            return instance;
+        });
+        return new provider(...parameters);
+    }
+};
+export { decoratorMiddleware, inject, injectable, tagged };

package/dist/middlewares/decorator.middleware.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @overview
+ * @author AEPKILL
+ * @created 2025-08-06 22:51:38
+ */
+/** biome-ignore-all lint/suspicious/noExplicitAny: need to use any to avoid type errors */
+import { type ResolveMiddleware } from "@husky-di/core";
+export declare const decoratorMiddleware: ResolveMiddleware<any, any>;

package/dist/shared/instances.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @overview
+ * @author AEPKILL
+ * @created 2025-08-06 21:47:22
+ */
+import type { Constructor } from "@husky-di/core";
+import type { InjectionMetadata } from "../types/injection-metadata.type";
+export declare const injectionMetadataMap: {
+    get<T>(target: Constructor<T>): InjectionMetadata<T>[];
+    has<T>(target: Constructor<T>): boolean;
+    set<T>(target: Constructor<T>, metadata: InjectionMetadata<T>[]): void;
+};

package/dist/types/injection-metadata.type.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @overview
+ * @author AEPKILL
+ * @created 2023-05-24 10:47:34
+ */
+import type { ResolveOptions, ServiceIdentifier } from "@husky-di/core";
+export type InjectionMetadata<T> = ResolveOptions<T> & {
+    serviceIdentifier: ServiceIdentifier<T>;
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@husky-di/decorator",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@husky-di/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.1.3",
+    "@rslib/core": "^0.11.2",
+    "@types/node": "^22.17.0",
+    "reflect-metadata": "^0.2.2",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "reflect-metadata": "^0.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "check": "biome check --write",
+    "dev": "rslib build --watch",
+    "format": "biome format --write",
+    "test": "vitest run"
+  }
+}