Skip to content

MSF TypeScript – Module Outline

@msflib/typescript is the shared, framework-agnostic TypeScript/JavaScript utility package for the MSF ecosystem. It ships a fetch-based HTTP client with consistent error handling plus a set of small object, function and string helpers. It has no runtime dependencies, works in any modern browser or Node 20+, and is the HTTP layer underneath @msflib/core in the msflib React modules.

Quick Start

1. Configure the registry (once)

The package lives on GitHub Packages. Create a GitHub personal access token (classic) with read:packages, export it as GITHUB_TOKEN, and add this .npmrc to your project:

@msflib:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

2. Install

pnpm add @msflib/typescript

3. Create a client and make a call

import { createApiClient, ApiResponseError } from '@msflib/typescript';

const { apiClient } = createApiClient({
  baseURL: 'https://api.example.com',
  getAccessToken: () => localStorage.getItem('access_token'),
});

try {
  const notes = await apiClient<{ id: number; title: string }[]>('GET', '/notes');
  console.log(notes);
} catch (error) {
  if (error instanceof ApiResponseError) {
    console.error(error.status, error.message, error.errors);
  }
}

That's it. For login, file uploads, error display and common gotchas, see the full Quick Start.

Core module

  • Errors (error.ts, type.ts) — The foundation the HTTP client is built on. UserError (a user-safe message plus cause) and its subclass ApiResponseError (status, statusText, field-level errors, raw body); defaultErrorBodyParser, which understands FastAPI, Laravel-style and generic error bodies; the ErrorBodyParser hook for custom shapes; and the ClientErrorDispatch event contract for global error reporting.

Feature modules

  • HTTP Client (http.ts) — createApiClient returns three fetch wrappers sharing one config: apiClient (JSON, bearer token, query strings), apiFormDataClient (multipart uploads) and loginClient (x-www-form-urlencoded login). Supports preRequest/postRequest decorators and a pluggable error-body parser. Also exports buildQueryString.
  • Object Utilities (object.ts) — omit, pick, omitUndefined (drops undefined and null), nestedGet/nestedSet for dot-paths, toRecord for indexing lists by key, and asFormData for turning objects into FormData.
  • Function Utilities (function.ts) — debounce (trailing-edge).
  • String Utilities (string.ts) — makeId for deterministic, readable element ids and slugify for URL slugs.

Overall architecture

  • One package, one entry point: everything is re-exported from @msflib/typescript (src/index.ts), and types are exported alongside values. It is built with tsup to CommonJS (dist/index.js), ESM (dist/index.mjs) and type declarations (dist/index.d.ts).
  • The error layer is the foundation: createApiClient routes every failure through it. Network failures go through makeNetworkError and become a UserError. Non-2xx responses go through makeResponseError, which runs the configured ErrorBodyParser and returns an ApiResponseError. Both also notify the optional emitError callback, so an app gets a typed exception and a global event from the same place.
  • The HTTP client is stateless and framework-agnostic: auth is pulled per request from getAccessToken, and cross-cutting behavior plugs in through apiClientDecorator rather than by forking. Framework integrations (e.g. @msflib/core's configuredApiClient in the React modules) wrap it rather than reimplementing it.
  • The utility modules are independent of each other and of the HTTP layer, with no shared state, so you can use any one of them on its own.
  • Published to GitHub Packages under the @msflib scope (publish.yml, triggered by v*.*.* tags); CI runs the Vitest suite on pushes and PRs to main/dev.

Module index

Working on this repo

pnpm install
pnpm build      # tsup -> dist/
pnpm test       # vitest
pnpm lint       # tsc --noEmit

# docs (one-time setup, then serve/build)
python3 -m venv .venv-docs && .venv-docs/bin/pip install -r requirements-docs.txt
source .venv-docs/bin/activate
pnpm docs:serve # http://127.0.0.1:8000/docsite/typescript/
pnpm docs:build # mkdocs build --strict