@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';importtype{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';interfaceEvents{data: [payload: string];error: [err: Error];}constemitter=newEventEmitter<Events>();emitter.on('data',(payload: string)=>console.log(payload));emitter.emit('data','hello');

Mutex

import{Mutex}from'@js-toolkit/utils/Mutex';constmutex=newMutex<string>();constrelease=awaitmutex.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';constinput='{"key":"value"}';// e.g. from API or userconstvalue=tryGet(()=>JSON.parse(input)asRecord<string,unknown>,null);if(value===null){// parse failed}try{awaitfetch('/api/data');// or any async operation}catch(err: unknown){console.error(getErrorMessage(err));}

Exhaustive switch with UnreachableCaseError

import{UnreachableCaseError}from'@js-toolkit/utils/UnreachableCaseError';typeStatus='idle'|'loading'|'done';functionhandle(status: Status): string{switch(status){case'idle':
return'idle';case'loading':
return'loading';case'done':
return'done';default:
thrownewUnreachableCaseError(status);}}

Option (FP)

import{Option}from'@js-toolkit/utils/fp/Option';constvalue: string|null=null;// or from API, form, etc.constopt=Option.of(value);if(opt.nonEmpty()){console.log(opt.get());}constresult=opt.getOrElse('default');

debounce

import{debounce}from'@js-toolkit/utils/debounce';asyncfunctionfetchResults(query: string): Promise<void>{/* fetch and render */}constdebouncedSearch=debounce((query: string)=>voidfetchResults(query),300);debouncedSearch('foo');if(debouncedSearch.isPending){// call is queued}debouncedSearch.cancel();

getAwaiter

import{getAwaiter}from'@js-toolkit/utils/getAwaiter';constawaiter=getAwaiter<number>();setTimeout(()=>awaiter.resolve(42),1000);constvalue=awaitawaiter.wait(2000);// 42

Types

importtype{DeepPartial,RequiredStrict,Keys}from'@js-toolkit/utils/types';interfaceConfig{a: number;b?: string;}typePartialConfig=DeepPartial<Config>;typeStrictConfig=RequiredStrict<Config>;typeConfigKeys=Keys<Config>;// 'a' | 'b'

@bind decorator

import{bind}from'@js-toolkit/utils/decorators/bind';classHandler{
@bindhandleClick(){// this is always bound}}

Testing

yarn test

Repository

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