@zap-studio/fetch 0.5.6 → 1.1.0

package/CHANGELOG.md

@@ -1,44 +1,67 @@
-## @zap-studio/fetch@0.5.6
+# Changelog
 
-### Tree-shakeable root re-exports
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0]
+
+### Added
+
+`createFetch(...)` gains an optional `logger?: Logger` option (from `@zap-studio/logger`). When provided, it logs outgoing requests at `debug`, response status at `debug` (2xx) or `warn` (non-2xx), and schema validation failures at `error`. Omitting it keeps zero logging overhead. See [Logging](https://www.zapstudio.dev/fetch/logging).
+
+## [1.0.0]
+
+### Changed
+
+- Clarified tree-shakeable design in the package description and README (no code change).
+
+### Removed
+
+Collapsed the internal request pipeline (`_internal.ts`, `_methods.ts`, `constants.ts`, `headers.ts`, `request.ts`, `url.ts`) into implementation-only files. `mergeHeaders`, `normalizeRequest`, and `resolveRequestUrl` are no longer public API — they were pipeline internals, not meant for standalone use.
+
+- Removed the `./constants`, `./headers`, `./request`, `./url`, and `./fetch` subpath exports. Use the root `@zap-studio/fetch` entry instead.
+- `GLOBAL_DEFAULTS`, `FetchError`, `$fetch`, `api`, `createFetch`, and all public types are unaffected and still exported from `.`; `./errors` and `./types` subpaths are unaffected.
+
+## [0.5.6]
+
+### Added
 
 The package root now re-exports the full public API, so everything can be imported from `@zap-studio/fetch` directly (`$fetch`, `api`, `createFetch`, `FetchError`, `mergeHeaders`, `GLOBAL_DEFAULTS`, `normalizeRequest`, `resolveRequestUrl`, and all public types). All exports are side-effect free and tree-shakeable; granular subpath imports keep working.
 
 - The `$fetch`/`api`/`createFetch` implementation moved from the entrypoint into its own module, available as the new `./fetch` subpath.
+
+### Removed
+
 - Removed the `./internal` and `./methods` subpath exports. Both were implementation details (`fetchInternal`, `createMethod`) and are no longer part of the public API.
 
-## @zap-studio/fetch@0.5.5
+## [0.5.5]
 
-### Migrate to ultracite lint/format
+### Changed
 
 Internal formatting and lint cleanup only. No public API or behavior change.
 
-# @zap-studio/fetch
-
-## 0.5.4
+## [0.5.4]
 
 ### Changed
 
 - Added fetch ecosystem benchmarks and grouped benchmark output for easier cross-library comparisons.
 - Applied small internal performance optimizations in request preparation, URL resolution, and header merging without changing public API behavior.
 
-## 0.5.3
+## [0.5.3]
 
 ### Changed
 
 - Refactor `createFetch(...)` to derive fallback defaults from `GLOBAL_DEFAULTS` instead of re-defining primitive defaults inline.
 
-## 0.5.2
+## [0.5.2]
 
 ### Changed
 
 - Expand TSDoc coverage across fetch modules and exported contracts for stronger JSR documentation completeness.
-
-### Dependencies
-
 - Updated dependency `@zap-studio/validation` to `0.3.4`.
 
-## 0.5.1
+## [0.5.1]
 
 ### Fixed
 
@@ -47,19 +70,18 @@ Internal formatting and lint cleanup only. No public API or behavior change.
 ### Changed
 
 - 2ea1a70: Cleaned up public option typings by removing redundant `| undefined` unions from fetch configuration types and overloads.
-
-### Dependencies
-
 - Updated dependency `@zap-studio/validation` to `0.3.3`.
 
-## 0.5.0
+## [0.5.0]
 
-### Breaking
+### Added
 
-- 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.
+- 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).
+- Added full package test coverage across statements, branches, functions, and lines.
 
 ### Changed
 
+- **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.
 - 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.
