or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mderrors.mdhooks.mdhttp-methods.mdindex.mdinstances.mdresponses.mdretry.md
tile.json

tessl/npm-ky

Tiny and elegant HTTP client based on the Fetch API

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ky@1.10.x

To install, run

npx @tessl/cli install tessl/npm-ky@1.10.0

index.mddocs/

Ky

Ky is a tiny and elegant HTTP client based on the Fetch API. It provides a simplified interface for making HTTP requests with modern features like automatic retries, JSON handling, timeout support, URL prefixing, and an extensible hooks system. Ky works seamlessly across browsers, Node.js, Bun, and Deno environments.

Package Information

  • Package Name: ky
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install ky

Core Imports

import ky from "ky";

For CommonJS:

const ky = require("ky").default;

Basic Usage

import ky from "ky";

// Simple GET request
const user = await ky.get("https://api.example.com/user/123").json();

// POST with JSON data
const response = await ky.post("https://api.example.com/users", {
  json: { name: "Alice", email: "alice@example.com" }
}).json();

// Request with options
const data = await ky("https://api.example.com/data", {
  timeout: 5000,
  retry: 3,
  headers: { "Authorization": "Bearer token" }
}).json();

Architecture

Ky is built around several key components:

  • Instance System: Default ky instance with the ability to create custom instances with different defaults
  • HTTP Methods: Convenient shortcuts for common HTTP methods (get, post, put, patch, delete, head)
  • Response Promise: Enhanced promises with body method shortcuts (json, text, blob, etc.)
  • Options System: Comprehensive configuration supporting both Fetch API options and Ky-specific extensions
  • Retry Engine: Intelligent retry logic with configurable backoff strategies and status code handling
  • Hooks System: Extensible request/response lifecycle hooks for custom behavior
  • Error Handling: Automatic HTTP error throwing with detailed error information

Capabilities

HTTP Methods

Core HTTP request methods with convenient shortcuts and full TypeScript support.

// Main request function
function ky<T>(url: Input, options?: Options): ResponsePromise<T>;

// HTTP method shortcuts
function get<T>(url: Input, options?: Options): ResponsePromise<T>;
function post<T>(url: Input, options?: Options): ResponsePromise<T>;
function put<T>(url: Input, options?: Options): ResponsePromise<T>;
function patch<T>(url: Input, options?: Options): ResponsePromise<T>;
function delete<T>(url: Input, options?: Options): ResponsePromise<T>;
function head(url: Input, options?: Options): ResponsePromise;

HTTP Methods

Instance Management

Create and extend ky instances with custom defaults for different API endpoints or configurations.

function create(defaultOptions?: Options): KyInstance;
function extend(defaultOptions?: Options | ((parentOptions: Options) => Options)): KyInstance;

Instance Management

Configuration Options

Comprehensive options for customizing request behavior including JSON handling, retries, timeouts, and progress tracking.

interface Options extends KyOptions, Omit<RequestInit, 'headers'> {
  method?: LiteralUnion<HttpMethod, string>;
  headers?: KyHeadersInit;
}

interface KyOptions {
  json?: unknown;
  parseJson?: (text: string) => unknown;
  stringifyJson?: (data: unknown) => string;
  searchParams?: SearchParamsOption;
  prefixUrl?: URL | string;
  retry?: RetryOptions | number;
  timeout?: number | false;
  throwHttpErrors?: boolean;
  onDownloadProgress?: (progress: Progress, chunk: Uint8Array) => void;
  onUploadProgress?: (progress: Progress, chunk: Uint8Array) => void;
  fetch?: (input: Input, init?: RequestInit) => Promise<Response>;
  hooks?: Hooks;
}

Configuration

Response Handling

Enhanced response promises with body method shortcuts and automatic error handling for non-2xx status codes.

