awilixify 2.2.1 → 3.0.0

package/dist/lib/http/openapi-builder.d.ts

@@ -0,0 +1,27 @@
+export interface RouteRegistration {
+    method: string;
+    path: string;
+    schema: RouteSchema;
+}
+export interface RouteSchema {
+    body?: unknown;
+    querystring?: unknown;
+    params?: unknown;
+    headers?: unknown;
+    response?: unknown;
+    description?: string;
+    summary?: string;
+    tags?: string[];
+    operationId?: string;
+    deprecated?: boolean;
+}
+export declare function hasValidationSchema(schema: RouteSchema): boolean;
+export declare class OpenAPIBuilder {
+    private routes;
+    registerRoute(method: string, path: string, schema: RouteSchema): void;
+    buildPaths(): Record<string, any>;
+    private buildOperation;
+    private buildParameters;
+    private buildRequestBody;
+    private buildResponses;
+}

package/dist/lib/http/openapi-builder.js

@@ -0,0 +1,83 @@
+export function hasValidationSchema(schema) {
+    return !!(schema?.body ||
+        schema?.querystring ||
+        schema?.params ||
+        schema?.headers);
+}
+export class OpenAPIBuilder {
+    routes = [];
+    registerRoute(method, path, schema) {
+        this.routes.push({ method: method.toLowerCase(), path, schema });
+    }
+    buildPaths() {
+        return this.routes.reduce((paths, route) => {
+            paths[route.path] ??= {};
+            paths[route.path][route.method] = this.buildOperation(route.schema);
+            return paths;
+        }, {});
+    }
+    buildOperation(schema) {
+        const parameters = this.buildParameters(schema);
+        const requestBody = this.buildRequestBody(schema);
+        const responses = this.buildResponses(schema);
+        return {
+            ...(schema.summary && { summary: schema.summary }),
+            ...(schema.description && { description: schema.description }),
+            ...(schema.tags && { tags: schema.tags }),
+            ...(schema.operationId && { operationId: schema.operationId }),
+            ...(schema.deprecated && { deprecated: schema.deprecated }),
+            ...(parameters.length > 0 && { parameters }),
+            ...(requestBody && { requestBody }),
+            responses,
+        };
+    }
+    buildParameters(schema) {
+        const parameters = [];
+        const querySchema = schema.querystring;
+        if (querySchema?.properties) {
+            parameters.push(...Object.entries(querySchema.properties).map(([name, propSchema]) => ({
+                name,
+                in: "query",
+                required: querySchema.required?.includes(name) ?? false,
+                schema: propSchema,
+            })));
+        }
+        const paramsSchema = schema.params;
+        if (paramsSchema?.properties) {
+            parameters.push(...Object.entries(paramsSchema.properties).map(([name, propSchema]) => ({
+                name,
+                in: "path",
+                required: true,
+                schema: propSchema,
+            })));
+        }
+        return parameters;
+    }
+    buildRequestBody(schema) {
+        return schema.body
+            ? {
+                required: true,
+                content: {
+                    "application/json": {
+                        schema: schema.body,
+                    },
+                },
+            }
+            : undefined;
+    }
+    buildResponses(schema) {
+        if (!schema.response)
+            return {};
+        return Object.entries(schema.response).reduce((acc, [statusCode, responseSchema]) => {
+            acc[statusCode] = {
+                description: statusCode === "200" ? "Successful response" : "Response",
+                content: {
+                    "application/json": {
+                        schema: responseSchema,
+                    },
+                },
+            };
+            return acc;
+        }, {});
+    }
+}

package/dist/lib/mediator/contract.types.d.ts

