@afoures/http-client 0.0.0 → 0.1.0

package/dist/lib/types.d.mts

@@ -0,0 +1,218 @@
+import { AbortedError, NetworkError, TimeoutError, UnexpectedError } from "./errors.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { Params } from "@remix-run/route-pattern";
+
+//#region src/lib/types.d.ts
+type Pretty<T> = { [K in keyof T]: T[K] } & {};
+type is_any<T> = boolean extends (T extends never ? true : false) ? true : false;
+type MaybePromise<T> = T | Promise<T>;
+declare const ZeroWidthSpace = "\u200B";
+/** Unrendered character (U+200B) used to mark a string type */
+type ZeroWidthSpace = typeof ZeroWidthSpace;
+type ErrorMessage<message extends string = string> = `error: ${message}${ZeroWidthSpace}`;
+declare namespace Pathname {
+  type Relative = `/${string}`;
+  type WithParams = `${string}:${string}`;
+  type Params<pathname extends Pathname.Relative> = Pretty<{ [param in keyof Params<pathname>]: Params<pathname>[param] | number }>;
+  type DefaultParamsObjectSchema<pathname extends Pathname.Relative> = pathname extends Pathname.WithParams ? Schema._<Pathname.Params<pathname>> : never;
+}
+declare namespace HTTPStatus {
+  type InformationalResponse = 100 | 101 | 102 | 103;
+  type SuccessfulResponse = 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226;
+  type RedirectMessage = 300 | 301 | 302 | 303 | 304 | 307 | 308;
+  type ClientErrorResponse = 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451;
+  type ServerErrorResponse = 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511;
+}
+declare namespace HTTPMethod {
+  type WithBody = "POST" | "PUT" | "PATCH" | "DELETE";
+  type WithoutBody = "GET";
+  type Any = HTTPMethod.WithoutBody | HTTPMethod.WithBody;
+}
+type HeaderValue = string | number | boolean | null | undefined;
+type HeaderReducer = (current_value: string | undefined) => string | undefined | null;
+type HeadersInitWithReducer = [string, HeaderValue | HeaderReducer][] | Record<string, HeaderValue | HeaderReducer> | Headers;
+declare namespace RetryPolicy {
+  type Condition = (context: {
+    request: Request;
+    response: Response | undefined;
+    error: UnexpectedError | NetworkError | TimeoutError | AbortedError | undefined;
+  }) => MaybePromise<boolean>;
+  type Attempts = number | ((context: {
+    request: Request;
+  }) => MaybePromise<number>);
+  type Delay = number | ((context: {
+    response: Response | undefined;
+    error: UnexpectedError | NetworkError | TimeoutError | AbortedError | undefined;
+    request: Request;
+    attempt: number;
+  }) => MaybePromise<number>);
+  type Configuration = {
+    /**
+     * the number of attempts to make before giving up
+     */
+    attempts?: Attempts;
+    /**
+     * the delay before retrying
+     */
+    delay?: Delay;
+    /**
+     * function to determine if a retry attempt should be made
+     */
+    when?: Condition;
+  };
+}
+declare namespace HTTPFetch {
+  type SharedResponseContent = {
+    headers: Headers;
+    raw_response: Response;
+  };
+  export type ClientErrorResponse<Error> = SharedResponseContent & {
+    ok: false;
+    status: HTTPStatus.ClientErrorResponse;
+    error: Error;
+  };
+  export type ServerErrorResponse<Error> = SharedResponseContent & {
+    ok: false;
+    status: HTTPStatus.ServerErrorResponse;
+    error: Error;
+  };
+  export type SuccessfulResponse<Data> = SharedResponseContent & {
+    ok: true;
+  } & ({
+    status: Exclude<HTTPStatus.SuccessfulResponse, 204>;
+    data: Data;
+  } | {
+    status: 204;
+    data: null;
+  });
+  export type RedirectMessage = SharedResponseContent & {
+    ok: false;
+    status: HTTPStatus.RedirectMessage;
+    redirect_to: string | null;
+  };
+  export type TypedParamsInit<pathname extends Pathname.Relative, params_schema extends Schema._> = is_any<params_schema> extends true ? {
+    params: any;
+  } : [params_schema] extends [never] ? pathname extends Pathname.WithParams ? {
+    params: Pathname.Params<pathname>;
+  } : {} : {
+    params: Schema.infer_input<params_schema>;
+  };
+  export type TypedQueryInit<query_schema extends Schema._> = is_any<query_schema> extends true ? {
+    query: any;
+  } : [query_schema] extends [never] ? {} : undefined extends Schema.infer_input<query_schema> ? {
+    query?: Schema.infer_input<query_schema>;
+  } : {
+    query: Schema.infer_input<query_schema>;
+  };
+  export type TypedBodyInit<body_schema extends Schema._> = is_any<body_schema> extends true ? {
+    body: any;
+  } : [body_schema] extends [never] ? {} : undefined extends Schema.infer_input<body_schema> ? {
+    body?: Schema.infer_input<body_schema>;
+  } : {
+    body: Schema.infer_input<body_schema>;
+  };
+  export type DefaultRequestInit = {
+    headers?: HeadersInitWithReducer;
+  } & Omit<RequestInit, "body" | "method" | "headers">;
+  export type OptionalRequestInit = {
+    /**
+     * timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * retry policy
+     */
+    retry?: RetryPolicy.Configuration;
+  };
+  export {};
+}
+declare namespace Schema {
+  type _<input = unknown, output = input> = StandardSchemaV1<input, output>;
+  type Any = Schema._<any, any>;
+  type Unknown = Schema._<unknown, unknown>;
+  type infer_input<schema extends Schema.Any, default_value extends unknown = never> = [default_value] extends [never] ? StandardSchemaV1.InferInput<schema> : [schema] extends [never] ? default_value : StandardSchemaV1.InferInput<schema>;
+  type infer_output<schema extends Schema.Any, default_value extends unknown = never> = [default_value] extends [never] ? StandardSchemaV1.InferOutput<schema> : [schema] extends [never] ? default_value : StandardSchemaV1.InferOutput<schema>;
+}
+declare namespace Json {
+  /**
+  Matches a JSON object.
+     @category JSON
+  */
+  type Object = { [Key in string]: Json.Value };
+  /**
+  Matches a JSON array.
+     @category JSON
+  */
+  type Array = Json.Value[] | readonly Json.Value[];
+  /**
+  Matches any valid JSON primitive value.
+     @category JSON
+  */
+  type Primitive = string | number | boolean | null;
+  /**
+  Matches any valid JSON value.
+     @category JSON
+  */
+  type Value = Json.Primitive | Json.Object | Json.Array;
+}
+declare namespace Serializer {
+  type Any = {
+    schema: Schema.Any;
+    serialization?: string | ((data: any) => any);
+  };
+  type Params<pathname extends Pathname.Relative, schema extends Schema._> = schema extends Schema._<any, Pathname.Params<pathname>> ? {
+    schema: schema;
+    serialization?: (data: Schema.infer_output<NoInfer<schema>>) => Pathname.Params<pathname>;
+  } : {
+    schema: schema;
+    serialization: (data: Schema.infer_output<NoInfer<schema>>) => Pathname.Params<pathname>;
+  };
+  type QueryString<schema extends Schema._> = schema extends Schema._<any, Array<Array<string>> | Record<string, string> | undefined> ? {
+    schema: schema;
+    serialization?: "urlencoded" | ((data: Schema.infer_output<NoInfer<schema>>) => URLSearchParams);
+  } : {
+    schema: schema;
+    serialization: (data: Schema.infer_output<NoInfer<schema>>) => URLSearchParams;
+  };
+  type Body<schema extends Schema._> = schema extends Schema._<any, Json.Value> ? {
+    schema: schema;
+    serialization?: "json" | ((data: Schema.infer_output<NoInfer<schema>>) => {
+      body: BodyInit | null;
+      content_type: string;
+    });
+  } : {
+    schema: schema;
+    serialization: (data: Schema.infer_output<NoInfer<schema>>) => {
+      body: BodyInit | null;
+      content_type: string;
+    };
+  };
+}
+declare namespace Parser {
+  type Any = {
+    schema: Schema.Any;
+    deserialization?: string | ((data: any) => any);
+  };
+  type Data<schema extends Schema._> = schema extends Schema._<string, any> ? {
+    schema: schema;
+    deserialization: "text" | "json" | ((body: Response["body"]) => Promise<Schema.infer_input<NoInfer<schema>>>);
+  } : schema extends Schema._<Json.Value, any> ? {
+    schema: schema;
+    deserialization?: "json" | ((body: Response["body"]) => Promise<Schema.infer_input<NoInfer<schema>>>);
+  } : {
+    schema: schema;
+    deserialization: (body: Response["body"]) => Promise<Schema.infer_input<NoInfer<schema>>>;
+  };
+  type Error<schema extends Schema._> = schema extends Schema._<string, any> ? {
+    schema: schema;
+    deserialization: "text" | "json" | ((body: Response["body"]) => Promise<Schema.infer_input<NoInfer<schema>>>);
+  } : schema extends Schema._<Json.Value, any> ? {
+    schema: schema;
+    deserialization: "json" | ((body: Response["body"]) => Promise<Schema.infer_input<NoInfer<schema>>>);
+  } : {
+    schema: schema;
+    deserialization: (body: Response["body"]) => Promise<Schema.infer_input<NoInfer<schema>>>;
+  };
+}
+//#endregion
+export { ErrorMessage, HTTPFetch, HTTPMethod, HTTPStatus, HeadersInitWithReducer, MaybePromise, Parser, Pathname, Pretty, Schema, Serializer };

