or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

errors.mdhooks.mdhttp-methods.mdindex.mdinstances.mdoptions.mdpagination.mdresponses.mdstreams.mdutilities.md
tile.json

http-methods.mddocs/

HTTP Methods

Core HTTP request methods providing the primary interface for making requests with comprehensive options and response handling.

Capabilities

Main Request Function

The primary got function supports multiple call signatures for different use cases and response types.

/**
 * Makes an HTTP request with the specified URL and options
 * @param url - The request URL
 * @param options - Request configuration options
 * @returns Cancelable promise resolving to response
 */
function got(url: string | URL, options?: OptionsInit): CancelableRequest<Response>;

/**
 * Makes an HTTP request using options-only syntax
 * @param options - Request configuration options including URL
 * @returns Cancelable promise resolving to response
 */
function got(options: OptionsInit): CancelableRequest<Response>;

// Type-specific overloads for different response types
function got(url: string | URL, options?: OptionsOfTextResponseBody): CancelableRequest<Response<string>>;
function got<T>(url: string | URL, options?: OptionsOfJSONResponseBody): CancelableRequest<Response<T>>;
function got(url: string | URL, options?: OptionsOfBufferResponseBody): CancelableRequest<Response<Buffer>>;

// Body-only response variants (resolveBodyOnly: true)
function got(url: string | URL, options?: OptionsOfTextResponseBodyOnly): CancelableRequest<string>;
function got<T>(url: string | URL, options?: OptionsOfJSONResponseBodyOnly): CancelableRequest<T>;
function got(url: string | URL, options?: OptionsOfBufferResponseBodyOnly): CancelableRequest<Buffer>;

Usage Examples:

import got from "got";

// Basic GET request
const response = await got("https://api.example.com/users");
console.log(response.body);

// GET with JSON response type
const users = await got("https://api.example.com/users", {
  responseType: "json"
});

// GET with body-only response
const data = await got("https://api.example.com/data", {
  resolveBodyOnly: true,
  responseType: "json"
});

// Options-only syntax
const response = await got({
  url: "https://api.example.com/users",
  method: "GET",
  headers: { "Authorization": "Bearer token" }
});

GET Method

Performs HTTP GET requests.

/**
 * Performs an HTTP GET request
 * @param url - The request URL
 * @param options - Request configuration options
 * @returns Cancelable promise resolving to response
 */
const get: GotRequestFunction;

Usage Examples:

// Simple GET request
const response = await got.get("https://api.example.com/users");

// GET with query parameters
const users = await got.get("https://api.example.com/users", {
  searchParams: { page: 1, limit: 10 }
});

// GET with custom headers
const data = await got.get("https://api.example.com/protected", {
  headers: { "Authorization": "Bearer token" }
});

POST Method

Performs HTTP POST requests, commonly used for creating resources or submitting data.

/**
 * Performs an HTTP POST request
 * @param url - The request URL
 * @param options - Request configuration options
 * @returns Cancelable promise resolving to response
 */
const post: GotRequestFunction;

Usage Examples:

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

// POST with form data
const response = await got.post("https://api.example.com/form", {
  form: {
    username: "alice",
    password: "secret"
  }
});

// POST with raw body
const result = await got.post("https://api.example.com/data", {
  body: JSON.stringify({ data: "value" }),
  headers: { "Content-Type": "application/json" }
});

PUT Method

Performs HTTP PUT requests, typically used for updating or replacing resources.

/**
 * Performs an HTTP PUT request
 * @param url - The request URL
 * @param options - Request configuration options
 * @returns Cancelable promise resolving to response
 */
const put: GotRequestFunction;

Usage Examples:

// PUT to update a resource
const updatedUser = await got.put("https://api.example.com/users/123", {
  json: {
    name: "Alice Smith",
    email: "alice.smith@example.com"
  }
}).json();

PATCH Method

Performs HTTP PATCH requests, used for partial updates to resources.

/**
 * Performs an HTTP PATCH request
 * @param url - The request URL
 * @param options - Request configuration options
 * @returns Cancelable promise resolving to response
 */
const patch: GotRequestFunction;

Usage Examples:

// PATCH to partially update a resource
const updatedUser = await got.patch("https://api.example.com/users/123", {
  json: {
    email: "newemail@example.com"
  }
}).json();

HEAD Method

Performs HTTP HEAD requests, which return only headers without a response body.

/**
 * Performs an HTTP HEAD request
 * @param url - The request URL
 * @param options - Request configuration options
 * @returns Cancelable promise resolving to response
 */
const head: GotRequestFunction;

Usage Examples:

// HEAD request to check resource existence
const response = await got.head("https://api.example.com/users/123");
console.log(response.statusCode); // 200 if exists, 404 if not
console.log(response.headers['last-modified']);

DELETE Method

Performs HTTP DELETE requests, used for removing resources.

/**
 * Performs an HTTP DELETE request
 * @param url - The request URL
 * @param options - Request configuration options
 * @returns Cancelable promise resolving to response
 */
const delete: GotRequestFunction;

Usage Examples:

// DELETE a resource
const response = await got.delete("https://api.example.com/users/123");
console.log(response.statusCode); // 204 for successful deletion

Response Shortcuts

All HTTP methods return a CancelableRequest that provides convenient shortcut methods for different response types:

interface CancelableRequest<T> extends Promise<T> {
  /**
   * Shortcut for JSON response parsing
   * @returns Promise resolving to parsed JSON
   */
  json<ReturnType>(): CancelableRequest<ReturnType>;
  
  /**
   * Shortcut for buffer response
   * @returns Promise resolving to Buffer
   */
  buffer(): CancelableRequest<Buffer>;
  
  /**
   * Shortcut for text response
   * @returns Promise resolving to string
   */
  text(): CancelableRequest<string>;
  
  /**
   * Cancel the request
   */
  cancel(): void;
}

Usage Examples:

// Using response shortcuts
const users = await got.get("https://api.example.com/users").json();
const htmlContent = await got.get("https://example.com").text();
const fileBuffer = await got.get("https://example.com/file.pdf").buffer();

// Canceling requests
const request = got.get("https://slow-api.example.com");
setTimeout(() => request.cancel(), 5000);
const result = await request.json();

Type Definitions

type GotRequestFunction<U extends ExtendOptions = Record<string, unknown>> = {
  // Promise API overloads for different response types
  (url: string | URL, options?: OptionsOfTextResponseBody): CancelableRequest<Response<string>>;
  <T>(url: string | URL, options?: OptionsOfJSONResponseBody): CancelableRequest<Response<T>>;
  (url: string | URL, options?: OptionsOfBufferResponseBody): CancelableRequest<Response<Buffer>>;
  (url: string | URL, options?: OptionsOfUnknownResponseBody): CancelableRequest<Response>;
  
  // Body-only response variants
  (url: string | URL, options?: OptionsOfTextResponseBodyOnly): CancelableRequest<string>;
  <T>(url: string | URL, options?: OptionsOfJSONResponseBodyOnly): CancelableRequest<T>;
  (url: string | URL, options?: OptionsOfBufferResponseBodyOnly): CancelableRequest<Buffer>;
  (url: string | URL, options?: OptionsOfUnknownResponseBodyOnly): CancelableRequest;
  
  // Options-only variants
  (options: OptionsOfTextResponseBody): CancelableRequest<Response<string>>;
  <T>(options: OptionsOfJSONResponseBody): CancelableRequest<Response<T>>;
  (options: OptionsOfBufferResponseBody): CancelableRequest<Response<Buffer>>;
  (options: OptionsOfUnknownResponseBody): CancelableRequest<Response>;
  
  // Stream variants
  (url: string | URL, options?: StreamOptions): Request;
  (options: StreamOptions): Request;
  
  // Fallback
  (url: string | URL, options?: OptionsInit): CancelableRequest | Request;
  (options: OptionsInit): CancelableRequest | Request;
};

type HTTPAlias = "get" | "post" | "put" | "patch" | "head" | "delete";

type Method = 
  | "GET" | "POST" | "PUT" | "PATCH" | "HEAD" | "DELETE" 
  | "OPTIONS" | "TRACE" | "CONNECT";