Utils

请求

访问传入请求的实用工具

assertMethod(event, expected, allowHead?)

Asserts that the incoming request method is of the expected type using isMethod.

If the method is not allowed, it will throw a 405 error with the message "HTTP method is not allowed".

If allowHead is true, it will allow HEAD requests to pass if the expected method is GET.

Example:

app.get("/", (event) => {
  assertMethod(event, "GET");
  // Handle GET request, otherwise throw 405 error
});

getQuery(event)

Get parsed query string object from the request URL.

Example:

app.get("/", (event) => {
  const query = getQuery(event); // { key: "value", key2: ["value1", "value2"] }
});

getRequestHost(event, opts: { xForwardedHost? })

Get the request hostname.

If xForwardedHost is true, it will use the x-forwarded-host header if it exists.

If no host header is found, it will default to "localhost".

Example:

app.get("/", (event) => {
  const host = getRequestHost(event); // "example.com"
});

getRequestIP(event)

Try to get the client IP address from the incoming request.

If xForwardedFor is true, it will use the x-forwarded-for header if it exists.

If IP cannot be determined, it will default to undefined.

Example:

app.get("/", (event) => {
  const ip = getRequestIP(event); // "192.0.2.0"
});

getRequestProtocol(event, opts: { xForwardedProto? })

Get the request protocol.

If x-forwarded-proto header is set to "https", it will return "https". You can disable this behavior by setting xForwardedProto to false.

If protocol cannot be determined, it will default to "http".

Example:

app.get("/", (event) => {
  const protocol = getRequestProtocol(event); // "https"
});

getRequestURL(event, opts: { xForwardedHost?, xForwardedProto? })

Generated the full incoming request URL.

If xForwardedHost is true, it will use the x-forwarded-host header if it exists.

If xForwardedProto is false, it will not use the x-forwarded-proto header.

Example:

app.get("/", (event) => {
  const url = getRequestURL(event); // "https://example.com/path"
});

getRouterParam(event, name, opts: { decode? })

Get a matched route param by name.

If decode option is true, it will decode the matched route param using decodeURI.

Example:

app.get("/", (event) => {
  const param = getRouterParam(event, "key");
});

getRouterParams(event, opts: { decode? })

Get matched route params.

If decode option is true, it will decode the matched route params using decodeURIComponent.

Example:

app.get("/", (event) => {
  const params = getRouterParams(event); // { key: "value" }
});

getValidatedQuery(event, validate)

Get the query param from the request URL validated with validate function.

You can use a simple function to validate the query object or a library like zod to define a schema.

Example:

app.get("/", async (event) => {
  const query = await getValidatedQuery(event, (data) => {
    return "key" in data && typeof data.key === "string";
  });
});

Example:

import { z } from "zod";
app.get("/", async (event) => {
  const query = await getValidatedQuery(
    event,
    z.object({
      key: z.string(),
    }).parse,
  );
});

getValidatedRouterParams(event, validate, opts: { decode? })

Get matched route params and validate with validate function.

If decode option is true, it will decode the matched route params using decodeURI.

You can use a simple function to validate the params object or a library like zod to define a schema.

Example:

app.get("/", async (event) => {
  const params = await getValidatedRouterParams(event, (data) => {
    return "key" in data && typeof data.key === "string";
  });
});

Example:

import { z } from "zod";
app.get("/", async (event) => {
  const params = await getValidatedRouterParams(
    event,
    z.object({
      key: z.string(),
    }).parse,
  );
});

isMethod(event, expected, allowHead?)

Checks if the incoming request method is of the expected type.

If allowHead is true, it will allow HEAD requests to pass if the expected method is GET.

Example:

app.get("/", (event) => {
  if (isMethod(event, "GET")) {
    // Handle GET request
  } else if (isMethod(event, ["POST", "PUT"])) {
    // Handle POST or PUT request
  }
});

getRequestFingerprint(event, opts)

Get a unique fingerprint for the incoming request.

请求体工具

readBody(event)

Reads request body and tries to parse using JSON.parse or URLSearchParams.

Example:

app.get("/", async (event) => {
  const body = await readBody(event);
});

readValidatedBody(event, validate)

Tries to read the request body via readBody, then uses the provided validation function and either throws a validation error or returns the result.

You can use a simple function to validate the body or use a library like zod to define a schema.

Example:

app.get("/", async (event) => {
  const body = await readValidatedBody(event, (body) => {
    return typeof body === "object" && body !== null;
  });
});

Example:

import { z } from "zod";
app.get("/", async (event) => {
  const objectSchema = z.object();
  const body = await readValidatedBody(event, objectSchema.safeParse);
});