smartdi 0.3.0 → 0.4.1

package/README.md

@@ -1,185 +1,252 @@
-# SmartDI
-
-A simple dependency injector based on decorators.
-
-## Installation
-
-```bash
-npm install smartdi
-```
-
-## Prerequisites
-
-Import the reflect-metadata package at the first line of your application.
-
-```typescript
-import 'reflect-metadata'
-
-// Your code here...
-```
-
-Enable "emitDecoratorMetadata" and "experimentalDecorators" in your tsconfig.json.
-
-```json
-{
-  "emitDecoratorMetadata": true,
-  "experimentalDecorators": true,
-}
-```
-
-## Basic Usage
-
-### Singlton
-
-```typescript
-import 'reflect-metadata'
-import { SmartDI, Injectable, Inject } from 'smartdi';
-
-@Injectable()
-class ExampleService {
-
-  sayHello() {
-    console.log('Hello');
-  }
-
-}
-
-@Injectable()
-class ExampleController {
-
-  @Inject(ExampleService)
-  private readonly myService!: ExampleService;
-
-  sayHello() {
-    this.myService.sayHello();
-  }
-
-}
-
-const controller = SmartDI.get(ExampleController);
-controller.sayHello();
-```
-
-### Factory
-
-```typescript
-import 'reflect-metadata'
-import { SmartDI, Injectable, Inject } from 'smartdi';
-
-interface Shape {
-  area(): number;
-}
-
-// multiple means that the injectable is not singleton.
-@Injectable({name: 'circle', multiple: true})
-class Circle implements Shape {
-
-  private radius: number;
-
-  constructor(radius: number) {
-    this.radius = radius;
-  }
-
-  area(): number {
-    return Math.PI * this.radius * this.radius;
-  }
-
-}
-
-@Injectable({name: 'rect', multiple: true})
-class Rect implements Shape {
-
-  private width: number;
-  private height: number;
-
-  constructor(width: number, height: number) {
-    this.width = width;
-    this.height = height;
-  }
-
-  area(): number {
-    return this.width * this.height;
-  }
-
-}
-
-const type1 = 'circle';
-const args1 = [5]; // radius = 5;
-const shape1 = SmartDI.get<Shape>(type1, ...args1);
-const area1 = shape1.area();
-const type2 = 'rect';
-const args2 = [3, 4]; // width = 3, height = 4;
-const shape2 = SmartDI.get<Shape>(type2, ...args2);
-const area2 = shape2.area();
-
-```
-
-### Circular Dependency
-
-```typescript
-import 'reflect-metadata'
-import { SmartDI, Injectable, Inject } from 'smartdi';
-
-@Injectable()
-class ExampleServiceA {
-
-  @Inject(ExampleServiceB)
-  private readonly exampleServiceB!: ExampleServiceB;
-
-}
-
-@Injectable()
-class ExampleServiceB {
-
-  @Inject(ExampleServiceA)
-  private readonly exampleServiceA!: ExampleServiceA;
-
-}
-
-const serviceA = SmartDI.get(ExampleServiceA);
-const serviceB = SmartDI.get(ExampleServiceB);
-
-```
-
-## APIs
-
-### @Injectable(options?)
-
-Decorate a class as injectable. An "injectable" refers to a class that can be instantiated and injected into other components.
-
- - options: Injectable options.
-
-| name | description |
-| --- | --- |
-| name | The name of the injectable. If not specified, the class name will be used. |
-| multiple | Whether the injectable is a factory. If not specified, the injectable is a singleton. |
-| args | Default arguments of the injectable's constructor. default is []. |
-
-### @Inject(cule, ...args)
-
-Decorate a property as injectable, which will be injected according to the specified clue.
-
- - clue: Name of the injectable or type of the injectable.
- - args: Arguments to pass to constructor.
-
-### @InjectArray(clue, ...args)
-
-Decorate a property as injectable, which will be injected according to the specified clue. 
-The property's type must be Array and the clue must be a type. All injectables that are subtypes of the specified type will be injected.
-
- - clue: Type of the injectable.
- - args: Arguments to pass to constructor.
-
-### SmartDI.get(clue, ...args)
-
-Get the injectable by name or type.
-
- - clue: Name of the injectable or type of the injectable.
- - args: Arguments to pass to constructor.
-
-## Limitations
-
-Injection is processed after construction, so do not access injectable values in the constructor.
-
-## License
-MIT
+# SmartDI
+
+A simple dependency injector based on decorators.
+基于装饰器的简单依赖注入器。
+
+## Installation | 安装
+
+```bash
+npm install smartdi
+```
+
+## Prerequisites | 先决条件
+
+Import the `reflect-metadata` package on the first line of your application.
+在应用程序的第一行导入 `reflect-metadata` 包。
+
+```typescript
+import 'reflect-metadata'
+
+// Your code here...
+```
+
+Enable `emitDecoratorMetadata` and `experimentalDecorators` in your `tsconfig.json`.
+在 `tsconfig.json` 中启用 `emitDecoratorMetadata` 和 `experimentalDecorators`。
+
+```json
+{
+  "emitDecoratorMetadata": true,
+  "experimentalDecorators": true,
+}
+```
+
+## Basic Usage | 基本用法
+
+### Singleton | 单例
+
+```typescript
+import 'reflect-metadata'
+import { SmartDI, Injectable, Inject } from 'smartdi';
+
+@Injectable()
+class ExampleService {
+
+  sayHello() {
+    console.log('Hello');
+  }
+
+}
+
+@Injectable()
+class ExampleController {
+
+  @Inject(ExampleService)
+  private readonly myService!: ExampleService;
+
+  sayHello() {
+    this.myService.sayHello();
+  }
+
+}
+
+const controller = SmartDI.get(ExampleController);
+controller.sayHello();
+```
+
+### Factory | 工厂模式
+
+```typescript
+import 'reflect-metadata'
+import { SmartDI, Injectable, Inject } from 'smartdi';
+
+interface Shape {
+  area(): number;
+}
+
+// multiple means that the injectable is not singleton.
+@Injectable({name: 'circle', multiple: true})
+class Circle implements Shape {
+
+  private radius: number;
+
+  constructor(radius: number) {
+    this.radius = radius;
+  }
+
+  area(): number {
+    return Math.PI * this.radius * this.radius;
+  }
+
+}
+
+@Injectable({name: 'rect', multiple: true})
+class Rect implements Shape {
+
+  private width: number;
+  private height: number;
+
+  constructor(width: number, height: number) {
+    this.width = width;
+    this.height = height;
+  }
+
+  area(): number {
+    return this.width * this.height;
+  }
+
+}
+
+const type1 = 'circle';
+const args1 = [5]; // radius = 5;
+const shape1 = SmartDI.get<Shape>(type1, ...args1);
+const area1 = shape1.area();
+const type2 = 'rect';
+const args2 = [3, 4]; // width = 3, height = 4;
+const shape2 = SmartDI.get<Shape>(type2, ...args2);
+const area2 = shape2.area();
+
+```
+
+### Circular Dependency | 循环依赖
+
+```typescript
+import 'reflect-metadata'
+import { SmartDI, Injectable, Inject } from 'smartdi';
+
+@Injectable()
+class ExampleServiceA {
+
+  @Inject(ExampleServiceB)
+  private readonly exampleServiceB!: ExampleServiceB;
+
+}
+
+@Injectable()
+class ExampleServiceB {
+
+  @Inject(ExampleServiceA)
+  private readonly exampleServiceA!: ExampleServiceA;
+
+}
+
+const serviceA = SmartDI.get(ExampleServiceA);
+const serviceB = SmartDI.get(ExampleServiceB);
+
+```
+
+## APIs | 接口
+
+### @Injectable(options?)
+
+Decorate a class as injectable. An "injectable" refers to a class that can be instantiated and injected into other components.
+将类装饰为 `injectable`。`injectable` 类是指可以被实例化并注入到其他组件中的类。
+
+ - options: Injectable options.
+ - options: 可注入选项。
+
+| name \| 字段名 | description \| 描述 |
+| --- | --- |
+| name | The name of the `injectable`. If not specified, the class name will be used.<br>`injectable` 的名称。若未指定，则使用类名。 |
+| multiple | Whether the `injectable` is a factory. If not specified, the `injectable` is a singleton.<br>`injectable` 的是否为工厂模式。若未指定，则为单例。 |
+| args | Default arguments of the `injectable`'s constructor. Defaults to [].<br>`injectable` 的构造函数的默认参数。默认为 []。 |
+
+### @Inject(clue, ...args)
+
+Decorate a property as a candidate for injection, which will be injected according to the specified clue.
+将属性装饰为待注入的，将根据指定的线索进行注入。
+
+ - clue: Name, type, or abstract class of `injectable`.
+ - clue: `injectable` 的名称、类型或抽象类。
+ - args: Arguments to pass to constructor.
+ - args: 传递给构造函数的参数。
+
+### @InjectArray(clue, ...args)
+
+Decorate a property as a candidate for injection, which will be injected according to the specified clue.
+将属性装饰为待注入的，将根据指定的线索进行注入。
+The property's type must be `Array` and the clue must be a type. All injectables that are subtypes of the specified type will be injected.
+属性的类型必须为 `Array`，且线索必须为 `injectable` 的类型。指定 `injectable` 类型的所有子类的 `injectable` 都将被注入。
+
+ - clue: Type or abstract class of the `injectable`.
+ - clue: `injectable` 的类型或抽象类。
+ - args: Arguments to pass to constructor.
+ - args:传递给构造函数的参数。
+
+### SmartDI.get(clue, ...args)
+
+Get an instance of the `injectable` by name or type.
+根据名称或类型获取 `injectable` 的实例。
+
+ - clue: Name of the `injectable` or type of the injectable.
+ - clue:  `injectable` 的名称或类型。
+ - args: Arguments to pass to constructor.
+ - args: 传递给构造函数的参数。
+
+### SmartDI.register(clazz, options?)
+
+Programmatically register a class as an `injectable`, serving as an alternative to the `@Injectable` decorator.
+以编程方式注册类为 `injectable`，作为 `@Injectable` 装饰器的替代方案。
+
+ - clazz: Class to register.
+ - clazz: 要注册的类。
+ - options: Same as `@Injectable` options.
+ - options: 与 `@Injectable` 的选项相同。
+
+### SmartDI.getArray(clue, ...args)
+
+Get all registered subtypes of the specified type as an array.
+以数组形式获取指定类型的所有已注册子类型的实例。
+
+ - clue: Type or abstract class of the `injectable`.
+ - clue: `injectable` 的类型或抽象类。
+ - args: Arguments to pass to constructor.
+ - args: 传递给构造函数的参数。
+
+### SmartDI.initialize()
+
+Create all singleton instances and invoke all methods decorated with `@PostConstruct`. Supports both synchronous and asynchronous lifecycle hooks.
+创建所有单例实例，并调用所有使用 `@PostConstruct` 装饰的方法。支持同步和异步的生命周期钩子。
+
+### SmartDI.uninitialize()
+
+Clear all singleton instances in reverse registration order, invoking the `@PreDestroy` decorated methods for each.
+按注册逆序清空所有单例实例，并调用使用 `@PreDestroy` 装饰的方法。
+
+### @PostConstruct()
+
+Decorate a method as a lifecycle hook, which will be invoked when `SmartDI.initialize()` is called.
+将方法装饰为生命周期钩子，在调用 `SmartDI.initialize()` 时执行。
+
+### @PreDestroy()
+
+Decorate a method as a lifecycle hook, which will be invoked when `SmartDI.uninitialize()` is called.
+将方法装饰为生命周期钩子，在调用 `SmartDI.uninitialize()` 时执行。
+
+## Inheritance | 继承
+
+Injected properties and lifecycle hooks declared on base classes apply to subclass instances. Decorators write only the metadata of the class they decorate; the prototype chain is merged when an instance is created.
+
+基类声明的注入属性与生命周期钩子会对子类实例生效。装饰器只写入所在类自己的元数据，实例创建时再沿原型链合并。
+
+- Injected properties are merged base-first, so a subclass property with the same name overrides the base one.
+  注入属性按基类在前合并，子类同名字段覆盖基类字段。
+- `@PostConstruct` / `@PreDestroy` methods run once per instance, base-class hooks first.
+  每个实例的 `@PostConstruct` / `@PreDestroy` 各执行一次，基类钩子在前。
+
+## Limitations
+
+Injection is processed after construction, so do not access injectable values in the constructor.
+注入是在构造函数执行之后再进行处理的，因此不要在构造函数中访问可注入的值。
+
+## License
+MIT

