Config types

The configuration object accepted by stitch(). Every field is optional; a stitch is the result of deep-merging these fragments through extends.

StitchConfig

import type { StitchConfig } from 'stitchapi';

wire

Every wire-format choice lives in one envelope, grouped by category rather than by request/response phase:

No single field dominates, so wire takes no scalar shorthand — like input, it is always the object form, and the opaque wire: {} is rejected.

wire.array

Controls how arrays are serialised on both application/x-www-form-urlencoded surfaces — the query string and a wire: { body: 'form' } request body. They run the same walker, so one setting governs both. The default ('indices') matches qs behaviour.

// repeat — Laravel, Rails, and many PHP frameworks expect this
const getUsers = stitch({ baseUrl, path: '/users', wire: { array: 'repeat' } });
await getUsers({ query: { ids: [1, 2] } });
// → GET /users?ids=1&ids=2

// the same setting shapes a form body
const search = stitch({
    method: 'POST',
    baseUrl,
    path: '/search',
    wire: { body: 'form', array: 'repeat' },
});
await search({ body: { ids: [1, 2] } });
// → POST /search   ids=1&ids=2

Nested objects always expand qs-style to a[b]=c on both surfaces — wire.array selects the array axis only:

await search({ body: { page: { size: 10 } } });
// → POST /search   page%5Bsize%5D=10

wire.multipart

A wire: { body: 'multipart' } body has its own grammar and is not governed by wire.array — use wire.multipart's nesting instead. Setting multipart without wire: { body: 'multipart' } is a type error, since the slot would otherwise be silently ignored.

A bare MultipartNesting string is shorthand for the object form — multipart: 'dot' ≡ multipart: { nesting: 'dot' }; the opaque multipart: {} is rejected.

Option shapes

The resilience, verdict, idempotency, cache, pagination, and drift fields above are themselves typed shapes. Each is documented from the source so it can never drift from the runtime.

RetryOptions

BackoffOptions

The shape behind retry.backoff. A bare curve is the shorthand for { curve } — backoff: 'fixed' ≡ backoff: { curve: 'fixed' }; the envelope adds base and max.

ThrottleOptions

TimeoutOptions

CircuitOptions

VerdictOptions

The shape behind verdict — what counts as success. Both members move the verdict in exactly one direction: accept can only turn a failure into a success, flag only a success into a failure. Neither invents a verdict from absence.

IdempotencyOptions

The shape behind idempotency. true is shorthand for the defaults — a random uuid minted once per logical call and reused across that call's retries.

CacheOptions

The shape behind cache. Off unless set; the key is derived from the resolved request, so it cannot drift from what it names.

methods defaults to ['GET','HEAD']. Two body-carrying reads opt in by naming their method: a GraphQL query (methods: 'POST') and QUERY (methods: 'QUERY'), whose responses are cacheable by spec. Neither is a default — a POST's read-vs-mutate intent cannot be inferred, and caching a body-carrying request is a decision worth writing down. The key already folds the request body in, so two different QUERY bodies to the same URL get two entries and cannot collide.

CacheFingerprintOptions

The shape behind cache.fingerprint — how a stored value is detected as stale against its contract (the ADR 0004 ladder). Every member is a rung of that ladder; ttl, tenancy, vary and the rest of CacheOptions answer a different question and stay outside. A bare version tag is the shorthand for { version } — fingerprint: 3 ≡ fingerprint: { version: 3 }, the always-available manual override.

Unset is the automatic path: a registered @stitchapi/fingerprint-* strategy makes output changes self-invalidate, and an un-fingerprintable schema refuses to cache.

CacheTransformOptions

The shape behind cache.fingerprint.transform — what the cache knows about an opaque transform. A bare version tag is the shorthand for { version } here too, one level in: fingerprint: { transform: 3 } ≡ fingerprint: { transform: { version: 3 } }. A stitch that has a transform and none of this refuses to cache: the closure cannot be hashed, and re-validation cannot detect a transform change, so no policy would be sound. version wins when both are set.

PaginateOptions

The shape behind paginate. next drives the loop; auth, retry, and throttle apply to every page.

DriftOptions

See also