@sepiariver/unique-set 2.0.0 → 2.0.1

package/README.md

@@ -4,15 +4,25 @@ Extends the native `Set` class to deeply compare using [fast-deep-equal](https:/
 
 Supports ESM and CommonJS.
 
+```js
+import { BloomSet, UniqueSet } from '@sepiariver/unique-set';
+```
+
+```js
+const { BloomSet, UniqueSet } = require('@sepiariver/unique-set');
+```
+
 WARNING: This version exports 2 classes instead of a single default class, breaking b/c with version 1.
 
-The extended methods iterate through the elements of the `UniqueSet` until equality is found. If no elements match, the entire `UniqueSet` would have been iterated. However fast `fast-deep-equal` is, calling it in a loop like this makes performance many, many times worse than the native `Set`. For datasets greater than a thousand elements, there is probably a better way to achieve what you're trying to do. Otherwise, `UniqueSet` is convenient.
+The overridden methods iterate through the elements of the `UniqueSet` deeply comparing equality until existence is found. If no elements match, the entire `UniqueSet` would have been iterated. However fast `fast-deep-equal` is [reported to be](https://github.com/epoberezkin/fast-deep-equal?tab=readme-ov-file#performance-benchmark), its time complexity is dependent on the depth of objects being compared. Calling it in a loop makes performance many, many times worse than the native `Set`.
+
+_For datasets greater than a thousand elements, there is probably a better way to achieve what you're trying to do._ Otherwise, `UniqueSet` is convenient.
 
-UPDATE: Version 2 ships with `BloomSet`, in which equality checks are optimized with a Bloom filter. This class is useful for larger datasets, performing about 3-10 times faster than `UniqueSet` for datasets greater than 1000 elements. Less than a few hundred (~400) elements, `UniqueSet` is faster. `BloomSet`'s probabilistic false positives are covered by a fallback to `fast-deep-equal`. BloomSet is still orders of magnitude slower than the native `Set`, but if deep equality is required, this is a decent option.
+**UPDATE:** Version 2 ships with `BloomSet`, which uses a Bloom filter to greatly optimize absence checks, falling back to `fast-deep-equal` to validate potential false positives. This class is useful for larger datasets, up to the tens of thousands or even 100k depending largely on configuration. It performs about 3-10 times faster than `UniqueSet` for datasets greater than 1000 elements. Less than a few hundred (~400) elements, `UniqueSet` can be faster—it all depens on your dataset and config options. In all scenarios except the absolute best case, BloomSet is still orders of magnitude slower than the native `Set`, but if deep equality is required, this is a decent option.
 
-Experiment with configurations to find the best performance for your use case.
+Highly recommended: experiment with config options to find the best performance for your use case.
 
-NOTE: The `delete` method is unmodified. In the case of duplicate objects that are equivalent but have different references, the results of `delete` operations may be unexpected.
+IMPORTANT: The `delete` method is unmodified in both classes. In the case of duplicate objects that are equivalent but have different references, the results of `delete` operations may be unexpected.
 
 ## Config Options
 

package/{index.d.ts → dist/index.d.mts}

@@ -1,34 +1,23 @@
-declare module "unique-set" {
-  /**
-   * A `Set` extension that ensures uniqueness of items using deep equality checks.
-   */
-  export class UniqueSet<T> extends Set<T> {
-    /**
-     * Creates a new `UniqueSet` instance.
-     * @param iterable Optional: an iterable with which to initialize the UniqueSet.
-     * @throws TypeError If the input is not iterable.
-     */
+/** A `Set` extension that ensures uniqueness of items using deep equality checks. */
+declare class UniqueSet<T> extends Set<T> {
+    /*** @throws TypeError If the input is not iterable. */
     constructor(iterable?: Iterable<T>);
-
     /**
      * Determines whether an object is in the UniqueSet using deep equality.
      * @param o The object to check for presence in the UniqueSet.
      * @returns `true` if the object is found, `false` otherwise.
      */
     has(o: T): boolean;
-
     /**
      * Adds a new object to the UniqueSet if it is not already present.
      * @param o The object to add to the UniqueSet.
      * @returns The `UniqueSet` instance, allowing for chaining.
      */
     add(o: T): this;
-  }
-
-  /**
-   * A `Set` extension that uses a Bloom filter for fast existence checks combined with deep equality for accuracy.
-   */
-  export class BloomSet<T> extends Set<T> {
+}
+/** A `Set` extension that uses a Bloom filter for fast existence checks combined with deep equality for accuracy. */
+declare class BloomSet<T> extends Set<T> {
+    #private;
     /**
      * Creates a new `BloomSet` instance.
      * @param iterable Optional: an iterable object with which to initialize the BloomSet.
@@ -37,24 +26,16 @@ declare module "unique-set" {
      * @param options.hashCount The number of hash functions to use. Defaults to 7.
      * @throws TypeError If the input is not iterable.
      */
-    constructor(
-      iterable?: Iterable<T>,
-      options?: { size?: number; hashCount?: number }
-    );
-
-    /**
-     * Determines existence of an object in the BloomSet using the Bloom filter and deep equality.
-     * @param o The object to check for presence in the BloomSet.
-     * @returns `true` if the object is found, `false` otherwise.
-     */
+    constructor(iterable?: Iterable<T>, options?: {
+        size?: number;
+        hashCount?: number;
+    });
+    /** Determines existence of an object in the BloomSet using the Bloom filter and deep equality */
     has(o: T): boolean;
-
-    /**
-     * Adds a new object to the BloomSet if it is not already present.
-     * @param o The object to add to the BloomSet.
+    /** Adds a new object to the BloomSet if it is not already present.
      * @returns The `BloomSet` instance, allowing for chaining.
      */
     add(o: T): this;
-  }
-
 }
+
+export { BloomSet, UniqueSet };

package/dist/index.mjs

@@ -0,0 +1,182 @@
+// index.ts
+import equal from "fast-deep-equal/es6/index.js";
+var UniqueSet = class extends Set {
+  /*** @throws TypeError If the input is not iterable. */
+  constructor(iterable = []) {
+    if (!Array.isArray(iterable) && !iterable[Symbol.iterator]) {
+      throw new TypeError("UniqueSet requires an iterable");
+    }
+    super();
+    for (const item of iterable) {
+      this.add(item);
+    }
+  }
+  /**
+   * Determines whether an object is in the UniqueSet using deep equality.
+   * @param o The object to check for presence in the UniqueSet.
+   * @returns `true` if the object is found, `false` otherwise.
+   */
+  has(o) {
+    for (const i of this) {
+      if (equal(o, i)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Adds a new object to the UniqueSet if it is not already present.
+   * @param o The object to add to the UniqueSet.
+   * @returns The `UniqueSet` instance, allowing for chaining.
+   */
+  add(o) {
+    if (!this.has(o)) {
+      super.add(o);
+    }
+    return this;
+  }
+};
+var BloomSet = class extends Set {
+  #bitArray;
+  #aSize;
+  #hashCount;
+  /**
+   * Creates a new `BloomSet` instance.
+   * @param iterable Optional: an iterable object with which to initialize the BloomSet.
+   * @param options Bloom filter configuration options.
+   * @param options.size The size of the Bloom filter's bit array. Defaults to 6553577.
+   * @param options.hashCount The number of hash functions to use. Defaults to 7.
+   * @throws TypeError If the input is not iterable.
+   */
+  constructor(iterable = [], options = {}) {
+    if (!Array.isArray(iterable) && !iterable[Symbol.iterator]) {
+      throw new TypeError("BloomSet requires an iterable");
+    }
+    super();
+    if (!options || typeof options !== "object") {
+      options = {};
+    }
+    options.hashCount ??= 7;
+    options.size ??= 6553577;
+    let { size, hashCount } = options;
+    if (typeof size !== "number" || size <= 0) {
+      size = 6553577;
+    }
+    this.#aSize = this.#findNextPrime(size);
+    if (typeof hashCount !== "number" || hashCount <= 0) {
+      hashCount = 7;
+    }
+    this.#hashCount = hashCount;
+    this.#bitArray = new Uint8Array(Math.ceil(size / 8));
+    for (const item of iterable) {
+      this.add(item);
+    }
+  }
+  /** @internal */
+  #findNextPrime(num) {
+    if (num < 2) return 2;
+    if (num % 2 === 0) num++;
+    while (!this.#isPrime(num)) {
+      num += 2;
+    }
+    return num;
+  }
+  /** @internal */
+  #isPrime(num) {
+    if (num < 2) return false;
+    if (num === 2 || num === 3) return true;
+    if (num % 2 === 0 || num % 3 === 0) return false;
+    const sqrt = Math.floor(Math.sqrt(num));
+    for (let i = 5; i <= sqrt; i += 6) {
+      if (num % i === 0 || num % (i + 2) === 0) return false;
+    }
+    return true;
+  }
+  /** @internal */
+  #serialize(item) {
+    if (typeof item === "number" && isNaN(item)) {
+      return "NaN";
+    }
+    if (item && typeof item === "object") {
+      const serialize = this.#serialize.bind(this);
+      if (Array.isArray(item)) {
+        return `[${item.map(serialize).join(",")}]`;
+      } else {
+        return `{${Object.entries(item).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}:${serialize(v)}`).join(",")}}`;
+      }
+    }
+    return String(item);
+  }
+  /** @internal */
+  #hashes(item) {
+    const hashes = [];
+    const str = this.#serialize(item);
+    let hash = this.#fnv1a(str);
+    for (let i = 0; i < this.#hashCount; i++) {
+      hash %= this.#aSize;
+      hashes.push(hash);
+      hash = (hash ^ hash >>> 13) * 3266489909;
+      hash >>>= 0;
+    }
+    return hashes;
+  }
+  /** @internal */
+  #fnv1a(str) {
+    if (typeof str !== "string") {
+      str = String(str);
+    }
+    let hash = 2166136261;
+    for (let i = 0; i < str.length; i++) {
+      hash ^= str.charCodeAt(i);
+      hash = hash * 16777619 >>> 0;
+    }
+    return hash >>> 0;
+  }
+  /** @internal */
+  #setBits(hashes) {
+    for (const hash of hashes) {
+      const index = Math.floor(hash / 8);
+      const bit = hash % 8;
+      this.#bitArray[index] |= 1 << bit;
+    }
+  }
+  /** @internal */
+  #checkBits(hashes) {
+    for (const hash of hashes) {
+      const index = Math.floor(hash / 8);
+      const bit = hash % 8;
+      if (!(this.#bitArray[index] & 1 << bit)) {
+        return false;
+      }
+    }
+    return true;
+  }
+  /** Determines existence of an object in the BloomSet using the Bloom filter and deep equality */
+  has(o) {
+    const hashes = this.#hashes(o);
+    if (!this.#checkBits(hashes)) {
+      return false;
+    }
+    for (const i of this) {
+      if (equal(o, i)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /** Adds a new object to the BloomSet if it is not already present.
+   * @returns The `BloomSet` instance, allowing for chaining.
+   */
+  add(o) {
+    if (!this.has(o)) {
+      const hashes = this.#hashes(o);
+      this.#setBits(hashes);
+      super.add(o);
+    }
+    return this;
+  }
+};
+export {
+  BloomSet,
+  UniqueSet
+};

package/{src/index.js → index.ts}

@@ -1,7 +1,9 @@
-import equal from "fast-deep-equal";
+import equal from "fast-deep-equal/es6/index.js";
 
-export class UniqueSet extends Set {
-  constructor(iterable = []) {
+/** A `Set` extension that ensures uniqueness of items using deep equality checks. */
+export class UniqueSet<T> extends Set<T> {
+  /*** @throws TypeError If the input is not iterable. */
+  constructor(iterable: Iterable<T> = []) {
     if (!Array.isArray(iterable) && !iterable[Symbol.iterator]) {
       throw new TypeError("UniqueSet requires an iterable");
     }
@@ -10,8 +12,12 @@ export class UniqueSet extends Set {
       this.add(item);
     }
   }
-
-  has(o) {
+  /**
+   * Determines whether an object is in the UniqueSet using deep equality.
+   * @param o The object to check for presence in the UniqueSet.
+   * @returns `true` if the object is found, `false` otherwise.
+   */
+  has(o: T): boolean {
     for (const i of this) {
       if (equal(o, i)) {
         return true;
@@ -19,8 +25,12 @@ export class UniqueSet extends Set {
     }
     return false;
   }
-
-  add(o) {
+  /**
+   * Adds a new object to the UniqueSet if it is not already present.
+   * @param o The object to add to the UniqueSet.
+   * @returns The `UniqueSet` instance, allowing for chaining.
+   */
+  add(o: T): this {
     if (!this.has(o)) {
       super.add(o);
     }
@@ -28,8 +38,23 @@ export class UniqueSet extends Set {
   }
 }
 
-export class BloomSet extends Set {
-  constructor(iterable = [], options = {}) {
+/** A `Set` extension that uses a Bloom filter for fast existence checks combined with deep equality for accuracy. */
+export class BloomSet<T> extends Set<T> {
+  #bitArray: Uint8Array;
+  #aSize: number;
+  #hashCount: number;
+  /**
+   * Creates a new `BloomSet` instance.
+   * @param iterable Optional: an iterable object with which to initialize the BloomSet.
+   * @param options Bloom filter configuration options.
+   * @param options.size The size of the Bloom filter's bit array. Defaults to 6553577.
+   * @param options.hashCount The number of hash functions to use. Defaults to 7.
+   * @throws TypeError If the input is not iterable.
+   */
+  constructor(
+    iterable: Iterable<T> = [],
+    options: { size?: number; hashCount?: number } = {}
+  ) {
     if (!Array.isArray(iterable) && !iterable[Symbol.iterator]) {
       throw new TypeError("BloomSet requires an iterable");
     }
@@ -39,37 +64,41 @@ export class BloomSet extends Set {
       options = {};
     }
 
-    const { size = 6553577, hashCount = 7 } = options;
+    options.hashCount ??= 7;
+    options.size ??= 6553577;
+
+    let { size, hashCount } = options;
 
     if (typeof size !== "number" || size <= 0) {
       size = 6553577; // Targeting < 1 collision per 100,000 elements, ~819 KB memory, needs 7 hashes
     }
-    this.aSize = this._findNextPrime(size);
+    this.#aSize = this.#findNextPrime(size);
 
     if (typeof hashCount !== "number" || hashCount <= 0) {
       hashCount = 7;
     }
-    this.hashCount = hashCount;
-
-    this.bitArray = new Uint8Array(Math.ceil(size / 8));
+    this.#hashCount = hashCount;
+    this.#bitArray = new Uint8Array(Math.ceil(size / 8));
 
     for (const item of iterable) {
       this.add(item);
     }
   }
 
-  _findNextPrime(num) {
+  /** @internal */
+  #findNextPrime(num: number) {
     if (num < 2) return 2;
     if (num % 2 === 0) num++; // Odd numbers only
 
-    while (!this._isPrime(num)) {
+    while (!this.#isPrime(num)) {
       num += 2; // Odd numbers only
     }
 
     return num;
   }
 
-  _isPrime(num) {
+  /** @internal */
+  #isPrime(num: number) {
     if (num < 2) return false;
     if (num === 2 || num === 3) return true;
     if (num % 2 === 0 || num % 3 === 0) return false;
@@ -82,13 +111,14 @@ export class BloomSet extends Set {
     return true;
   }
 
-  _serialize(item) {
+  /** @internal */
+  #serialize(item: T | number | object): string {
     if (typeof item === "number" && isNaN(item)) {
       return "NaN";
     }
 
     if (item && typeof item === "object") {
-      const serialize = this._serialize.bind(this);
+      const serialize = this.#serialize.bind(this);
       if (Array.isArray(item)) {
         return `[${item.map(serialize).join(",")}]`;
       } else {
@@ -102,14 +132,15 @@ export class BloomSet extends Set {
     return String(item);
   }
 
-  _hashes(item) {
-    const hashes = [];
-    const str = this._serialize(item);
-    let hash = this._fnv1a(str); // Base hash
+  /** @internal */
+  #hashes(item: T) {
+    const hashes: number[] = [];
+    const str = this.#serialize(item);
+    let hash = this.#fnv1a(str); // Base hash
 
     // Bloom into hashCount hash values
-    for (let i = 0; i < this.hashCount; i++) {
-      hash %= this.aSize; // Ensure within bounds
+    for (let i = 0; i < this.#hashCount; i++) {
+      hash %= this.#aSize; // Ensure within bounds
       // Track
       hashes.push(hash);
       // Modify
@@ -120,7 +151,8 @@ export class BloomSet extends Set {
     return hashes;
   }
 
-  _fnv1a(str) {
+  /** @internal */
+  #fnv1a(str: string) {
     if (typeof str !== "string") {
       str = String(str);
     }
@@ -132,28 +164,30 @@ export class BloomSet extends Set {
     return hash >>> 0;
   }
 
-  _setBits(hashes) {
+  /** @internal */
+  #setBits(hashes: number[]): void {
     for (const hash of hashes) {
       const index = Math.floor(hash / 8);
       const bit = hash % 8;
-      this.bitArray[index] |= 1 << bit;
+      this.#bitArray[index]! |= 1 << bit;
     }
   }
 
-  _checkBits(hashes) {
+  /** @internal */
+  #checkBits(hashes: number[]): boolean {
     for (const hash of hashes) {
       const index = Math.floor(hash / 8);
       const bit = hash % 8;
-      if (!(this.bitArray[index] & (1 << bit))) {
+      if (!(this.#bitArray[index]! & (1 << bit))) {
         return false;
       }
     }
     return true;
   }
-
-  has(o) {
-    const hashes = this._hashes(o);
-    if (!this._checkBits(hashes)) {
+  /** Determines existence of an object in the BloomSet using the Bloom filter and deep equality */
+  has(o: T): boolean {
+    const hashes = this.#hashes(o);
+    if (!this.#checkBits(hashes)) {
       return false; // Definitely not in the set
     }
     // Fall back to fast-deep-equal for false positives
@@ -164,20 +198,15 @@ export class BloomSet extends Set {
     }
     return false;
   }
-
-  add(o) {
+  /** Adds a new object to the BloomSet if it is not already present.
+   * @returns The `BloomSet` instance, allowing for chaining.
+   */
+  add(o: T): this {
     if (!this.has(o)) {
-      const hashes = this._hashes(o);
-      this._setBits(hashes);
+      const hashes = this.#hashes(o);
+      this.#setBits(hashes);
       super.add(o);
     }
     return this;
   }
 }
-
-if (typeof module !== "undefined" && module.exports) {
-  module.exports = {
-    UniqueSet,
-    BloomSet,
-  };
-}

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@sepiariver/unique-set",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Extends the native Set class to deeply compare using fast-deep-equal, with optional Bloom filter optimization. This version exports 2 classes instead of a default, breaking b/c with version 1.",
-  "main": "index.js",
-  "module": "dist/index.js",
-  "types": "index.d.ts",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
   "exports": {
-    "require": "./index.js",
-    "import": "./dist/index.js"
+    "require": "./dist/index.js",
+    "import": "./dist/index.mjs"
   },
   "scripts": {
-    "test": "jest",
-    "build": "babel src -d dist"
+    "test": "npm run build && vitest",
+    "lint": "tsc",
+    "build": "tsup index.ts --format esm --dts"
   },
   "repository": {
     "type": "git",
@@ -35,10 +36,8 @@
     "fast-deep-equal": "^3.1.3"
   },
   "devDependencies": {
-    "@babel/cli": "^7.17.6",
-    "@babel/core": "^7.17.8",
-    "@babel/preset-env": "^7.16.11",
-    "babel-jest": "^27.5.1",
-    "jest": "^27.5.1"
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
   }
 }

package/temp.cjs

@@ -0,0 +1,10 @@
+const { BloomSet, UniqueSet } = require("./dist/index.js");
+
+const bloom = new BloomSet();
+bloom.add("foo");
+console.log(bloom.has("foo")); // true
+
+const unique = new UniqueSet();
+unique.add("foo");
+unique.add("foo");
+console.log(unique.size); // 1

package/temp.mjs

@@ -0,0 +1,10 @@
+import { BloomSet, UniqueSet } from "./dist/index.js";
+
+const bloom = new BloomSet();
+bloom.add("foo");
+console.log(bloom.has("foo")); // true
+
+const unique = new UniqueSet();
+unique.add("foo");
+unique.add("foo");
+console.log(unique.size); // 1

package/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    /* Language and Environment */
+    "target": "ES2023",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+
+    /* Modules */
+    "module": "ES2022",                                /* Specify what module code is generated. */
+    "removeComments": false,                           /* Disable emitting comments. */
+    "moduleResolution": "bundler",
+    // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
+    // "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
+    /* Interop Constraints */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+
+    /* Type Checking */
+    "strict": true,                                      /* Enable all strict type-checking options. */
+    /* Completeness */
+    "skipLibCheck": true,                                /* Skip type checking all .d.ts files. */
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true
+  }
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = require("./dist");