package/index.d.ts

@@ -12,8 +12,12 @@ export declare abstract class SmartDI {
     static get<T>(clue: Class<T> | AbstractClass<T>, ...args: any[]): T;
     static get<T>(name: string, ...args: any[]): T;
     static getArray<T>(clue: Class<T> | AbstractClass<T>, ...args: any[]): T[];
+    static initialize(): Promise<void>;
+    static uninitialize(): Promise<void>;
 }
 export declare function Injectable(options?: InjectableOptions): ClassDecorator;
 export declare function Inject(constructor: Class<any> | AbstractClass<any>, ...args: any[]): PropertyDecorator;
 export declare function Inject(name: string, ...args: any[]): PropertyDecorator;
 export declare function InjectArray(constructor: Class<any> | AbstractClass<any>, ...args: any[]): PropertyDecorator;
+export declare function PostConstruct(): MethodDecorator;
+export declare function PreDestroy(): MethodDecorator;

package/index.js

@@ -1,8 +1,82 @@
 "use strict";
-var _a;
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var _a, _b;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InjectArray = exports.Inject = exports.Injectable = exports.SmartDI = void 0;
+exports.SmartDI = void 0;
+exports.Injectable = Injectable;
+exports.Inject = Inject;
+exports.InjectArray = InjectArray;
+exports.PostConstruct = PostConstruct;
+exports.PreDestroy = PreDestroy;
 const $registry = Symbol('registry');
