react-router-define-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# react-router-define-api
+
+Define HTTP method handlers for React Router v7 routes — no more manual `request.method` checks.
+
+## Install
+
+```bash
+npm install react-router-define-api
+```
+
+**Peer dependency:** `react-router@^7.0.0`
+
+## Usage
+
+```ts
+// app/routes/api.users.ts
+import { defineApi } from 'react-router-define-api';
+
+const api = defineApi({
+  GET: async ({ params }) => {
+    const users = await db.users.findMany();
+    return { users };
+  },
+  POST: async ({ request }) => {
+    const body = await request.formData();
+    const user = await db.users.create({ name: body.get('name') });
+    return { user };
+  },
+  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
+
+### All methods
+
+```ts
+const api = defineApi({
+  GET: async (args) => {
+    /* ... */
+  },
+  POST: async (args) => {
+    /* ... */
+  },
+  PUT: async (args) => {
+    /* ... */
+  },
+  PATCH: async (args) => {
+    /* ... */
+  },
+  DELETE: async (args) => {
+    /* ... */
+  },
+});
+```
+
+## 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.
+
+Handler args are the same as React Router's `LoaderFunctionArgs` / `ActionFunctionArgs`:
+
+- `request` — the incoming `Request` object
+- `params` — route parameters
+- `context` — app context
+
+## TypeScript
+
+Full type inference — return types are inferred from your handler functions.
+
+```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') };
+  },
+});
+
+// api.loader return type is inferred as { id: string | undefined, name: string }
+// api.action is undefined when no action methods defined
+```
+
+### Response type helpers
+
+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
+```
+
+These are **type-only** — zero runtime cost.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,50 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  defineApi: () => defineApi
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/define-api.ts
+var ACTION_METHODS = [
+  "POST",
+  "PUT",
+  "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) => {
+    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;
+  return { loader, action };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineApi
+});

package/dist/index.d.cts

@@ -0,0 +1,69 @@
+import { LoaderFunctionArgs, ActionFunctionArgs } from 'react-router';
+
+/** Supported HTTP methods */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** Handler function for a given HTTP method */
+type MethodHandler<Args, R = unknown> = (args: Args) => R | Promise<R>;
+/** 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;
+};
+/** Extract the awaited return type from a handler */
+type HandlerReturn<T> = T extends (...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 */
+type ActionReturn<H> = (H extends {
+    POST: infer F;
+} ? HandlerReturn<F> : never) | (H extends {
+    PUT: infer F;
+} ? HandlerReturn<F> : never) | (H extends {
+    PATCH: infer F;
+} ? HandlerReturn<F> : never) | (H extends {
+    DELETE: infer F;
+} ? 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;
+/** Return type of defineApi — loader/action presence and return types inferred from handlers */
+type ApiExports<H extends ApiHandlers> = {
+    loader: H extends {
+        GET: infer F;
+    } ? (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: ResponseOf<H, 'GET'>;
+    /** Inferred return type of the POST handler */
+    PostResponse: ResponseOf<H, 'POST'>;
+    /** Inferred return type of the PUT handler */
+    PutResponse: ResponseOf<H, 'PUT'>;
+    /** Inferred return type of the PATCH handler */
+    PatchResponse: ResponseOf<H, 'PATCH'>;
+    /** Inferred return type of the DELETE handler */
+    DeleteResponse: ResponseOf<H, 'DELETE'>;
+};
+
+/**
+ * Define HTTP method handlers for a React Router v7 route.
+ * Returns `{ loader, action }` ready to export from a route module.
+ *
+ * @example
+ * ```ts
+ * const api = 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;
+ * ```
+ */
+declare function defineApi<const H extends ApiHandlers>(handlers: H): ApiExports<H>;
+
+export { type ApiHandlers, type HttpMethod, type MethodHandler, defineApi };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { LoaderFunctionArgs, ActionFunctionArgs } from 'react-router';
+
+/** Supported HTTP methods */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/** Handler function for a given HTTP method */
+type MethodHandler<Args, R = unknown> = (args: Args) => R | Promise<R>;
+/** 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;
+};
+/** Extract the awaited return type from a handler */
+type HandlerReturn<T> = T extends (...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 */
+type ActionReturn<H> = (H extends {
+    POST: infer F;
+} ? HandlerReturn<F> : never) | (H extends {
+    PUT: infer F;
+} ? HandlerReturn<F> : never) | (H extends {
+    PATCH: infer F;
+} ? HandlerReturn<F> : never) | (H extends {
+    DELETE: infer F;
+} ? 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;
+/** Return type of defineApi — loader/action presence and return types inferred from handlers */
+type ApiExports<H extends ApiHandlers> = {
+    loader: H extends {
+        GET: infer F;
+    } ? (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: ResponseOf<H, 'GET'>;
+    /** Inferred return type of the POST handler */
+    PostResponse: ResponseOf<H, 'POST'>;
+    /** Inferred return type of the PUT handler */
+    PutResponse: ResponseOf<H, 'PUT'>;
+    /** Inferred return type of the PATCH handler */
+    PatchResponse: ResponseOf<H, 'PATCH'>;
+    /** Inferred return type of the DELETE handler */
+    DeleteResponse: ResponseOf<H, 'DELETE'>;
+};
+
+/**
+ * Define HTTP method handlers for a React Router v7 route.
+ * Returns `{ loader, action }` ready to export from a route module.
+ *
+ * @example
+ * ```ts
+ * const api = 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;
+ * ```
+ */
+declare function defineApi<const H extends ApiHandlers>(handlers: H): ApiExports<H>;
+
+export { type ApiHandlers, type HttpMethod, type MethodHandler, defineApi };

package/dist/index.js

@@ -0,0 +1,23 @@
+// src/define-api.ts
+var ACTION_METHODS = [
+  "POST",
+  "PUT",
+  "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) => {
+    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;
+  return { loader, action };
+}
+export {
+  defineApi
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "react-router-define-api",
+  "version": "0.1.0",
+  "description": "Define HTTP method handlers for React Router v7 routes",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "license": "MIT",
+  "keywords": [
+    "react-router",
+    "react-router-v7",
+    "loader",
+    "action",
+    "api",
+    "http-methods"
+  ],
+  "peerDependencies": {
+    "react-router": "^7.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "npm exec -- ultracite check",
+    "lint:fix": "npm exec -- ultracite fix",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "react-router": "^7.13.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "ultracite": "^7.4.0",
+    "vitest": "^4.1.2"
+  }
+}