README.md

# merge-objects-by-date

A small utility to merge multiple sorted asset arrays by **exact matching date**.

It is built for cases like crypto or stock candles where each asset has the same field name for time, for example `date`.

The merge is simple:

- it only matches rows with the **same exact date**
- it does **not** do multi-timeframe merging
- it uses `keepKey` as the main asset
- fields from `keepKey` stay unchanged
- fields from the other assets are prefixed with their key name

---

## Install

```bash
npm install merge-objects-by-date

Import

import mergeObjectsByDate from 'merge-objects-by-date';

Basic example

const assets = mergeObjectsByDate({
  inputObj: {
    btc: btc_1d,
    eth: eth_1d,
    sol: sol_1d,
  },
  target: 'date',
  keepKey: 'btc',
});

Input format

Each key inside inputObj must be an array of objects.

Example:

const btc_1d = [
  { date: '2024-01-01', open: 42000, close: 43000 },
  { date: '2024-01-02', open: 43000, close: 43500 },
  { date: '2024-01-03', open: 43500, close: 44000 },
];

const eth_1d = [
  { date: '2024-01-01', open: 2200, close: 2250 },
  { date: '2024-01-03', open: 2250, close: 2300 },
];

const sol_1d = [
  { date: '2024-01-01', open: 100, close: 101 },
  { date: '2024-01-03', open: 102, close: 103 },
];

Then:

const result = mergeObjectsByDate({
  inputObj: {
    btc: btc_1d,
    eth: eth_1d,
    sol: sol_1d,
  },
  target: 'date',
  keepKey: 'btc',
});

Output:

[
  {
    date: '2024-01-01',
    open: 42000,
    close: 43000,
    eth_date: '2024-01-01',
    eth_open: 2200,
    eth_close: 2250,
    sol_date: '2024-01-01',
    sol_open: 100,
    sol_close: 101,
  },
  {
    date: '2024-01-03',
    open: 43500,
    close: 44000,
    eth_date: '2024-01-03',
    eth_open: 2250,
    eth_close: 2300,
    sol_date: '2024-01-03',
    sol_open: 102,
    sol_close: 103,
  },
]

Only rows with the same exact date in all assets are merged.

API

mergeObjectsByDate({ inputObj, target, keepKey })

Params

inputObj

An object where:

• each key is the asset name
• each value is an array of rows

Example:

{
  btc: btc_1d,
  eth: eth_1d,
  sol: sol_1d,
}

target

The property name that contains the date.

Example:

target: 'date'

keepKey

The main asset to keep as the base row.

Its fields are kept without prefix.

Example:

keepKey: 'btc'

How output keys work

If keepKey is btc:

• btc fields stay as they are
• eth fields become eth_date, eth_open, eth_close
• sol fields become sol_date, sol_open, sol_close

Example output row:

{
  date: '2024-01-01',
  open: 42000,
  close: 43000,
  eth_date: '2024-01-01',
  eth_open: 2200,
  eth_close: 2250,
}

Rules

Your arrays should follow these rules:

• each asset array must be sorted in ascending date order
• dates inside the same array must not be duplicated
• every row must contain the target field
• all assets must use comparable date values

Supported date values

The library supports common date formats such as:

• JavaScript Date
• milliseconds timestamp
• seconds timestamp
• date strings like YYYY-MM-DD
• full date-time strings

Example:

{ date: '2024-01-01' }
{ date: '2024-01-01T00:00:00Z' }
{ date: 1704067200000 }

Notes

This library does exact-date merging only.

It does not:

• match nearest dates
• fill missing dates
• merge across different timeframes
• do candle interpolation

If a date does not exist in every asset, that row is skipped.

Test

npm test