@loutrejs/loutre 0.1.0

package/dist/core/error.js

@@ -0,0 +1,25 @@
+const domainErrorMarker = Symbol('loutre.domain-error');
+export class DomainError extends Error {
+    code;
+    data;
+    [domainErrorMarker] = true;
+    constructor(code, data, options = {}) {
+        super(code, options);
+        this.code = code;
+        this.data = data;
+        this.name = 'DomainError';
+    }
+}
+export function defineError(definition) {
+    const factory = ((data, options = {}) => new DomainError(definition.code, data, options));
+    Object.defineProperties(factory, {
+        kind: { value: 'error-definition', enumerable: true },
+        code: { value: definition.code, enumerable: true },
+        data: { value: definition.data, enumerable: true },
+        is: {
+            value: (error) => error instanceof DomainError && error.code === definition.code,
+            enumerable: false,
+        },
+    });
+    return factory;
+}

package/dist/core/execution.d.ts

@@ -0,0 +1,78 @@
+import { type SchemaOutput, type StandardSchemaV1 } from './schema.js';
+import { type Token } from './token.js';
+export type TaskRuntime<TInput, TOutput> = [TInput] extends [void] ? () => TOutput | Promise<TOutput> : (input: TInput) => TOutput | Promise<TOutput>;
+export interface TaskDescriptor<TInput = unknown, TOutput = unknown, TName extends string = string> {
+    readonly kind: 'task';
+    readonly name: TName;
+    readonly factory: () => TaskRuntime<TInput, TOutput>;
+}
+export type TaskInput<T> = T extends TaskDescriptor<infer TInput, any, any> ? TInput : never;
+export type TaskOutput<T> = T extends TaskDescriptor<any, infer TOutput, any> ? TOutput : never;
+export type TaskArguments<T> = [TaskInput<T>] extends [void] ? readonly [] : readonly [input: TaskInput<T>];
+export declare function task<TInput = void, TOutput = void, const TName extends string = string>(declaration: {
+    readonly name: TName;
+    readonly factory: () => TaskRuntime<TInput, TOutput>;
+}): TaskDescriptor<TInput, TOutput, TName>;
+type VoidTaskConstraint<TTask> = [TaskInput<TTask>] extends [void] ? unknown : never;
+export type CronOverlap = 'allow' | 'skip';
+export interface CronTriggerDescriptor<TTask extends TaskDescriptor<void, any> = TaskDescriptor<void, any>, TName extends string = string> {
+    readonly kind: 'trigger';
+    readonly trigger: 'cron';
+    readonly name: TName;
+    readonly expression: string;
+    readonly timezone: string;
+    readonly overlap: CronOverlap;
+    readonly task: TTask;
+}
+export declare function cron<const TTask extends TaskDescriptor<any, any>, const TName extends string>(declaration: {
+    readonly name: TName;
+    readonly expression: string;
+    readonly timezone: string;
+    readonly overlap?: CronOverlap;
+    readonly task: TTask;
+} & VoidTaskConstraint<TTask>): CronTriggerDescriptor<TTask & TaskDescriptor<void, any>, TName>;
+export interface FixedDelayTriggerDescriptor<TTask extends TaskDescriptor<void, any> = TaskDescriptor<void, any>, TName extends string = string> {
+    readonly kind: 'trigger';
+    readonly trigger: 'fixed-delay';
+    readonly name: TName;
+    readonly delay: number;
+    readonly immediate: boolean;
+    readonly task: TTask;
+}
+export declare function fixedDelay<const TTask extends TaskDescriptor<any, any>, const TName extends string>(declaration: {
+    readonly name: TName;
+    readonly delay: number;
+    readonly immediate?: boolean;
+    readonly task: TTask;
+} & VoidTaskConstraint<TTask>): FixedDelayTriggerDescriptor<TTask & TaskDescriptor<void, any>, TName>;
+declare const queueDriverToken: unique symbol;
+export interface QueueDescriptor<TSchema extends StandardSchemaV1 = StandardSchemaV1, TName extends string = string> {
+    readonly kind: 'queue';
+    readonly name: TName;
+    readonly payload: TSchema;
+    readonly [queueDriverToken]: Token<unknown>;
+}
+export type QueuePayload<T> = T extends QueueDescriptor<infer TSchema, any> ? SchemaOutput<TSchema> : never;
+export declare function queue<const TSchema extends StandardSchemaV1, const TName extends string = string>(declaration: {
+    readonly name: TName;
+    readonly payload: TSchema;
+}): QueueDescriptor<TSchema, TName>;
+export declare function queueRuntimeToken(descriptor: QueueDescriptor): Token<unknown>;
+export interface QueueConsumerTriggerDescriptor<TQueue extends QueueDescriptor<any> = QueueDescriptor<any>, TTask extends TaskDescriptor<any, any> = TaskDescriptor<any, any>, TName extends string = string> {
+    readonly kind: 'trigger';
+    readonly trigger: 'queue-consumer';
+    readonly name: TName;
+    readonly queue: TQueue;
+    readonly task: TTask;
+}
+type ConsumerTaskConstraint<TQueue, TTask> = [TaskInput<TTask>] extends [
+    QueuePayload<TQueue>
+] ? [QueuePayload<TQueue>] extends [TaskInput<TTask>] ? unknown : never : never;
+export declare function consume<const TQueue extends QueueDescriptor<any>, const TTask extends TaskDescriptor<any, any>, const TName extends string>(declaration: {
+    readonly name: TName;
+    readonly queue: TQueue;
+    readonly task: TTask;
+} & ConsumerTaskConstraint<TQueue, TTask>): QueueConsumerTriggerDescriptor<TQueue, TTask & TaskDescriptor<QueuePayload<TQueue>, any>, TName>;
+export type TriggerDescriptor = CronTriggerDescriptor<any, any> | FixedDelayTriggerDescriptor<any, any> | QueueConsumerTriggerDescriptor<any, any, any>;
+export type TriggerTask<TTrigger> = TTrigger extends TriggerDescriptor ? TTrigger['task'] : never;
+export {};

