3.1.1 • Published 3d ago

@pawells/typescript-common

Licence

MIT

Version

3.1.1

Deps

Size

502 kB

Vulns

Weekly

Summary Dependency Versions

TypeScript Common Utility Library

Description

General-purpose TypeScript utility library organized into seven domain modules and four standalone modules. All functions are pure, strongly typed, and tree-shakeable via a single public barrel export.

Domain modules: array, enum, error, function, object, string, time

Standalone modules: LRU cache, JSON sanitization, Zod schemas, async retry with exponential backoff

The package is ESM-only, targets Node.js >= 22, and ships with full TypeScript declarations and source maps.

Requirements

Node.js: >= 22.x
TypeScript: >= 6.x
Module system: ESM ("type": "module" — CommonJS is not supported)
Bundled runtime dependency: zod (^4.4.3) is installed automatically as a regular dependencies entry — it is not a peer dependency you need to install yourself. Import Zod-derived symbols (OBJECT_ID_SCHEMA, SEMVER_SCHEMA, etc.) from @pawells/typescript-common itself, not from 'zod/v4' directly (see Zod Utilities below).

Installation

npm install @pawells/typescript-common
# or
yarn add @pawells/typescript-common

Quick Start

import {
  ArrayChunk,
  ArrayPartition,
  ObjectPick,
  ObjectMerge,
  CamelCase,
  IsBlankString,
  EnumValues,
  BaseError,
  GetErrorMessage,
  Debounce,
  WithRetry,
  ElapsedTime,
  Stopwatch,
  LRUCache,
} from '@pawells/typescript-common';

// --- Array ---
ArrayChunk([1, 2, 3, 4, 5], 2);
// → [[1, 2], [3, 4], [5]]

const [evens, odds] = ArrayPartition([1, 2, 3, 4], (n) => n % 2 === 0);
// evens → [2, 4], odds → [1, 3]

// --- Object ---
ObjectPick({ a: 1, b: 2, c: 3 }, ['a', 'c']);
// → { a: 1, c: 3 }

// --- String ---
CamelCase('hello-world'); // → 'helloWorld'
IsBlankString('   '); // → true

// --- Function ---
const debouncedSave = Debounce(save, 300);
debouncedSave(); // fires after 300 ms of silence
debouncedSave.cancel(); // cancels any pending invocation

// --- Retry ---
const data = await WithRetry(() => fetchFromApi(), {
  maxRetries: 3,
  initialDelay: 500,
});

// --- Time ---
const sw = new Stopwatch();
sw.Start();
// ... work ...
sw.Stop();
console.log(sw.Elapsed.Format('short')); // e.g. '1s 234ms'

// --- LRU Cache ---
const cache = new LRUCache<string, number>(100);
cache.set('key', 42);
cache.get('key'); // → 42

// --- Object / Enum / Error ---
const merged = ObjectMerge({ a: 1 }, { b: 2 }); // → { a: 1, b: 2 }

enum Status { Active = 'active', Inactive = 'inactive' }
EnumValues(Status); // → ['active', 'inactive']

try {
  throw new BaseError('Something failed', { code: 'EXAMPLE_ERROR' });
}
catch (error) {
  console.log(GetErrorMessage(error)); // → 'Something failed'
}

API Reference

All symbols are re-exported from the single package entry point @pawells/typescript-common. There are no supported deep import paths.

Array

Functions for transforming, filtering, and querying arrays.

