@zudojs/core 0.0.1

package/dist/modules/module.d.ts

@@ -0,0 +1,171 @@
+import type { ApplicationContext } from "../application/applicationContext.context.js";
+import type { LifecycleScope } from "../lifecycle/scope/lifecycleScope.scope.js";
+import type { ModuleContext } from "./moduleContext.context.js";
+/**
+ * Unique identifier for a module.
+ */
+export type ModuleId = string;
+/**
+ * Configuration supplied to a module during creation.
+ */
+export type ModuleOptions = Readonly<Record<string, unknown>>;
+/**
+ * Lifecycle hooks supported by a module.
+ *
+ * Modules can implement only the hooks they need.
+ */
+export interface ModuleLifecycle {
+    /**
+     * Called when the module is initialized.
+     */
+    onInitialize?(context: ModuleContext): void | Promise<void>;
+    /**
+     * Called after all modules have been initialized.
+     *
+     * This is useful when a module depends on other modules
+     * being fully ready before performing startup work.
+     */
+    onReady?(context: ModuleContext): void | Promise<void>;
+    /**
+     * Called when the application begins shutting down.
+     */
+    onShutdown?(context: ModuleContext): void | Promise<void>;
+    /**
+     * Called when the module is destroyed.
+     */
+    onDestroy?(context: ModuleContext): void | Promise<void>;
+}
+/**
+ * Base contract implemented by Zudojs modules.
+ *
+ * A module represents an independently manageable unit of
+ * application functionality.
+ *
+ * Examples:
+ *
+ * AuthModule
+ * UserModule
+ * PaymentModule
+ * OrderModule
+ * NotificationModule
+ *
+ * The same module contract works inside a monolith,
+ * modular monolith, or independent microservice.
+ */
+export interface Module extends ModuleLifecycle {
+    /**
+     * Unique module identifier.
+     */
+    readonly id: ModuleId;
+    /**
+     * Human-readable module name.
+     */
+    readonly name: string;
+    /**
+     * Optional semantic version of the module.
+     */
+    readonly version?: string;
+    /**
+     * Other modules required by this module.
+     */
+    readonly dependencies?: readonly ModuleId[];
+    /**
+     * Optional module configuration.
+     */
+    readonly options?: ModuleOptions;
+    /**
+     * Optional lifecycle scope.
+     *
+     * This describes how long resources owned by the module
+     * should live.
+     */
+    readonly scope?: LifecycleScope;
+    /**
+     * Called when the module is attached to an application.
+     *
+     * Optional. Modules that need access to the application context
+     * can implement this method.
+     */
+    attach?(application: unknown): void;
+}
+/**
+ * Abstract base class for modules.
+ *
+ * Framework users can extend this instead of implementing
+ * the Module interface manually.
+ */
+export declare abstract class BaseModule implements Module {
+    /**
+     * Unique module identifier.
+     */
+    abstract readonly id: ModuleId;
+    /**
+     * Human-readable module name.
+     */
+    abstract readonly name: string;
+    /**
+     * Optional semantic version.
+     */
+    readonly version?: string;
+    /**
+     * Module dependencies.
+     */
+    readonly dependencies: readonly ModuleId[];
+    /**
+     * Module-specific options.
+     */
+    readonly options: ModuleOptions;
+    /**
+     * Lifecycle scope.
+     */
+    readonly scope?: LifecycleScope;
+    /**
+     * Application context becomes available after the module
+     * has been attached to an application.
+     */
+    protected applicationContext?: ApplicationContext;
+    protected constructor(options?: {
+        readonly version?: string;
+        readonly dependencies?: readonly ModuleId[];
+        readonly options?: ModuleOptions;
+        readonly scope?: LifecycleScope;
+    });
+    /**
+     * Called internally by the module runtime when the module
+     * becomes associated with an application.
+     */
+    attach(context: ApplicationContext): void;
+    /**
+     * Returns the application context.
+     *
+     * Throws if the module has not yet been attached.
+     */
+    protected getApplicationContext(): ApplicationContext;
+    /**
+     * Module initialization hook.
+     */
+    onInitialize(_context: ModuleContext): Promise<void>;
+    /**
+     * Module ready hook.
+     */
+    onReady(_context: ModuleContext): Promise<void>;
+    /**
+     * Module shutdown hook.
+     */
+    onShutdown(_context: ModuleContext): Promise<void>;
+    /**
+     * Module destruction hook.
+     */
+    onDestroy(_context: ModuleContext): Promise<void>;
+}
+/**
+ * Type guard for determining whether an object is a Module.
+ */
+export declare function isModule(value: unknown): value is Module;
+/**
+ * Creates a lightweight module definition.
+ *
+ * Useful for modules that do not require a class.
+ */
+export declare function createModule(definition: Module): Module;
+//# sourceMappingURL=module.d.ts.map

