transform

Use transform when the raw response isn't yet the shape the rest of the pipeline expects — scrape HTML text into a structured object, or flatten an odd envelope — so a single function reshapes the body before pick and validation ever see it.

Example

import { stitch } from 'stitchapi';

const listing = stitch({
    baseUrl: 'https://api.example.com',
    path: '/listings',
    // The body is `unknown` — narrow it, then reshape the raw envelope into a
    // plain array before pick and validation run.
    transform: (body) => (body as { results: unknown[] }).results,
});

The raw body arrives as a wrapped { results: [...] }; transform returns the inner array, and everything downstream works against that array instead.

Options

transform?: (body: unknown) => unknown runs first in the response pipeline — before pick and before validation (and drift). That ordering is the point: reshape a raw body — scrape HTML text into a structured object, or flatten an odd envelope — into the shape pick and validation are written for, rather than bending them around the source's quirks.

body is typed unknown, so narrow it before reading (a cast or a type guard) and return any reshaped value. See Reference → Config types for every field.

Reshaping the request

transform is a response slot. To reshape a body on the way out — your field names in, the API's on the wire — put the mapping in the input schema. A declared slot doesn't only validate: the request is built from the value the schema returned, so a schema that transforms is a request transform.

import { stitch } from 'stitchapi';
import { z } from 'zod';

const createUser = stitch({
    method: 'POST',
    baseUrl: 'https://api.example.com',
    path: '/users',
    input: {
        // Callers pass the house shape; the API's shape goes on the wire.
        body: z
            .object({ userName: z.string(), joinedAt: z.date() })
            .transform((b) => ({
                user_name: b.userName,
                joined_at: b.joinedAt.toISOString(),
            })),
    },
});

await createUser({ body: { userName: 'mango', joinedAt: new Date() } });

The call argument is typed from the schema's input side, so callers keep { userName, joinedAt } and never see { user_name, joined_at }. The mapping lives on the stitch once, instead of at every call site.

It runs in the right place, too: input schemas resolve before the request is built, so the reshaped body is what auth signs and what the cache key is derived from. Every slot works this way — params, query, body, headers, and GraphQL variables — and each is transformed independently.

Why transform is response-only

An output schema can reshape too, by the same rule: the stitch serves the value the schema returned. So why does transform exist as its own slot — and why only on the response?

Because on the response side the reshaping has to happen somewhere a schema can't reach, and has to stay visible to machinery a schema would hide it from:

• Ordering. transform runs before pick, so pick addresses the reshaped body. A schema's own transform runs at validation — after pick has already read the raw shape.
• Drift. Drift is anchored on the difference between the raw body and the validated value. A transform inside a drift() schema sits on the validated side, so every field it renames is reported as drift.
• Caching. A transform is a declared opacity: a stitch that has one refuses to cache until you set cache.fingerprint.transform, because re-validation cannot detect that the transform itself changed. A transform buried inside output is invisible to that check, so it silently defeats it.

None of the three has a request-side counterpart. There is no request pick and no request drift, and the cache key is derived from the request after the input schema shaped it, so the reshaping is already folded in. A request transform slot would add a second spelling and no guarantee — which is why there isn't one.

See also