uniqs: Unique and Union Utility

Common errors

• Expected [ { a: 1 }, { a: 1 } ] to be unique, but got two distinct objects.

  cause `uniqs` uses strict (===) equality, so two different object instances, even with identical content, are considered unique.
  fix If you need deep equality, serialize objects (e.g., `JSON.stringify`) or use a custom comparison function before passing them to `uniqs`, or switch to a library that supports deep equality.

• Application hangs or runs very slowly when processing a large array with `uniqs`.

  cause The internal implementation of `uniqs` has O(n^2) complexity, making it inefficient for very large input arrays due to repeated `indexOf` calls.
  fix For performance-critical applications with large datasets, use JavaScript's built-in `Set` for O(n) performance with primitive values, or a more optimized library function like Lodash's `uniq` for objects.

Warnings

• gotcha uniqs uses a simple `indexOf`-based deduplication, resulting in O(n^2) time complexity for the combined list. This can lead to significant performance degradation on large arrays (thousands of items or more).
  Fix: For performance-critical applications or very large datasets, consider alternatives like JavaScript's native `Set` or `Lodash.uniq` which offer better time complexity (O(n)).
• gotcha Uniqueness is determined solely by strict (`===`) object equality. This means two objects with identical properties but different references (e.g., `{a: 1}` and another `{a: 1}`) will be considered distinct items.
  Fix: To deduplicate objects based on deep equality, you must implement custom serialization (e.g., `JSON.stringify`) or a custom comparison logic before passing them to `uniqs`, or use a library that supports deep comparisons.
• breaking The transition to version 2.0.0 implies potential breaking changes as per semantic versioning. While specific details are not provided in the excerpt, developers upgrading from 1.x should expect behavioral shifts.
  Fix: Review the package's changelog or release notes for version 2.0.0 to understand specific breaking changes and update your codebase accordingly.

Install

• npm install uniqs npm
• yarn add uniqs yarn
• pnpm add uniqs pnpm

Imports

• uniqs
  wrong:

  import { uniqs } from 'uniqs';

  correct:

  const uniqs = require('uniqs');

  The package primarily uses CommonJS `require` for its default function export. While ESM `import uniqs from 'uniqs'` may work in some environments, it's not explicitly stated or guaranteed by the README.
• uniqs
  wrong:

  const { uniqs } = require('uniqs');

  correct:

  import uniqs from 'uniqs';

  For ESM environments, assuming a default export, this is the standard import. Attempting to destructure it as a named export from CommonJS will fail.

Quickstart

Demonstrates deduplication of a single list, union of multiple lists, and handling of mixed individual items and lists.

const uniqs = require('uniqs');

// Example usage to deduplicate a list
const foo = { id: 23 };
const list = [3, 2, 2, 1, foo, foo];
const uniqueList = uniqs(list);
console.log('Unique list:', uniqueList);
// Expected: [3, 2, 1, { id: 23 }]

// Example usage to create a union of multiple lists
const listA = [2, 1, 1];
const listB = [2, 3, 3, 4];
const listC = [4, 3, 2];
const unionList = uniqs(listA, listB, listC);
console.log('Union list:', unionList);
// Expected: [2, 1, 3, 4]

// Example with individual items and a list
const mixedInput = uniqs(3, 2, 2, [1, 1, 2]);
console.log('Mixed input:', mixedInput);
// Expected: [3, 2, 1]