atomic-fns 1.1.7 → 2.0.0

package/dist/collections/trie.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Prefix tree for strings, path-compressed: memory grows with the number of words, not their
+ * length. Insertions, lookups and removals in O(s) for string length s. Prefixes compare by UTF-16
+ * code unit, as `startsWith` does.
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Radix_tree Radix tree}
+ * @example
+ * ```ts
+ * const words = new Trie(['car', 'cart', 'cat'])
+ * ;[...words.withPrefix('car')] // ['car', 'cart']
+ * words.withPrefix('ca').take(1).toArray() // ['car']
+ * words.has('ca') // false
+ * ```
+ */
+export declare class Trie {
+    #private;
+    /**
+     * Create a trie holding `words`.
+     * @param words Initial words. `null` means none.
+     * @throws {TypeError} when `words` is not iterable or holds a non-string.
+     */
+    constructor(words?: Iterable<string> | null);
+    /**
+     * Add `word`. Non-strings throw. A duplicate is a no-op for size.
+     * @throws {TypeError} when `word` is not a string.
+     */
+    add(word: string): this;
+    /**
+     * Remove `word` if present (including `''`) and prune empty branches.
+     * @returns `true` iff the word was present.
+     */
+    delete(word: string): boolean;
+    /** Whether `word` was added. A prefix of a word is not a word. */
+    has(word: string): boolean;
+    /**
+     * Yield words that start with `prefix`, in child insertion order. The walk starts on the first
+     * `next()`, so it sees words added before then. A `clear` ends the iterator, started or not. Use
+     * `withPrefix(prefix).take(n)` for at most `n` words.
+     * @throws {TypeError} when `prefix` is not a string.
+     */
+    withPrefix(prefix: string): IteratorObject<string>;
+    /** Remove every word, and end every iterator taken before. */
+    clear(): void;
+    /** The number of words. */
+    get size(): number;
+    /** `'Trie'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag](): string;
+    /** Every word, in child insertion order. */
+    values(): IteratorObject<string>;
+    /** Every word, as `Set.prototype.keys` gives them. */
+    keys(): IteratorObject<string>;
+    /** `[word, word]` pairs, as `Set.prototype.entries` gives them. */
+    entries(): IteratorObject<[string, string]>;
+    /** Call `callback(word, word, trie)` for each word. */
+    forEach(callback: (value: string, key: string, trie: this) => void, thisArg?: unknown): void;
+    /** Every word, in child insertion order. */
+    [Symbol.iterator](): IteratorObject<string>;
+}

package/dist/collections/trie.js