@@ -71,46 +93,35 @@ Internal formatting and lint cleanup only. No public API or behavior change.
   - `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.
+- Reworked tests to mirror the `src` module structure.
+- JSR dependency mapping now pins `@zap-studio/validation` to `0.3.2`.
 
 ### 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
+## [0.4.7]
 
-- JSR dependency mapping now pins `@zap-studio/validation` to `0.3.2`.
-
-## 0.4.7
-
-### Patch Changes
+### Changed
 
 - e26293e: Updated dependencies.
   - @zap-studio/validation@0.3.2
 
-## 0.4.6
+## [0.4.6]
 
-### Patch Changes
+### Changed
 
 - 5ea3d3b: Updated dependencies.
   - @zap-studio/validation@0.3.1
 
-## 0.4.5
+## [0.4.5]
 
-### Dependencies
+### Changed
 
 - f75b984: Updated dependency `@zap-studio/validation` to `0.3.0`.
 
-## 0.4.4
+## [0.4.4]
 
 ### Fixed
 
@@ -119,39 +130,33 @@ Internal formatting and lint cleanup only. No public API or behavior change.
   - Auto-stringify plain JSON body values even when no response schema is provided.
   - Set `Content-Type: application/json` only when auto-stringifying and no explicit content type is set.
 
-## 0.4.3
+## [0.4.3]
 
 ### Changed
 
 - e4542bb: Refined `standardValidate` typings so return types depend on `throwOnError`, and updated `@zap-studio/fetch` integration while preserving the existing boolean configuration API.
-
-### Dependencies
-
 - e4542bb: Updated dependency `@zap-studio/validation` to `0.2.1`.
 
-## 0.4.2
+## [0.4.2]
 
-### Dependencies
+### Changed
 
 - 2de8183: Updated dependency `@zap-studio/validation` to `0.2.0`.
 
-## 0.4.1
+## [0.4.1]
 
 ### Changed
 
 - 447dbda: Switched shared Standard Schema validation utilities to `@zap-studio/validation`.
-
-### Dependencies
-
 - 447dbda: Updated dependency `@zap-studio/validation` to `0.1.0`.
 
-## 0.4.0
+## [0.4.0]
 
 ### Added
 
 - 69057cd: Exposed fetch defaults constants and utility helpers as public exports.
 
-## 0.3.1
+## [0.3.1]
 
 ### Changed
 
@@ -160,31 +165,26 @@ Internal formatting and lint cleanup only. No public API or behavior change.
   - `throwOnValidationError: false` returns `Promise<StandardSchemaV1.Result<TSchema>>`.
   - This improves type safety and removes manual narrowing in default usage.
 
-## 0.3.0
+## [0.3.0]
 
 ### Added
 
 - 659621c: Added `searchParams` support in `createFetch` for factory-level default query parameters.
   - Per-request `searchParams` still override factory defaults.
 
-## 0.2.2
+## [0.2.2]
 
 ### Changed
 
 - 5c3abbf: Prepared JSR publish and `isolatedDeclarations` support with explicit `$Fetch` and `ApiMethods` types.
 
-## 0.2.1
+## [0.2.1]
 
 ### Changed
 
 - 82bac5c: Replaced regex-based slash trimming with more efficient string manipulation for URL normalization.
 
-## 0.2.0
-
-### Changed
-
-- 78afb76: Migrated from Zod-only validation to Standard Schema v1 for broader validator compatibility.
-  - Supported libraries include Zod, Valibot, ArkType, and other Standard Schema-compliant validators.
+## [0.2.0]
 
 ### Added
 
@@ -192,25 +192,27 @@ Internal formatting and lint cleanup only. No public API or behavior change.
 - 78afb76: Added smart URL behavior so absolute URLs bypass `baseURL`.
 - 78afb76: Added automatic JSON body serialization and `Content-Type` handling for schema-based requests.
 
-### Breaking
+### Changed
 
-- 78afb76: Standard Schema-compliant validator libraries are now required (for example Zod 3.23+, Valibot 1.0+, ArkType 2.0+).
-- 78afb76: Internal file structure was reorganized (affects deep imports).
-- 78afb76: `FetchError` constructor now requires `(message, response)`.
+- 78afb76: Migrated from Zod-only validation to Standard Schema v1 for broader validator compatibility.
+  - Supported libraries include Zod, Valibot, ArkType, and other Standard Schema-compliant validators.
+- 78afb76: **Breaking:** Standard Schema-compliant validator libraries are now required (for example Zod 3.23+, Valibot 1.0+, ArkType 2.0+).
+- 78afb76: **Breaking:** Internal file structure was reorganized (affects deep imports).
+- 78afb76: **Breaking:** `FetchError` constructor now requires `(message, response)`.
 
-## 0.1.2
+## [0.1.2]
 
 ### Changed
 
 - 69c2b21: Renamed `safeFetch` to `$fetch` while preserving `safeFetch` compatibility for legacy usage.
 
-## 0.1.1
+## [0.1.1]
 
 ### Changed
 
 - 5f1812b: Updated `files` in `package.json` to publish only required artifacts.
 
-## 0.1.0
+## [0.1.0]
 
 ### Added
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 alexandretrotel
+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

@@ -2,76 +2,52 @@
 
 A small fetch wrapper with [**Standard Schema**](https://standardschema.dev/schema) response validation.
 
+Full documentation: [zapstudio.dev/fetch](https://www.zapstudio.dev/fetch)
+
 ## Installation
 
 ```bash