@@ -0,0 +1,159 @@
+import type { EmptyObject } from "../di/common.types.js";
+import type { Module, ModuleDefinition, ModuleImport } from "../di/modules/module.types.js";
+import type { DefPreHandlerMap } from "../di/providers/provider.types.js";
+import type { GlobalCommandPreHandlers, GlobalQueryPreHandlers, NormalizeGlobalPreHandlerMap } from "./global-middlewares.types.js";
+import type { EmptyContext } from "./middleware.types.js";
+type QueryContractModuleDef = {
+    queryPreHandlers?: DefPreHandlerMap;
+    imports?: readonly ModuleImport[];
+};
+type EmptyModuleDef = Record<never, never>;
+type CommandContractModuleDef = {
+    commandPreHandlers?: DefPreHandlerMap;
+    imports?: readonly ModuleImport[];
+};
+type ContractScenario<TPreHandlerKey extends string> = {
+    name: string;
+    includePreHandlerKeys?: readonly TPreHandlerKey[];
+    excludePreHandlerKeys?: readonly TPreHandlerKey[];
+};
+type PreHandlerExportKey = "queryPreHandlerExports" | "commandPreHandlerExports";
+type ExtractModuleDef<T> = T extends Module<infer TDef extends ModuleDefinition> ? TDef : T extends Record<string, unknown> ? T : never;
+type ExtractExportedPreHandlerMap<TModuleDef, TExportKey extends PreHandlerExportKey> = TModuleDef extends {
+    [K in TExportKey]?: infer E;
+} ? [NonNullable<E>] extends [DefPreHandlerMap] ? NonNullable<E> : EmptyObject : EmptyObject;
+type ExtractPreHandlerMapFromImports<TImports extends readonly ModuleImport[] | undefined, TExportKey extends PreHandlerExportKey> = TImports extends readonly [
+    infer First,
+    ...infer Rest extends readonly ModuleImport[]
+] ? ExtractExportedPreHandlerMap<ExtractModuleDef<First>, TExportKey> & ExtractPreHandlerMapFromImports<Rest, TExportKey> : EmptyObject;
+type ExtractMiddlewareContract<M> = M extends {
+    readonly contract: infer C;
+} ? C : M extends new (...args: any[]) => infer I ? I extends {
+    readonly contract: infer C;
+} ? C : never : M extends {
+    useClass: infer U;
+} ? ExtractMiddlewareContract<U> : never;
+type ExtractContextData<T> = T extends Result<infer Data, any> ? Data extends Record<string, unknown> ? Data : never : T extends Record<string, unknown> ? T : never;
+type ExtractContextFromMiddleware<M> = ExtractMiddlewareContract<M> extends {
+    returnType: infer R;
+} ? ExtractContextData<R> : never;
+type ExtractErrorFromMiddleware<M> = ExtractMiddlewareContract<M> extends {
+    returnType: infer R;
+} ? ExtractResultError<R> : never;
+export type AnyContract = {
+    key: string;
+    payload: unknown;
+    response: unknown;
+    returnType?: unknown;
+    context?: Record<string, unknown>;
+    scenarios?: Record<string, unknown>;
+};
+export type QueryContract<K extends string, P, R, Scenarios extends ContractScenario<QueryPreHandlerKeys<M>> | never = never, M extends QueryContractModuleDef = EmptyModuleDef> = Contract<K, P, R> & WithScenario<QueryContractPreHandlerMap<M>, QueryPreHandlerKeys<M>, R, Scenarios> & {
+    returnType: QueryContractReturnType<M, R>;
+    context: ResolveQueryContractContext<M, Scenarios>;
+};
+export type CommandContract<K extends string, P, R, Scenarios extends ContractScenario<CommandPreHandlerKeys<M>> | never = never, M extends CommandContractModuleDef = EmptyModuleDef> = Contract<K, P, R> & {
+    returnType: CommandContractReturnType<M, R>;
+    context: ResolveCommandContractContext<M, Scenarios>;
+} & WithScenario<CommandContractPreHandlerMap<M>, CommandPreHandlerKeys<M>, R, Scenarios>;
+type QueryContractPreHandlerMap<M extends QueryContractModuleDef> = [
+    M
+] extends [never] ? NormalizeGlobalPreHandlerMap<GlobalQueryPreHandlers> : NonNullable<M["queryPreHandlers"]> & NormalizeGlobalPreHandlerMap<GlobalQueryPreHandlers> & ExtractPreHandlerMapFromImports<M["imports"], "queryPreHandlerExports">;
+type CommandContractPreHandlerMap<M extends CommandContractModuleDef> = [
+    M
+] extends [never] ? NormalizeGlobalPreHandlerMap<GlobalCommandPreHandlers> : NonNullable<M["commandPreHandlers"]> & NormalizeGlobalPreHandlerMap<GlobalCommandPreHandlers> & ExtractPreHandlerMapFromImports<M["imports"], "commandPreHandlerExports">;
+type QueryContractReturnType<M extends QueryContractModuleDef, R> = ResolveContractReturnTypeByModule<M, NormalizeGlobalPreHandlerMap<GlobalQueryPreHandlers>, QueryContractPreHandlerMap<M>, R>;
+type CommandContractReturnType<M extends CommandContractModuleDef, R> = ResolveContractReturnTypeByModule<M, NormalizeGlobalPreHandlerMap<GlobalCommandPreHandlers>, CommandContractPreHandlerMap<M>, R>;
+type QueryPreHandlerKeys<M extends QueryContractModuleDef> = [M] extends [never] ? Extract<keyof NormalizeGlobalPreHandlerMap<GlobalQueryPreHandlers>, string> : Extract<keyof NonNullable<M["queryPreHandlers"]>, string> | Extract<keyof NormalizeGlobalPreHandlerMap<GlobalQueryPreHandlers>, string> | Extract<keyof ExtractPreHandlerMapFromImports<M["imports"], "queryPreHandlerExports">, string>;
+type CommandPreHandlerKeys<M extends CommandContractModuleDef> = [M] extends [
+    never
+] ? Extract<keyof NormalizeGlobalPreHandlerMap<GlobalCommandPreHandlers>, string> : Extract<keyof NonNullable<M["commandPreHandlers"]>, string> | Extract<keyof NormalizeGlobalPreHandlerMap<GlobalCommandPreHandlers>, string> | Extract<keyof ExtractPreHandlerMapFromImports<M["imports"], "commandPreHandlerExports">, string>;
+type WithScenario<TPreHandlerMap, TPreHandlerKey extends string, R, Scenarios extends ContractScenario<TPreHandlerKey> | never> = [Scenarios] extends [never] ? Record<never, never> : {
+    scenarios: ResolveScenarioResponseMap<TPreHandlerMap, TPreHandlerKey, R, Scenarios>;
+};
+type ExtractIncludedPreHandlerMap<TMap, TAllKeys extends string, TScenario> = NormalizeScenarioWithDefaultInclude<TScenario, TAllKeys> extends {
+    includePreHandlerKeys: infer Include extends readonly any[];
+} ? Pick<TMap, Extract<Include[number], TAllKeys>> : TMap;
+type NormalizeScenarioWithDefaultInclude<TScenario, TAllKeys extends string> = TScenario extends {
+    includePreHandlerKeys: readonly any[];
+} ? TScenario : TScenario & {
+    includePreHandlerKeys: readonly TAllKeys[];
+};
+type ExtractScenarioPreHandlerMap<TMap, TAllKeys extends string, TScenario> = ExtractIncludedPreHandlerMap<TMap, TAllKeys, TScenario> extends infer TIncluded ? TScenario extends {
+    excludePreHandlerKeys: infer Exclude extends readonly any[];
+} ? Omit<TIncluded, Extract<Exclude[number], keyof TIncluded>> : TIncluded : EmptyContext;
+type ResolveScenarioContext<TPreHandlerMap, TPreHandlerKey extends string, Scenarios extends ContractScenario<TPreHandlerKey>> = Scenarios extends ContractScenario<TPreHandlerKey> ? ResolveContextOrEmpty<ContextFromPreHandlerMap<ExtractScenarioPreHandlerMap<TPreHandlerMap, TPreHandlerKey, Scenarios>>> : never;
+type ExtractPreHandlerErrorsFromMap<TMap> = [
+    Extract<keyof TMap, string>
+] extends [never] ? never : {
+    [K in Extract<keyof TMap, string>]: ExtractErrorFromMiddleware<TMap[K]>;
+}[Extract<keyof TMap, string>];
+type ResolveScenarioResponse<TPreHandlerMap, TPreHandlerKey extends string, R, Scenario extends ContractScenario<TPreHandlerKey>> = ResponseWithErrors<R, ExtractPreHandlerErrorsFromMap<ExtractScenarioPreHandlerMap<TPreHandlerMap, TPreHandlerKey, Scenario>>>;
+type ResolveContractReturnType<TPreHandlerErrors, R> = MergeResponseWithPreHandlerErrors<R, TPreHandlerErrors>;
+type ResolveContractReturnTypeByModule<M, TGlobalPreHandlerMap, TContractPreHandlerMap, R> = [keyof M] extends [never] ? ResolveContractReturnType<ExtractPreHandlerErrorsFromMap<TGlobalPreHandlerMap>, R> : ResolveContractReturnType<ExtractPreHandlerErrorsFromMap<TContractPreHandlerMap>, R>;
+type ResolveScenarioResponseMap<TPreHandlerMap, TPreHandlerKey extends string, R, Scenarios extends ContractScenario<TPreHandlerKey>> = {
+    [Scenario in Scenarios as Scenario["name"]]: {
+        config: Omit<Scenario, "name">;
+        returnType: ResolveScenarioResponse<TPreHandlerMap, TPreHandlerKey, R, Scenario>;
+    };
+};
+type ContextFromMiddlewareOrEmpty<TMiddleware> = [
+    ExtractContextFromMiddleware<TMiddleware>
+] extends [never] ? EmptyContext : ExtractContextFromMiddleware<TMiddleware>;
+type ResolveContextOrEmpty<TContext> = [TContext] extends [
+    Record<string, unknown>
+] ? TContext : EmptyContext;
+type ContextFromPreHandlerMap<TMap> = Extract<keyof TMap, string> extends never ? EmptyContext : UnionToIntersection<{
+    [K in Extract<keyof TMap, string>]: ContextFromMiddlewareOrEmpty<TMap[K]>;
+}[Extract<keyof TMap, string>]>;
+type Contract<K extends string, P, R> = {
+    key: K;
+    payload: P;
+    response: R;
+};
+type ResolveQueryContractContext<M extends QueryContractModuleDef, Scenarios extends ContractScenario<QueryPreHandlerKeys<M>>> = [Scenarios] extends [never] ? ResolveContextOrEmpty<ContextFromPreHandlerMap<QueryContractPreHandlerMap<M>>> : ResolveScenarioContext<QueryContractPreHandlerMap<M>, QueryPreHandlerKeys<M>, Scenarios>;
+type ResolveCommandContractContext<M extends CommandContractModuleDef, Scenarios extends ContractScenario<CommandPreHandlerKeys<M>>> = [Scenarios] extends [never] ? ResolveContextOrEmpty<ContextFromPreHandlerMap<CommandContractPreHandlerMap<M>>> : ResolveScenarioContext<CommandContractPreHandlerMap<M>, CommandPreHandlerKeys<M>, Scenarios>;
+type ExtractResultSuccess<R> = R extends {
+    readonly ok: true;
+    readonly value: infer T;
+} ? T : never;
+type ExtractResultError<R> = R extends {
+    readonly ok: false;
+    readonly error: infer E;
+} ? E : never;
+type IsResult<R> = R extends {
+    readonly ok: true;
+    readonly value: any;
+} | {
+    readonly ok: false;
+    readonly error: any;
+} ? true : false;
+type ResponseWithErrors<Response, Errors> = [Errors] extends [never] ? Response : IsResult<Response> extends true ? Result<ExtractResultSuccess<Response>, ExtractResultError<Response> | Errors> : Result<Response, Errors>;
+type Result<Value, Err> = {
+    readonly ok: true;
+    readonly value: Value;
+    readonly error: undefined;
+} | {
+    readonly ok: false;
+    readonly value: undefined;
+    readonly error: Err;
+};
+type MergeResponseWithPreHandlerErrors<TResponse, TPreHandlerError> = [
+    TPreHandlerError
+] extends [never] ? TResponse : [TResponse] extends [{
+    readonly ok: true;
+    readonly value: infer V;
+}] ? Result<V, TPreHandlerError> : [TResponse] extends [{
+    readonly ok: false;
+    readonly error: infer E;
+}] ? Result<never, E | TPreHandlerError> : [TResponse] extends [
+    {
+        readonly ok: true;
+        readonly value: infer V;
+    } | {
+        readonly ok: false;
+        readonly error: infer E;
+    }
+] ? Result<V, E | TPreHandlerError> : Result<TResponse, TPreHandlerError>;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+export {};

