atomic-fns 1.2.0 → 2.0.0

package/dist/is/isError.js

@@ -0,0 +1,18 @@
+const nativeIsError = Error.isError;
+/**
+ * True for an error from any realm, as `Error.isError` decides. Where the runtime lacks
+ * `Error.isError`, the object tag decides; `DOMException` is not recognized by this fallback.
+ * Removed once `Error.isError` is Baseline.
+ * @param value Any value.
+ * @returns Whether `value` is an error.
+ * @example
+ * ```ts
+ * isError(new TypeError('x')) // true
+ * isError({ name: 'Error', message: 'x' }) // false
+ * ```
+ */
+export function isError(value) {
+    if (nativeIsError !== undefined)
+        return nativeIsError(value);
+    return Object.prototype.toString.call(value) === '[object Error]';
+}

package/dist/is/isNil.d.ts

@@ -0,0 +1,12 @@
+/**
+ * True for `null` and `undefined`.
+ * @param value Any value.
+ * @returns Whether `value` is `null` or `undefined`.
+ * @example
+ * ```ts
+ * isNil(null) // true
+ * isNil(undefined) // true
+ * isNil(0) // false
+ * ```
+ */
+export declare function isNil(value: unknown): value is null | undefined;

package/dist/is/isNil.js

@@ -0,0 +1,14 @@
+/**
+ * True for `null` and `undefined`.
+ * @param value Any value.
+ * @returns Whether `value` is `null` or `undefined`.
+ * @example
+ * ```ts
+ * isNil(null) // true
+ * isNil(undefined) // true
+ * isNil(0) // false
+ * ```
+ */
+export function isNil(value) {
+    return value == null;
+}

package/dist/is/isPlainObject.d.ts

@@ -0,0 +1,15 @@
+/**
+ * True when `value` is a plain object: an object literal, `Object.create(null)`, or either from
+ * another realm (an iframe, a worker, `vm`). Class instances, arrays, `Math`, `JSON`, `arguments`
+ * and objects with their own `Symbol.toStringTag` are not plain.
+ * @param value Any value.
+ * @returns Whether `value` is a plain object.
+ * @example
+ * ```ts
+ * isPlainObject({ a: 1 }) // true
+ * isPlainObject(Object.create(null)) // true
+ * isPlainObject(new Date()) // false
+ * isPlainObject(new (class Point {})()) // false
+ * ```
+ */
+export declare function isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;

package/dist/is/isPlainObject.js

@@ -0,0 +1,34 @@
+const OBJECT_SOURCE = Function.prototype.toString.call(Object);
+/**
+ * `Object.prototype` of this realm or of another one: its constructor has `Object`'s source.
+ */
+function isObjectPrototype(proto) {
+    if (proto === Object.prototype)
+        return true;
+    if (proto === null || Object.getPrototypeOf(proto) !== null)
+        return false;
+    const ctor = Object.getOwnPropertyDescriptor(proto, 'constructor')?.value;
+    return typeof ctor === 'function' && Function.prototype.toString.call(ctor) === OBJECT_SOURCE;
+}
+/**
+ * True when `value` is a plain object: an object literal, `Object.create(null)`, or either from
+ * another realm (an iframe, a worker, `vm`). Class instances, arrays, `Math`, `JSON`, `arguments`
+ * and objects with their own `Symbol.toStringTag` are not plain.
+ * @param value Any value.
+ * @returns Whether `value` is a plain object.
+ * @example
+ * ```ts
+ * isPlainObject({ a: 1 }) // true
+ * isPlainObject(Object.create(null)) // true
+ * isPlainObject(new Date()) // false
+ * isPlainObject(new (class Point {})()) // false
+ * ```
+ */
+export function isPlainObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    if (Object.prototype.toString.call(value) !== '[object Object]')
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || isObjectPrototype(proto);
+}