@@ -0,0 +1,196 @@
+import { requireIterable } from './internal/iterable.js';
+function newNode(path) {
+    return { path, isWord: false };
+}
+function attach(parent, unit, child) {
+    child.parent = parent;
+    parent.children ??= new Map();
+    parent.children.set(unit, child);
+    return child;
+}
+/** Where `a` and `b` first differ, given that they agree up to `from`. */
+function sharedLength(a, b, from) {
+    const end = Math.min(a.length, b.length);
+    let i = from;
+    while (i < end && a.charCodeAt(i) === b.charCodeAt(i))
+        i++;
+    return i;
+}
+/** Drop or merge a node that no longer holds a word. Nodes keep their paths, so open walks stay valid. */
+function prune(node) {
+    const { parent, children } = node;
+    if (parent === undefined || node.isWord)
+        return;
+    const unit = node.path.charCodeAt(parent.path.length);
+    if (children === undefined || children.size === 0) {
+        parent.children?.delete(unit);
+        prune(parent);
+    }
+    else if (children.size === 1) {
+        const [only] = children.values();
+        attach(parent, unit, only);
+    }
+}
+/**
+ * Prefix tree for strings, path-compressed: memory grows with the number of words, not their
+ * length. Insertions, lookups and removals in O(s) for string length s. Prefixes compare by UTF-16
+ * code unit, as `startsWith` does.
+ *
+ * @see {@link https://en.wikipedia.org/wiki/Radix_tree Radix tree}
+ * @example
+ * ```ts
+ * const words = new Trie(['car', 'cart', 'cat'])
+ * ;[...words.withPrefix('car')] // ['car', 'cart']
+ * words.withPrefix('ca').take(1).toArray() // ['car']
+ * words.has('ca') // false
+ * ```
+ */
+export class Trie {
+    #root = newNode('');
+    #count = 0;
+    #generation = 0;
+    /**
+     * Create a trie holding `words`.
+     * @param words Initial words. `null` means none.
+     * @throws {TypeError} when `words` is not iterable or holds a non-string.
+     */
+    constructor(words) {
+        for (const word of requireIterable(words ?? [])) {
+            this.add(word);
+        }
+    }
+    /**
+     * Add `word`. Non-strings throw. A duplicate is a no-op for size.
+     * @throws {TypeError} when `word` is not a string.
+     */
+    add(word) {
+        if (typeof word !== 'string')
+            throw new TypeError('Trie stores strings');
+        let node = this.#root;
+        while (node.path.length < word.length) {
+            const from = node.path.length;
+            const unit = word.charCodeAt(from);
+            const child = node.children?.get(unit);
+            if (child === undefined) {
+                node = attach(node, unit, newNode(word));
+                break;
+            }
+            const shared = sharedLength(word, child.path, from);
+            if (shared === child.path.length) {
+                node = child;
+            }
+            else {
+                const middle = attach(node, unit, newNode(word.slice(0, shared)));
+                attach(middle, child.path.charCodeAt(shared), child);
+                node = middle;
+            }
+        }
+        if (!node.isWord) {
+            node.isWord = true;
+            this.#count++;
+        }
+        return this;
+    }
+    /**
+     * Remove `word` if present (including `''`) and prune empty branches.
+     * @returns `true` iff the word was present.
+     */
+    delete(word) {
+        const node = this.#findWord(word);
+        if (node === undefined)
+            return false;
+        node.isWord = false;
+        this.#count--;
+        prune(node);
+        return true;
+    }
+    /** Whether `word` was added. A prefix of a word is not a word. */
+    has(word) {
+        return this.#findWord(word) !== undefined;
+    }
+    /**
+     * Yield words that start with `prefix`, in child insertion order. The walk starts on the first
+     * `next()`, so it sees words added before then. A `clear` ends the iterator, started or not. Use
+     * `withPrefix(prefix).take(n)` for at most `n` words.
+     * @throws {TypeError} when `prefix` is not a string.
+     */
+    withPrefix(prefix) {
+        if (typeof prefix !== 'string')
+            throw new TypeError('prefix must be a string');
+        return this.#walk(prefix, this.#generation);
+    }
+    *#walk(prefix, generation) {
+        const start = this.#locate(prefix);
+        if (start === undefined)
+            return;
+        const stack = [[start].values()];
+        while (stack.length > 0 && generation === this.#generation) {
+            const next = stack[stack.length - 1].next();
+            if (next.done) {
+                stack.pop();
+                continue;
+            }
+            const node = next.value;
+            if (node.isWord)
+                yield node.path;
+            if (node.children)
+                stack.push(node.children.values());
+        }
+    }
+    /** The topmost node whose path starts with `prefix`. */
+    #locate(prefix) {
+        let node = this.#root;
+        while (node.path.length < prefix.length) {
+            const from = node.path.length;
+            const child = node.children?.get(prefix.charCodeAt(from));
+            if (!child)
+                return undefined;
+            const shared = sharedLength(prefix, child.path, from);
+            if (shared < prefix.length && shared < child.path.length)
+                return undefined;
+            node = child;
+        }
+        return node;
+    }
+    #findWord(word) {
+        if (typeof word !== 'string')
+            return undefined;
+        const node = this.#locate(word);
+        return node?.isWord === true && node.path.length === word.length ? node : undefined;
+    }
+    /** Remove every word, and end every iterator taken before. */
+    clear() {
+        this.#root = newNode('');
+        this.#count = 0;
+        this.#generation++;
+    }
+    /** The number of words. */
+    get size() {
+        return this.#count;
+    }
+    /** `'Trie'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag]() {
+        return 'Trie';
+    }
+    /** Every word, in child insertion order. */
+    values() {
+        return this.withPrefix('');
+    }
+    /** Every word, as `Set.prototype.keys` gives them. */
+    keys() {
+        return this.values();
+    }
+    /** `[word, word]` pairs, as `Set.prototype.entries` gives them. */
+    entries() {
+        return this.values().map((w) => [w, w]);
+    }
+    /** Call `callback(word, word, trie)` for each word. */
+    forEach(callback, thisArg) {
+        for (const w of this.values())
+            Reflect.apply(callback, thisArg, [w, w, this]);
+    }
+    /** Every word, in child insertion order. */
+    [Symbol.iterator]() {
+        return this.values();
+    }
+}

