@husky-di/decorator 1.0.0 → 1.1.0

package/README.md

@@ -178,7 +178,7 @@ console.log(result); // "Logged: Executing: SELECT * FROM users WHERE id = 123"
 1. **重复使用 @injectable()**
 
    ```typescript
-   // ❌ 错误：不能对同一个类使用两次 @injectable()
+   // 错误：不能对同一个类使用两次 @injectable()
    @injectable()
    @injectable()
    class TestService {}
@@ -187,7 +187,7 @@ console.log(result); // "Logged: Executing: SELECT * FROM users WHERE id = 123"
 2. **注入非可注入类**
 
    ```typescript
-   // ❌ 错误：依赖的类没有使用 @injectable()
+   // 错误：依赖的类没有使用 @injectable()
    class NonInjectableService {}
 
    @injectable()
@@ -199,7 +199,7 @@ console.log(result); // "Logged: Executing: SELECT * FROM users WHERE id = 123"
 3. **循环依赖**
 
    ```typescript
-   // ❌ 错误：检测到循环依赖
+   // 错误：检测到循环依赖
    @injectable()
    class ServiceA {
      constructor(@inject(ServiceB) public serviceB: ServiceB) {}

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

@@ -1,8 +1,22 @@
 /**
  * @overview
+ * Metadata key constants used for storing and retrieving dependency injection metadata
  * @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";
+/**
+ * TypeScript's built-in metadata key for constructor parameter types.
+ *
+ * @see {@link https://www.typescriptlang.org/tsconfig/#Language_and_Environment_6254}
+ */
+export declare const PARAMS_METADATA_KEY = "design:paramtypes";
+/**
+ * Custom metadata key for storing injection metadata of a class.
+ * Contains information about how each constructor parameter should be resolved,
+ * including service identifiers and injection options.
+ *
+ * @remarks
+ * Stores: `Array<InjectionMetadata<T> | undefined>`
+ *
+ */
+export declare const INJECTION_METADATA_KEY = "husky-di.injection-metadata";

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

@@ -5,6 +5,6 @@
  */
 /**
  * @description
- * markup a class as a injectable class
+ * Mark a class as an injectable class
  */
 export declare const injectable: () => ClassDecorator;

package/dist/enums/decorator-error-code.enum.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @overview Decorator package error code enum.
+ * @author AEPKILL
+ * @created 2026-05-09 00:00:00
+ */
+export declare enum DecoratorErrorCodeEnum {
+    /**
+     * Class is decorated with @injectable() more than once.
+     * @see SPECIFICATION.md Section 4.1 M1
+     */
+    E_DUPLICATE_INJECTABLE = "E_DUPLICATE_INJECTABLE",
+    /**
+     * Constructor parameter without explicit metadata is not a class type.
+     * @see SPECIFICATION.md Section 4.1 M3
+     */
+    E_NON_CLASS_PARAMETER = "E_NON_CLASS_PARAMETER",
+    /**
+     * Class resolved through decorator middleware is not decorated with @injectable().
+     * @see SPECIFICATION.md Section 5.1 V1
+     */
+    E_NOT_INJECTABLE = "E_NOT_INJECTABLE",
+    /**
+     * Injection metadata does not include a serviceIdentifier.
+     * @see SPECIFICATION.md Section 4.3 T2
+     */
+    E_MISSING_SERVICE_IDENTIFIER = "E_MISSING_SERVICE_IDENTIFIER",
+    /**
+     * Injection metadata includes an invalid serviceIdentifier.
+     * @see SPECIFICATION.md Section 5.2 V3
+     */
+    E_INVALID_SERVICE_IDENTIFIER = "E_INVALID_SERVICE_IDENTIFIER",
+    /**
+     * Injection metadata enables dynamic and ref at the same time.
+     * @see SPECIFICATION.md Section 5.2 V4
+     */
+    E_CONFLICTING_OPTIONS = "E_CONFLICTING_OPTIONS",
+    /**
+     * Consolidated injection metadata is missing a parameter entry.
+     * @see SPECIFICATION.md Section 5.1 V2
+     */
+    E_INCOMPLETE_METADATA = "E_INCOMPLETE_METADATA"
+}

package/dist/exceptions/decorator.exception.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @overview Decorator package exception.
+ * @author AEPKILL
+ * @created 2026-05-09 00:00:00
+ */
+import { CodedException } from "@husky-di/core";
+import type { DecoratorErrorCodeEnum } from "../enums/decorator-error-code.enum";
+export declare class DecoratorException extends CodedException<DecoratorErrorCodeEnum> {
+    /** Internal marker to identify DecoratorException instances across frames. */
+    private __isDecoratorException__;
+    static isDecoratorException(error: unknown): error is DecoratorException;
+}

package/dist/index.cjs

@@ -13,7 +13,7 @@ var __webpack_require__ = {};
 })();
 (()=>{
     __webpack_require__.r = (exports1)=>{
-        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
             value: 'Module'
         });
         Object.defineProperty(exports1, '__esModule', {
@@ -25,27 +25,66 @@ var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     inject: ()=>inject,
+    DecoratorErrorCodeEnum: ()=>decorator_error_code_enum_DecoratorErrorCodeEnum,
+    injectable: ()=>injectable,
+    DecoratorException: ()=>DecoratorException,
     tagged: ()=>tagged,
-    decoratorMiddleware: ()=>decoratorMiddleware,
-    injectable: ()=>injectable
+    decoratorMiddleware: ()=>decoratorMiddleware
 });
-const ParamsMetadataKeyConst = "design:paramtypes";
-const InjectionMetadataKeyConst = "husky-di.injection-metadata";
-const tagged = (metadata)=>(target, _propertyKey, parameterIndex)=>{
-        const parametersMetadata = Reflect.getMetadata(InjectionMetadataKeyConst, target) || [];
+const PARAMS_METADATA_KEY = "design:paramtypes";
+const INJECTION_METADATA_KEY = "husky-di.injection-metadata";
+var decorator_error_code_enum_DecoratorErrorCodeEnum = /*#__PURE__*/ function(DecoratorErrorCodeEnum) {
+    DecoratorErrorCodeEnum["E_DUPLICATE_INJECTABLE"] = "E_DUPLICATE_INJECTABLE";
+    DecoratorErrorCodeEnum["E_NON_CLASS_PARAMETER"] = "E_NON_CLASS_PARAMETER";
+    DecoratorErrorCodeEnum["E_NOT_INJECTABLE"] = "E_NOT_INJECTABLE";
+    DecoratorErrorCodeEnum["E_MISSING_SERVICE_IDENTIFIER"] = "E_MISSING_SERVICE_IDENTIFIER";
+    DecoratorErrorCodeEnum["E_INVALID_SERVICE_IDENTIFIER"] = "E_INVALID_SERVICE_IDENTIFIER";
+    DecoratorErrorCodeEnum["E_CONFLICTING_OPTIONS"] = "E_CONFLICTING_OPTIONS";
+    DecoratorErrorCodeEnum["E_INCOMPLETE_METADATA"] = "E_INCOMPLETE_METADATA";
+    return DecoratorErrorCodeEnum;
+}({});
+const core_namespaceObject = require("@husky-di/core");
+class DecoratorException extends core_namespaceObject.CodedException {
+    static isDecoratorException(error) {
+        return error?.__isDecoratorException__ === true;
+    }
+    constructor(...args){
+        super(...args), this.__isDecoratorException__ = true;
+    }
+}
+const tagged = (metadata)=>{
+    validateInjectionMetadata(metadata);
+    return (target, _propertyKey, parameterIndex)=>{
+        const parametersMetadata = Reflect.getMetadata(INJECTION_METADATA_KEY, target) || [];
         parametersMetadata[parameterIndex] = metadata;
-        Reflect.defineMetadata(InjectionMetadataKeyConst, parametersMetadata, target);
+        Reflect.defineMetadata(INJECTION_METADATA_KEY, parametersMetadata, target);
     };
+};
+function validateInjectionMetadata(metadata) {
+    const serviceIdentifier = metadata?.serviceIdentifier;
+    if (null == serviceIdentifier) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_MISSING_SERVICE_IDENTIFIER, "Injection metadata must include a serviceIdentifier");
+    const isValidServiceIdentifier = "function" == typeof serviceIdentifier || "symbol" == typeof serviceIdentifier || "string" == typeof serviceIdentifier && serviceIdentifier.length > 0;
+    if (!isValidServiceIdentifier) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_INVALID_SERVICE_IDENTIFIER, `Invalid service identifier: ${String(serviceIdentifier)}`);
+    if (metadata.dynamic && metadata.ref) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_CONFLICTING_OPTIONS, 'Cannot use both "dynamic" and "ref" options simultaneously');
+}
 const inject = (serviceIdentifier, options)=>tagged({
         ...options,
         serviceIdentifier
     });
-const InjectionMetadataMap = "undefined" == typeof WeakMap ? Map : WeakMap;
+const InjectionMetadataMap = "u" < typeof WeakMap ? Map : WeakMap;
 const injectionMetadataMap = new InjectionMetadataMap();
+const NON_CLASS_PARAMETER_TYPES = new Set([
+    String,
+    Number,
+    Boolean,
+    BigInt,
+    Symbol,
+    Object
+]);
 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) || [];
+        if (injectionMetadataMap.has(target)) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_DUPLICATE_INJECTABLE, `Class '${target.name}' is already decorated with @Injectable()`);
+        const parametersServiceIdentifiers = Reflect.getMetadata(PARAMS_METADATA_KEY, target) || [];
+        const parametersMetadata = Reflect.getMetadata(INJECTION_METADATA_KEY, target) || [];
         const metadata = [];
         const parametersMetadataLength = Math.max(parametersServiceIdentifiers.length, parametersMetadata.length);
         for(let index = 0; index < parametersMetadataLength; index++){
@@ -54,22 +93,23 @@ const injectable = ()=>(target)=>{
                 continue;
             }
             const serviceIdentifier = parametersServiceIdentifiers[index];
-            if ("function" != typeof serviceIdentifier) throw new Error(`only can inject class type in constructor "${target.name}" parameter #${index}`);
+            if ("function" != typeof serviceIdentifier || NON_CLASS_PARAMETER_TYPES.has(serviceIdentifier)) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_NON_CLASS_PARAMETER, `Constructor '${target.name}' parameter #${index} must be a class type`);
             metadata.push({
                 serviceIdentifier
             });
         }