package/dist/number/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Number helpers: `clamp`, `inRange`, decimal `round`, `floor` and `ceil`, `sum`, `mean` and
+ * `formatBytes`.
+ * @module number
+ */
+export { ceil, clamp, floor, inRange, round } from './round.js';
+export { type FormatBytesOptions, formatBytes, mean, sum } from './stats.js';

package/dist/number/index.js

@@ -0,0 +1,7 @@
+/**
+ * Number helpers: `clamp`, `inRange`, decimal `round`, `floor` and `ceil`, `sum`, `mean` and
+ * `formatBytes`.
+ * @module number
+ */
+export { ceil, clamp, floor, inRange, round } from './round.js';
+export { formatBytes, mean, sum } from './stats.js';

package/dist/number/round.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Rounds `n` to `digits` places after the decimal point, ties toward `+Infinity` as `Math.round`
+ * does. It rounds the decimal that `String(n)` prints, not the binary value, so `round(1.005, 2)`
+ * is `1.01` where `(1.005).toFixed(2)` is `'1.00'`. Negative `digits` round to tens, hundreds and
+ * so on. Infinities and NaN come back unchanged. A result too large for a number, such as
+ * `round(Number.MAX_VALUE, -308)`, is `Infinity`. `-0` becomes `0`, unlike `Math.round`, so a
+ * value that rounds to zero, such as `round(-0.004, 2)`, does not print as `-0` through
+ * `Intl.NumberFormat`.
+ * @param n The number to round.
+ * @param digits Places after the decimal point (default 0); may be negative.
+ * @returns The rounded number.
+ * @throws {TypeError} when `n` or `digits` is not a number.
+ * @throws {RangeError} when `digits` is not an integer.
+ * @example
+ * ```ts
+ * round(4.006, 2) // 4.01
+ * round(4060, -2) // 4100
+ * round(-2.5) // -2
+ * ```
+ */
+export declare function round(n: number, digits?: number): number;
+/**
+ * Rounds `n` down, toward `-Infinity`, to `digits` places after the decimal point, on the decimal
+ * that `String(n)` prints, as {@link round} does.
+ * @param n The number to round down.
+ * @param digits Places after the decimal point (default 0); may be negative.
+ * @returns The rounded number.
+ * @throws {TypeError} when `n` or `digits` is not a number.
+ * @throws {RangeError} when `digits` is not an integer.
+ * @example
+ * ```ts
+ * floor(4.006, 2) // 4
+ * floor(0.29, 2) // 0.29
+ * floor(4060, -2) // 4000
+ * ```
+ */
+export declare function floor(n: number, digits?: number): number;
+/**
+ * Rounds `n` up, toward `+Infinity`, to `digits` places after the decimal point, on the decimal
+ * that `String(n)` prints, as {@link round} does.
+ * @param n The number to round up.
+ * @param digits Places after the decimal point (default 0); may be negative.
+ * @returns The rounded number.
+ * @throws {TypeError} when `n` or `digits` is not a number.
+ * @throws {RangeError} when `digits` is not an integer.
+ * @example
+ * ```ts
+ * ceil(4.006, 2) // 4.01
+ * ceil(6040, -2) // 6100
+ * ```
+ */
+export declare function ceil(n: number, digits?: number): number;
+/**
+ * Limits `n` to the range from `min` to `max`, both included. NaN stays NaN.
+ * @param n The number to clamp.
+ * @param min The lower bound.
+ * @param max The upper bound.
+ * @returns `n`, `min` or `max`.
+ * @throws {TypeError} when an argument is not a number.
+ * @throws {RangeError} when a bound is NaN or `min > max`.
+ * @example
+ * ```ts
+ * clamp(-10, -5, 5) // -5
+ * clamp(10, -5, 5) // 5
+ * ```
+ */
+export declare function clamp(n: number, min: number, max: number): number;
+/**
+ * Checks whether `n` is at least `start` and below `end`. With two arguments the range is
+ * `[0, end)`, and reversed bounds swap, as in lodash. A NaN `n` is never in range.
+ * @param n The number to check.
+ * @param start The lower bound (included).
+ * @param end The upper bound (excluded).
+ * @returns Whether `n` is in the range.
+ * @throws {TypeError} when an argument is not a number.
+ * @throws {RangeError} when a bound is NaN.
+ * @example
+ * ```ts
+ * inRange(3, 2, 4) // true
+ * inRange(4, 8) // true
+ * inRange(-3, -2, -6) // true
+ * ```
+ */
+export declare function inRange(n: number, start: number, end: number): boolean;
+/** {@link inRange} from `0` to `end`. */
+export declare function inRange(n: number, end: number): boolean;

