array-join

library4.0.0jsnpmunverified

Join (SQL-like) two iterables by a common key. v4.0.0 is the current stable version, ESM-only, requires Node >=22. Provides INNER JOIN, LEFT JOIN, and FULL JOIN operations on iterables. The user supplies key extractors and a result constructor. v3 introduced a simplified interface and up to 10x performance improvement. v3 dropped custom match functions and made all parameters required. v4 dropped CJS support and raised minimum Node version. Key differentiator: lightweight, typed (TypeScript), and fast for object array joins without a database.

storage

npm install array-join

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ARRAY-JOIN

array-join

storagejavascriptv4.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

join

✓ import { join } from 'array-join'

✗ const join = require('array-join').join

ESM-only since v4; CommonJS require will fail.

leftJoin

✓ import { leftJoin } from 'array-join'

✗ import leftJoin from 'array-join'

Named export, not default.

fullJoin

✓ import { fullJoin } from 'array-join'

✗ import { fulljoin } from 'array-join'

Export name is camelCase: fullJoin.

Shows INNER JOIN of two arrays by matching id and personId, combining properties.

import { join } from 'array-join'; const people = [ { id: 1, name: 'Bob' }, { id: 2, name: 'Mary' }, { id: 3, name: 'Alice' }, ]; const addresses = [ { personId: 1, address: { city: 'New York', country: 'US' } }, { personId: 2, address: { city: 'Toronto', country: 'Canada' } }, { personId: 4, address: { city: 'London', country: 'UK' } }, ]; const result = join( people, addresses, (left) => left.id, (right) => right.personId, (left, right) => ({ ...left, ...right }) ); console.log(result);

Debug

Known issues

breakingESM-only package: CommonJS require() will throw.

fix

Switch to import syntax. If using Node, set type: module in package.json or use .mjs extension.

affects: >=4.0.0

breakingMinimum Node.js version is 22. Older versions cannot run v4.

fix

Upgrade Node.js to >=22.

affects: >=4.0.0

breakingAll parameters are required; omitting any will throw a runtime error.

fix

Provide all four functions: leftKey, rightKey, resultItem.

affects: >=3.0.0

gotchajoin() performs INNER JOIN; leftJoin() for LEFT JOIN; fullJoin() for FULL JOIN. Do not expect all functions to behave identically.

fix

Choose the correct function based on desired join semantics.

affects: >=3.0.0

gotchaKey equality uses SameValueZero (like Map). Object keys by reference won't match custom objects.

fix

Ensure keys are primitives (string, number, symbol, boolean, undefined, null).

affects: >=3.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module

Using require() on an ESM-only package (v4+).

fix

Use import syntax: import { join } from 'array-join'

TypeError: getLeftKey is not a function

Missing a required parameter (getLeftKey, getRightKey, or getResultItem).

fix

Provide all three function arguments.

Error: The other collection is not iterable

Passed a non-iterable (e.g. plain object) as leftCollection or rightCollection.

fix

Pass only arrays or other iterables (e.g. Set, Map values).

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

61 hits · last 30 days

node

Bingbot

OpenAI (training)

Resources

githubhttps://github.com/iredchuk/array-join ↗

packagearray-join ↗

homepagehttps://github.com/iredchuk/array-join#readme ↗