package/dist/lib/mediator/contract.types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/mediator/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class HandlerAlreadyRegisteredError extends Error {
+    constructor(handlerKey: string);
+}
+export declare class HandlerNotRegisteredError extends Error {
+    constructor(handlerKey: string, moduleName: string);
+}
+export declare class InvalidMiddlewareReturnValueError extends Error {
+    constructor(middlewareKey: string, returnedType: string);
+}
+export declare class ContextKeyConflictError extends Error {
+    constructor(middlewareKey: string, conflictingKeys: string[]);
+}
+export declare class MiddlewareRequiredError extends Error {
+    constructor(middlewareKey: string, requiredKey: string);
+}

package/dist/lib/mediator/errors.js

@@ -0,0 +1,33 @@
+export class HandlerAlreadyRegisteredError extends Error {
+    constructor(handlerKey) {
+        super(`Handler "${handlerKey}" already registered!`);
+        this.name = "HandlerAlreadyRegisteredError";
+    }
+}
+export class HandlerNotRegisteredError extends Error {
+    constructor(handlerKey, moduleName) {
+        super(`Handler key of ${handlerKey} is not registered in module: "${moduleName}"`);
+        this.name = "HandlerNotRegisteredError";
+    }
+}
+export class InvalidMiddlewareReturnValueError extends Error {
+    constructor(middlewareKey, returnedType) {
+        super(`Middleware "${middlewareKey}" returned invalid value of type "${returnedType}". ` +
+            `Middlewares must return a Result type or a plain object for context merging.`);
+        this.name = "InvalidMiddlewareReturnValueError";
+    }
+}
+export class ContextKeyConflictError extends Error {
+    constructor(middlewareKey, conflictingKeys) {
+        super(`Middleware "${middlewareKey}" tried to add context keys that already exist: ${conflictingKeys.join(", ")}. ` +
+            `Each middleware must add unique keys to the context.`);
+        this.name = "ContextKeyConflictError";
+    }
+}
+export class MiddlewareRequiredError extends Error {
+    constructor(middlewareKey, requiredKey) {
+        super(`Middleware "${middlewareKey}" requires "${requiredKey}" to run before it. ` +
+            `Ensure "${requiredKey}" is included and appears before "${middlewareKey}" in the execution order.`);
+        this.name = "MiddlewareRequiredError";
+    }
+}