Symbol	Kind	Description
`ArrayChunk<T>(array, size)`	function	Splits an array into sub-arrays of `size`. Returns `[]` for null/undefined input or non-positive size.
`ArrayCompact<T>(array)`	function	Removes `null` and `undefined` elements, narrowing the return type to `T[]`.
`ArrayContains<T>(array, predicate)`	function	Returns `true` if any element satisfies the predicate.
`ArrayCountBy<T, K>(array, keyFn)`	function	Groups elements by key and returns a count map.
`ArrayDifference<T>(a, b, options?)`	function	Returns elements in `a` that are not in `b`. Supports custom comparator, deep equality, or key function.
`TArrayElement<A>`	type	Extracts the element type of an array type: `TArrayElement<string[]>` → `string`.
`ArrayFilter<T>(array, filter, options?)`	function	Filters array elements against a partial filter criteria object.
`ArrayFlatten<T>(array, depth?)`	function	Recursively flattens a nested array to the given depth (default: `Infinity`).
`ArrayGroupBy<T, K>(array, keyFn)`	function	Groups elements by a derived key, returning a `Record<K, T[]>`.
`ArrayIntersection<T>(a, b, options?)`	function	Returns elements present in both arrays. Supports comparator, deep equality, or key function.
`ArrayPartition<T>(array, predicate)`	function	Splits into `[passing, failing]` — a typed tuple.
`ArrayRange(start, end, step?)`	function	Generates a numeric range array.
`ArraySample<T>(array)` / `ArraySample<T>(array, n)`	function	Returns one random element or `n` random elements without replacement.
`ArrayShuffle<T>(array, random?)`	function	Returns a new array with elements in random order (Fisher-Yates).
`ArraySortBy<T>(array, keyFn, order?)`	function	Returns a sorted copy using a key extractor; `order` defaults to `'asc'`.
`ArrayZip<T>(...arrays)`	function	Zips multiple arrays into an array of tuples.
`Unique<T>(array)`	function	Removes duplicate elements using strict equality.
`FilteredIterator<TObject, TArgs>(iterator, args?, validator?)`	async generator	Async generator that filters an async iterable by optional criteria object and/or predicate.
`TPredicate<T>`	type	`(value: T) => boolean`
`TTransform<TInput, TOutput>`	type	`(input: TInput) => TOutput`
`TComparator<T>`	type	`(a: T, b: T) => number`
`TEqualityComparator<T>`	type	`(a: T, b: T) => boolean`
`TArrayComparisonOptions<T>`	type	Discriminated union for array comparison strategy: `comparator`, `useDeepEqual`, or `keyFn`.

Enum

Type-safe helpers for querying and coercing TypeScript enum members.

Symbol	Kind	Description
`EnumEntries<T>(e)`	function	Returns `[key, value]` pairs for all enum members, filtering reverse-mapping keys.
`EnumKeyByValue<T>(e, value)`	function	Looks up the key name for a given enum value; returns `undefined` if not found.
`EnumKeys<O>(obj)`	function	Returns the string keys of an enum, filtering out numeric reverse-mapping keys.
`EnumSafeValue<T>(e, value, fallback)`	function	Returns `value` if it is a valid enum member, otherwise `fallback`.
`EnumValues<TEnum>(e)`	function	Returns the values of an enum as a typed array.
`ValidateEnumValue<T>(e, value)`	function	Returns `true` if `value` is a member of the enum.
`TEnumValue`	type	`string \| number`
`TEnumType`	type	`Record<string, TEnumValue>`

Error

Custom error base class and safe extraction utilities.

Symbol	Kind	Description
`BaseError<TMetadata>`	class	Extends `Error` with a `Code` string, a typed `Metadata` bag, and a prototype-chain fix for correct `instanceof` checks after transpilation. All custom errors should extend `BaseError`.
`TErrorMetadata`	type	`{ code?: string; cause?: Error }`
`AssertErrorMetadata(metadata)`	function	Asserts (throws via Zod) that `metadata` conforms to `TErrorMetadata`.
`ValidateErrorMetadata(metadata)`	function	Returns `true` if `metadata` conforms to `TErrorMetadata`, `false` otherwise.
`ERROR_METADATA_SCHEMA`	const	Zod schema backing `TErrorMetadata`; validates `{ code?: string; cause?: Error }`.
`GetErrorMessage(error)`	function	Returns `error.message` for `Error` instances; `String(error)` for everything else. Safe to call in `catch` blocks with `unknown`.
`GetErrorStack(error)`	function	Returns `error.stack` for `Error` instances when defined; `undefined` otherwise.

Function

Higher-order utilities for controlling function execution.

