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.
Files changed (2) hide show
  1. package/README.md +87 -15
  2. 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. CORS Middleware
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
- ### 2. Multi-Level Rate Limiter
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
- ### 3. Input Validation (Standard Schema)
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
- app.post(
173
- "/api/v1/register",
174
- validateSchema("body", RegisterSchema),
175
- async (c) => {
176
- const payload = c.validData?.body;
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
- ### 4. Server-Sent Events (SSE)
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**: Automatic type inferencing for `c.params`.
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](https://www.google.com/search?q=./LICENSE) © Ayiin
348
+ [MIT](./LICENSE) © Ayiin
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fetchwork",
3
- "version": "1.0.22",
3
+ "version": "1.0.23",
4
4
  "description": "An ultra-fast, lightweight, and type-safe web framework built on W3C Web Standards with multi-runtime adapter support.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",