npm package: @igoforth/ts-utils
Description: TypeScript utilities - caching, memoization, decorators, async, and more
Author: igoforth
Latest version: 0.1.0

# @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

```bash
pnpm add @igoforth/ts-utils
```

## Usage

### Caching

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

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

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

## License

MIT