refactor(fetch): implement immutable builder and full-cycle middleware

This commit introduces a major architectural refactoring of the  package to improve flexibility, safety, and developer experience.

Key changes include:

- **Immutable FetchBuilder**: The  is now immutable. Methods like  or  return a new cloned instance instead of mutating the existing one, preventing side effects and making the builder safer to reuse.

- **Full-Cycle Middleware**: A new middleware system based on the  pattern has been implemented. This allows middleware to inspect and modify both the request and the response, enabling features like logging, caching, and authentication.

- **Lazy Response Parsing**: The  now receives a function to parse the JSON body () instead of an already-resolved JSON object. This gives developers full control over the raw  object, allowing for conditional parsing and better error handling.

- **Intelligent Body Handling**: The request body serialization logic has been improved to automatically set the  header for JSON objects and pass other body types through unmodified.

Author: danpacho

README.md

@@ -16,7 +16,7 @@
         "bench": "pnpm --filter=\"benchmark\" start run",
         "start": "turbo run start",
         "clean": "turbo run clean",
-        "test": "vitest",
+        "test": "vitest --run",
         "test:watch": "vitest --watch -u",
         "test:coverage": "vitest run --coverage",
         "test:ci": "pnpm test:coverage && pnpm prettier && pnpm ts:typecheck && pnpm build",
@@ -56,7 +56,8 @@
         "turbo": "^2.3.3",
         "typescript": "^5.7.3",
         "vite-tsconfig-paths": "^5.1.4",
-        "vitest": "^3.0.0"
+        "vitest": "^3.0.0",
+        "@metal-box/type": "^0.2.0"
     },
     "engines": {
         "node": ">=20.0.0"

package.json

@@ -18,8 +18,5 @@
     "scripts": {
         "build": "tsup src/index.ts --format=cjs,esm --dts",
         "build:fast": "tsup src/index.ts --format=cjs,esm"
-    },
-    "devDependencies": {
-        "@metal-box/type": "^0.2.0"
     }
 }

packages/fetch/package.json

@@ -1,5 +1,5 @@
 import { MetalSchemaShape, t } from '@metal-box/type'
-import * as f from '../../index'
+import { type GetRouterConfig, f } from '../..'
 import { BASE_URL } from './constant'
 import { Model } from './model'
 
