@loutrejs/loutre 0.5.0 → 0.6.0

package/dist/message-port/index.js

@@ -1,189 +1,2 @@
-import { validateSchema, protocolGroup, } from '../core/index.js';
-import { executePipeline, Logger, normalizeUnknownError, } from '../runtime/index.js';
-const handler = Object.freeze({
-    kind: 'terminal',
-    name: 'messagePort.handler',
-    role: 'terminal',
-    protocol: 'messagePort',
-});
-function defineMessagePort(definition) {
-    return {
-        kind: 'protocol',
-        protocol: 'messagePort',
-        interaction: definition.interaction ?? 'unary',
-        dispatchKey: null,
-        definition,
-    };
-}
-function defineMessagePortGroup(definitions) {
-    return protocolGroup('messagePort', Object.fromEntries(Object.entries(definitions).map(([name, definition]) => [
-        name,
-        defineMessagePort(definition),
-    ])));
-}
-export const messagePort = Object.assign(defineMessagePortGroup, {
-    protocol: 'messagePort',
-    route: defineMessagePort,
-    handler,
-});
-export function createMessagePortExecution(options) {
-    const graph = options.graph;
-    const applicationLogger = options.logger ?? new Logger();
-    const runtime = options.runtime;
-    const logger = applicationLogger.child({ protocol: 'messagePort' });
-    const routes = collectRoutes(runtime.graph.modules);
-    let initialization;
-    const initialize = () => (initialization ??= runtime.initialize());
-    return {
-        graph,
-        initialize,
-        shutdown: (signal) => runtime.shutdown(signal),
-        async invoke(procedure, input) {
-            const startedAt = Date.now();
-            let invocationLogger = logger.child({
-                procedure,
-                executionId: crypto.randomUUID(),
-            });
-            try {
-                return await runtime.execute(async () => {
-                    const route = routes.find((candidate) => candidate.procedure === procedure);
-                    if (!route)
-                        throw new Error(`MessagePort procedure not found: ${procedure}`);
-                    invocationLogger = invocationLogger.child({
-                        source: `${route.implementation.name}.${route.procedure}`,
-                    });
-                    const message = Object.fromEntries(Object.keys(route.protocol.definition.responses).map((variant) => [
-                        variant,
-                        (value) => ({
-                            kind: 'message-port-result',
-                            variant,
-                            value,
-                        }),
-                    ]));
-                    const context = {
-                        input,
-                        message,
-                        logger: invocationLogger,
-                    };
-                    const result = await executePipeline(route.protocol.definition.pipeline, {
-                        context,
-                        layer: (descriptor) => runtime.container.layerRuntime(descriptor),
-                        validate: () => undefined,
-                        terminal: async (_layer, terminalContext) => {
-                            const target = runtime.container.implementationRuntime(route.implementation);
-                            const method = target[route.procedure];
-                            if (typeof method !== 'function')
-                                throw new Error('Handler method is missing');
-                            return Reflect.apply(method, target, [
-                                terminalContext,
-                            ]);
-                        },
-                    });
-                    const finalized = await finalize(route.protocol.definition, result);
-                    invocationLogger.info('MessagePort invocation completed', {
-                        event: 'message_port.invocation.completed',
-                        durationMs: Math.max(0, Date.now() - startedAt),
-                    });
-                    return finalized;
-                });
-            }
-            catch (error) {
-                const normalized = normalizeUnknownError(error, invocationLogger.context);
-                invocationLogger.error('Unhandled application error', {
-                    event: 'application.error',
-                    durationMs: Math.max(0, Date.now() - startedAt),
-                    error: {
-                        code: normalized.code,
-                        id: normalized.errorId,
-                        name: error instanceof Error ? error.name : typeof error,
-                        message: normalized.message,
-                        ...(normalized.stack === undefined
-                            ? {}
-                            : { stack: normalized.stack }),
-                        ...(normalized.cause === undefined
-                            ? {}
-                            : { cause: normalized.cause }),
-                    },
-                });
-                throw error;
-            }
-        },
-    };
-}
-async function finalize(definition, result) {
-    const response = definition.responses[result.variant];
-    if (!response)
-        throw new Error(`Undeclared variant: ${result.variant}`);
-    if (response.stream === 'server') {
-        if (!isAsyncIterable(result.value)) {
-            throw new Error('Server-stream result requires an AsyncIterable');
-        }
-        const source = result.value;
-        return {
-            ...result,
-            value: (async function* () {
-                for await (const value of source) {
-                    yield await validateSchema(response.body, value);
-                }
-            })(),
-        };
-    }
-    return { ...result, value: await validateSchema(response.body, result.value) };
-}
-function collectRoutes(modules) {
-    return modules.flatMap((module) => (module.definition.implementations ?? []).flatMap((implementation) => {
-        if (implementation.protocol !== 'messagePort')
-            return [];
-        return implementation.procedures.map((procedure) => ({
-            procedure,
-            protocol: implementation.contract.procedures[procedure].protocols
-                .messagePort,
-            implementation,
-        }));
-    }));
-}
-export function attachMessagePort(application, port) {
-    port.addEventListener('message', async (event) => {
-        const request = event.data;
-        try {
-            const result = await application.invoke(request.procedure, request.input);
-            if (isAsyncIterable(result.value)) {
-                for await (const value of result.value) {
-                    port.postMessage({
-                        id: request.id,
-                        variant: result.variant,
-                        value,
-                        done: false,
-                    });
-                }
-                port.postMessage({
-                    id: request.id,
-                    variant: result.variant,
-                    done: true,
-                });
-            }
-            else {
-                port.postMessage({
-                    id: request.id,
-                    variant: result.variant,
-                    value: result.value,
-                    done: true,
-                });
-            }
-        }
-        catch (error) {
-            port.postMessage({
-                id: request.id,
-                error: error instanceof Error ? error.message : String(error),
-                done: true,
-            });
-        }
-    });
-    port.start?.();
-}
-function isAsyncIterable(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        Symbol.asyncIterator in value &&
-        typeof value[Symbol.asyncIterator] === 'function');
-}
+export { defineMessagePortContract, defineMessagePortImplementation, messagePort, messagePortExtension, } from './extension.js';
+export { attachMessagePort } from './transport.js';