-nub add @zap-studio/fetch
-# or
 npm install @zap-studio/fetch
-# or
-pnpm add @zap-studio/fetch
 ```
 
-## Runtime Support
+You also need a schema library that implements [Standard Schema](https://standardschema.dev/schema), such as Zod, Valibot, or ArkType.
 
-| Runtime            | Minimum version                                  |
-| ------------------ | ------------------------------------------------ |
-| Node.js            | 18.0.0 (ships native `fetch`)                    |
-| Bun                | 1.0.0                                            |
-| Deno               | 1.42                                             |
-| Cloudflare Workers | Any current release                              |
-| Browsers           | Latest evergreen (Chrome, Edge, Firefox, Safari) |
+## Features
 
-The package relies on the global `fetch` API and ships standard ESM only. Deno 1.42 is the first release that can install packages from JSR (`deno add jsr:@zap-studio/fetch`).
+- **Raw fetch mode** through `$fetch(input, options)` — behaves like native `fetch` and returns the `Response`.
+- **Validated fetch mode** through `$fetch(input, schema, options)` — parses and validates the JSON response.
+- **HTTP method helpers** through `api.get`, `api.post`, `api.put`, `api.patch`, and `api.delete`.
+- **Configured clients** through `createFetch(...)` with shared `baseURL`, headers, query params, and error defaults.
+- **JSON convenience** through the `json` option, which serializes the request body and sets `Content-Type`.
+- **Structured errors** with `FetchError` for HTTP failures and `ValidationError` for schema failures.
+- **Validator-agnostic** — works with any library that implements Standard Schema.
+- **Optional logging** through `createFetch({ logger })` ([`@zap-studio/logger`](https://www.npmjs.com/package/@zap-studio/logger)) — omit it and there's zero logging overhead.
+- **Tree-shakeable** — every export is a standalone function with no shared internal state; unused exports are dropped by any modern bundler.
 
-## Quick Example
+## Quick Start
 
 ```ts
-import { api } from "@zap-studio/fetch";
+import { ConsoleLogger } from "@zap-studio/logger";
+import { createFetch } from "@zap-studio/fetch";
 import { z } from "zod";
 
 const UserSchema = z.object({
   id: z.number(),
   name: z.string(),
-  email: z.string().email(),
+  email: z.email(),
 });
 
-const user = await api.get("https://api.example.com/users/1", UserSchema);
+const logger = new ConsoleLogger({ minLevel: "debug" });
+const { api } = createFetch({ logger });
 
-console.log(user.name);
-```
-
-## Before
-
-Without response validation, fetch code often needs unchecked assertions:
-
-```ts
-type User = {
-  id: number;
-  name: string;
-};
-
-const response = await fetch("/api/users/1");
-const data = await response.json();
-
-const user = data as User;
-```
-
-## After
-
-With `@zap-studio/fetch`, the response is validated before it is returned:
-
-```ts
-import { api } from "@zap-studio/fetch";
+const user = await api.get("https://api.example.com/users/1", UserSchema);
 
-const user = await api.get("/api/users/1", UserSchema);
+console.log(user.name); // typed as string, validated at runtime
 ```
 
-The returned value is inferred from the schema.
-
-## Raw Fetch Usage
+## Raw Fetch Mode
 
-Use `$fetch` without a schema when you want the normal `Response` object.
+Behaves like native `fetch` and returns the `Response`.
 
 ```ts
 import { $fetch } from "@zap-studio/fetch";
@@ -80,21 +56,9 @@ const response = await $fetch("/api/users/1");
 const user = await response.json();
 ```
 
-Native fetch options are passed through as `RequestInit`.
-
-```ts
-const response = await $fetch("/api/users", {
-  method: "POST",
-  body: JSON.stringify({ name: "Ada" }),
-  headers: {
-    "Content-Type": "application/json",
-  },
-});
-```
-
-## Validated Fetch Usage
+## Validated Fetch Mode
 
-Pass a Standard Schema as the second argument to validate the JSON response.
+Parses and validates the JSON response.
 
 ```ts
 import { $fetch } from "@zap-studio/fetch";
@@ -102,213 +66,93 @@ 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.
+## HTTP Method Helpers
 
