stitchkit 0.47.0 → 0.48.1

package/dist/index-p9d4cxt5.js

@@ -0,0 +1,436 @@
+import {
+  inputIsQuery
+} from "./index-48ffdxgk.js";
+import {
+  isRecord,
+  mapObject,
+  parseTrailingWildcard,
+  typedEntries
+} from "./index-h05ygjqx.js";
+
+// src/browser/cancellation.ts
+class RequestCancellationError extends Error {
+  cause;
+  constructor(cause) {
+    super(cause === "caller" ? "Request was aborted" : "Request timed out");
+    this.cause = cause;
+    this.name = "RequestCancellationError";
+  }
+}
+function createRequestCancellation(caller, timeoutMs) {
+  if (!caller && timeoutMs === undefined) {
+    return { signal: undefined, run: (operation) => operation() };
+  }
+  const controller = new AbortController;
+  let cause;
+  let timer;
+  const abortFromCaller = () => {
+    if (cause)
+      return;
+    cause = "caller";
+    controller.abort(caller?.reason);
+  };
+  if (caller?.aborted)
+    abortFromCaller();
+  else
+    caller?.addEventListener("abort", abortFromCaller, { once: true });
+  if (timeoutMs !== undefined) {
+    timer = setTimeout(() => {
+      if (cause)
+        return;
+      cause = "timeout";
+      controller.abort(new DOMException("Request timed out", "TimeoutError"));
+    }, timeoutMs);
+  }
+  return {
+    signal: controller.signal,
+    async run(operation) {
+      try {
+        if (cause === "caller")
+          throw cancellationError(cause);
+        return await operation(controller.signal);
+      } catch (error) {
+        if (cause)
+          throw cancellationError(cause);
+        throw error;
+      } finally {
+        if (timer !== undefined)
+          clearTimeout(timer);
+        caller?.removeEventListener("abort", abortFromCaller);
+      }
+    }
+  };
+}
+function cancellationError(cause) {
+  return new RequestCancellationError(cause);
+}
+
+// src/browser/client-multipart.ts
+function isFileDescriptor(value) {
+  return typeof value === "object" && value !== null && !(value instanceof Blob) && "uri" in value && typeof value.uri === "string" && "name" in value && typeof value.name === "string" && "type" in value && typeof value.type === "string";
+}
+function isMultipartFile(value) {
+  return value instanceof Blob || isFileDescriptor(value);
+}
+function appendMultipartFile(form, field, file) {
+  const sink = form;
+  sink.append(field, file);
+}
+function appendFormFields(formData, values, skipKeys) {
+  for (const [key, value] of Object.entries(values)) {
+    if (skipKeys.has(key) || value === undefined || value === null)
+      continue;
+    formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+  }
+}
+function buildMultipartForm(descriptor, values) {
+  const formData = new FormData;
+  const fileFields = new Set(Object.keys(descriptor.files));
+  for (const [field, policy] of Object.entries(descriptor.files)) {
+    const value = values[field];
+    if (value === undefined) {
+      if (policy.required !== false)
+        throw new Error(`Missing multipart file field: ${field}`);
+      continue;
+    }
+    if (policy.multiple === true) {
+      if (!Array.isArray(value) || value.length === 0) {
+        throw new Error(`Multipart file field "${field}" must be a non-empty array`);
+      }
+      for (const file of value) {
+        if (!isMultipartFile(file)) {
+          throw new Error(`Invalid multipart file field: ${field}`);
+        }
+        appendMultipartFile(formData, field, file);
+      }
+      continue;
+    }
+    if (!isMultipartFile(value))
+      throw new Error(`Invalid multipart file field: ${field}`);
+    appendMultipartFile(formData, field, value);
+  }
+  appendFormFields(formData, values, fileFields);
+  return formData;
+}
+
+// src/browser/client-url.ts
+function isParamArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number");
+}
+function collectQueryParams(args, endpoint) {
+  const params = {};
+  let hasParams = false;
+  for (const [key, value] of Object.entries(args)) {
+    if (value === undefined || value === null)
+      continue;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || isParamArray(value)) {
+      params[key] = value;
+      hasParams = true;
+      continue;
+    }
+    const what = Array.isArray(value) ? "an array with non-primitive items" : typeof value === "object" ? "a nested object" : `a ${typeof value}`;
+    throw new Error(`${endpoint.method} ${endpoint.path}: input field "${key}" is ${what} — it cannot ` + "travel as a query parameter. GET / DELETE input must be flat (string / number / " + "boolean, or an array of string / number); flatten the field or move the " + "operation to a body verb (POST).");
+  }
+  return hasParams ? params : undefined;
+}
+function hasStringKeys(args, keys) {
+  for (const key of keys) {
+    if (typeof args[key] !== "string")
+      return false;
+  }
+  return true;
+}
+function resolvePathPrefix(config, args) {
+  if (!config?.pathPrefix)
+    return "";
+  if (typeof config.pathPrefix === "string")
+    return config.pathPrefix;
+  const keys = config.stripPrefixKeys ?? [];
+  if (!hasStringKeys(args, keys)) {
+    const missing = keys.find((key) => typeof args[key] !== "string");
+    throw new Error(`Missing path prefix key: ${missing}`);
+  }
+  return config.pathPrefix(args);
+}
+function extractParamNames(path) {
+  const matches = path.match(/:(\w+)/g);
+  const names = matches ? matches.map((match) => match.slice(1)) : [];
+  const wildcard = parseTrailingWildcard(path);
+  if (wildcard)
+    names.push(wildcard.name);
+  return names;
+}
+function fillPathParams(path, args) {
+  const wildcard = parseTrailingWildcard(path);
+  let filled = path.replace(/:(\w+)/g, (_, key) => {
+    const value = args[key];
+    if (value === undefined || value === null) {
+      throw new Error(`Missing path param: ${key}`);
+    }
+    return encodeURIComponent(String(value));
+  });
+  if (!wildcard)
+    return filled;
+  const wildcardValue = args[wildcard.name];
+  if (wildcardValue === undefined || wildcardValue === null) {
+    throw new Error(`Missing path param: ${wildcard.name}`);
+  }
+  const remainder = String(wildcardValue).split("/").map((segment) => encodeURIComponent(segment)).join("/");
+  filled = `${filled.slice(0, -(wildcard.name.length + 1))}${remainder}`;
+  return filled;
+}
+function stripConsumedArgs(args, path, scopeKeys) {
+  const consumed = new Set(scopeKeys);
+  for (const name of extractParamNames(path))
+    consumed.add(name);
+  const remaining = {};
+  for (const [key, value] of Object.entries(args)) {
+    if (!consumed.has(key) && value !== undefined)
+      remaining[key] = value;
+  }
+  return remaining;
+}
+function appendQuery(relativeUrl, params) {
+  if (!params)
+    return relativeUrl;
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(params)) {
+    if (Array.isArray(value)) {
+      for (const item of value)
+        search.append(key, String(item));
+    } else {
+      search.set(key, String(value));
+    }
+  }
+  return search.size > 0 ? `${relativeUrl}?${search}` : relativeUrl;
+}
+function planClientRequest(endpoint, contractPrefix, args, config) {
+  let pathPrefix = resolvePathPrefix(config, args);
+  if (pathPrefix && !pathPrefix.endsWith("/"))
+    pathPrefix += "/";
+  if (pathPrefix.startsWith("/"))
+    pathPrefix = pathPrefix.slice(1);
+  const endpointPath = endpoint.path === "/" ? "" : endpoint.path;
+  let relativeUrl = fillPathParams(`${pathPrefix}${contractPrefix}${endpointPath}`, args);
+  if (relativeUrl.endsWith("/"))
+    relativeUrl = relativeUrl.slice(0, -1);
+  const remainingArgs = stripConsumedArgs(args, endpoint.path, config?.stripPrefixKeys ?? []);
+  if (inputIsQuery(endpoint.method)) {
+    relativeUrl = appendQuery(relativeUrl, collectQueryParams(remainingArgs, endpoint));
+  }
+  return { relativeUrl, remainingArgs };
+}
+function joinClientBaseUrl(baseUrl, relativeUrl) {
+  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const path = relativeUrl.startsWith("/") ? relativeUrl : `/${relativeUrl}`;
+  return `${base}${path}`;
+}
+
+// src/browser/http.ts
+import ky, {
+  isHTTPError,
+  isNetworkError,
+  isTimeoutError
+} from "ky";
+
+// src/browser/request-id.ts
+var REQUEST_ID_HEADER = "x-request-id";
+function responseTraceId(response) {
+  return response?.headers.get(REQUEST_ID_HEADER) ?? undefined;
+}
+
+// src/browser/http.ts
+class ApiError extends Error {
+  code;
+  status;
+  details;
+  hint;
+  traceId;
+  constructor(code, status = 0, details, message, hint, traceId) {
+    super(message ?? `API Error: ${code}`);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+    this.hint = hint;
+    this.traceId = traceId;
+    this.name = "ApiError";
+  }
+  static is(error) {
+    return error instanceof ApiError;
+  }
+}
+function parseApiErrorBody(body) {
+  if (!isRecord(body) || !isRecord(body.error))
+    return null;
+  const error = body.error;
+  if (typeof error.code !== "string")
+    return null;
+  return {
+    code: error.code,
+    message: typeof error.message === "string" ? error.message : undefined,
+    details: error.details,
+    hint: typeof error.hint === "string" ? error.hint : undefined
+  };
+}
+
+// src/browser/client.ts
+function withTimeout(options, endpoint) {
+  const responseType = endpoint.rawResponse ? "response" : endpoint.output ? undefined : "void";
+  if (endpoint.timeout === undefined && responseType === undefined)
+    return options;
+  return {
+    ...options,
+    ...endpoint.timeout !== undefined && { timeout: endpoint.timeout },
+    ...responseType && { responseType }
+  };
+}
+function withOutput(endpoint, result) {
+  if (endpoint.rawResponse)
+    return result;
+  const schema = endpoint.output;
+  return result.then((value) => {
+    if (!schema) {
+      if (value === undefined || value === null)
+        return;
+      throw new Error("Server returned data for an endpoint with no output contract");
+    }
+    if (value === undefined) {
+      throw new Error("Server returned no body for an endpoint with an output contract");
+    }
+    return schema.parse(value);
+  });
+}
+function createClient(contract, configOrClient, contractConfig) {
+  const client = {};
+  const makeExecutor = isHttpAdapter(configOrClient) ? (endpoint) => createHttpExecutor(endpoint, contract.meta.prefix, configOrClient, contractConfig) : (endpoint) => createFetchExecutor(endpoint, contract.meta.prefix, configOrClient, contractConfig);
+  for (const [key, endpoint] of typedEntries(contract.endpoints)) {
+    if (endpoint.expose && !endpoint.expose.includes("HTTP"))
+      continue;
+    setClientMethod(client, key, createEndpointMethod(endpoint, makeExecutor(endpoint), contractConfig));
+  }
+  return client;
+}
+function createClients(contracts, configOrClient, contractConfig) {
+  return mapObject(contracts, (_key, contract) => createClient(contract, configOrClient, contractConfig));
+}
+function isHttpAdapter(value) {
+  return typeof value === "object" && "get" in value && typeof value.get === "function";
+}
+function setClientMethod(target, key, method) {
+  target[key] = method;
+}
+function createEndpointMethod(endpoint, execute, contractConfig) {
+  const hasScopedArguments = (contractConfig?.stripPrefixKeys?.length ?? 0) > 0;
+  if (endpointHasArguments(endpoint) || hasScopedArguments) {
+    const method2 = (requestArgs) => execute(readClientRequestArgs(requestArgs), undefined);
+    return Object.assign(method2, {
+      withOptions: (requestArgs, options) => execute(readClientRequestArgs(requestArgs), readClientRequestOptions(options))
+    });
+  }
+  const method = () => execute({}, undefined);
+  return Object.assign(method, {
+    withOptions: (options) => execute({}, readClientRequestOptions(options))
+  });
+}
+function createHttpExecutor(endpoint, prefix, client, config) {
+  const httpMethod = endpoint.method.toLowerCase();
+  return (requestArgs, options) => {
+    const plan = planClientRequest(endpoint, prefix, requestArgs, config);
+    if (endpoint.multipart) {
+      if (httpMethod === "get" || httpMethod === "head" || httpMethod === "delete") {
+        throw new Error(`Multipart endpoint ${endpoint.method} ${endpoint.path} must be POST / PUT / PATCH`);
+      }
+      const formData = buildMultipartForm(endpoint.multipart, plan.remainingArgs);
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, formData, withTimeout(options, endpoint)));
+    }
+    if (httpMethod === "get" || httpMethod === "head") {
+      return withOutput(endpoint, client[httpMethod](plan.relativeUrl, withTimeout(options, endpoint)));
+    }
+    if (httpMethod === "delete") {
+      return withOutput(endpoint, client.delete(plan.relativeUrl, withTimeout(options, endpoint)));
+    }
+    return withOutput(endpoint, client[httpMethod](plan.relativeUrl, Object.keys(plan.remainingArgs).length > 0 ? plan.remainingArgs : undefined, withTimeout(options, endpoint)));
+  };
+}
+function createFetchExecutor(endpoint, prefix, config, contractConfig) {
+  const executeFetch = config.fetch ?? globalThis.fetch;
+  return async (requestArgs, options) => {
+    const plan = planClientRequest(endpoint, prefix, requestArgs, contractConfig);
+    const url = joinClientBaseUrl(config.baseUrl, plan.relativeUrl);
+    const headers = {
+      Accept: "application/json",
+      ...typeof config.headers === "function" ? config.headers() : config.headers
+    };
+    const cancellation = createRequestCancellation(options?.signal, endpoint.timeout ?? config.timeout ?? 30000);
+    const hasBody = endpoint.method !== "GET" && endpoint.method !== "HEAD" && endpoint.method !== "DELETE" && !endpoint.multipart && endpoint.input && Object.keys(plan.remainingArgs).length > 0;
+    if (hasBody)
+      headers["Content-Type"] = "application/json";
+    try {
+      return await cancellation.run(async (signal) => {
+        const body = endpoint.multipart ? buildMultipartForm(endpoint.multipart, plan.remainingArgs) : hasBody ? JSON.stringify(plan.remainingArgs) : undefined;
+        const res = await executeFetch(url, {
+          method: endpoint.method,
+          headers,
+          credentials: config.credentials,
+          signal,
+          ...body !== undefined && { body }
+        });
+        if (!res.ok) {
+          await throwForErrorResponse(res, config, { error: res.statusText });
+        }
+        if (endpoint.rawResponse)
+          return res;
+        if (!endpoint.output) {
+          const text = await res.text();
+          if (text.length > 0) {
+            throw new Error("Server returned data for an endpoint with no output contract");
+          }
+          return;
+        }
+        return endpoint.output.parse(await res.json());
+      });
+    } catch (error) {
+      if (error instanceof RequestCancellationError) {
+        throw new ApiError(error.cause === "caller" ? "REQUEST_ABORTED" : "REQUEST_TIMEOUT", 0, undefined, error.message);
+      }
+      if (ApiError.is(error))
+        throw error;
+      const message = error instanceof Error ? error.message : undefined;
+      throw new ApiError("UNKNOWN_ERROR", 0, message ? { message } : undefined, message);
+    }
+  };
+}
+function endpointHasArguments(endpoint) {
+  return Boolean(endpoint.params || endpoint.input || endpoint.multipart);
+}
+function readClientRequestArgs(requestArgs) {
+  if (requestArgs !== undefined && !isRecord(requestArgs)) {
+    throw new TypeError("Endpoint arguments must be an object");
+  }
+  return requestArgs ?? {};
+}
+function readClientRequestOptions(value) {
+  if (!isRecord(value))
+    throw new TypeError("Client request options must be an object");
+  const signal = value.signal;
+  if (signal === undefined)
+    return {};
+  if (!isAbortSignal(signal)) {
+    throw new TypeError("Client request signal must be an AbortSignal");
+  }
+  return { signal };
+}
+function isAbortSignal(value) {
+  return typeof value === "object" && value !== null && "aborted" in value && typeof value.aborted === "boolean" && "addEventListener" in value && typeof value.addEventListener === "function" && "removeEventListener" in value && typeof value.removeEventListener === "function";
+}
+async function throwForErrorResponse(res, config, fallbackBody) {
+  const body = await res.json().catch(() => fallbackBody);
+  config.onError?.(res.status, body);
+  const parsed = parseApiErrorBody(body);
+  if (parsed) {
+    throw new ApiError(parsed.code, res.status, parsed.details, parsed.message, parsed.hint, responseTraceId(res));
+  }
+  throw new ApiError("HTTP_ERROR", res.status, { body }, undefined, undefined, responseTraceId(res));
+}
+
+export { ApiError, createClient, createClients };

