@amriogit/injector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 amrio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @amriogit/injector
+
+轻量 DI（依赖注入）容器。零外部依赖，可在 Node.js、浏览器、SSR 中运行。
+
+## 安装
+
+```bash
+npm install @amriogit/injector
+```
+
+## 使用
+
+### 核心 DI
+
+```ts
+import { Injector, BaseService, InjectionToken } from '@amriogit/injector'
+
+// 定义 Service
+class Logger extends BaseService {
+  log = (msg: string) => console.log(msg)
+}
+
+class UserService extends BaseService {
+  private logger = this.$inject(Logger)  // 声明依赖
+  private db = this.$inject(DB_POOL)     // InjectionToken 也支持
+
+  state = reactive({ users: [] as User[] })
+
+  onInit() {
+    // 依赖已就绪，做初始化
+  }
+
+  fetchUsers = async () => { /* ... */ }
+}
+
+// 创建容器
+const injector = new Injector()
+
+// 覆写实现
+injector.provide(Logger, MockLogger)
+
+// 获取实例（自动实例化 + 单例）
+const userService = injector.inject(UserService)
+```
+
+### Vue 3 集成
+
+```ts
+import { createApp } from 'vue'
+import { ServicePlugin, useInject, useProvide } from '@amriogit/injector/vue'
+
+// 安装插件
+createApp(App)
+  .use(ServicePlugin)
+  .mount('#app')
+
+// 组件中注入 Service
+const userService = useInject(UserService)
+
+// 为子树覆写实现
+useProvide(UserService, MockUserService)
+```
+
+## 特性
+
+- **零依赖** — 纯 TypeScript，无运行时依赖
+- **无全局单例** — 每个应用/请求创建独立 Injector
+- **自动实例化** — 类 token 首次 `inject()` 时自动创建，无需手动注册
+- **类型安全** — `provide()` 函数重载在编译期防止错误的实现类型
+- **InjectionToken** — 为非类注入（配置、缓存等）提供类型安全
+- **生命周期** — `onInit()` 钩子在依赖就绪后调用
+- **SSR 兼容** — 无 DOM 依赖，InjectionToken 可序列化
+
+## 测试
+
+```bash
+npm test
+```

package/dist/injector-vue.d.ts

@@ -0,0 +1,41 @@
+import { Injector, InjectionToken, type Token } from './injector';
+/**
+ * Vue 3 插件。创建作用域 Injector 并通过 provide/inject
+ * 使其对所有后代组件可用。
+ *
+ * 用法：
+ * ```ts
+ * createApp(App).use(ServicePlugin).mount('#app')
+ * ```
+ *
+ * 可通过第二个参数传入 setup 回调，在 Service 自动实例化前
+ * 为 Injector 提供基础设施 token（如拦截器集合）：
+ * ```ts
+ * app.use(ServicePlugin, {
+ *   setup(injector) {
+ *     injector.provide(RESPONSE_INTERCEPTORS, new Set())
+ *   }
+ * })
+ * ```
+ *
+ * Service 在首次 useInject() 时自动实例化。
+ * useProvide() 仅用于为某个子树覆写实现。
+ */
+export declare const ServicePlugin: (app: any, options?: {
+    setup?: (injector: Injector) => void;
+}) => void;
+/** 从 Vue 作用域 Injector 中注入 Service 实例 */
+export declare function useInject<T>(token: Token<T>): T;
+/**
+ * 为组件子树提供/覆写 Service 绑定。
+ *
+ * 重载与 injector.provide() 保持一致，提供编译期类型安全：
+ * - 类 token 需要构造器（子类）实现
+ * - InjectionToken token 接受值类型
+ */
+export declare function useProvide<T>(token: {
+    new (...args: any[]): T;
+}, implementation: {
+    new (...args: any[]): T;
+}): void;
+export declare function useProvide<T>(token: InjectionToken<T>, implementation: T): void;

package/dist/injector-vue.js

