@loutrejs/loutre 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,69 @@
+# @loutrejs/loutre
+
+LoutreのCore packageです。Application Definition、Contract、DI、Pipeline、Task、Trigger、Environment、Arguments、Runtime bindingなど、Loutre Applicationを構成するpublic APIを提供します。
+
+> Loutreは現在v0.xです。Public APIには破壊的変更が入る可能性があります。
+
+## Install
+
+```sh
+npm install @loutrejs/loutre
+```
+
+新しいApplicationを始める場合はinitializerも利用できます。
+
+```sh
+npm create loutre@latest my-app
+```
+
+## Application model
+
+LoutreはHTTP endpointだけを中心にせず、Applicationが実行する処理を同じmodelへ載せます。
+
+- **Contract / Implementation** — protocolごとのinterfaceと実装
+- **Module / DI** — dependencyとApplication構成
+- **Pipeline / Layer** — requestやexecution contextの処理
+- **Task / Trigger / Queue** — 明示実行、schedule、queue consumer
+- **Environment / Arguments** — Hostから渡されるtyped input
+- **Application Graph** — Application構造をRuntimeとToolingで共有
+
+## Example
+
+```ts
+import { defineApplication, task } from '@loutrejs/loutre'
+
+export const hello = task<void, string>({
+  name: 'hello',
+  factory: () => () => 'Hello, Loutre!',
+})
+
+export default defineApplication({
+  modules: [],
+  tasks: [hello],
+})
+```
+
+## Entry points
+
+主なsubpath exportは次のとおりです。
+
+| Entry point                     | Role                     |
+| ------------------------------- | ------------------------ |
+| `@loutrejs/loutre/http`         | HTTP Contract / Pipeline |
+| `@loutrejs/loutre/host`         | Application bootstrap    |
+| `@loutrejs/loutre/binding`      | Host / Queue binding     |
+| `@loutrejs/loutre/runtime`      | Runtime capability       |
+| `@loutrejs/loutre/graph`        | Application Graph        |
+| `@loutrejs/loutre/openapi`      | OpenAPI generation       |
+| `@loutrejs/loutre/presentation` | startup presentation     |
+| `@loutrejs/loutre/message-port` | MessagePort protocol     |
+
+## Documentation
+
+- [Getting Started](https://github.com/come25136/loutrejs/blob/main/docs/getting-started.md)
+- [Architecture](https://github.com/come25136/loutrejs/blob/main/docs/architecture.md)
+- [Examples](https://github.com/come25136/loutrejs/tree/main/examples)
+
+## License
+
+[MIT](https://github.com/come25136/loutrejs/blob/main/LICENSE)

package/dist/adapters/aws-lambda.js

@@ -1,4 +1,5 @@
 import { binding, } from '../application/index.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
 export const awsLambdaRuntime = {
     runtime: 'aws-lambda',
     capabilities: new Set([
@@ -12,6 +13,7 @@ export const awsLambdaRuntime = {
     bind,
 };
 function bind(options) {
+    assertRuntimeEngine('aws-lambda');
     const invocation = binding.invocation({
         application: options.application,
         environment: 'environment' in options ? options.environment : process.env,

package/dist/adapters/bun.d.ts

@@ -3,12 +3,14 @@ type IsAny<TValue> = 0 extends 1 & TValue ? true : false;
 type HttpApplication<TDefinition extends ApplicationDefinition> = IsAny<TDefinition> extends true ? TDefinition : HasHttp<TDefinition> extends true ? TDefinition : never;
 export type BunServeOptions<TDefinition extends ApplicationDefinition> = {
     readonly application: HttpApplication<TDefinition>;
-    readonly port: number;
+    readonly port?: number;
     readonly hostname?: string;
+    readonly shutdownHooks?: boolean;
     readonly environment?: unknown;
 } & BootstrapArguments<TDefinition>;
 export interface BunServeHandle<TDefinition extends ApplicationDefinition = ApplicationDefinition> {
     readonly application: HostBindingApplication<TDefinition>;
+    readonly port: number;
     close(signal?: string): Promise<void>;
 }
 export declare const bunRuntime: {

package/dist/adapters/bun.js

@@ -1,4 +1,7 @@
 import { binding, } from '../application/index.js';
+import { LOUTRE_VERSION, detectPresentationTerminal, startStartupPresentation, } from '../presentation.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
+import { serverUrl } from '../runtime/server-url.js';
 export const bunRuntime = {
     runtime: 'bun',
     capabilities: new Set([
@@ -15,13 +18,20 @@ export const bunRuntime = {
     serve,
 };
 async function serve(options) {
+    assertRuntimeEngine('bun');
     const bun = bunGlobal();
     if (!bun?.serve) {
         throw new Error('LUTRE_BUN_UNAVAILABLE: Bun.serve() is not available.');
     }
+    const startedAt = performance.now();
+    const environment = bun.env ?? {};
+    const presentation = startStartupPresentation({ version: LOUTRE_VERSION }, {
+        terminal: detectPresentationTerminal(process.stdout, environment),
+        write: (value) => console.log(value),
+    });
     const host = binding.host({
         application: options.application,
-        environment: 'environment' in options ? options.environment : (bun.env ?? undefined),
+        environment: 'environment' in options ? options.environment : environment,
         ...('arguments' in options ? { arguments: options.arguments } : {}),
     });
     const http = 'http' in host ? host.http : undefined;
@@ -33,41 +43,88 @@ async function serve(options) {
     if ('triggers' in host.application)
         await host.application.triggers.start();
     let server;
-    try {
-        server = bun.serve({
-            port: options.port,
-            ...(options.hostname === undefined ? {} : { hostname: options.hostname }),
-            fetch: createBunFetchDriver(http),
-        });
-    }
-    catch (error) {
-        await host.application.close().catch(() => undefined);
-        throw error;
+    const requestedPort = options.port;
+    let port = requestedPort ?? 3000;
+    while (true) {
+        try {
+            server = bun.serve({
+                port,
+                ...(options.hostname === undefined
+                    ? {}
+                    : { hostname: options.hostname }),
+                fetch: createBunFetchDriver(http),
+            });
+            break;
+        }
+        catch (error) {
+            if (requestedPort !== undefined || !canRetryOnNextPort(error, port)) {
+                await host.application.close().catch(() => undefined);
+                throw error;
+            }
+            port += 1;
+        }
     }
+    presentation.ready({
+        server: serverUrl(options.hostname, port),
+        runtime: `Bun ${bun.version ?? 'unknown'}`,
+        environment: environment.NODE_ENV ?? 'development',
+        startupDurationMs: performance.now() - startedAt,
+    });
     let closed = false;
-    return {
-        application: host.application,
-        async close(signal) {
-            if (closed)
-                return;
-            closed = true;
-            const errors = [];
-            try {
-                await server.stop(true);
-            }
-            catch (error) {
-                errors.push(error);
-            }
-            try {
-                await host.application.close(signal);
-            }
-            catch (error) {
-                errors.push(error);
-            }
-            if (errors.length > 0)
-                throw new AggregateError(errors, 'Bun runtime shutdown failed');
-        },
+    const closeRuntime = async (signal) => {
+        if (closed)
+            return;
+        closed = true;
+        const errors = [];
+        try {
+            await server.stop(true);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await host.application.close(signal);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'Bun runtime shutdown failed');
+    };
+    const removeShutdownHooks = options.shutdownHooks === false
+        ? undefined
+        : registerBunShutdownHooks(closeRuntime);
+    const close = async (signal) => {
+        removeShutdownHooks?.();
+        await closeRuntime(signal);
+    };
+    return { application: host.application, port, close };
+}
+function registerBunShutdownHooks(close) {
+    const handlers = new Map();
+    const remove = () => {
+        for (const [signal, handler] of handlers)
+            process.off(signal, handler);
+        handlers.clear();
     };
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        const handler = () => {
+            remove();
+            void close(signal);
+        };
+        handlers.set(signal, handler);
+        process.once(signal, handler);
+    }
+    return remove;
+}
+function canRetryOnNextPort(error, port) {
+    return port < 65_535 && isAddressInUseError(error);
+}
+function isAddressInUseError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'EADDRINUSE');
 }
 function createBunFetchDriver(application) {
     let initialization;

package/dist/adapters/cloudflare-workers.js

@@ -1,4 +1,5 @@
 import { binding, } from '../application/index.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
 export const cloudflareWorkersRuntime = {
     runtime: 'cloudflare-workers',
     compatibilityDateMinimum: '2026-08-04',
@@ -15,6 +16,7 @@ export const cloudflareWorkersRuntime = {
     bind,
 };
 function bind(options) {
+    assertRuntimeEngine('cloudflare-workers');
     let invocation;
     let fetch;
     const resolve = (environment) => {

package/dist/adapters/deno.d.ts

@@ -6,8 +6,9 @@ export type DenoRuntimeOptions<TDefinition extends ApplicationDefinition> = {
     readonly environment?: unknown;
 } & BootstrapArguments<TDefinition>;
 export type DenoServeOptions<TDefinition extends ApplicationDefinition> = DenoRuntimeOptions<TDefinition> & {
-    readonly port: number;
+    readonly port?: number;
     readonly hostname?: string;
+    readonly shutdownHooks?: boolean;
 };
 export interface DenoBinding {
     fetch(request: Request): Promise<Response>;
@@ -15,6 +16,7 @@ export interface DenoBinding {
 }
 export interface DenoServeHandle<TDefinition extends ApplicationDefinition = ApplicationDefinition> {
     readonly application: HostBindingApplication<TDefinition>;
+    readonly port: number;
     close(signal?: string): Promise<void>;
 }
 export declare const denoRuntime: {

package/dist/adapters/deno.js

@@ -1,4 +1,7 @@
 import { binding, } from '../application/index.js';
+import { LOUTRE_VERSION, startStartupPresentation } from '../presentation.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
+import { serverUrl } from '../runtime/server-url.js';
 export const denoRuntime = {
     runtime: 'deno',
     capabilities: new Set([
@@ -16,6 +19,7 @@ export const denoRuntime = {
     serve,
 };
 function bind(options) {
+    assertRuntimeEngine('deno');
     const invocation = binding.invocation(bindingOptions(options, denoEnvironment()));
     const http = 'http' in invocation
         ? invocation.http
@@ -31,10 +35,20 @@ function bind(options) {
     };
 }
 async function serve(options) {
+    assertRuntimeEngine('deno');
     const deno = denoGlobal();
     if (!deno?.serve) {
         throw new Error('LUTRE_DENO_UNAVAILABLE: Deno.serve() is not available.');
     }
+    const startedAt = performance.now();
+    const isTTY = deno.stdout?.isTerminal?.() === true;
+    const presentation = startStartupPresentation({ version: LOUTRE_VERSION }, {
+        terminal: {
+            isTTY,
+            color: isTTY && deno.env?.get?.('NO_COLOR') === undefined,
+        },
+        write: (value) => console.log(value),
+    });
     const host = binding.host(bindingOptions(options, denoEnvironment()));
     const http = 'http' in host ? host.http : undefined;
     if (!http) {
@@ -45,42 +59,94 @@ async function serve(options) {
     if ('triggers' in host.application)
         await host.application.triggers.start();
     let server;
-    try {
-        server = deno.serve({
-            port: options.port,
-            ...(options.hostname === undefined
-                ? {}
-                : { hostname: options.hostname }),
-        }, createDenoFetchDriver(http));
-    }
-    catch (error) {
-        await host.application.close().catch(() => undefined);
-        throw error;
+    const requestedPort = options.port;
+    let port = requestedPort ?? 3000;
+    while (true) {
+        try {
+            server = deno.serve({
+                port,
+                ...(options.hostname === undefined
+                    ? {}
+                    : { hostname: options.hostname }),
+                onListen: () => undefined,
+            }, createDenoFetchDriver(http));
+            break;
+        }
+        catch (error) {
+            if (requestedPort !== undefined || !canRetryOnNextPort(error, port)) {
+                await host.application.close().catch(() => undefined);
+                throw error;
+            }
+            port += 1;
+        }
     }
+    presentation.ready({
+        server: serverUrl(options.hostname, port),
+        runtime: `Deno ${deno.version?.deno ?? 'unknown'}`,
+        environment: deno.env?.get?.('DENO_ENV') ??
+            deno.env?.get?.('NODE_ENV') ??
+            'development',
+        startupDurationMs: performance.now() - startedAt,
+    });
     let closed = false;
-    return {
-        application: host.application,
-        async close(signal) {
-            if (closed)
-                return;
-            closed = true;
-            const errors = [];
-            try {
-                await server.shutdown();
-            }
-            catch (error) {
-                errors.push(error);
-            }
-            try {
-                await host.application.close(signal);
-            }
-            catch (error) {
-                errors.push(error);
-            }
-            if (errors.length > 0)
-                throw new AggregateError(errors, 'Deno runtime shutdown failed');
-        },
+    const closeRuntime = async (signal) => {
+        if (closed)
+            return;
+        closed = true;
+        const errors = [];
+        try {
+            await server.shutdown();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await host.application.close(signal);
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'Deno runtime shutdown failed');
+    };
+    const removeShutdownHooks = options.shutdownHooks === false
+        ? undefined
+        : registerDenoShutdownHooks(deno, closeRuntime);
+    const close = async (signal) => {
+        removeShutdownHooks?.();
+        await closeRuntime(signal);
+    };
+    return { application: host.application, port, close };
+}
+function registerDenoShutdownHooks(deno, close) {
+    if (!deno.addSignalListener || !deno.removeSignalListener) {
+        return undefined;
+    }
+    const handlers = new Map();
+    const remove = () => {
+        for (const [signal, handler] of handlers) {
+            deno.removeSignalListener?.(signal, handler);
+        }
+        handlers.clear();
     };
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        const handler = () => {
+            remove();
+            void close(signal);
+        };
+        handlers.set(signal, handler);
+        deno.addSignalListener(signal, handler);
+    }
+    return remove;
+}
+function canRetryOnNextPort(error, port) {
+    return port < 65_535 && isAddressInUseError(error);
+}
+function isAddressInUseError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'EADDRINUSE');
 }
 function createDenoFetchDriver(application) {
     let initialization;

package/dist/adapters/electron.js

@@ -1,5 +1,6 @@
 import { binding, } from '../application/index.js';
 import { attachMessagePort, } from '../message-port/index.js';
+import { assertRuntimeEngine } from '../runtime/engine.js';
 export const electronRuntime = {
     runtime: 'electron',
     capabilities: new Set([
@@ -15,6 +16,7 @@ export const electronRuntime = {
     attach,
 };
 function attach(options) {
+    assertRuntimeEngine('electron');
     const invocation = binding.invocation({
         application: options.application,
         environment: 'environment' in options

package/dist/application/openapi.d.ts

@@ -8,9 +8,15 @@ export interface OpenApiServer {
     readonly url: string;
     readonly description?: string;
 }
+export interface OpenApiOperationIdContext {
+    readonly procedure: string;
+    readonly method: string;
+    readonly path: string;
+}
 export interface GenerateOpenApiOptions {
     readonly info: OpenApiInfo;
     readonly servers?: readonly OpenApiServer[];
+    readonly operationId?: (context: OpenApiOperationIdContext) => string | undefined;
 }
 export interface OpenApiDocument {
     readonly openapi: '3.2.0';

package/dist/application/openapi.js

@@ -13,7 +13,7 @@ const FIXED_METHODS = new Set([
     'query',
 ]);
 export function generateOpenApi(application, options) {
-    const graph = assertValidCompilation(compileApplication({
+    assertValidCompilation(compileApplication({
         modules: application.modules,
         ...(application.arguments === undefined
             ? {}
@@ -21,11 +21,6 @@ export function generateOpenApi(application, options) {
         tasks: application.tasks,
         triggers: application.triggers,
     }));
-    const executable = new Set(graph.executions
-        .filter((execution) => execution.kind === 'protocol' && execution.protocol === 'http')
-        .map((execution) => execution.kind === 'protocol'
-        ? `${execution.implementation}\u0000${execution.procedure}`
-        : ''));
     const registry = new SchemaRegistry();
     const paths = {};
     const operationIds = new Set();
@@ -34,20 +29,15 @@ export function generateOpenApi(application, options) {
             if (implementation.protocol !== 'http')
                 continue;
             for (const procedure of implementation.procedures) {
-                if (!executable.has(`${implementation.name}\u0000${procedure}`))
-                    continue;
                 const protocol = implementation.contract.procedures[procedure]?.protocols.http;
                 if (!protocol || protocol.protocol !== 'http')
                     continue;
                 const typed = protocol;
                 const target = {
                     definition: typed.definition,
-                    ...(implementation.contract.name === undefined
-                        ? {}
-                        : { contractName: implementation.contract.name }),
                     procedure,
                 };
-                const operation = createOperation(target, registry, operationIds);
+                const operation = createOperation(target, registry, operationIds, options.operationId);
                 attachOperation(paths, typed.definition, operation);
             }
         }
@@ -62,12 +52,17 @@ export function generateOpenApi(application, options) {
         ...(Object.keys(schemas).length === 0 ? {} : { components: { schemas } }),
     };
 }
-function createOperation(target, registry, operationIds) {
+function createOperation(target, registry, operationIds, resolveOperationId) {
     const definition = target.definition;
-    const operationId = target.contractName
-        ? `${target.contractName}.${target.procedure}`
-        : undefined;
-    if (operationId) {
+    const operationId = resolveOperationId?.({
+        procedure: target.procedure,
+        method: definition.method,
+        path: definition.path,
+    });
+    if (operationId !== undefined) {
+        if (operationId.length === 0) {
+            throw openApiError('LUTRE_OPENAPI_OPERATION_ID_002', `operationId must not be empty for ${describeTarget(target)}`);
+        }
         if (operationIds.has(operationId)) {
             throw openApiError('LUTRE_OPENAPI_OPERATION_ID_001', `Duplicate operationId: ${operationId}`);
         }
@@ -322,7 +317,7 @@ function rebaseLocalDefinitions(schema, schemaComponentName) {
     return visit(schema);
 }
 function componentName(target, suffix) {
-    return sanitizeComponentName(`${target.contractName ?? 'AnonymousContract'}_${target.procedure}_${suffix}`);
+    return sanitizeComponentName(`${target.definition.method} ${target.definition.path} ${target.procedure} ${suffix}`);
 }
 function sanitizeComponentName(value) {
     const sanitized = value.replace(/[^A-Za-z0-9_.-]+/g, '_');
@@ -340,7 +335,7 @@ function escapeJsonPointer(value) {
     return value.replace(/~/g, '~0').replace(/\//g, '~1');
 }
 function describeTarget(target) {
-    return `${target.contractName ?? 'AnonymousContract'}.${target.procedure}`;
+    return `${target.definition.method.toUpperCase()} ${target.definition.path} (${target.procedure})`;
 }
 function dedupeJsonSchemas(schemas) {
     const seen = new Set();

package/dist/core/contract.d.ts

@@ -12,17 +12,57 @@ export interface ProcedureDefinition<TProtocols extends Record<string, ProtocolD
     readonly kind: 'procedure';
     readonly protocols: TProtocols;
 }
-export declare function procedure<const TProtocols extends Record<string, ProtocolDescriptor>>(definition: {
-    readonly protocols: TProtocols;
-}): ProcedureDefinition<TProtocols>;
+export interface ProtocolGroup<TName extends string = string, TProcedures extends Record<string, ProtocolDescriptor<TName>> = Record<string, ProtocolDescriptor<TName>>> {
+    readonly kind: 'protocol-group';
+    readonly protocol: TName;
+    readonly procedures: TProcedures;
+}
+export declare function protocolGroup<const TName extends string, const TProcedures extends Record<string, ProtocolDescriptor<TName>>>(protocol: TName, procedures: TProcedures): ProtocolGroup<TName, TProcedures>;
 export interface ContractDefinition<TProcedures extends Record<string, ProcedureDefinition> = Record<string, ProcedureDefinition>> {
     readonly kind: 'contract';
-    readonly name?: string;
     readonly procedures: TProcedures;
 }
-export declare function contract<const TProcedures extends Record<string, ProcedureDefinition>>(procedures: TProcedures & DispatchKeyUniquenessConstraint<TProcedures>, options?: {
-    readonly name?: string;
-}): ContractDefinition<TProcedures>;
+type ProcedureNamesOfGroup<TGroup> = TGroup extends ProtocolGroup<string, infer TProcedures> ? keyof TProcedures & string : never;
+type ProcedureNamesOfGroups<TGroups extends readonly ProtocolGroup[]> = ProcedureNamesOfGroup<TGroups[number]>;
+type ProtocolOfGroupProcedure<TGroup, TProcedure extends string> = TGroup extends ProtocolGroup<infer TProtocol, infer TProcedures> ? TProcedure extends keyof TProcedures ? {
+    readonly [K in TProtocol]: TProcedures[TProcedure];
+} : never : never;
+type ProceduresFromGroups<TGroups extends readonly ProtocolGroup[]> = {
+    [TProcedure in ProcedureNamesOfGroups<TGroups>]: ProcedureDefinition<UnionToIntersection<ProtocolOfGroupProcedure<TGroups[number], TProcedure>> extends infer TProtocols extends Record<string, ProtocolDescriptor> ? TProtocols : never>;
+};
+type NonEmptyArrayConstraint<TValues extends readonly unknown[]> = TValues extends readonly [] ? {
+    readonly __requiresAtLeastOneEntry__: never;
+} : unknown;
+type ProcedureProtocolKeysOfGroup<TGroup> = TGroup extends ProtocolGroup<infer TProtocol, infer TProcedures> ? `${keyof TProcedures & string}.${TProtocol}` : never;
+type DuplicateGroupProcedureProtocolKeys<TGroups extends readonly ProtocolGroup[], TSeen extends string = never> = number extends TGroups['length'] ? never : TGroups extends readonly [
+    infer THead extends ProtocolGroup,
+    ...infer TTail extends readonly ProtocolGroup[]
+] ? Extract<ProcedureProtocolKeysOfGroup<THead>, TSeen> | DuplicateGroupProcedureProtocolKeys<TTail, TSeen | ProcedureProtocolKeysOfGroup<THead>> : never;
+type GroupProcedureProtocolUniquenessConstraint<TGroups extends readonly ProtocolGroup[]> = [DuplicateGroupProcedureProtocolKeys<TGroups>] extends [never] ? unknown : {
+    readonly __duplicateProcedureProtocol__: DuplicateGroupProcedureProtocolKeys<TGroups>;
+};
+declare function defineContract<const TGroups extends readonly ProtocolGroup[]>(groups: TGroups & NonEmptyArrayConstraint<TGroups> & GroupProcedureProtocolUniquenessConstraint<TGroups> & DispatchKeyUniquenessConstraint<ProceduresFromGroups<TGroups>>): ContractDefinition<ProceduresFromGroups<TGroups>>;
+type ProcedureNamesOfContract<TContract> = TContract extends ContractDefinition<infer TProcedures> ? keyof TProcedures & string : never;
+type ProcedureNamesOfContracts<TContracts extends readonly ContractDefinition[]> = ProcedureNamesOfContract<TContracts[number]>;
+type ProtocolsOfContractProcedure<TContract, TProcedure extends string> = TContract extends ContractDefinition<infer TProcedures> ? TProcedure extends keyof TProcedures ? TProcedures[TProcedure]['protocols'] : never : never;
+type UnionToIntersection<T> = (T extends unknown ? (value: T) => void : never) extends (value: infer TIntersection) => void ? TIntersection : never;
+type MergedProcedures<TContracts extends readonly ContractDefinition[]> = {
+    [TProcedure in ProcedureNamesOfContracts<TContracts>]: ProcedureDefinition<UnionToIntersection<ProtocolsOfContractProcedure<TContracts[number], TProcedure>> extends infer TProtocols extends Record<string, ProtocolDescriptor> ? TProtocols : never>;
+};
+type ProcedureProtocolKeysOfContract<TContract> = TContract extends ContractDefinition<infer TProcedures> ? {
+    [TProcedure in keyof TProcedures & string]: `${TProcedure}.${keyof TProcedures[TProcedure]['protocols'] & string}`;
+}[keyof TProcedures & string] : never;
+type DuplicateContractProcedureProtocolKeys<TContracts extends readonly ContractDefinition[], TSeen extends string = never> = number extends TContracts['length'] ? never : TContracts extends readonly [
+    infer THead extends ContractDefinition,
+    ...infer TTail extends readonly ContractDefinition[]
+] ? Extract<ProcedureProtocolKeysOfContract<THead>, TSeen> | DuplicateContractProcedureProtocolKeys<TTail, TSeen | ProcedureProtocolKeysOfContract<THead>> : never;
+type ContractProcedureProtocolUniquenessConstraint<TContracts extends readonly ContractDefinition[]> = [DuplicateContractProcedureProtocolKeys<TContracts>] extends [never] ? unknown : {
+    readonly __duplicateProcedureProtocol__: DuplicateContractProcedureProtocolKeys<TContracts>;
+};
+declare function mergeContracts<const TContracts extends readonly ContractDefinition[]>(contracts: TContracts & NonEmptyArrayConstraint<TContracts> & ContractProcedureProtocolUniquenessConstraint<TContracts> & DispatchKeyUniquenessConstraint<MergedProcedures<TContracts>>): ContractDefinition<MergedProcedures<TContracts>>;
+export declare const contract: typeof defineContract & {
+    merge: typeof mergeContracts;
+};
 type ProtocolDispatchEntries<TProcedures extends Record<string, ProcedureDefinition>> = {
     [TProcedure in keyof TProcedures & string]: {
         [TProtocol in keyof TProcedures[TProcedure]['protocols'] & string]: TProcedures[TProcedure]['protocols'][TProtocol] extends {