@forklaunch/core 0.11.1 → 0.11.3

package/lib/http/index.d.mts

@@ -1,6 +1,6 @@
 import { ParsedQs } from 'qs';
 export { ParsedQs } from 'qs';
-import { UnionToIntersection, StringWithoutSlash, ExclusiveRecord, Prettify, SanitizePathSlashes, MakePropertyOptionalIfChildrenOptional, PrettyCamelCase, TypeSafeFunction, MergeArrayOfMaps, UnionToIntersectionChildren, EmptyObject } from '@forklaunch/common';
+import { UnionToIntersection, StringWithoutSlash, ExclusiveRecord, Prettify, SanitizePathSlashes, MakePropertyOptionalIfChildrenOptional, PrettyCamelCase, TypeSafeFunction, EmptyObject } from '@forklaunch/common';
 import { AnySchemaValidator, UnboxedObjectSchema, IdiomaticSchema, Schema } from '@forklaunch/validator';
 import { CorsOptions } from 'cors';
 import { Counter, Gauge, Histogram, UpDownCounter, ObservableCounter, ObservableGauge, ObservableUpDownCounter, Span } from '@opentelemetry/api';
@@ -382,6 +382,24 @@ interface RequestContext {
     /** Active OpenTelemetry Span */
     span?: Span;
 }
