Type alias KyOptions

Type declaration

• Optional fetch?: ((input, init?) => Promise<Response>)

  User-defined fetch function. Has to be fully compatible with the Fetch API standard.

  Use-cases:

  1. Use custom fetch implementations like isomorphic-unfetch.
  2. Use the fetch wrapper function provided by some frameworks that use server-side rendering (SSR).

  Default

  fetch
  Copy

  Example

  import ky from 'ky';
  import fetch from 'isomorphic-unfetch';
  
  const json = await ky('https://example.com', {fetch}).json();
  Copy

  • • (input, init?): Promise<Response>

    • Parameters

      • input: Input
      • Optional init: RequestInit

      Returns Promise<Response>

• Optional hooks?: Hooks

  Hooks allow modifications during the request lifecycle. Hook functions may be async and are run serially.

• Optional json?: unknown

  Shortcut for sending JSON. Use this instead of the body option.

  Accepts any plain object or value, which will be JSON.stringify()'d and sent in the body with the correct header set.

• Optional onDownloadProgress?: ((progress, chunk) => void)

  Download progress event handler.

  Example

  import ky from 'ky';
  
  const response = await ky('https://example.com', {
      onDownloadProgress: (progress, chunk) => {
          // Example output:
          // `0% - 0 of 1271 bytes`
          // `100% - 1271 of 1271 bytes`
          console.log(`${progress.percent * 100}% - ${progress.transferredBytes} of ${progress.totalBytes} bytes`);
      }
  });
  Copy

  • • (progress, chunk): void

    • Parameters

      • progress: DownloadProgress
      • chunk: Uint8Array

        Note: It's empty for the first call.

      Returns void

• Optional parseJson?: ((text) => unknown)

  User-defined JSON-parsing function.

  Use-cases:

  1. Parse JSON via the bourne package to protect from prototype pollution.
  2. Parse JSON with reviver option of JSON.parse().

  Default

  JSON.parse()
  Copy

  Example

  import ky from 'ky';
  import bourne from '@hapijs/bourne';
  
  const json = await ky('https://example.com', {
      parseJson: text => bourne(text)
  }).json();
  Copy

  • • (text): unknown

    • Parameters

      • text: string

      Returns unknown

• Optional prefixUrl?: URL | string

  A prefix to prepend to the input URL when making the request. It can be any valid URL, either relative or absolute. A trailing slash / is optional and will be added automatically, if needed, when it is joined with input. Only takes effect when input is a string. The input argument cannot start with a slash / when using this option.

  Useful when used with ky.extend() to create niche-specific Ky-instances.

  Notes:

  • After prefixUrl and input are joined, the result is resolved against the base URL of the page (if any).
  • Leading slashes in input are disallowed when using this option to enforce consistency and avoid confusion about how the input URL is handled, given that input will not follow the normal URL resolution rules when prefixUrl is being used, which changes the meaning of a leading slash.

  Example

  import ky from 'ky';
  
  // On https://example.com
  
  const response = await ky('unicorn', {prefixUrl: '/api'});
  //=> 'https://example.com/api/unicorn'
  
  const response = await ky('unicorn', {prefixUrl: 'https://cats.com'});
  //=> 'https://cats.com/unicorn'
  Copy

• Optional retry?: RetryOptions | number

  An object representing limit, methods, statusCodes and maxRetryAfter fields for maximum retry count, allowed methods, allowed status codes and maximum Retry-After time.

  If retry is a number, it will be used as limit and other defaults will remain in place.

  If maxRetryAfter is set to undefined, it will use options.timeout. If Retry-After header is greater than maxRetryAfter, it will cancel the request.

  By default, delays between retries are calculated with the function 0.3 * (2 ** (attemptCount - 1)) * 1000, where attemptCount is the attempt number (starts from 1), however this can be changed by passing a delay function.

  Retries are not triggered following a timeout.

  Example

  import ky from 'ky';
  
  const json = await ky('https://example.com', {
      retry: {
          limit: 10,
          methods: ['get'],
          statusCodes: [413]
      }
  }).json();
  Copy

• Optional searchParams?: SearchParamsOption

  Search parameters to include in the request URL. Setting this will override all existing search parameters in the input URL.

  Accepts any value supported by URLSearchParams().

• Optional throwHttpErrors?: boolean

  Throw an HTTPError when, after following redirects, the response has a non-2xx status code. To also throw for redirects instead of following them, set the redirect option to 'manual'.

  Setting this to false may be useful if you are checking for resource availability and are expecting error responses.

  Note: If false, error responses are considered successful and the request will not be retried.

  Default

  true
  Copy

• Optional timeout?: number | false

  Timeout in milliseconds for getting a response, including any retries. Can not be greater than 2147483647. If set to false, there will be no timeout.

  Default

  10000
  Copy