@ac-kit/core 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024-2026 Anthony Champagne and contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,39 @@
+# @ac-kit/core
+
+The operations the JavaScript standard library leaves out, with no domain
+knowledge of its own — the base every other `@ac-kit` package is built on.
+
+Nothing here invents a concept. Each function is one a program keeps needing and
+keeps reimplementing slightly differently: comparing two values deeply, clamping
+a number, grouping a `Map`, reading a big-endian integer out of a buffer,
+serialising an object that turns out to be cyclic.
+
+```ts
+import { ByteReader, defaults, jsonSerializeSafe } from "@ac-kit/core";
+
+// Options merging that keeps an explicit `undefined` from clobbering a default.
+const options = defaults(userOptions, { retries: 3, timeoutMs: 1_000 });
+
+// A cursor over bytes, so a parser reads fields instead of tracking offsets.
+const reader = new ByteReader(buffer);
+const tag = reader.readByte();
+const payload = reader.read(4);
+
+// Survives cycles instead of throwing.
+jsonSerializeSafe(objectThatReferencesItself);
+```
+
+## What it covers
+
+Organised by the JavaScript type it extends: `array/`, `string/`, `number/`,
+`big-int/`, `map/`, `set/`, `iterable/`, `object/`, `promise/`, `time/`,
+`function/`, plus guards and type helpers, JSON replacers and safe
+serialisation, pattern matching, error utilities, and the `ByteReader` /
+`ByteBuilder` byte cursor.
+
+Portable: no Node.js built-ins, so it runs unchanged in browsers, Deno, Bun and
+edge runtimes. The host-bound counterpart is `@ac-kit/node`.
+
+See the
+[generated API docs](https://anthochamp.github.io/node-essentials/api/core/)
+for the full reference.

package/dist/array/find-index.d.ts

@@ -0,0 +1,19 @@
+import { EqualityComparisonStrategy } from "../object/is-equal.js";
+export declare const FIND_INDEX_DEFAULT_COMPARISON_STRATEGY: EqualityComparisonStrategy;
+/**
+ * Finds the index of an item in an array using a specified equality comparison
+ * strategy.
+ *
+ * Note: "strict" comparison uses the built-in `Array.prototype.indexOf` method,
+ * which is faster than a custom comparison function. For other strategies, a
+ * linear search (O(n)) is performed. On a sorted array, consider using a binary
+ * search for better performance.
+ *
+ * @param array The array to search in.
+ * @param item The item to find.
+ * @param comparisonStrategy The equality comparison strategy to use (default is
+ *   "strict").
+ * @returns The index of the item in the array, or -1 if not found.
+ */
+export declare function findIndex<T>(array: T[], item: T, comparisonStrategy?: EqualityComparisonStrategy<T, T>): number;
+//# sourceMappingURL=find-index.d.ts.map

package/dist/array/find-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-index.d.ts","sourceRoot":"","sources":["../../src/array/find-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAW,MAAM,uBAAuB,CAAC;AAE5E,eAAO,MAAM,sCAAsC,EAAE,0BAC5C,CAAC;AAEV;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAC1B,KAAK,EAAE,CAAC,EAAE,EACV,IAAI,EAAE,CAAC,EACP,kBAAkB,GAAE,0BAA0B,CAC7C,CAAC,EACD,CAAC,CACwC,GACxC,MAAM,CAWR"}

package/dist/array/find-index.js

@@ -0,0 +1,29 @@
+import { isEqual } from "../object/is-equal.js";
+export const FIND_INDEX_DEFAULT_COMPARISON_STRATEGY = "strict";
+/**
+ * Finds the index of an item in an array using a specified equality comparison
+ * strategy.
+ *
+ * Note: "strict" comparison uses the built-in `Array.prototype.indexOf` method,
+ * which is faster than a custom comparison function. For other strategies, a
+ * linear search (O(n)) is performed. On a sorted array, consider using a binary
+ * search for better performance.
+ *
+ * @param array The array to search in.
+ * @param item The item to find.
+ * @param comparisonStrategy The equality comparison strategy to use (default is
+ *   "strict").
+ * @returns The index of the item in the array, or -1 if not found.
+ */
+export function findIndex(array, item, comparisonStrategy = FIND_INDEX_DEFAULT_COMPARISON_STRATEGY) {
+    if (comparisonStrategy === "strict") {
+        return array.indexOf(item);
+    }
+    for (let index = 0; index < array.length; index++) {
+        if (isEqual(array[index], item, comparisonStrategy)) {
+            return index;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=find-index.js.map

package/dist/array/find-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-index.js","sourceRoot":"","sources":["../../src/array/find-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAE5E,MAAM,CAAC,MAAM,sCAAsC,GAClD,QAAQ,CAAC;AAEV;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CACxB,KAAU,EACV,IAAO,EACP,kBAAkB,GAGd,sCAAsC;IAE1C,IAAI,kBAAkB,KAAK,QAAQ,EAAE,CAAC;QACrC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACnD,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,CAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,EAAE,CAAC;YACtD,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACX,CAAC"}

package/dist/array/remove-all.d.ts

@@ -0,0 +1,19 @@
+import { type EqualityComparisonStrategy } from "../object/is-equal.js";
+export declare const REMOVE_DEFAULT_COMPARISON_STRATEGY: EqualityComparisonStrategy;
+/**
+ * Removes all occurrences of an item from an array safely, ensuring that only
+ * exact matches are removed.
+ *
+ * In asynchronous concurrent scenarios, this function ensures that the item
+ * being removed is the same as the one found at the index, preventing
+ * accidental removal of different items that may have been inserted or modified
+ * in the array during the operation.
+ *
+ * @param array The array to remove items from.
+ * @param item The item to remove.
+ * @param comparisonStrategy The equality comparison strategy to use (default is
+ *   "strict").
+ * @returns An array of removed items.
+ */
+export declare function removeAll<T>(array: T[], item: T, comparisonStrategy?: EqualityComparisonStrategy<T, T>): T[];
+//# sourceMappingURL=remove-all.d.ts.map

package/dist/array/remove-all.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-all.d.ts","sourceRoot":"","sources":["../../src/array/remove-all.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,0BAA0B,EAE/B,MAAM,uBAAuB,CAAC;AAM/B,eAAO,MAAM,kCAAkC,EAAE,0BACV,CAAC;AAExC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAC1B,KAAK,EAAE,CAAC,EAAE,EACV,IAAI,EAAE,CAAC,EACP,kBAAkB,GAAE,0BAA0B,CAC7C,CAAC,EACD,CAAC,CACoC,GACpC,CAAC,EAAE,CAkBL"}

package/dist/array/remove-all.js

@@ -0,0 +1,36 @@
+import { isEqual, } from "../object/is-equal.js";
+import { FIND_INDEX_DEFAULT_COMPARISON_STRATEGY, findIndex, } from "./find-index.js";
+export const REMOVE_DEFAULT_COMPARISON_STRATEGY = FIND_INDEX_DEFAULT_COMPARISON_STRATEGY;
+/**
+ * Removes all occurrences of an item from an array safely, ensuring that only
+ * exact matches are removed.
+ *
+ * In asynchronous concurrent scenarios, this function ensures that the item
+ * being removed is the same as the one found at the index, preventing
+ * accidental removal of different items that may have been inserted or modified
+ * in the array during the operation.
+ *
+ * @param array The array to remove items from.
+ * @param item The item to remove.
+ * @param comparisonStrategy The equality comparison strategy to use (default is
+ *   "strict").
+ * @returns An array of removed items.
+ */
+export function removeAll(array, item, comparisonStrategy = REMOVE_DEFAULT_COMPARISON_STRATEGY) {
+    const removedItems = [];
+    let index;
+    while ((index = findIndex(array, item, comparisonStrategy)) !== -1) {
+        const removed = array.splice(index, 1);
+        if (removed.length > 0) {
+            if (isEqual(removed[0], item, comparisonStrategy)) {
+                removedItems.push(removed[0]);
+            }
+            else {
+                // Re-insert the item if it does not match
+                array.splice(index, 0, ...removed);
+            }
+        }
+    }
+    return removedItems;
+}
+//# sourceMappingURL=remove-all.js.map

package/dist/array/remove-all.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-all.js","sourceRoot":"","sources":["../../src/array/remove-all.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,OAAO,GACP,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACN,sCAAsC,EACtC,SAAS,GACT,MAAM,iBAAiB,CAAC;AAEzB,MAAM,CAAC,MAAM,kCAAkC,GAC9C,sCAAsC,CAAC;AAExC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,SAAS,CACxB,KAAU,EACV,IAAO,EACP,kBAAkB,GAGd,kCAAkC;IAEtC,MAAM,YAAY,GAAQ,EAAE,CAAC;IAE7B,IAAI,KAAa,CAAC;IAClB,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,kBAAkB,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACpE,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAEvC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAE,EAAE,IAAI,EAAE,kBAAkB,CAAC,EAAE,CAAC;gBACpD,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC;YAChC,CAAC;iBAAM,CAAC;gBACP,0CAA0C;gBAC1C,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC;YACpC,CAAC;QACF,CAAC;IACF,CAAC;IAED,OAAO,YAAY,CAAC;AACrB,CAAC"}

package/dist/big-int/abs.d.ts

@@ -0,0 +1,3 @@
+/** Absolute value — the `bigint` equivalent `Math.abs` does not accept. */
+export declare function bigIntAbs(value: bigint): bigint;
+//# sourceMappingURL=abs.d.ts.map

package/dist/big-int/abs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abs.d.ts","sourceRoot":"","sources":["../../src/big-int/abs.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/big-int/abs.js

@@ -0,0 +1,5 @@
+/** Absolute value — the `bigint` equivalent `Math.abs` does not accept. */
+export function bigIntAbs(value) {
+    return value < 0n ? -value : value;
+}
+//# sourceMappingURL=abs.js.map

package/dist/big-int/abs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abs.js","sourceRoot":"","sources":["../../src/big-int/abs.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,MAAM,UAAU,SAAS,CAAC,KAAa;IACtC,OAAO,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AACpC,CAAC"}

package/dist/big-int/bit/bit-reverse64.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Reverses the bit order within the low 64 bits of `value`.
+ *
+ * The 64-bit counterpart of {@link bitReverse32}: the same halving strategy
+ * (pairs, nibbles, bytes, halfwords, then the two 32-bit halves) with `bigint`
+ * masks.
+ *
+ * @param value - The value to reverse; only its low 64 bits are considered.
+ * @returns The bit-reversed value as an unsigned 64-bit integer.
+ */
+export declare function bitReverse64(value: bigint): bigint;
+//# sourceMappingURL=bit-reverse64.d.ts.map

package/dist/big-int/bit/bit-reverse64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bit-reverse64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/bit-reverse64.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWlD"}

package/dist/big-int/bit/bit-reverse64.js

@@ -0,0 +1,23 @@
+import { MASK_64N } from "../../constants/mask.js";
+import { mask64 } from "./mask64.js";
+/**
+ * Reverses the bit order within the low 64 bits of `value`.
+ *
+ * The 64-bit counterpart of {@link bitReverse32}: the same halving strategy
+ * (pairs, nibbles, bytes, halfwords, then the two 32-bit halves) with `bigint`
+ * masks.
+ *
+ * @param value - The value to reverse; only its low 64 bits are considered.
+ * @returns The bit-reversed value as an unsigned 64-bit integer.
+ */
+export function bitReverse64(value) {
+    let v = mask64(value);
+    v = ((v >> 1n) & 0x5555555555555555n) | ((v & 0x5555555555555555n) << 1n);
+    v = ((v >> 2n) & 0x3333333333333333n) | ((v & 0x3333333333333333n) << 2n);
+    v = ((v >> 4n) & 0x0f0f0f0f0f0f0f0fn) | ((v & 0x0f0f0f0f0f0f0f0fn) << 4n);
+    v = ((v >> 8n) & 0x00ff00ff00ff00ffn) | ((v & 0x00ff00ff00ff00ffn) << 8n);
+    v = ((v >> 16n) & 0x0000ffff0000ffffn) | ((v & 0x0000ffff0000ffffn) << 16n);
+    v = (v >> 32n) | ((v << 32n) & MASK_64N);
+    return mask64(v);
+}
+//# sourceMappingURL=bit-reverse64.js.map

package/dist/big-int/bit/bit-reverse64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bit-reverse64.js","sourceRoot":"","sources":["../../../src/big-int/bit/bit-reverse64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACzC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEtB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,IAAI,GAAG,CAAC,CAAC;IAC5E,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAEzC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/big-int/bit/byte-swap64.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reverses the byte order within the low 64 bits of `value`.
+ *
+ * The 64-bit counterpart of {@link byteSwap32}: swaps adjacent byte-pairs, then
+ * 16-bit halfwords, then the two 32-bit halves, with `bigint` masks.
+ *
+ * @param value - The value to byte-swap; only its low 64 bits are considered.
+ * @returns The byte-swapped value as an unsigned 64-bit integer.
+ */
+export declare function byteSwap64(value: bigint): bigint;
+//# sourceMappingURL=byte-swap64.d.ts.map

package/dist/big-int/bit/byte-swap64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-swap64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/byte-swap64.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhD"}

package/dist/big-int/bit/byte-swap64.js

@@ -0,0 +1,18 @@
+import { mask64 } from "./mask64.js";
+/**
+ * Reverses the byte order within the low 64 bits of `value`.
+ *
+ * The 64-bit counterpart of {@link byteSwap32}: swaps adjacent byte-pairs, then
+ * 16-bit halfwords, then the two 32-bit halves, with `bigint` masks.
+ *
+ * @param value - The value to byte-swap; only its low 64 bits are considered.
+ * @returns The byte-swapped value as an unsigned 64-bit integer.
+ */
+export function byteSwap64(value) {
+    let v = mask64(value);
+    v = ((v >> 8n) & 0x00ff00ff00ff00ffn) | ((v & 0x00ff00ff00ff00ffn) << 8n);
+    v = ((v >> 16n) & 0x0000ffff0000ffffn) | ((v & 0x0000ffff0000ffffn) << 16n);
+    v = (v >> 32n) | mask64(v << 32n);
+    return mask64(v);
+}
+//# sourceMappingURL=byte-swap64.js.map

package/dist/big-int/bit/byte-swap64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-swap64.js","sourceRoot":"","sources":["../../../src/big-int/bit/byte-swap64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACvC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEtB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,mBAAmB,CAAC,IAAI,GAAG,CAAC,CAAC;IAC5E,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;IAElC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/big-int/bit/clz64.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Counts the leading zero bits in the low 64 bits of `value`.
+ *
+ * The generalisation of `Math.clz32`, which stops at 32 bits, and the high-end
+ * counterpart of {@link ctz64}.
+ *
+ * @param value - The value to inspect; only its low 64 bits are considered.
+ * @returns The number of leading zero bits, from 0 to 64. `clz64(0n)` is 64,
+ *   matching `Math.clz32(0)` being 32.
+ */
+export declare function clz64(value: bigint): number;
+//# sourceMappingURL=clz64.d.ts.map

package/dist/big-int/bit/clz64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clz64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/clz64.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3C"}

package/dist/big-int/bit/clz64.js

@@ -0,0 +1,16 @@
+import { bigIntBitLength } from "../bit-length.js";
+import { mask64 } from "./mask64.js";
+/**
+ * Counts the leading zero bits in the low 64 bits of `value`.
+ *
+ * The generalisation of `Math.clz32`, which stops at 32 bits, and the high-end
+ * counterpart of {@link ctz64}.
+ *
+ * @param value - The value to inspect; only its low 64 bits are considered.
+ * @returns The number of leading zero bits, from 0 to 64. `clz64(0n)` is 64,
+ *   matching `Math.clz32(0)` being 32.
+ */
+export function clz64(value) {
+    return 64 - bigIntBitLength(mask64(value));
+}
+//# sourceMappingURL=clz64.js.map

package/dist/big-int/bit/clz64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clz64.js","sourceRoot":"","sources":["../../../src/big-int/bit/clz64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,UAAU,KAAK,CAAC,KAAa;IAClC,OAAO,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5C,CAAC"}

package/dist/big-int/bit/ctz64.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Counts the trailing zero bits in the low 64 bits of `value`.
+ *
+ * The 64-bit counterpart of {@link ctz32} — see its doc for the `value & -value`
+ * isolation trick this composes with {@link popCount64}.
+ *
+ * @param value - The value to inspect; only its low 64 bits are considered.
+ * @returns The number of trailing zero bits, from 0 to 64.
+ */
+export declare function ctz64(value: bigint): number;
+//# sourceMappingURL=ctz64.d.ts.map

package/dist/big-int/bit/ctz64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctz64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/ctz64.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI3C"}

package/dist/big-int/bit/ctz64.js

@@ -0,0 +1,16 @@
+import { mask64 } from "./mask64.js";
+import { popCount64 } from "./pop-count64.js";
+/**
+ * Counts the trailing zero bits in the low 64 bits of `value`.
+ *
+ * The 64-bit counterpart of {@link ctz32} — see its doc for the `value & -value`
+ * isolation trick this composes with {@link popCount64}.
+ *
+ * @param value - The value to inspect; only its low 64 bits are considered.
+ * @returns The number of trailing zero bits, from 0 to 64.
+ */
+export function ctz64(value) {
+    const x = mask64(value);
+    return popCount64((x & -x) - 1n);
+}
+//# sourceMappingURL=ctz64.js.map

package/dist/big-int/bit/ctz64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctz64.js","sourceRoot":"","sources":["../../../src/big-int/bit/ctz64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,UAAU,KAAK,CAAC,KAAa;IAClC,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAExB,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;AAClC,CAAC"}

package/dist/big-int/bit/mask64.d.ts

@@ -0,0 +1,3 @@
+/** Masks a `bigint` to 64 bits, returning the low 64 bits of the value. */
+export declare function mask64(value: bigint): bigint;
+//# sourceMappingURL=mask64.d.ts.map

package/dist/big-int/bit/mask64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/mask64.ts"],"names":[],"mappings":"AAEA,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5C"}

package/dist/big-int/bit/mask64.js

@@ -0,0 +1,6 @@
+import { MASK_64N } from "../../constants/mask.js";
+/** Masks a `bigint` to 64 bits, returning the low 64 bits of the value. */
+export function mask64(value) {
+    return value & MASK_64N;
+}
+//# sourceMappingURL=mask64.js.map

package/dist/big-int/bit/mask64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask64.js","sourceRoot":"","sources":["../../../src/big-int/bit/mask64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,2EAA2E;AAC3E,MAAM,UAAU,MAAM,CAAC,KAAa;IACnC,OAAO,KAAK,GAAG,QAAQ,CAAC;AACzB,CAAC"}

package/dist/big-int/bit/mul-wide64.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Computes the wide product of two 64-bit `bigint`s, returning the low and high
+ * 64 bits of the result.
+ */
+export declare function mulWide64(lhs: bigint, rhs: bigint): {
+    low: bigint;
+    high: bigint;
+};
+//# sourceMappingURL=mul-wide64.d.ts.map

package/dist/big-int/bit/mul-wide64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mul-wide64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/mul-wide64.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,SAAS,CACxB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACT;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAI/B"}

package/dist/big-int/bit/mul-wide64.js

@@ -0,0 +1,10 @@
+import { mask64 } from "./mask64.js";
+/**
+ * Computes the wide product of two 64-bit `bigint`s, returning the low and high
+ * 64 bits of the result.
+ */
+export function mulWide64(lhs, rhs) {
+    const product = lhs * rhs;
+    return { low: mask64(product), high: mask64(product >> 64n) };
+}
+//# sourceMappingURL=mul-wide64.js.map

package/dist/big-int/bit/mul-wide64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mul-wide64.js","sourceRoot":"","sources":["../../../src/big-int/bit/mul-wide64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;GAGG;AACH,MAAM,UAAU,SAAS,CACxB,GAAW,EACX,GAAW;IAEX,MAAM,OAAO,GAAG,GAAG,GAAG,GAAG,CAAC;IAE1B,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC;AAC/D,CAAC"}

package/dist/big-int/bit/pop-count.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Counts the set bits across a `bigint` of any width (Hamming weight), where
+ * {@link popCount64} stops at the low 64.
+ *
+ * The magnitude is counted, so a negative value answers the same as its
+ * absolute value. Two's complement would otherwise make every negative number
+ * infinitely wide, which is not a count anyone can use.
+ *
+ * O(n / 64) iterations for an n-bit value, each one a constant-time SWAR
+ * reduction, rather than the O(n) shift-and-test a per-bit loop costs.
+ *
+ * @param value The value to count.
+ * @returns The number of set bits in `|value|`.
+ */
+export declare function bigIntPopCount(value: bigint): number;
+//# sourceMappingURL=pop-count.d.ts.map

package/dist/big-int/bit/pop-count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pop-count.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/pop-count.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUpD"}

package/dist/big-int/bit/pop-count.js

@@ -0,0 +1,26 @@
+import { mask64 } from "./mask64.js";
+import { popCount64 } from "./pop-count64.js";
+/**
+ * Counts the set bits across a `bigint` of any width (Hamming weight), where
+ * {@link popCount64} stops at the low 64.
+ *
+ * The magnitude is counted, so a negative value answers the same as its
+ * absolute value. Two's complement would otherwise make every negative number
+ * infinitely wide, which is not a count anyone can use.
+ *
+ * O(n / 64) iterations for an n-bit value, each one a constant-time SWAR
+ * reduction, rather than the O(n) shift-and-test a per-bit loop costs.
+ *
+ * @param value The value to count.
+ * @returns The number of set bits in `|value|`.
+ */
+export function bigIntPopCount(value) {
+    let remaining = value < 0n ? -value : value;
+    let count = 0;
+    while (remaining !== 0n) {
+        count += popCount64(mask64(remaining));
+        remaining >>= 64n;
+    }
+    return count;
+}
+//# sourceMappingURL=pop-count.js.map

package/dist/big-int/bit/pop-count.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pop-count.js","sourceRoot":"","sources":["../../../src/big-int/bit/pop-count.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC3C,IAAI,SAAS,GAAG,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;IAC5C,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,OAAO,SAAS,KAAK,EAAE,EAAE,CAAC;QACzB,KAAK,IAAI,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;QACvC,SAAS,KAAK,GAAG,CAAC;IACnB,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/big-int/bit/pop-count64.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Counts the set bits in the low 64 bits of `value` (Hamming weight).
+ *
+ * The 64-bit counterpart of {@link popcount32}: the same SWAR reduction with
+ * `bigint` masks and a final byte-sum multiply instead of a loop.
+ *
+ * @param value - The value to count; only its low 64 bits are considered.
+ * @returns The number of set bits, from 0 to 64.
+ */
+export declare function popCount64(value: bigint): number;
+//# sourceMappingURL=pop-count64.d.ts.map

package/dist/big-int/bit/pop-count64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pop-count64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/pop-count64.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAShD"}

package/dist/big-int/bit/pop-count64.js

@@ -0,0 +1,20 @@
+import { MASK_64N } from "../../constants/mask.js";
+import { mask64 } from "./mask64.js";
+/**
+ * Counts the set bits in the low 64 bits of `value` (Hamming weight).
+ *
+ * The 64-bit counterpart of {@link popcount32}: the same SWAR reduction with
+ * `bigint` masks and a final byte-sum multiply instead of a loop.
+ *
+ * @param value - The value to count; only its low 64 bits are considered.
+ * @returns The number of set bits, from 0 to 64.
+ */
+export function popCount64(value) {
+    let v = mask64(value);
+    v = v - ((v >> 1n) & 0x5555555555555555n);
+    v = (v & 0x3333333333333333n) + ((v >> 2n) & 0x3333333333333333n);
+    v = (v + (v >> 4n)) & 0x0f0f0f0f0f0f0f0fn;
+    v = (v * 0x0101010101010101n) & MASK_64N;
+    return Number((v >> 56n) & 0xffn);
+}
+//# sourceMappingURL=pop-count64.js.map

package/dist/big-int/bit/pop-count64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pop-count64.js","sourceRoot":"","sources":["../../../src/big-int/bit/pop-count64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa;IACvC,IAAI,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEtB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC;IAC1C,CAAC,GAAG,CAAC,CAAC,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC;IAClE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,mBAAmB,CAAC;IAC1C,CAAC,GAAG,CAAC,CAAC,GAAG,mBAAmB,CAAC,GAAG,QAAQ,CAAC;IAEzC,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;AACnC,CAAC"}

package/dist/big-int/bit/rotl64.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rotates `value` left within 64 bits.
+ *
+ * `bigint` shifts are unbounded, so the result has to be masked back down to 64
+ * bits after every rotation.
+ *
+ * @param value - The value to rotate; only its low 64 bits are considered.
+ * @param count - The rotation distance, which must be in the `0n`..`64n` range.
+ * @returns The rotated value as an unsigned 64-bit integer.
+ */
+export declare function rotl64(value: bigint, count: bigint): bigint;
+//# sourceMappingURL=rotl64.d.ts.map

package/dist/big-int/bit/rotl64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotl64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/rotl64.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/big-int/bit/rotl64.js

@@ -0,0 +1,15 @@
+import { mask64 } from "./mask64.js";
+/**
+ * Rotates `value` left within 64 bits.
+ *
+ * `bigint` shifts are unbounded, so the result has to be masked back down to 64
+ * bits after every rotation.
+ *
+ * @param value - The value to rotate; only its low 64 bits are considered.
+ * @param count - The rotation distance, which must be in the `0n`..`64n` range.
+ * @returns The rotated value as an unsigned 64-bit integer.
+ */
+export function rotl64(value, count) {
+    return mask64((value << count) | (value >> (64n - count)));
+}
+//# sourceMappingURL=rotl64.js.map

package/dist/big-int/bit/rotl64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotl64.js","sourceRoot":"","sources":["../../../src/big-int/bit/rotl64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,KAAa;IAClD,OAAO,MAAM,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/big-int/bit/rotr64.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rotates `value` right within 64 bits.
+ *
+ * `bigint` shifts are unbounded, so the result has to be masked back down to 64
+ * bits after every rotation.
+ *
+ * @param value - The value to rotate; only its low 64 bits are considered.
+ * @param count - The rotation distance, which must be in the `0n`..`64n` range.
+ * @returns The rotated value as an unsigned 64-bit integer.
+ */
+export declare function rotr64(value: bigint, count: bigint): bigint;
+//# sourceMappingURL=rotr64.d.ts.map

package/dist/big-int/bit/rotr64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotr64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/rotr64.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D"}

package/dist/big-int/bit/rotr64.js

@@ -0,0 +1,15 @@
+import { mask64 } from "./mask64.js";
+/**
+ * Rotates `value` right within 64 bits.
+ *
+ * `bigint` shifts are unbounded, so the result has to be masked back down to 64
+ * bits after every rotation.
+ *
+ * @param value - The value to rotate; only its low 64 bits are considered.
+ * @param count - The rotation distance, which must be in the `0n`..`64n` range.
+ * @returns The rotated value as an unsigned 64-bit integer.
+ */
+export function rotr64(value, count) {
+    return mask64((value >> count) | (value << (64n - count)));
+}
+//# sourceMappingURL=rotr64.js.map

package/dist/big-int/bit/rotr64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotr64.js","sourceRoot":"","sources":["../../../src/big-int/bit/rotr64.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CAAC,KAAa,EAAE,KAAa;IAClD,OAAO,MAAM,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/big-int/bit/shift-right-unsigned64.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Logical right shift of the low 64 bits — JavaScript's missing `>>>` for
+ * `bigint`, which only has the sign-propagating `>>`.
+ *
+ * The value is taken as an unsigned 64-bit word first, so a negative operand
+ * shifts in zeros from its two's complement pattern rather than ones. A shift
+ * of 64 or more clears the word, matching what a 64-bit machine instruction
+ * would leave behind rather than C's undefined behaviour.
+ *
+ * @param value The word to shift; only its low 64 bits are considered.
+ * @param count Bit positions to shift by. Zero or less returns the word
+ *   unchanged apart from the masking.
+ * @returns The shifted word, always non-negative.
+ */
+export declare function shiftRightUnsigned64(value: bigint, count: number): bigint;
+//# sourceMappingURL=shift-right-unsigned64.d.ts.map

package/dist/big-int/bit/shift-right-unsigned64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shift-right-unsigned64.d.ts","sourceRoot":"","sources":["../../../src/big-int/bit/shift-right-unsigned64.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAYzE"}