@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.
- package/CHANGELOG.md +70 -65
- package/README.md +53 -212
- package/dist/{errors.d.mts → errors.d.ts} +1 -1
- package/dist/errors.d.ts.map +1 -0
- package/dist/{errors.mjs → errors.js} +1 -1
- package/dist/errors.js.map +1 -0
- package/dist/{index.d.mts → index.d.ts} +16 -3
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +316 -0
- package/dist/index.js.map +1 -0
- package/dist/{types.d.mts → types.d.ts} +30 -2
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +0 -0
- package/package.json +8 -21
- package/dist/constants.d.mts +0 -17
- package/dist/constants.d.mts.map +0 -1
- package/dist/constants.mjs +0 -21
- package/dist/constants.mjs.map +0 -1
- package/dist/errors.d.mts.map +0 -1
- package/dist/errors.mjs.map +0 -1
- package/dist/headers.d.mts +0 -26
- package/dist/headers.d.mts.map +0 -1
- package/dist/headers.mjs +0 -34
- package/dist/headers.mjs.map +0 -1
- package/dist/index.d.mts.map +0 -1
- package/dist/index.mjs +0 -103
- package/dist/index.mjs.map +0 -1
- package/dist/internal.d.mts +0 -32
- package/dist/internal.d.mts.map +0 -1
- package/dist/internal.mjs +0 -75
- package/dist/internal.mjs.map +0 -1
- package/dist/methods.d.mts +0 -22
- package/dist/methods.d.mts.map +0 -1
- package/dist/methods.mjs +0 -58
- package/dist/methods.mjs.map +0 -1
- package/dist/request.d.mts +0 -30
- package/dist/request.d.mts.map +0 -1
- package/dist/request.mjs +0 -43
- package/dist/request.mjs.map +0 -1
- package/dist/types.d.mts.map +0 -1
- package/dist/types.mjs +0 -1
- package/dist/url.d.mts +0 -26
- package/dist/url.d.mts.map +0 -1
- package/dist/url.mjs +0 -60
- package/dist/url.mjs.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,35 +1,61 @@
|
|
|
1
|
-
|
|
1
|
+
# Changelog
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
28
|
+
### Removed
|
|
8
29
|
|
|
9
|
-
|
|
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
|
-
###
|
|
71
|
+
### Added
|
|
49
72
|
|
|
50
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
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
|
-
###
|
|
189
|
+
### Changed
|
|
187
190
|
|
|
188
|
-
- 78afb76:
|
|
189
|
-
-
|
|
190
|
-
- 78afb76:
|
|
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
|
-
|
|
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.
|
|
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
|
-
##
|
|
43
|
+
## Raw Fetch Mode
|
|
45
44
|
|
|
46
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
64
|
+
## HTTP Method Helpers
|
|
90
65
|
|
|
91
|
-
|
|
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
|
-
|
|
143
|
-
|
|
144
|
-
## Query Params
|
|
76
|
+
## Configured Clients
|
|
145
77
|
|
|
146
|
-
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
216
|
-
|
|
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
|
-
##
|
|
101
|
+
## Structured Errors
|
|
227
102
|
|
|
228
|
-
|
|
103
|
+
`FetchError` for HTTP failures and `ValidationError` for schema failures.
|
|
229
104
|
|
|
230
105
|
```ts
|
|
231
|
-
import { FetchError } from "@zap-studio/fetch
|
|
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/
|
|
110
|
+
await api.get("/api/users/1", UserSchema);
|
|
235
111
|
} catch (error) {
|
|
236
|
-
if (error instanceof FetchError)
|
|
237
|
-
|
|
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
|
-
|
|
117
|
+
## Validator-Agnostic
|
|
244
118
|
|
|
245
|
-
|
|
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
|
-
|
|
259
|
-
|
|
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
|
-
|
|
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
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
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
|
-
|
|
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
|
|
|
@@ -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"}
|
|
@@ -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 {
|
|
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.
|
|
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"}
|