package/dist/lib/types.mjs

@@ -0,0 +1,4 @@
+import "@standard-schema/spec";
+import "@remix-run/route-pattern";
+
+export {  };

package/dist/lib/utils.mjs

@@ -0,0 +1,69 @@
+//#region src/lib/utils.ts
+function get_entries(source) {
+	if (source instanceof Headers) return source.entries();
+	if (Array.isArray(source)) return source;
+	return Object.entries(source);
+}
+function merge_headers(...sources) {
+	const headers = new Headers();
+	for (const source of sources) {
+		if (!source) continue;
+		for (const [raw_key, value_or_reducer] of get_entries(source)) {
+			const key = raw_key.toLowerCase();
+			if (typeof value_or_reducer === "function") {
+				const new_value = value_or_reducer(headers.get(key) ?? void 0);
+				if (new_value != null) headers.set(key, new_value);
+				else headers.delete(key);
+			} else if (value_or_reducer == null) headers.delete(key);
+			else headers.set(key, value_or_reducer.toString());
+		}
+	}
+	return headers;
+}
+function extract_args(input) {
+	const { params, query, body, ...rest } = input;
+	return {
+		options: rest,
+		args: {
+			params,
+			query,
+			body
+		}
+	};
+}
+function remove_custom_options(options) {
+	const { timeout: _timeout, headers: _headers, signal: _signal, retry: _retry, ...rest } = options;
+	return rest;
+}
+function merge_options(...sources) {
+	return {
+		...sources.reduce((acc, source) => {
+			return {
+				...acc,
+				...source,
+				signal: acc.signal ? source.signal ? AbortSignal.any([acc.signal, source.signal]) : acc.signal : source.signal,
+				retry: {
+					...acc.retry,
+					...source.retry
+				}
+			};
+		}, {}),
+		headers: merge_headers(...sources.map((source) => source.headers))
+	};
+}
+function sleep(ms, signal) {
+	return new Promise((resolve, reject) => {
+		signal?.addEventListener("abort", on_abort, { once: true });
+		const token = setTimeout(() => {
+			signal?.removeEventListener("abort", on_abort);
+			resolve();
+		}, ms);
+		function on_abort() {
+			clearTimeout(token);
+			reject(signal.reason);
+		}
+	});
+}
+
+//#endregion
+export { extract_args, merge_options, remove_custom_options, sleep };

