@tpmjs/tools-rows-join

Joins two arrays of objects by key fields, supporting inner, left, right, and full outer joins.

Installation

npm install @tpmjs/tools-rows-join

Usage

import { rowsJoinTool } from '@tpmjs/tools-rows-join';

const result = await rowsJoinTool.execute({
  left: [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' },
    { id: 3, name: 'Charlie' },
  ],
  right: [
    { userId: 1, score: 95 },
    { userId: 2, score: 87 },
    { userId: 4, score: 92 },
  ],
  leftKey: 'id',
  rightKey: 'userId',
  type: 'left',
});

console.log(result);
// {
//   rows: [
//     { joinKey: 1, left_id: 1, left_name: 'Alice', right_userId: 1, right_score: 95 },
//     { joinKey: 2, left_id: 2, left_name: 'Bob', right_userId: 2, right_score: 87 },
//     { joinKey: 3, left_id: 3, left_name: 'Charlie' }
//   ],
//   matchedCount: 2,
//   unmatchedLeft: 1,
//   unmatchedRight: 0
// }

Parameters

• left (required): Left array of objects to join
• right (required): Right array of objects to join
• leftKey (required): Field name in left array to join on (supports dot notation)
• rightKey (required): Field name in right array to join on (supports dot notation)
• type (optional): Join type, defaults to 'inner'
  • 'inner': Only return rows that match in both arrays
  • 'left': Return all rows from left array, with matches from right
  • 'right': Return all rows from right array, with matches from left
  • 'full': Return all rows from both arrays

Output Format

The joined rows have fields prefixed to avoid collisions:

• Left array fields are prefixed with left_
• Right array fields are prefixed with right_
• joinKey field contains the matched key value

Features

• Supports nested field access with dot notation
• Handles one-to-many relationships (cartesian product for multiple matches)
• Type-safe with TypeScript
• Returns match statistics for analysis

Examples

Inner Join (Only Matches)

const result = await rowsJoinTool.execute({
  left: [{ id: 1 }, { id: 2 }],
  right: [{ id: 1 }],
  leftKey: 'id',
  rightKey: 'id',
  type: 'inner',
});
// Returns only the row with id: 1

Full Outer Join (All Rows)

const result = await rowsJoinTool.execute({
  left: [{ id: 1 }, { id: 2 }],
  right: [{ id: 2 }, { id: 3 }],
  leftKey: 'id',
  rightKey: 'id',
  type: 'full',
});
// Returns rows for id: 1, 2, and 3

License

MIT