my-super-utils

A powerful, type-safe JavaScript utility library — tiny, zero-dependency, TypeScript-first.

| Build | Bundle | |-------|--------| | ✅ TypeScript strict | 📦 CJS + ESM dual module | | ✅ ESLint | 🏷️ Full .d.ts types |

Install

npm install my-super-utils

Quick start

import { debounce, throttle, deepClone, formatTime, sleep } from 'my-super-utils';

// Debounce — delay invocation until calls stop
const save = debounce((val: string) => fetch('/api/save', { method: 'POST', body: val }), 300);

// Throttle — at most once per 200ms
const onScroll = throttle(() => console.log('scrolled'), 200);

// Deep clone
const copy = deepClone({ a: 1, b: { c: [1, 2, 3] } });

// Time formatting
formatTime(Date.now(), { relative: true });        // "刚刚"
formatTime('2025-06-04', { format: 'YYYY/MM/DD' }); // "2025/06/04"

// Async sleep
await sleep(1000);

API

Control flow

| Function | Signature | Description | |----------|-----------|-------------| | debounce | (fn, wait, opts?) => fn | Return a debounced function. Options: leading, trailing, maxWait. | | throttle | (fn, wait, opts?) => fn | Return a throttled function. Options: leading, trailing. | | sleep | (ms) => Promise<void> | Return a promise that resolves after ms milliseconds. | | once | (fn) => fn | Return a function that executes at most once, then caches the result. | | memoize | (fn, resolver?) => fn | Return a memoized function; cache key is String(args[0]) by default. |

Object

| Function | Signature | Description | |----------|-----------|-------------| | deepClone | <T>(value: T) => T | Deep clone via structuredClone (JSON fallback). | | pick | (obj, keys) => obj | Pick specified keys from an object. | | omit | (obj, keys) => obj | Omit specified keys from an object. | | merge | (target, ...sources) => obj | Deep merge sources into target. Arrays are replaced, not concatenated. |

Collection

| Function | Signature | Description | |----------|-----------|-------------| | range | (startOrEnd, end?, step?) => number[] | Generate a numeric range. range(5) → [0,1,2,3,4] | | shuffle | <T>(arr) => T[] | Fisher-Yates shuffle (returns a new array). | | groupBy | <T, K>(arr, fn) => Map<K, T[]> | Group elements by key. | | uniq | <T>(arr) => T[] | Return a new array with deduplicated values. |

Type checking

| Function | Signature | Description | |----------|-----------|-------------| | isNil | (v) => boolean | Check if value is null or undefined. | | isPlainObject | (v) => boolean | Check if value is a plain {} object. | | isEmpty | (v) => boolean | Check for empty: nil, '', [], {}, Set/Map. |

Time

| Function | Signature | Description | |----------|-----------|-------------| | formatTime | (date, opts?) => string | Format date: template (YYYY-MM-DD HH:mm) or relative ("3 小时前"). |

Scripts

| Command | Description | |---------|-------------| | npm run build | Build CJS + ESM bundles with Rollup | | npm run dev | Watch mode rebuild | | npm run typecheck | TypeScript type check (tsc --noEmit) | | npm run lint | ESLint check | | npm run lint:fix | Auto-fix ESLint issues |

License

MIT