@lopatnov/join

A TypeScript library providing SQL-like join operations for JavaScript objects. Merge two objects using one of 9 composable join types, with support for deep merging of nested objects.

Installation
Import
Join Types
API
Usage Examples
Demo
Contributing
Built With
License

Installation

npm install @lopatnov/join

Browser:

<script src="https://lopatnov.github.io/join/dist/join.umd.min.js"></script>

Import

TypeScript / ES Modules

import { join, JoinTypes } from "@lopatnov/join";

CommonJS

const { join, JoinTypes } = require("@lopatnov/join");

Join Types

The library uses a 4-bit flag system to describe which parts of two objects appear in the result:

Bit	Name	Meaning
3	`left`	Include properties unique to the left object
2	`innerLeft`	Include shared properties, keeping left values
1	`innerRight`	Include shared properties, using right values
0	`right`	Include properties unique to the right object

Named Join Types

Join Type	Bits	Description
`none`	`0000`	Empty result — no properties from either object
`left`	`1000`	Only properties unique to the left object
`right`	`0001`	Only properties unique to the right object
`innerLeft`	`0100`	Shared properties only, keeping left values
`innerRight`	`0010`	Shared properties only, replacing with right values
`innerJoin`	`0110`	Shared properties, deep-merged (left + right values combined)
`leftJoin`	`1110`	Left-unique + shared properties (deep-merged)
`rightJoin`	`0111`	Shared properties (deep-merged) + right-unique
`fullJoin`	`1111`	All properties from both objects, shared ones deep-merged
`expand`	`1011`	Left-unique + right values for shared + right-unique (default)

Custom join types can be composed with bitwise OR:

const customJoin = join(JoinTypes.left | JoinTypes.innerLeft | JoinTypes.right);

API

function join(
  joinType?: JoinTypes
): <TContext>(
  context: TContext
) => <TJoinObject>(joinObject: TJoinObject) => TContext & TJoinObject;

join uses a curried three-step pattern:

Step	Call	Description
1	`join(JoinTypes.xxx)`	Set the join type; returns a context-setter function
2	`contextSetter(leftObject)`	Set the left object; returns a joiner function
3	`joiner(rightObject)`	Set the right object; returns the merged result

JoinTypes.expand is the default join type when join() is called with no arguments.

Usage Examples

Right Join

Returns only the properties unique to the right object:

const rightJoin = join(JoinTypes.right);

const contextJoinBy = rightJoin({
  sample1: "One",
  sample2: "Two",
  sample3: "Three"
});

const result = contextJoinBy({
  sample2: "Dos",
  sample3: "Tres",
  sample4: "Quatro"
});

console.log(result); // { sample4: "Quatro" }

Left Join

Returns only the properties unique to the left object:

const leftJoin = join(JoinTypes.left);

const contextJoinBy = leftJoin({
  sample1: "One",
  sample2: "Two",
  sample3: "Three"
});

const result = contextJoinBy({
  sample2: "Dos",
  sample3: "Tres",
  sample4: "Quatro"
});

console.log(result); // { sample1: "One" }

Custom Bitwise Composition

Returns left-unique + shared (from left) + right-unique properties:

const customJoin = join(JoinTypes.left | JoinTypes.innerLeft | JoinTypes.right);

const contextJoinBy = customJoin({
  sample1: "One",
  sample2: "Two",
  sample3: "Three"
});

const result = contextJoinBy({
  sample2: "Dos",
  sample3: "Tres",
  sample4: "Quatro"
});

console.log(result); // { sample1: "One", sample2: "Two", sample3: "Three", sample4: "Quatro" }

Inner Join (Deep Merge)

Returns shared properties with their values deep-merged:

const result = join(JoinTypes.innerJoin)({
  sample1: "One",
  sample2: "Two",
  sample3: { smile: "cheese" }
})({
  sample2: "Dos",
  sample3: { sorrir: "queijo" },
  sample4: "Quatro"
});

console.log(result);
// { sample2: "Dos", sample3: { smile: "cheese", sorrir: "queijo" } }

Demo

Live demo: https://runkit.com/lopatnov/join
Try in browser: https://npm.runkit.com/@lopatnov/join

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a pull request.

Bug reports → open an issue
Questions → Discussions
Found it useful? A star on GitHub helps others discover the project

Built With

TypeScript — strict typing throughout
Rollup — bundled to ESM, CJS, and UMD formats
Vitest — unit testing with coverage
ESLint + Prettier — linting and formatting