+        if (metadata.length !== parametersMetadataLength) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_INCOMPLETE_METADATA, `Constructor '${target.name}' has incomplete injection metadata`);
         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;
+        if (isPrimitiveConstructor(provider)) return new 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);
+        if (!parametersMetadata) throw new core_namespaceObject.ResolveException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_NOT_INJECTABLE, `Class '${provider.name}' must be decorated with @Injectable()`, resolveRecord);
         const parameters = parametersMetadata.map((metadata, index)=>{
             const { serviceIdentifier, ...options } = metadata;
             resolveRecord._internalStashCurrent();
@@ -84,16 +124,23 @@ const decoratorMiddleware = {
         return new provider(...parameters);
     }
 };
+function isPrimitiveConstructor(value) {
+    return value === String || value === Number || value === Boolean || value === Symbol || value === BigInt;
+}
+exports.DecoratorErrorCodeEnum = __webpack_exports__.DecoratorErrorCodeEnum;
+exports.DecoratorException = __webpack_exports__.DecoratorException;
 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 === [
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "DecoratorErrorCodeEnum",
+    "DecoratorException",
     "decoratorMiddleware",
     "inject",
     "injectable",
     "tagged"
-].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {
     value: true
 });

package/dist/index.d.ts

@@ -6,5 +6,7 @@
 export * from "./decorators/inject.decorator";
 export * from "./decorators/injectable.decorator";
 export * from "./decorators/tagged.decorator";
