atomic-fns 1.1.7 → 2.0.0

package/dist/collections/deque.js

@@ -1,291 +1,239 @@
-import { KeyError, ValueError } from '../globals/index.js';
-import { IterableIterator } from '../itertools/index.js';
-import { eq } from '../operators/index.js';
-import { Sequence } from './abc.js';
+import { assertNotHugeSparse } from './internal/arrayKeys.js';
+import { sameValueZero } from '../internal/compare.js';
+import { iteratesAsArray, requireIterable } from './internal/iterable.js';
+const MIN_CAPACITY = 8;
 /**
- * Fixed capacity double-ended queue implemented as ring deque.
- * @template T
+ * A double-ended queue on a ring buffer, with Array's method names: `push` and `pop` at the end,
+ * `unshift` and `shift` at the front, `at` and `set` by index, all O(1) amortized. It grows by
+ * doubling when unbounded; with `maxlen` it evicts from the opposite end, as Python's `deque` does.
+ * `includes` uses SameValueZero.
+ *
+ * @example
+ * ```ts
+ * const recent = new Deque<number>([], { maxlen: 3 })
+ * recent.push(1, 2, 3, 4)
+ * ;[...recent] // [2, 3, 4]
+ * recent.shift() // 2
+ * ```
  */
-export class Deque extends Sequence {
-    items;
-    start = 0;
-    count = 0;
-    capacity;
-    ArrayConstructor;
-    /**
-     * Creates a new `Deque` instance of a fixed size.
-     * @param {Array} [arrType = []] The initial elements or array type to use (accepts any kind of typed array).
-     * @param {number} [capacity=1024] The fixed size of the deque. Defaults to `1024`.
-     */
-    constructor(arrType = [], capacity = 1024) {
-        super();
-        if (typeof capacity !== 'number' || capacity <= 0)
-            throw new ValueError(`Deque capacity should be a positive integer.`);
-        this.ArrayConstructor = arrType.constructor;
-        this.capacity = capacity;
-        this.items = new this.ArrayConstructor(arrType.length || this.capacity);
-        this.clear();
-        if (arrType.length) {
-            for (const item of arrType) {
-                this.append(item);
-            }
+export class Deque {
+    #buf;
+    #cap;
+    #head = 0;
+    #size = 0;
+    #maxlen;
+    #arrType;
+    #empty;
+    /**
+     * Create a deque holding `items`, in order.
+     * @param items Initial elements, read one at a time. When longer than `maxlen`, only the last
+     * `maxlen` remain.
+     * @param options.maxlen Maximum size; overflow evicts from the opposite end. `0` makes push/unshift
+     * no-ops. `null`, `undefined` and `Infinity` mean unbounded.
+     * @param options.arrType Typed-array (or similar) constructor used for storage.
+     * @throws {TypeError} when `items` is not iterable, or `maxlen` is not a number, `null` or
+     * `undefined`.
+     * @throws {RangeError} when `maxlen` is negative, not an integer, or above
+     * `Number.MAX_SAFE_INTEGER`, or when `items` is a huge sparse array.
+     */
+    constructor(items, options) {
+        const maxlen = options?.maxlen ?? undefined;
+        if (maxlen !== undefined && typeof maxlen !== 'number') {
+            throw new TypeError('maxlen must be a number');
+        }
+        if (maxlen !== undefined &&
+            maxlen !== Infinity &&
+            (!Number.isInteger(maxlen) || maxlen < 0 || maxlen > Number.MAX_SAFE_INTEGER)) {
+            throw new RangeError('maxlen must be a non-negative integer <= Number.MAX_SAFE_INTEGER or Infinity');
+        }
+        this.#maxlen = maxlen === Infinity ? undefined : maxlen;
+        this.#arrType = options?.arrType;
+        this.#empty = this.#alloc(1)[0];
+        const source = requireIterable(items ?? []);
+        if (iteratesAsArray(source))
+            assertNotHugeSparse(source);
+        this.#cap = MIN_CAPACITY;
+        this.#buf = this.#alloc(this.#cap);
+        for (const x of source) {
+            this.#pushOne(x);
         }
     }
-    /** Returns the total number of elements in the deque. */
+    /** The number of elements. */
     get size() {
-        return this.count;
-    }
-    /**
-     * Method used to clear the structure.
-     */
-    clear() {
-        // Properties
-        this.start = 0;
-        this.count = 0;
-    }
-    /**
-     * Alias of {@link Deque.append}
-     * @param {T} item Item to append.
-     * @returns {number} Returns the new size of the deque.
-     */
-    add(item) {
-        return this.append(item);
-    }
-    /**
-     * Appends a new element to the end of the deque.
-     * @param {T} item Item to append.
-     * @returns {number} Returns the new size of the deque.
-     */
-    append(item) {
-        if (this.count === this.capacity)
-            this.popleft();
-        const index = (this.start + this.count) % this.capacity;
-        this.items[index] = item;
-        return ++this.count;
-    }
-    /**
-     * Appends a new element to the beginning of the deque.
-     * @param {T} item Item to prepend.
-     * @returns {number} Returns the new size of the deque.
-     */
-    appendleft(item) {
-        if (this.count === this.capacity)
-            this.pop();
-        let index = this.start - 1;
-        if (this.start === 0)
-            index = this.capacity - 1;
-        this.items[index] = item;
-        this.start = index;
-        return ++this.count;
+        return this.#size;
     }
     /**
-     * Removes and returns the element at the end of the deque.
-     * @returns {?T} Returns the popped item.
+     * Maximum size when constructed with a finite `maxlen`, otherwise `undefined`.
      */
-    pop() {
-        if (this.count === 0)
-            return;
-        const index = (this.start + this.count - 1) % this.capacity;
-        this.count--;
-        return this.items[index];
+    get maxlen() {
+        return this.#maxlen;
     }
-    /**
-     * Alias of {@link Deque.pop}
-     * @returns {?T} Returns the popped item.
-     */
-    remove() {
-        return this.pop();
+    /** `'Deque'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag]() {
+        return 'Deque';
     }
-    /**
-     * Removes and returns the element at the beginning of the deque.
-     * @returns {?T} Returns the removed deque element.
-     */
-    popleft() {
-        if (this.count === 0)
-            return;
-        const index = this.start;
-        this.count--;
-        this.start++;
-        if (this.start === this.capacity)
-            this.start = 0;
-        return this.items[index];
+    /** Remove every element and give back the buffer a burst grew. */
+    clear() {
+        this.#cap = MIN_CAPACITY;
+        this.#buf = this.#alloc(this.#cap);
+        this.#head = 0;
+        this.#size = 0;
     }
     /**
-     * Returns the element at the beginning of the deque.
-     * @returns {?T} The element if exists
+     * Append one or more elements at the end.
+     * @returns The new size.
      */
-    first() {
-        if (this.count === 0)
-            return;
-        return this.items[this.start];
+    push(...xs) {
+        for (const x of xs)
+            this.#pushOne(x);
+        return this.#size;
     }
     /**
-     * Returns the element at a specified index position in the deque.
-     * @param {number} index The given index
-     * @returns {?T} The element if exists
+     * Insert one or more elements at the front, preserving argument order.
+     * @returns The new size.
      */
-    get(index) {
-        if (this.count === 0)
-            return;
-        index = this.start + index;
-        if (index < 0)
-            index += this.count;
-        if (index > this.capacity)
-            index -= this.capacity;
-        return this.items[index];
+    unshift(...xs) {
+        for (let i = xs.length - 1; i >= 0; i--)
+            this.#unshiftOne(xs[i]);
+        return this.#size;
     }
     /**
-     * Update the element at a given `index`.
-     * @param {number} index The given index
+     * Remove and return the last element, or `undefined` when empty.
      */
-    set(index, value) {
-        if (index < 0)
-            index += this.count;
-        if (index > this.count)
-            throw new KeyError(`Invalid index: ${index} not in Deque.`);
-        this.items[index] = value;
+    pop() {
+        if (this.#size === 0)
+            return undefined;
+        const j = this.#phys(this.#size - 1);
+        const x = this.#buf[j];
+        this.#buf[j] = this.#empty;
+        this.#size--;
+        return x;
     }
     /**
-     * Check if a given element is in the deque.
-     * @param {T} x The value to find
-     * @returns {boolean} `true` if the value is found
+     * Remove and return the first element, or `undefined` when empty.
      */
-    contains(x) {
-        for (const value of this.values()) {
-            if (eq(x, value))
-                return true;
-        }
-        return false;
+    shift() {
+        if (this.#size === 0)
+            return undefined;
+        const x = this.#buf[this.#head];
+        this.#buf[this.#head] = this.#empty;
+        this.#head = (this.#head + 1) % this.#cap;
+        this.#size--;
+        return x;
     }
     /**
-     * Returns the first element that matches the `iteratee` function.
-     * @param {Iteratee<T>} iteratee A function that will be invoked per element
-     * @returns {?T} The element if exists
+     * Element at index `i` (negative from the end). Out of range or empty -> `undefined`.
+     * The index coerces as in `Array.prototype.at`; values that coerce to `NaN` mean `0`.
      */
-    find(iteratee) {
-        for (const [key, value] of this.entries()) {
-            if (iteratee(value, key, this))
-                return value;
-        }
+    at(i) {
+        const idx = this.#fromEnd(i);
+        if (idx < 0 || idx >= this.#size)
+            return undefined;
+        return this.#buf[this.#phys(idx)];
     }
     /**
-     * Calls `iteratee` function for every element in the deque.
-     * @param {Iteratee<T>} iteratee A function that will be invoked per element
+     * Replace the element at index `i` (negative from the end). The index coerces as in {@link at}.
+     * @returns `this`
+     * @throws {RangeError} when the index is out of range.
      */
-    forEach(iteratee) {
-        const c = this.capacity;
-        const l = this.count;
-        let i = this.start;
-        let j = 0;
-        while (j < l) {
-            iteratee(this.items[i], j, this);
-            i++;
-            j++;
-            if (i === c)
-                i = 0;
+    set(i, v) {
+        const idx = this.#fromEnd(i);
+        if (idx < 0 || idx >= this.#size) {
+            throw new RangeError(`index ${String(i).slice(0, 40)} out of range`);
         }
+        this.#buf[this.#phys(idx)] = v;
+        return this;
     }
-    /**
-     * Returns a new array with all the elements in reverse order.
-     * @returns {Array<T>} The elements reversed
-     */
-    reversed() {
-        return this.toArray().reverse();
+    /** Whether `value` is present (SameValueZero). */
+    includes(value) {
+        return this.values().some((v) => sameValueZero(v, value));
     }
-    /**
-     * Returns a new array with all the elements in the order they were added to the deque.
-     * @returns {Array<T>} The elements array
-     */
-    toArray() {
-        // Optimization
-        const offset = this.start + this.count;
-        if (offset < this.capacity)
-            return this.items.slice(this.start, offset);
-        const array = new this.ArrayConstructor(this.count);
-        const c = this.capacity;
-        const l = this.count;
-        let i = this.start;
-        let j = 0;
-        while (j < l) {
-            array[j] = this.items[i];
-            i++;
-            j++;
-            if (i === c)
-                i = 0;
+    /** Call `callback(element, index, deque)` for each element, front to back. */
+    forEach(callback, thisArg) {
+        for (let i = 0; i < this.#size; i++) {
+            Reflect.apply(callback, thisArg, [this.#buf[this.#phys(i)], i, this]);
         }
-        return array;
     }
-    /**
-     * Returns an iterator over the deque's values.
-     * @returns {Iterator}
-     */
-    values() {
-        const items = this.items;
-        const c = this.capacity;
-        const l = this.count;
-        let i = this.start;
-        let j = 0;
-        return IterableIterator(() => {
-            if (j >= l)
-                return {
-                    done: true,
-                    value: undefined
-                };
-            const value = items[i];
-            i++;
-            j++;
-            if (i === c)
-                i = 0;
-            return { value };
-        });
+    /** The indices, front to back, as `Array.prototype.keys` gives them. */
+    *keys() {
+        for (let i = 0; i < this.#size; i++)
+            yield i;
     }
-    /**
-     * Alias of {@link Deque.values}. Returns iterator of values.
-     */
-    keys() {
-        return this.values();
+    /** The elements, front to back. */
+    *values() {
+        for (let i = 0; i < this.#size; i++)
+            yield this.#buf[this.#phys(i)];
     }
-    /**
-     * Creates an iterator of `[index, value]` pairs for all elements in the deque.
-     * @returns {Iterator}
-     */
-    entries() {
-        const items = this.items;
-        const c = this.capacity;
-        const l = this.count;
-        let i = this.start;
-        let j = 0;
-        return IterableIterator(() => {
-            if (j >= l)
-                return {
-                    done: true,
-                    value: undefined
-                };
-            const value = items[i];
-            i++;
-            if (i === c)
-                i = 0;
-            return {
-                value: [j++, value]
-            };
-        });
+    /** `[index, element]` pairs, front to back. */
+    *entries() {
+        for (let i = 0; i < this.#size; i++)
+            yield [i, this.#buf[this.#phys(i)]];
     }
+    /** The elements, front to back. */
     [Symbol.iterator]() {
         return this.values();
     }
-    [Symbol.for('nodejs.util.inspect.custom')]() {
-        return this.inspect();
+    /** Index `i` as `Array.prototype.at` reads it: truncated, `NaN` as `0`, negative from the end. */
+    #fromEnd(i) {
+        const idx = Math.trunc(i) || 0;
+        return idx < 0 ? idx + this.#size : idx;
+    }
+    #phys(i) {
+        return (this.#head + i) % this.#cap;
+    }
+    #alloc(n) {
+        if (this.#arrType)
+            return new this.#arrType(n);
+        return new Array(n);
+    }
+    /** Double the buffer, clamped to `maxlen`. Called only when full and below `maxlen`. */
+    #grow() {
+        let newCap = this.#cap * 2;
+        if (this.#maxlen !== undefined)
+            newCap = Math.min(newCap, this.#maxlen);
+        const nb = this.#alloc(newCap);
+        for (let i = 0; i < this.#size; i++)
+            nb[i] = this.#buf[this.#phys(i)];
+        this.#buf = nb;
+        this.#cap = newCap;
+        this.#head = 0;
+    }
+    // Both inserts write the new slot before they move `#head` or `#size`, so a value that typed
+    // storage rejects leaves the deque as it was, the element it would evict included. At `maxlen`
+    // with a full buffer the new slot is the one being evicted, so the write itself evicts it.
+    #pushOne(x) {
+        if (this.#maxlen === 0)
+            return;
+        const atMaxlen = this.#size === this.#maxlen;
+        if (!atMaxlen && this.#size === this.#cap)
+            this.#grow();
+        const j = this.#phys(this.#size);
+        this.#buf[j] = x;
+        if (atMaxlen) {
+            if (j !== this.#head)
+                this.#buf[this.#head] = this.#empty;
+            this.#head = (this.#head + 1) % this.#cap;
+        }
+        else {
+            this.#size++;
+        }
     }
-    // This is just for debugging in nodejs
-    inspect() {
-        const array = this.toArray();
-        array.type = this.ArrayConstructor.name;
-        array.capacity = this.capacity;
-        // Trick so that node displays the name of the constructor
-        Object.defineProperty(array, 'constructor', {
-            value: Deque,
-            enumerable: false
-        });
-        return array;
+    #unshiftOne(x) {
+        if (this.#maxlen === 0)
+            return;
+        const atMaxlen = this.#size === this.#maxlen;
+        if (!atMaxlen && this.#size === this.#cap)
+            this.#grow();
+        const j = (this.#head - 1 + this.#cap) % this.#cap;
+        this.#buf[j] = x;
+        if (atMaxlen) {
+            const back = this.#phys(this.#size - 1);
+            if (j !== back)
+                this.#buf[back] = this.#empty;
+        }
+        else {
+            this.#size++;
+        }
+        this.#head = j;
     }
 }

package/dist/collections/entries.d.ts

@@ -0,0 +1,89 @@
+/**
+ * What a collection holds: `keys`, `values`, `entries`, `size`, `isEmpty`, `includes`.
+ */
+import { type Collection, type CollectionKey, type CollectionValue } from './shape.js';
+/**
+ * The keys of `collection`: indices of an array (holes skipped), typed array, string (one per code
+ * point) or other iterable, the keys of a `Map`, the members of a `Set`, and the own enumerable
+ * string keys of any other object. `null`, `undefined`, numbers, booleans, bigints and symbols
+ * have none. Other iterables are consumed to obtain positions.
+ * @param collection The collection to read.
+ * @returns A new array of keys, in iteration order.
+ * @example
+ * ```ts
+ * keys({ a: 1, b: 2 }) // ['a', 'b']
+ * keys(new Map([['x', 1]])) // ['x']
+ * keys('héllo') // [0, 1, 2, 3, 4]
+ * ```
+ */
+export declare function keys<C extends Collection>(collection: C): CollectionKey<C>[];
+/**
+ * The values of `collection`, in the order {@link keys} gives their keys.
+ * @param collection The collection to read.
+ * @returns A new array of values.
+ * @example
+ * ```ts
+ * values({ a: 1, b: 2 }) // [1, 2]
+ * values(new Map([['x', 1]])) // [1]
+ * values('👍🏽!') // ['👍', '🏽', '!']
+ * ```
+ */
+export declare function values<C extends Collection>(collection: C): CollectionValue<C>[];
+/**
+ * The `[key, value]` pairs of `collection`, as `Map.prototype.entries` gives them.
+ * @param collection The collection to read.
+ * @returns A new array of pairs.
+ * @example
+ * ```ts
+ * entries({ a: 1 }) // [['a', 1]]
+ * entries(['x', 'y']) // [[0, 'x'], [1, 'y']]
+ * entries(new Set(['s'])) // [['s', 's']]
+ * ```
+ */
+export declare function entries<C extends Collection>(collection: C): [CollectionKey<C>, CollectionValue<C>][];
+/**
+ * How many entries `collection` has: the `size` of a `Map` or `Set`, the present elements of an
+ * array (holes do not count), the length of a typed array, the code points of a string, the own
+ * enumerable string keys of an object. An iterable that is none of these is read to its end to
+ * count it, so a one-shot iterator such as a generator is exhausted.
+ * @param collection The collection to measure.
+ * @returns The number of entries.
+ * @example
+ * ```ts
+ * size({ a: 1, b: 2 }) // 2
+ * size([1, , 3]) // 2
+ * size('👍🏽') // 2
+ * ```
+ */
+export declare function size(collection: Collection): number;
+/**
+ * True when `collection` has no entries, by the rules of {@link size}. An iterable is read only
+ * until its first element, and is then closed, so a one-shot iterator such as a generator has
+ * nothing left to give.
+ * @param collection The collection to test.
+ * @returns Whether it has no entries.
+ * @example
+ * ```ts
+ * isEmpty({}) // true
+ * isEmpty([, ,]) // true
+ * isEmpty(new Map([[1, 2]])) // false
+ * isEmpty(null) // true
+ * ```
+ */
+export declare function isEmpty(collection: Collection): boolean;
+/**
+ * True when `collection` holds `value`, compared with SameValueZero against its values (`NaN`
+ * finds `NaN`, `0` finds `-0`). For a string, `value` is a substring, as
+ * `String.prototype.includes` reads it. An iterable is read until the first match, where it is
+ * closed, or to its end, so a one-shot iterator such as a generator is used up either way.
+ * @param collection The collection to search.
+ * @param value The value to look for.
+ * @returns Whether it is there.
+ * @example
+ * ```ts
+ * includes({ a: 1 }, 1) // true
+ * includes(new Map([['k', NaN]]), NaN) // true
+ * includes('hello', 'ell') // true
+ * ```
+ */
+export declare function includes<C extends Collection>(collection: C, value: C extends string ? string : CollectionValue<C>): boolean;