@loutrejs/loutre 0.1.0

package/dist/runtime/di.js

@@ -0,0 +1,441 @@
+import { asModuleInstance, childPipelineOf, isArgsClass, isEnvClass, layerDefinitionOf, normalizeProvider, runInInjectionContext, tokenName, } from '../core/index.js';
+import { Logger } from './logger.js';
+export class DependencyResolutionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DependencyResolutionError';
+    }
+}
+class GraphProbeBoundary extends Error {
+    source;
+    constructor(source) {
+        super(`Graph Probe reached runtime-dependent value: ${source}`);
+        this.source = source;
+        this.name = 'GraphProbeBoundary';
+    }
+}
+export function collectRuntimeModuleGraph(roots) {
+    const modules = [];
+    const providers = [];
+    const environmentProviders = new Set();
+    const visited = new Set();
+    const visit = (moduleLike) => {
+        const module = asModuleInstance(moduleLike);
+        if (visited.has(module))
+            return;
+        visited.add(module);
+        for (const imported of module.definition.imports ?? [])
+            visit(imported);
+        modules.push(module);
+        for (const declaration of module.definition.providers ?? []) {
+            const provider = normalizeProvider(declaration);
+            if (provider.kind === 'environment') {
+                if (environmentProviders.has(provider.provide))
+                    continue;
+                environmentProviders.add(provider.provide);
+            }
+            providers.push(provider);
+        }
+    };
+    for (const root of roots)
+        visit(root);
+    return { modules, providers };
+}
+export class Container {
+    #providers = new Map();
+    #applicationCache = new Map();
+    #implementationCache = new Map();
+    #implementationConsumers = new Map();
+    #taskCache = new Map();
+    #taskConsumers = new Map();
+    #layerCache = new Map();
+    #logger;
+    #recorder;
+    #environment = new Map();
+    #arguments = new Map();
+    #probe;
+    constructor(providers, options = {}) {
+        this.#logger =
+            options instanceof Logger ? options : (options.logger ?? new Logger());
+        this.#recorder = options instanceof Logger ? undefined : options.recorder;
+        this.#probe = options instanceof Logger ? false : (options.probe ?? false);
+        if (!(options instanceof Logger)) {
+            for (const [environment, value] of options.environment ?? []) {
+                this.#environment.set(environment, value);
+            }
+            for (const [argumentsContract, value] of options.arguments ?? []) {
+                this.#arguments.set(argumentsContract, value);
+            }
+        }
+        for (const provider of providers) {
+            const existing = this.#providers.get(provider.provide);
+            if (existing) {
+                if (existing.kind === provider.kind &&
+                    isRuntimeInputProvider(provider)) {
+                    continue;
+                }
+                if (isRuntimeInputProvider(existing) ||
+                    isRuntimeInputProvider(provider)) {
+                    const source = existing.kind === 'arguments' || provider.kind === 'arguments'
+                        ? 'Arguments'
+                        : 'Environment';
+                    const code = source === 'Arguments' ? 'LUTRE_ARGS_001' : 'LUTRE_ENV_001';
+                    throw new DependencyResolutionError(`${code}: ${source} ${tokenName(provider.provide)} is runtime-managed and cannot also be declared as a normal provider.`);
+                }
+                throw new DependencyResolutionError(`LUTRE_DI_DUPLICATE: Duplicate provider for ${tokenName(provider.provide)}`);
+            }
+            this.#providers.set(provider.provide, provider);
+        }
+    }
+    bindEnvironment(environment, value) {
+        const provider = this.#providers.get(environment);
+        if (!provider || provider.kind !== 'environment') {
+            throw new DependencyResolutionError(`LUTRE_ENV_002: ${environment.name} is not declared by any Module.environment.`);
+        }
+        if (this.#applicationCache.has(environment)) {
+            throw new DependencyResolutionError(`LUTRE_ENV_006: Environment ${environment.name} was already resolved and cannot be rebound.`);
+        }
+        this.#environment.set(environment, value);
+    }
+    bindArguments(argumentsContract, value) {
+        const provider = this.#providers.get(argumentsContract);
+        if (!provider || provider.kind !== 'arguments') {
+            throw new DependencyResolutionError(`LUTRE_ARGS_002: ${argumentsContract.name} is not declared by Application.arguments.`);
+        }
+        if (this.#applicationCache.has(argumentsContract)) {
+            throw new DependencyResolutionError(`LUTRE_ARGS_006: Arguments ${argumentsContract.name} was already resolved and cannot be rebound.`);
+        }
+        this.#arguments.set(argumentsContract, value);
+    }
+    resolve(token) {
+        return this.#resolve(token);
+    }
+    probeClass(target) {
+        try {
+            return this.#instantiate(target, [target]);
+        }
+        catch (error) {
+            if (isGraphProbeBoundary(error)) {
+                return createOpaqueProbeValue(target.name);
+            }
+            throw error;
+        }
+    }
+    prepareImplementation(implementation) {
+        if (this.#implementationCache.has(implementation))
+            return;
+        let consumer = this.#implementationConsumers.get(implementation);
+        if (!consumer) {
+            consumer = {
+                kind: 'implementation-consumer',
+                id: `runtime-implementation:${this.#implementationConsumers.size + 1}`,
+                name: implementation.name,
+            };
+            this.#implementationConsumers.set(implementation, consumer);
+        }
+        this.#constructImplementation(implementation, consumer, true);
+    }
+    implementationRuntime(implementation) {
+        const cached = this.#implementationCache.get(implementation);
+        if (!cached) {
+            throw new DependencyResolutionError(`LUTRE_IMPL_NOT_PREPARED: Implementation ${implementation.name} is not prepared during application construction.`);
+        }
+        return cached;
+    }
+    prepareTask(task) {
+        if (this.#taskCache.has(task))
+            return;
+        let consumer = this.#taskConsumers.get(task);
+        if (!consumer) {
+            consumer = {
+                kind: 'task-consumer',
+                id: `runtime-task:${this.#taskConsumers.size + 1}`,
+                name: task.name,
+            };
+            this.#taskConsumers.set(task, consumer);
+        }
+        this.#constructTask(task, consumer, true);
+    }
+    taskRuntime(task) {
+        const cached = this.#taskCache.get(task);
+        if (!cached) {
+            throw new DependencyResolutionError(`LUTRE_TASK_NOT_PREPARED: Task ${task.name} is not prepared during application construction.`);
+        }
+        return cached;
+    }
+    probeTask(task, consumer) {
+        try {
+            this.#constructTask(task, consumer, false);
+        }
+        catch (error) {
+            if (isGraphProbeBoundary(error))
+                return;
+            throw error;
+        }
+    }
+    probeImplementation(implementation, consumer) {
+        try {
+            return this.#constructImplementation(implementation, consumer, false);
+        }
+        catch (error) {
+            if (isGraphProbeBoundary(error)) {
+                return createOpaqueProbeValue(implementation.name);
+            }
+            throw error;
+        }
+    }
+    preparePipeline(pipeline) {
+        for (const item of pipeline) {
+            if (item.kind !== 'layer')
+                continue;
+            const definition = layerDefinitionOf(item);
+            this.#constructLayer(definition, {
+                kind: 'layer-consumer',
+                id: `runtime-layer:${definition.name}`,
+                name: definition.name,
+            }, true);
+            const child = childPipelineOf(item);
+            if (child)
+                this.preparePipeline(child);
+        }
+    }
+    layerRuntime(layer) {
+        const cached = this.#layerCache.get(layer);
+        if (!cached) {
+            throw new DependencyResolutionError(`LUTRE_LAYER_NOT_PREPARED: Layer ${layer.name} is not prepared during application construction.`);
+        }
+        return cached;
+    }
+    probeLayer(layer, consumer) {
+        try {
+            this.#constructLayer(layer, consumer, false);
+        }
+        catch (error) {
+            if (isGraphProbeBoundary(error))
+                return;
+            throw error;
+        }
+    }
+    #resolve(token, source, lineage = []) {
+        const cycleStart = lineage.indexOf(token);
+        if (cycleStart >= 0) {
+            const cycle = [...lineage.slice(cycleStart), token]
+                .map(tokenName)
+                .join(' -> ');
+            throw new DependencyResolutionError(`LUTRE_DI_CYCLE: 循環依存を検出しました: ${cycle}`);
+        }
+        const provider = this.#providers.get(token);
+        if (!provider) {
+            if (token === Logger) {
+                return this.#logger.child(source === undefined ? {} : { source });
+            }
+            if (isEnvClass(token)) {
+                throw new DependencyResolutionError(`LUTRE_ENV_002: ${token.name} is injected by ${source ?? 'Application'} but is not declared by any Module.environment.`);
+            }
+            if (isArgsClass(token)) {
+                throw new DependencyResolutionError(`LUTRE_ARGS_002: ${token.name} is injected by ${source ?? 'Application'} but is not declared by Application.arguments.`);
+            }
+            throw new DependencyResolutionError(`LUTRE_DI_UNRESOLVED: ${source ?? 'Application'} requires ${tokenName(token)}, but no provider is declared for ${tokenName(token)}.`);
+        }
+        const nextLineage = [...lineage, token];
+        if (provider.scope !== 'application') {
+            return this.#create(provider, nextLineage);
+        }
+        const cached = this.#applicationCache.get(token);
+        if (this.#applicationCache.has(token))
+            return cached;
+        const instance = this.#create(provider, nextLineage);
+        this.#applicationCache.set(token, instance);
+        return instance;
+    }
+    #create(provider, lineage) {
+        try {
+            switch (provider.kind) {
+                case 'value':
+                    return provider.useValue;
+                case 'environment': {
+                    if (this.#environment.has(provider.provide)) {
+                        return this.#environment.get(provider.provide);
+                    }
+                    if (this.#probe)
+                        return createOpaqueProbeValue(provider.provide.name);
+                    throw new DependencyResolutionError(`LUTRE_ENV_005: Environment ${provider.provide.name} requires a runtime Environment source before Application initialization.`);
+                }
+                case 'arguments': {
+                    if (this.#arguments.has(provider.provide)) {
+                        return this.#arguments.get(provider.provide);
+                    }
+                    if (this.#probe)
+                        return createOpaqueProbeValue(provider.provide.name);
+                    throw new DependencyResolutionError(`LUTRE_ARGS_005: Arguments ${provider.provide.name} requires a runtime Arguments source before Application initialization.`);
+                }
+                case 'class':
+                    return this.#instantiate(provider.useClass, lineage);
+                case 'factory': {
+                    const dependencies = provider.inject.map((token) => this.#resolve(token, tokenName(provider.provide), lineage));
+                    const value = provider.useFactory(...dependencies);
+                    if (isThenable(value)) {
+                        throw new DependencyResolutionError('LUTRE_DI_ASYNC_FACTORY: Async factory providers are not supported. Move asynchronous resource initialization to application lifecycle.');
+                    }
+                    return value;
+                }
+                case 'conditional': {
+                    if (this.#probe)
+                        return Object.create(null);
+                    const input = this.#resolve(provider.select.contract, tokenName(provider.provide), lineage);
+                    const selected = input[provider.select.key];
+                    const implementation = provider.mapping[selected];
+                    if (!implementation) {
+                        throw new DependencyResolutionError(`${provider.select.key}=${String(selected)}に対応するconditional Providerがありません`);
+                    }
+                    return this.#instantiate(implementation, lineage);
+                }
+            }
+        }
+        catch (error) {
+            if (provider.scope === 'application') {
+                this.#applicationCache.delete(provider.provide);
+            }
+            if (this.#probe && isGraphProbeBoundary(error)) {
+                return createOpaqueProbeValue(tokenName(provider.provide));
+            }
+            throw error;
+        }
+    }
+    #instantiate(target, lineage) {
+        if (target.length > 0) {
+            throw new DependencyResolutionError(`LUTRE_DI_CONSTRUCTOR: ${target.name} has required constructor parameters. Declare framework dependencies with constructor default parameters using inject().`);
+        }
+        return runInInjectionContext({
+            consumer: target,
+            resolve: (token) => this.#resolve(token, target.name, lineage),
+            ...(this.#recorder === undefined
+                ? {}
+                : {
+                    record: (consumer, dependency) => this.#recorder.record(consumer, dependency),
+                }),
+        }, () => new target());
+    }
+    #constructLayer(layer, consumer, cache) {
+        const cached = this.#layerCache.get(layer);
+        if (cache && cached)
+            return cached;
+        const runtime = runInInjectionContext({
+            consumer,
+            resolve: (token) => this.#resolve(token, layer.name),
+            ...(this.#recorder === undefined
+                ? {}
+                : {
+                    record: (recordedConsumer, dependency) => this.#recorder.record(recordedConsumer, dependency),
+                }),
+        }, () => layer.factory());
+        if (isThenable(runtime)) {
+            throw new DependencyResolutionError(`LUTRE_LAYER_ASYNC_FACTORY: Layer ${layer.name} factory must be synchronous.`);
+        }
+        if (typeof runtime !== 'function') {
+            throw new DependencyResolutionError(`LUTRE_LAYER_FACTORY_RESULT: Layer ${layer.name} factory must return a runtime function.`);
+        }
+        const normalized = runtime;
+        if (cache)
+            this.#layerCache.set(layer, normalized);
+        return normalized;
+    }
+    #constructImplementation(implementation, consumer, cache) {
+        const cached = this.#implementationCache.get(implementation);
+        if (cache && cached)
+            return cached;
+        const runtime = runInInjectionContext({
+            consumer,
+            resolve: (token) => this.#resolve(token, implementation.name),
+            ...(this.#recorder === undefined
+                ? {}
+                : {
+                    record: (recordedConsumer, dependency) => this.#recorder.record(recordedConsumer, dependency),
+                }),
+        }, () => implementation.factory());
+        if (isThenable(runtime)) {
+            throw new DependencyResolutionError(`LUTRE_IMPL_ASYNC_FACTORY: Implementation ${implementation.name} factory must be synchronous.`);
+        }
+        if (typeof runtime !== 'object' ||
+            runtime === null ||
+            Array.isArray(runtime)) {
+            throw new DependencyResolutionError(`LUTRE_IMPL_FACTORY_RESULT: Implementation ${implementation.name} factory must return a non-null object.`);
+        }
+        const normalized = runtime;
+        for (const procedure of implementation.procedures) {
+            if (typeof normalized[procedure] !== 'function') {
+                throw new DependencyResolutionError(`LUTRE_IMPL_004: Implementation ${implementation.name} does not implement callable procedure ${procedure}.`);
+            }
+        }
+        if (cache)
+            this.#implementationCache.set(implementation, normalized);
+        return normalized;
+    }
+    #constructTask(task, consumer, cache) {
+        const cached = this.#taskCache.get(task);
+        if (cache && cached)
+            return cached;
+        const runtime = runInInjectionContext({
+            consumer,
+            resolve: (token) => this.#resolve(token, task.name),
+            ...(this.#recorder === undefined
+                ? {}
+                : {
+                    record: (recordedConsumer, dependency) => this.#recorder.record(recordedConsumer, dependency),
+                }),
+        }, () => task.factory());
+        if (isThenable(runtime)) {
+            throw new DependencyResolutionError(`LUTRE_TASK_ASYNC_FACTORY: Task ${task.name} factory must be synchronous.`);
+        }
+        if (typeof runtime !== 'function') {
+            throw new DependencyResolutionError(`LUTRE_TASK_FACTORY_RESULT: Task ${task.name} factory must return a runtime function.`);
+        }
+        const normalized = runtime;
+        if (cache)
+            this.#taskCache.set(task, normalized);
+        return normalized;
+    }
+}
+function isRuntimeInputProvider(provider) {
+    return provider.kind === 'environment' || provider.kind === 'arguments';
+}
+function isGraphProbeBoundary(error) {
+    return error instanceof GraphProbeBoundary;
+}
+function createOpaqueProbeValue(source) {
+    const boundary = (operation) => new GraphProbeBoundary(`${source}.${String(operation)}`);
+    return new Proxy(Object.create(null), {
+        get(_target, key) {
+            throw boundary(key);
+        },
+        set(_target, key) {
+            throw boundary(key);
+        },
+        has(_target, key) {
+            throw boundary(key);
+        },
+        ownKeys() {
+            throw boundary('*');
+        },
+        getOwnPropertyDescriptor(_target, key) {
+            throw boundary(key);
+        },
+        defineProperty(_target, key) {
+            throw boundary(key);
+        },
+        deleteProperty(_target, key) {
+            throw boundary(key);
+        },
+        getPrototypeOf() {
+            throw boundary('[[Prototype]]');
+        },
+        setPrototypeOf() {
+            throw boundary('[[Prototype]]');
+        },
+    });
+}
+function isThenable(value) {
+    return (((typeof value === 'object' && value !== null) ||
+        typeof value === 'function') &&
+        typeof value.then === 'function');
+}

