react-router-define-api 0.1.0 → 0.1.2

package/README.md

@@ -16,103 +16,76 @@ npm install react-router-define-api
 // app/routes/api.users.ts
 import { defineApi } from 'react-router-define-api';
 
-const api = defineApi({
+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();
-    const user = await db.users.create({ name: body.get('name') });
-    return { user };
+    return { user: await db.users.create({ name: body.get('name') }) };
   },
   DELETE: async ({ params }) => {
     await db.users.delete(params.id);
     return { deleted: true };
   },
 });
-
-export const loader = api.loader;
-export const action = api.action;
 ```
 
 ### How it works
 
-- `GET` handler → exported as `loader`
-- `POST`, `PUT`, `PATCH`, `DELETE` handlers → dispatched inside `action` by `request.method`
-- Undefined methods return a `405 Method Not Allowed` response
+- `GET` → `loader`
+- `POST`, `PUT`, `PATCH`, `DELETE` → dispatched inside `action` by `request.method`
+- Undefined methods → `405 Method Not Allowed`
 
-### All methods
+### Handler wrapper
+
+Wrap all handlers with a higher-order function for error handling, response transformation, logging, etc.:
 
 ```ts
-const api = defineApi({
-  GET: async (args) => {
-    /* ... */
-  },
-  POST: async (args) => {
-    /* ... */
-  },
-  PUT: async (args) => {
-    /* ... */
-  },
-  PATCH: async (args) => {
-    /* ... */
-  },
-  DELETE: async (args) => {
-    /* ... */
+export const { loader, action } = defineApi({
+  GET: async () => ({ name: 'John' }),
+  POST: async ({ request }) => {
+    const body = await request.formData();
+    return { name: body.get('name') };
   },
+}, {
+  handler: loaderActionHandler,
 });
 ```
 
-## API
-
-### `defineApi(handlers)`
-
-| Parameter  | Type          | Description                              |
-| ---------- | ------------- | ---------------------------------------- |
-| `handlers` | `ApiHandlers` | Map of HTTP methods to handler functions |
-
-Returns `{ loader, action }` — each is `undefined` if no relevant methods are defined.
+Example `loaderActionHandler`:
 
-Handler args are the same as React Router's `LoaderFunctionArgs` / `ActionFunctionArgs`:
-
-- `request` — the incoming `Request` object
-- `params` — route parameters
-- `context` — app context
+```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) };
+  }
+};
+```
 
-## TypeScript
+### Response type helpers
 
-Full type inference — return types are inferred from your handler functions.
+Access inferred response types for client-side fetchers or shared contracts:
 
 ```ts
 const api = defineApi({
   GET: async ({ params }) => ({ id: params.id, name: 'John' }),
-  POST: async ({ request }) => {
-    const body = await request.formData();
-    return { created: true, name: body.get('name') };
-  },
+  POST: async () => ({ created: true }),
 });
 
-// api.loader return type is inferred as { id: string | undefined, name: string }
-// api.action is undefined when no action methods defined
-```
-
-### Response type helpers
+export const { loader, action } = api;
 
-Access inferred response types via `typeof api.*Response` — useful for typing client-side fetchers or shared contracts:
-
-```ts
 type GetRes = typeof api.GetResponse;
 // → { id: string | undefined; name: string }
 
 type PostRes = typeof api.PostResponse;
-// → { created: boolean; name: FormDataEntryValue | null }
-
-// Undefined methods → never
-type PutRes = typeof api.PutResponse; // → never
+// → { created: boolean }
 ```
 
-These are **type-only** — zero runtime cost.
+These are **type-only** — zero runtime cost. Undefined methods resolve to `never`.
 
 ## License
 

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<T>> = (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> = <TArgs, TResult>(fn: (args: TArgs) => Promise<TResult>) => (args: TArgs) => 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<T>> = (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> = <TArgs, TResult>(fn: (args: TArgs) => Promise<TResult>) => (args: TArgs) => 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.0",
+  "version": "0.1.2",
   "description": "Define HTTP method handlers for React Router v7 routes",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -49,5 +49,13 @@
     "typescript": "^6.0.2",
     "ultracite": "^7.4.0",
     "vitest": "^4.1.2"
-  }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sonicname/react-router-define-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sonicname/react-router-define-api/issues"
+  },
+  "homepage": "https://github.com/sonicname/react-router-define-api#readme"
 }