@@ -12,67 +12,69 @@ export const api = f.router(BASE_URL, {
     auth: {
         login: {
             GET: f
-                .unit()
+                .builder()
                 .def_json()
                 .def_default_referrer('about:client')
-                .def_response(({ json }) =>
-                    ApiResponse(t.union(t.string, t.undefined)).parse(json)
+                .def_response(async ({ json }) =>
+                    ApiResponse(t.union(t.string, t.undefined)).parse(
+                        await json()
+                    )
                 ),
         },
     },
     books: {
         GET: f
-            .unit()
+            .builder()
             .def_json()
             .def_default_referrer('about:client')
-            .def_response(({ json }) =>
-                ApiResponse(Model.bookList).parse(json)
+            .def_response(async ({ json }) =>
+                ApiResponse(Model.bookList).parse(await json())
             ),
         POST: f
-            .unit()
+            .builder()
             .def_json()
             .def_default_referrer('about:client')
             .def_body(Model.bookRequest.parse)
-            .def_response(({ json }) => {
-                const parsed = ApiResponse(Model.book).parse(json)
+            .def_response(async ({ json }) => {
+                const parsed = ApiResponse(Model.book).parse(await json())
                 return parsed
             }),
         $id: {
             GET: f
-                .unit()
+                .builder()
                 .def_json()
                 .def_default_referrer('about:client')
                 .def_response(async ({ json }) => {
-                    return ApiResponse(Model.book).parse(json)
+                    return ApiResponse(Model.book).parse(await json())
                 }),
             PUT: f
-                .unit()
+                .builder()
                 .def_json()
                 .def_default_referrer('about:client')
                 .def_body(Model.bookRequest.parse)
-                .def_response(({ json }) =>
-                    ApiResponse(Model.book).parse(json)
+                .def_response(async ({ json }) =>
+                    ApiResponse(Model.book).parse(await json())
                 ),
             DELETE: f
-                .unit()
+                .builder()
                 .def_json()
                 .def_default_referrer('about:client')
-                .def_response(({ json }) =>
-                    ApiResponse(Model.book).parse(json)
+                .def_response(async ({ json }) =>
+                    ApiResponse(Model.book).parse(await json())
                 ),
         },
     },
     category: {
         $name: {
             GET: f
-                .unit()
+                .builder()
                 .def_json()
                 .def_default_referrer('about:client')
-                .def_response(({ json }) => {
-                    return ApiResponse(Model.bookList).parse(json)
+                .def_response(async ({ json }) => {
+                    return ApiResponse(Model.bookList).parse(await json())
                 }),
         },
     },
 })
 
-export type BookApi = f.GetRouterConfig<typeof api>
+export type BookApi = GetRouterConfig<typeof api>

packages/fetch/src/__tests__/__mocks__/client.ts

@@ -132,7 +132,7 @@ class BookServer {
         header: Headers,
         data: (authId: UUID) => T,
         skipAuth: boolean = false
-    ): HttpResponse {
+    ): HttpResponse<any> {
         if (skipAuth) {
             return HttpResponse.json(
                 {

packages/fetch/src/__tests__/__mocks__/server.ts

@@ -1,5 +1,5 @@
 import { setupServer } from 'msw/node'
-import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import { api } from './__mocks__/client'
 import {
     type BookModel,
@@ -14,7 +14,6 @@ const apiServer = setupServer(...bookServer.routes)
 
 beforeAll(() => apiServer.listen({ onUnhandledRequest: 'error' }))
 afterAll(() => apiServer.close())
-afterEach(() => apiServer.resetHandlers())
 // ---------------------------------------------------- //
 
 describe(label.unit('router api request'), () => {

packages/fetch/src/__tests__/build.router.test.ts

@@ -0,0 +1,82 @@
+import { t } from '@metal-box/type'
+import { describe, expect, it, vi } from 'vitest'
+import { f } from '..'
+import { FetchBuilder } from '../core/fetcher'
+import { FetchUnit } from '../core/fetcher/unit'
+
+describe('FetchBuilder', () => {
+    it('should create a new FetchBuilder instance', () => {
+        const b = f.builder()
+        expect(b).toBeInstanceOf(FetchBuilder)
+    })
+
+    it('should set the method', () => {
+        const b = f.builder().def_method('POST')
+        expect(b.$store.method).toBe('POST')
+    })
+
+    it('should set the base URL', () => {
+        const url = 'https://api.test.com'
+        const b = f.builder().def_url(url)
+        expect(b.$store.defaultUrl).toBe(url)
+    })
+
+    it('should set json mode', () => {
+        const b = f.builder().def_json()
+        expect(b.isJsonMode).toBe(true)
+    })
+
+    it('should build a FetchUnit', () => {
+        const unit = f.builder().build()
+        expect(unit).toBeInstanceOf(FetchUnit)
+    })
+
+    it('should define a body validator', () => {
+        const bodySchema = t.object({ name: t.string })
+        const b = f.builder().def_body(bodySchema.parse)
+        const testBody = { name: 'test' }
+        expect(b.bodyValidator(testBody)).toEqual(testBody)
+        expect(() => b.bodyValidator({ name: 123 })).toThrow()
+    })
+
+    it('should be immutable', () => {
+        const originalBuilder = f
+            .builder()
+            .def_method('GET')
+            .def_url('https://a.com')
+        const modifiedBuilder = originalBuilder.def_method('POST')
+
+        expect(originalBuilder.$store.method).toBe('GET')
+        expect(modifiedBuilder.$store.method).toBe('POST')
+        expect(originalBuilder.$store.defaultUrl).toBe('https://a.com')
+        expect(modifiedBuilder.$store.defaultUrl).toBe('https://a.com')
+    })
+
+    it('should handle request handler modification', async () => {
+        const fetchUnit = f
+            .builder()
+            .def_url('https://api.com')
+            .def_request_handler(({ request }) => {
+                if (request instanceof Request) {
+                    request.headers.set('X-Test', 'true')
+                }
+                return request
+            })
+            .build()
+
+        const mockFetch = vi
+            .spyOn(global, 'fetch')
+            .mockImplementation(async (req) => {
+                if (req instanceof Request) {
+                    expect(req.headers.get('X-Test')).toBe('true')
+                } else {
+                    throw new Error('Expected a Request object')
+                }
+                return new Response('OK')
+            })
+
+        await fetchUnit.query()
+        expect(mockFetch).toHaveBeenCalledOnce()
+        mockFetch.mockRestore()
+    })
+})

packages/fetch/src/__tests__/builder.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest'
+import { f } from '..'
+
+describe('Middleware Integration', () => {
+    it('should run middleware and modify request headers', async () => {
+        const TOKEN = 'token'
+        const middleware = new f.Middleware()
+
+        middleware.use(async (req, next) => {
+            req.headers.set('Authorization', TOKEN)
+            return next(req)
+        })
+
+        const fetchBuilder = f
+            .builder()
+            .def_method('GET')
+            .def_url('https://api.com')
+            .def_middleware(middleware.procedures[0]!)
+
+        const fetchUnit = fetchBuilder.build()
+
+        const mockFetch = vi
+            .spyOn(global, 'fetch')
+            .mockImplementation(async (req) => {
+                if (req instanceof Request) {
+                    expect(req.headers.get('Authorization')).toBe(TOKEN)
+                } else {
+                    throw new Error('Expected a Request object')
+                }
+                return new Response('OK', { status: 200 })
+            })
+
+        await fetchUnit.query()
+
+        expect(mockFetch).toHaveBeenCalledOnce()
+        mockFetch.mockRestore()
+    })
+
+    it('should run middleware and modify the response', async () => {
+        const middleware = new f.Middleware()
+
+        middleware.use(async (req, next) => {
+            const response = await next(req)
+            response.headers.set('X-Middleware-Handled', 'true')
+            return response
+        })
+
+        const fetchUnit = f
+            .builder()
+            .def_method('GET')
+            .def_url('https://api.com')
+            .def_middleware(middleware.procedures[0]!)
+            .def_response(async ({ response }) => {
+                expect(response.headers.get('X-Middleware-Handled')).toBe(
+                    'true'
+                )
+                return response.text()
+            })
+            .build()
+
+        const mockFetch = vi
+            .spyOn(global, 'fetch')
+            .mockImplementation(async () => new Response('OK'))
+
+        await fetchUnit.query()
+        expect(mockFetch).toHaveBeenCalledOnce()
+        mockFetch.mockRestore()
+    })
+})

packages/fetch/src/__tests__/middleware.integration.test.ts

@@ -1,41 +1,36 @@
 import { describe, expect, it } from 'vitest'
-import { Middleware } from '../utils/middleware'
+import { f } from '..'
 import { label } from './utils/test.label'
 
 describe(label.unit('middleware'), () => {
-    it(label.case('should add middleware'), () => {
-        const middleware = new Middleware<{ counter: number }, { b: string }>()
+    it(label.case('should execute middleware in order'), async () => {
+        const middleware = new f.Middleware()
+        const executionOrder: number[] = []
 
-        let counter = 0
-        middleware.use([
-            ({ next }) => {
-                counter++
+        middleware.use(async (req, next) => {
+            executionOrder.push(1)
+            const response = await next(req)
+            executionOrder.push(6)
+            return response
+        })
 
-                next({
-                    req: { counter },
-                })
-            },
-            ({ next }) => {
-                counter++
+        middleware.use(async (req, next) => {
+            executionOrder.push(2)
+            const response = await next(req)
+            executionOrder.push(5)
+            return response
+        })
 
-                next({
-                    req: { counter },
-                    res: {
-                        b: 'love',
-                    },
-                })
-            },
-            ({ next }) => {
-                counter++
+        middleware.use(async (req, next) => {
+            executionOrder.push(3)
+            const response = await next(req)
+            executionOrder.push(4)
+            return response
+        })
 
-                next({
-                    req: { counter },
-                })
-            },
-        ])
+        const mockFetcher = async (req: Request) => new Response('ok')
+        await middleware.execute(new Request('https://test.com'), mockFetcher)
 
-        middleware.execute({ counter }, { b: '2' })
-
-        expect(counter).toBe(3)
+        expect(executionOrder).toEqual([1, 2, 3, 4, 5, 6])
     })
 })