respond / isResponseEnvelope

A value paired with response metadata (status, headers, revalidate) — for the things a naked return can't express. Progressive enhancement stays invisible: the carried response holds a plain JSON body so consumers without the client runtime (no-JS form posts, direct HTTP) get real JSON, while integrations read value — no reparse. The body is encoded when read, so value may be anything a plain return may.

Typed as value's type: every caller of the function returning it — over HTTP or in-process — receives the value, never the envelope. At runtime it is a ResponseEnvelope, a real Response that integrations recognize with isResponseEnvelope().

Import

import { respond, isResponseEnvelope } from "@solidjs/web";

respond

Type signature

function respond<T>(value: T, init?: ResponseHelperInit): ResponseEnvelope<T>;

Parameters

value

• Type: T

init

• Type: ResponseHelperInit
• Optional

Examples

return respond(user, {
  status: 201,
  headers: { "x-created-user": user.id },
});

Common problems

• respond() reaches the client as Internal Server Error
• Errors show for a moment and then vanish

isResponseEnvelope

Returns whether a value is a response envelope, including across duplicated runtime modules.

Type signature

function isResponseEnvelope(value: unknown): value is ResponseEnvelope;

Parameters

value

• Type: unknown

Learn more

• Mutations and responses
• Forms
• Middleware and API routes

Related types

ResponseEnvelope

Envelope pairing HTTP metadata with a value. Produced by respond() and by server-function transformResult implementations (e.g. single-flight payloads); the HTTP handler forwards response's headers and (non-redirect) status and encodes value as the body through the codec, while client-only integrations read value directly — no reparse.

The envelope IS a Response — the given response's body, status and headers — so a consumer that knows nothing of Solid (a filesystem router's API dispatch, any fetch-style handler) answers with it as-is. response is the envelope itself, or undefined when constructed without one.

interface ResponseEnvelope<T = unknown> extends Response {
  response: Response | undefined;
  value: T;
}

response

• Type: Response | undefined

value

• Type: T

ResponseHelperInit

ResponseInit accepted by the response helpers, plus revalidate.

interface ResponseHelperInit extends ResponseInit {
  revalidate?: string | string[];
}

revalidate

• Type: string | string[]

The cache keys the mutation invalidated, sent as the X-Revalidate header for the client's integrations to apply. Three declarations, three scopes: omitted sends no header — the host's default (Solid Router revalidates everything after an action; a router without that convention reloads only what it owns); an empty list sends an empty header — nothing, explicitly; REVALIDATE_ALL ("*") — every entry, whatever the host's default. How named keys are matched (prefixes, namespaces) is each integration's business.

REVALIDATE_ALL

The reserved revalidate key meaning every entry, in every cache: the host-independent spelling of "all" (as Clear-Site-Data: "*" spells it), for authors who mean it rather than a host's default. Stands alone — naming it beside other keys is refused, since "everything and also these" is a mistake, not a scope.

const REVALIDATE_ALL: "*";