@@ -0,0 +1,60 @@
+/**
+ * Vue 3 集成层，用于对接共享 DI 核心。
+ * 与 injector.ts 分离，使服务端不打包 Vue。
+ *
+ * SSR 行为：
+ * - ServicePlugin 通过 app.provide/use 创建每个应用的 Injector（无全局状态）
+ * - SSR 中每个 createApp() 调用获得独立的 Injector
+ * - useInject() 和 useProvide() 仅在 Vue setup() 内可用 —
+ *   在组件上下文外调用将抛出明确错误
+ *
+ * @module injector-vue
+ */
+import { inject } from 'vue';
+import { Injector } from './injector';
+/** 从 Vue DI 树中访问 Injector 的注入 key */
+const INJECTOR_KEY = Symbol('injector');
+/**
+ * Vue 3 插件。创建作用域 Injector 并通过 provide/inject
+ * 使其对所有后代组件可用。
+ *
+ * 用法：
+ * ```ts
+ * createApp(App).use(ServicePlugin).mount('#app')
+ * ```
+ *
+ * 可通过第二个参数传入 setup 回调，在 Service 自动实例化前
+ * 为 Injector 提供基础设施 token（如拦截器集合）：
+ * ```ts
+ * app.use(ServicePlugin, {
+ *   setup(injector) {
+ *     injector.provide(RESPONSE_INTERCEPTORS, new Set())
+ *   }
+ * })
+ * ```
+ *
+ * Service 在首次 useInject() 时自动实例化。
+ * useProvide() 仅用于为某个子树覆写实现。
+ */
+export const ServicePlugin = (app, options) => {
+    const injector = new Injector();
+    options?.setup?.(injector);
+    app.provide(INJECTOR_KEY, injector);
+    app.config.globalProperties.$inject = injector.inject.bind(injector);
+    app.onUnmount(() => {
+        injector.reset();
+    });
+};
+/** 从 Vue 作用域 Injector 中注入 Service 实例 */
+export function useInject(token) {
+    const injector = inject(INJECTOR_KEY);
+    if (!injector)
+        throw new Error('[injector] ServicePlugin not installed — call app.use(ServicePlugin)');
+    return injector.inject(token);
+}
+export function useProvide(token, implementation) {
+    const injector = inject(INJECTOR_KEY);
+    if (!injector)
+        throw new Error('[injector] ServicePlugin not installed — call app.use(ServicePlugin)');
+    injector.provide(token, implementation);
+}

