@js-toolkit/utils

TypeScript utilities: helper functions, classes, FP data structures, and type helpers. Zero dependencies (optional @js-toolkit/node-utils for build minification).

Install

yarn add @js-toolkit/utils
# or
npm install @js-toolkit/utils

Import

Use subpath imports for tree-shaking:

import { EventEmitter } from '@js-toolkit/utils/EventEmitter';
import { debounce } from '@js-toolkit/utils/debounce';
import { getErrorMessage } from '@js-toolkit/utils/getErrorMessage';
import type { DeepPartial, RequiredStrict } from '@js-toolkit/utils/types';

API Overview

Classes and primitives

Module	Description
EventEmitter	Typed event emitter
Mutex	Async mutex with acquire/release
Queue	FIFO queue
CacheMap	Map with getOrCreate / getOrQueue
CancellablePromise	Promise with cancel support
DataEventEmitter	Event emitter with typed data payloads
Option, Try, Sink	FP data structures
List	Immutable list (collections/immutable)

Functions

Module	Description
noop	No-op function
clear	Clear array in place
debounce	Debounced function with isPending
delay	Delayed execution with cancel
delayed	Delayed promise
getErrorMessage	Extract message from unknown error
getAwaiter	Deferred promise (resolve/reject later)
promisify	Wrap sync fn in Promise
tryGet	Try thunk, return fallback on error
hasIn, hasOwn	Safe property checks
isEmptyObject	Check if object has no own keys
getEnumName, getEnumValues	Enum helpers
createDisposable	Create Symbol.dispose object
memoizeAsync	Async memoization
wait	Promise-based delay
escapeRegExp	Escape regex special chars

Types

Type	Description
DeepPartial, DeepRequired	Recursive partial/required
RequiredStrict, OptionalToUndefined	Strict optional handling
Merge, Diff, OmitStrict	Object type utilities
Keys, TupleToUnion, ArrayItem	Key and array helpers
MapToKey, GettersToProps	Mapped types
UnreachableCaseError	Exhaustive switch helper

Decorators

Module	Description
@bind	Bind method to instance

Logging

Module	Description
log	Logger with plugins (ConsolePlugin, LocalStoragePlugin)

Usage Examples

EventEmitter

import { EventEmitter } from '@js-toolkit/utils/EventEmitter';

interface Events {
  data: [payload: string];
  error: [err: Error];
}

const emitter = new EventEmitter<Events>();
emitter.on('data', (payload: string) => console.log(payload));
emitter.emit('data', 'hello');

Mutex

import { Mutex } from '@js-toolkit/utils/Mutex';

const mutex = new Mutex<string>();
const release = await mutex.acquire('worker-1');
try {
  // critical section
} finally {
  release[Symbol.dispose]();
}

tryGet and getErrorMessage

import { tryGet } from '@js-toolkit/utils/tryGet';
import { getErrorMessage } from '@js-toolkit/utils/getErrorMessage';

const input = '{"key":"value"}'; // e.g. from API or user
const value = tryGet(() => JSON.parse(input) as Record<string, unknown>, null);
if (value === null) {
  // parse failed
}

try {
  await fetch('/api/data'); // or any async operation
} catch (err: unknown) {
  console.error(getErrorMessage(err));
}

Exhaustive switch with UnreachableCaseError

import { UnreachableCaseError } from '@js-toolkit/utils/UnreachableCaseError';

type Status = 'idle' | 'loading' | 'done';

function handle(status: Status): string {
  switch (status) {
    case 'idle':
      return 'idle';
    case 'loading':
      return 'loading';
    case 'done':
      return 'done';
    default:
      throw new UnreachableCaseError(status);
  }
}

Option (FP)

import { Option } from '@js-toolkit/utils/fp/Option';

const value: string | null = null; // or from API, form, etc.
const opt = Option.of(value);
if (opt.nonEmpty()) {
  console.log(opt.get());
}
const result = opt.getOrElse('default');

debounce

import { debounce } from '@js-toolkit/utils/debounce';

async function fetchResults(query: string): Promise<void> {
  /* fetch and render */
}

const debouncedSearch = debounce((query: string) => void fetchResults(query), 300);
debouncedSearch('foo');
if (debouncedSearch.isPending) {
  // call is queued
}
debouncedSearch.cancel();

getAwaiter

import { getAwaiter } from '@js-toolkit/utils/getAwaiter';

const awaiter = getAwaiter<number>();
setTimeout(() => awaiter.resolve(42), 1000);
const value = await awaiter.wait(2000); // 42

Types

import type { DeepPartial, RequiredStrict, Keys } from '@js-toolkit/utils/types';

interface Config {
  a: number;
  b?: string;
}
type PartialConfig = DeepPartial<Config>;
type StrictConfig = RequiredStrict<Config>;
type ConfigKeys = Keys<Config>; // 'a' | 'b'

@bind decorator

import { bind } from '@js-toolkit/utils/decorators/bind';

class Handler {
  @bind
  handleClick() {
    // this is always bound
  }
}

Testing

yarn test

Repository

https://github.com/js-toolkit/utils