package/dist/modules/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../src/modules/module.ts"],"names":[],"mappings":"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"}

package/dist/modules/module.js

@@ -0,0 +1,99 @@
+/**
+ * Abstract base class for modules.
+ *
+ * Framework users can extend this instead of implementing
+ * the Module interface manually.
+ */
+export class BaseModule {
+    /**
+     * Optional semantic version.
+     */
+    version;
+    /**
+     * Module dependencies.
+     */
+    dependencies;
+    /**
+     * Module-specific options.
+     */
+    options;
+    /**
+     * Lifecycle scope.
+     */
+    scope;
+    /**
+     * Application context becomes available after the module
+     * has been attached to an application.
+     */
+    applicationContext;
+    constructor(options = {}) {
+        this.version = options.version;
+        this.dependencies = [...(options.dependencies ?? [])];
+        this.options = options.options ?? {};
+        this.scope = options.scope;
+    }
+    /**
+     * Called internally by the module runtime when the module
+     * becomes associated with an application.
+     */
+    attach(context) {
+        this.applicationContext = context;
+    }
+    /**
+     * Returns the application context.
+     *
+     * Throws if the module has not yet been attached.
+     */
+    getApplicationContext() {
+        if (!this.applicationContext) {
+            throw new Error(`Module "${this.name}" has not been attached to an application.`);
+        }
+        return this.applicationContext;
+    }
+    /**
+     * Module initialization hook.
+     */
+    async onInitialize(_context) {
+        // Optional hook.
+    }
+    /**
+     * Module ready hook.
+     */
+    async onReady(_context) {
+        // Optional hook.
+    }
+    /**
+     * Module shutdown hook.
+     */
+    async onShutdown(_context) {
+        // Optional hook.
+    }
+    /**
+     * Module destruction hook.
+     */
+    async onDestroy(_context) {
+        // Optional hook.
+    }
+}
+/**
+ * Type guard for determining whether an object is a Module.
+ */
+export function isModule(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.id === "string" &&
+        candidate.id.length > 0 &&
+        typeof candidate.name === "string" &&
+        candidate.name.length > 0);
+}
+/**
+ * Creates a lightweight module definition.
+ *
+ * Useful for modules that do not require a class.
+ */
+export function createModule(definition) {
+    return definition;
+}
+//# sourceMappingURL=module.js.map