package/dist/core/execution.js

@@ -0,0 +1,61 @@
+import { token } from './token.js';
+export function task(declaration) {
+    return Object.freeze({
+        kind: 'task',
+        name: declaration.name,
+        factory: declaration.factory,
+    });
+}
+export function cron(declaration) {
+    return Object.freeze({
+        kind: 'trigger',
+        trigger: 'cron',
+        name: declaration.name,
+        expression: declaration.expression,
+        timezone: declaration.timezone,
+        overlap: declaration.overlap ?? 'skip',
+        task: declaration.task,
+    });
+}
+export function fixedDelay(declaration) {
+    if (!Number.isFinite(declaration.delay) ||
+        !Number.isInteger(declaration.delay) ||
+        declaration.delay < 0) {
+        throw new Error('LUTRE_TRIGGER_INVALID_FIXED_DELAY: fixedDelay.delay must be a non-negative finite integer.');
+    }
+    return Object.freeze({
+        kind: 'trigger',
+        trigger: 'fixed-delay',
+        name: declaration.name,
+        delay: declaration.delay,
+        immediate: declaration.immediate ?? false,
+        task: declaration.task,
+    });
+}
+const queueDriverToken = Symbol('loutre.queue-driver');
+export function queue(declaration) {
+    const payload = declaration.payload;
+    if (payload === null ||
+        (typeof payload !== 'object' && typeof payload !== 'function') ||
+        !('~standard' in payload)) {
+        throw new Error('LUTRE_QUEUE_PAYLOAD_SCHEMA: queue.payload must implement Standard Schema.');
+    }
+    return Object.freeze({
+        kind: 'queue',
+        name: declaration.name,
+        payload: declaration.payload,
+        [queueDriverToken]: token(`loutre.queue-driver.${declaration.name}`),
+    });
+}
+export function queueRuntimeToken(descriptor) {
+    return descriptor[queueDriverToken];
+}
+export function consume(declaration) {
+    return Object.freeze({
+        kind: 'trigger',
+        trigger: 'queue-consumer',
+        name: declaration.name,
+        queue: declaration.queue,
+        task: declaration.task,
+    });
+}

package/dist/core/implementation.d.ts

