@path-ioc/core API Reference

@path-ioc/core provides the foundational topological scheduling engine and dependency lookup runtime. With an 8.8KB bundle footprint and zero external dependencies, it natively supports browsers, Node.js, and Cloudflare Workers.

---

Core Methods

compileModuleGraph(modules)

Compiles a declared module list into an immutable, validated Directed Acyclic Graph (DAG).

• Type Signature:

  function compileModuleGraph(modules: { key: string; module: IOCModule }[]): CompiledModuleGraph;

• Parameters:
  • modules: Array of module descriptor objects. Typically provided automatically by virtual:modular-container, or constructed manually in unit tests and scripts.
• Returns:
  • CompiledModuleGraph: A compiled structure containing the DFS topological sort array, cycle detection metadata, and short-alias lookup maps.
• Errors:
  • Throws a descriptive Error indicating the full circular reference path if a dependency cycle is detected.
  • Throws if conflicting module keys or invalid module definitions are encountered.

---

instantiateModuleContainer(compiledGraph, container)

Instantiates modules in topological order by invoking their main factories and populating the target container.

• Type Signature:

  function instantiateModuleContainer(
    compiledGraph: CompiledModuleGraph,
    container: Record<string, unknown>,
  ): Promise<void>;

• Parameters:
  • compiledGraph: Pre-compiled graph produced by compileModuleGraph.
  • container: Target mutable container object (e.g. { requestContext: c }).
• Performance:
  • Pure synchronous factory graphs resolve directly in 21.2 microseconds.

---

initialize(modules, container)

A convenience utility that executes compileModuleGraph followed immediately by instantiateModuleContainer.

• Type Signature:

  function initialize(
    modules: { key: string; module: IOCModule }[],
    container: Record<string, unknown>,
  ): Promise<void>;

---

Mesh Module Export Protocol

💡 The Mesh Concept: In Path-IoC, each business module is termed a Mesh (analogous to a Bean in Spring). Just as Spring is to Java and Bean is to Class, Path-IoC is an application-level modular system where Mesh is a high-level IoC unit contrasting with standard ES Modules (ESM).

Every module located at src/modules/**/index.ts may export up to four standard identifiers:

Identifier	Type Signature	Default	Description
main (Required)	(container: ModularContainer, moduleNames: string[]) => any | Promise<any>	-	Factory function invoked according to topological sort order. Supports async.
dependencies (Optional)	string[] | ((moduleNames: string[]) => string[])	[]	Explicit topological dependencies. Supports string arrays or dynamic filter functions.
order (Optional)	number	99999	Priority weight when no explicit topological dependencies constrain ordering. Smaller numbers execute earlier (ascending numerical order, default 99999).
skip (Optional)	boolean	false	Skips runtime execution of main. Used for externally injected modules (e.g. injecting requestContext in backend request isolation). Note: Even with skip: true, a dummy main function (e.g., export const main = (): MyType => ({} as any)) must still be exported to satisfy runtime graph validation and type generation.