@zap-studio/fetch 0.5.5 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (45) hide show
  1. package/CHANGELOG.md +70 -65
  2. package/README.md +53 -212
  3. package/dist/{errors.d.mts → errors.d.ts} +1 -1
  4. package/dist/errors.d.ts.map +1 -0
  5. package/dist/{errors.mjs → errors.js} +1 -1
  6. package/dist/errors.js.map +1 -0
  7. package/dist/{index.d.mts → index.d.ts} +16 -3
  8. package/dist/index.d.ts.map +1 -0
  9. package/dist/index.js +316 -0
  10. package/dist/index.js.map +1 -0
  11. package/dist/{types.d.mts → types.d.ts} +30 -2
  12. package/dist/types.d.ts.map +1 -0
  13. package/dist/types.js +0 -0
  14. package/package.json +8 -21
  15. package/dist/constants.d.mts +0 -17
  16. package/dist/constants.d.mts.map +0 -1
  17. package/dist/constants.mjs +0 -21
  18. package/dist/constants.mjs.map +0 -1
  19. package/dist/errors.d.mts.map +0 -1
  20. package/dist/errors.mjs.map +0 -1
  21. package/dist/headers.d.mts +0 -26
  22. package/dist/headers.d.mts.map +0 -1
  23. package/dist/headers.mjs +0 -34
  24. package/dist/headers.mjs.map +0 -1
  25. package/dist/index.d.mts.map +0 -1
  26. package/dist/index.mjs +0 -103
  27. package/dist/index.mjs.map +0 -1
  28. package/dist/internal.d.mts +0 -32
  29. package/dist/internal.d.mts.map +0 -1
  30. package/dist/internal.mjs +0 -75
  31. package/dist/internal.mjs.map +0 -1
  32. package/dist/methods.d.mts +0 -22
  33. package/dist/methods.d.mts.map +0 -1
  34. package/dist/methods.mjs +0 -58
  35. package/dist/methods.mjs.map +0 -1
  36. package/dist/request.d.mts +0 -30
  37. package/dist/request.d.mts.map +0 -1
  38. package/dist/request.mjs +0 -43
  39. package/dist/request.mjs.map +0 -1
  40. package/dist/types.d.mts.map +0 -1
  41. package/dist/types.mjs +0 -1
  42. package/dist/url.d.mts +0 -26
  43. package/dist/url.d.mts.map +0 -1
  44. package/dist/url.mjs +0 -60
  45. package/dist/url.mjs.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,35 +1,61 @@
1
- ## @zap-studio/fetch@0.5.5
1
+ # Changelog
2
2
 
3
- ### Migrate to ultracite lint/format
3
+ All notable changes to this project will be documented in this file.
4
4
 
5
- Internal formatting and lint cleanup only. No public API or behavior change.
5
+ 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).
6
+
7
+ ## [1.0.0]
8
+
9
+ ### Changed
10
+
11
+ - Clarified tree-shakeable design in the package description and README (no code change).
12
+
13
+ ### Removed
14
+
15
+ 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.
16
+
17
+ - Removed the `./constants`, `./headers`, `./request`, `./url`, and `./fetch` subpath exports. Use the root `@zap-studio/fetch` entry instead.
18
+ - `GLOBAL_DEFAULTS`, `FetchError`, `$fetch`, `api`, `createFetch`, and all public types are unaffected and still exported from `.`; `./errors` and `./types` subpaths are unaffected.
19
+
20
+ ## [0.5.6]
21
+
22
+ ### Added
23
+
24
+ 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.
25
+
26
+ - The `$fetch`/`api`/`createFetch` implementation moved from the entrypoint into its own module, available as the new `./fetch` subpath.
6
27
 
7
- # @zap-studio/fetch
28
+ ### Removed
8
29
 
9
- ## 0.5.4
30
+ - Removed the `./internal` and `./methods` subpath exports. Both were implementation details (`fetchInternal`, `createMethod`) and are no longer part of the public API.
31
+
32
+ ## [0.5.5]
33
+
34
+ ### Changed
35
+
36
+ Internal formatting and lint cleanup only. No public API or behavior change.
37
+
38
+ ## [0.5.4]
10
39
 
11
40
  ### Changed
12
41
 