+export { DecoratorErrorCodeEnum } from "./enums/decorator-error-code.enum";
+export { DecoratorException } from "./exceptions/decorator.exception";
 export { decoratorMiddleware } from "./middlewares/decorator.middleware";
 export * from "./types/injection-metadata.type";

package/dist/index.js

@@ -1,21 +1,57 @@
-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) || [];
+import { CodedException, RegistrationTypeEnum, ResolveException, ResolveRecordTypeEnum, resolve } from "@husky-di/core";
+const PARAMS_METADATA_KEY = "design:paramtypes";
+const INJECTION_METADATA_KEY = "husky-di.injection-metadata";
+var decorator_error_code_enum_DecoratorErrorCodeEnum = /*#__PURE__*/ function(DecoratorErrorCodeEnum) {
+    DecoratorErrorCodeEnum["E_DUPLICATE_INJECTABLE"] = "E_DUPLICATE_INJECTABLE";
+    DecoratorErrorCodeEnum["E_NON_CLASS_PARAMETER"] = "E_NON_CLASS_PARAMETER";
+    DecoratorErrorCodeEnum["E_NOT_INJECTABLE"] = "E_NOT_INJECTABLE";
+    DecoratorErrorCodeEnum["E_MISSING_SERVICE_IDENTIFIER"] = "E_MISSING_SERVICE_IDENTIFIER";
+    DecoratorErrorCodeEnum["E_INVALID_SERVICE_IDENTIFIER"] = "E_INVALID_SERVICE_IDENTIFIER";
+    DecoratorErrorCodeEnum["E_CONFLICTING_OPTIONS"] = "E_CONFLICTING_OPTIONS";
+    DecoratorErrorCodeEnum["E_INCOMPLETE_METADATA"] = "E_INCOMPLETE_METADATA";
+    return DecoratorErrorCodeEnum;
+}({});
+class DecoratorException extends CodedException {
+    static isDecoratorException(error) {
+        return error?.__isDecoratorException__ === true;
+    }
+    constructor(...args){
+        super(...args), this.__isDecoratorException__ = true;
+    }
+}
+const tagged = (metadata)=>{
+    validateInjectionMetadata(metadata);
+    return (target, _propertyKey, parameterIndex)=>{
+        const parametersMetadata = Reflect.getMetadata(INJECTION_METADATA_KEY, target) || [];
         parametersMetadata[parameterIndex] = metadata;
-        Reflect.defineMetadata(InjectionMetadataKeyConst, parametersMetadata, target);
+        Reflect.defineMetadata(INJECTION_METADATA_KEY, parametersMetadata, target);
     };
+};
+function validateInjectionMetadata(metadata) {
+    const serviceIdentifier = metadata?.serviceIdentifier;
+    if (null == serviceIdentifier) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_MISSING_SERVICE_IDENTIFIER, "Injection metadata must include a serviceIdentifier");
+    const isValidServiceIdentifier = "function" == typeof serviceIdentifier || "symbol" == typeof serviceIdentifier || "string" == typeof serviceIdentifier && serviceIdentifier.length > 0;
+    if (!isValidServiceIdentifier) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_INVALID_SERVICE_IDENTIFIER, `Invalid service identifier: ${String(serviceIdentifier)}`);
+    if (metadata.dynamic && metadata.ref) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_CONFLICTING_OPTIONS, 'Cannot use both "dynamic" and "ref" options simultaneously');
+}
 const inject = (serviceIdentifier, options)=>tagged({
         ...options,
         serviceIdentifier
     });