package/dist/message-port/transport.d.ts

@@ -0,0 +1,11 @@
+export interface MessagePortHost {
+    invoke(method: string, input?: unknown): Promise<{
+        readonly response: string;
+        readonly value: unknown;
+    }>;
+}
+export type MessagePortLike = {
+    postMessage(value: unknown): void;
+    start?(): void;
+} & Pick<EventTarget, 'addEventListener'>;
+export declare function attachMessagePort(host: MessagePortHost, port: MessagePortLike): void;

package/dist/message-port/transport.js

@@ -0,0 +1,45 @@
+export function attachMessagePort(host, port) {
+    port.addEventListener('message', async (event) => {
+        const request = event.data;
+        try {
+            const result = await host.invoke(request.procedure, request.input);
+            if (isAsyncIterable(result.value)) {
+                for await (const value of result.value) {
+                    port.postMessage({
+                        id: request.id,
+                        response: result.response,
+                        value,
+                        done: false,
+                    });
+                }
+                port.postMessage({
+                    id: request.id,
+                    response: result.response,
+                    done: true,
+                });
+            }
+            else {
+                port.postMessage({
+                    id: request.id,
+                    response: result.response,
+                    value: result.value,
+                    done: true,
+                });
+            }
+        }
+        catch (error) {
+            port.postMessage({
+                id: request.id,
+                error: error instanceof Error ? error.message : String(error),
+                done: true,
+            });
+        }
+    });
+    port.start?.();
+}
+function isAsyncIterable(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        Symbol.asyncIterator in value &&
+        typeof value[Symbol.asyncIterator] === 'function');
+}

package/dist/runtime/async-iterator-lifecycle.d.ts

