react-router-define-api 0.1.1 → 0.1.3

package/README.md

@@ -18,8 +18,7 @@ import { defineApi } from 'react-router-define-api';
 
 export const { loader, action } = defineApi({
   GET: async ({ params }) => {
-    const users = await db.users.findMany();
-    return { users };
+    return { users: await db.users.findMany() };
   },
   POST: async ({ request }) => {
     const body = await request.formData();
@@ -38,6 +37,35 @@ export const { loader, action } = defineApi({
 - `POST`, `PUT`, `PATCH`, `DELETE` → dispatched inside `action` by `request.method`
 - Undefined methods → `405 Method Not Allowed`
 
+### Handler wrapper
+
+Wrap all handlers with a higher-order function for error handling, response transformation, logging, etc.:
+
+```ts
+export const { loader, action } = defineApi({
+  GET: async () => ({ name: 'John' }),
+  POST: async ({ request }) => {
+    const body = await request.formData();
+    return { name: body.get('name') };
+  },
+}, {
+  handler: loaderActionHandler,
+});
+```
+
+Example `loaderActionHandler`:
+
+```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) };
+  }
+};
+```
+
 ### Response type helpers
 
 Access inferred response types for client-side fetchers or shared contracts:

package/dist/index.cjs

@@ -31,17 +31,21 @@ var ACTION_METHODS = [
   "PATCH",
   "DELETE"
 ];
-function defineApi(handlers) {
-  const loader = handlers.GET ?? void 0;
-  const hasActionHandlers = ACTION_METHODS.some((m) => handlers[m] != null);
-  const action = hasActionHandlers ? async (args) => {
+function defineApi(handlers, options) {
+  const { handler: wrapper } = options ?? {};
+  const wrap = (fn) => wrapper ? wrapper(fn) : fn;
+  const loader = handlers.GET ? wrap(handlers.GET) : void 0;
+  const hasActionHandlers = ACTION_METHODS.some(
+    (m) => handlers[m] != null
+  );
+  const action = hasActionHandlers ? wrap(async (args) => {
     const method = args.request.method.toUpperCase();
     const handler = handlers[method];
     if (typeof handler === "function") {
       return handler(args);
     }
     throw new Response("Method Not Allowed", { status: 405 });
-  } : void 0;
+  }) : void 0;
   return { loader, action };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -28,22 +28,47 @@ 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: LoaderFunctionArgs | ActionFunctionArgs) => unknown) => (args: LoaderFunctionArgs | ActionFunctionArgs) => 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> = {
+type ApiExports<H extends ApiHandlers, W = never> = {
     loader: H extends {
         GET: infer F;
-    } ? (args: LoaderFunctionArgs) => Promise<HandlerReturn<F>> : undefined;
-    action: HasActionMethods<H> extends true ? (args: ActionFunctionArgs) => Promise<ActionReturn<H>> : undefined;
+    } ? (args: LoaderFunctionArgs) => Promise<WithWrapper<HandlerReturn<F>, W>> : undefined;
+    action: HasActionMethods<H> extends true ? (args: ActionFunctionArgs) => Promise<WithWrapper<ActionReturn<H>, W>> : undefined;
     /** Inferred return type of the GET handler */
-    GetResponse: ResponseOf<H, 'GET'>;
+    GetResponse: WithWrapper<ResponseOf<H, 'GET'>, W>;
     /** Inferred return type of the POST handler */
-    PostResponse: ResponseOf<H, 'POST'>;
+    PostResponse: WithWrapper<ResponseOf<H, 'POST'>, W>;
     /** Inferred return type of the PUT handler */
-    PutResponse: ResponseOf<H, 'PUT'>;
+    PutResponse: WithWrapper<ResponseOf<H, 'PUT'>, W>;
     /** Inferred return type of the PATCH handler */
-    PatchResponse: ResponseOf<H, 'PATCH'>;
+    PatchResponse: WithWrapper<ResponseOf<H, 'PATCH'>, W>;
     /** Inferred return type of the DELETE handler */
-    DeleteResponse: ResponseOf<H, 'DELETE'>;
+    DeleteResponse: WithWrapper<ResponseOf<H, 'DELETE'>, W>;
 };
 
 /**
@@ -52,18 +77,24 @@ type ApiExports<H extends ApiHandlers> = {
  *
  * @example
  * ```ts
- * const api = defineApi({
+ * export const { loader, action } = defineApi({
  *   GET: async ({ params }) => ({ user: params.id }),
  *   POST: async ({ request }) => {
  *     const body = await request.formData();
  *     return { created: true };
  *   },
  * });
+ * ```
  *
- * export const loader = api.loader;
- * export const action = api.action;
+ * @example With handler wrapper
+ * ```ts
+ * export const { loader, action } = defineApi({
+ *   GET: async () => ({ data: 'ok' }),
+ * }, {
+ *   handler: loaderActionHandler,
+ * });
  * ```
  */
-declare function defineApi<const H extends ApiHandlers>(handlers: H): ApiExports<H>;
+declare function defineApi<const H extends ApiHandlers, W = never>(handlers: H, options?: DefineApiOptions<W>): ApiExports<H, W>;
 
-export { type ApiHandlers, type HttpMethod, type MethodHandler, defineApi };
+export { type ApiHandlers, type DefineApiOptions, type HandlerWrapper, type HttpMethod, type MethodHandler, defineApi };

package/dist/index.d.ts

@@ -28,22 +28,47 @@ 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: LoaderFunctionArgs | ActionFunctionArgs) => unknown) => (args: LoaderFunctionArgs | ActionFunctionArgs) => 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> = {
+type ApiExports<H extends ApiHandlers, W = never> = {
     loader: H extends {
         GET: infer F;
-    } ? (args: LoaderFunctionArgs) => Promise<HandlerReturn<F>> : undefined;
-    action: HasActionMethods<H> extends true ? (args: ActionFunctionArgs) => Promise<ActionReturn<H>> : undefined;
+    } ? (args: LoaderFunctionArgs) => Promise<WithWrapper<HandlerReturn<F>, W>> : undefined;
+    action: HasActionMethods<H> extends true ? (args: ActionFunctionArgs) => Promise<WithWrapper<ActionReturn<H>, W>> : undefined;
     /** Inferred return type of the GET handler */
-    GetResponse: ResponseOf<H, 'GET'>;
+    GetResponse: WithWrapper<ResponseOf<H, 'GET'>, W>;
     /** Inferred return type of the POST handler */
-    PostResponse: ResponseOf<H, 'POST'>;
+    PostResponse: WithWrapper<ResponseOf<H, 'POST'>, W>;
     /** Inferred return type of the PUT handler */
-    PutResponse: ResponseOf<H, 'PUT'>;
+    PutResponse: WithWrapper<ResponseOf<H, 'PUT'>, W>;
     /** Inferred return type of the PATCH handler */
-    PatchResponse: ResponseOf<H, 'PATCH'>;
+    PatchResponse: WithWrapper<ResponseOf<H, 'PATCH'>, W>;
     /** Inferred return type of the DELETE handler */
-    DeleteResponse: ResponseOf<H, 'DELETE'>;
+    DeleteResponse: WithWrapper<ResponseOf<H, 'DELETE'>, W>;
 };
 
 /**
@@ -52,18 +77,24 @@ type ApiExports<H extends ApiHandlers> = {
  *
  * @example
  * ```ts
- * const api = defineApi({
+ * export const { loader, action } = defineApi({
  *   GET: async ({ params }) => ({ user: params.id }),
  *   POST: async ({ request }) => {
  *     const body = await request.formData();
  *     return { created: true };
  *   },
  * });
+ * ```
  *
- * export const loader = api.loader;
- * export const action = api.action;
+ * @example With handler wrapper
+ * ```ts
+ * export const { loader, action } = defineApi({
+ *   GET: async () => ({ data: 'ok' }),
+ * }, {
+ *   handler: loaderActionHandler,
+ * });
  * ```
  */
-declare function defineApi<const H extends ApiHandlers>(handlers: H): ApiExports<H>;
+declare function defineApi<const H extends ApiHandlers, W = never>(handlers: H, options?: DefineApiOptions<W>): ApiExports<H, W>;
 
-export { type ApiHandlers, type HttpMethod, type MethodHandler, defineApi };
+export { type ApiHandlers, type DefineApiOptions, type HandlerWrapper, type HttpMethod, type MethodHandler, defineApi };

package/dist/index.js

@@ -5,17 +5,21 @@ var ACTION_METHODS = [
   "PATCH",
   "DELETE"
 ];
-function defineApi(handlers) {
-  const loader = handlers.GET ?? void 0;
-  const hasActionHandlers = ACTION_METHODS.some((m) => handlers[m] != null);
-  const action = hasActionHandlers ? async (args) => {
+function defineApi(handlers, options) {
+  const { handler: wrapper } = options ?? {};
+  const wrap = (fn) => wrapper ? wrapper(fn) : fn;
+  const loader = handlers.GET ? wrap(handlers.GET) : void 0;
+  const hasActionHandlers = ACTION_METHODS.some(
+    (m) => handlers[m] != null
+  );
+  const action = hasActionHandlers ? wrap(async (args) => {
     const method = args.request.method.toUpperCase();
     const handler = handlers[method];
     if (typeof handler === "function") {
       return handler(args);
     }
     throw new Response("Method Not Allowed", { status: 405 });
-  } : void 0;
+  }) : void 0;
   return { loader, action };
 }
 export {

package/package.json

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