@zudojs/core 0.1.0 → 1.1.0

package/dist/modules/moduleDependency/moduleDependency.ordering.js

@@ -1,44 +1,50 @@
-import { validateModuleDependencyGraph } from "./moduleDependency.graph.js";
+import { CircularModuleDependencyError, MissingModuleDependencyError, } from "../moduleError/moduleError.dependency.js";
 /**
  * Detects circular dependencies in a module graph.
  *
  * Returns the dependency cycle when one exists.
+ *
+ * This is the single cycle-detection mechanism used by the
+ * dependency subsystem. The implementation is iterative so very
+ * deep graphs cannot overflow the call stack.
  */
 export function findModuleDependencyCycle(graph) {
-    const visiting = new Set();
     const visited = new Set();
-    const path = [];
-    const visit = (moduleId) => {
-        if (visiting.has(moduleId)) {
-            const index = path.indexOf(moduleId);
-            if (index >= 0) {
-                return [...path.slice(index), moduleId];
-            }
-            return [moduleId];
-        }
-        if (visited.has(moduleId)) {
-            return undefined;
-        }
-        visiting.add(moduleId);
-        path.push(moduleId);
-        for (const dependency of graph.getDependencies(moduleId)) {
-            if (!graph.hasModule(dependency.id)) {
+    for (const startId of graph.nodes.keys()) {
+        if (visited.has(startId))
+            continue;
+        /*
+         * Iterative DFS. Each stack frame tracks the module and the
+         * index of the next dependency to visit.
+         */
+        const stack = [
+            { id: startId, nextDependency: 0 },
+        ];
+        const inPath = new Set([startId]);
+        const path = [startId];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const dependencies = graph.getDependencies(frame.id);
+            if (frame.nextDependency >= dependencies.length) {
+                stack.pop();
+                path.pop();
+                inPath.delete(frame.id);
+                visited.add(frame.id);
                 continue;
             }
-            const cycle = visit(dependency.id);
-            if (cycle) {
-                return cycle;
+            const dependency = dependencies[frame.nextDependency];
+            frame.nextDependency += 1;
+            if (!graph.hasModule(dependency.id))
+                continue;
+            if (inPath.has(dependency.id)) {
+                const index = path.indexOf(dependency.id);
+                return [...path.slice(index), dependency.id];
             }
-        }
-        path.pop();
-        visiting.delete(moduleId);
-        visited.add(moduleId);
-        return undefined;
-    };
-    for (const moduleId of graph.nodes.keys()) {
-        const cycle = visit(moduleId);
-        if (cycle) {
-            return cycle;
+            if (visited.has(dependency.id))
+                continue;
+            stack.push({ id: dependency.id, nextDependency: 0 });
+            inPath.add(dependency.id);
+            path.push(dependency.id);
         }
     }
     return undefined;
@@ -65,38 +71,60 @@ export function hasModuleDependencyCycle(graph) {
  * produces:
  *
  * users → orders → payments
+ *
+ * The sort is implemented iteratively (Kahn's algorithm). When
+ * not every module can be ordered, the cycle is located with
+ * findModuleDependencyCycle and reported.
  */
 export function resolveModuleStartupOrder(graph) {
-    const missing = validateModuleDependencyGraph(graph);
-    if (missing.length > 0) {
-        throw new Error(`Cannot resolve module startup order. Missing required dependencies: ${missing.join(", ")}`);
+    /*
+     * Missing required dependencies make the order meaningless,
+     * so they are reported first with the requiring module.
+     */
+    for (const node of graph.nodes.values()) {
+        for (const dependency of node.dependencies) {
+            if (dependency.optional)
+                continue;
+            if (!graph.hasModule(dependency.id)) {
+                throw new MissingModuleDependencyError(node.id, dependency.id);
+            }
+        }
+    }
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const node of graph.nodes.values()) {
+        let degree = 0;
+        for (const dependency of node.dependencies) {
+            if (!graph.hasModule(dependency.id))
+                continue;
+            degree += 1;
+            const list = dependents.get(dependency.id);
+            if (list)
+                list.push(node.id);
+            else
+                dependents.set(dependency.id, [node.id]);
+        }
+        inDegree.set(node.id, degree);
     }
-    const cycle = findModuleDependencyCycle(graph);
-    if (cycle) {
-        throw new Error(`Circular module dependency detected: ${cycle.join(" -> ")}`);
+    const queue = [];
+    for (const [moduleId, degree] of inDegree) {
+        if (degree === 0)
+            queue.push(moduleId);
     }
-    const temporary = new Set();
-    const permanent = new Set();
     const order = [];
-    const visit = (moduleId) => {
-        if (permanent.has(moduleId)) {
-            return;
-        }
-        if (temporary.has(moduleId)) {
-            throw new Error(`Circular module dependency detected involving "${moduleId}".`);
-        }
-        temporary.add(moduleId);
-        for (const dependency of graph.getDependencies(moduleId)) {
-            if (graph.hasModule(dependency.id)) {
-                visit(dependency.id);
-            }
-        }
-        temporary.delete(moduleId);
-        permanent.add(moduleId);
+    for (let index = 0; index < queue.length; index++) {
+        const moduleId = queue[index];
         order.push(moduleId);
-    };
-    for (const moduleId of graph.nodes.keys()) {
-        visit(moduleId);
+        for (const dependent of dependents.get(moduleId) ?? []) {
+            const degree = (inDegree.get(dependent) ?? 0) - 1;
+            inDegree.set(dependent, degree);
+            if (degree === 0)
+                queue.push(dependent);
+        }
+    }
+    if (order.length !== graph.nodes.size) {
+        const cycle = findModuleDependencyCycle(graph);
+        throw new CircularModuleDependencyError(cycle ?? [...graph.nodes.keys()].filter((id) => !order.includes(id)));
     }
     return Object.freeze(order);
 }

package/dist/modules/moduleDependency/moduleDependency.type.d.ts

@@ -37,6 +37,13 @@ export interface ModuleDependencyNode {
      * Dependencies declared by the module.
      */
     readonly dependencies: ModuleDependencies;
+    /**
+     * Semantic version of the module, when known.
+     *
+     * Used to check dependency version constraints while
+     * building the graph.
+     */
+    readonly version?: string;
 }
 /**
  * Complete module dependency graph.
@@ -62,5 +69,25 @@ export interface ModuleDependencyGraph {
 /**
  * A raw dependency declaration accepted by the framework.
  */
-export type ModuleDependencyInput = ModuleId | ModuleDependency;
+export type ModuleDependencyInput = ModuleId | (Pick<ModuleDependency, "id"> & Partial<Omit<ModuleDependency, "id">>);
+/**
+ * A raw dependency graph node accepted by `createModuleDependencyGraph`.
+ *
+ * Dependencies may be declared as plain ids or partial dependency objects;
+ * they are normalized while the graph is built.
+ */
+export interface ModuleDependencyNodeInput {
+    /**
+     * Module identifier.
+     */
+    readonly id: ModuleId;
+    /**
+     * Dependencies declared by the module.
+     */
+    readonly dependencies?: readonly ModuleDependencyInput[];
+    /**
+     * Semantic version of the module, when known.
+     */
+    readonly version?: string;
+}
 //# sourceMappingURL=moduleDependency.type.d.ts.map

package/dist/modules/moduleError/index.d.ts

@@ -5,7 +5,7 @@
  */
 export { ModuleErrorCode, type ModuleErrorCode as ModuleErrorCodeType, type ModuleErrorDetails, ModuleError, } from "./moduleError.base.js";
 export { InvalidModuleDefinitionError, ModuleNotFoundError, DuplicateModuleError, } from "./moduleError.registration.js";
-export { MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
+export { InvalidModuleDependencyError, MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
 export { getLifecycleErrorCode, ModuleInstantiationError, ModuleOperationError, InvalidModuleInstanceError, InvalidModuleStateError, ModuleOperationInProgressError, } from "./moduleError.lifecycle.js";
 export { isModuleError, hasModuleErrorCode, toModuleError, } from "./moduleError.helpers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleError/index.js

@@ -5,7 +5,7 @@
  */
 export { ModuleErrorCode, ModuleError, } from "./moduleError.base.js";
 export { InvalidModuleDefinitionError, ModuleNotFoundError, DuplicateModuleError, } from "./moduleError.registration.js";
-export { MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
+export { InvalidModuleDependencyError, MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
 export { getLifecycleErrorCode, ModuleInstantiationError, ModuleOperationError, InvalidModuleInstanceError, InvalidModuleStateError, ModuleOperationInProgressError, } from "./moduleError.lifecycle.js";
 export { isModuleError, hasModuleErrorCode, toModuleError, } from "./moduleError.helpers.js";
 //# sourceMappingURL=index.js.map

package/dist/modules/moduleError/moduleError.dependency.d.ts

@@ -12,6 +12,17 @@ export declare class MissingModuleDependencyError extends ModuleError {
 export declare class CircularModuleDependencyError extends ModuleError {
     constructor(cycle: readonly ModuleId[]);
 }
+/**
+ * Error thrown when a dependency declaration is malformed:
+ * empty ids, self-dependencies, duplicate declarations, or
+ * unsupported version constraints.
+ */
+export declare class InvalidModuleDependencyError extends ModuleError {
+    constructor(message: string, options?: {
+        readonly moduleId?: ModuleId;
+        readonly dependencyId?: ModuleId;
+    });
+}
 /**
  * Error thrown when a module dependency version
  * cannot be satisfied.

package/dist/modules/moduleError/moduleError.dependency.js

@@ -26,6 +26,21 @@ export class CircularModuleDependencyError extends ModuleError {
         this.name = "CircularModuleDependencyError";
     }
 }
+/**
+ * Error thrown when a dependency declaration is malformed:
+ * empty ids, self-dependencies, duplicate declarations, or
+ * unsupported version constraints.
+ */
+export class InvalidModuleDependencyError extends ModuleError {
+    constructor(message, options = {}) {
+        super(message, {
+            code: ModuleErrorCode.INVALID_DEPENDENCY,
+            moduleId: options.moduleId,
+            dependencyId: options.dependencyId,
+        });
+        this.name = "InvalidModuleDependencyError";
+    }
+}
 /**
  * Error thrown when a module dependency version
  * cannot be satisfied.

package/dist/modules/moduleLifecycle/index.d.ts

@@ -3,8 +3,11 @@
  *
  * Manages the lifecycle phases of loaded modules:
  * initialize → start → stop → destroy.
+ *
+ * The state-machine plumbing (hook invocation, phase execution,
+ * state maps) is internal to this subsystem and intentionally
+ * not exported from this barrel.
  */
-export { type ModuleLifecyclePhase, type ModuleLifecycleState, type ModuleLifecycleHooks, type ModuleLifecycleOptions, ModuleLifecycleError, type ModuleLifecycleResult, type LifecycleStateMap, } from "./moduleLifecycle.type.js";
-export { ensureStateSynchronized, getLifecycleState, requireLifecycleState, getAllLifecycleStates, isModuleInitialized, isModuleStarted, isModuleDestroyed, invokeLifecycleHook, canModuleEnterPhase, setLifecycleState, executeLifecyclePhase, } from "./moduleLifecycle.stateMachine.js";
+export { type ModuleLifecyclePhase, type ModuleLifecycleState, type ModuleLifecycleHookName, type ModuleLifecycleStep, type ModuleLifecycleHooks, type ModuleLifecycleOptions, type ModuleLifecyclePhaseOptions, ModuleLifecycleError, type ModuleLifecycleResult, type ModuleLifecycleSkip, } from "./moduleLifecycle.type.js";
 export { ModuleLifecycleManager, createModuleLifecycleManager, } from "./moduleLifecycle.lifecycle.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleLifecycle/index.js

@@ -3,8 +3,11 @@
  *
  * Manages the lifecycle phases of loaded modules:
  * initialize → start → stop → destroy.
+ *
+ * The state-machine plumbing (hook invocation, phase execution,
+ * state maps) is internal to this subsystem and intentionally
+ * not exported from this barrel.
  */
 export { ModuleLifecycleError, } from "./moduleLifecycle.type.js";
-export { ensureStateSynchronized, getLifecycleState, requireLifecycleState, getAllLifecycleStates, isModuleInitialized, isModuleStarted, isModuleDestroyed, invokeLifecycleHook, canModuleEnterPhase, setLifecycleState, executeLifecyclePhase, } from "./moduleLifecycle.stateMachine.js";
 export { ModuleLifecycleManager, createModuleLifecycleManager, } from "./moduleLifecycle.lifecycle.js";
 //# sourceMappingURL=index.js.map

package/dist/modules/moduleLifecycle/moduleLifecycle.lifecycle.d.ts

@@ -1,7 +1,9 @@
-import type { ModuleId } from "../module.js";
-import type { ModuleRegistry } from "../moduleRegistry/index.js";
+import type { Module, ModuleId } from "../module.js";
+import type { ModuleDefinition } from "../moduleDefinition.definition.js";
+import type { ModuleRegistration, ModuleRegistry } from "../moduleRegistry/index.js";
 import type { ModuleLoader } from "../moduleLoader/index.js";
-import type { ModuleLifecycleOptions, ModuleLifecycleResult } from "./moduleLifecycle.type.js";
+import type { ModuleLifecycleOptions, ModuleLifecyclePhaseOptions, ModuleLifecycleResult, ModuleLifecycleState } from "./moduleLifecycle.type.js";
+import type { ModuleDependency } from "../moduleDependency/moduleDependency.type.js";
 /**
  * Module lifecycle manager.
  * Initializes, starts, stops, and destroys modules in dependency order.
@@ -10,13 +12,58 @@ export declare class ModuleLifecycleManager {
     private readonly registry;
     private readonly loader;
     private readonly options;
+    private readonly contextStorage;
     private readonly states;
     private operation;
     constructor(registry: ModuleRegistry, loader: ModuleLoader, options?: ModuleLifecycleOptions);
-    initialize(): Promise<ModuleLifecycleResult>;
-    start(): Promise<ModuleLifecycleResult>;
-    stop(): Promise<ModuleLifecycleResult>;
-    destroy(): Promise<ModuleLifecycleResult>;
+    initialize(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
+    start(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
+    stop(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
+    destroy(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
+    /**
+     * Rolls back modules that completed earlier phases after a
+     * startup failure.
+     *
+     * The rollback is best-effort: the already-completed subset is
+     * stopped (when requested) and destroyed in reverse dependency
+     * order, and any rollback errors are collected onto the
+     * original ModuleLifecycleError instead of masking it.
+     */
+    private rollbackAfterFailure;
+    /**
+     * Shuts down and unloads a single module.
+     *
+     * The module is stopped (when started) and destroyed, its
+     * lifecycle state is dropped, and the loader forgets its
+     * instance and context. Hook failures never abort the unload;
+     * they are reported in the result and on the lifecycle state.
+     *
+     * A module that other loaded modules still depend on cannot be
+     * unloaded; ModuleError (MODULE_OPERATION_NOT_ALLOWED) is thrown.
+     */
+    unloadModule(moduleId: ModuleId): Promise<ModuleLifecycleResult>;
+    /**
+     * Replaces a module definition, shutting down the currently
+     * loaded instance first.
+     *
+     * The registry must allow replacement (allowReplacement: true).
+     * The new definition is registered but not loaded; call the
+     * loader and lifecycle methods afterwards to bring it up.
+     */
+    replaceModule<TModule extends Module>(definition: ModuleDefinition<TModule>): Promise<ModuleRegistration<TModule>>;
+    /**
+     * Returns ids of loaded modules that declare a required or
+     * optional dependency on the given module.
+     */
+    private getLoadedDependents;
+    /**
+     * Dependencies of a registered module: those declared on the
+     * definition plus any the loaded instance declares itself
+     * (`Module.dependencies`, e.g. via the BaseModule constructor).
+     * Instance-declared dependencies are required; a definition
+     * entry for the same id wins so optional/version flags survive.
+     */
+    private resolveDependencies;
     startApplication(): Promise<{
         readonly initialized: ModuleLifecycleResult;
         readonly started: ModuleLifecycleResult;
@@ -25,17 +72,33 @@ export declare class ModuleLifecycleManager {
         readonly stopped: ModuleLifecycleResult;
         readonly destroyed: ModuleLifecycleResult;
     }>;
-    getState(moduleId: ModuleId): import("./moduleLifecycle.type.js").ModuleLifecycleState | undefined;
-    requireState(moduleId: ModuleId): import("./moduleLifecycle.type.js").ModuleLifecycleState;
-    getStates(): ReadonlyMap<ModuleId, import("./moduleLifecycle.type.js").ModuleLifecycleState>;
+    getState(moduleId: ModuleId): ModuleLifecycleState | undefined;
+    requireState(moduleId: ModuleId): ModuleLifecycleState;
+    getStates(): ReadonlyMap<ModuleId, ModuleLifecycleState>;
     isInitialized(moduleId: ModuleId): boolean;
     isStarted(moduleId: ModuleId): boolean;
     isDestroyed(moduleId: ModuleId): boolean;
+    /**
+     * Builds the dependency graph over the loaded modules only.
+     *
+     * Lifecycle phases run for loaded modules, so a registered but
+     * unloaded definition (autoLoad: false) must not be able to
+     * break them with a missing or circular dependency of its own.
+     * Dependencies of a loaded module that are not loaded are kept
+     * as edges so the ordering reports them as missing.
+     */
     private createGraph;
     private getStartupOrder;
     private getShutdownOrder;
     private runExclusive;
 }
+/**
+ * Resolves the dependencies of a registration: definition-declared
+ * dependencies plus the ids the loaded instance declares through
+ * `Module.dependencies`. Shared by the lifecycle manager and the
+ * loader so both agree on the graph.
+ */
+export declare function resolveRegistrationDependencies(registry: ModuleRegistry, registration: ModuleRegistration): readonly ModuleDependency[];
 /** Creates a module lifecycle manager. */
 export declare function createModuleLifecycleManager(registry: ModuleRegistry, loader: ModuleLoader, options?: ModuleLifecycleOptions): ModuleLifecycleManager;
 //# sourceMappingURL=moduleLifecycle.lifecycle.d.ts.map