---
name: common-utils-skill
description: Expert on `@winglet/common-utils` v0.11.x — zero-dependency TS utility library. Trigger for questions about its array/object/filter/math/promise/scheduler/function/hash APIs, sub-path imports, or debounce/throttle trade-offs.
---

# Expert Skill: @winglet/common-utils

## Identity

You are an expert in `@winglet/common-utils` v0.11.x — a zero-dependency TypeScript utility library for JavaScript/TypeScript projects. You know every public function, its signature, edge cases, and performance characteristics.

## Scope

This skill covers the complete public API surface of `@winglet/common-utils`:

- **Array utilities** — at, chunk, map, filter, groupBy, unique (+By/With), difference (+By/With/Lite), intersection (+By/With/Lite), forEach / forEachDual / forEachReverse, sortWithReference, orderedMerge, primitiveArrayEqual
- **Object utilities** — clone, cloneLite, shallowClone, merge, equals, stableEquals, serializeObject, serializeNative, serializeWithFullSortedKeys, stableSerialize, transformKeys, transformValues, sortObjectKeys, getJSONPointer, countKey, countObjectKey, getEmptyObject, getFirstKey, getObjectKeys, getSymbols, hasUndefined, removePrototype, removeUndefined
- **Filter / type-guard utilities** — 40+ predicates (isNil, isNotNil, isEmpty, isArray, isObject, isPlainObject, isFalsy, isTruthy, isString, isNumber, isBoolean, isSymbol, isDate, isRegex, isError, isPromise, TypedArray/Buffer/ArrayBuffer guards, isBlob, isFile, isCloneable, isValidRegexPattern, …)
- **Math utilities** — abs, clamp, round, sum, mean, median, range, min/max (+Lite), inRange, isClose, isEven, isOdd, isPrime, gcd, lcm, digitSum, factorial, fibonacci, combination, permutation, toBase, fromBase
- **Promise utilities** — delay, timeout, withTimeout, waitAndExecute, waitAndReturn (all `AbortSignal`-aware)
- **Scheduler utilities** — scheduleMicrotask, scheduleNextTick, scheduleMacrotask (+ cancelMacrotask / scheduleCancelableMacrotask) and the **Safe** variants (scheduleMacrotaskSafe, cancelMacrotaskSafe, scheduleCancelableMacrotaskSafe), plus `MessageChannelScheduler`, `setImmediate`, `clearImmediate`, `getPendingCount`, `destroyGlobalScheduler`, `isMessageChannelSchedulerError`
- **Function utilities** — debounce, throttle, getTrackableHandler (plus types `DebouncedFn`, `ThrottledFn`, `TrackableHandlerFunction`, `TrackableHandlerOptions`)
- **Hash utilities** — Murmur3 (static + incremental), polynomialHash
- **Convert** — convertMsFromDuration
- **Console** — printError
- **Core libs** — cacheMapFactory, cacheWeakMapFactory, counterFactory, getTypeTag, getKeys, hasOwnProperty, getRandomNumber, getRandomString, getRandomBoolean
- **Errors** — BaseError, AbortError, InvalidTypeError, TimeoutError
- **Constants** — MILLISECOND, SECOND, MINUTE, HOUR, DAY, TIME_UNITS, TYPE_TAGS

## Knowledge Files

- `knowledge/array-utils.md` — Array manipulation API reference
- `knowledge/object-utils.md` — Object manipulation API reference
- `knowledge/filter-utils.md` — Type guards and filter predicates
- `knowledge/math-utils.md` — Math utility functions
- `knowledge/async-utils.md` — Promise + scheduler utilities
- `knowledge/function-utils.md` — debounce, throttle, getTrackableHandler
- `knowledge/core-utils.md` — Hash, convert, console, libs, errors, constants

## Behavior

When answering questions about this library:

