@andrew_l/toolkit 0.2.12 → 0.2.14

package/dist/index.d.cts

@@ -43,6 +43,28 @@ declare function arrayable<T>(value: ArrayableValue<T>): ItemType<T>[];
  */
 declare const avg: (values: readonly number[]) => number;
 
+/**
+ * Computes the average of circular values using vector summation.
+ *
+ * This function calculates the circular mean of an array of values,
+ * which is useful for cyclic data (e.g., time of day, angles).
+ *
+ * @param {readonly number[]} values - The array of numbers representing circular values.
+ * @param {number} max - The maximum possible value in the cycle (e.g., 24 for hours, 360 for degrees).
+ * @returns {number} - The computed circular mean, wrapped within the range [0, max).
+ *
+ * @example
+ * // Averaging angles in degrees
+ * avgCircular([350, 10, 20], 360); // Returns approximately 0
+ *
+ * @example
+ * // Averaging times in hours (on a 24-hour clock)
+ * avgCircular([23, 1, 2], 24); // Returns approximately 0
+ *
+ * @group Array
+ */
+declare const avgCircular: (values: readonly number[], max: number) => number;
+
 /**
  * Splits an array into smaller sub-arrays (chunks) of a specified size.
  *
@@ -111,6 +133,8 @@ declare function chunkSeries(list: number[], step?: number): number[][];
  * const array3 = [1, 5];
  * const result = difference(array1, array2, array3);
  * // result will be [3] since 1, 2, 4 and 5 are in other arrays and are excluded from the result.
+ *
+ * @group Array
  */
 declare function difference<T>(...arrays: readonly T[][]): T[];
 
