@zap-studio/fetch 0.4.6 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @zap-studio/fetch
 
+## 0.5.0
+
+### Breaking
+
+- Request bodies are no longer auto-serialized from plain objects; use the explicit `json` option (or set `body` yourself). `body` and `json` are mutually exclusive at the type level and enforced at runtime.
+
+### Changed
+
+- Simplified the request API around web platform types.
+  - The first argument is named `input` and typed as `FetchInput` (`Parameters<typeof fetch>[0]` from `lib.dom`), exported from `@zap-studio/fetch/types`, so allowed inputs track global `fetch` when DOM typings change.
+  - Non-`Request` values (including `URL`) are normalized to a string URL before query merge.
+  - `ExtendedRequestInit` now extends native `RequestInit` directly instead of redefining request options.
+  - `searchParams` now accepts the same input shape as `new URLSearchParams(...)`.
+- Replaced automatic object body serialization with an explicit `json` option.
+  - Use `json: value` when you want JSON stringification and `Content-Type: application/json`.
+  - Use native `body` when you want standard `fetch` behavior.
+  - `body` and `json` are mutually exclusive in TypeScript and guarded at runtime.
+- Reworked URL handling to use the platform `URL` and `URLSearchParams` APIs while preserving relative URL output when no `baseURL` is configured.
+- Simplified the internal module structure and removed the old `utils` module.
+
+### Fixed
+
+- Fixed absolute URL handling when no `baseURL` is configured.
+- `resolveSearchParams` keeps a trailing `#` when the input URL had an empty fragment (for example `.../path#`), matching typical `URL` serialization instead of dropping the delimiter.
+
+### Tests
+
+- Reworked tests to mirror the `src` module structure.
+- Added full package coverage across statements, branches, functions, and lines.
+
+### Documentation
+
+- Documented the throwable error surface for `$fetch`, `createFetch`, and internal request execution with explicit `@throws` tags (for example `FetchError`, `ValidationError`, `TypeError`, `DOMException`, `SyntaxError`, and validator-thrown errors).
+
+### Dependencies
+
+- JSR dependency mapping now pins `@zap-studio/validation` to `0.3.2`.
+
+## 0.4.7
+
+### Patch Changes
+
+- e26293e: Updated dependencies.
+  - @zap-studio/validation@0.3.2
+
 ## 0.4.6
 
 ### Patch Changes
@@ -7,7 +52,6 @@
 - 5ea3d3b: Updated dependencies.
   - @zap-studio/validation@0.3.1
 
-
 ## 0.4.5
 
 ### Dependencies

package/{LICENSE.md → LICENSE}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Alexandre Trotel
+Copyright (c) 2026 Alexandre Trotel
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,57 +1,301 @@
 # @zap-studio/fetch
 