+interface ForklaunchBaseRequest<P extends ParamsDictionary, ReqBody extends Record<string, unknown>, ReqQuery extends ParsedQs, ReqHeaders extends Record<string, string>> {
+    /** Request parameters */
+    params: P;
+    /** Request headers */
+    headers: ReqHeaders;
+    /** Request body */
+    body: ReqBody;
+    /** Request query */
+    query: ReqQuery;
+    /** Method */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD' | 'CONNECT' | 'TRACE';
+    /** Request path */
+    path: string;
+    /** Original path */
+    originalPath: string;
+    /** OpenTelemetry Collector */
+    openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>;
+}
 /**
  * Interface representing a Forklaunch request.
  *
@@ -561,6 +579,9 @@ type ForklaunchNextFunction = (err?: unknown) => void;
 type ResolvedForklaunchRequest<SV extends AnySchemaValidator, P extends ParamsDictionary, ReqBody extends Record<string, unknown>, ReqQuery extends ParsedQs, ReqHeaders extends Record<string, string>, BaseRequest> = unknown extends BaseRequest ? ForklaunchRequest<SV, P, ReqBody, ReqQuery, ReqHeaders> : {
     [key in keyof BaseRequest]: key extends keyof ForklaunchRequest<SV, P, ReqBody, ReqQuery, ReqHeaders> ? ForklaunchRequest<SV, P, ReqBody, ReqQuery, ReqHeaders>[key] : key extends keyof BaseRequest ? BaseRequest[key] : never;
 };
+type ResolvedForklaunchAuthRequest<P extends ParamsDictionary, ReqBody extends Record<string, unknown>, ReqQuery extends ParsedQs, ReqHeaders extends Record<string, string>, BaseRequest> = unknown extends BaseRequest ? ForklaunchBaseRequest<P, ReqBody, ReqQuery, ReqHeaders> : {
+    [key in keyof BaseRequest]: key extends keyof ForklaunchBaseRequest<P, ReqBody, ReqQuery, ReqHeaders> ? ForklaunchBaseRequest<P, ReqBody, ReqQuery, ReqHeaders>[key] : key extends keyof BaseRequest ? BaseRequest[key] : never;
+};
 /**
  * Represents a middleware handler with schema validation.
  *
@@ -900,13 +921,67 @@ type ContractDetailsOrMiddlewareOrTypedHandler<SV extends AnySchemaValidator, Na
 type MiddlewareOrMiddlewareWithTypedHandler<SV extends AnySchemaValidator, Name extends string, ContractMethod extends Method, Path extends `/${string}`, P extends ParamsObject<SV>, ResBodyMap extends ResponsesObject<SV>, ReqBody extends Body<SV>, ReqQuery extends QueryObject<SV>, ReqHeaders extends HeadersObject<SV>, ResHeaders extends HeadersObject<SV>, LocalsObj extends Record<string, unknown>, BaseRequest, BaseResponse, NextFunction, Auth extends SchemaAuthMethods<SV, P, ReqBody, ReqQuery, ReqHeaders, BaseRequest>> = ExpressLikeSchemaHandler<SV, P, ResBodyMap, ReqBody, ReqQuery, ReqHeaders, ResHeaders, LocalsObj, BaseRequest, BaseResponse, NextFunction> | TypedHandler<SV, Name, ContractMethod, Path, P, ResBodyMap, ReqBody, ReqQuery, ReqHeaders, ResHeaders, LocalsObj, BaseRequest, BaseResponse, NextFunction, Auth>;
 
 /**
- * Extracts all fetchMaps from an array of routers and merges them
- */
-type UnionedFetchMap<Routers extends readonly unknown[]> = MergeArrayOfMaps<{
-    [K in keyof Routers]: Routers[K] extends {
-        fetchMap: infer FM;
-    } ? FM extends Record<string, unknown> ? FM : Record<string, never> : Record<string, never>;
-}>;
+ * Creates a type-safe fetch function based on a provided fetch map.
+ * This type generates a function that provides compile-time type safety for HTTP requests,
+ * ensuring that the correct path and request parameters are used for each endpoint.
+ *
+ * @template FetchMap - A record mapping paths to their corresponding TypeSafeFunction signatures
+ * @param FetchMap[Path] - Each path should map to a TypeSafeFunction that defines the request/response contract
+ *
+ * @returns A generic function that:
+ * - Takes a path parameter constrained to keys of FetchMap
+ * - Takes optional request initialization parameters based on the function signature
+ * - Returns a Promise of the expected response type
+ *
+ * @remarks
+ * The function parameters are conditionally typed:
+ * - If the mapped function expects body, query, params, or headers, reqInit is required
+ * - Otherwise, reqInit is optional
+ * - If the path doesn't map to a TypeSafeFunction, reqInit is never
+ *
+ * @example
+ * ```typescript
+ * // Define your API endpoints
+ * type UserAPI = {
+ *   '/users': (baseUrl: string, options?: { query?: { limit?: number } }) => Promise<User[]>;
+ *   '/users/:id': (baseUrl: string, options: { params: { id: string } }) => Promise<User>;
+ *   '/users/create': (baseUrl: string, options: { body: CreateUserRequest }) => Promise<User>;
+ * };
+ *
+ * // Create a type-safe fetch function
+ * type UserFetch = FetchFunction<UserAPI>;
+ *
+ * // Usage examples
+ * const userFetch: UserFetch = async (path, reqInit) => {
+ *   // Implementation details...
+ * };
+ *
+ * // Type-safe calls
+ * const users = await userFetch('/users'); // reqInit is optional
+ * const user = await userFetch('/users/:id', { params: { id: '123' } }); // reqInit required
+ * const newUser = await userFetch('/users/create', { body: { name: 'John' } }); // reqInit required
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced usage with multiple parameter types
+ * type ComplexAPI = {
+ *   '/search': (baseUrl: string, options: {
+ *     query: { q: string; limit?: number };
+ *     headers: { 'X-API-Key': string };
+ *   }) => Promise<SearchResult[]>;
+ * };
+ *
+ * type ComplexFetch = FetchFunction<ComplexAPI>;
+ * const complexFetch: ComplexFetch = async (path, reqInit) => { ... };
+ *
+ * // Both query and headers are required
+ * const results = await complexFetch('/search', {
+ *   query: { q: 'typescript' },
+ *   headers: { 'X-API-Key': 'secret' }
+ * });
+ * ```
+ **/
 type FetchFunction<FetchMap> = <Path extends keyof FetchMap>(path: Path, ...reqInit: FetchMap[Path] extends TypeSafeFunction ? Parameters<FetchMap[Path]>[1] extends {
     body: unknown;
 } | {
@@ -917,52 +992,174 @@ type FetchFunction<FetchMap> = <Path extends keyof FetchMap>(path: Path, ...reqI
     headers: unknown;
 } ? [reqInit: Parameters<FetchMap[Path]>[1]] : [reqInit?: Parameters<FetchMap[Path]>[1]] : [reqInit?: never]) => Promise<FetchMap[Path] extends TypeSafeFunction ? ReturnType<FetchMap[Path]> : never>;
 /**
- * Creates a client SDK type from an array of routers.
+ * Creates a router SDK by combining the router's SDK with its fetch functionality.
+ * This type merges the router's SDK interface with its fetch methods to create
+ * a complete router client.
  *
- * This type maps over router configurations to create a unified SDK client interface.
- * Each router can be either:
- * - A direct object with `sdkName` and `sdk` properties
- * - A function that returns an object with `sdkName` and `sdk` properties
+ * @template TRoute - A route object that must contain both `sdk` and `fetch` properties
+ * @param TRoute.sdk - The SDK interface/methods for the route
+ * @param TRoute.fetch - The fetch functionality for the route
  *
- * @template Routers - Array of router configurations or router factory functions
- * @template {string} Routers[K]['sdkName'] - The name of the SDK for each router
- * @template {Record<string, unknown>} Routers[K]['sdk'] - The SDK methods/endpoints for each router
+ * @returns A prettified object combining the SDK and fetch properties
  *
  * @example
  * ```typescript
- * const routers = [
- *   { sdkName: 'user', sdk: { create: () => {}, get: () => {} } },
- *   () => ({ sdkName: 'auth', sdk: { login: () => {}, logout: () => {} } })
- * ];
+ * type UserRoute = {
+ *   sdk: { getUser: () => Promise<User>; createUser: (data: UserData) => Promise<User> };
+ *   fetch: { get: (path: string) => Promise<Response> };
+ * };
  *
- * type Client = SdkClient<typeof routers>;
- * // Result: { user: { create: () => {}, get: () => {} }, auth: { login: () => {}, logout: () => {} } }
+ * type UserRouter = SdkRouter<UserRoute>;
+ * // Result: {
+ * //   getUser: () => Promise<User>;
+ * //   createUser: (data: UserData) => Promise<User>;
+ * //   fetch: { get: (path: string) => Promise<Response> };
+ * // }
  * ```
  */
-type SdkClient<Routers extends ({
+type SdkRouter<TRoute extends {
+    sdk: unknown;
+    fetch: unknown;
+}> = Prettify<TRoute['sdk'] & {
+    fetch: TRoute['fetch'];
+}>;
+/**
+ * Creates a complete SDK client from a record of route definitions.
+ * Each route in the input is transformed into an SdkRouter, creating a comprehensive
+ * client SDK with all routes and their associated fetch functionality.
+ *
+ * @template Input - A record where each key represents a route name and each value
+ *                   contains the route's SDK, fetch methods, optional SDK name, and base path
+ * @param Input[K].sdk - The SDK interface for route K
+ * @param Input[K].fetch - The fetch functionality for route K
+ * @param Input[K].sdkName - Optional custom name for the SDK (defaults to camelCase basePath)
+ * @param Input[K].basePath - The base URL path for the route (used for SDK naming if sdkName not provided)
+ *
+ * @returns A prettified object where each route becomes an SdkRouter
+ *
+ * @example
+ * ```typescript
+ * type Routes = {
+ *   users: {
+ *     sdk: { getUser: () => Promise<User> };
+ *     fetch: { get: (path: string) => Promise<Response> };
+ *     basePath: '/api/users';
+ *   };
+ *   posts: {
+ *     sdk: { getPost: () => Promise<Post> };
+ *     fetch: { get: (path: string) => Promise<Response> };
+ *     basePath: '/api/posts';
+ *     sdkName: 'articles';
+ *   };
+ * };
+ *
+ * type Client = SdkClient<Routes>;
+ * // Result: {
+ * //   users: { getUser: () => Promise<User>; fetch: {...} };
+ * //   posts: { getPost: () => Promise<Post>; fetch: {...} };
+ * // }
+ * ```
+ */
+type SdkClient<Input extends Record<string, {
+    sdk: unknown;
+    fetch: unknown;
+    sdkName?: string;
     basePath: string;
+}>> = Prettify<{
+    [K in keyof Input]: Prettify<SdkRouter<Input[K]>>;
+}>;
+/**
+ * Validates and unpacks SDK client input by ensuring that each key in the input record
+ * corresponds to either the route's custom `sdkName` or the PrettyCamelCase version
+ * of its `basePath`. This type provides compile-time validation for SDK client configuration.
+ *
+ * @template Input - A record of route definitions to validate
+ * @param Input[K].sdk - The SDK interface for route K
+ * @param Input[K].fetch - The fetch functionality for route K
+ * @param Input[K].sdkName - Optional custom SDK name that should match the key K
+ * @param Input[K].basePath - Base path that when converted to PrettyCamelCase should match key K
+ *
+ * @returns The original Input type if valid, or 'Invalid SDK Client Input' if validation fails
+ *
+ * @example
+ * ```typescript
+ * // Valid input - key matches basePath in camelCase
+ * type ValidInput = {
+ *   apiUsers: {
+ *     sdk: UserSdk;
+ *     fetch: FetchMethods;
+ *     basePath: '/api/users'; // PrettyCamelCase becomes 'apiUsers'
+ *   };
+ * };
+ * type Result1 = UnpackSdkClientInput<ValidInput>; // Returns ValidInput
+ *
+ * // Valid input - key matches custom sdkName
+ * type ValidInput2 = {
+ *   userService: {
+ *     sdk: UserSdk;
+ *     fetch: FetchMethods;
+ *     sdkName: 'userService';
+ *     basePath: '/api/users';
+ *   };
+ * };
+ * type Result2 = UnpackSdkClientInput<ValidInput2>; // Returns ValidInput2
+ *
+ * // Invalid input - key doesn't match either sdkName or camelCase basePath
+ * type InvalidInput = {
+ *   wrongKey: {
+ *     sdk: UserSdk;
+ *     fetch: FetchMethods;
+ *     basePath: '/api/users'; // Should be 'apiUsers'
+ *   };
+ * };
+ * type Result3 = UnpackSdkClientInput<InvalidInput>; // Returns 'Invalid SDK Client Input'
+ * ```
+ */
+type UnpackSdkClientInput<Input extends Record<string, {
+    sdk: unknown;
+    fetch: unknown;
     sdkName?: string;
-    sdk: Record<string, unknown>;
-} | ((...args: never[]) => {
     basePath: string;
+}>> = Prettify<{
+    [K in keyof Input]: K extends Input[K]['sdkName'] ? Input[K] : K extends PrettyCamelCase<Input[K]['basePath']> ? Input[K] : unknown;
+} extends Input ? Prettify<Input> : 'Invalid SDK Client Input'>;
+/**
+ * Type alias for valid SDK client input configuration.
+ * This type serves as a constraint to ensure that input to SDK client functions
+ * conforms to the expected structure with required sdk, fetch, and basePath properties,
+ * plus an optional sdkName property.
+ *
+ * @template Input - A record of route definitions that must conform to the SDK client structure
+ * @param Input[K].sdk - The SDK interface containing route-specific methods
+ * @param Input[K].fetch - The fetch functionality for making HTTP requests
+ * @param Input[K].sdkName - Optional custom name for the SDK (if not provided, uses camelCase basePath)
+ * @param Input[K].basePath - Required base URL path for the route
+ *
+ * @returns The input type unchanged, serving as a validation constraint
+ *
+ * @example
+ * ```typescript
+ * // Use as a constraint in function parameters
+ * function createSdkClient<T extends ValidSdkClientInput<T>>(input: T): SdkClient<T> {
+ *   // Function implementation
+ * }
+ *
+ * // Valid usage
+ * const validInput = {
+ *   users: {
+ *     sdk: { getUser: () => Promise.resolve({}) },
+ *     fetch: { get: (path: string) => fetch(path) },
+ *     basePath: '/api/users'
+ *   }
+ * } satisfies ValidSdkClientInput<UnpackSdkClientInput<typeof validInput>>;
+ * ```
+ */
+type ValidSdkClientInput<Input extends Record<string, {
+    sdk: unknown;
+    fetch: unknown;
     sdkName?: string;
-    sdk: Record<string, unknown>;
-}))[]> = {
-    fetch: UnionedFetchMap<Routers> extends infer MergedFetchMap ? FetchFunction<MergedFetchMap> : never;
-    sdk: UnionToIntersectionChildren<{
-        [K in Routers[number] as PrettyCamelCase<K extends (...args: never[]) => {
-            sdkName?: infer SdkName;
-            basePath: infer BasePath;
-        } ? string extends SdkName ? BasePath : SdkName : K extends {
-            sdkName?: infer SdkName;
-            basePath: infer BasePath;
-        } ? string extends SdkName ? BasePath : SdkName : never>]: K extends (...args: never[]) => {
-            sdk: infer Sdk;
-        } ? Prettify<Sdk> : K extends {
-            sdk: infer Sdk;
-        } ? Prettify<Sdk> : never;
-    }>;
-};
+    basePath: string;
+}>> = Input;
 
 /**
  * A class that represents an Express-like router.
@@ -1426,4 +1623,4 @@ type DocsConfiguration = ({
     type: 'swagger';
 };
 
-export { ATTR_API_NAME, ATTR_CORRELATION_ID, type AuthMethods, type AuthMethodsBase, type BasicAuthMethods, type Body, type BodyObject, type ConstrainedForklaunchRouter, type ContractDetails, type ContractDetailsExpressLikeSchemaHandler, type ContractDetailsOrMiddlewareOrTypedHandler, type DocsConfiguration, type ErrorContainer, type ExpressLikeAuthMapper, type ExpressLikeHandler, type ExpressLikeRouter, type ExpressLikeSchemaAuthMapper, type ExpressLikeSchemaHandler, type ExpressLikeTypedHandler, type ExtractBody, type ExtractContentType, type ExtractResponseBody, type ExtractedParamsObject, type FetchFunction, type FileBody, ForklaunchExpressLikeApplication, ForklaunchExpressLikeRouter, type ForklaunchNextFunction, type ForklaunchRequest, type ForklaunchResErrors, type ForklaunchResHeaders, type ForklaunchResponse, type ForklaunchRoute, type ForklaunchRouter, type ForklaunchSendableData, type ForklaunchStatusResponse, HTTPStatuses, type HeadersObject, type HttpContractDetails, type HttpMethod, type JsonBody, type JwtAuthMethods, type LiveSdkFunction, type LiveTypeFunction, type LiveTypeFunctionRequestInit, type LiveTypeRouteDefinition, type LogFn, type LoggerMeta, type MapParamsSchema, type MapReqBodySchema, type MapReqHeadersSchema, type MapReqQuerySchema, type MapResBodyMapSchema, type MapResHeadersSchema, type MapSchema, type Method, type MetricType, type MetricsDefinition, type MiddlewareContractDetails, type MiddlewareOrMiddlewareWithTypedHandler, type MultipartForm, type NestableRouterBasedHandler, type NumberOnlyObject, OpenTelemetryCollector, type ParamsDictionary, type ParamsObject, type PathBasedHandler, type PathMatch, type PathOrMiddlewareBasedHandler, type PathParamHttpContractDetails, type PathParamMethod, type QueryObject, type RawTypedResponseBody, type RequestContext, type ResolvedForklaunchRequest, type ResponseBody, type ResponseCompiledSchema, type ResponseShape, type ResponsesObject, type SchemaAuthMethods, type SdkClient, type ServerSentEventBody, type StatusCode, type StringOnlyObject, type TelemetryOptions, type TextBody, type TypedBody, type TypedHandler, type TypedMiddlewareDefinition, type TypedNestableMiddlewareDefinition, type TypedResponseBody, type UnionedFetchMap, type UnknownBody, type UnknownResponseBody, type UrlEncodedForm, delete_, discriminateBody, discriminateResponseBodies, enrichExpressLikeSend, evaluateTelemetryOptions, generateMcpServer, generateSwaggerDocument, get, getCodeForStatus, head, httpRequestsTotalCounter, httpServerDurationHistogram, isClientError, isForklaunchRequest, isForklaunchRouter, isInformational, isRedirection, isServerError, isSuccessful, isValidStatusCode, logger, meta, metricsDefinitions, middleware, options, patch, post, put, recordMetric, trace, typedAuthHandler, typedHandler };
+export { ATTR_API_NAME, ATTR_CORRELATION_ID, type AuthMethods, type AuthMethodsBase, type BasicAuthMethods, type Body, type BodyObject, type ConstrainedForklaunchRouter, type ContractDetails, type ContractDetailsExpressLikeSchemaHandler, type ContractDetailsOrMiddlewareOrTypedHandler, type DocsConfiguration, type ErrorContainer, type ExpressLikeAuthMapper, type ExpressLikeHandler, type ExpressLikeRouter, type ExpressLikeSchemaAuthMapper, type ExpressLikeSchemaHandler, type ExpressLikeTypedHandler, type ExtractBody, type ExtractContentType, type ExtractResponseBody, type ExtractedParamsObject, type FetchFunction, type FileBody, type ForklaunchBaseRequest, ForklaunchExpressLikeApplication, ForklaunchExpressLikeRouter, type ForklaunchNextFunction, type ForklaunchRequest, type ForklaunchResErrors, type ForklaunchResHeaders, type ForklaunchResponse, type ForklaunchRoute, type ForklaunchRouter, type ForklaunchSendableData, type ForklaunchStatusResponse, HTTPStatuses, type HeadersObject, type HttpContractDetails, type HttpMethod, type JsonBody, type JwtAuthMethods, type LiveSdkFunction, type LiveTypeFunction, type LiveTypeFunctionRequestInit, type LiveTypeRouteDefinition, type LogFn, type LoggerMeta, type MapParamsSchema, type MapReqBodySchema, type MapReqHeadersSchema, type MapReqQuerySchema, type MapResBodyMapSchema, type MapResHeadersSchema, type MapSchema, type Method, type MetricType, type MetricsDefinition, type MiddlewareContractDetails, type MiddlewareOrMiddlewareWithTypedHandler, type MultipartForm, type NestableRouterBasedHandler, type NumberOnlyObject, OpenTelemetryCollector, type ParamsDictionary, type ParamsObject, type PathBasedHandler, type PathMatch, type PathOrMiddlewareBasedHandler, type PathParamHttpContractDetails, type PathParamMethod, type QueryObject, type RawTypedResponseBody, type RequestContext, type ResolvedForklaunchAuthRequest, type ResolvedForklaunchRequest, type ResponseBody, type ResponseCompiledSchema, type ResponseShape, type ResponsesObject, type SchemaAuthMethods, type SdkClient, type SdkRouter, type ServerSentEventBody, type StatusCode, type StringOnlyObject, type TelemetryOptions, type TextBody, type TypedBody, type TypedHandler, type TypedMiddlewareDefinition, type TypedNestableMiddlewareDefinition, type TypedResponseBody, type UnknownBody, type UnknownResponseBody, type UnpackSdkClientInput, type UrlEncodedForm, type ValidSdkClientInput, delete_, discriminateBody, discriminateResponseBodies, enrichExpressLikeSend, evaluateTelemetryOptions, generateMcpServer, generateSwaggerDocument, get, getCodeForStatus, head, httpRequestsTotalCounter, httpServerDurationHistogram, isClientError, isForklaunchRequest, isForklaunchRouter, isInformational, isRedirection, isServerError, isSuccessful, isValidStatusCode, logger, meta, metricsDefinitions, middleware, options, patch, post, put, recordMetric, trace, typedAuthHandler, typedHandler };