package/docs/endpoint-definition.md

@@ -0,0 +1,128 @@
+# Endpoint Definition
+
+The `Endpoint` class defines an HTTP endpoint with its method, path, serializers, and parsers.
+
+## Constructor
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users/(:id)',
+  // ...options
+})
+```
+
+## Options
+
+### `method` (required)
+
+HTTP method for the endpoint:
+
+```typescript
+type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+```
+
+- `GET` - Cannot have a body schema
+- `POST`, `PUT`, `PATCH`, `DELETE` - Can have a body schema
+
+### `pathname` (required)
+
+URL path with optional dynamic segments:
+
+```typescript
+pathname: '/users'           // Static path
+pathname: '/users/:id'       // Required param
+pathname: '/users/(:id)'     // Optional param
+pathname: '/posts/:id/comments/:commentId'  // Multiple params
+```
+
+### `params`
+
+Serializer for path parameters. See [Serialization](./serialization.md#params).
+
+### `query`
+
+Serializer for query string parameters. See [Serialization](./serialization.md#query).
+
+### `body`
+
+Serializer for request body. See [Serialization](./serialization.md#body).
+
+### `data`
+
+Parser for successful response body. See [Response Parsing](./response-parsing.md#data).
+
+### `error`
+
+Parser for error response body. See [Response Parsing](./response-parsing.md#error).
+
+## Constructor
+
+The `Endpoint` constructor takes a definition and optional default options:
+
+```typescript
+const endpoint = new Endpoint({
+  method: 'GET',
+  pathname: '/users',
+  // Definition: method, pathname, params, query, body, data, error
+}, {
+  headers: {
+    'X-API-Version': '2',
+  },
+  timeout: 5000,
+  retry: {
+    attempts: 3,
+    delay: 1000,
+    when: ({ response }) => response?.status === 503,
+  },
+})
+```
+
+The second argument accepts:
+- `headers`: Default headers for all requests
+- `timeout`: Request timeout in milliseconds
+- `retry`: Default retry policy
+
+These can be overridden per-request.
+
+See [Retry Policy](./retry-policy.md) for retry configuration.
+
+## Low-level Methods
+
+Most users should use `http_client` instead of calling these methods directly. The HTTP client handles URL generation, body serialization, and response parsing automatically.
+
+### `generate_url(init)`
+
+Generates a full URL with params and query serialized:
+
+```typescript
+const url = await endpoint.generate_url({
+  origin: 'https://api.example.com',
+  params: { id: '123' },
+  query: { include: 'posts' },
+})
+```
+
+Returns `URL` on success or `SerializationError` on validation failure.
+
+### `serialize_body(init)`
+
+Serializes the request body:
+
+```typescript
+const { body, content_type } = await endpoint.serialize_body({
+  body: { name: 'John' },
+})
+```
+
+Returns `{ body, content_type }` on success or `SerializationError` on validation failure.
+
+### `parse_response(response)`
+
+Parses an HTTP response:
+
+```typescript
+const result = await endpoint.parse_response(response)
+```
+
+Returns typed result based on status code. See [Response Parsing](./response-parsing.md).

package/docs/error-handling.md

@@ -0,0 +1,148 @@
+# Error Handling
+
+The HTTP client provides typed errors for different failure scenarios.
+
+## Error Types
+
+### `HttpClientError`
+
+Base class for all HTTP client errors:
+
+```typescript
+if (error instanceof HttpClientError) {
+  console.log(error.name)    // "HttpClientError"
+  console.log(error.message) // Error message
+  console.log(error.context) // { operation: string }
+}
+```
+
+### `TimeoutError`
+
+Request exceeded the timeout:
+
+```typescript
+const result = await api.users.get({ params: { id: '123' }, timeout: 1000 })
+
+if (result instanceof TimeoutError) {
+  console.log(result.kind) // "TimeoutError"
+  console.log(result.context.operation) // "fetch"
+}
+```
+
+### `AbortedError`
+
+Request was aborted via `AbortSignal`:
+
+```typescript
+const controller = new AbortController()
+const result = await api.users.get({
+  params: { id: '123' },
+  signal: controller.signal,
+})
+
+if (result instanceof AbortedError) {
+  console.log(result.kind) // "AbortedError"
+}
+```
+
+### `NetworkError`
+
+Network-level failure (no response received):
+
+```typescript
+const result = await api.users.get({ params: { id: '123' } })
+
+if (result instanceof NetworkError) {
+  console.log(result.kind) // "NetworkError"
+  console.log(result.cause) // Underlying error
+}
+```
+
+### `SerializationError`
+
+Failed to serialize params, query, or body:
+
+```typescript
+const result = await api.users.create({
+  body: { name: '' }, // Fails validation
+})
+
+if (result instanceof SerializationError) {
+  console.log(result.kind) // "SerializationError"
+  console.log(result.context.operation) // "serialize_body" | "generate_url"
+  console.log(result.cause) // Schema validation issues
+}
+```
+
+### `DeserializationError`
+
+Failed to parse response:
+
+```typescript
+const result = await api.users.get({ params: { id: '123' } })
+
+if (result instanceof DeserializationError) {
+  console.log(result.kind) // "DeserializationError"
+  console.log(result.cause) // Schema validation issues
+}
+```
+
+### `UnexpectedError`
+
+Unexpected failure during request:
+
+```typescript
+const result = await api.users.get({ params: { id: '123' } })
+
+if (result instanceof UnexpectedError) {
+  console.log(result.name) // "UnexpectedError"
+  console.log(result.context.operation) // "create_request" | "parse_response" | etc.
+}
+```
+
+## Checking Results
+
+### Instance Check
+
+```typescript
+const result = await api.users.get({ params: { id: '123' } })
+
+if (result instanceof Error) {
+  // Handle all error types
+  if (result instanceof TimeoutError) {
+    // Retry or show timeout message
+  } else if (result instanceof NetworkError) {
+    // Show network error, maybe retry
+  }
+  return
+}
+
+// Handle successful response
+if (result.ok) {
+  console.log(result.data)
+}
+```
+
+## Error Context
+
+All errors have a `context` property with the operation that failed:
+
+```typescript
+if (result instanceof HttpClientError) {
+  result.context.operation
+  // "fetch" | "generate_url" | "serialize_body" | "parse_response" | "create_request" | "retry_policy" | "..."
+}
+```
+
+## Raw Response
+
+When available, the raw `Response` object is accessible:
+
+```typescript
+const result = await api.users.get({ params: { id: '123' } })
+
+if (!result.ok && !(result instanceof Error)) {
+  console.log(result.raw_response.status)
+  console.log(result.raw_response.headers)
+}
+```