interface ResponsePromise<T = unknown> extends Promise<KyResponse<T>> {
  arrayBuffer(): Promise<ArrayBuffer>;
  blob(): Promise<Blob>;
  formData(): Promise<FormData>;
  bytes(): Promise<Uint8Array>;
  json<J = T>(): Promise<J>;
  text(): Promise<string>;
}

Response Handling

Retry System

Configurable retry logic with exponential backoff, status code filtering, and Retry-After header support.

interface RetryOptions {
  limit?: number;
  methods?: string[];
  statusCodes?: number[];
  afterStatusCodes?: number[];
  maxRetryAfter?: number;
  backoffLimit?: number;
  delay?: (attemptCount: number) => number;
}

Retry System

Hooks System

Extensible lifecycle hooks for request modification, response processing, error handling, and retry customization.

interface Hooks {
  beforeRequest?: BeforeRequestHook[];
  beforeRetry?: BeforeRetryHook[];
  afterResponse?: AfterResponseHook[];
  beforeError?: BeforeErrorHook[];
}

Hooks System

Error Handling

Comprehensive error handling with detailed HTTP and timeout error classes containing request and response information.

class HTTPError<T = unknown> extends Error {
  response: KyResponse<T>;
  request: KyRequest;
  options: NormalizedOptions;
}

class TimeoutError extends Error {
  request: KyRequest;
}

Error Handling

Types

Core type definitions used throughout the Ky API:

interface NormalizedOptions extends RequestInit {
  method: NonNullable<RequestInit['method']>;
  credentials?: NonNullable<RequestInit['credentials']>;
  retry: RetryOptions;
  prefixUrl: string;
  onDownloadProgress: Options['onDownloadProgress'];
  onUploadProgress: Options['onUploadProgress'];
}
type Input = string | URL | Request;

type KyInstance = {
  <T>(url: Input, options?: Options): ResponsePromise<T>;
  get: <T>(url: Input, options?: Options) => ResponsePromise<T>;
  post: <T>(url: Input, options?: Options) => ResponsePromise<T>;
  put: <T>(url: Input, options?: Options) => ResponsePromise<T>;
  patch: <T>(url: Input, options?: Options) => ResponsePromise<T>;
  delete: <T>(url: Input, options?: Options) => ResponsePromise<T>;
  head: (url: Input, options?: Options) => ResponsePromise;
  create: (defaultOptions?: Options) => KyInstance;
  extend: (defaultOptions?: Options | ((parentOptions: Options) => Options)) => KyInstance;
  readonly stop: typeof stop;
};

interface KyRequest<T = unknown> extends Request {
  json: <J = T>() => Promise<J>;
}

interface KyResponse<T = unknown> extends Response {
  json: <J = T>() => Promise<J>;
}

interface Progress {
  percent: number;
  transferredBytes: number;
  totalBytes: number;
}

type SearchParamsInit = string | string[][] | Record<string, string> | URLSearchParams | undefined;

type SearchParamsOption = SearchParamsInit | Record<string, string | number | boolean | undefined> | Array<Array<string | number | boolean>>;

type KyHeadersInit = NonNullable<RequestInit['headers']> | Record<string, string | undefined>;

type LiteralUnion<LiteralType, BaseType extends string> = LiteralType | (BaseType & Record<never, never>);

type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'head' | 'delete';

type BeforeRequestHook = (
  request: KyRequest,
  options: NormalizedOptions
) => Request | Response | void | Promise<Request | Response | void>;

type BeforeRetryState = {
  request: KyRequest;
  options: NormalizedOptions;
  error: Error;
  retryCount: number;
};

type BeforeRetryHook = (options: BeforeRetryState) => typeof stop | void | Promise<typeof stop | void>;

type AfterResponseHook = (
  request: KyRequest,
  options: NormalizedOptions,
  response: KyResponse
) => Response | void | Promise<Response | void>;

type BeforeErrorHook = (error: HTTPError) => HTTPError | Promise<HTTPError>;

declare const stop: unique symbol;