@@ -0,0 +1,34 @@
+import type { ContractDefinition, ContractProcedures, ProtocolDescriptor, ProtocolFactory } from './contract.js';
+type ProcedureNamesForProtocol<TContract extends ContractDefinition, TProtocol extends string> = {
+    [K in keyof ContractProcedures<TContract>]: TProtocol extends keyof ContractProcedures<TContract>[K]['protocols'] ? K : never;
+}[keyof ContractProcedures<TContract>] & string;
+type ImplementationRuntimeShape<TContract extends ContractDefinition, TProtocol extends string, TProcedures extends string> = {
+    [K in TProcedures]: ContractProcedures<TContract>[K]['protocols'][TProtocol & keyof ContractProcedures<TContract>[K]['protocols']] extends ProtocolDescriptor<TProtocol, infer TContext, infer TResult, any, any> ? (context: TContext) => TResult | Promise<TResult> : never;
+};
+export interface ImplementationDescriptor<TContract extends ContractDefinition = ContractDefinition, TProtocol extends string = string, TProcedures extends readonly string[] = readonly string[], TRuntime extends object = object, TCapabilities extends readonly string[] = readonly string[]> {
+    readonly kind: 'implementation';
+    readonly name: string;
+    readonly contract: TContract;
+    readonly protocol: TProtocol;
+    readonly capabilities: TCapabilities;
+    readonly procedures: TProcedures;
+    readonly factory: () => TRuntime;
+}
+type AvailableProtocolConstraint<TContract extends ContractDefinition, TProtocol extends string, TCapabilities extends readonly string[]> = [ProcedureNamesForProtocol<TContract, TProtocol>] extends [never] ? never : ProtocolFactory<TProtocol, TCapabilities>;
+type FullImplementationDeclaration<TContract extends ContractDefinition, TProtocol extends string, TCapabilities extends readonly string[]> = {
+    readonly name: string;
+    readonly contract: TContract;
+    readonly protocol: AvailableProtocolConstraint<TContract, TProtocol, TCapabilities>;
+    readonly procedures?: never;
+    readonly factory: () => ImplementationRuntimeShape<TContract, TProtocol, ProcedureNamesForProtocol<TContract, TProtocol>>;
+};
+type PartialImplementationDeclaration<TContract extends ContractDefinition, TProtocol extends string, TProcedures extends readonly ProcedureNamesForProtocol<TContract, TProtocol>[], TCapabilities extends readonly string[]> = {
+    readonly name: string;
+    readonly contract: TContract;
+    readonly protocol: AvailableProtocolConstraint<TContract, TProtocol, TCapabilities>;
+    readonly procedures: TProcedures;
+    readonly factory: () => ImplementationRuntimeShape<TContract, TProtocol, TProcedures[number]>;
+};
+export declare function implementation<const TContract extends ContractDefinition, const TProtocol extends string, const TCapabilities extends readonly string[]>(declaration: FullImplementationDeclaration<TContract, TProtocol, TCapabilities>): ImplementationDescriptor<TContract, TProtocol, readonly ProcedureNamesForProtocol<TContract, TProtocol>[], ImplementationRuntimeShape<TContract, TProtocol, ProcedureNamesForProtocol<TContract, TProtocol>>, TCapabilities>;
+export declare function implementation<const TContract extends ContractDefinition, const TProtocol extends string, const TProcedures extends readonly ProcedureNamesForProtocol<TContract, TProtocol>[], const TCapabilities extends readonly string[]>(declaration: PartialImplementationDeclaration<TContract, TProtocol, TProcedures, TCapabilities>): ImplementationDescriptor<TContract, TProtocol, TProcedures, ImplementationRuntimeShape<TContract, TProtocol, TProcedures[number]>, TCapabilities>;
+export {};

package/dist/core/implementation.js

@@ -0,0 +1,30 @@
+export function implementation(declaration) {
+    const protocol = declaration.protocol.protocol;
+    const available = Object.entries(declaration.contract.procedures)
+        .filter(([, procedure]) => protocol in procedure.protocols)
+        .map(([name]) => name);
+    if (available.length === 0) {
+        throw new Error(`LUTRE_IMPL_003: Contract does not declare any procedure for protocol ${protocol}.`);
+    }
+    const procedures = [...(declaration.procedures ?? available)];
+    const selected = new Set();
+    for (const procedure of procedures) {
+        if (selected.has(procedure)) {
+            throw new Error(`LUTRE_IMPL_003: Implementation ${declaration.name} selects procedure ${procedure} more than once.`);
+        }
+        selected.add(procedure);
+        const definition = declaration.contract.procedures[procedure];
+        if (!definition || !(protocol in definition.protocols)) {
+            throw new Error(`LUTRE_IMPL_003: ${procedure} is not declared for protocol ${protocol}.`);
+        }
+    }
+    return Object.freeze({
+        kind: 'implementation',
+        name: declaration.name,
+        contract: declaration.contract,
+        protocol,
+        capabilities: declaration.protocol.capabilities ?? [],
+        procedures: Object.freeze(procedures),
+        factory: declaration.factory,
+    });
+}

package/dist/core/index.d.ts

@@ -0,0 +1,15 @@
+export * from './args.js';
+export * from './contract.js';
+export * from './context-key.js';
+export * from './env.js';
+export * from './error.js';
+export * from './execution.js';
+export * from './implementation.js';
+export * from './injection.js';
+export * from './layer.js';
+export * from './lifecycle.js';
+export * from './module.js';
+export * from './provider.js';
+export * from './runtime-input.js';
+export * from './schema.js';
+export * from './token.js';

package/dist/core/index.js

@@ -0,0 +1,15 @@
+export * from './args.js';
+export * from './contract.js';
+export * from './context-key.js';
+export * from './env.js';
+export * from './error.js';
+export * from './execution.js';
+export * from './implementation.js';
+export * from './injection.js';
+export * from './layer.js';
+export * from './lifecycle.js';
+export * from './module.js';
+export * from './provider.js';
+export * from './runtime-input.js';
+export * from './schema.js';
+export * from './token.js';