package/dist/lib/mediator/global-middlewares.types.d.ts

@@ -0,0 +1,13 @@
+import type { EmptyObject } from "../di/common.types.js";
+import type { DefPreHandlerMap } from "../di/providers/provider.types.js";
+export interface GlobalQueryPreHandlers {
+}
+export interface GlobalCommandPreHandlers {
+}
+export type NormalizeGlobalPreHandlerMap<T> = [T] extends [DefPreHandlerMap] ? T : EmptyObject;
+export type InferGlobalQueryPreHandlers<TModuleDef> = TModuleDef extends {
+    queryPreHandlerExports: infer TPreHandlers;
+} ? NormalizeGlobalPreHandlerMap<TPreHandlers> : EmptyObject;
+export type InferGlobalCommandPreHandlers<TModuleDef> = TModuleDef extends {
+    commandPreHandlerExports: infer TPreHandlers;
+} ? NormalizeGlobalPreHandlerMap<TPreHandlers> : EmptyObject;

package/dist/lib/mediator/global-middlewares.types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/mediator/handler.types.d.ts

@@ -0,0 +1,16 @@
+import type { AnyContract } from "./contract.types.js";
+import type { EmptyContext } from "./middleware.types.js";
+export interface Handler<C extends AnyContract, K extends C["key"] = C["key"]> {
+    readonly contract: C;
+    executor: Executor<ExtractPayload<C, K>, ExtractResponse<C, K>, ExtractContractContext<C>>;
+}
+export type Executor<P = unknown, R = unknown, Ctx extends EmptyContext = EmptyContext> = (payload: P, context: Ctx) => Promise<R>;
+type ExtractContractContext<C extends AnyContract> = C extends {
+    context: infer TContext extends Record<string, unknown>;
+} ? TContext : EmptyContext;
+type ExtractContractByKey<C extends AnyContract, K extends C["key"]> = Extract<C, {
+    key: K;
+}>;
+export type ExtractPayload<C extends AnyContract, K extends C["key"]> = ExtractContractByKey<C, K>["payload"];
+export type ExtractResponse<C extends AnyContract, K extends C["key"]> = ExtractContractByKey<C, K>["response"];
+export {};