-A type-safe fetch wrapper with Standard Schema validation.
+A small fetch wrapper with [**Standard Schema**](https://standardschema.dev/schema) response validation.
 
-## Why @zap-studio/fetch?
+## Installation
+
+```bash
+npm install @zap-studio/fetch
+```
+
+## Quick Example
+
+```ts
+import { api } from "@zap-studio/fetch";
+import { z } from "zod";
+
+const UserSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const user = await api.get("https://api.example.com/users/1", UserSchema);
+
+console.log(user.name);
+```
+
+## Before
 
-**Before:**
+Without response validation, fetch code often needs unchecked assertions:
+
+```ts
+type User = {
+  id: number;
+  name: string;
+};
 
-```typescript
 const response = await fetch("/api/users/1");
 const data = await response.json();
-const user = data as User; // 😱 Unsafe type assertion
+
+const user = data as User;
 ```
 
-**After:**
+## After
+
+With `@zap-studio/fetch`, the response is validated before it is returned:
+
+```ts
+import { api } from "@zap-studio/fetch";
 
-```typescript
 const user = await api.get("/api/users/1", UserSchema);
-// ✨ Typed, validated, and safe!
 ```
 
-## Features
+The returned value is inferred from the schema.
 
-- 🎯 **Type-safe requests** with automatic type inference
-- 🛡️ **Runtime validation** using Standard Schema (Zod, Valibot, ArkType, etc.)
-- ⚡️ **Convenient API methods** (GET, POST, PUT, PATCH, DELETE)
-- 🏭 **Factory pattern** for creating pre-configured instances with base URLs
-- 🚨 **Custom error handling** with FetchError and ValidationError classes
-- 📘 **Full TypeScript support** with zero configuration
+## Raw Fetch Usage
 
-## Installation
+Use `$fetch` without a schema when you want the normal `Response` object.
 
-```bash
-pnpm add @zap-studio/fetch
-# or
-npm install @zap-studio/fetch
+```ts
+import { $fetch } from "@zap-studio/fetch";
+
+const response = await $fetch("/api/users/1");
+const user = await response.json();
 ```
 
-## Quick Start
+Native fetch options are passed through as `RequestInit`.
 
-```typescript
-import { z } from "zod";
+```ts
+const response = await $fetch("/api/users", {
+  method: "POST",
+  body: JSON.stringify({ name: "Ada" }),
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
+```
+
+## Validated Fetch Usage
+
+Pass a Standard Schema as the second argument to validate the JSON response.
+
+```ts
+import { $fetch } from "@zap-studio/fetch";
+
+const user = await $fetch("/api/users/1", UserSchema);
+```
+
+The schema validates the response body, not the request body.
+
+When validation fails, a `ValidationError` is thrown by default.
+
+## API Method Helpers
+
+The `api` export provides common HTTP methods.
+
+```ts
 import { api } from "@zap-studio/fetch";
 
-// Define your schema
-const UserSchema = z.object({
-  id: z.number(),
-  name: z.string(),
-  email: z.email(),
+const user = await api.get("/api/users/1", UserSchema);
+
+const created = await api.post("/api/users", UserSchema, {
+  json: {
+    name: "Ada",
+    email: "ada@example.com",
+  },
 });
+```
 
-// Make a type-safe request
-const user = await api.get("https://api.example.com/users/1", UserSchema);
+In this example, `UserSchema` validates the response from `/api/users`.
+The `json` value is the outgoing request body and is not validated by `UserSchema`.
+
+These helpers set the HTTP method for you. For raw responses without validation, use `$fetch`.
+
+## JSON Request Bodies
+
+Use `json` when you want the package to serialize a JSON request body.
+
+```ts
+await api.post("/api/users", UserSchema, {
+  json: {
+    name: "Ada",
+  },
+});
+```
+
+The schema argument still validates the response. Validate request bodies separately before
+passing them to `json` if your application needs outgoing payload validation.
+
+This sets:
+
+- `body` to `JSON.stringify(json)`
+- `Content-Type` to `application/json` when no content type was already provided
+
+Use native `body` for standard fetch behavior.
+
+```ts
+await $fetch("/api/upload", {
+  method: "POST",
+  body: formData,
+});
+```
+
+`body` and `json` are mutually exclusive.
+
+## Query Params
+
+Use `searchParams` for per-request query params.
+
+```ts
+await api.get("/api/users", UserListSchema, {
+  searchParams: {
+    page: "1",
+    limit: "20",
+  },
+});
+```
+
+`searchParams` accepts the same input shapes as `new URLSearchParams(...)`.
+
+```ts
+await api.get("/api/users", UserListSchema, {
+  searchParams: new URLSearchParams({ q: "ada" }),
+});
+
+await api.get("/api/users", UserListSchema, {
+  searchParams: "q=ada&page=1",
+});
+
+await api.get("/api/users", UserListSchema, {
+  searchParams: [["q", "ada"]],
+});
+```
+
+When defaults, URL query params, and request params overlap, later values win:
+
+1. `createFetch({ searchParams })`
+2. query params already present in the URL
+3. per-request `searchParams`
+
+## Creating a Client
+
+Use `createFetch` to configure shared defaults.
+
+```ts
+import { createFetch } from "@zap-studio/fetch";
+
+const { $fetch, api } = createFetch({
+  baseURL: "https://api.example.com",
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+  searchParams: {
+    locale: "en",
+  },
+});
 
-// user is fully typed and validated! ✨
-console.log(user.name); // TypeScript knows this is a string
+const user = await api.get("/users/1", UserSchema);
+const response = await $fetch("/health");
 ```
+
+Supported defaults:
+
+| Option                   | Description                                     |
+| ------------------------ | ----------------------------------------------- |
+| `baseURL`                | Base URL for relative request URLs              |
+| `headers`                | Headers applied to every request                |
+| `searchParams`           | Query params applied to every request           |
+| `throwOnFetchError`      | Throw `FetchError` for non-ok responses         |
+| `throwOnValidationError` | Throw `ValidationError` for validation failures |
+
+## Non-throwing Validation
+
+Set `throwOnValidationError: false` to receive the raw Standard Schema result.
+
+```ts
+const result = await api.get("/api/users/1", UserSchema, {
+  throwOnValidationError: false,
+});
+
+if (result.issues) {
+  console.error("Validation failed:", result.issues);
+} else {
+  console.log("Validation passed:", result.value);
+}
+```
+
+## HTTP Errors
+
+By default, non-ok responses throw a `FetchError`.
+
+```ts
+import { FetchError } from "@zap-studio/fetch/errors";
+
+try {
+  await api.get("/api/users/404", UserSchema);
+} catch (error) {
+  if (error instanceof FetchError) {
+    console.error(error.status);
+    console.error(error.response);
+  }
+}
+```
+
+Disable this behavior when you want to handle the raw response yourself.
+
+```ts
+const response = await $fetch("/api/users/404", {
+  throwOnFetchError: false,
+});
+
+console.log(response.status);
+```
+
+## Request Objects
+
+The first argument (`input`) uses the same type as global `fetch`.
+
+```ts
+const request = new Request("https://api.example.com/users/1", {
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+});
+
+const user = await $fetch(request, UserSchema);
+```
+
+Per-request options are merged on top of the `Request`.
+
+## Standard Schema
+
+`@zap-studio/fetch` validates responses through `@zap-studio/validation`, so it works with any validation library that implements Standard Schema.
+
+Examples include:
+
+- [Zod](https://zod.dev/)
+- [Valibot](https://valibot.dev/)
+- [ArkType](https://arktype.io/)
+
+You can also import Standard Schema types from `@zap-studio/validation` when needed.
+
+```ts
+import type { StandardSchemaV1 } from "@zap-studio/validation";
+```
+
+## Choosing the Right API
+
+| API           | Use when                                          |
+| ------------- | ------------------------------------------------- |
+| `$fetch`      | You want raw fetch behavior or a custom method    |
+| `api.get`     | You want a validated GET request                  |
+| `api.post`    | You want a validated POST request                 |
+| `api.put`     | You want a validated PUT request                  |
+| `api.patch`   | You want a validated PATCH request                |
+| `api.delete`  | You want a validated DELETE request               |
+| `createFetch` | You want shared defaults like base URL or headers |
+
+## License
+
+MIT

package/dist/constants.d.mts

@@ -1,9 +1,16 @@
 import { FetchDefaults } from "./types.mjs";
 
 //#region src/constants.d.ts
-
 /**
 * Default options for the global $fetch
+*
+* These defaults are used by the top-level `$fetch` export.
+* Use `createFetch(...)` when you need per-client defaults.
+*
+* @example
+* import { GLOBAL_DEFAULTS } from "@zap-studio/fetch/constants";
+*
+* console.log(GLOBAL_DEFAULTS.throwOnFetchError); // true
 */
 declare const GLOBAL_DEFAULTS: FetchDefaults;
 //#endregion

package/dist/constants.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.mts","names":["GLOBAL_DEFAULTS: FetchDefaults"],"sources":["../src/constants.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;cAAaA,iBAAiB"}
+{"version":3,"file":"constants.d.mts","names":[],"sources":["../src/constants.ts"],"mappings":";;;;;;;;;;;;;;cAmBa,eAAA,EAAiB,aAAA"}

package/dist/constants.mjs

@@ -1,14 +1,21 @@
 //#region src/constants.ts
 /**
 * Default options for the global $fetch
+*
+* These defaults are used by the top-level `$fetch` export.
+* Use `createFetch(...)` when you need per-client defaults.
+*
+* @example
+* import { GLOBAL_DEFAULTS } from "@zap-studio/fetch/constants";
+*
+* console.log(GLOBAL_DEFAULTS.throwOnFetchError); // true
 */
 const GLOBAL_DEFAULTS = {
 	baseURL: "",
-	headers: void 0,
 	throwOnFetchError: true,
 	throwOnValidationError: true
 };
-
 //#endregion
 export { GLOBAL_DEFAULTS };
+
 //# sourceMappingURL=constants.mjs.map

package/dist/constants.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"constants.mjs","names":["GLOBAL_DEFAULTS: FetchDefaults"],"sources":["../src/constants.ts"],"sourcesContent":["import type { FetchDefaults } from \"./types\";\n\n/**\n * Default options for the global $fetch\n */\nexport const GLOBAL_DEFAULTS: FetchDefaults = {\n  baseURL: \"\",\n  headers: undefined,\n  throwOnFetchError: true,\n  throwOnValidationError: true,\n};\n"],"mappings":";;;;AAKA,MAAaA,kBAAiC;CAC5C,SAAS;CACT,SAAS;CACT,mBAAmB;CACnB,wBAAwB;CACzB"}
+{"version":3,"file":"constants.mjs","names":[],"sources":["../src/constants.ts"],"sourcesContent":["/**\n * Shared defaults and constants for fetch behavior.\n *\n * @module\n */\n\nimport type { FetchDefaults } from \"./types.js\";\n\n/**\n * Default options for the global $fetch\n *\n * These defaults are used by the top-level `$fetch` export.\n * Use `createFetch(...)` when you need per-client defaults.\n *\n * @example\n * import { GLOBAL_DEFAULTS } from \"@zap-studio/fetch/constants\";\n *\n * console.log(GLOBAL_DEFAULTS.throwOnFetchError); // true\n */\nexport const GLOBAL_DEFAULTS: FetchDefaults = {\n  baseURL: \"\",\n  throwOnFetchError: true,\n  throwOnValidationError: true,\n};\n"],"mappings":";;;;;;;;;;;;AAmBA,MAAa,kBAAiC;CAC5C,SAAS;CACT,mBAAmB;CACnB,wBAAwB;CACzB"}

package/dist/errors.d.mts

@@ -1,10 +1,39 @@
 //#region src/errors.d.ts
 /**
+* Custom error types used by the fetch package.
+*
+* @module
+*/
+/**
 * Error thrown for HTTP errors (non-2xx responses)
+*
+* Includes the failing `Response` object and status code for
+* downstream error handling and response inspection.
+*
+* @example
+* import { FetchError } from "@zap-studio/fetch/errors";
+*
+* try {
+*   await $fetch("/users/404");
+* } catch (error) {
+*   if (error instanceof FetchError) {
+*     console.error(error.status);
+*     console.error(await error.response.text());
+*   }
+* }
 */
 declare class FetchError extends Error {
+  /**
+  * HTTP status code from the failing response.
+  */
   status: Response["status"];
+  /**
+  * Full response object for additional inspection.
+  */
   response: Response;
+  /**
+  * Creates a FetchError from a non-ok response.
+  */
   constructor(message: string, response: Response);
 }
 //#endregion

package/dist/errors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.mts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;AAGA;;AAEY,cAFC,UAAA,SAAmB,KAAA,CAEpB;EAE6B,MAAA,EAH/B,QAG+B,CAAA,QAAA,CAAA;EAJT,QAAA,EAEpB,QAFoB;EAAA,WAAA,CAAA,OAAA,EAAA,MAAA,EAAA,QAAA,EAIS,QAJT"}
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../src/errors.ts"],"mappings":";;AAwBA;;;;;;;;;;;;;;;;;;;;;;cAAa,UAAA,SAAmB,KAAA;;;;EAI9B,MAAA,EAAQ,QAAA;;;;EAIR,QAAA,EAAU,QAAA;;;;EAKV,WAAA,CAAY,OAAA,UAAiB,QAAA,EAAU,QAAA;AAAA"}

package/dist/errors.mjs

@@ -1,3 +1,47 @@
-import { t as FetchError } from "./errors-DQfwnwmz.mjs";
+//#region src/errors.ts
+/**
+* Custom error types used by the fetch package.
+*
+* @module
+*/
+/**
+* Error thrown for HTTP errors (non-2xx responses)
+*
+* Includes the failing `Response` object and status code for
+* downstream error handling and response inspection.
+*
+* @example
+* import { FetchError } from "@zap-studio/fetch/errors";
+*
+* try {
+*   await $fetch("/users/404");
+* } catch (error) {
+*   if (error instanceof FetchError) {
+*     console.error(error.status);
+*     console.error(await error.response.text());
+*   }
+* }
+*/
+var FetchError = class extends Error {
+	/**
+	* HTTP status code from the failing response.
+	*/
+	status;
+	/**
+	* Full response object for additional inspection.
+	*/
+	response;
+	/**
+	* Creates a FetchError from a non-ok response.
+	*/
+	constructor(message, response) {
+		super(message);
+		this.name = "FetchError";
+		this.status = response.status;
+		this.response = response;
+	}
+};
+//#endregion
+export { FetchError };
 
-export { FetchError };
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Custom error types used by the fetch package.\n *\n * @module\n */\n\n/**\n * Error thrown for HTTP errors (non-2xx responses)\n *\n * Includes the failing `Response` object and status code for\n * downstream error handling and response inspection.\n *\n * @example\n * import { FetchError } from \"@zap-studio/fetch/errors\";\n *\n * try {\n *   await $fetch(\"/users/404\");\n * } catch (error) {\n *   if (error instanceof FetchError) {\n *     console.error(error.status);\n *     console.error(await error.response.text());\n *   }\n * }\n */\nexport class FetchError extends Error {\n  /**\n   * HTTP status code from the failing response.\n   */\n  status: Response[\"status\"];\n  /**\n   * Full response object for additional inspection.\n   */\n  response: Response;\n\n  /**\n   * Creates a FetchError from a non-ok response.\n   */\n  constructor(message: string, response: Response) {\n    super(message);\n    this.name = \"FetchError\";\n    this.status = response.status;\n    this.response = response;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAwBA,IAAa,aAAb,cAAgC,MAAM;;;;CAIpC;;;;CAIA;;;;CAKA,YAAY,SAAiB,UAAoB;AAC/C,QAAM,QAAQ;AACd,OAAK,OAAO;AACZ,OAAK,SAAS,SAAS;AACvB,OAAK,WAAW"}

package/dist/headers.d.mts

@@ -0,0 +1,26 @@
+//#region src/headers.d.ts
+/**
+* Header utility helpers for request normalization and merging.
+*
+* @module
+*/
+/**
+* Merges two HeadersInit objects, with the second one taking precedence.
+*
+* @param base - Base/default headers.
+* @param override - Request-level override headers.
+* @returns A merged `Headers` object, or `undefined` when both inputs are empty.
+* @throws {TypeError} When either header input contains invalid header names or values.
+*
+* @example
+* const headers = mergeHeaders(
+*   { Authorization: "Bearer token" },
+*   { "X-Trace-Id": "abc" },
+* );
+*
+* console.log(headers?.get("Authorization")); // Bearer token
+*/
+declare function mergeHeaders(base?: HeadersInit, override?: HeadersInit): Headers | undefined;
+//#endregion
+export { mergeHeaders };
+//# sourceMappingURL=headers.d.mts.map

package/dist/headers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.d.mts","names":[],"sources":["../src/headers.ts"],"mappings":";;AAsBA;;;;;;;;;;;;;;;;;;;;iBAAgB,YAAA,CAAa,IAAA,GAAO,WAAA,EAAa,QAAA,GAAW,WAAA,GAAc,OAAA"}

package/dist/headers.mjs

@@ -0,0 +1,35 @@
+//#region src/headers.ts
+/**
+* Header utility helpers for request normalization and merging.
+*
+* @module
+*/
+/**
+* Merges two HeadersInit objects, with the second one taking precedence.
+*
+* @param base - Base/default headers.
+* @param override - Request-level override headers.
+* @returns A merged `Headers` object, or `undefined` when both inputs are empty.
+* @throws {TypeError} When either header input contains invalid header names or values.
+*
+* @example
+* const headers = mergeHeaders(
+*   { Authorization: "Bearer token" },
+*   { "X-Trace-Id": "abc" },
+* );
+*
+* console.log(headers?.get("Authorization")); // Bearer token
+*/
+function mergeHeaders(base, override) {
+	if (!(base || override)) return;
+	const merged = new Headers(base);
+	if (override) {
+		const overrideHeaders = new Headers(override);
+		for (const [key, value] of overrideHeaders.entries()) merged.set(key, value);
+	}
+	return merged;
+}
+//#endregion
+export { mergeHeaders };
+
+//# sourceMappingURL=headers.mjs.map

package/dist/headers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.mjs","names":[],"sources":["../src/headers.ts"],"sourcesContent":["/**\n * Header utility helpers for request normalization and merging.\n *\n * @module\n */\n\n/**\n * Merges two HeadersInit objects, with the second one taking precedence.\n *\n * @param base - Base/default headers.\n * @param override - Request-level override headers.\n * @returns A merged `Headers` object, or `undefined` when both inputs are empty.\n * @throws {TypeError} When either header input contains invalid header names or values.\n *\n * @example\n * const headers = mergeHeaders(\n *   { Authorization: \"Bearer token\" },\n *   { \"X-Trace-Id\": \"abc\" },\n * );\n *\n * console.log(headers?.get(\"Authorization\")); // Bearer token\n */\nexport function mergeHeaders(base?: HeadersInit, override?: HeadersInit): Headers | undefined {\n  if (!(base || override)) {\n    return;\n  }\n\n  const merged = new Headers(base);\n  if (override) {\n    const overrideHeaders = new Headers(override);\n    for (const [key, value] of overrideHeaders.entries()) {\n      merged.set(key, value);\n    }\n  }\n  return merged;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,aAAa,MAAoB,UAA6C;AAC5F,KAAI,EAAE,QAAQ,UACZ;CAGF,MAAM,SAAS,IAAI,QAAQ,KAAK;AAChC,KAAI,UAAU;EACZ,MAAM,kBAAkB,IAAI,QAAQ,SAAS;AAC7C,OAAK,MAAM,CAAC,KAAK,UAAU,gBAAgB,SAAS,CAClD,QAAO,IAAI,KAAK,MAAM;;AAG1B,QAAO"}