package/dist/runtime/error.d.ts

@@ -0,0 +1,10 @@
+export interface NormalizedApplicationError {
+    readonly code: 'INTERNAL_ERROR';
+    readonly errorId: string;
+    readonly message: string;
+    readonly stack?: string;
+    readonly cause?: unknown;
+    readonly context: Readonly<Record<string, unknown>>;
+    readonly original: unknown;
+}
+export declare function normalizeUnknownError(error: unknown, context?: Readonly<Record<string, unknown>>): NormalizedApplicationError;

package/dist/runtime/error.js

@@ -0,0 +1,15 @@
+export function normalizeUnknownError(error, context = {}) {
+    return {
+        code: 'INTERNAL_ERROR',
+        errorId: crypto.randomUUID(),
+        message: error instanceof Error ? error.message : String(error),
+        ...(error instanceof Error && error.stack !== undefined
+            ? { stack: error.stack }
+            : {}),
+        ...(error instanceof Error && error.cause !== undefined
+            ? { cause: error.cause }
+            : {}),
+        context,
+        original: error,
+    };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,7 @@
+export * from './application.js';
+export * from './capability.js';
+export * from './di.js';
+export * from './error.js';
+export * from './logger.js';
+export * from './pipeline.js';
+export * from './node-capabilities.js';

package/dist/runtime/index.js

@@ -0,0 +1,7 @@
+export * from './application.js';
+export * from './capability.js';
+export * from './di.js';
+export * from './error.js';
+export * from './logger.js';
+export * from './pipeline.js';
+export * from './node-capabilities.js';

package/dist/runtime/logger.d.ts

@@ -0,0 +1,36 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface LogRecord {
+    readonly timestamp: string;
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly [key: string]: unknown;
+}
+export interface LoggerBackend {
+    write(record: LogRecord): void;
+}
+export interface ConsoleLoggerBackendOptions {
+    readonly colors?: boolean;
+    readonly prefix?: string;
+}
+export declare class ConsoleLoggerBackend implements LoggerBackend {
+    #private;
+    constructor(options?: ConsoleLoggerBackendOptions);
+    write(record: LogRecord): void;
+}
+export declare class JsonConsoleLoggerBackend implements LoggerBackend {
+    write(record: LogRecord): void;
+}
+export declare class Logger {
+    #private;
+    readonly backend: LoggerBackend;
+    readonly context: Readonly<Record<string, unknown>>;
+    constructor(backend?: LoggerBackend, context?: Readonly<Record<string, unknown>>);
+    child(context: Readonly<Record<string, unknown>>): Logger;
+    debug(message: string, context?: Readonly<Record<string, unknown>>): void;
+    info(message: string, context?: Readonly<Record<string, unknown>>): void;
+    warn(message: string, context?: Readonly<Record<string, unknown>>): void;
+    error(message: string, context?: Readonly<Record<string, unknown>>): void;
+}
+export declare class SilentLogger extends Logger {
+    constructor(context?: Readonly<Record<string, unknown>>);
+}