@zudojs/core 0.0.1 → 1.0.0

package/dist/modules/moduleLifecycle/moduleLifecycle.stateMachine.js

@@ -1,11 +1,23 @@
 import { ModuleLifecycleError } from "./moduleLifecycle.type.js";
-/** Ensures lifecycle state is synchronized with the registry. */
+import { ModuleNotFoundError } from "../moduleError/moduleError.registration.js";
+/**
+ * Ensures lifecycle state is synchronized with the registry.
+ *
+ * Registered modules gain a "created" state; states belonging to
+ * modules that are no longer registered are pruned.
+ */
 export function ensureStateSynchronized(registry, states) {
+    const registered = new Set();
     for (const registration of registry.getAll()) {
         const moduleId = registration.definition.id;
+        registered.add(moduleId);
         if (!states.has(moduleId))
             states.set(moduleId, { moduleId, phase: "created" });
     }
+    for (const moduleId of [...states.keys()]) {
+        if (!registered.has(moduleId))
+            states.delete(moduleId);
+    }
 }
 export function getLifecycleState(moduleId, states) {
     return states.get(moduleId);
@@ -13,7 +25,7 @@ export function getLifecycleState(moduleId, states) {
 export function requireLifecycleState(moduleId, states) {
     const state = getLifecycleState(moduleId, states);
     if (!state)
-        throw new Error(`No lifecycle state exists for module "${moduleId}".`);
+        throw new ModuleNotFoundError(moduleId);
     return state;
 }
 export function getAllLifecycleStates(states) {
@@ -29,13 +41,59 @@ export function isModuleStarted(moduleId, states) {
 export function isModuleDestroyed(moduleId, states) {
     return getLifecycleState(moduleId, states)?.phase === "destroyed";
 }
-export async function invokeLifecycleHook(module, hook, context) {
-    const lifecycleModule = module;
-    const handler = lifecycleModule[hook];
+/**
+ * Maps each lifecycle step to the hook of the public Module
+ * contract (ModuleLifecycle) that the engine invokes for it.
+ */
+const STEP_HOOKS = {
+    initialize: "onInitialize",
+    start: "onReady",
+    stop: "onShutdown",
+    destroy: "onDestroy",
+};
+/**
+ * Invokes the lifecycle hook for a step on a module.
+ *
+ * Only the canonical Module contract hooks are invoked:
+ *
+ * initialize → onInitialize
+ * start      → onReady
+ * stop       → onShutdown
+ * destroy    → onDestroy
+ *
+ * Modules that do not implement a hook are skipped for that step.
+ *
+ * When `contextStorage` holds an active execution context (the
+ * runtime's, during bootstrap and shutdown), the hook runs inside a
+ * context derived from it: `module` is the module id, `operation`
+ * is the hook name, and `{ moduleId, phase }` is merged into the
+ * metadata. Everything the hook awaits observes that context.
+ */
+export async function invokeLifecycleHook(module, step, context, contextStorage, phase = STEP_PHASES[step]) {
+    const hookName = STEP_HOOKS[step];
+    const handler = module[hookName];
     if (typeof handler !== "function")
         return;
-    await handler.call(module, context);
+    const invoke = () => handler.call(module, context);
+    if (contextStorage?.has()) {
+        await contextStorage.runDerived({
+            module: module.id,
+            operation: hookName,
+            metadata: { moduleId: module.id, phase },
+        }, invoke);
+        return;
+    }
+    await invoke();
 }
+/**
+ * Active phase a module is in while each step's hook runs.
+ */
+const STEP_PHASES = {
+    initialize: "initializing",
+    start: "starting",
+    stop: "stopping",
+    destroy: "destroying",
+};
 export function canModuleEnterPhase(moduleId, hook, states) {
     const state = getLifecycleState(moduleId, states);
     if (!state)
@@ -50,7 +108,9 @@ export function canModuleEnterPhase(moduleId, hook, states) {
         case "destroy":
             return (state.phase === "stopped" ||
                 state.phase === "initialized" ||
-                state.phase === "created");
+                state.phase === "created" ||
+                state.phase === "started" ||
+                state.phase === "failed");
         default:
             return false;
     }
@@ -68,9 +128,30 @@ export function setLifecycleState(moduleId, phase, states, error) {
         destroyedAt: phase === "destroyed" ? now : previous?.destroyedAt,
     }));
 }
-export async function executeLifecyclePhase(order, hook, activePhase, completedPhase, continueOnError, registry, loader, states) {
+/**
+ * Phases that count as "already satisfied" for a hook: modules
+ * in these phases are silently skipped rather than reported.
+ */
+const SATISFIED_PHASES = {
+    initialize: ["initialized", "starting", "started"],
+    start: ["started"],
+    stop: ["created", "initialized", "stopped", "destroying", "destroyed"],
+    destroy: ["destroyed"],
+};
+/**
+ * Phases a required dependency must be in before a dependent
+ * module may enter a forward phase.
+ */
+const REQUIRED_DEPENDENCY_PHASES = {
+    initialize: ["initialized", "starting", "started"],
+    start: ["started"],
+};
+export async function executeLifecyclePhase(order, hook, activePhase, completedPhase, continueOnError, registry, loader, states, contextStorage) {
     const completed = [];
     const failed = [];
+    const skipped = [];
+    const blocked = new Set();
+    const requiredDependencyPhases = REQUIRED_DEPENDENCY_PHASES[hook];
     for (const moduleId of order) {
         const registration = registry.get(moduleId);
         if (!registration?.instance)
@@ -84,11 +165,49 @@ export async function executeLifecyclePhase(order, hook, activePhase, completedP
                 throw new ModuleLifecycleError(moduleId, activePhase, new Error(`Module "${moduleId}" does not have a ModuleContext.`));
             continue;
         }
-        if (!canModuleEnterPhase(moduleId, hook, states))
+        const currentPhase = getLifecycleState(moduleId, states)?.phase;
+        if (!canModuleEnterPhase(moduleId, hook, states)) {
+            if (currentPhase !== undefined &&
+                SATISFIED_PHASES[hook].includes(currentPhase)) {
+                continue;
+            }
+            skipped.push({
+                moduleId,
+                reason: `Module is in phase "${currentPhase ?? "unknown"}" and cannot enter ${hook}.`,
+            });
+            blocked.add(moduleId);
             continue;
+        }
+        /*
+         * Forward phases only run when every required dependency
+         * reached the requisite state. Modules whose dependencies
+         * failed (or were skipped) are skipped with a reason instead
+         * of being initialized against a broken dependency.
+         */
+        if (requiredDependencyPhases) {
+            const blockingDependency = registry
+                .getDependencies(moduleId)
+                .find((dependency) => {
+                if (dependency.optional)
+                    return false;
+                if (blocked.has(dependency.id) || failed.includes(dependency.id))
+                    return true;
+                const dependencyPhase = getLifecycleState(dependency.id, states)?.phase;
+                return (dependencyPhase === undefined ||
+                    !requiredDependencyPhases.includes(dependencyPhase));
+            });
+            if (blockingDependency) {
+                skipped.push({
+                    moduleId,
+                    reason: `Dependency "${blockingDependency.id}" is not ready for ${hook}.`,
+                });
+                blocked.add(moduleId);
+                continue;
+            }
+        }
         setLifecycleState(moduleId, activePhase, states);
         try {
-            await invokeLifecycleHook(module, hook, context);
+            await invokeLifecycleHook(module, hook, context, contextStorage, activePhase);
             setLifecycleState(moduleId, completedPhase, states);
             completed.push(moduleId);
         }
@@ -102,6 +221,7 @@ export async function executeLifecyclePhase(order, hook, activePhase, completedP
     return {
         completed: Object.freeze([...completed]),
         failed: Object.freeze([...failed]),
+        skipped: Object.freeze([...skipped]),
     };
 }
 //# sourceMappingURL=moduleLifecycle.stateMachine.js.map

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

@@ -1,5 +1,5 @@
-import type { ModuleId } from "../module.js";
-import type { ModuleContext } from "../moduleContext.context.js";
+import type { ModuleId, ModuleLifecycle } from "../module.js";
+import type { ContextStorage } from "../../context/provider/contextStorage.storage.js";
 /**
  * Lifecycle phases supported by the module system.
  */
@@ -16,34 +16,34 @@ export interface ModuleLifecycleState {
     readonly stoppedAt?: Date;
     readonly destroyedAt?: Date;
 }
+/**
+ * Canonical lifecycle hook names of the public Module contract.
+ *
+ * The lifecycle engine invokes exactly these methods:
+ *
+ * initialize step → onInitialize
+ * start step      → onReady
+ * stop step       → onShutdown
+ * destroy step    → onDestroy
+ */
+export type ModuleLifecycleHookName = "onInitialize" | "onReady" | "onShutdown" | "onDestroy";
+/**
+ * Lifecycle steps executed by the module lifecycle engine.
+ *
+ * Each step maps onto one ModuleLifecycleHookName; see
+ * ModuleLifecycleHookName for the mapping.
+ */
+export type ModuleLifecycleStep = "initialize" | "start" | "stop" | "destroy";
 /**
  * Lifecycle hooks supported by a module.
  *
- * Modules can implement any subset of these hooks.
+ * @deprecated The module hook contract is ModuleLifecycle
+ * (onInitialize/onReady/onShutdown/onDestroy). This alias exists
+ * for source compatibility only; the legacy
+ * initialize/start/stop/destroy method names are never invoked
+ * by the lifecycle engine.
  */
-export interface ModuleLifecycleHooks {
-    /**
-     * Called before the module starts accepting work.
-     */
-    initialize?(context: ModuleContext): void | Promise<void>;
-    /**
-     * Called after all modules have initialized.
-     *
-     * This is useful when a module needs other modules to
-     * already be initialized before it becomes active.
-     */
-    start?(context: ModuleContext): void | Promise<void>;
-    /**
-     * Called when the application begins shutting down.
-     */
-    stop?(context: ModuleContext): void | Promise<void>;
-    /**
-     * Called after the module has stopped.
-     *
-     * This is the place for final resource cleanup.
-     */
-    destroy?(context: ModuleContext): void | Promise<void>;
-}
+export type ModuleLifecycleHooks = ModuleLifecycle;
 /**
  * Options controlling module lifecycle behavior.
  */
@@ -72,20 +72,57 @@ export interface ModuleLifecycleOptions {
      * Defaults to true.
      */
     readonly continueOnDestroyError?: boolean;
+    /**
+     * ContextStorage consulted before every hook invocation. When an
+     * execution context is active in it (the runtime establishes its
+     * RuntimeExecutionContext around bootstrap and shutdown), each
+     * hook runs in a context derived from it with
+     * `module`/`operation` set and `{ moduleId, phase }` merged into
+     * the metadata. When no context is active the hook is invoked
+     * directly.
+     *
+     * Defaults to getDefaultContextStorage(); pass the runtime's
+     * storage when injecting a custom one.
+     */
+    readonly contextStorage?: ContextStorage;
 }
-import { ModuleLifecycleError as BaseModuleLifecycleError } from "@zudojs/errors";
+import { ModuleOperationError } from "../moduleError/moduleError.lifecycle.js";
 /**
  * Error thrown when a module lifecycle operation fails.
+ *
+ * Part of the core module error taxonomy: it is a ModuleError
+ * carrying the phase-specific code (MODULE_INITIALIZATION_FAILED,
+ * MODULE_START_FAILED, ...), so callers can catch it by type or by
+ * code.
  */
-export declare class ModuleLifecycleError extends BaseModuleLifecycleError {
+export declare class ModuleLifecycleError extends ModuleOperationError {
+    /**
+     * Errors encountered while rolling back already-completed
+     * modules after this failure. Best-effort: rollback itself
+     * never masks the original failure.
+     */
+    rollbackErrors?: readonly unknown[];
     constructor(moduleId: ModuleId, phase: ModuleLifecyclePhase, cause: unknown);
 }
+/**
+ * Reason a module was skipped during a lifecycle phase.
+ */
+export interface ModuleLifecycleSkip {
+    readonly moduleId: ModuleId;
+    readonly reason: string;
+}
 /**
  * Result of a lifecycle operation.
  */
 export interface ModuleLifecycleResult {
     readonly completed: readonly ModuleId[];
     readonly failed: readonly ModuleId[];
+    /**
+     * Modules that could not participate in the phase, with the
+     * reason: their required dependencies failed or were skipped,
+     * or their current phase does not permit the transition.
+     */
+    readonly skipped: readonly ModuleLifecycleSkip[];
 }
 /**
  * Internal lifecycle state map.

package/dist/modules/moduleLifecycle/moduleLifecycle.type.js

@@ -1,11 +1,22 @@
-import { ModuleLifecycleError as BaseModuleLifecycleError } from "@zudojs/errors";
+import { ModuleOperationError } from "../moduleError/moduleError.lifecycle.js";
 /**
  * Error thrown when a module lifecycle operation fails.
+ *
+ * Part of the core module error taxonomy: it is a ModuleError
+ * carrying the phase-specific code (MODULE_INITIALIZATION_FAILED,
+ * MODULE_START_FAILED, ...), so callers can catch it by type or by
+ * code.
  */
-export class ModuleLifecycleError extends BaseModuleLifecycleError {
+export class ModuleLifecycleError extends ModuleOperationError {
+    /**
+     * Errors encountered while rolling back already-completed
+     * modules after this failure. Best-effort: rollback itself
+     * never masks the original failure.
+     */
+    rollbackErrors;
     constructor(moduleId, phase, cause) {
-        const message = cause instanceof Error ? cause.message : String(cause);
-        super(moduleId, phase, `Module "${moduleId}" failed during ${phase}: ${message}`, cause);
+        super(moduleId, phase, cause);
+        this.name = "ModuleLifecycleError";
     }
 }
 //# sourceMappingURL=moduleLifecycle.type.js.map

package/dist/modules/moduleLoader/moduleLoader.loader.d.ts

@@ -7,6 +7,11 @@ import type { ModuleLoaderOptions, ModuleLoadResult } from "./moduleLoader.type.
  *
  * Reads definitions from registry, builds dependency graph,
  * validates, resolves startup order, instantiates modules.
+ *
+ * Dependencies are always resolved against every registered
+ * definition. autoLoad filtering applies only to load roots:
+ * a module registered with autoLoad disabled is still loaded
+ * when another loading module requires it.
  */
 export declare class ModuleLoader {
     private readonly application;
@@ -15,21 +20,50 @@ export declare class ModuleLoader {
     private readonly registry;
     private readonly allowExplicitLoad;
     private readonly contexts;
+    private readonly inFlightLoads;
     constructor(registry: ModuleRegistry, options: ModuleLoaderOptions);
-    /** Loads every module whose definition has autoLoad enabled. */
+    /**
+     * Loads every module whose definition has autoLoad enabled,
+     * plus every module those modules require (regardless of the
+     * required module's autoLoad setting).
+     */
     loadAll(): Promise<ModuleLoadResult>;
-    /** Loads a specific module and all of its required dependencies. */
+    /**
+     * Loads a specific module and all of its required dependencies.
+     *
+     * Concurrent load() calls for the same module share a single
+     * in-flight load.
+     */
     load(moduleId: ModuleId): Promise<Module>;
-    private loadDefinitions;
+    /**
+     * Loads the dependency closure of the requested module ids.
+     */
+    private loadClosure;
+    /**
+     * Collects the dependency closure of the requested modules
+     * across every registered definition.
+     *
+     * Optional dependencies join the closure only when they are
+     * registered; missing required dependencies are reported with
+     * the module that needs them.
+     */
+    private collectClosure;
     private createGraph;
-    private collectDependencies;
     private instantiate;
     private createModuleLogger;
-    private isExplicitlyRequested;
     getContext(moduleId: ModuleId): ModuleContext | undefined;
     requireContext(moduleId: ModuleId): ModuleContext;
     getContexts(): ReadonlyMap<ModuleId, ModuleContext>;
     isLoaded(moduleId: ModuleId): boolean;
+    /**
+     * Forgets a module's runtime instance and context.
+     *
+     * The loader does not run lifecycle hooks; callers that need
+     * the instance shut down first should use
+     * ModuleLifecycleManager.unloadModule(). Returns false when the
+     * module is not registered or holds no instance.
+     */
+    unload(moduleId: ModuleId): boolean;
 }
 /** Creates a module loader. */
 export declare function createModuleLoader(registry: ModuleRegistry, options: ModuleLoaderOptions): ModuleLoader;