-## API Method Helpers
-
-The `api` export provides common HTTP methods.
+`api.get`, `api.post`, `api.put`, `api.patch`, and `api.delete`.
 
 ```ts
 import { api } from "@zap-studio/fetch";
 
-const user = await api.get("/api/users/1", UserSchema);
-
 const created = await api.post("/api/users", UserSchema, {
-  json: {
-    name: "Ada",
-    email: "ada@example.com",
-  },
-});
-```
-
-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,
+  json: { name: "Ada", email: "ada@example.com" },
 });
 ```
 
-`body` and `json` are mutually exclusive.
+## Configured Clients
 
-## 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.
+Shared `baseURL`, headers, query params, and error defaults.
 
 ```ts
 import { createFetch } from "@zap-studio/fetch";
 
-const { $fetch, api } = createFetch({
+const { api } = createFetch({
   baseURL: "https://api.example.com",
-  headers: {
-    Authorization: `Bearer ${token}`,
-  },
-  searchParams: {
-    locale: "en",
-  },
+  headers: { Authorization: `Bearer ${token}` },
 });
 
 const user = await api.get("/users/1", UserSchema);
-const response = await $fetch("/health");
 ```
 
-Supported defaults:
+## JSON Convenience
 
-| 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.
+Serializes the request body and sets `Content-Type`.
 
 ```ts
-const result = await api.get("/api/users/1", UserSchema, {
-  throwOnValidationError: false,
+await api.post("/api/users", UserSchema, {
+  json: { name: "Ada" }, // mutually exclusive with `body`
 });
-
-if (result.issues) {
-  console.error("Validation failed:", result.issues);
-} else {
-  console.log("Validation passed:", result.value);
-}
 ```
 
-## HTTP Errors
+## Structured Errors
 
-By default, non-ok responses throw a `FetchError`.
+`FetchError` for HTTP failures and `ValidationError` for schema failures.
 
 ```ts
 import { FetchError } from "@zap-studio/fetch";
+import { ValidationError } from "@zap-studio/validation";
 
 try {
-  await api.get("/api/users/404", UserSchema);
+  await api.get("/api/users/1", UserSchema);
 } catch (error) {
-  if (error instanceof FetchError) {
-    console.error(error.status);
-    console.error(error.response);
-  }
+  if (error instanceof FetchError) console.error(error.status);
+  if (error instanceof ValidationError) console.error(error.issues);
 }
 ```
 
-Disable this behavior when you want to handle the raw response yourself.
+## Validator-Agnostic
 
-```ts
-const response = await $fetch("/api/users/404", {
-  throwOnFetchError: false,
-});
+Works with any library that implements Standard Schema.
 
-console.log(response.status);
+```ts
+// UserSchema can come from Zod, Valibot, ArkType, or any Standard Schema-compatible library
+import type { StandardSchemaV1 } from "@zap-studio/validation";
 ```
 
-## Request Objects
+## Logging
 
-The first argument (`input`) uses the same type as global `fetch`.
+Pass a `logger?: Logger` from [`@zap-studio/logger`](https://www.npmjs.com/package/@zap-studio/logger) to `createFetch(...)` to observe requests, responses, and validation failures. Omit it and nothing is logged.
 
 ```ts
-const request = new Request("https://api.example.com/users/1", {
-  headers: {
-    Authorization: `Bearer ${token}`,
-  },
-});
+import { ConsoleLogger } from "@zap-studio/logger";
+import { createFetch } from "@zap-studio/fetch";
 
-const user = await $fetch(request, UserSchema);
+const logger = new ConsoleLogger({ minLevel: "debug" });
+const { api } = createFetch({ baseURL: "https://api.example.com", logger });
 ```
 
-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/)
+Outgoing requests log at `debug`, response status logs at `debug` (2xx) or `warn` (non-2xx), and schema validation failures log at `error`.
 
-You can also import Standard Schema types from `@zap-studio/validation` when needed.
+## Runtime Support
 
-```ts
-import type { StandardSchemaV1 } from "@zap-studio/validation";
-```
+| Runtime            | Minimum version                                  |
+| ------------------ | ------------------------------------------------ |
+| Node.js            | 18.0.0 (ships native `fetch`)                    |
+| Bun                | 1.0.0                                            |
+| Deno               | 1.42                                             |
+| Cloudflare Workers | Any current release                              |
+| Browsers           | Latest evergreen (Chrome, Edge, Firefox, Safari) |
 
-## 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 |
+The package relies on the global `fetch` API and ships standard ESM only. Deno 1.42 is the first release that can install packages from JSR (`deno add jsr:@zap-studio/fetch`).
 
 ## License