Architecture

Ky is organized as a TypeScript library with a single distributable bundle compiled from source/ into distribution/, plus a substantial test suite that exercises the library against real HTTP servers. The repository is split into five top-level areas: source/ (library code, 29 files), test/ (262 symbols across 23 files), .github/, media/, and a small set of root-level configuration files.

A high-level import diagram is rendered separately from the dependency graph; the dominant edge is test → source (16 imports), reflecting that the test suite is the primary consumer of the public surface exported from source/index.js.

source/

The library code lives under source/ and is compiled with tsconfig.dist.json, which sets rootDir: "./source" and outDir: "./distribution" while inheriting from the base tsconfig. The base tsconfig.json extends @sindresorhus/tsconfig and enables exactOptionalPropertyTypes. Internally, source/ is further divided:

source/core/

Contains the request engine. source/core/Ky.ts is the central class implementation: it pulls in error types (HTTPError, NetworkError, NonError, ForceRetryError, SchemaValidationError, TimeoutError), the option/normalization types from source/types/, and utilities for merging, streaming, timeouts, delay, and network-error detection. It is the orchestrator that ties hooks, retries, schema validation, and fetch invocation together.

source/types/

Holds the shared type vocabulary. source/types/options.ts declares Options, Hooks, and RetryOptions re-exports and depends on ./common.js for utility types like LiteralUnion and Required. These types are consumed throughout source/core/ and source/utils/.

source/errors/

Defines the error hierarchy imported by Ky.ts: HTTPError, NetworkError, NonError, ForceRetryError, SchemaValidationError, and TimeoutError. Several of these (HTTPError, KyError, SchemaValidationError, TimeoutError) plus the isKyError guard are re-exported from source/index.js as part of the public API.

source/utils/

Implementation helpers. source/utils/merge.ts exports the merge primitives (cloneShallow, mergeHeaders, mergeHooks, deletedParametersSymbol) used by Ky.ts to combine parent and child option sets — the same mechanism that powers ky.extend(). Other utilities referenced from Ky.ts include streamRequest/streamResponse from utils/body.js, normalizeRequestMethod/normalizeRetryOptions from utils/normalize.js, plus timeout, delay, options, and is-network-error modules.

source/index.ts

The public entry point. Tests import the full public API from ../source/index.js, including ky (default), HTTPError, KyError, SchemaValidationError, TimeoutError, isKyError, replaceOption, and the StandardSchemaV1 type.

test/

The test suite uses AVA and expect-type for type-level assertions. test/main.ts exercises behavioral contracts such as hook composition across chained .extend() calls (e.g. extendHooksMacro verifying that beforeRequest and afterResponse hooks from intermediate and extended option sets all fire). Tests rely on local helpers in test/helpers/, including create-http-test-server.js and parse-body.js, to spin up real servers per test.

test/browser.ts

A separate browser-environment test entry point that loads the compiled bundle directly: it injects a module script with import ky from '/distribution/index.js' and assigns it to globalThis.ky. This validates the published artifact rather than the TypeScript sources.

Root configuration

The root contains build and tooling configuration: tsconfig.json, tsconfig.dist.json, and .gitignore (which excludes node_modules/, distribution/, yarn.lock, and package-lock.json, so the compiled output is never committed).

.github/ and media/

.github/ holds repository metadata (1 symbol across 3 files), and media/ contains binary assets only (no code symbols).