package/dist/core/injection.d.ts

@@ -0,0 +1,28 @@
+import type { TokenLike, TokenValue } from './token.js';
+export interface LayerConsumer {
+    readonly kind: 'layer-consumer';
+    readonly id: string;
+    readonly name: string;
+}
+export interface ImplementationConsumer {
+    readonly kind: 'implementation-consumer';
+    readonly id: string;
+    readonly name: string;
+}
+export interface TaskConsumer {
+    readonly kind: 'task-consumer';
+    readonly id: string;
+    readonly name: string;
+}
+export type DependencyConsumer = TokenLike | LayerConsumer | ImplementationConsumer | TaskConsumer;
+export interface InjectionContext {
+    readonly consumer: DependencyConsumer;
+    readonly resolve: <T>(token: TokenLike<T>) => T;
+    readonly record?: (consumer: DependencyConsumer, dependency: TokenLike) => void;
+}
+export declare function runInInjectionContext<T>(context: InjectionContext, run: () => T): T;
+export declare class InjectionContextError extends Error {
+    readonly code = "LUTRE_DI_CONTEXT";
+    constructor(token: TokenLike);
+}
+export declare function inject<TToken extends TokenLike>(token: TToken): TokenValue<TToken>;

package/dist/core/injection.js

@@ -0,0 +1,35 @@
+const injectionContextKey = Symbol.for('loutre.injection-context');
+function currentInjectionContext() {
+    return globalThis[injectionContextKey];
+}
+function setCurrentInjectionContext(context) {
+    const storage = globalThis;
+    if (context === undefined)
+        delete storage[injectionContextKey];
+    else
+        storage[injectionContextKey] = context;
+}
+export function runInInjectionContext(context, run) {
+    const previous = currentInjectionContext();
+    setCurrentInjectionContext(context);
+    try {
+        return run();
+    }
+    finally {
+        setCurrentInjectionContext(previous);
+    }
+}
+export class InjectionContextError extends Error {
+    code = 'LUTRE_DI_CONTEXT';
+    constructor(token) {
+        super(`inject(${typeof token === 'function' ? token.name : token.id}) was called outside a Loutre injection context.`);
+        this.name = 'InjectionContextError';
+    }
+}
+export function inject(token) {
+    const context = currentInjectionContext();
+    if (!context)
+        throw new InjectionContextError(token);
+    context.record?.(context.consumer, token);
+    return context.resolve(token);
+}

package/dist/core/layer.d.ts

