react-router-define-api 0.1.4 → 0.1.6

package/README.md

@@ -31,41 +31,137 @@ export const { loader, action } = defineApi({
 });
 ```
 
+### Builder API
+
+Prefer a fluent style? Call `defineApi()` with no arguments to get a chainable builder:
+
+```ts
+import { defineApi } from 'react-router-define-api';
+
+export const { loader, action } = defineApi()
+  .middleware([auth, logger])
+  .get(async ({ params }) => {
+    return { user: await db.users.find(params.id) };
+  })
+  .post(async ({ request }) => {
+    const body = await request.formData();
+    return { user: await db.users.create({ name: body.get('name') }) };
+  })
+  .delete(async ({ params }) => {
+    await db.users.delete(params.id);
+    return { deleted: true };
+  })
+  .build();
+```
+
+Available methods: `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.middleware()`, `.build()`. Each accepts plain functions or validated handler configs:
+
+```ts
+export const { loader, action } = defineApi()
+  .middleware([auth, logger])
+  .get({
+    params: z.object({ id: z.string().uuid() }),
+    handler: async ({ params }) => {
+      return { user: await db.users.find(params.id) };
+    },
+  })
+  .post({
+    body: z.object({ name: z.string() }),
+    handler: async ({ body }) => {
+      return { user: await db.users.create(body) };
+    },
+  })
+  .delete({
+    params: z.object({ id: z.string() }),
+    handler: async ({ params }) => {
+      await db.users.delete(params.id);
+      return { deleted: true };
+    },
+  })
+  .build();
+```
+
 ### How it works
 
 - `GET` → `loader`
 - `POST`, `PUT`, `PATCH`, `DELETE` → dispatched inside `action` by `request.method`
 - Undefined methods → `405 Method Not Allowed`
 
-### Handler wrapper
+### Middleware
 
-Wrap all handlers with a higher-order function for error handling, response transformation, logging, etc.:
+Add middleware that runs before every handler. Middleware uses the onion model — call `next()` to proceed, or return early to short-circuit.
 
 ```ts
+import type { MiddlewareFn } from 'react-router-define-api';
+
+const auth: MiddlewareFn = async (args, next) => {
+  const token = args.request.headers.get('Authorization');
+  if (!token) {
+    throw new Response('Unauthorized', { status: 401 });
+  }
+  return next();
+};
+
+const logger: MiddlewareFn = async (args, next) => {
+  console.log(`${args.request.method} ${args.request.url}`);
+  return next();
+};
+
 export const { loader, action } = defineApi({
-  GET: async () => ({ name: 'John' }),
+  middleware: [auth, logger],
+  GET: async ({ params }) => ({ user: params.id }),
   POST: async ({ request }) => {
     const body = await request.formData();
-    return { name: body.get('name') };
+    return { created: true };
   },
-}, {
-  handler: loaderActionHandler,
 });
 ```
 
-Example `loaderActionHandler`:
+Middleware executes in array order. Each middleware can:
+
+- **Pass through** — call `next()` and return its result
+- **Short-circuit** — return a value without calling `next()`
+- **Transform** — call `next()`, modify the result, then return it
+
+### Request validation
+
+Validate params and body using any schema library with a `.parse()` method (Zod, Valibot, ArkType, etc.). Pass a handler config object instead of a plain function:
 
 ```ts