package/dist/lib/mediator/handler.types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/mediator/mediator.d.ts

@@ -0,0 +1,21 @@
+import type { AnyContract } from "./contract.types.js";
+import type { Executor, ExtractPayload } from "./handler.types.js";
+import type { ExecuteArgs, ExecuteResponse, ExecuteResponseByScenario, ExecuteRuntimeOptions, ExtractScenarioName } from "./mediator.types.js";
+import type { MiddlewareResolverMap } from "./middleware.types.js";
+export declare class Mediator<C extends AnyContract> {
+    private handlers;
+    private middlewareResolvers;
+    private moduleName;
+    constructor(middlewareResolvers: MiddlewareResolverMap, moduleName: string);
+    register(key: string, executor: Executor): void;
+    execute<K extends C["key"], Name extends ExtractScenarioName<C, K>>(key: K, payload: ExtractPayload<C, K>, options: ExecuteRuntimeOptions<C, K> & {
+        scenario: Name;
+    }): Promise<ExecuteResponseByScenario<C, K, Name>>;
+    execute<K extends C["key"], TOptions extends ExecuteRuntimeOptions<C, K> = ExecuteRuntimeOptions<C, K>>(key: K, payload: ExtractPayload<C, K>, ...args: ExecuteArgs<C, K, TOptions>): Promise<ExecuteResponse<C, K>>;
+    private executeMiddlewares;
+    private processMiddlewareResult;
+    private resolveApplicableMiddlewares;
+    private ensureMiddlewareDependencies;
+    private mergeContext;
+    private isResult;
+}