13
42
  - Added fetch ecosystem benchmarks and grouped benchmark output for easier cross-library comparisons.
14
43
  - Applied small internal performance optimizations in request preparation, URL resolution, and header merging without changing public API behavior.
15
44
 
16
- ## 0.5.3
45
+ ## [0.5.3]
17
46
 
18
47
  ### Changed
19
48
 
20
49
  - Refactor `createFetch(...)` to derive fallback defaults from `GLOBAL_DEFAULTS` instead of re-defining primitive defaults inline.
21
50
 
22
- ## 0.5.2
51
+ ## [0.5.2]
23
52
 
24
53
  ### Changed
25
54
 
26
55
  - Expand TSDoc coverage across fetch modules and exported contracts for stronger JSR documentation completeness.
27
-
28
- ### Dependencies
29
-
30
56
  - Updated dependency `@zap-studio/validation` to `0.3.4`.
31
57
 
32
- ## 0.5.1
58
+ ## [0.5.1]
33
59
 
34
60
  ### Fixed
35
61
 
@@ -38,19 +64,18 @@ Internal formatting and lint cleanup only. No public API or behavior change.
38
64
  ### Changed
39
65
 
40
66
  - 2ea1a70: Cleaned up public option typings by removing redundant `| undefined` unions from fetch configuration types and overloads.
41
-
42
- ### Dependencies
43
-
44
67
  - Updated dependency `@zap-studio/validation` to `0.3.3`.
45
68
 
46
- ## 0.5.0
69
+ ## [0.5.0]
47
70
 
48
- ### Breaking
71
+ ### Added
49
72
 
50
- - 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.
73
+ - 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).
74
+ - Added full package test coverage across statements, branches, functions, and lines.
51
75
 
52
76
  ### Changed
53
77
 
78
+ - **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.
54
79
  - Simplified the request API around web platform types.
55
80
  - 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.
56
81
  - Non-`Request` values (including `URL`) are normalized to a string URL before query merge.
@@ -62,46 +87,35 @@ Internal formatting and lint cleanup only. No public API or behavior change.
62
87
  - `body` and `json` are mutually exclusive in TypeScript and guarded at runtime.
63
88
  - Reworked URL handling to use the platform `URL` and `URLSearchParams` APIs while preserving relative URL output when no `baseURL` is configured.
64
89
  - Simplified the internal module structure and removed the old `utils` module.
90
+ - Reworked tests to mirror the `src` module structure.
91
+ - JSR dependency mapping now pins `@zap-studio/validation` to `0.3.2`.
65
92
 
66
93
  ### Fixed
67
94
 
68
95
  - Fixed absolute URL handling when no `baseURL` is configured.
69
96
  - `resolveSearchParams` keeps a trailing `#` when the input URL had an empty fragment (for example `.../path#`), matching typical `URL` serialization instead of dropping the delimiter.
70
97
 
71
- ### Tests
72
-
73
- - Reworked tests to mirror the `src` module structure.
74
- - Added full package coverage across statements, branches, functions, and lines.
75
-
76
- ### Documentation
77
-
78
- - 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).
79
-
80
- ### Dependencies
98
+ ## [0.4.7]
81
99
 
82
- - JSR dependency mapping now pins `@zap-studio/validation` to `0.3.2`.
83
-
84
- ## 0.4.7
85
-
86
- ### Patch Changes
100
+ ### Changed
87
101
 
88
102
  - e26293e: Updated dependencies.
89
103
  - @zap-studio/validation@0.3.2
90
104
 
91
- ## 0.4.6
105
+ ## [0.4.6]
92
106
 
93
- ### Patch Changes
107
+ ### Changed
94
108
 
95
109
  - 5ea3d3b: Updated dependencies.
96
110
  - @zap-studio/validation@0.3.1
97
111
 
98
- ## 0.4.5
112
+ ## [0.4.5]
99
113
 
100
- ### Dependencies
114
+ ### Changed
101
115
 
102
116
  - f75b984: Updated dependency `@zap-studio/validation` to `0.3.0`.
103
117
 
104
- ## 0.4.4
118
+ ## [0.4.4]
105
119
 
106
120
  ### Fixed
107
121
 