@@ -0,0 +1,12 @@
+export declare class AsyncIteratorCleanupDeadlineError extends Error {
+    constructor(message: string);
+}
+export declare class AsyncIteratorLifecycle<T> {
+    #private;
+    constructor(iterator: AsyncIterator<T>);
+    get done(): boolean;
+    next(): Promise<IteratorResult<T>>;
+    return(reason?: unknown): Promise<IteratorResult<T>>;
+    throw(error?: unknown): Promise<IteratorResult<T>>;
+    drain(reason: unknown, deadline: () => number | undefined, timeoutMessage: string): Promise<void>;
+}

package/dist/runtime/async-iterator-lifecycle.js

@@ -0,0 +1,95 @@
+const cleanupYieldInterval = 32;
+export class AsyncIteratorCleanupDeadlineError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AsyncIteratorCleanupDeadlineError';
+    }
+}
+export class AsyncIteratorLifecycle {
+    #iterator;
+    #idleWaiters = new Set();
+    #inFlight = 0;
+    #returnPending = false;
+    #returnContinuationPending = false;
+    #done = false;
+    constructor(iterator) {
+        this.#iterator = iterator;
+    }
+    get done() {
+        return this.#done;
+    }
+    async next() {
+        return this.#run(() => this.#iterator.next());
+    }
+    async return(reason) {
+        if (!this.#iterator.return) {
+            const result = { done: true, value: reason };
+            this.#record(result);
+            return result;
+        }
+        this.#returnPending = true;
+        try {
+            const result = await this.#run(() => this.#iterator.return(reason));
+            this.#returnContinuationPending = !result.done;
+            return result;
+        }
+        finally {
+            this.#returnPending = false;
+        }
+    }
+    async throw(error) {
+        if (!this.#iterator.throw)
+            throw error;
+        return this.#run(() => this.#iterator.throw(error));
+    }
+    async drain(reason, deadline, timeoutMessage) {
+        if (this.#returnPending)
+            await this.#waitForIdle();
+        if (this.#done)
+            return;
+        if (!this.#returnContinuationPending) {
+            const result = await this.return(reason);
+            if (result.done)
+                return;
+        }
+        await this.#waitForIdle();
+        let continuationSteps = 0;
+        while (!this.#done) {
+            const currentDeadline = deadline();
+            if (currentDeadline !== undefined && Date.now() >= currentDeadline) {
+                throw new AsyncIteratorCleanupDeadlineError(timeoutMessage);
+            }
+            await this.next();
+            continuationSteps += 1;
+            if (continuationSteps % cleanupYieldInterval === 0) {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            }
+        }
+    }
+    async #run(operation) {
+        this.#inFlight += 1;
+        try {
+            return this.#record(await operation());
+        }
+        finally {
+            this.#inFlight -= 1;
+            if (this.#inFlight === 0) {
+                for (const resolve of this.#idleWaiters)
+                    resolve();
+                this.#idleWaiters.clear();
+            }
+        }
+    }
+    #record(result) {
+        if (result.done) {
+            this.#done = true;
+            this.#returnContinuationPending = false;
+        }
+        return result;
+    }
+    #waitForIdle() {
+        return this.#inFlight === 0
+            ? Promise.resolve()
+            : new Promise((resolve) => this.#idleWaiters.add(resolve));
+    }
+}

package/dist/runtime/capability.d.ts

@@ -1,16 +1,16 @@
-export type RuntimeCapability = string;
-export interface RuntimeCapabilities {
+export type RuntimeCapabilityId = string;
+export interface RuntimeSupportProfile {
     readonly runtime: string;
-    readonly capabilities: ReadonlySet<RuntimeCapability>;
+    readonly capabilities: ReadonlySet<RuntimeCapabilityId>;
 }
-export interface CapabilityCheck {
+export interface RuntimeSupportCheck {
     readonly ok: boolean;
-    readonly required: readonly RuntimeCapability[];
-    readonly supported: readonly RuntimeCapability[];
-    readonly missing: readonly RuntimeCapability[];
+    readonly required: readonly RuntimeCapabilityId[];
+    readonly supported: readonly RuntimeCapabilityId[];
+    readonly missing: readonly RuntimeCapabilityId[];
 }
-export declare function checkCapabilities(required: Iterable<RuntimeCapability>, runtime: RuntimeCapabilities): CapabilityCheck;
-export declare class MissingCapabilitiesError extends Error {
-    readonly check: CapabilityCheck;
-    constructor(check: CapabilityCheck);
+export declare function checkRuntimeSupport(required: Iterable<RuntimeCapabilityId>, runtime: RuntimeSupportProfile): RuntimeSupportCheck;
+export declare class MissingRuntimeSupportError extends Error {
+    readonly check: RuntimeSupportCheck;
+    constructor(check: RuntimeSupportCheck);
 }

package/dist/runtime/capability.js

@@ -1,4 +1,4 @@
-export function checkCapabilities(required, runtime) {
+export function checkRuntimeSupport(required, runtime) {
     const requirements = [...new Set(required)];
     const missing = requirements.filter((capability) => !runtime.capabilities.has(capability));
     return {
@@ -8,11 +8,11 @@ export function checkCapabilities(required, runtime) {
         missing,
     };
 }
-export class MissingCapabilitiesError extends Error {
+export class MissingRuntimeSupportError extends Error {
     check;
     constructor(check) {
         super(`Runtime is missing required capabilities: ${check.missing.join(', ')}`);
         this.check = check;
-        this.name = 'MissingCapabilitiesError';
+        this.name = 'MissingRuntimeSupportError';
     }
 }

package/dist/runtime/di.d.ts

@@ -1,38 +1,18 @@
-import { type ArgsClass, type Class, type DependencyConsumer, type EnvClass, type ImplementationConsumer, type ImplementationDescriptor, type LayerConsumer, type LayerDescriptor, type LayerRuntime, type ModuleInstance, type ModuleTemplate, type ProviderDescriptor, type PipelineItem, type TaskConsumer, type TaskDescriptor, type TaskRuntime, type TokenLike } from '../core/index.js';
+import { type ArgsClass, type EnvClass, type ProviderDescriptor, type TokenLike } from '../core/index.js';
 import { Logger } from './logger.js';
 export declare class DependencyResolutionError extends Error {
     constructor(message: string);
 }
-export interface RuntimeModuleGraph {
-    readonly modules: readonly ModuleInstance[];
-    readonly providers: readonly ProviderDescriptor[];
-}
-export interface DependencyRecorder {
-    record(consumer: DependencyConsumer, dependency: TokenLike): void;
-}
 export interface ContainerOptions {
     readonly logger?: Logger;
-    readonly recorder?: DependencyRecorder;
     readonly environment?: ReadonlyMap<EnvClass, object>;
     readonly arguments?: ReadonlyMap<ArgsClass, object>;
-    readonly probe?: boolean;
 }
-export declare function collectRuntimeModuleGraph(roots: readonly (ModuleInstance | ModuleTemplate<void>)[]): RuntimeModuleGraph;
 export declare class Container {
     #private;
     constructor(providers: readonly ProviderDescriptor[], options?: Logger | ContainerOptions);
     bindEnvironment(environment: EnvClass, value: object): void;
     bindArguments(argumentsContract: ArgsClass, value: object): void;
-    resolve<T>(token: TokenLike<T>): T;
+    resolve<T>(token: TokenLike<T>, source?: string): T;
     get<T>(token: TokenLike<T>): T;
-    probeClass<T>(target: Class<T>): T;
-    prepareImplementation(implementation: ImplementationDescriptor): void;
-    implementationRuntime(implementation: ImplementationDescriptor): object;
-    prepareTask(task: TaskDescriptor): void;
-    taskRuntime<TInput, TOutput>(task: TaskDescriptor<TInput, TOutput>): TaskRuntime<TInput, TOutput>;
-    probeTask(task: TaskDescriptor, consumer: TaskConsumer): void;
-    probeImplementation(implementation: ImplementationDescriptor, consumer: ImplementationConsumer): object;
-    preparePipeline(pipeline: readonly PipelineItem[]): void;
-    layerRuntime(layer: LayerDescriptor): LayerRuntime<object, readonly [], unknown>;
-    probeLayer(layer: LayerDescriptor, consumer: LayerConsumer): void;
 }