package/dist/number/round.js

@@ -0,0 +1,130 @@
+function assertNumber(n, name) {
+    if (typeof n !== 'number')
+        throw new TypeError(`${name} must be a number`);
+}
+/** The shortest round-trip decimal of `|n|` as integer digits and a base-10 exponent. */
+function decimalParts(n) {
+    const [coefficient, exp = '0'] = String(Math.abs(n)).split('e');
+    const [whole, fraction = ''] = coefficient.split('.');
+    const digits = (whole + fraction).replace(/^0+(?=\d)/, '');
+    return { digits, exponent: Number(exp) - fraction.length };
+}
+function roundTo(n, digits, mode) {
+    assertNumber(n, 'n');
+    assertNumber(digits, 'digits');
+    if (!Number.isSafeInteger(digits))
+        throw new RangeError('digits must be an integer');
+    if (!Number.isFinite(n) || n === 0)
+        return n === 0 ? 0 : n;
+    const parts = decimalParts(n);
+    const drop = -digits - parts.exponent;
+    if (drop <= 0)
+        return n;
+    const negative = n < 0;
+    const { length } = parts.digits;
+    // Past the leading digit the dropped part is below half a unit, and it is never zero.
+    const head = length > drop ? parts.digits.slice(0, length - drop) : '0';
+    const tail = length >= drop ? parts.digits.slice(length - drop) : '';
+    const exact = drop <= length && /^0*$/.test(tail);
+    let up;
+    if (mode === 'floor')
+        up = negative && !exact;
+    else if (mode === 'ceil')
+        up = !negative && !exact;
+    else {
+        const half = '5'.padEnd(tail.length, '0');
+        up = tail > half || (tail === half && !negative);
+    }
+    const magnitude = BigInt(head) + (up ? 1n : 0n);
+    const result = Number(`${negative ? '-' : ''}${magnitude}e${-digits}`);
+    return result === 0 ? 0 : result;
+}
+/**
+ * Rounds `n` to `digits` places after the decimal point, ties toward `+Infinity` as `Math.round`
+ * does. It rounds the decimal that `String(n)` prints, not the binary value, so `round(1.005, 2)`
+ * is `1.01` where `(1.005).toFixed(2)` is `'1.00'`. Negative `digits` round to tens, hundreds and
+ * so on. Infinities and NaN come back unchanged. A result too large for a number, such as
+ * `round(Number.MAX_VALUE, -308)`, is `Infinity`. `-0` becomes `0`, unlike `Math.round`, so a
+ * value that rounds to zero, such as `round(-0.004, 2)`, does not print as `-0` through
+ * `Intl.NumberFormat`.
+ * @param n The number to round.
+ * @param digits Places after the decimal point (default 0); may be negative.
+ * @returns The rounded number.
+ * @throws {TypeError} when `n` or `digits` is not a number.
+ * @throws {RangeError} when `digits` is not an integer.
+ * @example
+ * ```ts
+ * round(4.006, 2) // 4.01
+ * round(4060, -2) // 4100
+ * round(-2.5) // -2
+ * ```
+ */
+export function round(n, digits = 0) {
+    return roundTo(n, digits, 'halfCeil');
+}
+/**
+ * Rounds `n` down, toward `-Infinity`, to `digits` places after the decimal point, on the decimal
+ * that `String(n)` prints, as {@link round} does.
+ * @param n The number to round down.
+ * @param digits Places after the decimal point (default 0); may be negative.
+ * @returns The rounded number.
+ * @throws {TypeError} when `n` or `digits` is not a number.
+ * @throws {RangeError} when `digits` is not an integer.
+ * @example
+ * ```ts
+ * floor(4.006, 2) // 4
+ * floor(0.29, 2) // 0.29
+ * floor(4060, -2) // 4000
+ * ```
+ */
+export function floor(n, digits = 0) {
+    return roundTo(n, digits, 'floor');
+}
+/**
+ * Rounds `n` up, toward `+Infinity`, to `digits` places after the decimal point, on the decimal
+ * that `String(n)` prints, as {@link round} does.
+ * @param n The number to round up.
+ * @param digits Places after the decimal point (default 0); may be negative.
+ * @returns The rounded number.
+ * @throws {TypeError} when `n` or `digits` is not a number.
+ * @throws {RangeError} when `digits` is not an integer.
+ * @example
+ * ```ts
+ * ceil(4.006, 2) // 4.01
+ * ceil(6040, -2) // 6100
+ * ```
+ */
+export function ceil(n, digits = 0) {
+    return roundTo(n, digits, 'ceil');
+}
+/**
+ * Limits `n` to the range from `min` to `max`, both included. NaN stays NaN.
+ * @param n The number to clamp.
+ * @param min The lower bound.
+ * @param max The upper bound.
+ * @returns `n`, `min` or `max`.
+ * @throws {TypeError} when an argument is not a number.
+ * @throws {RangeError} when a bound is NaN or `min > max`.
+ * @example
+ * ```ts
+ * clamp(-10, -5, 5) // -5
+ * clamp(10, -5, 5) // 5
+ * ```
+ */
+export function clamp(n, min, max) {
+    assertNumber(n, 'n');
+    assertNumber(min, 'min');
+    assertNumber(max, 'max');
+    if (!(min <= max))
+        throw new RangeError('min and max must not be NaN, and min must be <= max');
+    return Math.min(Math.max(n, min), max);
+}
+export function inRange(n, first, last) {
+    assertNumber(n, 'n');
+    const [start, end] = last === undefined ? [0, first] : [first, last];
+    assertNumber(start, 'start');
+    assertNumber(end, 'end');
+    if (Number.isNaN(start) || Number.isNaN(end))
+        throw new RangeError('start and end must not be NaN');
+    return n >= Math.min(start, end) && n < Math.max(start, end);
+}