package/dist/modules/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../../src/modules/module.ts"],"names":[],"mappings":"AA0GA;;;;;GAKG;AACH,MAAM,OAAgB,UAAU;IAW9B;;OAEG;IACa,OAAO,CAAU;IAEjC;;OAEG;IACa,YAAY,CAAsB;IAElD;;OAEG;IACa,OAAO,CAAgB;IAEvC;;OAEG;IACa,KAAK,CAAkB;IAEvC;;;OAGG;IACO,kBAAkB,CAAsB;IAElD,YACE,OAAO,GAKH,EAAE;QAEN,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;QAE/B,IAAI,CAAC,YAAY,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC,CAAC,CAAC;QAEtD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;QAErC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACI,MAAM,CAAC,OAA2B;QACvC,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC;IACpC,CAAC;IAED;;;;OAIG;IACO,qBAAqB;QAC7B,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CACb,WAAW,IAAI,CAAC,IAAI,4CAA4C,CACjE,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACjC,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,YAAY,CAAC,QAAuB;QAC/C,iBAAiB;IACnB,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,OAAO,CAAC,QAAuB;QAC1C,iBAAiB;IACnB,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,UAAU,CAAC,QAAuB;QAC7C,iBAAiB;IACnB,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,SAAS,CAAC,QAAuB;QAC5C,iBAAiB;IACnB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,KAAwB,CAAC;IAE3C,OAAO,CACL,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ;QAChC,SAAS,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC;QACvB,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ;QAClC,SAAS,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAC1B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC7C,OAAO,UAAU,CAAC;AACpB,CAAC"}

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

@@ -0,0 +1,170 @@
+import type { ApplicationContext } from "../application/applicationContext.context.js";
+import type { ConfigurationManager } from "../configuration/configurationManager.manager.js";
+import type { Configuration } from "../configuration/core/configuration.js";
+import type { Logger } from "../logging/core/logger.js";
+import type { LifecycleScope } from "../lifecycle/scope/lifecycleScope.scope.js";
+import type { Module, ModuleId, ModuleOptions } from "./module.js";
+import type { ModuleMetadata } from "./moduleMetadata.metadata.js";
+/**
+ * Dependencies exposed to a module through its context.
+ *
+ * This is intentionally a narrow interface. The module should
+ * receive capabilities, not unrestricted access to the runtime.
+ */
+export interface ModuleContextDependencies {
+    /**
+     * Application context.
+     */
+    readonly application: ApplicationContext;
+    /**
+     * Configuration manager.
+     */
+    readonly configuration: ConfigurationManager;
+    /**
+     * Module-scoped logger.
+     */
+    readonly logger: Logger;
+}
+/**
+ * Immutable information describing the current module.
+ */
+export interface ModuleContextInfo {
+    /**
+     * Module identifier.
+     */
+    readonly id: ModuleId;
+    /**
+     * Module name.
+     */
+    readonly name: string;
+    /**
+     * Module version.
+     */
+    readonly version?: string;
+    /**
+     * Module metadata.
+     */
+    readonly metadata?: ModuleMetadata;
+    /**
+     * Module options.
+     */
+    readonly options: ModuleOptions;
+    /**
+     * Lifecycle scope.
+     */
+    readonly scope?: LifecycleScope;
+}
+/**
+ * Context supplied to a module during its lifecycle.
+ *
+ * ModuleContext is deliberately narrower than ApplicationContext.
+ * It gives modules controlled access to framework capabilities.
+ */
+export interface ModuleContext extends ModuleContextInfo {
+    /**
+     * Application-level context.
+     *
+     * This is exposed as a typed capability rather than requiring
+     * modules to import and manipulate the application directly.
+     */
+    readonly application: ApplicationContext;
+    /**
+     * Configuration manager.
+     */
+    readonly configuration: ConfigurationManager;
+    /**
+     * Logger scoped to this module.
+     */
+    readonly logger: Logger;
+    /**
+     * Gets the current configuration snapshot.
+     */
+    getConfiguration(): Configuration;
+    /**
+     * Gets a configuration value.
+     */
+    getConfig<T = unknown>(path: string): T | undefined;
+    /**
+     * Gets a required configuration value.
+     */
+    requireConfig<T = unknown>(path: string): T;
+    /**
+     * Returns another module's context.
+     *
+     * This should only be used for declared module dependencies.
+     */
+    getModuleContext(moduleId: ModuleId): ModuleContext | undefined;
+    /**
+     * Returns whether another module is available.
+     */
+    hasModule(moduleId: ModuleId): boolean;
+}
+/**
+ * Internal implementation of ModuleContext.
+ *
+ * The public ModuleContext interface is intentionally small,
+ * while this implementation owns the actual state.
+ */
+export declare class DefaultModuleContext implements ModuleContext {
+    readonly id: ModuleId;
+    readonly name: string;
+    readonly version?: string;
+    readonly metadata?: ModuleMetadata;
+    readonly options: ModuleOptions;
+    readonly scope?: LifecycleScope;
+    readonly application: ApplicationContext;
+    readonly configuration: ConfigurationManager;
+    readonly logger: Logger;
+    private readonly moduleContexts;
+    constructor(module: Module, dependencies: ModuleContextDependencies, metadata?: ModuleMetadata, moduleContexts?: ReadonlyMap<ModuleId, ModuleContext>);
+    /**
+     * Returns the current configuration.
+     */
+    getConfiguration(): Configuration;
+    /**
+     * Gets an optional configuration value.
+     */
+    getConfig<T = unknown>(path: string): T | undefined;
+    /**
+     * Gets a required configuration value.
+     */
+    requireConfig<T = unknown>(path: string): T;
+    /**
+     * Gets the context of another module.
+     */
+    getModuleContext(moduleId: ModuleId): ModuleContext | undefined;
+    /**
+     * Checks whether another module exists.
+     */
+    hasModule(moduleId: ModuleId): boolean;
+}
+/**
+ * Options used to create a module context.
+ */
+export interface CreateModuleContextOptions {
+    /**
+     * Module instance.
+     */
+    readonly module: Module;
+    /**
+     * Application-level dependencies.
+     */
+    readonly dependencies: ModuleContextDependencies;
+    /**
+     * Optional metadata associated with the module.
+     */
+    readonly metadata?: ModuleMetadata;
+    /**
+     * Contexts of modules that have already been resolved.
+     */
+    readonly moduleContexts?: ReadonlyMap<ModuleId, ModuleContext>;
+}
+/**
+ * Creates a module context.
+ */
+export declare function createModuleContext(options: CreateModuleContextOptions): ModuleContext;
+/**
+ * Type guard for ModuleContext.
+ */
+export declare function isModuleContext(value: unknown): value is ModuleContext;
+//# sourceMappingURL=moduleContext.context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"moduleContext.context.d.ts","sourceRoot":"","sources":["../../src/modules/moduleContext.context.ts"],"names":[],"mappings":"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"}