+const $singletons = Symbol('singletons');
+const METADATA_INJECTS = 'smartdi:injects';
+const METADATA_POST_CONSTRUCT = 'smartdi:post-construct';
+const METADATA_PRE_DESTROY = 'smartdi:pre-destroy';
+function prototypeChain(instance) {
+    const chain = [];
+    let proto = Object.getPrototypeOf(instance);
+    while (proto && proto !== Object.prototype) {
+        chain.push(proto);
+        proto = Object.getPrototypeOf(proto);
+    }
+    return chain.reverse();
+}
+function isSubclass(sub, sup) {
+    let proto = Object.getPrototypeOf(sub);
+    while (proto) {
+        if (proto === sup)
+            return true;
+        proto = Object.getPrototypeOf(proto);
+    }
+    return false;
+}
+const injectsCache = new WeakMap();
+function collectInjects(instance) {
+    const prototype = Object.getPrototypeOf(instance);
+    let merged = injectsCache.get(prototype);
+    if (merged)
+        return merged;
+    merged = {};
+    for (const proto of prototypeChain(instance))
+        Object.assign(merged, Reflect.getOwnMetadata(METADATA_INJECTS, proto));
+    injectsCache.set(prototype, merged);
+    return merged;
+}
+function collectLifecycle(instance, key) {
+    var _c;
+    const methods = [];
+    const seen = new Set();
+    for (const proto of prototypeChain(instance)) {
+        for (const method of (_c = Reflect.getOwnMetadata(key, proto)) !== null && _c !== void 0 ? _c : []) {
+            if (seen.has(method))
+                continue;
+            seen.add(method);
+            methods.push(method);
+        }
+    }
+    return methods;
+}
+function defineInject(target, prop, item) {
+    var _c;
+    const injects = (_c = Reflect.getOwnMetadata(METADATA_INJECTS, target)) !== null && _c !== void 0 ? _c : {};
+    injects[prop] = item;
+    Reflect.defineMetadata(METADATA_INJECTS, injects, target);
+}
+function appendLifecycle(target, key, method) {
+    var _c;
+    const methods = (_c = Reflect.getOwnMetadata(key, target)) !== null && _c !== void 0 ? _c : [];
+    methods.push(method);
+    Reflect.defineMetadata(key, methods, target);
+}
 class SmartDI {
     static register(clazz, options) {
         const name = (options === null || options === void 0 ? void 0 : options.name) || clazz.name;
@@ -10,13 +84,16 @@ class SmartDI {
         const singleton = !(options === null || options === void 0 ? void 0 : options.multiple);
         if (SmartDI[$registry][name])
             throw new Error(`Duplicated injectable name '${name}'!`);
-        SmartDI[$registry][name] = {
+        const item = {
             name,
             class: clazz,
             args: args,
             singleton,
             instance: undefined
         };
+        if (singleton)
+            SmartDI[$singletons].push(item);
+        SmartDI[$registry][name] = item;
     }
     static get(clue, ...args) {
         return SmartDI.internalGet(clue, new Set(), ...args);
@@ -24,6 +101,50 @@ class SmartDI {
     static getArray(clue, ...args) {
         return SmartDI.internalGetArray(clue, new Set(), ...args);
     }
+    static initialize() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const instances = [];
+            for (const item of SmartDI[$singletons])
+                instances.push(SmartDI.obtainInstance(item, new Set()));
+            const promises = [];
+            for (const instance of instances) {
+                const methods = collectLifecycle(instance, METADATA_POST_CONSTRUCT);
+                if (!methods.length)
+                    continue;
+                for (const method of methods) {
+                    const result = instance[method]();
+                    if (result instanceof Promise)
+                        promises.push(result);
+                }
+            }
+            if (!promises.length)
+                return;
+            yield Promise.all(promises);
+        });
+    }
+    static uninitialize() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const items = [...SmartDI[$singletons]].reverse();
+            const promises = [];
+            for (const item of items) {
+                const instance = item.instance;
+                if (!instance)
+                    continue;
+                item.instance = undefined;
+                const methods = collectLifecycle(instance, METADATA_PRE_DESTROY);
+                if (!methods.length)
+                    continue;
+                for (const method of methods) {
+                    const result = instance[method]();
+                    if (result instanceof Promise)
+                        promises.push(result);
+                }
+            }
+            if (!promises.length)
+                return;
+            yield Promise.all(promises);
+        });
+    }
     static internalGet(clue, creatings, ...args) {
         let constructor, name;
         if (typeof clue === 'function') {
@@ -36,14 +157,14 @@ class SmartDI {
         }
         let item = SmartDI[$registry][name];
         if (!item && constructor)
-            item = SmartDI.resovleOneByConstructor(constructor);
+            item = SmartDI.resolveOneByConstructor(constructor);
         if (!item)
             throw new Error(`Can not resolve injectable '${name}'!`);
         return SmartDI.obtainInstance(item, creatings, ...args);
     }
     static internalGetArray(constructor, creatings, ...args) {
-        const items = SmartDI.resovleByConstructor(constructor);
-        if (items.length == 0)
+        const items = SmartDI.resolveByConstructor(constructor);
+        if (items.length === 0)
             throw new Error(`Can not resolve injectable '${constructor.name}'!`);
         const instances = [];
         for (const item of items)
@@ -53,70 +174,78 @@ class SmartDI {
     static obtainInstance(item, creatings, ...args) {
         if (item.instance)
             return item.instance;
-        if (args.length == 0)
+        if (args.length === 0)
             args = item.args;
         const instance = new item.class(...args);
         if (item.singleton)
             item.instance = instance;
-        const injects = Reflect.getMetadata('smartdi:injects', instance);
-        if (!injects)
+        const injects = collectInjects(instance);
+        const injectKeys = Reflect.ownKeys(injects);
+        if (!injectKeys.length)
             return instance;
         if (!item.singleton && creatings.has(item.name))
             throw new Error('Circular dependency detected!');
         creatings.add(item.name);
-        for (const prop of Object.keys(injects))
-            instance[prop] = injects[prop].array
-                ? SmartDI.internalGetArray(injects[prop].clue, creatings, ...injects[prop].args)
-                : SmartDI.internalGet(injects[prop].clue, creatings, ...injects[prop].args);
+        try {
+            for (const prop of injectKeys)
+                instance[prop] = injects[prop].array
+                    ? SmartDI.internalGetArray(injects[prop].clue, creatings, ...injects[prop].args)
+                    : SmartDI.internalGet(injects[prop].clue, creatings, ...injects[prop].args);
+        }
+        catch (e) {
+            if (item.singleton)
+                item.instance = undefined;
+            throw e;
+        }
         return instance;
     }
-    static resovleByConstructor(constructor) {
-        let matched = [];
-        function isSubclass(sub, sup) {
-            let proto = Object.getPrototypeOf(sub);
-            while (proto) {
-                if (proto === sup)
-                    return true;
-                proto = Object.getPrototypeOf(proto);
-            }
-            return false;
-        }
+    static resolveByConstructor(constructor) {
+        const matched = [];
         for (const item of Object.values(SmartDI[$registry])) {
-            if (!isSubclass(item.class, constructor))
-                continue;
-            matched.push(item);
+            if (isSubclass(item.class, constructor))
+                matched.push(item);
         }
         return matched;
     }
-    static resovleOneByConstructor(constructor) {
-        const items = SmartDI.resovleByConstructor(constructor);
-        if (items.length > 1)
-            throw new Error(`Multiple injectable classes found for '${constructor.name}': ${items.map(item => item.name).join(', ')}`);
-        return items[0];
+    static resolveOneByConstructor(constructor) {
+        const matched = [];
+        for (const item of Object.values(SmartDI[$registry])) {
+            if (item.class === constructor)
+                return item;
+            if (isSubclass(item.class, constructor))
+                matched.push(item);
+        }
+        if (matched.length > 1)
+            throw new Error(`Multiple injectable classes found for '${constructor.name}': ${matched.map(item => item.name).join(', ')}`);
+        return matched[0];
     }
 }
 exports.SmartDI = SmartDI;
-_a = $registry;
+_a = $registry, _b = $singletons;
 SmartDI[_a] = {};
+SmartDI[_b] = [];
 function Injectable(options) {
     return (target) => {
         SmartDI.register(target, options);
     };
 }
-exports.Injectable = Injectable;
 function Inject(clue, ...args) {
     return function (target, prop) {
-        let injects = Reflect.getMetadata('smartdi:injects', target) || {};
-        injects[prop] = { array: false, clue, args };
-        Reflect.defineMetadata('smartdi:injects', injects, target);
+        defineInject(target, prop, { array: false, clue, args });
     };
 }
-exports.Inject = Inject;
 function InjectArray(clue, ...args) {
     return function (target, prop) {
-        let injects = Reflect.getMetadata('smartdi:injects', target) || {};
-        injects[prop] = { array: true, clue, args };
-        Reflect.defineMetadata('smartdi:injects', injects, target);
+        defineInject(target, prop, { array: true, clue, args });
+    };
+}
+function PostConstruct() {
+    return function (target, key, _descriptor) {
+        appendLifecycle(target, METADATA_POST_CONSTRUCT, key);
+    };
+}
+function PreDestroy() {
+    return function (target, key, _descriptor) {
+        appendLifecycle(target, METADATA_PRE_DESTROY, key);
     };
 }
-exports.InjectArray = InjectArray;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "smartdi",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "A simple dependency injector based on decorators.",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest"
   },
   "keywords": [
     "DI",
@@ -27,7 +28,11 @@
   },
   "homepage": "https://github.com/iwares/smartdi#readme",
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.13.10",
-    "reflect-metadata": "^0.2.2"
+    "jest": "^30.5.2",
+    "reflect-metadata": "^0.2.2",
+    "ts-jest": "^29.4.15",
+    "typescript": "^6.0.3"
   }
-}
+}