Symbol	Kind	Description
`Compose(...fns)`	function	Right-to-left function composition. Up to five type-safe overloads; falls back to untyped for more.
`Debounce<T>(fn, wait)`	function	Returns a debounced function that delays invocation until `wait` ms have passed since the last call. The returned function has a `.cancel()` method.
`Memoize<T>(fn, resolver?)`	function	Returns a memoized function that caches results by arguments. Accepts an optional custom cache-key resolver.
`Once<T>(fn)`	function	Returns a function that calls `fn` only on the first invocation; subsequent calls return the cached result.
`Pipe(...fns)`	function	Left-to-right function composition. Up to five type-safe overloads.
`Sleep(ms)`	function	Returns a `Promise<void>` that resolves after `ms` milliseconds.
`Throttle<T>(fn, limit)`	function	Returns a throttled function that fires at most once per `limit` ms. The returned function has a `.cancel()` method.
`TAnyFunction`	type	`(...args: any[]) => any`
`TAsyncFunction<T>`	type	`(...args: any[]) => Promise<T>`
`TConstructorFunction<T>`	type	`new (...args: never[]) => T`

Object

Utilities for cloning, diffing, picking, merging, hashing, and filtering plain objects.

Symbol	Kind	Description
`CreateCircularReferenceDetector()`	function	Returns a detector object that tracks visited references to prevent circular-reference attacks.
`CreateJsonCircularReplacer()`	function	Returns a `JSON.stringify` replacer that replaces circular references with `'[Circular]'`.
`FilterDangerousKeys<T>(obj)`	function	Removes keys that could enable prototype pollution (`__proto__`, `constructor`, `prototype`).
`FilterObject<T>(obj, predicate)`	function	Returns a `Partial<T>` containing only the properties for which `predicate` returns `true`.
`IsInputSafe(input, maxLength?)`	function	Returns `true` if `input` passes basic safety checks (no `null`-byte injection, within length limit).
`IsObject(item)`	function	Type guard — returns `true` if `item` is a plain object (not `null`, not an array).
`IsPropertyKeySafe(key)`	function	Returns `true` if `key` is safe to use as a property name (no prototype-pollution risk).
`IsPropertyPathSafe(path)`	function	Returns `true` if every segment of a dot-notation path is safe.
`ObjectClone<T>(obj)`	function	Deep-clones a value using structured clone (falls back to JSON round-trip).
`ObjectDiff(a, b)`	function	Returns an `IObjectDiffResult` describing added, removed, and changed keys.
`ObjectEquals(a, b)`	function	Deep structural equality check.
`ObjectFilter<T>(object, filter, options?)`	function	Returns `true` if `object` matches all key/value pairs in `filter`.
`ObjectFilterCached<T>(options?)`	function	Returns a cached synchronous filter function that reuses compiled filter predicates.
`ObjectFlatten(obj, separator?)`	function	Flattens a nested object to dot-notation keys.
`ObjectFromKeyValuePairs<T>(entries)`	function	Constructs a `Record<string, T>` from `[key, value]` pairs.
`ObjectGetPropertyByPath<T>(obj, path, defaultValue?)`	function	Reads a nested property by dot-notation path. Returns `defaultValue` (or `undefined`) on missing.
`ObjectHash(obj, hashFunction?)`	function	Produces a stable deterministic hash string for a plain object.
`ObjectHasCircularReference(obj)`	function	Returns `true` if `obj` contains at least one circular reference.
`ObjectInvert<T>(obj)`	function	Swaps keys and values, returning a new object.
`MapObjectCached<T>(options?)`	function	Returns a cached synchronous map function that reuses compiled property mappers.
`ObjectMerge<T>(target, source)`	function	Deeply merges `source` into `target` (nested plain objects recurse, arrays concatenate), returning a new object without mutating `target` or `source`.
`ObjectOmit<T, K>(obj, keys)`	function	Returns a copy of `obj` with the specified keys removed.
`ObjectPick<T, K>(obj, keys)`	function	Returns a new object containing only the specified keys.
`ObjectSetPropertyByPath<T>(obj, path, value)`	function	Sets a nested property by dot-notation path, creating intermediate objects as needed.
`ObjectSortKeys<T>(object)`	function	Returns a copy of `object` with keys sorted alphabetically.
`ObjectToKeyValuePairs<T>(obj)`	function	Converts a `Record<string, T>` to `[key, value]` pairs.
`SanitizePropertyKey(key)`	function	Returns a safe version of `key`, or `undefined` if it cannot be sanitized.
`TransformObject<TInput, TOutput>(obj, transformer)`	function	Applies a transformation function to an object, returning a new object.
`MapObject<T>(obj, mapper)`	function	Maps each property of `obj` through `mapper`, returning a new `Record`.
`IObjectDiffResult`	interface	`{ added: string[]; removed: string[]; changed: string[] }`
`IObjectFilterOptions`	interface	Options for `ObjectFilter`: `useDeepEqual`, `caseInsensitiveStrings`, `validatePaths`.
`ICachedObjectFilterOptions`	interface	Options for `ObjectFilterCached`: `maxCacheSize`, plus the `IObjectFilterOptions` fields (`useDeepEqual`, `caseInsensitiveStrings`, `validatePaths`).
`ICachedObjectMapOptions`	interface	Options for `MapObjectCached`: `maxCacheSize`.
`ICircularReferenceDetector`	interface	Exposes `markVisited(obj)`, `isVisited(obj)`, and `clear()` for circular-reference tracking.
`TPropertyMapper<T, K>`	type	`(key: K, value: T[K]) => unknown`
`TPropertyFilter<T, K>`	type	`(key: K, value: T[K]) => boolean`
`DEFAULT_CACHED_OBJECT_MAX_SIZE`	const	Default `maxCacheSize` (1000) used by `ObjectFilterCached` and `MapObjectCached` when not overridden.
`TCachedObjectFilterFunction<T>`	type	`(cursor: T, filter: Partial<Record<string, unknown>>) => boolean`
`TCachedObjectMapperFunction<T>`	type	`(cursor: T, mapper: TPropertyMapper<T>, mapperKey?: string) => Record<keyof T, unknown>`
`TObjectPredicate<T>`	type	`(obj: T) => boolean`
`TObjectTransformer<TInput, TOutput>`	type	`(input: TInput) => TOutput`
`TObjectComparator<T>`	type	`(a: T, b: T) => number`
`TObjectEqualityComparator<T>`	type	`(a: T, b: T) => boolean`

