DataWeaver

DataWeaver is a JavaScript library for weaving together multiple data objects into a single data structure. It provides a declarative way to define objects, link attributes between objects, and generate a final data structure by merging the objects together.

It allows you to keep your data modular and composed, while still generating flattened data structures for consumption. This enables loose coupling between data sources and flexible generation of customized data representations from a single data model.

Installation:

To install this module, you can use npm by running the following command in your terminal:

npm install d-dataweaver

or with yarn:

yarn add d-dataweaver

Usage:

To use this module, you will need to import it into your TypeScript file:

import { WeaveObject, DataWeaver } from 'd-dataweaver';

or using the CommonJS

const { WeaveObject, DataWeaver } = require('d-dataweaver');

Here is an example usage how you can utilize the classes.

const contact = WeaveObject.fromObject<{
  full_contact: string;
  name: string;
}>(
  {
    full_contact: () => '+1234567890',
    name: () => 'John Doe',
  },
  'contact',
);

const user1 = WeaveObject.fromObject<{
  phone_number: string;
  user_id: string;
}>(
  {
    phone_number: () => '', // will be overwritten upon linking
    user_id: () => `${Math.random().toString(36).split('.')[1]}`,
  },
  'user1',
);

const user2 = user1.__clone('user2');
const user3 = user1.__clone('user3');

const connection = WeaveObject.fromObject<{
  user_1: string;
  user_2: string;
}>(
  {
    user_1: () => '', // will be overwritten upon linking
    user_2: () => '', // will be overwritten upon linking
  },
  'user_mapping',
);

const data = new DataWeaver()
  .add(contact, user1, user2, user3, connection)
  .link(contact.__attribute('full_contact'), user1.__attribute('phone_number'))
  .link(user1.__attribute('user_id'), connection.__attribute('user_1'))
  .link(user2.__attribute('user_id'), connection.__attribute('user_2'))
  .link(user3.__attribute('user_id'), connection.__attribute('user_2'))
  .weave();

console.dir(data);

// output:
{
  contact: { full_contact: '+1234567890', name: 'John Doe' },
  user1: { phone_number: '+1234567890', user_id: 'hsv7o644gid' },
  user2: { phone_number: '', user_id: 'byjjyyt4kwm' },
  user3: { phone_number: '', user_id: 'zr3yz0hq4tc' },
  user_mapping: { user_1: 'hsv7o644gid', user_2: [ 'byjjyyt4kwm', 'zr3yz0hq4tc' ] }
}

API

The DataWeaver class contains methods for adding objects, linking attributes, and generating the final data structure.

WeaveObject<T>

A WeaveObject represents a data object that can be woven with other WeaveObjects.

Constructor(obj: WObjectParam<T>, name: string)

Creates a new WeaveObject instance from a WObjectParam and a name.

__clone(name: string): WeaveObject<T>

Creates a new WeaveObject instance with the same properties and values as the original WeaveObject.

__generate(): T

Generates an object with the properties and values of the WeaveObject, calling each property function to obtain its value.

__attribute(path: StringKeys<T>): WeaveAttribute<T>

Returns a WeaveAttribute instance for the specified path in the WeaveObject.

Properties

__name: string - The name of the WeaveObject.

DataWeaver

The DataWeaver class is the core of the Weave library. It is responsible for managing the objects and links in the data graph and generating the final data output.

add(...obj: WeaveObject<any>[]): DataWeaver

Adds one or more WeaveObject instances to the data graph. Returns a new instance of DataWeaver containing the added objects.

link(from: WeaveAttribute<any>, to: WeaveAttribute<any>): DataWeaver

Links two WeaveAttribute instances in the data graph. Returns a new instance of DataWeaver containing the added link.

weave(): any

Generates the final data output by generating the objects and resolving the links in the data graph.

Returns the final data output.