ky

ky is a small HTTP client built on top of the Fetch API. The package entry point source/index.ts composes the public KyInstance from the core Ky class, the HTTP method shortcuts in requestMethods, the stop and retry constants, and the option-merging helper validateAndMerge. Calling ky(input, options?) returns a Response object augmented with body-method shortcuts that throw on non-2xx status codes.

The root README (readme.md) is the canonical reference: it documents the call signature, every supported option, the error hierarchy, retry/cancellation behavior, and Node.js-specific features (proxy and HTTP/2). The declarations below are headings within that document plus the top-level exports surfaced from source/index.ts.

Core call signature

• ky(input, options?) — Takes the same input/options as fetch, with extra Ky-specific options. Returns a Response whose .json(), .text(), .formData(), .arrayBuffer(), .blob(), and .bytes() shortcuts throw an HTTPError outside the 200...299 range; .json() additionally throws on empty bodies or status 204. An appropriate Accept header is set based on the body method used.

Benefits over plain fetch

The Benefits over plain fetch section enumerates the value-add: method shortcuts, treating non-2xx as errors, retries, JSON option, timeout, upload/download progress, base URL, instances with custom defaults, hooks, Standard Schema response validation, and TypeScript niceties such as .json() defaulting to unknown.

Method shortcuts

ky.get, ky.post, ky.put, ky.patch, ky.head, and ky.delete are thin wrappers around ky(input, options?) that set the corresponding HTTP method. The README's ky.delete heading is split across 14 ranges (part 1 … part 14), under which most option documentation lives (e.g. parseJson, stringifyJson, fetch).

Notable options documented under the method sections

• json — Plain object or value stringified via JSON.stringify() with the appropriate Content-Type header.
• parseJson — Custom JSON parser receiving (text, {request, response}); defaults to JSON.parse(). Used for e.g. @hapijs/bourne prototype-pollution protection.
• stringifyJson — Custom replacer; defaults to JSON.stringify().
• fetch — User-supplied Fetch-compatible function for SSR wrappers or instrumentation. Defaults to the global fetch.
• onUploadProgress — Callback (progress, chunk: Uint8Array) => void invoked with transferred/total byte counts.

Instances and defaults

• ky.extend(defaultOptions) — Returns a new KyInstance that inherits and merges defaults from the parent.
• ky.create(defaultOptions) — Returns a fresh KyInstance with no inherited defaults.
• replaceOption — Sentinel used in defaultOptions to fully replace (rather than merge) a particular option.

Control flow constants

• ky.stop — Sentinel returned from a beforeRetry hook to abort retrying.
• ky.retry(options?) — Configures retry behavior (count, methods, status codes, backoff, delay).

Errors

The error hierarchy exported from the package root:

• KyError — Base class.
• HTTPError — Thrown for non-2xx responses (subject to throwHttpErrors; can be thrown manually from afterResponse hooks, as shown in the FAQ).
• SchemaValidationError — Thrown when a Standard Schema validation fails.
• TimeoutError — Thrown when the request exceeds the configured timeout.
• NetworkError — Thrown for underlying transport failures.

Tips

The Tips section covers practical recipes:

• Sending form data
• Setting a custom Content-Type
• Cancellation (via AbortController)
• Proxy support (Node.js)
• HTTP/2 support (Node.js)