Browse documentation

request

Provides the asynchronous Valyrian.js HTTP client entry point.

Table of contents

Category

Value

Import

js
import { request } from "valyrian.js/request";

Public signature

ts
request(method: string, url: string, data?: Record<string, any> | null, options?: Partial<SendOptions>): any | Response
request.new(baseUrl: string, options?: RequestOptions): RequestInterface

API form

request is a callable singleton and scoped-client factory. request.new(...) returns another RequestInterface and is a method named new, not a JavaScript constructor.

Options and defaults

ts
type RequestOptions = {
  allowedMethods?: string[];
  urls?: { base?: string; node?: string | null; api?: string | null };
  headers?: Record<string, string>;
  resolveWithFullResponse?: boolean; // false
};

type SendOptions = RequestInit & RequestOptions & {
  method: string;
  headers: Record<string, string>;
};
type RequestCallOptions = Partial<SendOptions>;
type RequestContext = {
  method: string;
  url: URL;
  data?: Record<string, unknown> | null;
  options: SendOptions;
};
type ResponseContext = RequestContext & { response: Response; body: unknown };
type ErrorContext = RequestContext & {
  response?: Response;
  error: unknown;
  body?: unknown;
};

type RequestPlugin = {
  request?: (context: RequestContext) => RequestContext | Promise<RequestContext | void> | void;
  response?: (context: ResponseContext) => ResponseContext | Promise<ResponseContext | void> | void;
  error?: (context: ErrorContext) => ErrorContext | Promise<ErrorContext | void> | void;
};

// Default helpers
get | post | put | patch | delete | head | options
// Default URL options
{ base: "", node: null, api: null }
// Default Accept
application/json

Essential methods

ts
request.get(url, data?, options?): any | Response
request.post(url, data?, options?): any | Response
request.put(url, data?, options?): any | Response
request.patch(url, data?, options?): any | Response
request.delete(url, data?, options?): any | Response
request.head(url, data?, options?): any | Response
request.options(url, data?, options?): any | Response
request.new(baseUrl, options?): RequestInterface
request.use(plugin: RequestPlugin): number
request.eject(pluginId: number): void
request.setOption(path: string, value: unknown): RequestOptions
request.setOptions(values: Record<string, unknown>): RequestOptions
request.getOption(path: string): unknown
request.getOptions(key?: string): RequestOptions | void

Runtime async behavior

The installed .d.ts declares any | Response for the callable request and its generated method helpers. The runtime implementation is async, so every request call returns a promise and must be used with await. This runtime behavior is separate from the published TypeScript signature above.

Plugins and responses

Call-site options are Partial<SendOptions>; request fills method, headers, URL settings and defaults before sending. Await request calls and their generated method helpers. Request plugins can provide request, response and error hooks and run in registration order. Non-success HTTP responses reject with an error that may include response and, for JSON or text, a parsed body. resolveWithFullResponse returns the raw Response only for successful responses.