package/dist/lib/mediator/mediator.js

@@ -0,0 +1,123 @@
+import { runInRequestScopeContext } from "../di/request-scope-context.js";
+import * as errors from "./errors.js";
+import { Result } from "./result.js";
+export class Mediator {
+    handlers = new Map();
+    middlewareResolvers;
+    moduleName;
+    constructor(middlewareResolvers, moduleName) {
+        this.moduleName = moduleName;
+        this.middlewareResolvers = middlewareResolvers;
+    }
+    register(key, executor) {
+        const keyStr = String(key);
+        if (this.handlers.has(keyStr)) {
+            throw new errors.HandlerAlreadyRegisteredError(keyStr);
+        }
+        this.handlers.set(keyStr, executor);
+    }
+    async execute(key, payload, options) {
+        return runInRequestScopeContext(async () => {
+            const keyStr = String(key);
+            const executor = this.handlers.get(keyStr);
+            if (!executor) {
+                throw new errors.HandlerNotRegisteredError(keyStr, this.moduleName);
+            }
+            const { executionContext, includePreHandlerKeys, excludePreHandlerKeys } = options ?? {};
+            const applicableMiddlewares = this.resolveApplicableMiddlewares({
+                excludePreHandlerKeys,
+                includePreHandlerKeys,
+            });
+            const middlewareResult = await this.executeMiddlewares(applicableMiddlewares, payload, executionContext ?? {});
+            if (middlewareResult.type === "error") {
+                return middlewareResult.error;
+            }
+            const handlerResult = await executor(payload, middlewareResult.context);
+            if (middlewareResult.hasResultMiddleware) {
+                return (this.isResult(handlerResult)
+                    ? handlerResult
+                    : Result.ok(handlerResult));
+            }
+            return handlerResult;
+        });
+    }
+    async executeMiddlewares(middlewares, payload, executionContext) {
+        let context = {};
+        let hasResultMiddleware = false;
+        for (const [middlewareKey, middleware] of middlewares) {
+            const result = await middleware.execute(payload, context, executionContext);
+            if (this.isResult(result)) {
+                hasResultMiddleware = true;
+            }
+            const processed = this.processMiddlewareResult(result, context, middlewareKey);
+            if (processed.shouldShortCircuit) {
+                return { type: "error", error: processed.result };
+            }
+            context = processed.context;
+        }
+        return { type: "success", context, hasResultMiddleware };
+    }
+    processMiddlewareResult(result, currentContext, middlewareKey) {
+        if (this.isResult(result)) {
+            return result.ok
+                ? {
+                    shouldShortCircuit: false,
+                    context: this.mergeContext(currentContext, result.value, middlewareKey),
+                }
+                : { shouldShortCircuit: true, result };
+        }
+        return {
+            shouldShortCircuit: false,
+            context: this.mergeContext(currentContext, result, middlewareKey),
+        };
+    }
+    resolveApplicableMiddlewares(options) {
+        const { includePreHandlerKeys = [], excludePreHandlerKeys = [] } = options ?? {};
+        const filtered = Array.from(this.middlewareResolvers.entries()).filter(([key]) => {
+            if (excludePreHandlerKeys.includes(key)) {
+                return false;
+            }
+            if (includePreHandlerKeys.length > 0) {
+                return includePreHandlerKeys.includes(key);
+            }
+            return true;
+        });
+        const resolvedMiddlewares = filtered.map(([key, resolver]) => [key, resolver()]);
+        this.ensureMiddlewareDependencies(resolvedMiddlewares);
+        return resolvedMiddlewares;
+    }
+    ensureMiddlewareDependencies(middlewares) {
+        const processedKeys = [];
+        for (const [key, middleware] of middlewares) {
+            const requires = middleware.requires || [];
+            for (const requiredKey of requires) {
+                if (!processedKeys.includes(requiredKey)) {
+                    throw new errors.MiddlewareRequiredError(key, requiredKey);
+                }
+            }
+            processedKeys.push(key);
+        }
+    }
+    mergeContext(currentContext, data, middlewareKey) {
+        if (data === undefined) {
+            return currentContext;
+        }
+        if (typeof data !== "object" || data === null) {
+            const returnedType = data === null ? "null" : typeof data;
+            throw new errors.InvalidMiddlewareReturnValueError(middlewareKey, returnedType);
+        }
+        const currentKeys = Object.keys(currentContext);
+        const newKeys = Object.keys(data);
+        const conflictingKeys = newKeys.filter((key) => currentKeys.includes(key));
+        if (conflictingKeys.length > 0) {
+            throw new errors.ContextKeyConflictError(middlewareKey, conflictingKeys);
+        }
+        return { ...currentContext, ...data };
+    }
+    isResult(value) {
+        return (typeof value === "object" &&
+            value !== null &&
+            "ok" in value &&
+            typeof value.ok === "boolean");
+    }
+}