@@ -0,0 +1,109 @@
+import type { ContextKey, ContextProperties } from './context-key.js';
+export type LayerRole = 'generic' | 'authentication' | 'guard' | 'validation' | 'framework' | 'terminal';
+export type ValidatedInputPart = 'params' | 'query' | 'headers' | 'body';
+declare const shortCircuitMarker: unique symbol;
+export interface ShortCircuit<TResult = unknown> {
+    readonly kind: 'short-circuit';
+    readonly result: TResult;
+    readonly [shortCircuitMarker]: true;
+}
+export declare function shortCircuit<const TResult>(result: TResult): ShortCircuit<TResult>;
+export declare function isShortCircuit(value: unknown): value is ShortCircuit;
+declare const shortCircuitResultType: unique symbol;
+export interface ShortCircuitDeclaration {
+    readonly protocol: string;
+    readonly variant: string;
+    readonly response?: Readonly<Record<string, unknown>>;
+}
+export type LayerNext<TProvides extends readonly ContextKey[]> = number extends TProvides['length'] ? (provided: ContextProperties<TProvides>) => Promise<void> : TProvides extends readonly [] ? () => Promise<void> : (provided: ContextProperties<TProvides>) => Promise<void>;
+export type LayerRuntime<TContext extends object, TProvides extends readonly ContextKey[], TShortCircuitResult> = (context: TContext, next: LayerNext<TProvides>) => Promise<void | ShortCircuit<TShortCircuitResult>>;
+export type LayerFactory<TContext extends object, TProvides extends readonly ContextKey[], TShortCircuitResult> = () => LayerRuntime<TContext, TProvides, TShortCircuitResult>;
+export interface LayerDefinition<TRequires extends readonly ContextKey[] = readonly [], TProvides extends readonly ContextKey[] = readonly [], TContext extends object = {}, TShortCircuitResult = never, TShortCircuits extends readonly ShortCircuitDeclaration[] = readonly [], TName extends string = string, TRole extends Exclude<LayerRole, 'terminal' | 'validation'> = 'generic', TRequiresValidated extends readonly ValidatedInputPart[] = readonly []> {
+    readonly name: TName;
+    readonly role?: TRole;
+    readonly requires?: TRequires;
+    readonly provides?: TProvides;
+    readonly requiresValidated?: TRequiresValidated;
+    readonly shortCircuits?: TShortCircuits;
+    readonly factory: LayerFactory<TContext & ContextProperties<TRequires>, TProvides, TShortCircuitResult>;
+}
+export interface LayerOccurrenceDescriptor<TRequires extends readonly ContextKey[] = readonly ContextKey[], TProvides extends readonly ContextKey[] = readonly ContextKey[], TShortCircuitResult = unknown, TShortCircuits extends readonly ShortCircuitDeclaration[] = readonly ShortCircuitDeclaration[], TName extends string = string, TRole extends Exclude<LayerRole, 'terminal' | 'validation'> = Exclude<LayerRole, 'terminal' | 'validation'>, TRequiresValidated extends readonly ValidatedInputPart[] = readonly ValidatedInputPart[], TContext extends object = object, TPipeline extends readonly PipelineItem[] = readonly PipelineItem[]> {
+    readonly kind: 'layer';
+    readonly name: TName;
+    readonly role: TRole;
+    readonly requires: TRequires;
+    readonly provides: TProvides;
+    readonly requiresValidated: TRequiresValidated;
+    readonly shortCircuits: TShortCircuits;
+    readonly definition: LayerDescriptor<TRequires, TProvides, TShortCircuitResult, TShortCircuits, TName, TRole, TRequiresValidated, TContext>;
+    readonly pipeline: TPipeline;
+    readonly factory?: never;
+    readonly [shortCircuitResultType]?: TShortCircuitResult;
+}
+export interface LayerDescriptor<TRequires extends readonly ContextKey[] = readonly ContextKey[], TProvides extends readonly ContextKey[] = readonly ContextKey[], TShortCircuitResult = unknown, TShortCircuits extends readonly ShortCircuitDeclaration[] = readonly ShortCircuitDeclaration[], TName extends string = string, TRole extends Exclude<LayerRole, 'terminal' | 'validation'> = Exclude<LayerRole, 'terminal' | 'validation'>, TRequiresValidated extends readonly ValidatedInputPart[] = readonly ValidatedInputPart[], TContext extends object = object> {
+    <const TPipeline extends readonly PipelineItem[]>(pipeline: TPipeline): LayerOccurrenceDescriptor<TRequires, TProvides, TShortCircuitResult, TShortCircuits, TName, TRole, TRequiresValidated, TContext, TPipeline>;
+    readonly kind: 'layer';
+    readonly name: TName;
+    readonly role: TRole;
+    readonly requires: TRequires;
+    readonly provides: TProvides;
+    readonly requiresValidated: TRequiresValidated;
+    readonly shortCircuits: TShortCircuits;
+    readonly factory: LayerFactory<TContext & ContextProperties<TRequires>, TProvides, TShortCircuitResult>;
+    readonly definition?: never;
+    readonly pipeline?: never;
+    readonly [shortCircuitResultType]?: TShortCircuitResult;
+}
+export interface ValidationLayerDescriptor {
+    readonly kind: 'validation';
+    readonly name: `validate.${'params' | 'query' | 'headers' | 'body'}`;
+    readonly role: 'validation';
+    readonly part: 'params' | 'query' | 'headers' | 'body';
+}
+export interface TerminalLayerDescriptor<TProtocol extends string = string> {
+    readonly kind: 'terminal';
+    readonly name: `${TProtocol}.${string}`;
+    readonly role: 'terminal';
+    readonly protocol: TProtocol;
+}
+type AnyLayerDescriptor = LayerDescriptor<any, any, any, any, any, any, any, any>;
+type AnyLayerOccurrence = LayerOccurrenceDescriptor<any, any, any, any, any, any, any, any, any>;
+export type PipelineItem = AnyLayerDescriptor | AnyLayerOccurrence | ValidationLayerDescriptor | TerminalLayerDescriptor;
+export declare function isLayerOccurrence(item: PipelineItem): item is AnyLayerOccurrence;
+export declare function layerDefinitionOf(item: AnyLayerDescriptor | AnyLayerOccurrence): AnyLayerDescriptor;
+export declare function childPipelineOf(item: AnyLayerDescriptor | AnyLayerOccurrence): readonly PipelineItem[] | undefined;
+interface PipelineTerminalState<THasTerminal extends boolean, TValid extends boolean> {
+    readonly hasTerminal: THasTerminal;
+    readonly valid: TValid;
+}
+type InvalidPipelineTerminalState = PipelineTerminalState<boolean, false>;
+type FoldPipelineTerminals<TPipeline extends readonly PipelineItem[], TProtocol extends string, TState extends PipelineTerminalState<boolean, boolean>> = TState['valid'] extends false ? TState : number extends TPipeline['length'] ? InvalidPipelineTerminalState : TPipeline extends readonly [infer THead, ...infer TTail] ? TState['hasTerminal'] extends true ? InvalidPipelineTerminalState : FoldPipelineTerminals<Extract<TTail, readonly PipelineItem[]>, TProtocol, FoldPipelineItemTerminals<THead, TProtocol, TState>> : TState;
+type FoldPipelineItemTerminals<TItem, TProtocol extends string, TState extends PipelineTerminalState<boolean, boolean>> = TItem extends TerminalLayerDescriptor<infer TItemProtocol> ? [TItemProtocol, TProtocol] extends [TProtocol, TItemProtocol] ? PipelineTerminalState<true, true> : InvalidPipelineTerminalState : TItem extends LayerOccurrenceDescriptor<any, any, any, any, any, any, any, any, infer TPipeline> ? FoldPipelineTerminals<TPipeline, TProtocol, TState> : TState;
+export type IsValidProtocolPipeline<TPipeline extends readonly PipelineItem[], TProtocol extends string> = FoldPipelineTerminals<TPipeline, TProtocol, PipelineTerminalState<false, true>> extends PipelineTerminalState<true, true> ? true : false;
+export type ShortCircuitResultOf<TItem> = TItem extends LayerOccurrenceDescriptor<any, any, any, any, any, any, any, any, infer TPipeline> ? ShortCircuitResultOfPipeline<TPipeline> | ShortCircuitResultOfLayer<TItem> : ShortCircuitResultOfLayer<TItem>;
+type ShortCircuitResultOfLayer<TItem> = TItem extends {
+    readonly [shortCircuitResultType]?: infer TResult;
+} ? TResult : never;
+export type ShortCircuitDeclarationsOf<TItem> = TItem extends LayerOccurrenceDescriptor<any, any, any, any, any, any, any, any, infer TPipeline> ? readonly [
+    ...NormalizeDeclarations<TItem['shortCircuits']>,
+    ...ShortCircuitDeclarationsOfPipeline<TPipeline>
+] : TItem extends {
+    readonly shortCircuits: infer TShortCircuits;
+} ? TShortCircuits : never;
+type ShortCircuitResultOfPipeline<TPipeline extends readonly PipelineItem[]> = TPipeline[number] extends infer TItem ? ShortCircuitResultOf<TItem> : never;
+type ShortCircuitDeclarationsOfPipeline<TPipeline extends readonly PipelineItem[]> = TPipeline extends readonly [infer THead, ...infer TTail] ? readonly [
+    ...NormalizeDeclarations<ShortCircuitDeclarationsOf<THead>>,
+    ...ShortCircuitDeclarationsOfPipeline<Extract<TTail, readonly PipelineItem[]>>
+] : readonly [];
+type NormalizeDeclarations<TDeclarations> = TDeclarations extends readonly ShortCircuitDeclaration[] ? TDeclarations : readonly [];
+interface PipelineTypeState<TContext extends object, TValidated extends ValidatedInputPart, TDone extends boolean> {
+    readonly context: TContext;
+    readonly validated: TValidated;
+    readonly done: TDone;
+}
+type FoldPipeline<TPipeline extends readonly PipelineItem[], TState extends PipelineTypeState<object, ValidatedInputPart, boolean>> = TState['done'] extends true ? TState : number extends TPipeline['length'] ? TState : TPipeline extends readonly [infer THead, ...infer TTail] ? FoldPipeline<Extract<TTail, readonly PipelineItem[]>, FoldPipelineItem<THead, TState>> : TState;
+type FoldPipelineItem<TItem, TState extends PipelineTypeState<object, ValidatedInputPart, boolean>> = TItem extends TerminalLayerDescriptor ? PipelineTypeState<TState['context'], TState['validated'], true> : TItem extends ValidationLayerDescriptor ? PipelineTypeState<TState['context'], TState['validated'] | TItem['part'], false> : TItem extends LayerOccurrenceDescriptor<any, infer TProvides, any, any, any, any, any, any, infer TPipeline> ? FoldPipeline<TPipeline, PipelineTypeState<TState['context'] & ContextProperties<TProvides>, TState['validated'], false>> : TItem extends LayerDescriptor<any, infer TProvides, any, any, any, any, any, any> ? PipelineTypeState<TState['context'] & ContextProperties<TProvides>, TState['validated'], false> : TState;
+export type ContextProvidedBeforeTerminal<TPipeline extends readonly PipelineItem[], TContext extends object = {}> = number extends TPipeline['length'] ? TContext : FoldPipeline<TPipeline, PipelineTypeState<TContext, never, false>>['context'];
+export type HasValidationBeforeTerminal<TPipeline extends readonly PipelineItem[], TPart extends ValidatedInputPart> = number extends TPipeline['length'] ? false : TPart extends FoldPipeline<TPipeline, PipelineTypeState<{}, never, false>>['validated'] ? true : false;
+export declare function layer<const TRequires extends readonly ContextKey[] = readonly [], const TProvides extends readonly ContextKey[] = readonly [], TContext extends object = {}, TShortCircuitResult = never, const TShortCircuits extends readonly ShortCircuitDeclaration[] = readonly [], const TName extends string = string, const TRole extends Exclude<LayerRole, 'terminal' | 'validation'> = 'generic', const TRequiresValidated extends readonly ValidatedInputPart[] = readonly []>(definition: LayerDefinition<TRequires, TProvides, TContext, TShortCircuitResult, TShortCircuits, TName, TRole, TRequiresValidated>): LayerDescriptor<TRequires, TProvides, TShortCircuitResult, TShortCircuits, TName, TRole, TRequiresValidated, TContext>;
+export {};

