@zudojs/core 0.1.0 → 1.0.0

package/dist/modules/moduleContext.context.d.ts

@@ -91,14 +91,30 @@ export interface ModuleContext extends ModuleContextInfo {
     /**
      * Returns another module's context.
      *
-     * This should only be used for declared module dependencies.
+     * Access is restricted to declared module dependencies: when
+     * the requested module is not declared as a dependency of the
+     * current module, MissingModuleDependencyError is thrown.
+     * Declared dependencies that have not been loaded yet resolve
+     * to undefined.
      */
     getModuleContext(moduleId: ModuleId): ModuleContext | undefined;
     /**
-     * Returns whether another module is available.
+     * Returns whether another module is available to this module.
+     *
+     * Only declared dependencies can be observed: undeclared modules
+     * always report false, so a module cannot discover modules it
+     * does not depend on.
      */
     hasModule(moduleId: ModuleId): boolean;
 }
+/**
+ * Resolves the context of another module by id.
+ *
+ * The loader hands each module a resolver instead of its live
+ * context map, so modules never hold a reference to shared
+ * runtime state.
+ */
+export type ModuleContextResolver = (moduleId: ModuleId) => ModuleContext | undefined;
 /**
  * Internal implementation of ModuleContext.
  *
@@ -115,8 +131,15 @@ export declare class DefaultModuleContext implements ModuleContext {
     readonly application: ApplicationContext;
     readonly configuration: ConfigurationManager;
     readonly logger: Logger;
-    private readonly moduleContexts;
-    constructor(module: Module, dependencies: ModuleContextDependencies, metadata?: ModuleMetadata, moduleContexts?: ReadonlyMap<ModuleId, ModuleContext>);
+    private readonly resolveModuleContext;
+    /**
+     * Ids of the modules this module declares as dependencies.
+     *
+     * When undefined, dependency access is not enforced (legacy
+     * construction path).
+     */
+    private readonly declaredDependencies?;
+    constructor(module: Module, dependencies: ModuleContextDependencies, metadata?: ModuleMetadata, moduleContexts?: ReadonlyMap<ModuleId, ModuleContext> | ModuleContextResolver, declaredDependencies?: readonly ModuleId[]);
     /**
      * Returns the current configuration.
      */
@@ -131,10 +154,13 @@ export declare class DefaultModuleContext implements ModuleContext {
     requireConfig<T = unknown>(path: string): T;
     /**
      * Gets the context of another module.
+     *
+     * Only declared dependencies are accessible; requesting an
+     * undeclared module throws MissingModuleDependencyError.
      */
     getModuleContext(moduleId: ModuleId): ModuleContext | undefined;
     /**
-     * Checks whether another module exists.
+     * Checks whether a declared dependency is available.
      */
     hasModule(moduleId: ModuleId): boolean;
 }