package/dist/decimal/currency.d.ts

@@ -0,0 +1,211 @@
+import { Decimal, type DecimalInput, type DivideOptions, type RoundingMode } from './decimal.js';
+/**
+ * An exact amount of money in one ISO 4217 currency, as the TC39 Amount proposal pairs a value
+ * with its unit. Arithmetic and ordering with another currency throw `RangeError`; nothing
+ * converts between currencies.
+ *
+ * @example
+ * ```ts
+ * const price = new Currency('19.99', 'USD')
+ * price.multiply(3).format('en-US') // '$59.97'
+ * price.add(new Currency('0.01', 'USD')).toString() // '20 USD'
+ * ```
+ */
+export declare class Currency {
+    #private;
+    /**
+     * Orders two amounts of the same currency, for `toSorted` and sorted collections.
+     * @throws {TypeError} when `a` or `b` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * [new Currency(5, 'EUR'), new Currency(2, 'EUR')].toSorted(Currency.compare).map(String)
+     * // ['2 EUR', '5 EUR']
+     * ```
+     */
+    static compare(a: Currency, b: Currency): -1 | 0 | 1;
+    /**
+     * Pairs an amount with a currency code.
+     * @param amount The amount, read as {@link Decimal} reads it.
+     * @param currency A three-letter ISO 4217 code, in any case.
+     * @throws {TypeError} when `currency` is not a string, or `amount` not a Decimal input.
+     * @throws {RangeError} when `currency` is not three letters, or `amount` is malformed.
+     * @example
+     * ```ts
+     * new Currency('12.50', 'usd').currency // 'USD'
+     * ```
+     */
+    constructor(amount: DecimalInput, currency: string);
+    /** The exact amount. */
+    get amount(): Decimal;
+    /** The upper-case ISO 4217 code, such as `'USD'`. */
+    get currency(): string;
+    /**
+     * The sum of two amounts of the same currency.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency('0.1', 'USD').add(new Currency('0.2', 'USD')).toString() // '0.3 USD'
+     * ```
+     */
+    add(other: Currency): Currency;
+    /**
+     * The difference of two amounts of the same currency.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(10, 'EUR').subtract(new Currency('2.5', 'EUR')).toString() // '7.5 EUR'
+     * ```
+     */
+    subtract(other: Currency): Currency;
+    /**
+     * This amount times a plain factor.
+     * @example
+     * ```ts
+     * new Currency('19.99', 'USD').multiply(3).toString() // '59.97 USD'
+     * ```
+     */
+    multiply(factor: DecimalInput): Currency;
+    /**
+     * This amount divided by a plain divisor, rounded as {@link Decimal.divide} rounds, to 34
+     * significant digits by default; follow with {@link Currency.round} for the minor unit.
+     * @throws {RangeError} for a zero divisor.
+     * @example
+     * ```ts
+     * new Currency(10, 'USD').divide(3).round().toString() // '3.33 USD'
+     * ```
+     */
+    divide(divisor: DecimalInput, options?: DivideOptions): Currency;
+    /**
+     * This amount with the opposite sign.
+     * @example
+     * ```ts
+     * new Currency(5, 'USD').negate().toString() // '-5 USD'
+     * ```
+     */
+    negate(): Currency;
+    /**
+     * The absolute amount.
+     * @example
+     * ```ts
+     * new Currency(-5, 'USD').abs().toString() // '5 USD'
+     * ```
+     */
+    abs(): Currency;
+    /**
+     * Rounds the amount, by default to the currency's ISO 4217 minor unit (2 digits for USD, 0 for
+     * JPY, 3 for IQD). The mode defaults to `'halfEven'`, while {@link Currency.format} rounds what
+     * it shows half away from zero, as `Intl.NumberFormat` does.
+     * @param digits Fractional digits (may be negative); defaults to the minor unit.
+     * @param roundingMode One of the `Intl.NumberFormat` rounding modes; defaults to `'halfEven'`.
+     * @throws {RangeError} when `digits` is left out and ISO 4217 gives the code no minor unit, as
+     * for XAU or a code it does not list.
+     * @example
+     * ```ts
+     * new Currency('2.675', 'USD').round().toString() // '2.68 USD'
+     * new Currency('1234.5', 'JPY').round().toString() // '1234 JPY'
+     * new Currency('2.665', 'USD').round(undefined, 'halfExpand').toString() // '2.67 USD'
+     * ```
+     */
+    round(digits?: number, roundingMode?: RoundingMode): Currency;
+    /**
+     * Orders this amount against another of the same currency: -1, 0 or 1.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(1, 'USD').compare(new Currency('1.00', 'USD')) // 0
+     * ```
+     */
+    compare(other: Currency): -1 | 0 | 1;
+    /**
+     * True for a Currency with the same code and amount; false for anything else, including the
+     * same amount in another currency.
+     * @example
+     * ```ts
+     * new Currency(1, 'USD').equals(new Currency(1, 'EUR')) // false
+     * ```
+     */
+    equals(other: Currency): boolean;
+    /**
+     * True when this amount is less than `other`.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(1, 'USD').lessThan(new Currency(2, 'USD')) // true
+     * ```
+     */
+    lessThan(other: Currency): boolean;
+    /**
+     * True when this amount is less than or equal to `other`.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(2, 'USD').lessThanOrEqual(new Currency(2, 'USD')) // true
+     * ```
+     */
+    lessThanOrEqual(other: Currency): boolean;
+    /**
+     * True when this amount is greater than `other`.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(3, 'USD').greaterThan(new Currency(2, 'USD')) // true
+     * ```
+     */
+    greaterThan(other: Currency): boolean;
+    /**
+     * True when this amount is greater than or equal to `other`.
+     * @throws {TypeError} when `other` is not a Currency.
+     * @throws {RangeError} when the currencies differ.
+     * @example
+     * ```ts
+     * new Currency(2, 'USD').greaterThanOrEqual(new Currency(3, 'USD')) // false
+     * ```
+     */
+    greaterThanOrEqual(other: Currency): boolean;
+    /**
+     * Formats with `Intl.NumberFormat` in currency style. Unless `options` set the digits, the
+     * amount keeps its own fraction digits, up to 20, instead of rounding to the minor unit, so
+     * `0.125` dollars show as `$0.125`; pass `{ maximumFractionDigits: 2 }` or {@link Currency.round}
+     * first for minor units. A `roundingMode` alone changes nothing, since no digits are cut; pair it
+     * with `maximumFractionDigits`. `style` and `currency` always come from this amount.
+     * @throws {RangeError} when the amount is beyond `Number.MAX_VALUE`, which `Intl` shows as `∞`,
+     * or the locale is malformed or longer than 255 characters.
+     * @example
+     * ```ts
+     * new Currency('1234.5', 'EUR').format('de-DE') // '1.234,50 €'
+     * new Currency('0.125', 'USD').format('en-US', { maximumFractionDigits: 2 }) // '$0.13'
+     * ```
+     */
+    format(locale?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string;
+    /**
+     * The same as {@link Currency.format}, under the name `Intl` and Temporal use.
+     * @example
+     * ```ts
+     * new Currency(5, 'GBP').toLocaleString('en-GB') // '£5.00'
+     * ```
+     */
+    toLocaleString(locales?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions): string;
+    /**
+     * The amount's canonical string and the code, such as `'12.5 USD'`, for logs and keys.
+     * @example
+     * ```ts
+     * new Currency('12.50', 'usd').toString() // '12.5 USD'
+     * ```
+     */
+    toString(): string;
+    /** The same string as {@link Currency.toString}, so `JSON.stringify` keeps every digit. */
+    toJSON(): string;
+    /**
+     * Throws, so `<` and `+` cannot silently compare or add amounts. Use {@link Currency.compare}
+     * or {@link Currency.add}.
+     * @throws {TypeError} always.
+     */
+    valueOf(): never;
+}