@objectwow/join NPM

@objectwow/join

Perform a deep join of arrays of objects using UIDs.

⭐️ Your star shines on us. Star us on GitHub!

Use case

When you aggregate data, such as orders and products, you might have something like the following example:

const orders = [
  {
    id: 1,
    code: "1",
    fulfillments: [
      {
        id: 12,
        code: "12",
        products: [{ id: 111, quantity: 8 }],
      },
      {
        id: 13,
        code: "13",
        products: [{ id: 112, quantity: 10 }],
      },
    ],
  },
];

const products = [
  { id: 111, name: "Product 1", price: 10 },
  { id: 112, name: "Product 2", price: 20 },
];

Add name, price to fulfillments.products

orders = [
  {
    id: 1,
    code: "1",
    fulfillments: [
      {
        id: 12,
        code: "12",
        products: [{ id: 111, name: "Product 1", price: 10, quantity: 8 }],
      },
      // another data
    ],
  },
];

Add product to fulfillments.products

orders = [
  {
    id: 1,
    code: "1",
    fulfillments: [
      {
        id: 12,
        code: "12",
        products: [
          {
            id: 111,
            quantity: 8,
            product: {
              id: 111,
              name: "Product 1",
              price: 10,
            },
          },
        ],
      },
      // another data
    ],
  },
];

Add productNames to root

orders = [
  {
    id: 1,
    code: "1",
    productNames: ["Product 1", "Product 2"],
    // another data
  },
];

Add productNameWithPrices to root

orders = [
  {
    id: 1,
    code: "1",
    productNameWithPrices: ["Product 1 10", "Product 2 20"],
    // another data
  },
];

We need a library to simplify this process.

Installation

npm i @objectwow/join

Usage

import { joinData } from "@objectwow/join";

const result = await joinData({
  local: orders,
  from: products,
  localField: "fulfillments.products.id",
  fromField: "id",
  as: "fulfillments.products",
});

LocalData (orders) will be overwritten. Order products will have the name and price fields.

orders = [
  {
    id: 1,
    code: "1",
    fulfillments: [
      {
        id: 12,
        code: "12",
        products: [{ id: 111, name: "Product 1", price: 10, quantity: 8 }],
      },
      {
        id: 13,
        code: "13",
        products: [{ id: 112, name: "Product 2", price: 20, quantity: 10 }],
      },
    ],
  },
];

result = {
  allSuccess: true,
  joinFailedValues: [],
};

Note: see more samples in the tests and test-by-cases

Parameters

/**
 * Parameters for the `joinData` function to perform joins between local data and source data.
 */
export interface JoinDataParam {
  /**
   * Local object or array of local objects to be joined.
   */
  local: LocalParam;

  /**
   * Objects or an asynchronous callback function that returns the data from the source.
   */
  from: FromParam;

  /**
   * Field name in the local object(s) used for the join.
   */
  localField: string;

  /**
   * Field name in the `from` object(s) used for the join.
   */
  fromField: string;

  /**
   * Optional new field name to store the result of the join in the local object(s).
   */
  as?: string;

  /**
   * Optional mapping from the `fromField` values to new field names in the local object(s).
   */
  asMap?: AsMap;
}

export type LocalParam = object | object[];

export type FromParam =
  | ((localFieldValues: Primitive[], metadata: any) => object[])
  | object[];

export type AsMap =
  | ((currentFrom: any, currentLocal: any, metadata: any) => any)
  | { [key: string]: string }
  | string;