http

@resq-sw/http

Effect-based HTTP client with retry, timeout, schema validation, and security middleware.

Installation

bun add @resq-sw/http effect

Peer dependency: effect.

Quick Start

import { get, post } from "@resq-sw/http";
import { Effect } from "effect";
import { HttpClient } from "effect/unstable/http";

const program = Effect.gen(function* () {
  const users = yield* get<User[]>("/api/users");
  const created = yield* post<User>("/api/users", { name: "Alice" });
  return { users, created };
});

// Run with the default HTTP client
Effect.runPromise(program.pipe(Effect.provide(HttpClient.layer)));

API Reference

fetcher(url, method?, options?, params?, body?)

Core HTTP function. All convenience methods delegate to this.

Parameter	Type	Default	Description
url	string	required	URL path or absolute URL
method	HttpMethod	"GET"	HTTP method
options	FetcherOptions<T>	{}	Request options
params	QueryParams	--	Query parameters
body	RequestBody	--	Request body (POST/PUT/PATCH only)

Returns Effect.Effect<T, FetcherError | FetcherValidationError, HttpClient.HttpClient>.

URL resolution: absolute URLs are used as-is; relative paths are prefixed with VITE_SITE_URL, SITE_URL, or http://localhost:5173.

FetcherOptions

Option	Type	Default	Description
retries	number	0	Retry count on failure
retryDelay	number	1000	Base delay between retries (exponential backoff)
timeout	number	10000	Request timeout in ms
headers	Record<string, string>	{}	Additional request headers
schema	Schema.Schema<T>	--	Effect Schema for response validation
onError	(error: unknown) => void	--	Error callback
signal	AbortSignal	--	Abort signal
bodyType	"json" | "text" | "form"	"json"	Request body encoding

Retry Behavior

• Uses exponential backoff starting from retryDelay.
• Always retries: 429 (rate limit), 5xx, network errors, timeouts.
• Never retries: validation errors, 4xx (except 429).

Convenience Methods

All return Effect.Effect<T, FetcherError | FetcherValidationError, HttpClient.HttpClient>.

Function	Signature
get	(url, options?, params?) => Effect
post	(url, body?, options?, params?) => Effect
put	(url, body?, options?, params?) => Effect
patch	(url, body?, options?, params?) => Effect
del	(url, options?, params?) => Effect
options	(url, options?, params?) => Effect
head	(url, options?, params?) => Effect

All methods support schema overloads for compile-time type safety:

import { Schema } from "effect";

const UserSchema = Schema.Struct({ id: Schema.Number, name: Schema.String });

const user = get("/api/users/1", { schema: UserSchema });
// Type: Effect<{ id: number; name: string }, ...>

Schema Helpers

createPaginatedSchema(itemSchema)

Creates a schema for paginated API responses.

const PagedUsers = createPaginatedSchema(UserSchema);
// { data: User[], pagination: { page, pageSize, total, totalPages } }

createApiResponseSchema(dataSchema)

Creates a schema for standard API responses.

const ApiUser = createApiResponseSchema(UserSchema);
// { success: boolean, data: User, message?: string, errors?: string[] }

Error Types

FetcherError

Thrown on network errors, timeouts, and non-2xx responses.

Property	Type	Description
message	string	Error description
url	string	Request URL
status	number?	HTTP status code
responseData	unknown?	Response body if available
attempt	number?	Retry attempt number

FetcherValidationError

Thrown when response data fails schema validation.

Property	Type	Description
message	string	Error description
url	string	Request URL
problems	string	Schema validation errors
responseData	unknown	Raw response data
attempt	number?	Retry attempt number

Security Utilities

shouldRedirectToHttps(protocol, url, headers, nodeEnv?): string | null

Checks if a request should be redirected to HTTPS. Handles proxy headers (x-forwarded-proto, x-forwarded-ssl). Returns the HTTPS URL or null.

• Skipped in development and test environments.

const redirect = shouldRedirectToHttps("http", req.url, req.headers);
if (redirect) return Response.redirect(redirect, 301);

getRequestId(existingId?): string

Returns the existing request ID or generates a new UUID.

const reqId = getRequestId(headers["x-request-id"]);

License

Apache-2.0