package/dist/{index-44xysy8r.js → index-ts21eyz4.js}

@@ -5,31 +5,33 @@ import {
 } from "./index-r1qp4rve.js";
 import {
   AppError,
-  __require,
   badRequest,
-  callRuntimeHandler,
   errorCode,
   extractIp,
   getClientInfo,
   getRequestContext,
-  isRecord,
   isUnsafeKey,
   mergeMeta,
   normalizeError,
   parseQueryParams,
-  parseTrailingWildcard,
   recordedErrorMessage,
   resolveSocketIp,
-  resolveTraceContext,
   resolveTraceId,
   runWithRequestContext,
   safeJsonParse,
   setRequestEndpoint,
   setRequestError,
-  typedEntries,
   validateDeclaredOutput,
   zodIssues
-} from "./index-ee621cmy.js";
+} from "./index-jewp9r0a.js";
+import {
+  __require,
+  callRuntimeHandler,
+  isRecord,
+  parseTrailingWildcard,
+  resolveTraceContext,
+  typedEntries
+} from "./index-h05ygjqx.js";
 
 // src/server/multipart.ts
 var DEFAULT_MAX_REQUEST_BYTES = 25 * 1024 * 1024;
@@ -803,6 +805,50 @@ function joinPath(...parts) {
   const joined = parts.filter(Boolean).map((part) => part.replace(/^\/+|\/+$/g, "")).filter(Boolean).join("/");
   return `/${joined}`;
 }