package/dist/core/layer.js

@@ -0,0 +1,52 @@
+const shortCircuitMarker = Symbol('loutre.short-circuit');
+export function shortCircuit(result) {
+    return {
+        kind: 'short-circuit',
+        result,
+        [shortCircuitMarker]: true,
+    };
+}
+export function isShortCircuit(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        shortCircuitMarker in value &&
+        value[shortCircuitMarker] === true);
+}
+export function isLayerOccurrence(item) {
+    return item.kind === 'layer' && item.definition !== undefined;
+}
+export function layerDefinitionOf(item) {
+    return isLayerOccurrence(item) ? item.definition : item;
+}
+export function childPipelineOf(item) {
+    return isLayerOccurrence(item) ? item.pipeline : undefined;
+}
+export function layer(definition) {
+    let descriptor;
+    const callable = (pipeline) => Object.freeze({
+        kind: 'layer',
+        name: descriptor.name,
+        role: descriptor.role,
+        requires: descriptor.requires,
+        provides: descriptor.provides,
+        requiresValidated: descriptor.requiresValidated,
+        shortCircuits: descriptor.shortCircuits,
+        definition: descriptor,
+        pipeline,
+    });
+    Object.defineProperty(callable, 'name', {
+        value: definition.name,
+        enumerable: true,
+        configurable: true,
+    });
+    descriptor = Object.assign(callable, {
+        kind: 'layer',
+        role: definition.role ?? 'generic',
+        requires: definition.requires ?? [],
+        provides: definition.provides ?? [],
+        requiresValidated: definition.requiresValidated ?? [],
+        shortCircuits: definition.shortCircuits ?? [],
+        factory: definition.factory,
+    });
+    return Object.freeze(descriptor);
+}