package/dist/lib/mediator/mediator.types.d.ts

@@ -0,0 +1,64 @@
+import type { AnyContract } from "./contract.types.js";
+import type { ExecutionContext } from "./middleware.types.js";
+export type ExtractScenarioName<C extends AnyContract, K extends C["key"]> = Extract<keyof ExtractContractScenarios<C, K>, string>;
+export type ExecuteResponseByScenario<C extends AnyContract, K extends C["key"], Name extends ExtractScenarioName<C, K>> = ExtractScenarioReturnType<C, K, Name>;
+export type ExecuteRuntimeOptions<C extends AnyContract, K extends C["key"]> = ExecutionContextOption & ExecuteOptions<C, K>;
+export type ExecuteArgs<C extends AnyContract, K extends C["key"], TOptions extends ExecuteRuntimeOptions<C, K> = ExecuteRuntimeOptions<C, K>> = IsExecuteOptionsRequired<C, K> extends true ? [options: TOptions] : [options?: never];
+export type ExecuteResponse<C extends AnyContract, K extends C["key"]> = ExtractContractReturnType<C, K>;
+type ExtractContractScenarios<C extends AnyContract, K extends C["key"]> = Extract<C, {
+    key: K;
+}> extends {
+    scenarios: infer S extends Record<string, unknown>;
+} ? S : never;
+type ExtractScenarioByName<C extends AnyContract, K extends C["key"], Name extends string> = Name extends keyof ExtractContractScenarios<C, K> ? ExtractContractScenarios<C, K>[Name] : never;
+type ExtractScenarioConfig<C extends AnyContract, K extends C["key"], Name extends string> = ExtractScenarioByName<C, K, Name> extends {
+    config: infer Config;
+} ? Config : never;
+type ExtractScenarioReturnType<C extends AnyContract, K extends C["key"], Name extends string> = ExtractScenarioByName<C, K, Name> extends {
+    returnType: infer ReturnType;
+} ? ReturnType : ExtractContractReturnType<C, K>;
+type ExecuteNoScenarioOptions = {
+    scenario?: never;
+    includePreHandlerKeys?: never;
+    excludePreHandlerKeys?: never;
+};
+type ExecuteOptions<C extends AnyContract, K extends C["key"]> = [
+    ExtractContractScenarios<C, K>
+] extends [never] ? ExecuteNoScenarioOptions : ExecuteScenarioOptions<C, K>;
+type ScenarioIncludeOption<C extends AnyContract, K extends C["key"], Name extends string> = ExtractScenarioConfig<C, K, Name> extends {
+    includePreHandlerKeys: infer Include extends readonly any[];
+} ? {
+    includePreHandlerKeys: Include;
+} : {
+    includePreHandlerKeys?: never;
+};
+type ScenarioExcludeOption<C extends AnyContract, K extends C["key"], Name extends string> = ExtractScenarioConfig<C, K, Name> extends {
+    excludePreHandlerKeys: infer Exclude extends readonly any[];
+} ? {
+    excludePreHandlerKeys: Exclude;
+} : {
+    excludePreHandlerKeys?: never;
+};
+type ExecuteScenarioOptions<C extends AnyContract, K extends C["key"]> = {
+    [Name in ExtractScenarioName<C, K>]: {
+        scenario: Name;
+    } & ScenarioIncludeOption<C, K, Name> & ScenarioExcludeOption<C, K, Name>;
+}[ExtractScenarioName<C, K>];
+type ExecutionContextOption = [keyof ExecutionContext] extends [never] ? {
+    executionContext?: never;
+} : {
+    executionContext: ExecutionContext;
+};
+type HasScenarios<C extends AnyContract, K extends C["key"]> = [
+    ExtractContractScenarios<C, K>
+] extends [never] ? false : true;
+type IsExecutionContextRequired = [keyof ExecutionContext] extends [never] ? false : true;
+type IsExecuteOptionsRequired<C extends AnyContract, K extends C["key"]> = HasScenarios<C, K> extends true ? true : IsExecutionContextRequired;
+type ExtractContractReturnType<C extends AnyContract, K extends C["key"]> = Extract<C, {
+    key: K;
+}> extends {
+    returnType: infer ReturnType;
+} ? ReturnType : Extract<C, {
+    key: K;
+}>["response"];
+export {};

