lianhanlin-modular weekly downloads statistics

Path-IoC (lianhanlin-modular)

Spring 有 Bean，Nest 有 Provider，Path-IoC 有 Mesh。

🚀 像 lodash-es 一样纯粹通用的 TypeScript/JavaScript 路径依赖查找引擎 (IoC-DL)

✨ JavaScript/TypeScript 动态语言模块控制反转的唯一正解

📦 项目标识与包名对照 (Identity Mapping)：

- NPM 安装包名：lianhanlin-modular (npm i lianhanlin-modular) - 核心架构思想：Path-IoC（基于物理路径契约的控制反转与依赖查找引擎） - 核心物理单元：Mesh（对应 Spring 中的 Bean） - 虚拟模块导入：virtual:modular-container（构建插件在内存中全自动收集导出的 Mesh 注册表）

💡 什么是 Path-IoC (IoC-DL)？：告别原始 import 泥潭与 Java 式重型黑盒 DI（如 NestJS）在 JS 异步生态里的死锁/反射包袱。Path-IoC 采用 Dependency Lookup (依赖查找) 范式——路径即契约，静态图预编译，原生 async/await 支持。零反射、零概念包袱，组件面向 container 极简解构。

🌟 典范应用模式直达：

- 🌐 前端全动态路由自动聚合 (allRoutes) - 📦 后端 ORM 实体自动收集与路径类型抽取 (entities) - 🚀 终态收敛启动器 (bootstrap)

⚡ 5 秒上手 (5-Second Quick Start)

1. 插件配置（以 Vite 为例；Webpack / Rspack 配置 👉 点击跳转）

vite.config.ts：

2. 目录结构

3. 项目编译构建入口 (src/index.ts)

4. 编写 Mesh (src/modules/...)

💡 类型提示：ModularContainer 类型由 Vite / 构建插件全自动根据目录生成并注入，零手动导入。

🏛️ 核心设计哲学 (Architecture Philosophy)

Path-IoC 的底层设计建立在 4 大高维架构哲学之上：

1. 💡 约定优于配置 + 闭包工厂 (Convention Over Configuration)

拒绝伪注解与重型 @Injectable() 装饰器，保持模块 100% 纯 TypeScript 函数与闭包纯洁性。依靠构建工具链在编译期进行隐式目录契约挂载，零配置开箱即用。

2. 🏷️ 目录即契约，路径即寻址 (Directory as Contract & Path Address)

• 目录即契约 (Directory as Contract)：抛弃显式声明与 @Inject('token') 伪元数据，物理目录路径即为全局服务契约 Token。短名称提供极致直觉的无感解构 (const { add } = container)，全限定路径提供确定性的歧义消除； • 路径即寻址 (Pattern Discovery)：路径不仅是坐标，更是服务发现的天然索引。支持基于路径前缀模式的动态批量收集与副作用扫描（如全动态路由收集 allRoutes、ORM Schema 自动挂载 entities）。

3. ⚡ 零运行期反射与静态图编译 (Zero-Reflection & Precompiled Graph)

彻底摆脱 reflect-metadata 重型反射包袱。架构上将静态图编译 (compileModuleGraph) 与 动态容器填充 (instantiateModuleContainer) 彻底分离，服务启动时仅编译一次拓扑图，高并发请求下零重复拓扑计算，提升 80% CPU 性能。

4. 🔒 循环依赖秒级定位 (不内置与不推荐隐式解环)

不内置也不推荐隐式自动解环（主要避免 async 异步初始化死锁风险与切面模块时序紊乱）。一旦误写循环依赖，框架在启动瞬间（Fail-Fast）立刻拦截并精准打印出完整闭环调用链（如 /A -> /B -> /C -> /A），保证 100% 确定性（👉 点击查看 FAQ 深度解析）。

☯️ 架构范式：前端单例 vs 后端多例 (Practices Matrix)

Path-IoC 本身是一个纯粹的拓扑图引擎与容器填充器，天然适配不同端的架构诉求：

模式 A：前端全局单例 (Frontend Singleton)