-const loaderActionHandler = (fn) => async (args) => {
-  try {
-    const result = await fn(args);
-    return { success: true, status: 200, data: result };
-  } catch (error) {
-    return { success: false, status: 500, message: String(error) };
-  }
-};
+import { z } from 'zod';
+
+export const { loader, action } = defineApi({
+  GET: {
+    params: z.object({ id: z.string().uuid() }),
+    handler: async ({ params }) => {
+      return { user: await db.users.find(params.id) };
+    },
+  },
+  POST: {
+    body: z.object({ name: z.string(), email: z.string().email() }),
+    handler: async ({ body }) => {
+      return { user: await db.users.create(body) };
+    },
+  },
+  PUT: {
+    params: z.object({ id: z.string() }),
+    body: z.object({ name: z.string() }),
+    handler: async ({ params, body }) => {
+      return { user: await db.users.update(params.id, body) };
+    },
+  },
+});
 ```
 
+- **`params`** — validates `args.params` (route path parameters)
+- **`body`** — auto-parses the request body based on `Content-Type`, then validates:
+  - `application/json` → `request.json()`
+  - `application/x-www-form-urlencoded` / `multipart/form-data` → `request.formData()`
+  - `text/*` → `request.text()`
+  - Other → `415 Unsupported Media Type`
+- Validation failure → `400` response with error details
+- Plain functions and handler configs can be mixed in the same `defineApi` call
+
 ### Response type helpers
 
 Access inferred response types for client-side fetchers or shared contracts:

package/dist/index.cjs

@@ -20,10 +20,71 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ApiBuilder: () => ApiBuilder,
   defineApi: () => defineApi
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/api-builder.ts
+var ApiBuilder = class _ApiBuilder {
+  handlers;
+  constructor(handlers = {}) {
+    this.handlers = handlers;
+  }
+  /** Add middleware that runs before every handler */
+  middleware(fns) {
+    return new _ApiBuilder({
+      ...this.handlers,
+      middleware: [...this.handlers.middleware ?? [], ...fns]
+    });
+  }
+  /** Define the GET handler (becomes the loader) */
+  get(handler) {
+    return new _ApiBuilder({ ...this.handlers, GET: handler });
+  }
+  /** Define the POST handler */
+  post(handler) {
+    return new _ApiBuilder({ ...this.handlers, POST: handler });
+  }
+  /** Define the PUT handler */
+  put(handler) {
+    return new _ApiBuilder({ ...this.handlers, PUT: handler });
+  }
+  /** Define the PATCH handler */
+  patch(handler) {
+    return new _ApiBuilder({ ...this.handlers, PATCH: handler });
+  }
+  /** Define the DELETE handler */
+  delete(handler) {
+    return new _ApiBuilder({
+      ...this.handlers,
+      DELETE: handler
+    });
+  }
+  /** Build and return { loader, action } with response type helpers */
+  build() {
+    return _ApiBuilder._buildFn(this.handlers);
+  }
+  /** @internal — set by define-api.ts to wire up the build logic */
+  static _buildFn;
+};
+
+// src/parse-body.ts
+async function parseBody(request) {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return request.json();
+  }
+  if (contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data")) {
+    const formData = await request.formData();
+    return Object.fromEntries(formData);
+  }
+  if (contentType.includes("text/")) {
+    return request.text();
+  }
+  throw new Response("Unsupported Media Type", { status: 415 });
+}
+
 // src/define-api.ts
 var ACTION_METHODS = [
   "POST",
@@ -31,24 +92,85 @@ var ACTION_METHODS = [
   "PATCH",
   "DELETE"
 ];
-function defineApi(handlers, options) {
-  const { handler: wrapper } = options ?? {};
-  const wrap = (fn) => wrapper ? wrapper(fn) : fn;
-  const loader = handlers.GET ? wrap(handlers.GET) : void 0;
+function isHandlerDef(entry) {
+  return typeof entry === "object" && "handler" in entry;
+}
+function runMiddleware(middleware, args, handler) {
+  let index = 0;
+  const next = async () => {
+    if (index < middleware.length) {
+      return middleware[index++](args, next);
+    }
+    return handler(args);
+  };
+  return next();
+}
+function wrapWithValidation(entry) {
+  if (!isHandlerDef(entry)) return entry;
+  const { params: paramsSchema, body: bodySchema, handler } = entry;
+  return async (args) => {
+    let validatedParams = args.params;
+    if (paramsSchema) {
+      try {
+        validatedParams = paramsSchema.parse(args.params);
+      } catch (error) {
+        throw new Response(
+          JSON.stringify({ error: "Validation failed", details: error }),
+          { status: 400, headers: { "content-type": "application/json" } }
+        );
+      }
+    }
+    let body;
+    if (bodySchema) {
+      const raw = await parseBody(args.request);
+      try {
+        body = bodySchema.parse(raw);
+      } catch (error) {
+        throw new Response(
+          JSON.stringify({ error: "Validation failed", details: error }),
+          { status: 400, headers: { "content-type": "application/json" } }
+        );
+      }
+    }
+    const handlerArgs = {
+      ...args,
+      params: validatedParams,
+      ...bodySchema ? { body } : {}
+    };
+    return handler(handlerArgs);
+  };
+}
+function buildExports(handlers) {
+  const mw = handlers.middleware ?? [];
+  const getEntry = handlers.GET;
+  const getHandler = getEntry ? wrapWithValidation(getEntry) : void 0;
+  const loader = getHandler ? mw.length > 0 ? (args) => runMiddleware(mw, args, getHandler) : getHandler : void 0;
   const hasActionHandlers = ACTION_METHODS.some(
     (m) => handlers[m] != null
   );
-  const action = hasActionHandlers ? wrap(async (args) => {
+  const action = hasActionHandlers ? async (args) => {
     const method = args.request.method.toUpperCase();
-    const handler = handlers[method];
-    if (typeof handler === "function") {
-      return handler(args);
+    const entry = handlers[method];
+    if (entry == null) {
+      throw new Response("Method Not Allowed", { status: 405 });
     }
-    throw new Response("Method Not Allowed", { status: 405 });
-  }) : void 0;
+    const handler = wrapWithValidation(entry);
+    if (mw.length > 0) {
+      return runMiddleware(mw, args, handler);
+    }
+    return handler(args);
+  } : void 0;
   return { loader, action };
 }
+ApiBuilder._buildFn = buildExports;
+function defineApi(handlers) {
+  if (handlers === void 0) {
+    return new ApiBuilder();
+  }
+  return buildExports(handlers);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ApiBuilder,
   defineApi
 });

package/dist/index.d.cts

@@ -4,16 +4,35 @@ import { LoaderFunctionArgs, ActionFunctionArgs } from 'react-router';
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /** Handler function for a given HTTP method */
 type MethodHandler<Args, R = unknown> = (args: Args) => R | Promise<R>;
+/** Route handler args (union of loader and action args) */
+type HandlerArgs = LoaderFunctionArgs | ActionFunctionArgs;
+/** Middleware function — call next() to proceed, or return early to short-circuit */
+type MiddlewareFn = (args: HandlerArgs, next: () => Promise<unknown>) => unknown | Promise<unknown>;
+/** Generic schema interface — works with Zod, Valibot, ArkType, etc. */
+interface Schema<T = unknown> {
+    parse(input: unknown): T;
+}
+/** Handler definition with optional validation schemas */
+interface HandlerDef {
+    params?: Schema;
+    body?: Schema;
+    handler: (args: HandlerArgs & {
+        body?: unknown;
+    }) => unknown;
+}
 /** Map of HTTP method handlers passed to defineApi */
 type ApiHandlers = {
-    GET?: (args: LoaderFunctionArgs) => unknown;
-    POST?: (args: ActionFunctionArgs) => unknown;
-    PUT?: (args: ActionFunctionArgs) => unknown;
-    PATCH?: (args: ActionFunctionArgs) => unknown;
-    DELETE?: (args: ActionFunctionArgs) => unknown;
+    middleware?: MiddlewareFn[];
+    GET?: ((args: LoaderFunctionArgs) => unknown) | HandlerDef;
+    POST?: ((args: ActionFunctionArgs) => unknown) | HandlerDef;
+    PUT?: ((args: ActionFunctionArgs) => unknown) | HandlerDef;
+    PATCH?: ((args: ActionFunctionArgs) => unknown) | HandlerDef;
+    DELETE?: ((args: ActionFunctionArgs) => unknown) | HandlerDef;
 };
-/** Extract the awaited return type from a handler */
-type HandlerReturn<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+/** Extract the awaited return type from a handler (plain function or config) */
+type HandlerReturn<T> = T extends (...args: never[]) => infer R ? Awaited<R> : T extends {
+    handler: (...args: never[]) => infer R;
+} ? Awaited<R> : never;
 /** Checks if handler map includes any action methods */
 type HasActionMethods<H> = 'POST' extends keyof H ? true : 'PUT' extends keyof H ? true : 'PATCH' extends keyof H ? true : 'DELETE' extends keyof H ? true : false;
 /** Build union return type from all defined action handlers */
@@ -28,73 +47,92 @@ type ActionReturn<H> = (H extends {
 } ? HandlerReturn<F> : never);
 /** Extract response type for a specific method, or never if not defined */
 type ResponseOf<H, M extends HttpMethod> = H extends Record<M, infer F> ? HandlerReturn<F> : never;
-/**
- * Higher-order function that wraps each method handler.
- * Receives the original handler and returns a new handler with transformed behavior.
- *
- * @example
- * ```ts
- * const loaderActionHandler: HandlerWrapper<BaseResponse<unknown>> =
- *   (fn) => async (args) => {
- *     try {
- *       const result = await fn(args);
- *       return { success: true, status: 200, data: result };
- *     } catch (error) {
- *       return { success: false, status: 500, message: String(error) };
- *     }
- *   };
- * ```
- */
-type HandlerWrapper<W = unknown> = (fn: (...args: any[]) => any) => (...args: any[]) => Promise<W>;
-/** Options for defineApi */
-interface DefineApiOptions<W = never> {
-    /** Higher-order function to wrap all method handlers (e.g. for error handling, response transformation) */
-    handler?: HandlerWrapper<W>;
-}
-/** Apply wrapper type: if wrapper is provided, use its return type; otherwise use the raw handler return */
-type WithWrapper<R, W> = [W] extends [never] ? R : Awaited<W>;
 /** Return type of defineApi — loader/action presence and return types inferred from handlers */
-type ApiExports<H extends ApiHandlers, W = never> = {
+type ApiExports<H extends ApiHandlers> = {
     loader: H extends {
         GET: infer F;
-    } ? (args: LoaderFunctionArgs) => Promise<WithWrapper<HandlerReturn<F>, W>> : undefined;
-    action: HasActionMethods<H> extends true ? (args: ActionFunctionArgs) => Promise<WithWrapper<ActionReturn<H>, W>> : undefined;
+    } ? (args: LoaderFunctionArgs) => Promise<HandlerReturn<F>> : undefined;
+    action: HasActionMethods<H> extends true ? (args: ActionFunctionArgs) => Promise<ActionReturn<H>> : undefined;
     /** Inferred return type of the GET handler */
-    GetResponse: WithWrapper<ResponseOf<H, 'GET'>, W>;
+    GetResponse: ResponseOf<H, 'GET'>;
     /** Inferred return type of the POST handler */
-    PostResponse: WithWrapper<ResponseOf<H, 'POST'>, W>;
+    PostResponse: ResponseOf<H, 'POST'>;
     /** Inferred return type of the PUT handler */
-    PutResponse: WithWrapper<ResponseOf<H, 'PUT'>, W>;
+    PutResponse: ResponseOf<H, 'PUT'>;
     /** Inferred return type of the PATCH handler */
-    PatchResponse: WithWrapper<ResponseOf<H, 'PATCH'>, W>;
+    PatchResponse: ResponseOf<H, 'PATCH'>;
     /** Inferred return type of the DELETE handler */
-    DeleteResponse: WithWrapper<ResponseOf<H, 'DELETE'>, W>;
+    DeleteResponse: ResponseOf<H, 'DELETE'>;
 };
 
+/** Loader handler — plain function or validated config */
+type LoaderEntry = ((args: LoaderFunctionArgs) => unknown) | HandlerDef;
+/** Action handler — plain function or validated config */
+type ActionEntry = ((args: ActionFunctionArgs) => unknown) | HandlerDef;
 /**
- * Define HTTP method handlers for a React Router v7 route.
- * Returns `{ loader, action }` ready to export from a route module.
+ * Fluent builder for defining HTTP method handlers.
+ * Each method returns a new builder with updated type state.
  *
  * @example
  * ```ts
+ * const api = new ApiBuilder()
+ *   .get(async ({ params }) => ({ user: params.id }))
+ *   .post(async ({ request }) => ({ created: true }))
+ *   .build();
+ * export const { loader, action } = api;
+ * ```
+ */
+declare class ApiBuilder<H extends ApiHandlers = object> {
+    private handlers;
+    constructor(handlers?: ApiHandlers);
+    /** Add middleware that runs before every handler */
+    middleware(fns: MiddlewareFn[]): ApiBuilder<H>;
+    /** Define the GET handler (becomes the loader) */
+    get<F extends LoaderEntry>(handler: F): ApiBuilder<H & {
+        GET: F;
+    }>;
+    /** Define the POST handler */
+    post<F extends ActionEntry>(handler: F): ApiBuilder<H & {
+        POST: F;
+    }>;
+    /** Define the PUT handler */
+    put<F extends ActionEntry>(handler: F): ApiBuilder<H & {
+        PUT: F;
+    }>;
+    /** Define the PATCH handler */
+    patch<F extends ActionEntry>(handler: F): ApiBuilder<H & {
+        PATCH: F;
+    }>;
+    /** Define the DELETE handler */
+    delete<F extends ActionEntry>(handler: F): ApiBuilder<H & {
+        DELETE: F;
+    }>;
+    /** Build and return { loader, action } with response type helpers */
+    build(): ApiExports<H>;
+    /** @internal — set by define-api.ts to wire up the build logic */
+    static _buildFn: (handlers: ApiHandlers) => unknown;
+}
+
+/**
+ * Define HTTP method handlers for a React Router v7 route.
+ *
+ * **Object style** — pass all handlers at once:
+ * ```ts
  * export const { loader, action } = defineApi({
  *   GET: async ({ params }) => ({ user: params.id }),
- *   POST: async ({ request }) => {
- *     const body = await request.formData();
- *     return { created: true };
- *   },
+ *   POST: async ({ request }) => ({ created: true }),
  * });
  * ```
  *
- * @example With handler wrapper
+ * **Builder style** — chain methods fluently:
  * ```ts
- * export const { loader, action } = defineApi({
- *   GET: async () => ({ data: 'ok' }),
- * }, {
- *   handler: loaderActionHandler,
- * });
+ * export const { loader, action } = defineApi()
+ *   .get(async ({ params }) => ({ user: params.id }))
+ *   .post(async ({ request }) => ({ created: true }))
+ *   .build();
  * ```
  */
-declare function defineApi<const H extends ApiHandlers, W = never>(handlers: H, options?: DefineApiOptions<W>): ApiExports<H, W>;
+declare function defineApi(): ApiBuilder;
+declare function defineApi<const H extends ApiHandlers>(handlers: H): ApiExports<H>;
 
-export { type ApiHandlers, type DefineApiOptions, type HandlerWrapper, type HttpMethod, type MethodHandler, defineApi };
+export { ApiBuilder, type ApiHandlers, type HandlerArgs, type HandlerDef, type HttpMethod, type MethodHandler, type MiddlewareFn, type Schema, defineApi };

package/dist/index.d.ts

@@ -4,16 +4,35 @@ import { LoaderFunctionArgs, ActionFunctionArgs } from 'react-router';
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 /** Handler function for a given HTTP method */
 type MethodHandler<Args, R = unknown> = (args: Args) => R | Promise<R>;
+/** Route handler args (union of loader and action args) */
+type HandlerArgs = LoaderFunctionArgs | ActionFunctionArgs;
+/** Middleware function — call next() to proceed, or return early to short-circuit */
+type MiddlewareFn = (args: HandlerArgs, next: () => Promise<unknown>) => unknown | Promise<unknown>;
+/** Generic schema interface — works with Zod, Valibot, ArkType, etc. */
+interface Schema<T = unknown> {
+    parse(input: unknown): T;
+}
+/** Handler definition with optional validation schemas */
+interface HandlerDef {
+    params?: Schema;
+    body?: Schema;
+    handler: (args: HandlerArgs & {
+        body?: unknown;
+    }) => unknown;
+}
 /** Map of HTTP method handlers passed to defineApi */
 type ApiHandlers = {
-    GET?: (args: LoaderFunctionArgs) => unknown;
-    POST?: (args: ActionFunctionArgs) => unknown;
-    PUT?: (args: ActionFunctionArgs) => unknown;
-    PATCH?: (args: ActionFunctionArgs) => unknown;
-    DELETE?: (args: ActionFunctionArgs) => unknown;
+    middleware?: MiddlewareFn[];
+    GET?: ((args: LoaderFunctionArgs) => unknown) | HandlerDef;
+    POST?: ((args: ActionFunctionArgs) => unknown) | HandlerDef;
+    PUT?: ((args: ActionFunctionArgs) => unknown) | HandlerDef;
+    PATCH?: ((args: ActionFunctionArgs) => unknown) | HandlerDef;
+    DELETE?: ((args: ActionFunctionArgs) => unknown) | HandlerDef;
 };
-/** Extract the awaited return type from a handler */
-type HandlerReturn<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+/** Extract the awaited return type from a handler (plain function or config) */
+type HandlerReturn<T> = T extends (...args: never[]) => infer R ? Awaited<R> : T extends {
+    handler: (...args: never[]) => infer R;
+} ? Awaited<R> : never;
 /** Checks if handler map includes any action methods */
 type HasActionMethods<H> = 'POST' extends keyof H ? true : 'PUT' extends keyof H ? true : 'PATCH' extends keyof H ? true : 'DELETE' extends keyof H ? true : false;
 /** Build union return type from all defined action handlers */
@@ -28,73 +47,92 @@ type ActionReturn<H> = (H extends {
 } ? HandlerReturn<F> : never);
 /** Extract response type for a specific method, or never if not defined */
 type ResponseOf<H, M extends HttpMethod> = H extends Record<M, infer F> ? HandlerReturn<F> : never;
-/**
- * Higher-order function that wraps each method handler.
- * Receives the original handler and returns a new handler with transformed behavior.
- *
- * @example
- * ```ts
- * const loaderActionHandler: HandlerWrapper<BaseResponse<unknown>> =
- *   (fn) => async (args) => {
- *     try {
- *       const result = await fn(args);
- *       return { success: true, status: 200, data: result };
- *     } catch (error) {
- *       return { success: false, status: 500, message: String(error) };
- *     }
- *   };
- * ```
- */
-type HandlerWrapper<W = unknown> = (fn: (...args: any[]) => any) => (...args: any[]) => Promise<W>;
-/** Options for defineApi */
-interface DefineApiOptions<W = never> {
-    /** Higher-order function to wrap all method handlers (e.g. for error handling, response transformation) */
-    handler?: HandlerWrapper<W>;
-}
-/** Apply wrapper type: if wrapper is provided, use its return type; otherwise use the raw handler return */
-type WithWrapper<R, W> = [W] extends [never] ? R : Awaited<W>;
 /** Return type of defineApi — loader/action presence and return types inferred from handlers */
-type ApiExports<H extends ApiHandlers, W = never> = {
+type ApiExports<H extends ApiHandlers> = {
     loader: H extends {
         GET: infer F;
-    } ? (args: LoaderFunctionArgs) => Promise<WithWrapper<HandlerReturn<F>, W>> : undefined;
-    action: HasActionMethods<H> extends true ? (args: ActionFunctionArgs) => Promise<WithWrapper<ActionReturn<H>, W>> : undefined;
+    } ? (args: LoaderFunctionArgs) => Promise<HandlerReturn<F>> : undefined;
+    action: HasActionMethods<H> extends true ? (args: ActionFunctionArgs) => Promise<ActionReturn<H>> : undefined;
     /** Inferred return type of the GET handler */
-    GetResponse: WithWrapper<ResponseOf<H, 'GET'>, W>;
+    GetResponse: ResponseOf<H, 'GET'>;
     /** Inferred return type of the POST handler */
-    PostResponse: WithWrapper<ResponseOf<H, 'POST'>, W>;
+    PostResponse: ResponseOf<H, 'POST'>;
     /** Inferred return type of the PUT handler */
-    PutResponse: WithWrapper<ResponseOf<H, 'PUT'>, W>;
+    PutResponse: ResponseOf<H, 'PUT'>;
     /** Inferred return type of the PATCH handler */
-    PatchResponse: WithWrapper<ResponseOf<H, 'PATCH'>, W>;
+    PatchResponse: ResponseOf<H, 'PATCH'>;
     /** Inferred return type of the DELETE handler */
-    DeleteResponse: WithWrapper<ResponseOf<H, 'DELETE'>, W>;
+    DeleteResponse: ResponseOf<H, 'DELETE'>;
 };
 
+/** Loader handler — plain function or validated config */
+type LoaderEntry = ((args: LoaderFunctionArgs) => unknown) | HandlerDef;
+/** Action handler — plain function or validated config */
+type ActionEntry = ((args: ActionFunctionArgs) => unknown) | HandlerDef;
 /**
- * Define HTTP method handlers for a React Router v7 route.
- * Returns `{ loader, action }` ready to export from a route module.
+ * Fluent builder for defining HTTP method handlers.
+ * Each method returns a new builder with updated type state.
  *
  * @example
  * ```ts
+ * const api = new ApiBuilder()
+ *   .get(async ({ params }) => ({ user: params.id }))
+ *   .post(async ({ request }) => ({ created: true }))
+ *   .build();
+ * export const { loader, action } = api;
+ * ```
+ */
+declare class ApiBuilder<H extends ApiHandlers = object> {
+    private handlers;
+    constructor(handlers?: ApiHandlers);
+    /** Add middleware that runs before every handler */
+    middleware(fns: MiddlewareFn[]): ApiBuilder<H>;
+    /** Define the GET handler (becomes the loader) */
+    get<F extends LoaderEntry>(handler: F): ApiBuilder<H & {
+        GET: F;
+    }>;
+    /** Define the POST handler */
+    post<F extends ActionEntry>(handler: F): ApiBuilder<H & {
+        POST: F;
+    }>;
+    /** Define the PUT handler */
+    put<F extends ActionEntry>(handler: F): ApiBuilder<H & {
+        PUT: F;
+    }>;
+    /** Define the PATCH handler */
+    patch<F extends ActionEntry>(handler: F): ApiBuilder<H & {
+        PATCH: F;
+    }>;
+    /** Define the DELETE handler */
+    delete<F extends ActionEntry>(handler: F): ApiBuilder<H & {
+        DELETE: F;
+    }>;
+    /** Build and return { loader, action } with response type helpers */
+    build(): ApiExports<H>;
+    /** @internal — set by define-api.ts to wire up the build logic */
+    static _buildFn: (handlers: ApiHandlers) => unknown;
+}
+
+/**
+ * Define HTTP method handlers for a React Router v7 route.
+ *
+ * **Object style** — pass all handlers at once:
+ * ```ts
  * export const { loader, action } = defineApi({
  *   GET: async ({ params }) => ({ user: params.id }),
- *   POST: async ({ request }) => {
- *     const body = await request.formData();
- *     return { created: true };
- *   },
+ *   POST: async ({ request }) => ({ created: true }),
  * });
  * ```
  *
- * @example With handler wrapper
+ * **Builder style** — chain methods fluently:
  * ```ts
- * export const { loader, action } = defineApi({
- *   GET: async () => ({ data: 'ok' }),
- * }, {
- *   handler: loaderActionHandler,
- * });
+ * export const { loader, action } = defineApi()
+ *   .get(async ({ params }) => ({ user: params.id }))
+ *   .post(async ({ request }) => ({ created: true }))
+ *   .build();
  * ```
  */
-declare function defineApi<const H extends ApiHandlers, W = never>(handlers: H, options?: DefineApiOptions<W>): ApiExports<H, W>;
+declare function defineApi(): ApiBuilder;
+declare function defineApi<const H extends ApiHandlers>(handlers: H): ApiExports<H>;
 
-export { type ApiHandlers, type DefineApiOptions, type HandlerWrapper, type HttpMethod, type MethodHandler, defineApi };
+export { ApiBuilder, type ApiHandlers, type HandlerArgs, type HandlerDef, type HttpMethod, type MethodHandler, type MiddlewareFn, type Schema, defineApi };

package/dist/index.js

@@ -1,3 +1,63 @@
+// src/api-builder.ts
+var ApiBuilder = class _ApiBuilder {
+  handlers;
+  constructor(handlers = {}) {
+    this.handlers = handlers;
+  }
+  /** Add middleware that runs before every handler */
+  middleware(fns) {
+    return new _ApiBuilder({
+      ...this.handlers,
+      middleware: [...this.handlers.middleware ?? [], ...fns]
+    });
+  }
+  /** Define the GET handler (becomes the loader) */
+  get(handler) {
+    return new _ApiBuilder({ ...this.handlers, GET: handler });
+  }
+  /** Define the POST handler */
+  post(handler) {
+    return new _ApiBuilder({ ...this.handlers, POST: handler });
+  }
+  /** Define the PUT handler */
+  put(handler) {
+    return new _ApiBuilder({ ...this.handlers, PUT: handler });
+  }
+  /** Define the PATCH handler */
+  patch(handler) {
+    return new _ApiBuilder({ ...this.handlers, PATCH: handler });
+  }
+  /** Define the DELETE handler */
+  delete(handler) {
+    return new _ApiBuilder({
+      ...this.handlers,
+      DELETE: handler
+    });
+  }
+  /** Build and return { loader, action } with response type helpers */
+  build() {
+    return _ApiBuilder._buildFn(this.handlers);
+  }
+  /** @internal — set by define-api.ts to wire up the build logic */
+  static _buildFn;
+};
+
+// src/parse-body.ts
+async function parseBody(request) {
+  const contentType = request.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return request.json();
+  }
+  if (contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data")) {
+    const formData = await request.formData();
+    return Object.fromEntries(formData);
+  }
+  if (contentType.includes("text/")) {
+    return request.text();
+  }
+  throw new Response("Unsupported Media Type", { status: 415 });
+}
+
 // src/define-api.ts
 var ACTION_METHODS = [
   "POST",
@@ -5,23 +65,84 @@ var ACTION_METHODS = [
   "PATCH",
   "DELETE"
 ];
-function defineApi(handlers, options) {
-  const { handler: wrapper } = options ?? {};
-  const wrap = (fn) => wrapper ? wrapper(fn) : fn;
-  const loader = handlers.GET ? wrap(handlers.GET) : void 0;
+function isHandlerDef(entry) {
+  return typeof entry === "object" && "handler" in entry;
+}
+function runMiddleware(middleware, args, handler) {
+  let index = 0;
+  const next = async () => {
+    if (index < middleware.length) {
+      return middleware[index++](args, next);
+    }
+    return handler(args);
+  };
+  return next();
+}
+function wrapWithValidation(entry) {
+  if (!isHandlerDef(entry)) return entry;
+  const { params: paramsSchema, body: bodySchema, handler } = entry;
+  return async (args) => {
+    let validatedParams = args.params;
+    if (paramsSchema) {
+      try {
+        validatedParams = paramsSchema.parse(args.params);
+      } catch (error) {
+        throw new Response(
+          JSON.stringify({ error: "Validation failed", details: error }),
+          { status: 400, headers: { "content-type": "application/json" } }
+        );
+      }
+    }
+    let body;
+    if (bodySchema) {
+      const raw = await parseBody(args.request);
+      try {
+        body = bodySchema.parse(raw);
+      } catch (error) {
+        throw new Response(
+          JSON.stringify({ error: "Validation failed", details: error }),
+          { status: 400, headers: { "content-type": "application/json" } }
+        );
+      }
+    }
+    const handlerArgs = {
+      ...args,
+      params: validatedParams,
+      ...bodySchema ? { body } : {}
+    };
+    return handler(handlerArgs);
+  };
+}
+function buildExports(handlers) {
+  const mw = handlers.middleware ?? [];
+  const getEntry = handlers.GET;
+  const getHandler = getEntry ? wrapWithValidation(getEntry) : void 0;
+  const loader = getHandler ? mw.length > 0 ? (args) => runMiddleware(mw, args, getHandler) : getHandler : void 0;
   const hasActionHandlers = ACTION_METHODS.some(
     (m) => handlers[m] != null
   );
-  const action = hasActionHandlers ? wrap(async (args) => {
+  const action = hasActionHandlers ? async (args) => {
     const method = args.request.method.toUpperCase();
-    const handler = handlers[method];
-    if (typeof handler === "function") {
-      return handler(args);
+    const entry = handlers[method];
+    if (entry == null) {
+      throw new Response("Method Not Allowed", { status: 405 });
     }
-    throw new Response("Method Not Allowed", { status: 405 });
-  }) : void 0;
+    const handler = wrapWithValidation(entry);
+    if (mw.length > 0) {
+      return runMiddleware(mw, args, handler);
+    }
+    return handler(args);
+  } : void 0;
   return { loader, action };
 }
+ApiBuilder._buildFn = buildExports;
+function defineApi(handlers) {
+  if (handlers === void 0) {
+    return new ApiBuilder();
+  }
+  return buildExports(handlers);
+}
 export {
+  ApiBuilder,
   defineApi
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-router-define-api",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Define HTTP method handlers for React Router v7 routes",
   "type": "module",
   "main": "./dist/index.cjs",