API Reference

This document provides a complete API reference for Hook-Fetch, including all methods, configuration options, and type definitions.

Main Exports

import hookFetch, {
  get, post, put, patch, del, head, options, upload, request
} from 'hook-fetch';

Default Export

hookFetch(url, options?)

The main request function.

Parameters:

• url (string): The request URL
• options (RequestOptions, optional): Request configuration

Returns: HookFetchRequest<T> - Request object

Example:

const response = await hookFetch('https://api.example.com/users').json();

hookFetch.create(options)

Creates a configured Hook-Fetch instance.

Parameters:

• options (BaseOptions): Instance configuration

Returns: HookFetch - Instance object

Example:

const api = hookFetch.create({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Content-Type': 'application/json'
  }
});

Convenience Methods

get(url, params?, options?)

Makes a GET request.

Parameters:

• url (string): Request URL
• params (object, optional): Query parameters
• options (GetOptions, optional): Request configuration

Example:

const users = await get('/users', { page: 1, limit: 10 }).json();

post(url, data?, options?)

Makes a POST request.

Parameters:

• url (string): Request URL
• data (any, optional): Request body data
• options (PostOptions, optional): Request configuration

Example:

const newUser = await post('/users', { name: 'John', email: 'john@example.com' }).json();

put(url, data?, options?)

Makes a PUT request.

patch(url, data?, options?)

Makes a PATCH request.

del(url, options?)

Makes a DELETE request.

head(url, params?, options?)

Makes a HEAD request.

options(url, params?, options?)

Makes an OPTIONS request.

upload(url, data?, options?)

Makes a file upload request.

Example:

const result = await upload('/upload', {
  file: fileInput.files[0],
  name: 'My File'
}).json();

HookFetch Instance Methods

use(plugin)

Registers a plugin.

Parameters:

• plugin (HookFetchPlugin): Plugin object

Returns: this - The instance itself (supports method chaining)

Example:

api.use(myPlugin());

abortAll()

Aborts all ongoing requests.

HookFetchRequest Methods

Response Methods

• json() - Parse response as JSON
• text() - Parse response as text
• blob() - Parse response as Blob
• arrayBuffer() - Parse response as ArrayBuffer
• formData() - Parse response as FormData
• bytes() - Parse response as bytes

Stream Methods

• stream() - Get response as stream

Control Methods

• abort() - Abort the request
• retry() - Retry the request

Configuration Options

BaseOptions

interface BaseOptions {
  baseURL?: string;        // Base URL for requests
  timeout?: number;        // Request timeout in milliseconds
  headers?: HeadersInit;   // Default headers
  plugins?: HookFetchPlugin[]; // Plugin list
  withCredentials?: boolean;   // Include credentials
}

RequestOptions

interface RequestOptions<P, D, E> {
  method?: RequestMethod;      // HTTP method
  params?: P;                  // Query parameters
  data?: D;                    // Request body data
  headers?: HeadersInit;       // Request headers
  timeout?: number;            // Request timeout
  extra?: E;                   // Extra data for plugins
  withCredentials?: boolean;   // Include credentials
  qsArrayFormat?: 'indices' | 'brackets' | 'repeat' | 'comma';
}

Plugin System

HookFetchPlugin Interface

interface HookFetchPlugin<T, E, P, D> {
  name: string;                    // Plugin name (required)
  priority?: number;               // Priority (optional, default 0)
  beforeRequest?: BeforeRequestHandler<E, P, D>;
  afterResponse?: AfterResponseHandler<T, E, P, D>;
  beforeStream?: BeforeStreamHandler<E, P, D>;
  transformStreamChunk?: TransformStreamChunkHandler<E, P, D>;
  onError?: OnErrorHandler<E, P, D>;
  onFinally?: OnFinallyHandler<E, P, D>;
}

Plugin Lifecycle

1. beforeRequest - Before request is sent
2. beforeStream - Before stream processing (stream requests only)
3. transformStreamChunk - Transform stream chunks (stream requests only)
4. afterResponse - After response is received
5. onError - Error handling
6. onFinally - Final cleanup

TypeScript Support

Hook-Fetch provides complete TypeScript support with generic types:

interface User {
  id: number;
  name: string;
  email: string;
}

// Type-safe request
const user = await api.get<User>('/users/1').json();
console.log(user.name); // TypeScript provides full type hints

Error Handling

ResponseError

interface ResponseError<E = any> extends Error {
  response?: Response;
  request?: Request;
  config?: RequestConfig<any, any, E>;
  status?: number;
  statusText?: string;
}

Examples

Basic Usage

// Simple GET request
const data = await hookFetch('https://api.example.com/data').json();

// POST with data
const result = await hookFetch('https://api.example.com/users', {
  method: 'POST',
  data: { name: 'John', email: 'john@example.com' }
}).json();

Instance Usage

const api = hookFetch.create({
  baseURL: 'https://api.example.com',
  headers: { 'Authorization': 'Bearer token' }
});

const users = await api.get('/users').json();
const newUser = await api.post('/users', userData).json();

Plugin Usage

const loggerPlugin = {
  name: 'logger',
  beforeRequest: (config) => {
    console.log(`Making request to: ${config.url}`);
    return config;
  }
};

api.use(loggerPlugin);

Streaming Usage

for await (const chunk of api.get('/stream').stream()) {
  console.log('Received:', chunk.result);
}

This covers the main API surface of Hook-Fetch. For more detailed examples and advanced usage, see the other documentation sections.