在前端应用入口初始化全局单例容器，视图组件或应用逻辑直接消费该单例：

模式 B：后端 Request-Scoped 多例 (Backend Multi-Instance)

在 Node.js / Hono / Express 后端服务中，启动时预编译静态图，HTTP 请求到达时高频实例化独立隔离容器：

📊 主流 IoC 框架选型对比 (Selection Matrix)

| 对比维度 | 传统 TS 装饰器类 (NestJS / InversifyJS) | 动态 Proxy / 注册表类 (Awilix) | Java 传统重型 IoC (Spring Framework) | Path-IoC (本框架) |

| 学习成本与概念包袱 | ❌ 概念极其繁重 (需学 @Module, @Injectable, @inject(), forwardRef, OnModuleInit) | ⚠️ 中度注册链 (需学 asClass/asFunction 注册链与生命周期) | ❌ 概念浩瀚繁重 (需学 Bean 作用域、三级缓存、动态代理、Lifecycle 钩子) | ✅ 零新概念 (目录即 Service Token，仅需导 main 工厂 + dependencies 数组) | | 依赖处理与异步调度 | ❌ 死锁与串行阻塞 (物理机制限制) 1. 死锁：因 JS constructor 无法 async，异步 Provider 与 forwardRef 遇微任务队列直接挂起死锁 2. 阻塞：生命周期钩子 (如 onModuleInit) 需按模块树层级串行递归 await，子树中某个模块的异步挂起容易引发全局初始化延迟，无法做到节点级反应式并发 | ❌ 功能与性能受限 1. 功能：依赖外部驱动，Proxy 无法解决异步初始化时序 2. 性能：挂起等待，无节点级拓扑并发支持 | ⚠️ 多线程同步阻塞模型 (依赖 JVM 多线程同步栈与三级缓存，完全不适配 JavaScript 单线程异步 Event Loop) | ✅ 回归语言原生与反应式拓扑 1. 功能：main 天然支持原生 async/await，反应式自动级联等待 2. 性能：基于 DAG 反应式拓扑并发，绝对不阻塞任何无关模块初始化 | | 构建工具链兼容性 (Vite/SWC/ESBuild) | ❌ 纯类型擦除模式失效 (强依赖 reflect-metadata 与 TS Decorator Metadata，导致 ESBuild、Vite 内置转译器及 Node.js 原生 --strip-types 等纯类型擦除转译直接报错失效，使用 SWC 时也必须专门开启专有元数据转换插件) | ✅ 兼容 (无元数据依赖，但依赖函数 toString() 正则解析入参) | ➖ 不适用 (JVM 生态) (需通过 javac / Bytecode 字节码动态增强) | ✅ 100% 极速构建兼容 (纯 ES Module 函数闭包，零元数据/零反射，天然适配 Vite/SWC/ESBuild/Rspack) | | 循环依赖与安全性 | ❌ 遇到 async 必引发死锁 (forwardRef / @lazyInject / delay() 遇异步微任务挂起) | ⚠️ 仅限同步 (Proxy 延迟 get 拦截，遇异步同样挂起) | ⚠️ 仅限 Setter 注入解环 (三级缓存解环；在构造器注入、@Async 或代理包装时仍抛异常失效) | ✅ 编译期精准定位与确定性 (不内置隐式解环，DFS 环检测秒级打印 /A -> /B -> /A 路径) | | AOP 切面机制 | ❌ 概念繁多 & 框架重度绑定 (切面拆分为 Guards / Interceptors / Pipes / Filters 等多个特权概念；虽然支持全局绑定，但切面逻辑重度绑定 Nest 的 ExecutionContext 抽象，无法作为纯 JS 函数脱离框架独立复用) | ❌ 无内置 AOP (无内置切面概念，需在注册链处由开发者手动包裹 Proxy 或高阶函数) | ✅ 经典声明式代理 (Java 物理约束下的伟大突破) (在 Java 静态强类型与 JVM 字节码约束下，全自动封装 JDK 动态代理与 CGLIB，彻底解放手写代理；类内部自调用切面受代理机制物理限制) | ✅ 极简纯粹 (依赖查找) 仅提供依赖查找能力 (DL)，基于物理路径与原生解构，JS 作为动态语言无需额外的特权 AOP 工具。 | | 团队规范与分层约束 | ✅ 强规范约束 (强制 Controller/Service 死板分层，极大降低百人团队目录混乱与协作成本) | ⚠️ 中度规范 (依赖团队自行约束注册表结构与生命周期) | 🏆 工业级分层标杆 (拥有全行业最成熟的 DDD/MVC 分层规约与包结构标准) | ✅ 物理契约自约束 (基于目录契约自动分层，短名称解构 + 路径切面，兼顾规范与极其灵活的重构) | | 生态扩展与特色工具 | ✅ Swagger 自动推导 (基于 Decorator Metadata 全自动生成 OpenAPI 文档与客户端 SDK) | ✅ 老代码无侵入改装 (支持在外部把任意第三方/遗留 Class/Function 注册为容器 Bean) | 🏆 浩瀚的企业级生态 (拥有全行业最强声明式数据库事务 @Transactional 与微服务治理生态) | ⚡ 路径模式发现 & 动态 Schema (基于路径模式全自动收集路由/实体，一键导出全站 Postman 测试集合) | | 高并发 / 运行时性能 | ⚠️ 高频元数据反射损耗 (Request-scoped 在每次 HTTP 请求到达时，重新遍历 Decorator Metadata 进行反射解析与对象 new 实例化) | ⚠️ 代理解构与属性访问开销 (依赖 ES6 Proxy cradle 机制进行参数解构与动态依赖查找，无法利用编译期静态分析) | ⚠️ 反射与代理开销 (基于 Java 反射机制实例化，存在反射与 CGLIB 代理额外开销) | ⚡ 极高 (性能提升 80%) (静态图预编译与填充分离，填充后为原生 JS 对象，零 Proxy/零反射开销) |

