Wasapi 🌶️

Wasapi is a lightweight TypeScript REST API client library that simplifies HTTP service generation using decorator-based API definitions, a fluent builder, typed responses, and smart polling utilities.

The TypeScript counterpart of wasapi for Java — same design philosophy, native TypeScript experience.

Features

• Decorator-based API definitions — @GET, @POST, @PUT, @DELETE, @PATCH, @HTTP
• Fluent builder — configure base URL, headers, timeouts, proxy, logging
• Typed responses — ApiCall<T>, ApiResponse<T>, ResponsePair<R, E>
• Strict / lenient modes — throw on failure or return null
• Response polling — monitorResponseCode(), monitorFieldValue()
• Zero HTTP dependencies — uses native fetch (Node 18+)
• TC39 Stage 3 decorators — no experimentalDecorators, no reflect-metadata

Installation

npm install @civitas-cerebrum/wasapi

Quick Start

1. Define your API with decorators

import { GET, POST, DELETE, ApiCall } from '@civitas-cerebrum/wasapi';

interface User {
  id: string;
  name: string;
  email: string;
}

class UserApi {
  @GET('/users')
  getUsers(): ApiCall<User[]> { return null!; }

  @GET('/users/:id')
  getUser(pathParams: { id: string }): ApiCall<User> { return null!; }

  @POST('/users')
  createUser(body: { name: string; email: string }): ApiCall<User> { return null!; }

  @DELETE('/users/:id')
  deleteUser(pathParams: { id: string }): ApiCall<void> { return null!; }
}

2. Build the client

import { WasapiClient } from '@civitas-cerebrum/wasapi';

const api = new WasapiClient.Builder()
  .setBaseUrl('https://api.example.com')
  .setHeaders({ Authorization: 'Bearer token' })
  .setLogHeaders(true)
  .build(UserApi);

3. Execute requests

// Lenient mode (default) — returns null on failure
const users = await api.getUsers().perform();

// Strict mode — throws FailedCallException on non-2xx
const users = await api.getUsers().perform(true);

// Strict + log response body
const users = await api.getUsers().perform(true, true);

// Full response wrapper
const response = await api.getUser({ id: '5' }).getResponse();
console.log(response.status);    // 200
console.log(response.body);      // User object
console.log(response.headers);   // Record<string, string>

// Typed error handling
const pair = await api.getUser({ id: 'bad' }).getResponsePair(ErrorModel);
if (pair.isError()) {
  console.log(pair.errorBody);   // ErrorModel instance
}

API Reference

Decorators

Path parameters use :param syntax — e.g., /users/:id is substituted from pathParams: { id: '5' }.

Query parameters are appended as ?key=value from queryParams: Record<string, string>.

@HTTP — Custom HTTP Methods

For unconventional methods like PURGE, COPY, or LOCK:

import { HTTP, ApiCall } from '@civitas-cerebrum/wasapi';

class CacheApi {
  @HTTP('PURGE', '/cache/:key')
  purge(pathParams: { key: string }): ApiCall<void> { return null!; }

  @HTTP('REPORT', '/analytics', true)  // hasBody = true
  report(body: ReportRequest): ApiCall<ReportResult> { return null!; }
}

WasapiClient.Builder

Pass a ContextStore instance to the constructor to read defaults from configuration:

const store = new ContextStore();
store.put('wasapi.baseUrl', 'https://api.example.com');
store.put('wasapi.timeout', 30);

const api = new WasapiClient.Builder(store).build(MyApi);

ApiCall<T>

Every decorated method returns an ApiCall<T> — a lazy request descriptor that doesn't execute until you call one of its methods:

ApiResponse<T>

ResponsePair<R, E>

Exceptions

Logging

Uses the debug package with wasapi:* namespace. Enabled by default.

# Suppress all wasapi logs
WASAPI_DEBUG=false npx tsx tests/my-test.ts

# Show only request logs
DEBUG=wasapi:request npx tsx tests/my-test.ts

Comparison with Java Wasapi

Important Notes

Argument order matters. Body-bearing methods (@POST, @PUT, @PATCH) take (body, pathParams?, queryParams?, options?). Non-body methods (@GET, @DELETE) take (pathParams?, queryParams?, options?). TypeScript enforces this at compile time, but be careful when constructing calls dynamically.

perform() returns null in lenient mode for both empty successful responses (e.g., 204) and failed requests. If you need to distinguish these cases, use getResponse() which gives you the full ApiResponse<T> with status code.

Response body is a plain JSON object, not a class instance. ApiCall<User>.perform() returns a plain object shaped as User, not an instance of User with methods. This is standard TypeScript REST client behavior (same as axios, ky, etc.).

Timeout units: Builder's setTimeout() is in seconds. Polling methods (monitorResponseCode, monitorFieldValue) take milliseconds for timeout and interval.

FormData via options: To send multipart requests through the decorator path, pass formData in the options parameter:

const form = WasapiClient.getMultipartFromFile('./photo.jpg', 'avatar');
await api.uploadAvatar(undefined, undefined, { formData: form }).perform(true);

License

MIT