ts-utils

한국어 · 0.8 migration guide

TypeScript utility modules for common application development.

Reusable helpers for API clients, runtime validation, sessions, async control flow, data conversion, formatting, and other everyday TypeScript tasks.

Install

npm install @maxxuxx/ts-utils

Or install directly from GitHub:

npm install github:maxxuxx/ts-utils

Quick start

Create a validated API client and reusable endpoint:

import {
  createApiFetcher,
  endpoint,
  z
} from "@maxxuxx/ts-utils/api-fetch";

const api = createApiFetcher({
  baseURL: "https://api.example.com",
  retry: {
    delay: 250,
    limit: 2,
    strategy: "exponential"
  },
  timeout: 5000
});

const User = z.object({
  id: z.number(),
  name: z.string()
});

const getUser = endpoint.get("/users/:id", {
  params: z.object({
    id: z.coerce.number().int().positive()
  }),
  responseSchema: User
});

const result = await api.call(getUser, {
  params: {
    id: 42
  }
});

console.log(result.response.name);

Featured modules

| Module | Use it for | |---|---| | api-fetch | Validated API clients, typed endpoints, auth refresh, retry, timeout, and hooks | | session | Token sessions for plain TypeScript, React, and SvelteKit applications | | parser | Reusable strict and coercing Zod parsers | | promise | Timeout, retry, parallel tasks, settling, and single-flight work | | json | Safe JSON parsing, stringifying, and schema validation | | jwt | JWT decoding, schema validation, and expiration checks |

Module map

| Entry point | Core role | Details | |---|---|---| | @maxxuxx/ts-utils/parser | Zod parser presets and wrappers for repeated runtime validation | parser | | @maxxuxx/ts-utils/is | Runtime type guards for primitives, objects, collections, and built-ins | is | | @maxxuxx/ts-utils/result | Discriminated success and failure values with mapping helpers | result | | @maxxuxx/ts-utils/try-catch | Result helpers for sync and async error boundaries | try-catch | | @maxxuxx/ts-utils/format | Formatting helpers for numbers, currency, dates, phone numbers, and units | format | | @maxxuxx/ts-utils/normalize | Small coercion helpers for stable number, text, date, and boolean values | normalize | | @maxxuxx/ts-utils/object | Plain object shaping helpers for request and response payloads | object | | @maxxuxx/ts-utils/url | Web path, API URL, and query string helpers | url | | @maxxuxx/ts-utils/promise | Timeout, retry, parallel, and settle helpers for promise tasks | promise | | @maxxuxx/ts-utils/json | JSON parse, stringify, fallback, safe result, and schema boundary helpers | json | | @maxxuxx/ts-utils/encoding | UTF-8, base64, hex, and byte conversion helpers | encoding | | @maxxuxx/ts-utils/encoding/base64url | Strict browser and Node base64url text and byte helpers | encoding/base64url | | @maxxuxx/ts-utils/jwt | JWT header and payload readers with expiration checks | jwt | | @maxxuxx/ts-utils/env | Runtime environment readers and Zod schema helpers | env | | @maxxuxx/ts-utils/time | Client/server timestamp helpers for estimating server time | time | | @maxxuxx/ts-utils/device | Runtime-selecting device UUID helper | device | | @maxxuxx/ts-utils/device/browser | Browser and renderer cookie-backed device UUID helpers | device/browser | | @maxxuxx/ts-utils/device/node | Node machine ID based device UUID helpers | device/node | | @maxxuxx/ts-utils/session | Framework-neutral token session controller | session | | @maxxuxx/ts-utils/session/sveltekit | SvelteKit cookie session factory | session/sveltekit | | @maxxuxx/ts-utils/session/react | React browser-storage token session helper | session/react | | @maxxuxx/ts-utils/api-fetch | Fetch API client with validation, refresh, retry, timeout, hooks, and endpoints | api-fetch | | @maxxuxx/ts-utils/api-fetch/sveltekit | SvelteKit adapter for api-fetch auth refresh | api-fetch/sveltekit | | @maxxuxx/ts-utils/http-response | Small Web Response helpers for route handlers | http-response |

Runtime notes

• The package is ESM-only and requires Node.js 22.12 or later for Node-targeted usage.
• Zod is the only direct runtime dependency and is re-exported from schema-oriented subpaths.
• React and iron-session are optional peer dependencies used only by their corresponding session adapters.
• General utility modules are designed for browser and server code; device helpers provide explicit browser and Node entry points.
• Detailed behavior, edge cases, and related APIs live in each module README linked above.

Development

npm run typecheck
npm run build