-const InjectionMetadataMap = "undefined" == typeof WeakMap ? Map : WeakMap;
+const InjectionMetadataMap = "u" < typeof WeakMap ? Map : WeakMap;
 const injectionMetadataMap = new InjectionMetadataMap();
+const NON_CLASS_PARAMETER_TYPES = new Set([
+    String,
+    Number,
+    Boolean,
+    BigInt,
+    Symbol,
+    Object
+]);
 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) || [];
+        if (injectionMetadataMap.has(target)) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_DUPLICATE_INJECTABLE, `Class '${target.name}' is already decorated with @Injectable()`);
+        const parametersServiceIdentifiers = Reflect.getMetadata(PARAMS_METADATA_KEY, target) || [];
+        const parametersMetadata = Reflect.getMetadata(INJECTION_METADATA_KEY, target) || [];
         const metadata = [];
         const parametersMetadataLength = Math.max(parametersServiceIdentifiers.length, parametersMetadata.length);
         for(let index = 0; index < parametersMetadataLength; index++){
@@ -24,11 +60,12 @@ const injectable = ()=>(target)=>{
                 continue;
             }
             const serviceIdentifier = parametersServiceIdentifiers[index];
-            if ("function" != typeof serviceIdentifier) throw new Error(`only can inject class type in constructor "${target.name}" parameter #${index}`);
+            if ("function" != typeof serviceIdentifier || NON_CLASS_PARAMETER_TYPES.has(serviceIdentifier)) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_NON_CLASS_PARAMETER, `Constructor '${target.name}' parameter #${index} must be a class type`);
             metadata.push({
                 serviceIdentifier
             });
         }
+        if (metadata.length !== parametersMetadataLength) throw new DecoratorException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_INCOMPLETE_METADATA, `Constructor '${target.name}' has incomplete injection metadata`);
         injectionMetadataMap.set(target, metadata);
     };
 const decoratorMiddleware = {
@@ -37,8 +74,9 @@ const decoratorMiddleware = {
         const { registration, resolveRecord } = params;
         if (registration.type !== RegistrationTypeEnum["class"]) return next(params);
         const provider = registration.provider;
+        if (isPrimitiveConstructor(provider)) return new 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);
+        if (!parametersMetadata) throw new ResolveException(decorator_error_code_enum_DecoratorErrorCodeEnum.E_NOT_INJECTABLE, `Class '${provider.name}' must be decorated with @Injectable()`, resolveRecord);
         const parameters = parametersMetadata.map((metadata, index)=>{
             const { serviceIdentifier, ...options } = metadata;
             resolveRecord._internalStashCurrent();
@@ -53,4 +91,7 @@ const decoratorMiddleware = {
         return new provider(...parameters);
     }
 };
-export { decoratorMiddleware, inject, injectable, tagged };
+function isPrimitiveConstructor(value) {
+    return value === String || value === Number || value === Boolean || value === Symbol || value === BigInt;
+}
+export { DecoratorException, decoratorMiddleware, decorator_error_code_enum_DecoratorErrorCodeEnum as DecoratorErrorCodeEnum, inject, injectable, tagged };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@husky-di/decorator",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "exports": {
     ".": {
@@ -15,15 +15,15 @@
     "dist"
   ],
   "dependencies": {
-    "@husky-di/core": "1.0.0"
+    "@husky-di/core": "1.1.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.1.3",
-    "@rslib/core": "^0.11.2",
-    "@types/node": "^22.17.0",
+    "@biomejs/biome": "2.4.15",
+    "@rslib/core": "^0.20.1",
+    "@types/node": "^25.5.0",
     "reflect-metadata": "^0.2.2",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.2"
   },
   "peerDependencies": {
     "reflect-metadata": "^0.2.2"