🧼 TSoapy
_{Type-Safe OpenAPI Calls}

Create a fully-typed & lightweight client for your openapi-typescript type definitions. Zero dependencies. 2.4k. Optimized for OpenAPI v3.

Usage

Taken from the Pet Store Example

import type { paths } from "../__generated__/petstore";
import { tsoapy } from "../";

const client = tsoapy<paths>(new URL("https://example.com/api/petstore"));

// call your api using .path().method() to select the specific endpoint you need
const r1 = await client
  .path("/store/order")
  .method("post")
  // then, include your body, set params, query string, etc
  .body({
    id: 123,
    petId: 456,
    quantity: 1,
    shipDate: "2023-02-25T00:00:00Z",
    status: "placed",
    complete: false,
  })
  // send the request and get a descriminated union as a response
  .send();

if (r1.status === 200) {
  // union is discriminated on .status, and contains a .data property
  r1.data.id; // <= typed from response
}

API

Descriptions here provide a generic type such as string for clarity, but use a more complex typing in the codebase

tsoapy<paths>(url: URL, ctx?: ExtendedRequestInit)

Configure the initial value of tsoapy, including the URL base all path values are derrived from, and any RequestInit options you want to share between all chained methods.

Returns: An object containing the single .path() method.

tsoapy().path(path: string)

Select a path from the tsoapy collection.

Returns: An object containing the single .method() method.

tsoapy().path().method(method: string, contentType?: string, serialize: Function)

Select a method from the tsoapy collection, constrained to the previously built path. Because OpenAPI JSON is top-down desiged (path => method => params), you need to have a path before you can select a method. During method selection, you can specify a content type other than the default application/json, and set up a custom serialize function for converting your request object to a string.

Returns: A tsoapy builder object for configuring the request data, containing params, query, body, and send

Tsoapy Builder Builder

After chaining tsoapy().path().method(), the API opens up in order to configure and send the request. Depending on your OpenAPI endpoint, you may need to set URL parameters, configure query string values, or set the request body. Once configured, you can send the request via .send(), returning a promise containing the API result.

tsoapy().path().method()....params(params: object)

Set URL parameters in a request such as /pet/{petId}.

Returns: Builder object for configuring the request data, containing params, query, body, and send

tsoapy().path().method()....query(query: object)

Set query string parameters for the request.

Returns: Builder object for configuring the request data, containing params, query, body, and send

tsoapy().path().method()....body(body: object)

Set the body for the request. Will use serializer to conver the object to a suitable string, defaulting to JSON.stringify().

Returns: Builder object for configuring the request data, containing params, query, body, and send

tsoapy().path().method()....send(options?: RequestInit, contentType?: string, deserialize?: Function):Promise

Send the request via fetch.

Returns: A tsoapy response as a discriminated union in the following format:

{
  status: number;
  data: object;
}

Sending Content Types other than application/json

Tsoapy uses application/json by default for requests & responses. If you need to change this, you can control the input and output handing.

• input typing and serialization is controlled when calling .method(). In addition to setting the content type (which selects the responseBody from OpenAPI), the third parameter serialize allows you to pass in a custom serializer function for turning the JSON object into the requested content type, expressed as a string. Because there's a variety of content types, it's beyond Tsoapy to add custom converters for every possible serialization.
• output typing and deserialization is controlled when calling .send(). Like method, you can pass a content type as the second argument which maps to a content type inside of the OpenAPI responses.[code] collection. The third parameter deserialize can be a function that takes in a string and returns a JSON object conforming to the object schema on OpenAPIs side. Like serialization, adding custom deserialization goes beyond the scope of this library.

⚠️ note You'll need to specify your content type and serializer/deserializer every time, as OpenAPI is designed in a top-down method of path => method => requestBody => content => [contentType] and path => method => responses => [code] => content => [contentType], making it difficult to set these at the top-level tsoapy() as you do not know at that time which path & method (and therefore which content types) you are invoking.

Common Serializer / Deserializers

If JSON isn't sufficient and you do need to serialize / deserialize in order to talk to your OpenAPI endpoint, there are already excellent battle-tested libraries that can be dropped into tsoapy without much effort.

• application/xml - xml2json
• application/x-www-form-urlencoded - form-urlencoded

FAQ

• Why is it so small? Tsoapy is 90% type management. The exported index.js is the builder API, designed to build the fetch call in a way consistent with how you walk the OpenAPI paths object. In 0.0.4, the ESM version is 2.4kb and the CJS version is 3.43kb with the increase being the CommonJS harness provided by tsup.
• Why not openapi? openapi is an excellent library, but its types are not as semantically correct as those generated by openapi-typescript. By separating type generation from runtime library, you can stop using tsoapy, go back to plain fetch and still take advantage of the types generated by openapi-typescript. This also means that tsoapy can focus on being a really good fetch builder.

Stuff Still To Do

• Tests (maybe using MSW as the network is at the heart of this)
• There's a coercion of number to ResultCodeOf<T, P, M> which I can't seem to get right

License

MIT