@@ -155,9 +181,17 @@ export interface CreateModuleContextOptions {
      */
     readonly metadata?: ModuleMetadata;
     /**
-     * Contexts of modules that have already been resolved.
+     * Contexts of modules that have already been resolved, either
+     * as a map or as a resolver function. The loader supplies a
+     * resolver so the module never receives the live context map.
+     */
+    readonly moduleContexts?: ReadonlyMap<ModuleId, ModuleContext> | ModuleContextResolver;
+    /**
+     * Ids of the modules the current module declares as
+     * dependencies. When supplied, getModuleContext enforces
+     * declared-dependency access.
      */
-    readonly moduleContexts?: ReadonlyMap<ModuleId, ModuleContext>;
+    readonly declaredDependencies?: readonly ModuleId[];
 }
 /**
  * Creates a module context.

package/dist/modules/moduleContext.context.js

@@ -1,3 +1,5 @@
+import { deepFreezeModuleOptions } from "./moduleDefinition.definition.js";
+import { MissingModuleDependencyError } from "./moduleError/moduleError.dependency.js";
 /**
  * Internal implementation of ModuleContext.
  *
@@ -14,20 +16,33 @@ export class DefaultModuleContext {
     application;
     configuration;
     logger;
-    moduleContexts;
-    constructor(module, dependencies, metadata, moduleContexts = new Map()) {
+    resolveModuleContext;
+    /**
+     * Ids of the modules this module declares as dependencies.
+     *
+     * When undefined, dependency access is not enforced (legacy
+     * construction path).
+     */
+    declaredDependencies;
+    constructor(module, dependencies, metadata, moduleContexts = new Map(), declaredDependencies) {
         this.id = module.id;
         this.name = module.name;
         this.version = module.version;
         this.metadata = metadata;
-        this.options = Object.freeze({
+        this.options = deepFreezeModuleOptions({
             ...(module.options ?? {}),
         });
         this.scope = module.scope;
         this.application = dependencies.application;
         this.configuration = dependencies.configuration;
         this.logger = dependencies.logger;
-        this.moduleContexts = moduleContexts;
+        this.resolveModuleContext =
+            typeof moduleContexts === "function"
+                ? moduleContexts
+                : (moduleId) => moduleContexts.get(moduleId);
+        this.declaredDependencies = declaredDependencies
+            ? new Set(declaredDependencies)
+            : undefined;
     }
     /**
      * Returns the current configuration.
@@ -49,22 +64,30 @@ export class DefaultModuleContext {
     }
     /**
      * Gets the context of another module.
+     *
+     * Only declared dependencies are accessible; requesting an
+     * undeclared module throws MissingModuleDependencyError.
      */
     getModuleContext(moduleId) {
-        return this.moduleContexts.get(moduleId);
+        if (this.declaredDependencies && !this.declaredDependencies.has(moduleId)) {
+            throw new MissingModuleDependencyError(this.id, moduleId);
+        }
+        return this.resolveModuleContext(moduleId);
     }
     /**
-     * Checks whether another module exists.
+     * Checks whether a declared dependency is available.
      */
     hasModule(moduleId) {
-        return this.moduleContexts.has(moduleId);
+        if (this.declaredDependencies && !this.declaredDependencies.has(moduleId))
+            return false;
+        return this.resolveModuleContext(moduleId) !== undefined;
     }
 }
 /**
  * Creates a module context.
  */
 export function createModuleContext(options) {
-    return new DefaultModuleContext(options.module, options.dependencies, options.metadata, options.moduleContexts);
+    return new DefaultModuleContext(options.module, options.dependencies, options.metadata, options.moduleContexts, options.declaredDependencies);
 }
 /**
  * Type guard for ModuleContext.

package/dist/modules/moduleDefinition.definition.d.ts

@@ -1,5 +1,12 @@
 import type { Module, ModuleId, ModuleOptions } from "./module.js";
 import type { ModuleMetadata } from "./moduleMetadata.metadata.js";
+/**
+ * Recursively freezes a module options tree.
+ *
+ * Already frozen nodes are skipped. Only plain objects and
+ * arrays are traversed; class instances are frozen shallowly.
+ */
+export declare function deepFreezeModuleOptions<T>(value: T): T;
 /**
  * Factory used to create a module instance.
  *
@@ -65,14 +72,12 @@ export interface ModuleDefinition<TModule extends Module = Module> {
      * Whether the module should be automatically loaded.
      *
      * Defaults to true.
-     */
-    readonly autoLoad?: boolean;
-    /**
-     * Whether multiple instances of this module are allowed.
      *
-     * Defaults to false.
+     * A module with autoLoad disabled is still loaded when it is
+     * requested explicitly or when another loading module requires
+     * it as a dependency.
      */
-    readonly multiInstance?: boolean;
+    readonly autoLoad?: boolean;
 }
 /**
  * Options used when creating a module definition.
@@ -86,7 +91,6 @@ export interface DefineModuleOptions<TModule extends Module = Module> {
     readonly metadata?: ModuleMetadata;
     readonly options?: ModuleOptions;
     readonly autoLoad?: boolean;
-    readonly multiInstance?: boolean;
 }
 /**
  * Creates an immutable module definition.

package/dist/modules/moduleDefinition.definition.js

@@ -1,3 +1,27 @@
+import { InvalidModuleDefinitionError } from "./moduleError/moduleError.registration.js";
+/**
+ * Recursively freezes a module options tree.
+ *
+ * Already frozen nodes are skipped. Only plain objects and
+ * arrays are traversed; class instances are frozen shallowly.
+ */
+export function deepFreezeModuleOptions(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Object.isFrozen(value))
+        return value;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            deepFreezeModuleOptions(item);
+        return Object.freeze(value);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === Object.prototype || prototype === null) {
+        for (const child of Object.values(value))
+            deepFreezeModuleOptions(child);
+    }
+    return Object.freeze(value);
+}
 /**
  * Creates an immutable module definition.
  *
@@ -12,9 +36,10 @@ export function defineModule(options) {
         factory: options.factory,
         dependencies: normalizeDependencies(options.dependencies),
         metadata: options.metadata,
-        options: options.options,
+        options: options.options
+            ? deepFreezeModuleOptions({ ...options.options })
+            : undefined,
         autoLoad: options.autoLoad ?? true,
-        multiInstance: options.multiInstance ?? false,
     });
 }
 /**
@@ -74,26 +99,34 @@ export function isModuleDefinition(value) {
  */
 function validateModuleDefinition(definition) {
     if (!definition.id || definition.id.trim().length === 0) {
-        throw new TypeError("Module definition requires a non-empty id.");
+        throw new InvalidModuleDefinitionError("Module definition requires a non-empty id.");
+    }
+    /*
+     * Ids are canonicalized once here: a definition whose id would
+     * change under trim() is rejected so the registry, loader, and
+     * lifecycle can use definition.id directly everywhere.
+     */
+    if (definition.id !== definition.id.trim()) {
+        throw new InvalidModuleDefinitionError(`Module id "${definition.id}" must not contain leading or trailing whitespace.`, definition.id);
     }
     if (!definition.name || definition.name.trim().length === 0) {
-        throw new TypeError(`Module "${definition.id}" requires a non-empty name.`);
+        throw new InvalidModuleDefinitionError(`Module "${definition.id}" requires a non-empty name.`, definition.id);
     }
     if (typeof definition.factory !== "function") {
-        throw new TypeError(`Module "${definition.id}" requires a factory function.`);
+        throw new InvalidModuleDefinitionError(`Module "${definition.id}" requires a factory function.`, definition.id);
     }
     const dependencies = definition.dependencies ?? [];
     const dependencyIds = new Set();
     for (const dependency of dependencies) {
         const id = typeof dependency === "string" ? dependency : dependency.id;
         if (!id || id.trim().length === 0) {
-            throw new TypeError(`Module "${definition.id}" contains an invalid dependency.`);
+            throw new InvalidModuleDefinitionError(`Module "${definition.id}" contains an invalid dependency.`, definition.id);
         }
         if (id === definition.id) {
-            throw new TypeError(`Module "${definition.id}" cannot depend on itself.`);
+            throw new InvalidModuleDefinitionError(`Module "${definition.id}" cannot depend on itself.`, definition.id);
         }
         if (dependencyIds.has(id)) {
-            throw new TypeError(`Module "${definition.id}" declares dependency "${id}" more than once.`);
+            throw new InvalidModuleDefinitionError(`Module "${definition.id}" declares dependency "${id}" more than once.`, definition.id);
         }
         dependencyIds.add(id);
     }

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

@@ -4,7 +4,7 @@
  * Dependency graph types, validation, and topological ordering
  * for module dependency resolution.
  */
-export { type ModuleDependency, type ModuleDependencies, type ModuleDependencyNode, type ModuleDependencyGraph, type ModuleDependencyInput, } from "./moduleDependency.type.js";
-export { normalizeModuleDependency, normalizeModuleDependencies, validateModuleDependencies, validateModuleDependencyGraph, createModuleDependencyGraph, createModuleDependency, isOptionalModuleDependency, hasModuleVersionConstraint, } from "./moduleDependency.graph.js";
+export { type ModuleDependency, type ModuleDependencies, type ModuleDependencyNode, type ModuleDependencyGraph, type ModuleDependencyInput, type ModuleDependencyNodeInput, } from "./moduleDependency.type.js";
+export { normalizeModuleDependency, normalizeModuleDependencies, validateModuleDependencies, validateModuleDependencyGraph, createModuleDependencyGraph, createModuleDependency, isOptionalModuleDependency, hasModuleVersionConstraint, satisfiesModuleVersionConstraint, } from "./moduleDependency.graph.js";
 export { findModuleDependencyCycle, hasModuleDependencyCycle, resolveModuleStartupOrder, resolveModuleShutdownOrder, } from "./moduleDependency.ordering.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleDependency/index.js

@@ -5,6 +5,6 @@
  * for module dependency resolution.
  */
 export {} from "./moduleDependency.type.js";
-export { normalizeModuleDependency, normalizeModuleDependencies, validateModuleDependencies, validateModuleDependencyGraph, createModuleDependencyGraph, createModuleDependency, isOptionalModuleDependency, hasModuleVersionConstraint, } from "./moduleDependency.graph.js";
+export { normalizeModuleDependency, normalizeModuleDependencies, validateModuleDependencies, validateModuleDependencyGraph, createModuleDependencyGraph, createModuleDependency, isOptionalModuleDependency, hasModuleVersionConstraint, satisfiesModuleVersionConstraint, } from "./moduleDependency.graph.js";
 export { findModuleDependencyCycle, hasModuleDependencyCycle, resolveModuleStartupOrder, resolveModuleShutdownOrder, } from "./moduleDependency.ordering.js";
 //# sourceMappingURL=index.js.map

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

@@ -1,5 +1,5 @@
 import type { ModuleId } from "../module.js";
-import type { ModuleDependency, ModuleDependencies, ModuleDependencyNode, ModuleDependencyGraph, ModuleDependencyInput } from "./moduleDependency.type.js";
+import type { ModuleDependency, ModuleDependencies, ModuleDependencyGraph, ModuleDependencyInput, ModuleDependencyNodeInput } from "./moduleDependency.type.js";
 /**
  * Normalizes a dependency declaration.
  */
@@ -18,7 +18,7 @@ export declare function validateModuleDependencies(moduleId: ModuleId, dependenc
  * This function validates duplicate nodes and self-dependencies,
  * but deliberately does not perform topological sorting.
  */
-export declare function createModuleDependencyGraph(nodes: readonly ModuleDependencyNode[]): ModuleDependencyGraph;
+export declare function createModuleDependencyGraph(nodes: readonly ModuleDependencyNodeInput[]): ModuleDependencyGraph;
 /**
  * Validates that all required dependencies exist.
  *
@@ -40,4 +40,21 @@ export declare function isOptionalModuleDependency(dependency: ModuleDependency)
  * Checks whether a dependency has a version constraint.
  */
 export declare function hasModuleVersionConstraint(dependency: ModuleDependency): boolean;
+/**
+ * Checks whether a module version satisfies a constraint.
+ *
+ * Supported constraint forms:
+ *
+ * 1.2.3      exact match
+ * ^1.2.3     compatible within the same major (same minor for 0.x)
+ * ~1.2.3     compatible within the same minor
+ * >=1.2.3    at least
+ * >1.2.3     greater than
+ * <=1.2.3    at most
+ * <1.2.3     less than
+ *
+ * A dependency with a declared constraint is NOT satisfied when
+ * the dependency module declares no version at all.
+ */
+export declare function satisfiesModuleVersionConstraint(constraint: string, version: string | undefined): boolean;
 //# sourceMappingURL=moduleDependency.graph.d.ts.map

package/dist/modules/moduleDependency/moduleDependency.graph.js

@@ -1,3 +1,5 @@
+import { InvalidModuleDependencyError, ModuleVersionMismatchError, } from "../moduleError/moduleError.dependency.js";
+import { InvalidModuleDefinitionError } from "../moduleError/moduleError.registration.js";
 /**
  * Normalizes a dependency declaration.
  */
@@ -5,7 +7,7 @@ export function normalizeModuleDependency(dependency) {
     if (typeof dependency === "string") {
         const id = dependency.trim();
         if (!id) {
-            throw new TypeError("Module dependency id cannot be empty.");
+            throw new InvalidModuleDependencyError("Module dependency id cannot be empty.");
         }
         return Object.freeze({
             id,
@@ -14,7 +16,7 @@ export function normalizeModuleDependency(dependency) {
     }
     const id = dependency.id?.trim();
     if (!id) {
-        throw new TypeError("Module dependency id cannot be empty.");
+        throw new InvalidModuleDependencyError("Module dependency id cannot be empty.");
     }
     return Object.freeze({
         id,
@@ -34,7 +36,7 @@ export function normalizeModuleDependencies(dependencies) {
     for (const dependency of dependencies) {
         const item = normalizeModuleDependency(dependency);
         if (seen.has(item.id)) {
-            throw new TypeError(`Module dependency "${item.id}" is declared more than once.`);
+            throw new InvalidModuleDependencyError(`Module dependency "${item.id}" is declared more than once.`, { dependencyId: item.id });
         }
         seen.add(item.id);
         normalized.push(item);
@@ -47,15 +49,15 @@ export function normalizeModuleDependencies(dependencies) {
 export function validateModuleDependencies(moduleId, dependencies) {
     const normalizedModuleId = moduleId.trim();
     if (!normalizedModuleId) {
-        throw new TypeError("Module id cannot be empty.");
+        throw new InvalidModuleDefinitionError("Module id cannot be empty.");
     }
     for (const dependency of dependencies) {
         if (dependency.id === normalizedModuleId) {
-            throw new TypeError(`Module "${normalizedModuleId}" cannot depend on itself.`);
+            throw new InvalidModuleDependencyError(`Module "${normalizedModuleId}" cannot depend on itself.`, { moduleId: normalizedModuleId, dependencyId: dependency.id });
         }
         if (dependency.version !== undefined &&
             !isValidVersionConstraint(dependency.version)) {
-            throw new TypeError(`Invalid version constraint "${dependency.version}" for module dependency "${dependency.id}".`);
+            throw new InvalidModuleDependencyError(`Invalid version constraint "${dependency.version}" for module dependency "${dependency.id}".`, { moduleId: normalizedModuleId, dependencyId: dependency.id });
         }
     }
 }
@@ -70,18 +72,36 @@ export function createModuleDependencyGraph(nodes) {
     for (const node of nodes) {
         const id = node.id.trim();
         if (!id) {
-            throw new TypeError("Module dependency graph nodes require a non-empty id.");
+            throw new InvalidModuleDefinitionError("Module dependency graph nodes require a non-empty id.");
         }
         if (nodeMap.has(id)) {
-            throw new TypeError(`Module "${id}" appears more than once in the dependency graph.`);
+            throw new InvalidModuleDefinitionError(`Module "${id}" appears more than once in the dependency graph.`, id);
         }
         const dependencies = normalizeModuleDependencies(node.dependencies);
         validateModuleDependencies(id, dependencies);
         nodeMap.set(id, Object.freeze({
             id,
             dependencies,
+            version: node.version,
         }));
     }
+    /*
+     * Version constraints are enforced while building the graph:
+     * every dependency with a declared constraint must be satisfied
+     * by the dependency module's declared version.
+     */
+    for (const node of nodeMap.values()) {
+        for (const dependency of node.dependencies) {
+            if (dependency.version === undefined)
+                continue;
+            const target = nodeMap.get(dependency.id);
+            if (!target)
+                continue;
+            if (!satisfiesModuleVersionConstraint(dependency.version, target.version)) {
+                throw new ModuleVersionMismatchError(dependency.id, dependency.version, target.version);
+            }
+        }
+    }
     const readonlyNodes = new Map(nodeMap);
     return {
         nodes: readonlyNodes,
@@ -172,4 +192,98 @@ function normalizeVersionConstraint(value) {
 function isValidVersionConstraint(value) {
     return /^(?:[<>=~^]*\s*)?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\s*)$/.test(value);
 }
+/**
+ * Parses a semantic version string.
+ */
+function parseSemanticVersion(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value.trim());
+    if (!match) {
+        return undefined;
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4],
+    };
+}
+/**
+ * Compares two parsed semantic versions.
+ *
+ * Returns a negative value when a < b, zero when equal, and a
+ * positive value when a > b. Prerelease identifiers sort below
+ * their release version but are not compared to each other in
+ * detail; this is a deliberately simple comparison.
+ */
+function compareSemanticVersions(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    if (a.patch !== b.patch)
+        return a.patch - b.patch;
+    if (a.prerelease && !b.prerelease)
+        return -1;
+    if (!a.prerelease && b.prerelease)
+        return 1;
+    return 0;
+}
+/**
+ * Checks whether a module version satisfies a constraint.
+ *
+ * Supported constraint forms:
+ *
+ * 1.2.3      exact match
+ * ^1.2.3     compatible within the same major (same minor for 0.x)
+ * ~1.2.3     compatible within the same minor
+ * >=1.2.3    at least
+ * >1.2.3     greater than
+ * <=1.2.3    at most
+ * <1.2.3     less than
+ *
+ * A dependency with a declared constraint is NOT satisfied when
+ * the dependency module declares no version at all.
+ */
+export function satisfiesModuleVersionConstraint(constraint, version) {
+    const trimmedConstraint = constraint.trim();
+    // `(\S.*)` rather than `(.+)`: `.` matches spaces too, so `\s*(.+)` lets the
+    // engine split a whitespace run at every position before giving up.
+    const operatorMatch = /^(\^|~|>=|<=|>|<)?\s*(\S.*)$/.exec(trimmedConstraint);
+    if (!operatorMatch)
+        return false;
+    const operator = operatorMatch[1] ?? "";
+    const base = parseSemanticVersion(operatorMatch[2] ?? "");
+    if (!base)
+        return false;
+    if (version === undefined)
+        return false;
+    const actual = parseSemanticVersion(version);
+    if (!actual)
+        return false;
+    const comparison = compareSemanticVersions(actual, base);
+    switch (operator) {
+        case "":
+            return comparison === 0;
+        case "^":
+            if (actual.major !== base.major)
+                return false;
+            if (base.major === 0 && actual.minor !== base.minor)
+                return false;
+            return comparison >= 0;
+        case "~":
+            return (actual.major === base.major &&
+                actual.minor === base.minor &&
+                comparison >= 0);
+        case ">=":
+            return comparison >= 0;
+        case ">":
+            return comparison > 0;
+        case "<=":
+            return comparison <= 0;
+        case "<":
+            return comparison < 0;
+        default:
+            return false;
+    }
+}
 //# sourceMappingURL=moduleDependency.graph.js.map

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

@@ -4,6 +4,10 @@ import type { ModuleDependencyGraph } from "./moduleDependency.type.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 declare function findModuleDependencyCycle(graph: ModuleDependencyGraph): readonly ModuleId[] | undefined;
 /**
@@ -26,6 +30,10 @@ export declare function hasModuleDependencyCycle(graph: ModuleDependencyGraph):
  * 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 declare function resolveModuleStartupOrder(graph: ModuleDependencyGraph): readonly ModuleId[];
 /**