package/dist/core/lifecycle.d.ts

@@ -0,0 +1,34 @@
+import type { TokenLike, TokenValue } from './token.js';
+export interface OnModuleInit {
+    onModuleInit(): void | Promise<void>;
+}
+export interface OnApplicationBootstrap {
+    onApplicationBootstrap(): void | Promise<void>;
+}
+export interface OnModuleDestroy {
+    onModuleDestroy(): void | Promise<void>;
+}
+export interface BeforeApplicationShutdown {
+    beforeApplicationShutdown(signal?: string): void | Promise<void>;
+}
+export interface OnApplicationShutdown {
+    onApplicationShutdown(signal?: string): void | Promise<void>;
+}
+export interface LifecycleHook<TInject extends readonly TokenLike[] = readonly TokenLike[]> {
+    readonly kind: 'lifecycle-hook';
+    readonly inject: TInject;
+    readonly run: (...dependencies: {
+        [K in keyof TInject]: TokenValue<TInject[K]>;
+    }) => void | Promise<void>;
+}
+export declare function hook<const TInject extends readonly TokenLike[]>(definition: {
+    readonly inject: TInject;
+    readonly run: LifecycleHook<TInject>['run'];
+}): LifecycleHook<TInject>;
+export interface ModuleLifecycle {
+    readonly onModuleInit?: LifecycleHook<any>;
+    readonly onApplicationBootstrap?: LifecycleHook<any>;
+    readonly onModuleDestroy?: LifecycleHook<any>;
+    readonly beforeApplicationShutdown?: LifecycleHook<any>;
+    readonly onApplicationShutdown?: LifecycleHook<any>;
+}

package/dist/core/lifecycle.js

@@ -0,0 +1,3 @@
+export function hook(definition) {
+    return { kind: 'lifecycle-hook', ...definition };
+}

package/dist/core/module.d.ts

