Typesafe API Call Utility

Common errors

• TypeError: APICaller.call is not a function

  cause Incorrect module import, especially in CommonJS environments prior to v5.1.1, or attempting to access `call` on an undefined `APICaller`.
  fix Ensure you are using `import { APICaller } from 'typesafe-api-call';` (ESM) and have updated to `typesafe-api-call@^5.1.1` or later. Verify that `APICaller` is correctly imported and not `undefined`.

• ReferenceError: APISuccess is not defined

  cause The `APISuccess` class was not correctly imported from the `typesafe-api-call` package.
  fix Add `import { APISuccess } from 'typesafe-api-call';` to the top of your file. Remember it's a named export.

• Property 'data' does not exist on type 'unknown'.

  cause This error occurs when you attempt to access properties like `data` or `error` on the `APISuccess` or `APIFailure` instances without properly defining the type parameters (`T` and `U`) in `APIResponse<T, U>`, or without implementing the decoding functions correctly.
  fix Ensure your `APIResponse` is correctly typed (e.g., `APIResponse<MyDataType, ErrorType>`) and that the success/error decoding functions passed to `APICaller.call` return the expected types. The example's `(successResponse: unknown) => successResponse as Post[]` is a minimal cast; for production, implement actual type guards or decoders.

Warnings

• breaking Prior to version 5.1.1, users utilizing CommonJS environments or specific bundler configurations might have encountered issues resolving the main package entrypoint.
  Fix: Upgrade to `typesafe-api-call@^5.1.1` or later to ensure proper module resolution across different environments. Prefer ESM imports where possible.
• gotcha This library replaces traditional `try/catch` blocks for network and API errors with a functional result pattern (`APISuccess` | `APIFailure`). Direct exception handling for API calls will bypass this pattern.
  Fix: Always check the `APIResponse` object using `if (response instanceof APISuccess)` or `if (response instanceof APIFailure)` to handle outcomes, rather than relying on `try/catch` for HTTP-level errors.
• gotcha The `call` method requires two decoding functions: one for a successful API response and one for an erroneous API response. If these are not provided or implemented correctly, the `data` or `error` properties within `APISuccess` or `APIFailure` will remain `unknown`.
  Fix: Implement robust decoding logic within the success and error callbacks passed to `APICaller.call`. Consider using complementary libraries like `type-decoder` for structured decoding.
• gotcha The `url` property in `APIRequest` strictly expects a `URL` object, not a string. Passing a string will result in a runtime TypeError.
  Fix: Ensure that the `url` property of your `APIRequest` object is always instantiated as `new URL('your-api-endpoint')`.

Install

• npm install typesafe-api-call npm
• yarn add typesafe-api-call yarn
• pnpm add typesafe-api-call pnpm

Imports

• APICaller
  wrong:

  const APICaller = require('typesafe-api-call').APICaller;

  correct:

  import { APICaller } from 'typesafe-api-call';

  ESM is the primary module system. While `packageJson.main` was patched in v5.1.1 for CJS compatibility, direct ESM imports are recommended for modern Node.js and bundlers.
• APIResponse
  wrong:

  import APIResponse from 'typesafe-api-call';

  correct:

  import { APIResponse } from 'typesafe-api-call';

  APIResponse is a named export, not a default export. Ensure correct destructuring.
• APISuccess
  wrong:

  import { APISuccess } from 'typesafe-api-call/lib';

  correct:

  import { APISuccess } from 'typesafe-api-call';

  The library exports directly from its root. Do not attempt to import from internal paths like `/lib` as these are not stable API surfaces.
• APIRequest (type)

  import type { APIRequest } from 'typesafe-api-call';

  For type-only imports, use `import type` to ensure they are stripped from the JavaScript output, preventing potential runtime errors in certain environments.

Quickstart

Demonstrates a basic GET API call using `APICaller`, showing how to define a request, provide decoding functions, and handle the explicit `APISuccess` or `APIFailure` result.

import { APICaller, APIResponse, type APIRequest, APISuccess } from 'typesafe-api-call';

interface Post {
  userId: number;
  id: number;
  title: string;
  body: string;
}

const serverEndpoint = 'https://jsonplaceholder.typicode.com';

async function getAllPosts(): Promise<APIResponse<Post[], unknown>> {
  const apiRequest: APIRequest = {
    url: new URL(`${serverEndpoint}/posts`),
    method: 'GET'
  };

  // Using an anonymous function for decoding. In a real app, you'd use a dedicated decoder.
  const apiResponse = await APICaller.call(
    apiRequest,
    (successResponse: unknown) => successResponse as Post[], // Simulate decoding
    (errorResponse: unknown) => errorResponse // Error handling can also include decoding
  );
  return apiResponse;
}

async function runExample() {
  console.log('Fetching all posts...');
  const getAllPostResult = await getAllPosts();

  if (getAllPostResult instanceof APISuccess) {
    console.log('Successfully fetched posts:', getAllPostResult.data.slice(0, 2));
  } else {
    console.log('Failed to fetch posts:', getAllPostResult.error);
  }
}

runExample();