package/dist/modules/moduleContext.context.js

@@ -0,0 +1,82 @@
+/**
+ * Internal implementation of ModuleContext.
+ *
+ * The public ModuleContext interface is intentionally small,
+ * while this implementation owns the actual state.
+ */
+export class DefaultModuleContext {
+    id;
+    name;
+    version;
+    metadata;
+    options;
+    scope;
+    application;
+    configuration;
+    logger;
+    moduleContexts;
+    constructor(module, dependencies, metadata, moduleContexts = new Map()) {
+        this.id = module.id;
+        this.name = module.name;
+        this.version = module.version;
+        this.metadata = metadata;
+        this.options = Object.freeze({
+            ...(module.options ?? {}),
+        });
+        this.scope = module.scope;
+        this.application = dependencies.application;
+        this.configuration = dependencies.configuration;
+        this.logger = dependencies.logger;
+        this.moduleContexts = moduleContexts;
+    }
+    /**
+     * Returns the current configuration.
+     */
+    getConfiguration() {
+        return this.configuration.getConfiguration();
+    }
+    /**
+     * Gets an optional configuration value.
+     */
+    getConfig(path) {
+        return this.configuration.get(path);
+    }
+    /**
+     * Gets a required configuration value.
+     */
+    requireConfig(path) {
+        return this.configuration.require(path);
+    }
+    /**
+     * Gets the context of another module.
+     */
+    getModuleContext(moduleId) {
+        return this.moduleContexts.get(moduleId);
+    }
+    /**
+     * Checks whether another module exists.
+     */
+    hasModule(moduleId) {
+        return this.moduleContexts.has(moduleId);
+    }
+}
+/**
+ * Creates a module context.
+ */
+export function createModuleContext(options) {
+    return new DefaultModuleContext(options.module, options.dependencies, options.metadata, options.moduleContexts);
+}
+/**
+ * Type guard for ModuleContext.
+ */
+export function isModuleContext(value) {
+    if (value === null || typeof value !== "object") {
+        return false;
+    }
+    const context = value;
+    return (typeof context.id === "string" &&
+        typeof context.name === "string" &&
+        typeof context.getConfig === "function" &&
+        typeof context.requireConfig === "function");
+}
+//# sourceMappingURL=moduleContext.context.js.map