package/dist/lib/mediator/mediator.types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/mediator/middleware.types.d.ts

@@ -0,0 +1,41 @@
+import type { Result } from "./result.js";
+type EmptyObject = Record<never, never>;
+export interface ExecutionContext {
+}
+export type EmptyContext = EmptyObject;
+export type AnyMiddlewareContract = MiddlewareContract<string, unknown, any>;
+export type AnyContext = Record<string, unknown>;
+export type MiddlewareResolver = () => Middleware;
+export type MiddlewareResolverMap = Map<string, () => Middleware>;
+export type Middleware<C extends AnyMiddlewareContract = AnyMiddlewareContract> = MiddlewareRequires<C> & {
+    readonly contract: C;
+    execute: MiddlewareFn<ExtractContractContext<C>, ExtractMiddlewareReturnType<C>>;
+};
+export type ExtractMiddlewareContext<T> = [T] extends [Result<infer Data, any>] ? Data extends Record<string, unknown> ? Data : EmptyObject : T extends Record<string, unknown> ? T : EmptyObject;
+export type MiddlewareContract<K extends string, ReturnType, RequiredContracts extends readonly AnyMiddlewareContract[] = readonly []> = {
+    key: K;
+    returnType: ReturnType;
+    requires: ExtractRequiredKeysTupleFromContracts<RequiredContracts>;
+    context: MergeContextFromContracts<RequiredContracts>;
+    executionContext: ExecutionContext;
+};
+type ExtractRequiredKeysTupleFromContracts<Contracts extends readonly AnyMiddlewareContract[]> = number extends Contracts["length"] ? readonly string[] : Contracts extends readonly [] ? readonly [] : Contracts extends readonly [infer First, ...infer Rest] ? First extends AnyMiddlewareContract ? Rest extends readonly AnyMiddlewareContract[] ? readonly [
+    First["key"],
+    ...ExtractRequiredKeysTupleFromContracts<Rest>
+] : readonly [First["key"]] : readonly [] : readonly [];
+type MergeContextFromContracts<Contracts extends readonly AnyMiddlewareContract[]> = number extends Contracts["length"] ? AnyContext : Contracts extends readonly [] ? EmptyObject : Contracts extends readonly [infer First, ...infer Rest] ? First extends AnyMiddlewareContract ? Rest extends readonly AnyMiddlewareContract[] ? ExtractMiddlewareContext<First["returnType"]> & MergeContextFromContracts<Rest> : ExtractMiddlewareContext<First["returnType"]> : EmptyObject : EmptyObject;
+type ExtractMiddlewareReturnType<C extends AnyMiddlewareContract> = C["returnType"];
+type ExtractRequiredKeys<C extends AnyMiddlewareContract> = C["requires"][number];
+type ExtractRequiredList<C extends AnyMiddlewareContract> = C["requires"];
+type ExtractContractContext<C extends AnyMiddlewareContract> = C["context"];
+type MiddlewareFn<RequiredContext extends AnyContext = EmptyContext, ReturnType = unknown> = (payload: unknown, context: RequiredContext, executionContext: ExecutionContext) => Promise<ReturnType>;
+type MiddlewareRequires<C extends AnyMiddlewareContract> = [
+    ExtractRequiredKeys<C>
+] extends [never] ? {
+    readonly requires?: readonly [];
+} : string extends ExtractRequiredKeys<C> ? {
+    readonly requires?: readonly string[];
+} : {
+    readonly requires: ExtractRequiredList<C>;
+};
+export {};

package/dist/lib/mediator/middleware.types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/mediator/result.d.ts

@@ -0,0 +1,18 @@
+export type Result<T, E> = Ok<T> | Err<E>;
+declare class Ok<T> {
+    readonly value: T;
+    readonly ok: true;
+    readonly error: undefined;
+    constructor(value: T);
+}
+declare class Err<E> {
+    readonly error: E;
+    readonly ok: false;
+    readonly value: undefined;
+    constructor(error: E);
+}
+export declare const Result: {
+    ok<T>(value: T): Result<T, never>;
+    error<E>(error: E): Result<never, E>;
+};
+export {};