@@ -110,39 +124,33 @@ Internal formatting and lint cleanup only. No public API or behavior change.
110
124
  - Auto-stringify plain JSON body values even when no response schema is provided.
111
125
  - Set `Content-Type: application/json` only when auto-stringifying and no explicit content type is set.
112
126
 
113
- ## 0.4.3
127
+ ## [0.4.3]
114
128
 
115
129
  ### Changed
116
130
 
117
131
  - e4542bb: Refined `standardValidate` typings so return types depend on `throwOnError`, and updated `@zap-studio/fetch` integration while preserving the existing boolean configuration API.
118
-
119
- ### Dependencies
120
-
121
132
  - e4542bb: Updated dependency `@zap-studio/validation` to `0.2.1`.
122
133
 
123
- ## 0.4.2
134
+ ## [0.4.2]
124
135
 
125
- ### Dependencies
136
+ ### Changed
126
137
 
127
138
  - 2de8183: Updated dependency `@zap-studio/validation` to `0.2.0`.
128
139
 
129
- ## 0.4.1
140
+ ## [0.4.1]
130
141
 
131
142
  ### Changed
132
143
 
133
144
  - 447dbda: Switched shared Standard Schema validation utilities to `@zap-studio/validation`.
134
-
135
- ### Dependencies
136
-
137
145
  - 447dbda: Updated dependency `@zap-studio/validation` to `0.1.0`.
138
146
 
139
- ## 0.4.0
147
+ ## [0.4.0]
140
148
 
141
149
  ### Added
142
150
 
143
151
  - 69057cd: Exposed fetch defaults constants and utility helpers as public exports.
144
152
 
145
- ## 0.3.1
153
+ ## [0.3.1]
146
154
 
147
155
  ### Changed
148
156
 
@@ -151,31 +159,26 @@ Internal formatting and lint cleanup only. No public API or behavior change.
151
159
  - `throwOnValidationError: false` returns `Promise<StandardSchemaV1.Result<TSchema>>`.
152
160
  - This improves type safety and removes manual narrowing in default usage.
153
161
 
154
- ## 0.3.0
162
+ ## [0.3.0]
155
163
 
156
164
  ### Added
157
165
 
158
166
  - 659621c: Added `searchParams` support in `createFetch` for factory-level default query parameters.
159
167
  - Per-request `searchParams` still override factory defaults.
160
168
 
161
- ## 0.2.2
169
+ ## [0.2.2]
162
170
 
163
171
  ### Changed
164
172
 
165
173
  - 5c3abbf: Prepared JSR publish and `isolatedDeclarations` support with explicit `$Fetch` and `ApiMethods` types.
166
174
 
167
- ## 0.2.1
175
+ ## [0.2.1]
168
176
 
169
177
  ### Changed
170
178
 
171
179
  - 82bac5c: Replaced regex-based slash trimming with more efficient string manipulation for URL normalization.
172
180
 
173
- ## 0.2.0
174
-
175
- ### Changed
176
-
177
- - 78afb76: Migrated from Zod-only validation to Standard Schema v1 for broader validator compatibility.
178
- - Supported libraries include Zod, Valibot, ArkType, and other Standard Schema-compliant validators.
181
+ ## [0.2.0]
179
182
 
180
183
  ### Added
181
184
 
@@ -183,25 +186,27 @@ Internal formatting and lint cleanup only. No public API or behavior change.
183
186
  - 78afb76: Added smart URL behavior so absolute URLs bypass `baseURL`.
184
187
  - 78afb76: Added automatic JSON body serialization and `Content-Type` handling for schema-based requests.
185
188
 
186
- ### Breaking
189
+ ### Changed
187
190
 
188
- - 78afb76: Standard Schema-compliant validator libraries are now required (for example Zod 3.23+, Valibot 1.0+, ArkType 2.0+).
189
- - 78afb76: Internal file structure was reorganized (affects deep imports).
190
- - 78afb76: `FetchError` constructor now requires `(message, response)`.
191
+ - 78afb76: Migrated from Zod-only validation to Standard Schema v1 for broader validator compatibility.
192
+ - Supported libraries include Zod, Valibot, ArkType, and other Standard Schema-compliant validators.
193
+ - 78afb76: **Breaking:** Standard Schema-compliant validator libraries are now required (for example Zod 3.23+, Valibot 1.0+, ArkType 2.0+).
194
+ - 78afb76: **Breaking:** Internal file structure was reorganized (affects deep imports).
195
+ - 78afb76: **Breaking:** `FetchError` constructor now requires `(message, response)`.
191
196
 
