@chidchanun/bcp 0.3.1 → 0.3.2

package/packages/server/src/modules.ts

@@ -0,0 +1,682 @@
+import {
+    type ServiceContainer,
+    type ServiceProvider,
+    type ServiceToken,
+} from "./container.js";
+
+import {
+    type DeploymentResource,
+} from "./deployment.js";
+
+import {
+    type PluginDefinition,
+    type PluginHookBus,
+    type PluginServiceKey,
+    type PluginServiceRegistry,
+} from "./plugins.js";
+
+export const MODULE_V2_KIND =
+    "bcp-module-v2" as const;
+
+export interface ModuleConfigSchema<TConfig> {
+    parse(value: unknown): TConfig;
+}
+
+export type ModuleConfigParser<TConfig> =
+    | ModuleConfigSchema<TConfig>
+    | ((value: unknown) => TConfig);
+
+export interface ModuleContext<TConfig = unknown> {
+    readonly name: string;
+    readonly config: TConfig;
+    readonly container: ServiceContainer;
+    readonly services: PluginServiceRegistry;
+    readonly hooks: PluginHookBus;
+}
+
+export interface ModuleDefinition<TConfig = unknown> {
+    readonly kind: typeof MODULE_V2_KIND;
+    readonly name: string;
+    readonly version?: string;
+    readonly imports?: readonly ModuleDefinition<any>[];
+    readonly providers?: readonly ServiceProvider<any>[];
+    readonly exports?: readonly ServiceToken<any>[];
+    readonly plugins?: readonly PluginDefinition<any>[];
+    readonly services?: Iterable<
+        readonly [PluginServiceKey, unknown]
+    >;
+    readonly resources?: readonly DeploymentResource[];
+    readonly config?: unknown;
+    readonly schema?: ModuleConfigParser<TConfig>;
+    setup?(
+        context: ModuleContext<TConfig>
+    ): void | Promise<void>;
+    start?(
+        context: ModuleContext<TConfig>
+    ): void | Promise<void>;
+    stop?(
+        context: ModuleContext<TConfig>
+    ): void | Promise<void>;
+    dispose?(
+        context: ModuleContext<TConfig>
+    ): void | Promise<void>;
+}
+
+export interface ModuleInput<TConfig = unknown>
+extends Omit<ModuleDefinition<TConfig>, "kind"> {
+    kind?: typeof MODULE_V2_KIND;
+}
+
+export interface ModuleRecord {
+    name: string;
+    version?: string;
+    imports: string[];
+    providers: string[];
+    exports: string[];
+    plugins: string[];
+    resources: string[];
+}
+
+export interface ModuleComposition {
+    readonly modules: readonly ModuleDefinition<any>[];
+    readonly providers: readonly ServiceProvider<any>[];
+    readonly plugins: readonly PluginDefinition<any>[];
+    readonly services: readonly (
+        readonly [PluginServiceKey, unknown]
+    )[];
+    readonly resources: readonly DeploymentResource[];
+    records(): ModuleRecord[];
+    exportedTokens(moduleName: string): ServiceToken<any>[];
+    createLifecycleResources(
+        context: {
+            container: ServiceContainer;
+            services: PluginServiceRegistry;
+            hooks: PluginHookBus;
+        }
+    ): DeploymentResource[];
+}
+
+export class ModuleDependencyError
+extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name =
+            "ModuleDependencyError";
+    }
+}
+
+export class ModuleLifecycleError
+extends Error {
+    readonly module: string;
+    readonly phase: string;
+    readonly cause: unknown;
+
+    constructor(
+        moduleName: string,
+        phase: string,
+        cause: unknown
+    ) {
+        super(
+            `BCP Modules: ${phase} failed for module "${moduleName}": ${formatError(cause)}`
+        );
+        this.name =
+            "ModuleLifecycleError";
+        this.module = moduleName;
+        this.phase = phase;
+        this.cause = cause;
+    }
+}
+
+export function defineModule<TConfig = unknown>(
+    input: ModuleInput<TConfig>
+): ModuleDefinition<TConfig> {
+    const definition = {
+        ...input,
+        kind:
+            MODULE_V2_KIND,
+    } satisfies ModuleDefinition<TConfig>;
+
+    validateModuleDefinition(definition);
+    return definition;
+}
+
+export function isModuleDefinition(
+    value: unknown
+): value is ModuleDefinition<any> {
+    return Boolean(
+        value &&
+        typeof value === "object" &&
+        (
+            value as {
+                kind?: unknown;
+            }
+        ).kind === MODULE_V2_KIND
+    );
+}
+
+export function composeModules(
+    roots: readonly ModuleDefinition<any>[] = []
+): ModuleComposition {
+    const ordered =
+        resolveModuleOrder(roots);
+    const providers:
+        ServiceProvider<any>[] = [];
+    const plugins:
+        PluginDefinition<any>[] = [];
+    const services:
+        Array<
+            readonly [PluginServiceKey, unknown]
+        > = [];
+    const resources:
+        DeploymentResource[] = [];
+    const serviceKeys =
+        new Set<PluginServiceKey>();
+
+    for (const module of ordered) {
+        providers.push(
+            ...(module.providers ?? [])
+        );
+        plugins.push(
+            ...(module.plugins ?? [])
+        );
+        resources.push(
+            ...(module.resources ?? [])
+        );
+
+        for (
+            const entry
+            of module.services ?? []
+        ) {
+            const [key] = entry;
+            if (serviceKeys.has(key)) {
+                throw new ModuleDependencyError(
+                    `BCP Modules: duplicate shared service ${formatServiceKey(key)} while composing module "${module.name}".`
+                );
+            }
+            serviceKeys.add(key);
+            services.push(entry);
+        }
+
+        validateModuleExports(
+            module
+        );
+    }
+
+    return {
+        modules:
+            ordered,
+        providers,
+        plugins,
+        services,
+        resources,
+
+        records() {
+            return ordered.map(
+                module => ({
+                    name:
+                        module.name,
+                    ...(module.version
+                        ? {
+                            version:
+                                module.version,
+                        }
+                        : {}),
+                    imports:
+                        (
+                            module.imports ?? []
+                        ).map(
+                            dependency =>
+                                dependency.name
+                        ),
+                    providers:
+                        (
+                            module.providers ?? []
+                        ).map(
+                            provider =>
+                                provider.token.description
+                        ),
+                    exports:
+                        (
+                            module.exports ?? []
+                        ).map(
+                            token =>
+                                token.description
+                        ),
+                    plugins:
+                        (
+                            module.plugins ?? []
+                        ).map(
+                            plugin =>
+                                plugin.name
+                        ),
+                    resources:
+                        (
+                            module.resources ?? []
+                        ).map(
+                            resource =>
+                                resource.name
+                        ),
+                })
+            );
+        },
+
+        exportedTokens(moduleName) {
+            const normalized =
+                normalizeName(
+                    moduleName,
+                    "module name"
+                );
+            const module =
+                ordered.find(
+                    entry =>
+                        entry.name ===
+                        normalized
+                );
+            if (!module) {
+                throw new ModuleDependencyError(
+                    `BCP Modules: module "${normalized}" is not part of this composition.`
+                );
+            }
+            return [
+                ...(module.exports ?? []),
+            ];
+        },
+
+        createLifecycleResources(context) {
+            return ordered.flatMap(
+                module => [
+                    ...(module.resources ?? []),
+                    createModuleLifecycleResource(
+                        module,
+                        context
+                    ),
+                ]
+            );
+        },
+    };
+}
+
+export function resolveModuleOrder(
+    roots: readonly ModuleDefinition<any>[]
+): ModuleDefinition<any>[] {
+    const byName =
+        new Map<string, ModuleDefinition<any>>();
+    const visiting =
+        new Set<string>();
+    const visited =
+        new Set<string>();
+    const order:
+        ModuleDefinition<any>[] = [];
+
+    const visit = (
+        module: ModuleDefinition<any>,
+        path: string[]
+    ): void => {
+        validateModuleDefinition(module);
+        const name = module.name;
+        const existing =
+            byName.get(name);
+
+        if (
+            existing &&
+            existing !== module
+        ) {
+            throw new ModuleDependencyError(
+                `BCP Modules: duplicate module name "${name}" refers to different definitions.`
+            );
+        }
+        byName.set(name, module);
+
+        if (visited.has(name)) {
+            return;
+        }
+        if (visiting.has(name)) {
+            throw new ModuleDependencyError(
+                `BCP Modules: circular module dependency detected: ${[
+                    ...path,
+                    name,
+                ].join(" -> ")}.`
+            );
+        }
+
+        visiting.add(name);
+        for (
+            const dependency
+            of module.imports ?? []
+        ) {
+            visit(
+                dependency,
+                [
+                    ...path,
+                    name,
+                ]
+            );
+        }
+        visiting.delete(name);
+        visited.add(name);
+        order.push(module);
+    };
+
+    for (const root of roots) {
+        visit(root, []);
+    }
+
+    return order;
+}
+
+function createModuleLifecycleResource(
+    module: ModuleDefinition<any>,
+    shared: {
+        container: ServiceContainer;
+        services: PluginServiceRegistry;
+        hooks: PluginHookBus;
+    }
+): DeploymentResource {
+    const config =
+        parseModuleConfig(
+            module.schema,
+            module.config
+        );
+    const context:
+        ModuleContext<any> = {
+        name:
+            module.name,
+        config,
+        container:
+            shared.container,
+        services:
+            shared.services,
+        hooks:
+            shared.hooks,
+    };
+    let setupComplete = false;
+    let disposed = false;
+
+    return {
+        name:
+            `bcp:module:${module.name}`,
+
+        async start() {
+            try {
+                if (!setupComplete) {
+                    await runModuleHook(
+                        module,
+                        "setup",
+                        module.setup,
+                        context
+                    );
+                    setupComplete = true;
+                }
+                await runModuleHook(
+                    module,
+                    "start",
+                    module.start,
+                    context
+                );
+            } catch (error) {
+                if (!disposed) {
+                    disposed = true;
+                    try {
+                        await runModuleHook(
+                            module,
+                            "dispose",
+                            module.dispose,
+                            context
+                        );
+                    } catch (disposeError) {
+                        throw new AggregateError(
+                            [
+                                error,
+                                disposeError,
+                            ],
+                            `BCP Modules: startup and cleanup failed for module "${module.name}".`
+                        );
+                    }
+                }
+                throw error;
+            }
+        },
+
+        ready() {
+            return true;
+        },
+
+        async stop() {
+            const errors:
+                unknown[] = [];
+            try {
+                await runModuleHook(
+                    module,
+                    "stop",
+                    module.stop,
+                    context
+                );
+            } catch (error) {
+                errors.push(error);
+            }
+
+            if (!disposed) {
+                disposed = true;
+                try {
+                    await runModuleHook(
+                        module,
+                        "dispose",
+                        module.dispose,
+                        context
+                    );
+                } catch (error) {
+                    errors.push(error);
+                }
+            }
+
+            if (errors.length > 0) {
+                throw new AggregateError(
+                    errors,
+                    `BCP Modules: shutdown failed for module "${module.name}".`
+                );
+            }
+        },
+
+        diagnostics() {
+            return {
+                name:
+                    module.name,
+                ...(module.version
+                    ? {
+                        version:
+                            module.version,
+                    }
+                    : {}),
+                imports:
+                    (
+                        module.imports ?? []
+                    ).map(
+                        dependency =>
+                            dependency.name
+                    ),
+                exports:
+                    (
+                        module.exports ?? []
+                    ).map(
+                        token =>
+                            token.description
+                    ),
+            };
+        },
+    };
+}
+
+async function runModuleHook<TConfig>(
+    module: ModuleDefinition<TConfig>,
+    phase: string,
+    hook:
+        | ((
+            context: ModuleContext<TConfig>
+        ) => void | Promise<void>)
+        | undefined,
+    context: ModuleContext<TConfig>
+): Promise<void> {
+    if (!hook) {
+        return;
+    }
+    try {
+        await hook(context);
+    } catch (error) {
+        throw new ModuleLifecycleError(
+            module.name,
+            phase,
+            error
+        );
+    }
+}
+
+function validateModuleDefinition(
+    module: ModuleDefinition<any>
+): void {
+    if (
+        !module ||
+        typeof module !== "object"
+    ) {
+        throw new TypeError(
+            "BCP Modules: module must be an object."
+        );
+    }
+    if (module.kind !== MODULE_V2_KIND) {
+        throw new TypeError(
+            `BCP Modules: module kind must be "${MODULE_V2_KIND}". Use defineModule().`
+        );
+    }
+    normalizeName(
+        module.name,
+        "module name"
+    );
+
+    for (
+        const [label, value]
+        of [
+            ["imports", module.imports],
+            ["providers", module.providers],
+            ["exports", module.exports],
+            ["plugins", module.plugins],
+            ["resources", module.resources],
+        ] as const
+    ) {
+        if (
+            value !== undefined &&
+            !Array.isArray(value)
+        ) {
+            throw new TypeError(
+                `BCP Modules: ${label} must be an array.`
+            );
+        }
+    }
+
+    for (
+        const [phase, hook]
+        of [
+            ["setup", module.setup],
+            ["start", module.start],
+            ["stop", module.stop],
+            ["dispose", module.dispose],
+        ] as const
+    ) {
+        if (
+            hook !== undefined &&
+            typeof hook !== "function"
+        ) {
+            throw new TypeError(
+                `BCP Modules: ${phase} must be a function.`
+            );
+        }
+    }
+}
+
+function validateModuleExports(
+    module: ModuleDefinition<any>
+): void {
+    const available =
+        new Set<symbol>();
+
+    for (
+        const provider
+        of module.providers ?? []
+    ) {
+        available.add(
+            provider.token.id
+        );
+    }
+    for (
+        const dependency
+        of module.imports ?? []
+    ) {
+        for (
+            const token
+            of dependency.exports ?? []
+        ) {
+            available.add(token.id);
+        }
+    }
+
+    for (
+        const token
+        of module.exports ?? []
+    ) {
+        if (!available.has(token.id)) {
+            throw new ModuleDependencyError(
+                `BCP Modules: module "${module.name}" exports "${token.description}" but does not provide or import it.`
+            );
+        }
+    }
+}
+
+function parseModuleConfig<TConfig>(
+    parser:
+        ModuleConfigParser<TConfig> |
+        undefined,
+    value: unknown
+): TConfig {
+    if (!parser) {
+        return value as TConfig;
+    }
+    if (typeof parser === "function") {
+        return parser(value);
+    }
+    return parser.parse(value);
+}
+
+function normalizeName(
+    value: unknown,
+    label: string
+): string {
+    if (typeof value !== "string") {
+        throw new TypeError(
+            `BCP Modules: ${label} must be a string.`
+        );
+    }
+    const normalized =
+        value.trim();
+    if (!normalized) {
+        throw new TypeError(
+            `BCP Modules: ${label} cannot be empty.`
+        );
+    }
+    return normalized;
+}
+
+function formatServiceKey(
+    key: PluginServiceKey
+): string {
+    return typeof key === "symbol"
+        ? key.description
+            ? `Symbol(${key.description})`
+            : key.toString()
+        : key;
+}
+
+function formatError(
+    value: unknown
+): string {
+    return value instanceof Error
+        ? value.message
+        : String(value);
+}