📚 API 参考与规格 (API & Specifications)

🧩 1. Mesh 规范与导出协议 (Mesh Export Protocol)

在 Path-IoC 中，每一个按目录组织的 index.ts(x) 即为一个 Mesh。一个标准的 Mesh 模块文件允许导出以下 4 个标准属性：

| 导出变量名 | 类型签名 | 默认值 | 作用说明 |

| main _(必须)_ | (container: ModularContainer, moduleNames: string[]) => any \| Promise | - | 模块主工厂。按拓扑顺序唤醒，接收 container 与全量模块 Key 列表。支持 async 异步初始化。 | | dependencies _(可选)_ | string[] \| ((moduleNames: string[]) => string[]) | [] | 拓扑依赖声明。图编译阶段优先唤醒。支持静态数组，或函数形式 (names) => string[]。 | | order _(可选)_ | number | 99999 | 初始化优先级。无 dependencies 约束时按数值从小到大排序（负数优先，Infinity 置后）。 | | skip _(可选)_ | boolean \| ((moduleNames: string[]) => boolean) | false | 条件跳过标记。为 true 时跳过该 Mesh 的初始化（用于环境隔离与条件加载）。 |

2. 构建工具集成 (vite.config.ts / webpack.config.js)

Vite 配置：

Webpack / Rspack 配置：

3. 虚拟模块 API (导入自 virtual:modular-container)

💡 由 Vite / Webpack 插件自动生成，内部预装静态图编译逻辑。

| 导出 API | 签名 / 说明 | 描述 |

| createModularContainer | (container?) => Promise> | 开箱即用首选。内置静态图缓存，一行代码自动解析并按拓扑顺序装配所有 Mesh。 | | modules | ModuleDeclaration[] | 自动扫描发现的原始 Mesh 注册表，可用于跨项目/跨包注册表合并。 |

4. 运行时核心 API (导入自 lianhanlin-modular)

🛠️ 高级定制 API：用于脱离 Vite、多注册表合并或极致定制化场景。

| API / 类型 | 签名 / 说明 | 描述 & 使用建议 |…

Description from the npm listing.