192
- ## 0.1.2
197
+ ## [0.1.2]
193
198
 
194
199
  ### Changed
195
200
 
196
201
  - 69c2b21: Renamed `safeFetch` to `$fetch` while preserving `safeFetch` compatibility for legacy usage.
197
202
 
198
- ## 0.1.1
203
+ ## [0.1.1]
199
204
 
200
205
  ### Changed
201
206
 
202
207
  - 5f1812b: Updated `files` in `package.json` to publish only required artifacts.
203
208
 
204
- ## 0.1.0
209
+ ## [0.1.0]
205
210
 
206
211
  ### Added
207
212
 
package/README.md CHANGED
@@ -2,13 +2,28 @@
2
2
 
3
3
  A small fetch wrapper with [**Standard Schema**](https://standardschema.dev/schema) response validation.
4
4
 
5
+ Full documentation: [zapstudio.dev/fetch](https://www.zapstudio.dev/fetch)
6
+
5
7
  ## Installation
6
8
 
7
9
  ```bash
8
10
  npm install @zap-studio/fetch
9
11
  ```
10
12
 
11
- ## Quick Example
13
+ You also need a schema library that implements [Standard Schema](https://standardschema.dev/schema), such as Zod, Valibot, or ArkType.
14
+
15
+ ## Features
16
+
17
+ - **Raw fetch mode** through `$fetch(input, options)` — behaves like native `fetch` and returns the `Response`.
18
+ - **Validated fetch mode** through `$fetch(input, schema, options)` — parses and validates the JSON response.
19
+ - **HTTP method helpers** through `api.get`, `api.post`, `api.put`, `api.patch`, and `api.delete`.
20
+ - **Configured clients** through `createFetch(...)` with shared `baseURL`, headers, query params, and error defaults.
21
+ - **JSON convenience** through the `json` option, which serializes the request body and sets `Content-Type`.
22
+ - **Structured errors** with `FetchError` for HTTP failures and `ValidationError` for schema failures.
23
+ - **Validator-agnostic** — works with any library that implements Standard Schema.
24
+ - **Tree-shakeable** — every export is a standalone function with no shared internal state; unused exports are dropped by any modern bundler.
25
+
26
+ ## Quick Start
12
27
 
13
28
  ```ts
14
29
  import { api } from "@zap-studio/fetch";
@@ -17,45 +32,17 @@ import { z } from "zod";
17
32
  const UserSchema = z.object({
18
33
  id: z.number(),
19
34
  name: z.string(),
20
- email: z.string().email(),
35
+ email: z.email(),
21
36
  });
22
37
 
23
38
  const user = await api.get("https://api.example.com/users/1", UserSchema);
24
39
 
25
- console.log(user.name);
26
- ```
27
-
28
- ## Before
29
-
30
- Without response validation, fetch code often needs unchecked assertions:
31
-
32
- ```ts
33
- type User = {
34
- id: number;
35
- name: string;
36
- };
37
-
38
- const response = await fetch("/api/users/1");
39
- const data = await response.json();
40
-
41
- const user = data as User;
40
+ console.log(user.name); // typed as string, validated at runtime
42
41
  ```
43
42
 
44
- ## After
43
+ ## Raw Fetch Mode
45
44
 
46
- With `@zap-studio/fetch`, the response is validated before it is returned:
47
-
48
- ```ts
49
- import { api } from "@zap-studio/fetch";
50
-
51
- const user = await api.get("/api/users/1", UserSchema);
52
- ```
53
-
54
- The returned value is inferred from the schema.
55
-
56
- ## Raw Fetch Usage
57
-
58
- Use `$fetch` without a schema when you want the normal `Response` object.
45
+ Behaves like native `fetch` and returns the `Response`.
59
46
 
60
47
  ```ts
61
48
  import { $fetch } from "@zap-studio/fetch";
@@ -64,21 +51,9 @@ const response = await $fetch("/api/users/1");
64
51
  const user = await response.json();
65
52
  ```
66
53
 
67
- Native fetch options are passed through as `RequestInit`.
68
-
69
- ```ts
70
- const response = await $fetch("/api/users", {
71
- method: "POST",
72
- body: JSON.stringify({ name: "Ada" }),
73
- headers: {
74
- "Content-Type": "application/json",
75
- },
76
- });
77
- ```
78
-
79
- ## Validated Fetch Usage
54
+ ## Validated Fetch Mode
80
55
 
81
- Pass a Standard Schema as the second argument to validate the JSON response.
56
+ Parses and validates the JSON response.
82
57
 
83
58
  ```ts
84
59
  import { $fetch } from "@zap-studio/fetch";
@@ -86,213 +61,79 @@ import { $fetch } from "@zap-studio/fetch";
86
61
  const user = await $fetch("/api/users/1", UserSchema);
87
62
  ```
88
63
 
89
- The schema validates the response body, not the request body.
64
+ ## HTTP Method Helpers
90
65
 
91
- When validation fails, a `ValidationError` is thrown by default.
92
-
93
- ## API Method Helpers
94
-
95
- The `api` export provides common HTTP methods.
66
+ `api.get`, `api.post`, `api.put`, `api.patch`, and `api.delete`.
96
67
 
97
68
  ```ts
98
69
  import { api } from "@zap-studio/fetch";
99
70
 
100
- const user = await api.get("/api/users/1", UserSchema);
101
-
102
71
  const created = await api.post("/api/users", UserSchema, {
103
- json: {
104
- name: "Ada",
105
- email: "ada@example.com",
106
- },
107
- });
108
- ```
109
-
110
- In this example, `UserSchema` validates the response from `/api/users`. The `json` value is the outgoing request body and is not validated by `UserSchema`.
111
-
112
- These helpers set the HTTP method for you. For raw responses without validation, use `$fetch`.
113
-
114
- ## JSON Request Bodies
115
-
116
- Use `json` when you want the package to serialize a JSON request body.
117
-
118
- ```ts
119
- await api.post("/api/users", UserSchema, {
120
- json: {
121
- name: "Ada",
122
- },
123
- });
124
- ```
125
-
126
- The schema argument still validates the response. Validate request bodies separately before passing them to `json` if your application needs outgoing payload validation.
127
-
128
- This sets:
129
-
130
- - `body` to `JSON.stringify(json)`
131
- - `Content-Type` to `application/json` when no content type was already provided
132
-
133
- Use native `body` for standard fetch behavior.
134
-
135
- ```ts
136
- await $fetch("/api/upload", {
137
- method: "POST",
138
- body: formData,
72
+ json: { name: "Ada", email: "ada@example.com" },
139
73
  });
140
74
  ```
141
75
 
142
- `body` and `json` are mutually exclusive.
143
-
144
- ## Query Params
76
+ ## Configured Clients
145
77
 
146
- Use `searchParams` for per-request query params.
147
-
148
- ```ts
149
- await api.get("/api/users", UserListSchema, {
150
- searchParams: {
151
- page: "1",
152
- limit: "20",
153
- },
154
- });
155
- ```
156
-
157
- `searchParams` accepts the same input shapes as `new URLSearchParams(...)`.
158
-
159
- ```ts
160
- await api.get("/api/users", UserListSchema, {
161
- searchParams: new URLSearchParams({ q: "ada" }),
162
- });
163
-
164
- await api.get("/api/users", UserListSchema, {
165
- searchParams: "q=ada&page=1",
166
- });
167
-
168
- await api.get("/api/users", UserListSchema, {
169
- searchParams: [["q", "ada"]],
170
- });
171
- ```
172
-
173
- When defaults, URL query params, and request params overlap, later values win:
174
-
175
- 1. `createFetch({ searchParams })`
176
- 2. query params already present in the URL
177
- 3. per-request `searchParams`
178
-
179
- ## Creating a Client
180
-
181
- Use `createFetch` to configure shared defaults.
78
+ Shared `baseURL`, headers, query params, and error defaults.
182
79
 
183
80
  ```ts
184
81
  import { createFetch } from "@zap-studio/fetch";
185
82
 
186
- const { $fetch, api } = createFetch({
83
+ const { api } = createFetch({
187
84
  baseURL: "https://api.example.com",
188
- headers: {
189
- Authorization: `Bearer ${token}`,
190
- },
191
- searchParams: {
192
- locale: "en",
193
- },
85
+ headers: { Authorization: `Bearer ${token}` },
194
86
  });
195
87
 
196
88
  const user = await api.get("/users/1", UserSchema);
197
- const response = await $fetch("/health");
198
89
  ```
199
90
 
200
- Supported defaults:
201
-
202
- | Option | Description |
203
- | ------------------------ | ----------------------------------------------- |
204
- | `baseURL` | Base URL for relative request URLs |
205
- | `headers` | Headers applied to every request |
206
- | `searchParams` | Query params applied to every request |
207
- | `throwOnFetchError` | Throw `FetchError` for non-ok responses |
208
- | `throwOnValidationError` | Throw `ValidationError` for validation failures |
91
+ ## JSON Convenience
209
92
 
210
- ## Non-throwing Validation
211
-
212
- Set `throwOnValidationError: false` to receive the raw Standard Schema result.
93
+ Serializes the request body and sets `Content-Type`.
213
94
 
214
95
  ```ts
215
- const result = await api.get("/api/users/1", UserSchema, {
216
- throwOnValidationError: false,
96
+ await api.post("/api/users", UserSchema, {
97
+ json: { name: "Ada" }, // mutually exclusive with `body`
217
98
  });
218
-
219
- if (result.issues) {
220
- console.error("Validation failed:", result.issues);
221
- } else {
222
- console.log("Validation passed:", result.value);
223
- }
224
99
  ```
225
100
 
226
- ## HTTP Errors
101
+ ## Structured Errors
227
102
 
228
- By default, non-ok responses throw a `FetchError`.
103
+ `FetchError` for HTTP failures and `ValidationError` for schema failures.
229
104
 
230
105
  ```ts
231
- import { FetchError } from "@zap-studio/fetch/errors";
106
+ import { FetchError } from "@zap-studio/fetch";
107
+ import { ValidationError } from "@zap-studio/validation";
232
108
 
233
109
  try {
234
- await api.get("/api/users/404", UserSchema);
110
+ await api.get("/api/users/1", UserSchema);
235
111
  } catch (error) {
236
- if (error instanceof FetchError) {
237
- console.error(error.status);
238
- console.error(error.response);
239
- }
112
+ if (error instanceof FetchError) console.error(error.status);
113
+ if (error instanceof ValidationError) console.error(error.issues);
240
114
  }
241
115
  ```
242
116
 
243
- Disable this behavior when you want to handle the raw response yourself.
117
+ ## Validator-Agnostic
244
118
 
245
- ```ts
246
- const response = await $fetch("/api/users/404", {
247
- throwOnFetchError: false,
248
- });
249
-
250
- console.log(response.status);
251
- ```
252
-
253
- ## Request Objects
254
-
255
- The first argument (`input`) uses the same type as global `fetch`.
119
+ Works with any library that implements Standard Schema.
256
120
 
257
121
  ```ts
258
- const request = new Request("https://api.example.com/users/1", {
259
- headers: {
260
- Authorization: `Bearer ${token}`,
261
- },
262
- });
263
-
264
- const user = await $fetch(request, UserSchema);
122
+ // UserSchema can come from Zod, Valibot, ArkType, or any Standard Schema-compatible library
123
+ import type { StandardSchemaV1 } from "@zap-studio/validation";
265
124
  ```
266
125
 
267
- Per-request options are merged on top of the `Request`.
268
-
269
- ## Standard Schema
270
-
271
- `@zap-studio/fetch` validates responses through `@zap-studio/validation`, so it works with any validation library that implements Standard Schema.
272
-
273
- Examples include:
126
+ ## Runtime Support
274
127
 
275
- - [Zod](https://zod.dev/)
276
- - [Valibot](https://valibot.dev/)
277
- - [ArkType](https://arktype.io/)
278
-
279
- You can also import Standard Schema types from `@zap-studio/validation` when needed.
280
-
281
- ```ts
282
- import type { StandardSchemaV1 } from "@zap-studio/validation";
283
- ```
128
+ | Runtime | Minimum version |
129
+ | ------------------ | ------------------------------------------------ |
130
+ | Node.js | 18.0.0 (ships native `fetch`) |
131
+ | Bun | 1.0.0 |
132
+ | Deno | 1.42 |
133
+ | Cloudflare Workers | Any current release |
134
+ | Browsers | Latest evergreen (Chrome, Edge, Firefox, Safari) |
284
135
 
285
- ## Choosing the Right API
286
-
287
- | API | Use when |
288
- | ------------- | ------------------------------------------------- |
289
- | `$fetch` | You want raw fetch behavior or a custom method |
290
- | `api.get` | You want a validated GET request |
291
- | `api.post` | You want a validated POST request |
292
- | `api.put` | You want a validated PUT request |
293
- | `api.patch` | You want a validated PATCH request |
294
- | `api.delete` | You want a validated DELETE request |
295
- | `createFetch` | You want shared defaults like base URL or headers |
136
+ 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`).
296
137
 
297
138
  ## License
298
139
 
@@ -38,4 +38,4 @@ declare class FetchError extends Error {
38
38
  }
39
39
  //#endregion
40
40
  export { FetchError };
41
- //# sourceMappingURL=errors.d.mts.map
41
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;cAwBa,mBAAmB;;;;EAI9B,QAAQ;;;;EAIR,UAAU;;;;EAKV,YAAY,iBAAiB,UAAU"}
@@ -44,4 +44,4 @@ var FetchError = class extends Error {
44
44
  //#endregion
45
45
  export { FetchError };
46
46
 
47
- //# sourceMappingURL=errors.mjs.map
47
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Custom error types used by the fetch package.\n *\n * @module @zap-studio/fetch/errors\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;EAC/C,MAAM,OAAO;EACb,KAAK,OAAO;EACZ,KAAK,SAAS,SAAS;EACvB,KAAK,WAAW;CAClB;AACF"}
@@ -1,6 +1,19 @@
1
- import { $Fetch, ApiMethods, ExtendedRequestInit, FetchDefaults, FetchInput } from "./types.mjs";
1
+ import { FetchError } from "./errors.js";
2
+ import { $Fetch, ApiMethods, ExtendedRequestInit, FetchDefaults, FetchInput, NormalizedRequest } from "./types.js";
2
3
  import { StandardSchemaV1 } from "@zap-studio/validation";
3
4
  //#region src/index.d.ts
5
+ /**
6
+ * Default options for the global $fetch
7
+ *
8
+ * These defaults are used by the top-level `$fetch` export.
9
+ * Use `createFetch(...)` when you need per-client defaults.
10
+ *
11
+ * @example
12
+ * import { GLOBAL_DEFAULTS } from "@zap-studio/fetch";
13
+ *
14
+ * console.log(GLOBAL_DEFAULTS.throwOnFetchError); // true
15
+ */
16
+ declare const GLOBAL_DEFAULTS: FetchDefaults;
4
17
  /**
5
18
  * Type-safe fetch wrapper with Standard Schema validation.
6
19
  *
@@ -110,5 +123,5 @@ declare const createFetch: (factoryOptions?: Partial<FetchDefaults>) => {
110
123
  api: ApiMethods;
111
124
  };
112
125
  //#endregion
113
- export { $fetch, api, createFetch };
114
- //# sourceMappingURL=index.d.mts.map
126
+ export { type $Fetch, $fetch, type ApiMethods, type ExtendedRequestInit, type FetchDefaults, FetchError, type FetchInput, GLOBAL_DEFAULTS, type NormalizedRequest, api, createFetch };
127
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;;;;;;;;;;;cA8Ca,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgYR,OAAO,gBAAgB,kBAC3C,OAAO,YACP,QAAQ,SACR,SAAS;EAAwB;IAChC,QAAQ,iBAAiB,OAAO,iBAAiB,YAAY;iBAE1C,OAAO,gBAAgB,kBAC3C,OAAO,YACP,QAAQ,SACR,UAAU;EAAwB;IACjC,QAAQ,iBAAiB,YAAY;iBAElB,OACpB,OAAO,YACP,UAAU,sBACT,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;cAqCE,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmCL,cACX,iBAAgB,QAAQ;EAExB,QAAQ;EACR,KAAK"}