@beignet/core 0.0.1

package/src/client/index.ts

@@ -0,0 +1,45 @@
+/**
+ * beignet/core/client/base
+ *
+ * Base HTTP client for making contract-based requests
+ */
+
+export { SchemaValidationError } from "../errors";
+export type {
+  AnyContractError,
+  ClientContractError,
+  ContractErrorSource,
+  ContractErrorWithCode,
+  ContractErrorWithSource,
+  ContractErrorWithStatus,
+  HttpContractError,
+  InferEndpointContractError,
+  InferEndpointErrorCode,
+  NetworkContractError,
+  ResponseContractError,
+} from "./client";
+export {
+  Client,
+  ContractError,
+  createClient,
+  Endpoint,
+  isContractError,
+} from "./client";
+export type {
+  CallArgs,
+  ClientConfig,
+  EndpointCallArgs,
+  EndpointErrorResult,
+  EndpointResult,
+  EndpointSuccessResult,
+  InferBody,
+  InferEndpointErrorResponse,
+  InferEndpointErrorResponseByStatus,
+  InferEndpointErrorStatus,
+  InferErrorResponse,
+  InferErrorResponseByStatus,
+  InferHeaders,
+  InferPathParams,
+  InferQuery,
+  InferSuccessResponse,
+} from "./types";

package/src/client/types.ts

