feat: add getPayload utility for unified request data access

Merges route params, query params, and body into a single object:

- GET/HEAD: route params + query params
- POST/PUT/PATCH/DELETE: route params + parsed body

Route params have lowest priority — body/query values override them.

Usage:
  app.post("/users/:id", async (event) => {
    const payload = await getPayload(event);
    // { id: "123", name: "Alice" }
  });

Closes #785

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: productdevbook

src/index.ts

@@ -118,6 +118,10 @@ export {
 
 export { readBody, readValidatedBody, assertBodySize } from "./utils/body.ts";
 
+// Payload
+
+export { getPayload } from "./utils/payload.ts";
+
 // Cookie
 
 export {

src/utils/payload.ts

@@ -0,0 +1,39 @@
+import type { H3Event, HTTPEvent } from "../event.ts";
+import { getQuery } from "./request.ts";
+import { readBody } from "./body.ts";
+import { getRouterParams } from "./request.ts";
+
+const _payloadMethods = new Set(["PATCH", "POST", "PUT", "DELETE"]);
+
+/**
+ * Get the request payload by merging route params, query params, and body data.
+ *
+ * For `GET` and `HEAD` requests, returns query params merged with route params.
+ * For `POST`, `PUT`, `PATCH`, and `DELETE` requests, returns parsed body merged with route params.
+ *
+ * Route params take lowest priority (body/query overrides them).
+ *
+ * @example
+ * app.post("/users/:id", async (event) => {
+ *   const payload = await getPayload(event);
+ *   // { id: "123", name: "Alice" } — id from route, name from body
+ * });
+ *
+ * @example
+ * app.get("/search/:category", async (event) => {
+ *   const payload = await getPayload(event);
+ *   // { category: "books", q: "h3" } — category from route, q from query
+ * });
+ */
+export async function getPayload<T = Record<string, unknown>>(
+  event: H3Event | HTTPEvent,
+  opts?: { decode?: boolean },
+): Promise<T> {
+  const params = getRouterParams(event, opts);
+  if (_payloadMethods.has(event.req.method)) {
+    const body = (await readBody(event)) || {};
+    return { ...params, ...(typeof body === "object" ? body : { body }) } as T;
+  }
+  const query = getQuery(event);
+  return { ...params, ...query } as T;
+}

test/unit/package.test.ts

@@ -58,6 +58,7 @@ describe("h3 package", () => {
         "getHeader",
         "getHeaders",
         "getMethod",
+        "getPayload",
         "getProxyRequestHeaders",
         "getQuery",
         "getRequestFingerprint",

test/unit/payload.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { H3, getPayload } from "../../src/index.ts";
+import { describeMatrix } from "../_setup.ts";
+
+describeMatrix("getPayload", (t, { it, expect }) => {
+  it("returns query params for GET requests", async () => {
+    t.app.get("/search", async (event) => {
+      return getPayload(event);
+    });
+    const res = await t.fetch("/search?q=hello&page=1");
+    expect(await res.json()).toMatchObject({ q: "hello", page: "1" });
+  });
+
+  it("returns body for POST requests", async () => {
+    t.app.post("/users", async (event) => {
+      return getPayload(event);
+    });
+    const res = await t.fetch("/users", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "Alice" }),
+    });
+    expect(await res.json()).toMatchObject({ name: "Alice" });
+  });
+
+  it("merges route params with query for GET", async () => {
+    t.app.get("/search/:category", async (event) => {
+      return getPayload(event);
+    });
+    const res = await t.fetch("/search/books?q=h3");
+    const data = await res.json();
+    expect(data.category).toBe("books");
+    expect(data.q).toBe("h3");
+  });
+
+  it("merges route params with body for POST", async () => {
+    t.app.post("/users/:id", async (event) => {
+      return getPayload(event);
+    });
+    const res = await t.fetch("/users/123", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: "Bob" }),
+    });
+    const data = await res.json();
+    expect(data.id).toBe("123");
+    expect(data.name).toBe("Bob");
+  });
+
+  it("body overrides route params on conflict", async () => {
+    t.app.put("/items/:id", async (event) => {
+      return getPayload(event);
+    });
+    const res = await t.fetch("/items/old", {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ id: "new" }),
+    });
+    expect((await res.json()).id).toBe("new");
+  });
+});