package/dist/number/stats.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Adds the numbers of an iterable from left to right, as a loop with `+` does; an empty iterable
+ * sums to `0`. For a correctly rounded total, use `Math.sumPrecise` where the runtime has it.
+ * @param values The numbers to add.
+ * @returns The total.
+ * @throws {TypeError} when `values` is not iterable, `null` and `undefined` included (lodash
+ * sums those to `0`), or holds a non-number.
+ * @example
+ * ```ts
+ * sum([4, 2, 8, 6]) // 20
+ * sum(new Set([1, 2])) // 3
+ * ```
+ */
+export declare function sum(values: Iterable<number>): number;
+/**
+ * Averages the numbers of an iterable; an empty iterable gives `NaN`, as in lodash.
+ * @param values The numbers to average.
+ * @returns The arithmetic mean.
+ * @throws {TypeError} when `values` is not iterable, `null` and `undefined` included (lodash
+ * averages those to `NaN`), or holds a non-number.
+ * @example
+ * ```ts
+ * mean([4, 2, 8, 6]) // 5
+ * mean([]) // NaN
+ * ```
+ */
+export declare function mean(values: Iterable<number>): number;
+/** Options for {@link formatBytes}. */
+export interface FormatBytesOptions {
+    /** A BCP 47 tag or list of tags for the number, as `Intl.NumberFormat` takes. */
+    locale?: Intl.LocalesArgument;
+    /** Use powers of 1024 and IEC units (`KiB`, `MiB`) instead of powers of 1000 (`kB`, `MB`). */
+    binary?: boolean;
+}
+/**
+ * Formats a byte count for people: powers of 1000 with SI units by default, or powers of 1024
+ * with IEC units when `binary` is set, rounded to about three significant digits. The number is
+ * formatted with `Intl.NumberFormat` for `locale`; the unit symbol follows after a space. Bytes
+ * past the yottabyte keep the largest unit.
+ * @param n The byte count; may be negative or fractional.
+ * @param options `locale` and `binary`.
+ * @returns The formatted size.
+ * @throws {TypeError} when `n` is not a number.
+ * @throws {RangeError} when `n` is not finite.
+ * @example
+ * ```ts
+ * formatBytes(1536) // '1.54 kB'
+ * formatBytes(1536, { binary: true }) // '1.5 KiB'
+ * formatBytes(1234567, { locale: 'de' }) // '1,23 MB'
+ * ```
+ */
+export declare function formatBytes(n: number, options?: FormatBytesOptions): string;

