@igoforth/ts-utils

TypeScript utilities for modern applications - featuring caching, memoization, decorators, async primitives, and more.

Features

• Caching: LRU cache, instance cache, callback cache
• Memoization: Advanced memoization with WeakMap support
• Async Utilities: Mutex, async queue, pause
• Decorators: Injectable, Log, ReadOnly, Catch for TypeScript decorators
• Type Guards: Comprehensive runtime type checking
• Object Utilities: Deep clone, merge, path operations
• JSON Utilities: Deep diff, clone, walk, apply
• Number Utilities: Clamp, rounding, modulus, range checking
• Hash Utilities: Stable JSON hashing
• Utility Types: Advanced TypeScript type utilities

Installation

pnpm add @igoforth/ts-utils

Usage

Caching

import { LRUCache, InstanceCache, CallbackCache } from '@igoforth/ts-utils/cache'

// LRU Cache
const cache = new LRUCache<string, number>(5)
cache.set('key', 42)
const value = cache.get('key') // 42

// Instance Cache
class MyClass {
  constructor(public id: string) {}
}
const instanceCache = new InstanceCache(MyClass)
const instance = await instanceCache.getOrCreateInstance('id1')

// Callback Cache
const callbackCache = new CallbackCache()
const result = callbackCache.call(expensiveFunction, arg1, arg2)

Async Utilities

import { Mutex, AsyncAwaitQueue, pause } from '@igoforth/ts-utils/async'

// Mutex for exclusive access
const mutex = new Mutex()
await mutex.acquire(async () => {
  // Critical section
})

// Async queue with timeout
const queue = new AsyncAwaitQueue()
const success = await queue.await(100)
queue.notify()

// Async pause
await pause()

Memoization

import { memo, simpleMemorize } from '@igoforth/ts-utils/memo'

// Memoize function generators
const fn = memo({ key: 'value' }, (params) => () => {
  return computeExpensiveValue(params)
})

// Simple memoization
const memoized = simpleMemorize((a: number, b: number) => a + b)

Decorators

import { Injectable, Log, ReadOnly, Catch, instrument } from '@igoforth/ts-utils/decorators'

@Injectable()
class MyService {
  @Log('info')
  async fetchData() {
    return await fetch('/api/data')
  }

  @Catch('null', true)
  async mayFail() {
    return await riskyOperation()
  }
}

// Function instrumentation
const instrumented = instrument('myFunction', myFunction)

Type Guards

import {
  isDefined,
  isArray,
  isObject,
  isUnknownRecord,
  isString,
  isNumber,
} from '@igoforth/ts-utils/guards'

if (isDefined(value)) {
  // value is not null or undefined
}

if (isUnknownRecord(obj)) {
  // obj is a plain object
}

Object Utilities

import {
  objectsEqual,
  mergeDefaults,
  deepFreeze,
  getPath,
  setPath,
} from '@igoforth/ts-utils/object'

// Deep equality check
const equal = objectsEqual(obj1, obj2)

// Merge with defaults
const config = mergeDefaults(userConfig, defaultConfig)

// Deep freeze
const frozen = deepFreeze(obj)

// Path operations
const value = getPath(obj, 'a.b.c')
setPath(obj, 'a.b.c', newValue)

JSON Utilities

import {
  jsonDiff,
  deepClone,
  shallowClone,
  jsonWalk,
} from '@igoforth/ts-utils/json'

// JSON diff
const diff = jsonDiff(oldData, newData)

// Deep clone
const clone = deepClone(originalObject)

// Walk JSON tree
jsonWalk(data, (node) => {
  console.log(node)
  return acc
})

Number Utilities

import {
  clamp,
  round,
  mod,
  isNumberEqual,
  findMinMax,
} from '@igoforth/ts-utils/number'

// Clamp value
const clamped = clamp(0, value, 100)

// Round to decimals
const rounded = round(3.14159, 2) // 3.14

// True modulus (not remainder)
const modulo = mod(-5, 3) // 1

// Epsilon equality
const equal = isNumberEqual(0.1 + 0.2, 0.3) // true

Hash Utilities

import { calculateHash } from '@igoforth/ts-utils/hash'

const hash = calculateHash({ key: 'value', nested: { data: 123 } })
// Produces stable SHA-256 hash

License

MIT