String

Case conversion, formatting, transformation, validation, and comparison utilities.

Symbol	Kind	Description
`CamelCase(value)`	function	Converts a string to camelCase.
`Capitalize(value)`	function	Uppercases the first character and lowercases the rest.
`CountOccurrences(str, substr)`	function	Counts non-overlapping occurrences of `substr` in `str`.
`EscapeHTML(str)`	function	Replaces `&`, `<`, `>`, `"`, and `'` with HTML entities.
`EscapeNewlines(s)`	function	Replaces literal newline characters with `\n`.
`FormatString(template, params)`	function	Interpolates named or positional placeholders in a template string.
`IsBlankString(value)`	function	Returns `true` if the string is empty or contains only whitespace.
`IsHexString(value)`	function	Returns `true` if the string is a valid hexadecimal string.
`KebabCase(value)`	function	Converts a string to kebab-case.
`PadString(str, length, char?, padEnd?)`	function	Pads `str` to `length` with `char` on the start or end.
`PascalCase(value)`	function	Converts a string to PascalCase.
`Pluralize(word, count, plural?)`	function	Returns the singular or plural form of a word based on `count`.
`ReverseString(input)`	function	Reverses the characters in a string.
`ScreamingSnakeCase(value)`	function	Converts a string to SCREAMING_SNAKE_CASE.
`Slugify(input)`	function	Converts a string to a URL-safe slug (lowercase, hyphens, no special characters).
`SnakeCase(value)`	function	Converts a string to snake_case.
`StripHTML(str)`	function	Removes all HTML tags from a string.
`StringEquals(a, b, caseInsensitive?)`	function	Compares two strings for equality, optionally case-insensitively.
`TruncateString(str, maxLength, ellipsis?)`	function	Truncates `str` to `maxLength` characters, appending `ellipsis` (default `'...'`) if truncated.
`WordCount(str)`	function	Returns the number of whitespace-delimited words in `str`.
`TCaseConverter`	type	`(value: string) => string`
`TFormatArgs`	type	`TFormatValue[]`
`TFormatParams`	type	`Record<string, TFormatValue>`
`TFormatValue`	type	`string \| number \| boolean \| null \| undefined`
`TStringFormatter`	type	`(value: string, ...params: unknown[]) => string`
`TStringPredicate`	type	`(value: string) => boolean`
`TStringTransformer`	type	`(input: string) => string`
`TStringValidator`	type	`(value: string) => boolean`

