v0.7.1 (build 925)
Koya home

Module/http

Full-featured async HTTP client available to QuickJS scripts.

Full-featured async HTTP client with Promise-based API. Supports all HTTP verbs (GET, POST, PUT, PATCH, DELETE), custom headers, request bodies, and both HTTP and HTTPS protocols.

Import #

import * as Http from 'Module/http';

Types #

RequestOptions
Options object passed to request().
  • url string - The URL to request.
  • method 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' optional - HTTP method. Defaults to 'GET'.
  • headers Record<string, string> optional - Custom request headers.
  • body string optional - Request body for POST, PUT, and PATCH.
  • binary boolean optional - When true, returns body as ArrayBuffer instead of string.
Response
Object resolved by request().
  • status number - HTTP status code.
  • headers Record<string, string> - Response headers.
  • body string | ArrayBuffer - Response body. ArrayBuffer when binary: true was set.

Functions #

request
Queues an HTTP request and resolves when complete.
  • Supports all HTTP verbs with optional request body for POST, PUT, and PATCH.
  • Custom headers support for authentication (Bearer tokens), content negotiation, etc.
  • Works with both HTTP and HTTPS protocols.
  • When binary: true, returns body as ArrayBuffer; when binary: false (default), returns body as string.
  • Rejects on network or TLS failure. Inspect the error object for details.
request(options: RequestOptions): Promise<Response>
drain
Manually drain completed jobs. Normally unnecessary because the engine calls the update hook each frame.
drain(): void

Examples #

Basic GET request #

Fetch a URL and inspect the response status and body. Wrap the call in try/catch to handle network errors gracefully.

import * as Http from 'Module/http';
import * as Log from 'Helix/Log';

try {
  const res = await Http.request({ url: 'https://example.org', method: 'GET' });
  Log.info('status=' + res.status);
  Log.debug('length=' + res.body.length);
} catch (e) {
  Log.error('http failed: ' + JSON.stringify(e));
}

GET request with authentication #

Pass a Bearer token and content-type headers for authenticated API requests.

const res = await Http.request({
  url: 'https://api.example.com/users',
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your-token-here',
    'Accept': 'application/json'
  }
});

POST request with JSON body #

Submit a JSON payload to create a new resource. Set the Content-Type header and serialize the body with JSON.stringify.

const userData = { name: 'John Doe', email: 'john@example.com' };
const res = await Http.request({
  url: 'https://api.example.com/users',
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-token-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(userData)
});

PUT request to update a resource #

Replace an entire resource by sending a full JSON body to a specific endpoint.

const updateData = { name: 'Jane Doe', email: 'jane@example.com' };
const res = await Http.request({
  url: 'https://api.example.com/users/123',
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer your-token-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
});

PATCH request for partial updates #

Update individual fields on a resource without replacing the entire object.

const patchData = { email: 'newemail@example.com' };
const res = await Http.request({
  url: 'https://api.example.com/users/123',
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer your-token-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(patchData)
});

DELETE request #

Remove a resource by its ID with an authenticated DELETE request.

const res = await Http.request({
  url: 'https://api.example.com/users/123',
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer your-token-here'
  }
});

HTTP (non-HTTPS) request #

Plain HTTP requests work the same way — useful for local services or development servers that don't use TLS.

const res = await Http.request({
  url: 'http://httpbin.org/get',
  method: 'GET',
  headers: {
    'X-Custom-Header': 'test-value'
  }
});

Download and save a binary file #

Use binary: true to receive the response as an ArrayBuffer, then write it to disk with Process.writeFile. Useful for downloading images, archives, or other non-text content.

import * as Http from 'Module/http';
import * as Process from 'Module/process';
import * as Log from 'Helix/Log';

const response = await Http.request({
  url: 'https://example.com/image.png',
  method: 'GET',
  binary: true
});

if (response.status === 200) {
  if (!Process.exists('./downloads')) {
    Process.mkdir('./downloads');
  }

  const success = Process.writeFile('./downloads/image.png', response.body);

  if (success) {
    Log.info('File downloaded and saved successfully!');
  } else {
    Log.error('Failed to save file');
  }
}

Notes #

  • All HTTP verbs (GET, POST, PUT, PATCH, DELETE) are fully implemented and supported.
  • Both HTTP and HTTPS protocols are supported.
  • Request bodies are automatically sent for POST, PUT, and PATCH requests.
  • Custom headers support authentication, content negotiation, and other HTTP features.
  • Use binary: true to get binary data as ArrayBuffer; binary: false (default) returns text as string.
  • The binary option is ideal for downloading images, archives, or other binary files.
  • Certificate validation errors will be surfaced in logs with OpenSSL messages.
  • The module uses a background worker thread to prevent blocking the main engine thread.
<- Koya/ImageModule/sqlite ->