+function routeSegments(path) {
+  return path.split("/").filter(Boolean);
+}
+function rawRouteShape(path) {
+  parseTrailingWildcard(path);
+  const segments = routeSegments(path).map((segment) => {
+    if (segment.startsWith(":"))
+      return { kind: "param" };
+    if (segment.startsWith("*"))
+      return { kind: "wildcard" };
+    return { kind: "static", value: segment };
+  });
+  return {
+    segments,
+    signature: segments.map((segment) => segment.kind === "static" ? segment.value : `:${segment.kind}`).join("/"),
+    wildcard: segments.at(-1)?.kind === "wildcard"
+  };
+}
+function segmentCovers(earlier, later) {
+  if (earlier.kind === "param")
+    return later.kind !== "wildcard";
+  if (earlier.kind === "wildcard")
+    return true;
+  return later.kind === "static" && earlier.value === later.value;
+}
+function routeShapeCovers(earlier, later) {
+  const earlierPrefixLength = earlier.wildcard ? earlier.segments.length - 1 : earlier.segments.length;
+  const laterPrefixLength = later.wildcard ? later.segments.length - 1 : later.segments.length;
+  if (earlier.wildcard) {
+    if (earlierPrefixLength > laterPrefixLength)
+      return false;
+  } else {
+    if (later.wildcard || earlierPrefixLength !== laterPrefixLength)
+      return false;
+  }
+  for (let index = 0;index < earlierPrefixLength; index++) {
+    const earlierSegment = earlier.segments[index];
+    const laterSegment = later.segments[index];
+    if (!earlierSegment || !laterSegment || !segmentCovers(earlierSegment, laterSegment)) {
+      return false;
+    }
+  }
+  return true;
+}
 function matchSegments(patternSegments, requestSegments) {
   const wildcardSegment = patternSegments.at(-1);
   const wildcardName = wildcardSegment?.startsWith("*") ? wildcardSegment.slice(1) : null;
@@ -844,7 +890,7 @@ function buildRouteMap(groups) {
         continue;
       const servicePath = joinPath("/", service.prefix, method.path === "/" ? "" : method.path);
       const fullPath = prefix ? joinPath(prefix, servicePath) : servicePath;
-      const segments = fullPath.split("/").filter(Boolean);
+      const segments = routeSegments(fullPath);
       const entries = map.get(method.method) ?? [];
       entries.push({ method, pattern: fullPath, segments, groupHooks: hooks });
       map.set(method.method, entries);
@@ -867,7 +913,7 @@ function matchRoute(routeMap, httpMethod, pathname) {
   const entries = routeMap.get(httpMethod);
   if (!entries)
     return null;
-  const requestSegments = pathname.split("/").filter(Boolean);
+  const requestSegments = routeSegments(pathname);
   for (const entry of entries) {
     const pathParams = matchSegments(entry.segments, requestSegments);
     if (pathParams) {
@@ -881,7 +927,7 @@ function matchRoute(routeMap, httpMethod, pathname) {
   return null;
 }
 function allowedMethods(routeMap, pathname) {
-  const requestSegments = pathname.split("/").filter(Boolean);
+  const requestSegments = routeSegments(pathname);
   const methods = [];
   for (const [method, entries] of routeMap) {
     for (const entry of entries) {
@@ -939,16 +985,16 @@ function matchRawRoute(rawRoutes, httpMethod, pathname) {
     if (route.method !== "ALL" && route.method !== httpMethod)
       continue;
     if (parseTrailingWildcard(route.path)) {
-      const routeSegs = route.path.split("/").filter(Boolean);
-      const pathSegs = pathname.split("/").filter(Boolean);
+      const routeSegs = routeSegments(route.path);
+      const pathSegs = routeSegments(pathname);
       const params = matchSegments(routeSegs, pathSegs);
       if (params)
         return { route, params };
       continue;
     }
     if (route.path.includes("/:")) {
-      const routeSegs = route.path.split("/").filter(Boolean);
-      const pathSegs = pathname.split("/").filter(Boolean);
+      const routeSegs = routeSegments(route.path);
+      const pathSegs = routeSegments(pathname);
       const params = matchSegments(routeSegs, pathSegs);
       if (params)
         return { route, params };
@@ -960,8 +1006,37 @@ function matchRawRoute(rawRoutes, httpMethod, pathname) {
   return null;
 }
 function validateRawRoutes(rawRoutes) {
-  for (const route of rawRoutes ?? [])
-    parseTrailingWildcard(route.path);
+  const routes = rawRoutes ?? [];
+  const shapes = routes.map((route) => rawRouteShape(route.path));
+  const conflicts = [];
+  for (const [laterIndex, later] of routes.entries()) {
+    const laterShape = shapes[laterIndex];
+    if (!laterShape)
+      continue;
+    for (let earlierIndex = 0;earlierIndex < laterIndex; earlierIndex++) {
+      const earlier = routes[earlierIndex];
+      const earlierShape = shapes[earlierIndex];
+      if (!earlier || !earlierShape)
+        continue;
+      if (earlier.method === later.method && earlier.path === later.path) {
+        conflicts.push(`${later.method} ${later.path} duplicates earlier ${earlier.method} ${earlier.path}`);
+        continue;
+      }
+      if (earlier.method === later.method && earlierShape.signature === laterShape.signature) {
+        conflicts.push(`${later.method} ${later.path} has the same parameter shape as earlier ${earlier.method} ${earlier.path}`);
+        continue;
+      }
+      const methodCovered = earlier.method === "ALL" || earlier.method === later.method;
+      if (methodCovered && routeShapeCovers(earlierShape, laterShape)) {
+        conflicts.push(`${later.method} ${later.path} is unreachable because earlier ${earlier.method} ${earlier.path} matches every request it could receive`);
+      }
+    }
+  }
+  if (conflicts.length > 0) {
+    throw new Error(`[stitchkit] conflicting raw routes:
+- ${conflicts.join(`
+- `)}`);
+  }
 }
 
 // src/server/create.ts
@@ -1345,11 +1420,11 @@ function defineMultipartStream(endpoint, config) {
   };
 }
 var HTTP_ONLY = Object.freeze(["HTTP"]);
-function implement(contract, handlers) {
+function bindContract(contract, handlers) {
   const methods = {};
   const groupScope = contract.meta.scope ?? "public";
   for (const [key, endpoint] of typedEntries(contract.endpoints)) {
-    const typedHandler = handlers[key];
+    const typedHandler = handlers[String(key)];
     const isStreaming = endpoint.multipart?.delivery === "stream";
     if (!isStreaming && typeof typedHandler !== "function") {
       throw new Error(`[stitchkit] implement: missing handler for "${contract.meta.prefix}.${String(key)}"`);
@@ -1398,9 +1473,56 @@ function implement(contract, handlers) {
     methods
   };
 }
+function implement(contract, handlers) {
+  return bindContract(contract, handlers);
+}
 function createImplement() {
   return (contract, handlers) => implement(contract, handlers);
 }
+function isImplementationContract(value) {
+  return isRecord(value) && isRecord(value.meta) && typeof value.meta.prefix === "string" && isRecord(value.endpoints);
+}
+function bindRegistry(contracts, handlers) {
+  const contractKeys = Object.keys(contracts);
+  const handlerKeys = Object.keys(handlers);
+  const missing = contractKeys.filter((key) => !Object.hasOwn(handlers, key));
+  const extra = handlerKeys.filter((key) => !Object.hasOwn(contracts, key));
+  if (missing.length > 0 || extra.length > 0) {
+    throw new Error(`[stitchkit] implementRegistry: registry mismatch (missing: ${missing.join(", ") || "none"}; extra: ${extra.join(", ") || "none"})`);
+  }
+  const prefixes = new Map;
+  const services = [];
+  for (const [key, candidate] of Object.entries(contracts)) {
+    if (!isImplementationContract(candidate)) {
+      throw new TypeError(`[stitchkit] implementRegistry: registry entry "${key}" must be one contract; composed arrays and namespaces are not supported`);
+    }
+    const contract = candidate;
+    const previousKey = prefixes.get(contract.meta.prefix);
+    if (previousKey !== undefined) {
+      throw new Error(`[stitchkit] implementRegistry: duplicate contract prefix "${contract.meta.prefix}" at "${previousKey}" and "${key}"`);
+    }
+    prefixes.set(contract.meta.prefix, key);
+    const entryHandlers = handlers[key];
+    if (!isRecord(entryHandlers)) {
+      throw new TypeError(`[stitchkit] implementRegistry: handlers for "${key}" must be an object`);
+    }
+    const endpointKeys = Object.keys(contract.endpoints);
+    const handlerEntryKeys = Object.keys(entryHandlers);
+    const missingEndpoints = endpointKeys.filter((endpointKey) => !Object.hasOwn(entryHandlers, endpointKey));
+    const extraEndpoints = handlerEntryKeys.filter((endpointKey) => !Object.hasOwn(contract.endpoints, endpointKey));
+    if (missingEndpoints.length > 0 || extraEndpoints.length > 0) {
+      throw new Error(`[stitchkit] implementRegistry: handlers for "${key}" mismatch (missing: ${missingEndpoints.join(", ") || "none"}; extra: ${extraEndpoints.join(", ") || "none"})`);
+    }
+    services.push(bindContract(contract, entryHandlers));
+  }
+  return services;
+}
+function implementRegistry(contracts, handlers) {
+  return bindRegistry(contracts, handlers);
+}
+function createImplementRegistry() {
+  return (contracts, handlers) => bindRegistry(contracts, handlers);
+}
 
 // src/realtime/rejection.ts
 import { z } from "zod";
@@ -1768,4 +1890,4 @@ function socketIoLane(websocket) {
   });
 }
 
-export { parseMultipart, createHandler, defineMultipartStream, implement, createImplement, bindRealtimeServer, webSocketLane, composeWebSocketHandlers, createSocketIOServer, socketIoLane };
+export { parseMultipart, createHandler, defineMultipartStream, implement, createImplement, implementRegistry, createImplementRegistry, bindRealtimeServer, webSocketLane, composeWebSocketHandlers, createSocketIOServer, socketIoLane };