package/dist/modules/moduleContext.context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleContext.context.js","sourceRoot":"","sources":["../../src/modules/moduleContext.context.ts"],"names":[],"mappings":"AA+HA;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IACf,EAAE,CAAW;IAEb,IAAI,CAAS;IAEb,OAAO,CAAU;IAEjB,QAAQ,CAAkB;IAE1B,OAAO,CAAgB;IAEvB,KAAK,CAAkB;IAEvB,WAAW,CAAqB;IAEhC,aAAa,CAAuB;IAEpC,MAAM,CAAS;IAEd,cAAc,CAAuC;IAEtE,YACE,MAAc,EACd,YAAuC,EACvC,QAAyB,EACzB,cAAc,GAAyC,IAAI,GAAG,EAAE;QAEhE,IAAI,CAAC,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QAEpB,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QAExB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAE9B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAEzB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;YAC3B,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;SAC1B,CAAC,CAAC;QAEH,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAE1B,IAAI,CAAC,WAAW,GAAG,YAAY,CAAC,WAAW,CAAC;QAE5C,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC,aAAa,CAAC;QAEhD,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC;QAElC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;IAED;;OAEG;IACI,gBAAgB;QACrB,OAAO,IAAI,CAAC,aAAa,CAAC,gBAAgB,EAAE,CAAC;IAC/C,CAAC;IAED;;OAEG;IACI,SAAS,CAAc,IAAY;QACxC,OAAO,IAAI,CAAC,aAAa,CAAC,GAAG,CAAI,IAAI,CAAC,CAAC;IACzC,CAAC;IAED;;OAEG;IACI,aAAa,CAAc,IAAY;QAC5C,OAAO,IAAI,CAAC,aAAa,CAAC,OAAO,CAAI,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACI,gBAAgB,CAAC,QAAkB;QACxC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACI,SAAS,CAAC,QAAkB;QACjC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3C,CAAC;CACF;AA2BD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAmC;IAEnC,OAAO,IAAI,oBAAoB,CAC7B,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,YAAY,EACpB,OAAO,CAAC,QAAQ,EAChB,OAAO,CAAC,cAAc,CACvB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,KAA+B,CAAC;IAEhD,OAAO,CACL,OAAO,OAAO,CAAC,EAAE,KAAK,QAAQ;QAC9B,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ;QAChC,OAAO,OAAO,CAAC,SAAS,KAAK,UAAU;QACvC,OAAO,OAAO,CAAC,aAAa,KAAK,UAAU,CAC5C,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,112 @@
+import type { Module, ModuleId, ModuleOptions } from "./module.js";
+import type { ModuleMetadata } from "./moduleMetadata.metadata.js";
+/**
+ * Factory used to create a module instance.
+ *
+ * The factory receives the module's resolved options.
+ */
+export type ModuleFactory<TModule extends Module = Module> = (options?: ModuleOptions) => TModule;
+/**
+ * Defines a module dependency.
+ *
+ * This is intentionally more expressive than simply using
+ * a ModuleId because future versions of the framework may
+ * need optional or versioned dependencies.
+ */
+export interface ModuleDependencyDefinition {
+    /**
+     * Identifier of the required module.
+     */
+    readonly id: ModuleId;
+    /**
+     * Whether the dependency is optional.
+     *
+     * Defaults to false.
+     */
+    readonly optional?: boolean;
+    /**
+     * Optional version constraint.
+     */
+    readonly version?: string;
+}
+/**
+ * Complete static definition of a Zudojs module.
+ */
+export interface ModuleDefinition<TModule extends Module = Module> {
+    /**
+     * Unique module identifier.
+     */
+    readonly id: ModuleId;
+    /**
+     * Human-readable module name.
+     */
+    readonly name: string;
+    /**
+     * Optional semantic version.
+     */
+    readonly version?: string;
+    /**
+     * Factory used to create the module instance.
+     */
+    readonly factory: ModuleFactory<TModule>;
+    /**
+     * Dependencies required by the module.
+     */
+    readonly dependencies?: readonly (ModuleId | ModuleDependencyDefinition)[];
+    /**
+     * Static module metadata.
+     */
+    readonly metadata?: ModuleMetadata;
+    /**
+     * Default module options.
+     */
+    readonly options?: ModuleOptions;
+    /**
+     * Whether the module should be automatically loaded.
+     *
+     * Defaults to true.
+     */
+    readonly autoLoad?: boolean;
+    /**
+     * Whether multiple instances of this module are allowed.
+     *
+     * Defaults to false.
+     */
+    readonly multiInstance?: boolean;
+}
+/**
+ * Options used when creating a module definition.
+ */
+export interface DefineModuleOptions<TModule extends Module = Module> {
+    readonly id: ModuleId;
+    readonly name: string;
+    readonly version?: string;
+    readonly factory: ModuleFactory<TModule>;
+    readonly dependencies?: readonly (ModuleId | ModuleDependencyDefinition)[];
+    readonly metadata?: ModuleMetadata;
+    readonly options?: ModuleOptions;
+    readonly autoLoad?: boolean;
+    readonly multiInstance?: boolean;
+}
+/**
+ * Creates an immutable module definition.
+ *
+ * A definition describes a module but does not instantiate it.
+ */
+export declare function defineModule<TModule extends Module = Module>(options: DefineModuleOptions<TModule>): ModuleDefinition<TModule>;
+/**
+ * Converts a Module instance into a module definition.
+ *
+ * Useful when a module has already been implemented as a class.
+ */
+export declare function moduleToDefinition<TModule extends Module>(module: TModule, factory?: ModuleFactory<TModule>): ModuleDefinition<TModule>;
+/**
+ * Normalizes dependency declarations into a consistent
+ * representation.
+ */
+export declare function normalizeDependencies(dependencies?: readonly (ModuleId | ModuleDependencyDefinition)[]): readonly ModuleDependencyDefinition[];
+/**
+ * Checks whether a value is a valid module definition.
+ */
+export declare function isModuleDefinition(value: unknown): value is ModuleDefinition;
+//# sourceMappingURL=moduleDefinition.definition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"moduleDefinition.definition.d.ts","sourceRoot":"","sources":["../../src/modules/moduleDefinition.definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAEnE;;;;GAIG;AACH,MAAM,MAAM,aAAa,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,CAC3D,OAAO,CAAC,EAAE,aAAa,KACpB,OAAO,CAAC;AAEb;;;;;;GAMG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IAC/D;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,QAAQ,GAAG,0BAA0B,CAAC,EAAE,CAAC;IAE3E;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IAClE,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IAEtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAEzC,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,CAAC,QAAQ,GAAG,0BAA0B,CAAC,EAAE,CAAC;IAE3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAEnC,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAEjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAE5B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,EAC1D,OAAO,EAAE,mBAAmB,CAAC,OAAO,CAAC,GACpC,gBAAgB,CAAC,OAAO,CAAC,CAc3B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,SAAS,MAAM,EACvD,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,GAC/B,gBAAgB,CAAC,OAAO,CAAC,CAS3B;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,CAAC,EAAE,SAAS,CAAC,QAAQ,GAAG,0BAA0B,CAAC,EAAE,GAChE,SAAS,0BAA0B,EAAE,CAqBvC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAc5E"}