fetchwork 1.0.22 → 1.0.23
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/README.md +87 -15
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<h1 align="center">FetchWork</h1>
|
|
6
6
|
|
|
7
7
|
<p align="center" style="font-size: 1.2rem; line-height: 1.6; margin: 2rem 0;">
|
|
8
|
-
An ultra-fast, lightweight, and type-safe web framework built natively on <b>W3C Web Standards</b> for <b>Bun</b>. Designed with zero runtime dependencies, high-throughput compiled regex routing, and an intuitive unified context.
|
|
8
|
+
An ultra-fast, lightweight, and type-safe web framework built natively on <b>W3C Web Standards</b> for <b>Bun</b>. Designed with zero runtime dependencies, high-throughput compiled regex routing, and an intuitive generic unified context.
|
|
9
9
|
</p>
|
|
10
10
|
|
|
11
11
|
---
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
## Features
|
|
14
14
|
|
|
15
15
|
- **Pure W3C Web Standard Core**: Built 100% on native `Request` and `Response` web interfaces with zero-copy I/O.
|
|
16
|
+
- **Generic Type-Safe Context**: Strongly-typed `Context<{ body, query, params }>` with optional parameters—use plain `Context` or specify only the fields you need.
|
|
16
17
|
- **Fast Compiled Regex Engine**: High-performance $O(1)$ `Map` lookups for static routes and single-pass compiled regex matching for dynamic routes.
|
|
17
18
|
- **Standard Schema Interoperability**: First-class validation for `body`, `query`, `params`, and `headers` using Zod, Valibot, or ArkType via Standard Schema (`validateSchema`).
|
|
18
19
|
- **Ultra-Low Latency SSE**: Built-in `c.sse()` streaming helper backed by native `TransformStream` and zero proxy buffering headers.
|
|
@@ -56,7 +57,6 @@ _Throughput evaluation when rate limiting is applied across static and wildcard
|
|
|
56
57
|
|
|
57
58
|
```bash
|
|
58
59
|
bun add fetchwork
|
|
59
|
-
|
|
60
60
|
```
|
|
61
61
|
|
|
62
62
|
---
|
|
@@ -101,7 +101,58 @@ export default {
|
|
|
101
101
|
|
|
102
102
|
## Usage Guide
|
|
103
103
|
|
|
104
|
-
### 1.
|
|
104
|
+
### 1. Type-Safe Generic Context
|
|
105
|
+
|
|
106
|
+
`Context` accepts a single optional generic object `{ body?, query?, params? }`. You can omit the generic completely (`c: Context`) or type only the parts your handler or middleware needs:
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
import { FetchWork, type Context } from "fetchwork";
|
|
110
|
+
import { z } from "zod";
|
|
111
|
+
|
|
112
|
+
const app = new FetchWork();
|
|
113
|
+
|
|
114
|
+
const CreateUserSchema = z.object({
|
|
115
|
+
name: z.string().min(2),
|
|
116
|
+
email: z.string().email(),
|
|
117
|
+
});
|
|
118
|
+
|
|
119
|
+
const SearchQuerySchema = z.object({
|
|
120
|
+
q: z.string().optional(),
|
|
121
|
+
limit: z.string().optional(),
|
|
122
|
+
});
|
|
123
|
+
|
|
124
|
+
// 1. Plain Context (no generics required)
|
|
125
|
+
app.get("/health", (c: Context) => {
|
|
126
|
+
return c.json({ ok: true });
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
// 2. Typing only `query`
|
|
130
|
+
app.get(
|
|
131
|
+
"/users",
|
|
132
|
+
(c: Context<{ query: z.infer<typeof SearchQuerySchema> }>) => {
|
|
133
|
+
const { q, limit } = c.query;
|
|
134
|
+
return c.json({ q, limit });
|
|
135
|
+
},
|
|
136
|
+
);
|
|
137
|
+
|
|
138
|
+
// 3. Typing `body`, `params`, and `headers` together
|
|
139
|
+
app.put(
|
|
140
|
+
"/tenants/:tenantId/users",
|
|
141
|
+
async (
|
|
142
|
+
c: Context<{
|
|
143
|
+
body: z.infer<typeof CreateUserSchema>;
|
|
144
|
+
params: { tenantId: string };
|
|
145
|
+
}>,
|
|
146
|
+
) => {
|
|
147
|
+
const { tenantId } = c.params;
|
|
148
|
+
const { name, email } = await c.reqBody();
|
|
149
|
+
|
|
150
|
+
return c.json({ tenantId, name, email });
|
|
151
|
+
},
|
|
152
|
+
);
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### 2. CORS Middleware
|
|
105
156
|
|
|
106
157
|
Apply CORS globally or per route using the built-in `cors` middleware:
|
|
107
158
|
|
|
@@ -122,7 +173,7 @@ app.use(
|
|
|
122
173
|
);
|
|
123
174
|
```
|
|
124
175
|
|
|
125
|
-
###
|
|
176
|
+
### 3. Multi-Level Rate Limiter
|
|
126
177
|
|
|
127
178
|
Protect specific static or wildcard paths with level-based penalty windows (`FloodWait`):
|
|
128
179
|
|
|
@@ -155,13 +206,17 @@ app.rateLimit(
|
|
|
155
206
|
);
|
|
156
207
|
```
|
|
157
208
|
|
|
158
|
-
###
|
|
209
|
+
### 4. Input Validation & API Docs (Standard Schema)
|
|
159
210
|
|
|
160
|
-
Validate incoming payloads with Zod, Valibot, or ArkType using `validateSchema
|
|
211
|
+
Validate incoming payloads with Zod, Valibot, or ArkType using `validateSchema`, and attach schemas to `document` for automatic OpenAPI / Swagger generation:
|
|
161
212
|
|
|
162
213
|
```typescript
|
|
163
214
|
import { z } from "zod";
|
|
215
|
+
import { FetchWork, type Context } from "fetchwork";
|
|
164
216
|
import { validateSchema } from "fetchwork/validator";
|
|
217
|
+
import { generateDocument } from "fetchwork/docs";
|
|
218
|
+
|
|
219
|
+
const app = new FetchWork();
|
|
165
220
|
|
|
166
221
|
const RegisterSchema = z.object({
|
|
167
222
|
name: z.string().min(2),
|
|
@@ -169,17 +224,33 @@ const RegisterSchema = z.object({
|
|
|
169
224
|
password: z.string().min(6),
|
|
170
225
|
});
|
|
171
226
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
227
|
+
type RegisterBody = z.infer<typeof RegisterSchema>;
|
|
228
|
+
|
|
229
|
+
app.post({
|
|
230
|
+
path: "/api/v1/register",
|
|
231
|
+
validator: validateSchema("body", RegisterSchema),
|
|
232
|
+
controller: async (c: Context<{ body: RegisterBody }>) => {
|
|
233
|
+
const payload = c.body;
|
|
177
234
|
return c.json({ success: true, data: payload }, 201);
|
|
178
235
|
},
|
|
236
|
+
document: {
|
|
237
|
+
tags: ["Auth"],
|
|
238
|
+
summary: "Register a new user",
|
|
239
|
+
body: RegisterSchema,
|
|
240
|
+
},
|
|
241
|
+
});
|
|
242
|
+
|
|
243
|
+
app.docs(
|
|
244
|
+
"/docs",
|
|
245
|
+
generateDocument({
|
|
246
|
+
type: "swagger",
|
|
247
|
+
title: "My API",
|
|
248
|
+
version: "1.0.0",
|
|
249
|
+
}),
|
|
179
250
|
);
|
|
180
251
|
```
|
|
181
252
|
|
|
182
|
-
###
|
|
253
|
+
### 5. Server-Sent Events (SSE)
|
|
183
254
|
|
|
184
255
|
Stream real-time updates seamlessly with non-blocking `c.sse()`:
|
|
185
256
|
|
|
@@ -254,8 +325,9 @@ export default serveCloudflare(app);
|
|
|
254
325
|
|
|
255
326
|
**Type Safety & DX**
|
|
256
327
|
|
|
328
|
+
- [x] **Generic Unified Context**: Optional object generic `Context<{ body, query, params }>` for full type-safety without boilerplate.
|
|
257
329
|
- [x] **Standard Schema Interoperability**: Validation support for `body`, `query`, `params`, and `headers` via `validateSchema()`.
|
|
258
|
-
- [x] **Route Parameter Inferencing**:
|
|
330
|
+
- [x] **Route Parameter Inferencing**: Typed route parameters via `c.params`.
|
|
259
331
|
|
|
260
332
|
**Streaming & Real-Time Utilities**
|
|
261
333
|
|
|
@@ -266,11 +338,11 @@ export default serveCloudflare(app);
|
|
|
266
338
|
|
|
267
339
|
- [x] **Built-in CORS Helper**: Optimized CORS middleware supporting static and $O(1)$ set matching.
|
|
268
340
|
- [x] **Multi-Level Rate Limiter**: Path-based `FloodWait` rate limiter (`app.rateLimit()`).
|
|
269
|
-
- [x] **OpenAPI / Swagger Generator**: Automatic OpenAPI doc generator reading route metadata and schemas.
|
|
341
|
+
- [x] **OpenAPI / Swagger Generator**: Automatic OpenAPI/Swagger doc generator reading route `document` metadata and schemas.
|
|
270
342
|
- [x] **Body Size Limits**: Memory protection for large `reqBody()` payloads.
|
|
271
343
|
|
|
272
344
|
---
|
|
273
345
|
|
|
274
346
|
## License
|
|
275
347
|
|
|
276
|
-
[MIT](
|
|
348
|
+
[MIT](./LICENSE) © Ayiin
|
package/package.json
CHANGED