package/dist/injector.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 轻量 DI（依赖注入）容器。
+ *
+ * 架构决策：
+ * - 零外部依赖 — 可在 Node.js、浏览器、SSR 中运行
+ * - 无全局单例 — 每个应用或每个请求创建一个 Injector
+ * - 类 token 首次 inject() 时自动实例化 — 无需手动注册
+ * - provide() 使用函数重载：编译期防止非构造器实现传入类 token
+ * - InjectionToken<T> 为非类注入（值、缓存、配置）提供类型安全
+ * - onInit() 生命周期钩子在构造器注入的依赖就绪后调用
+ *
+ * SSR / Node.js 兼容：
+ * - 无 DOM、无 Node 内置模块导入
+ * - 全部同步逻辑 — 无异步初始化
+ * - InjectionToken 可完全序列化（toString()），支持 SSR 水合
+ * - 每个 Injector 实例完全隔离 — 无跨请求污染
+ */
+export declare class InjectionToken<T> {
+    readonly description: string;
+    private defaultFactory?;
+    constructor(description: string, defaultFactory?: (() => T) | undefined);
+    hasDefault(): boolean;
+    createDefault(): T;
+    toString(): string;
+}
+export type Token<T> = {
+    new (...args: any[]): T;
+} | InjectionToken<T>;
+type RawToken = {
+    new (...args: any[]): any;
+} | InjectionToken<any>;
+export declare class Injector {
+    private bindings;
+    private instances;
+    /**
+     * 覆写 token 对应的实现。
+     *
+     * 两个重载在编译期保障类型安全：
+     * 1. 类 token → implementation 必须是构造器（子类），不能是普通对象
+     * 2. InjectionToken → implementation 必须是对应类型的值
+     *
+     * 必须在首次 inject() 之前调用才生效。
+     * 一旦 inject() 缓存了实例，provide() 对该 token 变成空操作。
+     *
+     * @returns this — 支持链式调用
+     */
+    provide<T>(token: {
+        new (...args: any[]): T;
+    }, implementation: {
+        new (...args: any[]): T;
+    }): this;
+    provide<T>(token: InjectionToken<T>, implementation: T): this;
+    /**
+     * 根据 token 解析服务或值。
+     *
+     * 按 token 类型不同行为：
+     * - 类 token 无 provide() → 自动实例化并缓存
+     * - 类 token 有 provide() → 实例化 provided 的实现并缓存（每个 Injector 单例）
+     * - InjectionToken 无 provide() → 使用默认值（如有），否则抛出 Error
+     * - InjectionToken 有 provide() → 返回 provided 的值
+     *
+     * 返回值在当前 Injector 内始终是单例，后续调用返回缓存实例。
+     */
+    inject<T>(token: Token<T>): T;
+    private _instantiate;
+    /** 检查 token 是否有绑定（不检查实例缓存） */
+    has(token: RawToken): boolean;
+    /** 清除所有绑定和缓存实例（会先调用所有缓存实例的 onDestroy） */
+    reset(): void;
+    /** 销毁指定 token 的缓存实例（调用 onDestroy 后移出缓存，下次 inject 重新创建） */
+    destroy<T>(token: Token<T>): void;
+}
+/**
+ * 所有可注入 Service 的基类。
+ *
+ * - 构造函数唯一参数为 Injector
+ * - 子类通过箭头函数字段声明依赖：`svc = this.$inject(Dep)`
+ * - onInit() 由 Injector 在实例构造并缓存后调用（而非构造函数内）
+ *
+ * @example
+ * ```ts
+ * class UserService extends BaseService {
+ *   private api = this.$inject(ApiService)
+ *   private db = this.$inject(DB_POOL)
+ *   state = reactive({ ... })
+ *   fetchUsers = async () => { ... }
+ * }
+ * ```
+ */
+export declare abstract class BaseService {
+    protected $injector: Injector;
+    constructor(injector: Injector);
+    /** 从父级 Injector 解析依赖 */
+    protected $inject<T>(token: Token<T>): T;
+    /**
+     * 生命周期钩子，在构造器注入的依赖全部就绪后调用。
+     * 不要在构造函数中做初始化逻辑，应使用 onInit()。
+     */
+    onInit?(): void;
+    onDestroy?(): void;
+}
+export {};

package/dist/injector.js