@@ -0,0 +1,53 @@
+import type { EnvClass } from './env.js';
+import type { ImplementationDescriptor } from './implementation.js';
+import type { ModuleLifecycle } from './lifecycle.js';
+import { type ProviderDeclaration } from './provider.js';
+export interface ModuleDefinition {
+    readonly name?: string;
+    readonly description?: string;
+    readonly imports?: readonly ModuleInstance[];
+    readonly environment?: readonly EnvClass[];
+    readonly providers?: readonly ProviderDeclaration[];
+    readonly implementations?: readonly ImplementationDescriptor[];
+    readonly exports?: readonly unknown[];
+    readonly lifecycle?: ModuleLifecycle;
+    readonly requires?: readonly string[];
+}
+export declare const moduleTypeInfo: unique symbol;
+export interface ModuleTypeInfo<TDefinition extends ModuleDefinition = ModuleDefinition> {
+    readonly protocols: ProtocolsOfModuleDefinition<TDefinition>;
+    readonly capabilities: CapabilitiesOfModuleDefinition<TDefinition>;
+}
+type DirectProtocols<TDefinition extends ModuleDefinition> = TDefinition['implementations'] extends readonly ImplementationDescriptor[] ? TDefinition['implementations'][number]['protocol'] : never;
+type ImportedProtocols<TDefinition extends ModuleDefinition> = TDefinition['imports'] extends readonly ModuleInstance[] ? ModuleProtocols<TDefinition['imports'][number]> : never;
+export type ProtocolsOfModuleDefinition<TDefinition extends ModuleDefinition> = DirectProtocols<TDefinition> | ImportedProtocols<TDefinition>;
+type DirectCapabilities<TDefinition extends ModuleDefinition> = TDefinition['implementations'] extends readonly ImplementationDescriptor[] ? TDefinition['implementations'][number]['capabilities'][number] : never;
+type ImportedCapabilities<TDefinition extends ModuleDefinition> = TDefinition['imports'] extends readonly ModuleInstance[] ? ModuleCapabilities<TDefinition['imports'][number]> : never;
+export type CapabilitiesOfModuleDefinition<TDefinition extends ModuleDefinition> = DirectCapabilities<TDefinition> | ImportedCapabilities<TDefinition>;
+export type ModuleProtocols<TModule> = TModule extends ModuleInstance<infer TDefinition> ? ProtocolsOfModuleDefinition<TDefinition> : never;
+export type ModuleCapabilities<TModule> = TModule extends ModuleInstance<infer TDefinition> ? CapabilitiesOfModuleDefinition<TDefinition> : never;
+export interface ModuleInstance<TDefinition extends ModuleDefinition = ModuleDefinition> {
+    readonly kind: 'module-instance';
+    readonly template: AnyModuleTemplate;
+    readonly args: unknown;
+    readonly definition: TDefinition;
+    readonly [moduleTypeInfo]?: ModuleTypeInfo<TDefinition>;
+}
+export interface AnyModuleTemplate {
+    (args?: any): ModuleInstance<any>;
+    readonly kind: 'module-template';
+    readonly instantiate: (args: any) => ModuleInstance<any>;
+    readonly [moduleTypeInfo]?: ModuleTypeInfo<any>;
+}
+export type ModuleTemplate<Args, TDefinition extends ModuleDefinition = ModuleDefinition> = ([Args] extends [void] ? {
+    (): ModuleInstance<TDefinition>;
+} : {
+    (args: Args): ModuleInstance<TDefinition>;
+}) & {
+    readonly kind: 'module-template';
+    readonly instantiate: (args: Args) => ModuleInstance<TDefinition>;
+    readonly [moduleTypeInfo]?: ModuleTypeInfo<TDefinition>;
+};
+export declare function defineModule<Args = void, const TDefinition extends ModuleDefinition = ModuleDefinition>(factory: (args: Args) => TDefinition): ModuleTemplate<Args, TDefinition>;
+export declare function asModuleInstance(module: ModuleInstance | ModuleTemplate<void>): ModuleInstance;
+export {};

package/dist/core/module.js

@@ -0,0 +1,31 @@
+import { environmentProvider } from './provider.js';
+export const moduleTypeInfo = Symbol('loutre.module-type-info');
+export function defineModule(factory) {
+    const instantiate = (args) => {
+        const declared = factory(args);
+        const environment = [...new Set(declared.environment ?? [])];
+        const providers = [
+            ...environment.map(environmentProvider),
+            ...(declared.providers ?? []),
+        ];
+        return {
+            kind: 'module-instance',
+            template: template,
+            args,
+            definition: {
+                ...declared,
+                ...(environment.length === 0 ? {} : { environment }),
+                ...(providers.length === 0 ? {} : { providers }),
+            },
+        };
+    };
+    const template = ((args) => instantiate(args));
+    Object.defineProperties(template, {
+        kind: { value: 'module-template', enumerable: true },
+        instantiate: { value: instantiate, enumerable: false },
+    });
+    return template;
+}
+export function asModuleInstance(module) {
+    return module.kind === 'module-instance' ? module : module();
+}