Time

Value-objects and classes for measuring and formatting durations.

Symbol	Kind	Description
`ElapsedTime`	class	Immutable value-object representing a duration in milliseconds. Provides `Format(preset)` and numeric/padded component getters (`Hours`, `HoursPadded()`, `TotalSeconds`, etc.).
`FormatElapsedTime(milliseconds, options?)`	function	Formats a raw millisecond count as a human-readable duration string.
`Stopwatch`	class	Records timestamped events: `Start()`, `Stop()`, `Pause()`, `Resume()`, `Click()`, `Lap()`, and `Reset()`. Returns `ElapsedTime`/`StopwatchEntry` instances from timing methods.
`StopwatchEntry`	class	Represents a single timestamped stopwatch event (`timestamp`, `Elapsed`, `ElapsedTotal`).
`StopwatchError`	class	Thrown by `Stopwatch` when operations are called in an invalid state (e.g., calling `Resume()` after `Stop()`).
`ITimeElapsedFormatOptions`	interface	Configuration for `ElapsedTime.Format()`: unit labels, format preset, and separator.
`ITimeUnitValue`	interface	`{ unit: TTimeUnit; value: number }` — a single time unit with its numeric value.
`IUnitLabelMap`	interface	Maps each `TTimeUnit` to a singular and plural label string or function.
`TTimeElapsedFormats`	type	`'concise' \| 'short' \| 'medium' \| 'long' \| 'mostSignificant' \| 'time' \| 'timeWithSeconds'`
`TTimeUnit`	type	`'week' \| 'day' \| 'hour' \| 'minute' \| 'second' \| 'millisecond'`

LRU Cache (standalone)

Symbol	Kind	Description
`LRUCache<K, V>`	class	Fixed-capacity Least Recently Used cache. Both `get()` and `set()` update recency order. Evicts the least recently used entry when capacity is reached. Do not cache sensitive values such as tokens or PII.

JSON Sanitization (standalone)

Symbol	Kind	Description
`SanitizeJsonSchema(schema)`	function	Recursively removes all keys that begin with `$` from a plain object. Designed for stripping JSON Schema metadata before storage (e.g., MongoDB). Returns `Record<string, unknown>`.

Zod Utilities (standalone)

All schemas use zod v4 and must be imported with import ... from '@pawells/typescript-common' (not directly from 'zod/v4').

Symbol	Kind	Description
`OBJECT_ID_SCHEMA`	const	Zod schema that validates a 24-character hexadecimal MongoDB ObjectId string.
`TObjectId`	type	`z.infer<typeof OBJECT_ID_SCHEMA>`
`SEMVER_SCHEMA`	const	Zod schema that validates and transforms a semver string into a `SemVer` instance.
`ZOD_OBJECT_SCHEMA`	const	Zod schema that validates a value is a `ZodObject` instance.
`TZodObjectSchema`	type	`z.infer<typeof ZOD_OBJECT_SCHEMA>`
`JSON_SERIALIZABLE_SCHEMA`	const	Recursive Zod schema accepting any JSON-serializable value.
`TJSONSerializable`	type	`string \| number \| boolean \| null \| TJSONSerializable[] \| { [key: string]: TJSONSerializable }`
`JSON_OBJECT_SCHEMA`	const	Zod schema for a `Record<string, TJSONSerializable>`.
`JSON_DATE_SCHEMA`	const	Zod schema that parses an ISO date string into a `Date`. Does not reject `Invalid Date` — chain `.refine(d => !isNaN(d.getTime()))` for strict validation.

Retry (standalone)

Symbol	Kind	Description
`WithRetry<T>(fn, config?)`	function	Wraps an async function with exponential backoff and ±20% jitter. Default: 3 retries, 1 s initial delay, 30 s cap, ×2 multiplier.
`IRetryConfig`	interface	Options: `maxRetries`, `initialDelay`, `maxDelay`, `backoffMultiplier`, `onError` (return `false` to abort early).