package/dist/number/stats.js

@@ -0,0 +1,115 @@
+import { round } from './round.js';
+/** Adds the numbers of `values` from left to right and counts them. */
+function total(values, name) {
+    if (values == null || typeof values[Symbol.iterator] !== 'function') {
+        const received = values === null ? 'null' : typeof values;
+        throw new TypeError(`${name} expects an iterable of numbers, got ${received}`);
+    }
+    let sum = 0;
+    let count = 0;
+    for (const value of values) {
+        if (typeof value !== 'number')
+            throw new TypeError(`${name} expects numbers, got ${typeof value}`);
+        sum += value;
+        count++;
+    }
+    return { sum, count };
+}
+/**
+ * Adds the numbers of an iterable from left to right, as a loop with `+` does; an empty iterable
+ * sums to `0`. For a correctly rounded total, use `Math.sumPrecise` where the runtime has it.
+ * @param values The numbers to add.
+ * @returns The total.
+ * @throws {TypeError} when `values` is not iterable, `null` and `undefined` included (lodash
+ * sums those to `0`), or holds a non-number.
+ * @example
+ * ```ts
+ * sum([4, 2, 8, 6]) // 20
+ * sum(new Set([1, 2])) // 3
+ * ```
+ */
+export function sum(values) {
+    return total(values, 'sum').sum;
+}
+/**
+ * Averages the numbers of an iterable; an empty iterable gives `NaN`, as in lodash.
+ * @param values The numbers to average.
+ * @returns The arithmetic mean.
+ * @throws {TypeError} when `values` is not iterable, `null` and `undefined` included (lodash
+ * averages those to `NaN`), or holds a non-number.
+ * @example
+ * ```ts
+ * mean([4, 2, 8, 6]) // 5
+ * mean([]) // NaN
+ * ```
+ */
+export function mean(values) {
+    const { sum, count } = total(values, 'mean');
+    return sum / count;
+}
+const DECIMAL_UNITS = ['B', 'kB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+const BINARY_UNITS = ['B', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'EiB', 'ZiB', 'YiB'];
+/** Fraction digits that show three significant digits below 1000 and none above. */
+function fractionDigits(size) {
+    return size < 10 ? 2 : size < 100 ? 1 : 0;
+}
+/** Rounds a non-negative size to the digits {@link fractionDigits} picks for it. */
+function roundSize(size) {
+    return round(size, fractionDigits(size));
+}
+const MAX_CACHED_FORMATS = 64;
+/** Formats by fraction digits and locale tag, cleared when full since locales may come from requests. */
+const formats = new Map();
+function numberFormat(locale, digits) {
+    const options = { maximumFractionDigits: digits };
+    // Locale lists and Intl.Locale objects have no cheap exact key, so they are not cached.
+    if (locale !== undefined && typeof locale !== 'string')
+        return new Intl.NumberFormat(locale, options);
+    const key = locale === undefined ? `${digits}` : `${digits} ${locale}`;
+    let format = formats.get(key);
+    if (format === undefined) {
+        format = new Intl.NumberFormat(locale, options);
+        if (formats.size >= MAX_CACHED_FORMATS)
+            formats.clear();
+        formats.set(key, format);
+    }
+    return format;
+}
+/**
+ * Formats a byte count for people: powers of 1000 with SI units by default, or powers of 1024
+ * with IEC units when `binary` is set, rounded to about three significant digits. The number is
+ * formatted with `Intl.NumberFormat` for `locale`; the unit symbol follows after a space. Bytes
+ * past the yottabyte keep the largest unit.
+ * @param n The byte count; may be negative or fractional.
+ * @param options `locale` and `binary`.
+ * @returns The formatted size.
+ * @throws {TypeError} when `n` is not a number.
+ * @throws {RangeError} when `n` is not finite.
+ * @example
+ * ```ts
+ * formatBytes(1536) // '1.54 kB'
+ * formatBytes(1536, { binary: true }) // '1.5 KiB'
+ * formatBytes(1234567, { locale: 'de' }) // '1,23 MB'
+ * ```
+ */
+export function formatBytes(n, options) {
+    if (typeof n !== 'number')
+        throw new TypeError('n must be a number');
+    if (!Number.isFinite(n))
+        throw new RangeError('n must be finite');
+    const binary = options?.binary ?? false;
+    const units = binary ? BINARY_UNITS : DECIMAL_UNITS;
+    const base = binary ? 1024 : 1000;
+    const size = Math.abs(n);
+    let exponent = 0;
+    let rounded = roundSize(size);
+    while (exponent < 8 && rounded >= base) {
+        exponent++;
+        rounded = roundSize(size / base ** exponent);
+    }
+    // `|| 0` turns the -0 of a negative size that rounds to zero into 0.
+    const value = (n < 0 ? -rounded : rounded) || 0;
+    const formatted = numberFormat(options?.locale, fractionDigits(rounded)).format(value);
+    // Intl's `style: 'unit'` would localize the symbols, but it has no IEC units and stops at petabyte.
+    return `${formatted} ${units[exponent]}`;
+}

package/dist/object/cloneDeep.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `cloneDeep`: a structural copy that keeps prototypes, symbol keys, sharing and cycles.
+ */
+/**
+ * A deep copy of `value`. Plain objects, arrays, `Map`, `Set`, `Date`, `RegExp`, typed arrays,
+ * `DataView`, `ArrayBuffer`, `SharedArrayBuffer` and boxed primitives are copied with their
+ * prototype (a subclass stays a subclass) and their own enumerable symbol keys; all but typed
+ * arrays, `DataView` and `String` wrappers also keep their own enumerable string keys, and arrays
+ * keep their holes. `Map` keys keep their identity while values are copied. A subclass copy gets
+ * the prototype only: its constructor does not run, so it has none of its private fields. A
+ * resizable or growable buffer stays so, and a detached one copies as an empty buffer. Class
+ * instances, functions, errors, promises and every other object are kept by reference:
+ * `structuredClone` throws on them, and copying their fields would produce an object whose private
+ * state and invariants are gone. An object reached twice is copied once, so shared references and
+ * cycles stay shared and cyclic in the copy, and views over one buffer share one copied buffer.
+ * @param value The value to copy.
+ * @returns The copy.
+ * @throws {RangeError} past 1000 levels of nesting.
+ * @throws {TypeError} for a typed array kind this runtime has no constructor for.
+ * @example
+ * ```ts
+ * const src = { when: new Date(0), tags: new Set(['a']), list: [{ id: 1 }] }
+ * const copy = cloneDeep(src)
+ * copy.list[0] === src.list[0] // false
+ * copy.when.getTime() // 0
+ * ```
+ */
+export declare function cloneDeep<T>(value: T): T;