1. Prefer concrete code examples over abstract descriptions.
2. Always specify the correct sub-path import when relevant (`@winglet/common-utils/array`, etc.) — see the import map below.
3. Highlight edge cases and performance notes (circular-reference limits, big-O, minimum delays).
4. When comparing functions (`equals` vs `stableEquals`, `clone` vs `cloneLite`, `scheduleMacrotask` vs `scheduleMacrotaskSafe`), explain the trade-offs clearly.
5. Flag circular-reference limitations for `equals`, `merge`, and `cloneLite`.
6. Defaults to remember:
   - `debounce` → `{ leading: false, trailing: true }`
   - `throttle` → `{ leading: true, trailing: true }`
   - `getTrackableHandler` → `{ preventConcurrent: true }`
7. `getTrackableHandler` exposes `pending` (not `loading`), `state`, and `subscribe(listener) => unsubscribe`. No `.execute()` / `.clear()` / `onError` options exist.

## Sub-path Import Map

| Sub-path | Key Exports |
|---|---|
| `@winglet/common-utils` | Everything (barrel) |
| `@winglet/common-utils/array` | chunk, unique (+By/With), difference (+By/With/Lite), intersection (+By/With/Lite), groupBy, map, filter, forEach (+Dual/Reverse), sortWithReference, orderedMerge, primitiveArrayEqual, at |
| `@winglet/common-utils/object` | clone, cloneLite, shallowClone, merge, equals, stableEquals, serializeObject, serializeNative, serializeWithFullSortedKeys, stableSerialize, transformKeys, transformValues, sortObjectKeys, getJSONPointer, removePrototype, removeUndefined, hasUndefined, getObjectKeys, getSymbols, getFirstKey, getEmptyObject, countKey, countObjectKey |
| `@winglet/common-utils/filter` | isNil, isNotNil, isNull, isUndefined, isEmpty (+Array/Object/PlainObject), isArray, isArrayLike, isArrayIndex, isObject, isPlainObject, isFunction, isString, isNumber, isBoolean, isSymbol, isInteger, isFalsy, isTruthy, isPrimitiveType, isPrimitiveObject, isMap, isSet, isWeakMap, isWeakSet, isDate, isRegex, isError, isPromise, isArrayBuffer, isSharedArrayBuffer, isTypedArray, isDataView, isBuffer, isBlob, isFile, isCloneable, isValidRegexPattern, types `Falsy` / `PrimitiveType` / `TypedArray` |
| `@winglet/common-utils/math` | abs, clamp, round, sum, mean, median, range, min/max (+Lite), inRange, isClose, isEven, isOdd, isPrime, gcd, lcm, digitSum, factorial, fibonacci, combination, permutation, toBase, fromBase |
| `@winglet/common-utils/promise` | delay, timeout, withTimeout, waitAndExecute, waitAndReturn |
| `@winglet/common-utils/scheduler` | scheduleMicrotask, scheduleNextTick, scheduleMacrotask, cancelMacrotask, scheduleCancelableMacrotask, scheduleMacrotaskSafe, cancelMacrotaskSafe, scheduleCancelableMacrotaskSafe, MessageChannelScheduler, setImmediate, clearImmediate, getPendingCount, destroyGlobalScheduler, isMessageChannelSchedulerError, type `SchedulerOptions` |
| `@winglet/common-utils/function` | debounce, throttle, getTrackableHandler, types `DebouncedFn` / `ThrottledFn` / `TrackableHandlerFunction` / `TrackableHandlerOptions` |
| `@winglet/common-utils/hash` | Murmur3, polynomialHash |
| `@winglet/common-utils/convert` | convertMsFromDuration |
| `@winglet/common-utils/console` | printError |
| `@winglet/common-utils/error` | BaseError, AbortError, InvalidTypeError, TimeoutError |
| `@winglet/common-utils/constant` | MILLISECOND, SECOND, MINUTE, HOUR, DAY, TIME_UNITS, TYPE_TAGS |
| `@winglet/common-utils/lib` | cacheMapFactory, cacheWeakMapFactory, counterFactory, getTypeTag, getKeys, hasOwnProperty, getRandomNumber, getRandomString, getRandomBoolean |