0.1.0-alpha.7

@zerolith/client

Import from @zerolith/client. Generated from the source; every signature below is what the published types declare.

Functions

createClient

function createClient<A extends Contract<A>>(routes: RouteTable<A>, options?: ClientOptions): Client<A>

Creates a client for a generated route table. routes and the Api type parameter come from the same generated module, so an operation name, its parameters, its body, and its output are checked together.

Source: packages/client/src/index.ts:246

Classes

ProblemError

class ProblemError extends Error

Thrown for a response outside 2xx, carrying the problem the server sent or one built from the status line.

  • constructor(problem: Problem, response: Response): Wraps problem and the response it came from; the message is the problem's title, or HTTP <status> when it has none.
  • readonly problem: Problem: The problem the server sent, with status filled from the response when the body omits it; a body that is not a JSON problem yields status and a title from the status line.
  • readonly response: Response: The response outside 2xx, for its status and headers; its body has already been read when the content type is JSON.

Source: packages/client/src/index.ts:70

Interfaces

Operation

interface Operation

One operation as the generated Api interface describes it.

  • readonly method: Method: The HTTP method in lowercase, such as get; the request sends it uppercased.
  • readonly path: string: The path template, such as /notes/{id}, whose placeholders the client fills from params with URI-encoded values.
  • readonly params?: Record<string, string | number | boolean>: Path parameters, by the name inside the braces.
  • readonly query?: Record<string, unknown>: Query parameters; arrays repeat the key, objects are JSON.
  • readonly body?: unknown: The request body; JSON unless it is a FormData, URLSearchParams, Blob, ArrayBuffer, ReadableStream, or string, which are sent as they are.
  • readonly output: unknown: What a successful call resolves to.

Source: packages/client/src/index.ts:16

CallOptions

interface CallOptions

Per-call options.

  • signal?: AbortSignal: Becomes the request's signal, so aborting it rejects the call under fetch or portTransport; query replaces it with the resource's own signal.
  • headers?: HeadersInit: Headers for this call, set over the client's headers so that a name in both takes this value.

Source: packages/client/src/index.ts:45

ClientOptions

interface ClientOptions

Options for createClient.

  • baseUrl?: string: Prepended to every path. Defaults to "", the page's origin in a browser; pass an absolute URL elsewhere.
  • transport?: Transport: Sends every request the client builds and resolves with the response. Defaults to the global fetch, looked up on each call.
  • headers?: HeadersInit | (() => HeadersInit): Headers sent with every request, or a function returning them, for values such as a bearer token.

Source: packages/client/src/index.ts:59

Client

interface Client<A extends Contract<A>>

The client for one contract.

  • call<K extends keyof A>(name: K, ...args: InputArgs<A[K]>): Promise<Output<A[K]>>: Calls an operation and resolves with its output, or rejects with a ProblemError for a response outside 2xx.
  • query<K extends keyof A>(name: K, input: () => Input<A[K]> | undefined, options?: CallOptions): Resource<Output<A[K]>>: A resource over an operation: it calls again when the signals read by input change, and is idle while input returns undefined.
  • request<K extends keyof A>(name: K, ...args: InputArgs<A[K]>): Request: The Request a call would send, for tests and custom transports.

Source: packages/client/src/index.ts:88

Types

Method

type Method = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "query" | (string & {})

The HTTP method of an operation, in lowercase: one OpenAPI names, query being the HTTP QUERY method, or any other method token, as an OpenAPI 3.2 additionalOperations entry such as copy gives.

Source: packages/client/src/index.ts:13

Contract

type Contract<A> = { readonly [K in keyof A]: Operation }

What a generated Api interface satisfies: every member is an operation.

Source: packages/client/src/index.ts:33

RouteTable

type RouteTable<A extends Contract<A>> = { readonly [K in keyof A]: { readonly method: A[K]["method"]; readonly path: A[K]["path"] } }

The runtime half of a contract: the method and path of every operation.

Source: packages/client/src/index.ts:36

Input

type Input<Op extends Operation> = Omit<Op, "method" | "path" | "output">

What a call takes: the operation's params, query, and body, as optional as the contract makes them.

Source: packages/client/src/index.ts:39

Output

type Output<Op extends Operation> = Op["output"]

What a call resolves to.

Source: packages/client/src/index.ts:42

Transport

type Transport = (request: Request) => Promise<Response>

Sends a request. The default is fetch; a test or an Electron bridge can answer in process.

Source: packages/client/src/index.ts:56