@@ -0,0 +1,137 @@
+/**
+ * 轻量 DI（依赖注入）容器。
+ *
+ * 架构决策：
+ * - 零外部依赖 — 可在 Node.js、浏览器、SSR 中运行
+ * - 无全局单例 — 每个应用或每个请求创建一个 Injector
+ * - 类 token 首次 inject() 时自动实例化 — 无需手动注册
+ * - provide() 使用函数重载：编译期防止非构造器实现传入类 token
+ * - InjectionToken<T> 为非类注入（值、缓存、配置）提供类型安全
+ * - onInit() 生命周期钩子在构造器注入的依赖就绪后调用
+ *
+ * SSR / Node.js 兼容：
+ * - 无 DOM、无 Node 内置模块导入
+ * - 全部同步逻辑 — 无异步初始化
+ * - InjectionToken 可完全序列化（toString()），支持 SSR 水合
+ * - 每个 Injector 实例完全隔离 — 无跨请求污染
+ */
+export class InjectionToken {
+    constructor(description, defaultFactory) {
+        this.description = description;
+        this.defaultFactory = defaultFactory;
+    }
+    hasDefault() {
+        return this.defaultFactory !== undefined;
+    }
+    createDefault() {
+        return this.defaultFactory();
+    }
+    toString() {
+        return `InjectionToken(${this.description})`;
+    }
+}
+export class Injector {
+    constructor() {
+        this.bindings = new Map();
+        this.instances = new Map();
+    }
+    provide(token, implementation) {
+        this.bindings.set(token, implementation);
+        return this;
+    }
+    /**
+     * 根据 token 解析服务或值。
+     *
+     * 按 token 类型不同行为：
+     * - 类 token 无 provide() → 自动实例化并缓存
+     * - 类 token 有 provide() → 实例化 provided 的实现并缓存（每个 Injector 单例）
+     * - InjectionToken 无 provide() → 使用默认值（如有），否则抛出 Error
+     * - InjectionToken 有 provide() → 返回 provided 的值
+     *
+     * 返回值在当前 Injector 内始终是单例，后续调用返回缓存实例。
+     */
+    inject(token) {
+        const existing = this.instances.get(token);
+        if (existing !== undefined)
+            return existing;
+        const binding = this.bindings.get(token);
+        if (binding === undefined) {
+            if (typeof token === 'function') {
+                return this._instantiate(token, token);
+            }
+            // InjectionToken — 有默认值则使用，否则抛异常
+            if (token.hasDefault()) {
+                const val = token.createDefault();
+                this.instances.set(token, val);
+                return val;
+            }
+            throw new Error(`Service not registered: ${token}`);
+        }
+        if (typeof binding !== 'function' || !binding.prototype) {
+            this.instances.set(token, binding);
+            return binding;
+        }
+        return this._instantiate(token, binding);
+    }
+    _instantiate(token, Class) {
+        const instance = new Class(this);
+        this.instances.set(token, instance);
+        if (typeof instance.onInit === 'function') {
+            ;
+            instance.onInit();
+        }
+        return instance;
+    }
+    /** 检查 token 是否有绑定（不检查实例缓存） */
+    has(token) {
+        return this.bindings.has(token);
+    }
+    /** 清除所有绑定和缓存实例（会先调用所有缓存实例的 onDestroy） */
+    reset() {
+        for (const [, instance] of this.instances) {
+            if (typeof instance === 'object' && instance !== null && typeof instance.onDestroy === 'function') {
+                ;
+                instance.onDestroy();
+            }
+        }
+        this.bindings.clear();
+        this.instances.clear();
+    }
+    /** 销毁指定 token 的缓存实例（调用 onDestroy 后移出缓存，下次 inject 重新创建） */
+    destroy(token) {
+        const instance = this.instances.get(token);
+        if (instance !== undefined && typeof instance === 'object' && instance !== null && typeof instance.onDestroy === 'function') {
+            ;
+            instance.onDestroy();
+        }
+        this.instances.delete(token);
+    }
+}
+/**
+ * 所有可注入 Service 的基类。
+ *
+ * - 构造函数唯一参数为 Injector
+ * - 子类通过箭头函数字段声明依赖：`svc = this.$inject(Dep)`
+ * - onInit() 由 Injector 在实例构造并缓存后调用（而非构造函数内）
+ *
+ * @example
+ * ```ts
+ * class UserService extends BaseService {
+ *   private api = this.$inject(ApiService)
+ *   private db = this.$inject(DB_POOL)
+ *   state = reactive({ ... })
+ *   fetchUsers = async () => { ... }
+ * }
+ * ```
+ */
+export class BaseService {
+    constructor(injector) {
+        if (!injector)
+            throw new Error('BaseService requires an Injector instance');
+        this.$injector = injector;
+    }
+    /** 从父级 Injector 解析依赖 */
+    $inject(token) {
+        return this.$injector.inject(token);
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@amriogit/injector",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "轻量 DI 容器 — Injector, BaseService, InjectionToken。零外部依赖，支持 SSR，Vue 集成。",
+  "keywords": ["di", "dependency-injection", "injector", "typescript", "vue", "ssr"],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amriogit/injector.git"
+  },
+  "bugs": {
+    "url": "https://github.com/amriogit/injector/issues"
+  },
+  "homepage": "https://github.com/amriogit/injector#readme",
+  "main": "./dist/injector.js",
+  "types": "./dist/injector.d.ts",
+  "exports": {
+    ".": "./dist/injector.js",
+    "./vue": "./dist/injector-vue.js"
+  },
+  "files": ["dist"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "vue": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm test && npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "vue": "^3.5.34"
+  },
+  "license": "MIT"
+}