@@ -151,6 +175,8 @@ declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (
  * const array2 = [3, 4, 5, 6, 7];
  * const result = intersection(array1, array2);
  * // result will be [3, 4, 5] since these elements are in both arrays.
+ *
+ * @group Array
  */
 declare function intersection<T>(...arrays: readonly T[][]): T[];
 
@@ -213,9 +239,78 @@ declare function orderBy<T>(array: readonly T[], fields: (string | ((item: T) =>
  * const array = [1, 2, 3, 4, 5];
  * const shuffledArray = shuffle(array);
  * // shuffledArray will be a new array with elements of array in random order, e.g., [3, 1, 4, 5, 2]
+ *
+ * @group Array
  */
 declare function shuffle<T>(arr: readonly T[]): T[];
 
+/**
+ * Function that compares two elements and returns a number indicating their relative order.
+ * - Negative number if a < b
+ * - Zero if a equals b
+ * - Positive number if a > b
+ *
+ * @template T The type of elements in the array
+ */
+type SortedArrayCompareFn<T> = (a: T, b: T) => number;
+/**
+ * A self-sorting array that maintains elements in a sorted order based on a comparison function.
+ * All mutating operations preserve the sorted order of elements.
+ *
+ * @template T The type of elements in the array
+ *
+ * @example
+ * // Create a numerically sorted array
+ * const arr = new SortedArray((a, b) => a - b);
+ * arr.push(3, 2, 1);
+ * console.log(arr); // [1, 2, 3]
+ *
+ * @example
+ * // Create a sorted array with initial values
+ * const names = new SortedArray((a, b) => a.localeCompare(b), ["Charlie", "Alice", "Bob"]);
+ * console.log(names); // ["Alice", "Bob", "Charlie"]
+ *
+ * @example
+ * // Create a sorted array with a custom comparator
+ * const people = new SortedArray(
+ *   (a, b) => a.age - b.age || a.name.localeCompare(b.name),
+ *   [{ name: "Alice", age: 30 }, { name: "Bob", age: 25 }]
+ * );
+ *
+ * @group Array
+ */
+declare class SortedArray<T> extends Array<T> {
+    #private;
+    /**
+     * Creates a new SortedArray instance.
+     *
+     * @param compareFn The comparison function to determine the sort order
+     * @param items Optional initial items to add to the array (will be sorted immediately)
+     */
+    constructor(compareFn: SortedArrayCompareFn<T>, items?: T[]);
+    /**
+     * Inserts multiple items while maintaining sort order
+     * @param items The items to insert
+     * @returns The new length of the array
+     */
+    push(...items: T[]): number;
+    /**
+     * Override Array methods that would break the sorted order
+     */
+    unshift(...items: T[]): number;
+    /**
+     * Creates a new SortedArray with the same comparison function
+     * @returns A new SortedArray instance
+     */
+    slice(start?: number, end?: number): SortedArray<T>;
+    /**
+     * Concatenates arrays or values while maintaining sort order
+     * @param items Arrays or values to concatenate
+     * @returns A new SortedArray with the concatenated elements
+     */
+    concat(...items: (T | ConcatArray<T>)[]): SortedArray<T>;
+}
+
 /**
  * Sums the values in an array of numbers, ignoring non-numeric values.
  *
@@ -1620,7 +1715,7 @@ declare const ColorParser: {
  * Calculate crc32 hash from string
  * @group Crypto
  */
-declare function crc32(str: string, seed?: number): number;
+declare function crc32(current: Uint8Array | string, seed?: number): number;
 
 type DateObjectInput = Date | string | number | DateObject;
 declare function createDateObject(value: DateObjectInput): DateObject;
@@ -5138,4 +5233,4 @@ declare function wrapText(value: string, maxLength?: number): string;
  */
 declare function toError<T>(value: T, unknownMessage?: string): T extends Error ? T : Error;
 
-export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, base64ToBytes, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };
+export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSON as EJSONInstance, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EJSONType, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, SortedArray, type SortedArrayCompareFn, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, avgCircular, base64ToBytes, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };

package/dist/index.d.mts

@@ -43,6 +43,28 @@ declare function arrayable<T>(value: ArrayableValue<T>): ItemType<T>[];
  */
 declare const avg: (values: readonly number[]) => number;
 
+/**
+ * Computes the average of circular values using vector summation.
+ *
+ * This function calculates the circular mean of an array of values,
+ * which is useful for cyclic data (e.g., time of day, angles).
+ *
+ * @param {readonly number[]} values - The array of numbers representing circular values.
+ * @param {number} max - The maximum possible value in the cycle (e.g., 24 for hours, 360 for degrees).
+ * @returns {number} - The computed circular mean, wrapped within the range [0, max).
+ *
+ * @example
+ * // Averaging angles in degrees
+ * avgCircular([350, 10, 20], 360); // Returns approximately 0
+ *
+ * @example
+ * // Averaging times in hours (on a 24-hour clock)
+ * avgCircular([23, 1, 2], 24); // Returns approximately 0
+ *
+ * @group Array
+ */
+declare const avgCircular: (values: readonly number[], max: number) => number;
+
 /**
  * Splits an array into smaller sub-arrays (chunks) of a specified size.
  *
@@ -111,6 +133,8 @@ declare function chunkSeries(list: number[], step?: number): number[][];
  * const array3 = [1, 5];
  * const result = difference(array1, array2, array3);
  * // result will be [3] since 1, 2, 4 and 5 are in other arrays and are excluded from the result.
+ *
+ * @group Array
  */
 declare function difference<T>(...arrays: readonly T[][]): T[];
 
@@ -151,6 +175,8 @@ declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (
  * const array2 = [3, 4, 5, 6, 7];
  * const result = intersection(array1, array2);
  * // result will be [3, 4, 5] since these elements are in both arrays.
+ *
+ * @group Array
  */
 declare function intersection<T>(...arrays: readonly T[][]): T[];
 
@@ -213,9 +239,78 @@ declare function orderBy<T>(array: readonly T[], fields: (string | ((item: T) =>
  * const array = [1, 2, 3, 4, 5];
  * const shuffledArray = shuffle(array);
  * // shuffledArray will be a new array with elements of array in random order, e.g., [3, 1, 4, 5, 2]
+ *
+ * @group Array
  */
 declare function shuffle<T>(arr: readonly T[]): T[];
 
+/**
+ * Function that compares two elements and returns a number indicating their relative order.
+ * - Negative number if a < b
+ * - Zero if a equals b
+ * - Positive number if a > b
+ *
+ * @template T The type of elements in the array
+ */
+type SortedArrayCompareFn<T> = (a: T, b: T) => number;
+/**
+ * A self-sorting array that maintains elements in a sorted order based on a comparison function.
+ * All mutating operations preserve the sorted order of elements.
+ *
+ * @template T The type of elements in the array
+ *
+ * @example
+ * // Create a numerically sorted array
+ * const arr = new SortedArray((a, b) => a - b);
+ * arr.push(3, 2, 1);
+ * console.log(arr); // [1, 2, 3]
+ *
+ * @example
+ * // Create a sorted array with initial values
+ * const names = new SortedArray((a, b) => a.localeCompare(b), ["Charlie", "Alice", "Bob"]);
+ * console.log(names); // ["Alice", "Bob", "Charlie"]
+ *
+ * @example
+ * // Create a sorted array with a custom comparator
+ * const people = new SortedArray(
+ *   (a, b) => a.age - b.age || a.name.localeCompare(b.name),
+ *   [{ name: "Alice", age: 30 }, { name: "Bob", age: 25 }]
+ * );
+ *
+ * @group Array
+ */
+declare class SortedArray<T> extends Array<T> {
+    #private;
+    /**
+     * Creates a new SortedArray instance.
+     *
+     * @param compareFn The comparison function to determine the sort order
+     * @param items Optional initial items to add to the array (will be sorted immediately)
+     */
+    constructor(compareFn: SortedArrayCompareFn<T>, items?: T[]);
+    /**
+     * Inserts multiple items while maintaining sort order
+     * @param items The items to insert
+     * @returns The new length of the array
+     */
+    push(...items: T[]): number;
+    /**
+     * Override Array methods that would break the sorted order
+     */
+    unshift(...items: T[]): number;
+    /**
+     * Creates a new SortedArray with the same comparison function
+     * @returns A new SortedArray instance
+     */
+    slice(start?: number, end?: number): SortedArray<T>;
+    /**
+     * Concatenates arrays or values while maintaining sort order
+     * @param items Arrays or values to concatenate
+     * @returns A new SortedArray with the concatenated elements
+     */
+    concat(...items: (T | ConcatArray<T>)[]): SortedArray<T>;
+}
+
 /**
  * Sums the values in an array of numbers, ignoring non-numeric values.
  *
@@ -1620,7 +1715,7 @@ declare const ColorParser: {
  * Calculate crc32 hash from string
  * @group Crypto
  */
-declare function crc32(str: string, seed?: number): number;
+declare function crc32(current: Uint8Array | string, seed?: number): number;
 
 type DateObjectInput = Date | string | number | DateObject;
 declare function createDateObject(value: DateObjectInput): DateObject;
@@ -5138,4 +5233,4 @@ declare function wrapText(value: string, maxLength?: number): string;
  */
 declare function toError<T>(value: T, unknownMessage?: string): T extends Error ? T : Error;
 
-export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, base64ToBytes, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };
+export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSON as EJSONInstance, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EJSONType, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, SortedArray, type SortedArrayCompareFn, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, avgCircular, base64ToBytes, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };

package/dist/index.d.ts

@@ -43,6 +43,28 @@ declare function arrayable<T>(value: ArrayableValue<T>): ItemType<T>[];
  */
 declare const avg: (values: readonly number[]) => number;
 
+/**
+ * Computes the average of circular values using vector summation.
+ *
+ * This function calculates the circular mean of an array of values,
+ * which is useful for cyclic data (e.g., time of day, angles).
+ *
+ * @param {readonly number[]} values - The array of numbers representing circular values.
+ * @param {number} max - The maximum possible value in the cycle (e.g., 24 for hours, 360 for degrees).
+ * @returns {number} - The computed circular mean, wrapped within the range [0, max).
+ *
+ * @example
+ * // Averaging angles in degrees
+ * avgCircular([350, 10, 20], 360); // Returns approximately 0
+ *
+ * @example
+ * // Averaging times in hours (on a 24-hour clock)
+ * avgCircular([23, 1, 2], 24); // Returns approximately 0
+ *
+ * @group Array
+ */
+declare const avgCircular: (values: readonly number[], max: number) => number;
+
 /**
  * Splits an array into smaller sub-arrays (chunks) of a specified size.
  *
@@ -111,6 +133,8 @@ declare function chunkSeries(list: number[], step?: number): number[][];
  * const array3 = [1, 5];
  * const result = difference(array1, array2, array3);
  * // result will be [3] since 1, 2, 4 and 5 are in other arrays and are excluded from the result.
+ *
+ * @group Array
  */
 declare function difference<T>(...arrays: readonly T[][]): T[];
 
@@ -151,6 +175,8 @@ declare function groupBy<T, K extends PropertyKey>(array: readonly T[], keyBy: (
  * const array2 = [3, 4, 5, 6, 7];
  * const result = intersection(array1, array2);
  * // result will be [3, 4, 5] since these elements are in both arrays.
+ *
+ * @group Array
  */
 declare function intersection<T>(...arrays: readonly T[][]): T[];
 
@@ -213,9 +239,78 @@ declare function orderBy<T>(array: readonly T[], fields: (string | ((item: T) =>
  * const array = [1, 2, 3, 4, 5];
  * const shuffledArray = shuffle(array);
  * // shuffledArray will be a new array with elements of array in random order, e.g., [3, 1, 4, 5, 2]
+ *
+ * @group Array
  */
 declare function shuffle<T>(arr: readonly T[]): T[];
 
+/**
+ * Function that compares two elements and returns a number indicating their relative order.
+ * - Negative number if a < b
+ * - Zero if a equals b
+ * - Positive number if a > b
+ *
+ * @template T The type of elements in the array
+ */
+type SortedArrayCompareFn<T> = (a: T, b: T) => number;
+/**
+ * A self-sorting array that maintains elements in a sorted order based on a comparison function.
+ * All mutating operations preserve the sorted order of elements.
+ *
+ * @template T The type of elements in the array
+ *
+ * @example
+ * // Create a numerically sorted array
+ * const arr = new SortedArray((a, b) => a - b);
+ * arr.push(3, 2, 1);
+ * console.log(arr); // [1, 2, 3]
+ *
+ * @example
+ * // Create a sorted array with initial values
+ * const names = new SortedArray((a, b) => a.localeCompare(b), ["Charlie", "Alice", "Bob"]);
+ * console.log(names); // ["Alice", "Bob", "Charlie"]
+ *
+ * @example
+ * // Create a sorted array with a custom comparator
+ * const people = new SortedArray(
+ *   (a, b) => a.age - b.age || a.name.localeCompare(b.name),
+ *   [{ name: "Alice", age: 30 }, { name: "Bob", age: 25 }]
+ * );
+ *
+ * @group Array
+ */
+declare class SortedArray<T> extends Array<T> {
+    #private;
+    /**
+     * Creates a new SortedArray instance.
+     *
+     * @param compareFn The comparison function to determine the sort order
+     * @param items Optional initial items to add to the array (will be sorted immediately)
+     */
+    constructor(compareFn: SortedArrayCompareFn<T>, items?: T[]);
+    /**
+     * Inserts multiple items while maintaining sort order
+     * @param items The items to insert
+     * @returns The new length of the array
+     */
+    push(...items: T[]): number;
+    /**
+     * Override Array methods that would break the sorted order
+     */
+    unshift(...items: T[]): number;
+    /**
+     * Creates a new SortedArray with the same comparison function
+     * @returns A new SortedArray instance
+     */
+    slice(start?: number, end?: number): SortedArray<T>;
+    /**
+     * Concatenates arrays or values while maintaining sort order
+     * @param items Arrays or values to concatenate
+     * @returns A new SortedArray with the concatenated elements
+     */
+    concat(...items: (T | ConcatArray<T>)[]): SortedArray<T>;
+}
+
 /**
  * Sums the values in an array of numbers, ignoring non-numeric values.
  *
@@ -1620,7 +1715,7 @@ declare const ColorParser: {
  * Calculate crc32 hash from string
  * @group Crypto
  */
-declare function crc32(str: string, seed?: number): number;
+declare function crc32(current: Uint8Array | string, seed?: number): number;
 
 type DateObjectInput = Date | string | number | DateObject;
 declare function createDateObject(value: DateObjectInput): DateObject;
@@ -5138,4 +5233,4 @@ declare function wrapText(value: string, maxLength?: number): string;
  */
 declare function toError<T>(value: T, unknownMessage?: string): T extends Error ? T : Error;
 
-export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, base64ToBytes, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };
+export { type AnyFunction, AppError, type AppErrorOptions, type ArgumentsType, type Arrayable, AsyncIterableQueue, type Awaitable, type Base64ToBytesOptions, BrowserAssertionError, type BytesToBase64Options, CancellablePromise, type CatchErrorResult, Color, type ColorChannels, ColorParser, type Data, type DateObject, type DateObjectInput, type DebouncedFunction, type DeepPartial, type DeepReadonly, type Defer, instance as EJSON, EJSON as EJSONInstance, EJSONStream, type EJSONStreamOptions, type EJSONStreamOptionsWithPayload, type EJSONType, type EnvParser, type ExecResult, type ExecResultToSkip, type ExecResultToSuccess, type ExecSkip, type ExecSuccess, FindMean, FixedMap, FixedWeakMap, type Fn, type FormatMoney, type FormatNumber, type FunctionArgs, type GenericObject, type IfAny, type IsAny, type LiteralUnion, type Logger, LruCache, type Nothing, type OverwriteWith, type Prettify, type Primitive, type PromisifyFn, Queue, type RandomizerOptions, type RetryOnErrorConfig, type SelectOptionItem, type SelectOptions, type SimpleDefaultEventMap, SimpleEventEmitter, type SimpleEventMap, SortedArray, type SortedArrayCompareFn, _default as TWEMOJI_REGEX, type ThemeConfig, type ThrottledFunction, TimeBucket, type TimeBucketOptions, type TimeObject, type TimeObjectInput, TimeSpan, type TimeSpanUnit, type TimeString, type TimeValue, type TimestampMsInput, type TypeOf, type TypeOfMap, type ValuesOfObject, type WithCache, type WithCacheBucketBatchOptions, type WithCacheBucketOptions, type WithCacheFixedOptions, type WithCacheLruOptions, type WithCacheOptions, type WithCachePointer, type WithCacheResult, type WithCacheStorage, type WithCustomizer, type WithCustomizerFactory, type WithCustomizerValue, type WrrItem, alpha, arrayable, assert, asyncFilter, asyncFind, asyncForEach, asyncMap, avg, avgCircular, base64ToBytes, bigIntBytes, bigIntFromBytes, blendColors, buildCssColor, bytesToBase64, cache, cacheBucket, cacheFixed, cacheLRU, camelCase, capitalize, captureStackTrace, catchError, channelsToHSL, channelsToHex, channelsToRGB, checkBitmask, chunk, chunkSeries, clamp, cleanEmpty, cleanObject, colorToChannels, compareBytes, concatenateBytes, contrastRatio, convertToUnit, crc32, createCustomizer, createCustomizerFactory, createDateObject, createDeepCloneWith, createEJSON, createEJSONStream, createEnvParser, createRandomizer, createSecureCustomizer, createTimeObject, createTimeSpan, createWithCache, cssVariable, dateInDays, dateInSeconds, debounce, deepAssign, deepClone, deepCloneWith, deepDefaults, deepFreeze, def, defer, delay, difference, dropCache, env, escapeHtml, escapeNumeric, escapeRegExp, fastIdle, fastIdlePromise, fastRaf, findMean, flagsToMap, flatten, formatMoney, formatNumber, get, getFileExtension, getFileName, getInitials, getMostSpecificPaths, getRandomInt, getRandomTime, getWords, groupBy, has, hasOwn, hasProtocol, hex, hexToChannels, hmToSeconds, hslToChannels, humanFileSize, humanize, interpolateColor, intersection, isBigInt, isBoolean, isCached, isClient, isColorChannels, isCustomizerFactory, isDate, isDateObject, isDef, isEmpty, isEqual, isError, isFunction, isInfinity, isMap, isNullOrUndefined, isNumber, isObject, isOneEmoji, isPlainObject, isPrimitive, isPromise, isRegExp, isSet, isSkip, isString, isSuccess, isSymbol, isTimeObject, isTimeString, isTimeValue, isValidWeekDay, isWeakMap, isWeakSet, isWithCache, isoToFlagEmoji, kebabCase, keyBy, logger, loggerSetLevel, lowerCase, luminance, maskingEmail, maskingPhone, maskingWords, nextTickIteration, noop, objectId, omit, omitPrefixed, orderBy, parseAllNumbers, parseAlpha, parsePercentage, percentOf, pick, pickPrefixed, qs, rafPromise, randomString, removeVS16s, retryOnError, rgbToChannels, round2digits, secondsToHm, set, shuffle, snakeCase, sprintf, startCase, strAssign, sum, throttle, timeFromMinutes, timeStringify, timeToMinutes, timeout, timestamp, timestampMs, timestampToDate, tintedTextColor, toError, toMap, truncate, typeOf, uint16ToUint8, uint32ToUint8, uint8ToUint16, uint8ToUint32, unflatten, union, uniq, uniqBy, unset, weeksInYear, weightedRoundRobin, withCache, withCacheBucket, withCacheBucketBatch, withCacheFixed, withCacheLRU, withDeepClone, withPointerCache, wrapText };