@@ -0,0 +1,305 @@
+import type {
+  BodyHttpMethod,
+  HttpContractConfig,
+  InferHeaderSchemaInput,
+  InferInput,
+  InferOutput,
+  StandardSchema,
+  StandardSchemaV1,
+} from "../contracts";
+import type { ErrorResponseBody } from "../errors";
+
+/**
+ * Client configuration
+ */
+export type ClientConfig<TProvidedHeaders extends string = never> = {
+  baseUrl?: string;
+  headers?: () => Promise<Record<string, string>> | Record<string, string>;
+  providedHeaders?: readonly TProvidedHeaders[];
+  fetch?: typeof fetch;
+  /** Enable client-side input validation for path, query, and body. Default: false. */
+  validate?: boolean;
+};
+
+type PathParamPrimitive = string | number | boolean;
+
+type UnsupportedPathParamName<Name extends string> = Name extends ""
+  ? true
+  : Name extends `...${string}`
+    ? true
+    : Name extends `[${string}`
+      ? true
+      : Name extends `${string}.${string}`
+        ? true
+        : false;
+
+type SegmentPathParam<Segment extends string> = Segment extends `:${infer Name}`
+  ? UnsupportedPathParamName<Name> extends true
+    ? never
+    : Name
+  : Segment extends `[${infer Name}]`
+    ? UnsupportedPathParamName<Name> extends true
+      ? never
+      : Name
+    : never;
+
+type PathParamNames<TPath extends string> = string extends TPath
+  ? never
+  : TPath extends `${infer Segment}/${infer Rest}`
+    ? SegmentPathParam<Segment> | PathParamNames<Rest>
+    : SegmentPathParam<TPath>;
+
+type InferPathParamsFromTemplate<TPath extends string> = [
+  PathParamNames<TPath>,
+] extends [never]
+  ? undefined
+  : { [K in PathParamNames<TPath>]: PathParamPrimitive };
+
+/**
+ * Infer path params from contract
+ */
+export type InferPathParams<TContract extends HttpContractConfig> =
+  TContract["pathParams"] extends StandardSchemaV1
+    ? InferInput<TContract["pathParams"]>
+    : InferPathParamsFromTemplate<TContract["path"]>;
+
+/**
+ * Infer query params from contract
+ */
+export type InferQuery<TContract extends HttpContractConfig> =
+  TContract["query"] extends StandardSchemaV1
+    ? InferInput<TContract["query"]>
+    : undefined;
+
+export type InferHeaders<TContract extends HttpContractConfig> =
+  InferHeaderSchemaInput<
+    Exclude<TContract["headers"], undefined>
+  > extends undefined
+    ? undefined
+    : InferHeaderSchemaInput<Exclude<TContract["headers"], undefined>>;
+
+/**
+ * Infer body from contract
+ */
+export type InferBody<TContract extends HttpContractConfig> =
+  TContract["method"] extends BodyHttpMethod
+    ? TContract["body"] extends StandardSchemaV1
+      ? InferInput<TContract["body"]>
+      : undefined
+    : undefined;
+
+/**
+ * Any 2xx HTTP success status code (200–299).
+ */
+type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+type ToNumber<S extends string> = S extends `${infer N extends number}`
+  ? N
+  : never;
+type Any2xxCode = ToNumber<`2${Digit}${Digit}`>;
+type NumericKey<K> = K extends number
+  ? K
+  : K extends `${infer N extends number}`
+    ? N
+    : never;
+
+/**
+ * Find all 2xx status keys from a responses record
+ */
+type Any2xxKey<T extends object> = {
+  [K in keyof T]: NumericKey<K> extends Any2xxCode ? K : never;
+}[keyof T];
+
+/**
+ * Find all non-2xx status keys from a responses record
+ */
+type AnyErrorKey<T extends object> = {
+  [K in keyof T]: NumericKey<K> extends Any2xxCode ? never : K;
+}[keyof T];
+
+type ResponseForStatus<
+  TResponses extends object,
+  TStatus extends number,
+> = TStatus extends keyof TResponses
+  ? TResponses[TStatus]
+  : `${TStatus}` extends keyof TResponses
+    ? TResponses[`${TStatus}`]
+    : never;
+
+/**
+ * Infer a single response type from a schema or null
+ */
+type InferResponseType<T> = T extends null
+  ? undefined
+  : T extends StandardSchemaV1
+    ? InferOutput<T>
+    : unknown;
+
+/**
+ * Infer success response from contract (union of all 2xx response types)
+ */
+export type InferSuccessResponse<TContract extends HttpContractConfig> =
+  TContract["responses"] extends Partial<Record<number, StandardSchema | null>>
+    ? Any2xxKey<TContract["responses"]> extends infer K
+      ? K extends keyof TContract["responses"]
+        ? InferResponseType<TContract["responses"][K]>
+        : unknown
+      : unknown
+    : unknown;
+
+/**
+ * Infer error response from contract (union of all non-2xx response types)
+ */
+export type InferErrorResponse<TContract extends HttpContractConfig> =
+  TContract["responses"] extends Partial<Record<number, StandardSchema | null>>
+    ? AnyErrorKey<TContract["responses"]> extends infer K
+      ? K extends keyof TContract["responses"]
+        ? InferResponseType<TContract["responses"][K]>
+        : unknown
+      : unknown
+    : unknown;
+
+/**
+ * Infer declared non-2xx status codes from a contract.
+ */
+export type InferEndpointErrorStatus<TContract extends HttpContractConfig> =
+  TContract["responses"] extends Partial<Record<number, StandardSchema | null>>
+    ? NumericKey<AnyErrorKey<TContract["responses"]>>
+    : never;
+
+/**
+ * Infer a declared non-2xx response body for a specific status.
+ */
+export type InferErrorResponseByStatus<
+  TContract extends HttpContractConfig,
+  TStatus extends number,
+> =
+  TContract["responses"] extends Partial<Record<number, StandardSchema | null>>
+    ? InferResponseType<ResponseForStatus<TContract["responses"], TStatus>>
+    : unknown;
+
+/**
+ * Error bodies a Beignet client can receive for a specific status.
+ */
+export type InferEndpointErrorResponseByStatus<
+  TContract extends HttpContractConfig,
+  TStatus extends number,
+> =
+  | InferErrorResponseByStatus<TContract, TStatus>
+  | ErrorResponseBody
+  | string
+  | undefined;
+
+/**
+ * Error bodies a Beignet client can receive for an endpoint.
+ *
+ * Declared route-owned errors come from the contract. Framework-owned errors
+ * use the standard envelope. Transport escape hatches may return text or no body.
+ */
+export type InferEndpointErrorResponse<TContract extends HttpContractConfig> =
+  | InferErrorResponse<TContract>
+  | ErrorResponseBody
+  | string
+  | undefined;
+
+export type EndpointSuccessResult<TContract extends HttpContractConfig> = {
+  ok: true;
+  status: number;
+  data: InferSuccessResponse<TContract>;
+  response: Response;
+};
+
+export type EndpointErrorResult<TError> = {
+  ok: false;
+  status?: number;
+  error: TError;
+  response?: Response;
+};
+
+export type EndpointResult<TContract extends HttpContractConfig, TError> =
+  | EndpointSuccessResult<TContract>
+  | EndpointErrorResult<TError>;
+
+/**
+ * Call arguments for an endpoint
+ */
+type RequestArg<
+  Name extends "path" | "query" | "body",
+  Value,
+> = Value extends undefined
+  ? { [K in Name]?: undefined }
+  : undefined extends Value
+    ? { [K in Name]?: Value }
+    : { [K in Name]: Value };
+
+type PathArgs<TContract extends HttpContractConfig> = RequestArg<
+  "path",
+  InferPathParams<TContract>
+>;
+
+type QueryArgs<TContract extends HttpContractConfig> = RequestArg<
+  "query",
+  InferQuery<TContract>
+>;
+
+type BodyArgs<TContract extends HttpContractConfig> = RequestArg<
+  "body",
+  InferBody<TContract>
+>;
+
+type ProvidedHeaderKeys<THeaders, TProvidedHeaders extends string> = Extract<
+  keyof THeaders,
+  TProvidedHeaders
+>;
+
+type ApplyProvidedHeaders<THeaders, TProvidedHeaders extends string> = Omit<
+  THeaders,
+  ProvidedHeaderKeys<THeaders, TProvidedHeaders>
+> &
+  Partial<Pick<THeaders, ProvidedHeaderKeys<THeaders, TProvidedHeaders>>>;
+
+type HeaderInput<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string,
+> =
+  InferHeaders<TContract> extends undefined
+    ? Record<string, string>
+    : ApplyProvidedHeaders<InferHeaders<TContract>, TProvidedHeaders>;
+
+type HeadersArgs<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string,
+> =
+  InferHeaders<TContract> extends undefined
+    ? { headers?: Record<string, string> }
+    : HasRequiredKeys<HeaderInput<TContract, TProvidedHeaders>> extends never
+      ? { headers?: HeaderInput<TContract, TProvidedHeaders> }
+      : { headers: HeaderInput<TContract, TProvidedHeaders> };
+
+export type EndpointCallArgs<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string = never,
+> = PathArgs<TContract> &
+  QueryArgs<TContract> &
+  BodyArgs<TContract> & {
+    /**
+     * Escape hatch for non-JSON request bodies such as FormData, Blob,
+     * ArrayBuffer, ReadableStream, or pre-serialized text.
+     *
+     * Use `body` for contract-validated JSON requests. `rawBody` is sent as-is
+     * and is not validated or JSON-serialized.
+     */
+    rawBody?: TContract["method"] extends BodyHttpMethod ? BodyInit : never;
+    signal?: AbortSignal;
+  } & HeadersArgs<TContract, TProvidedHeaders>;
+
+type HasRequiredKeys<T> = {
+  [K in keyof T]-?: Record<string, never> extends Pick<T, K> ? never : K;
+}[keyof T];
+
+export type CallArgs<
+  TContract extends HttpContractConfig,
+  TProvidedHeaders extends string = never,
+> =
+  HasRequiredKeys<EndpointCallArgs<TContract, TProvidedHeaders>> extends never
+    ? [args?: EndpointCallArgs<TContract, TProvidedHeaders>]
+    : [args: EndpointCallArgs<TContract, TProvidedHeaders>];