datashaper-js - Pure js minimalist data shaper

Data shaper is extremely useful when working with APIs that return complex JSON objects. It allows to re-shape the returned data into the form that is consumable by your UI components.

Usage

Import:

const { from } = require('datashaper-js');

Import with extra functions:

const { from, id, konst, pair } = require('datashaper-js');

Example with array:

from([0, 1, 1, 2, 3])
    .filter((x) => x >= 1)      // [1, 1, 2, 3]
    .map((x) => x + 1)          // [2, 2, 3, 4]
    .map((x) => x * 2)          // [3, 4, 6, 8]
    .distinct()                 // [4, 6, 8]
    .sorted((a, b) => b - a)    // [8, 6, 4]
    .skip(1)                    // [6, 4]
    .take(1)                    // [6]
    .return();                  // [6]

Example with an object:

from({
    alice: { height: 171 },
    bob: { height: 185 },
    joe: { height: 168 },
  })
    .map((x) => x.height)       // { alice: 171, bob: 185, joe: 168 }
    .filter((x) => x > 170)     // { alice: 171, bob: 185 }
    .listValues()               // [171, 185]
    .sorted((a, b) => b - a)    // [185, 171]
    .return();                  // [185, 171]

Notes

Does not modify the initial object (sorted returns new array instead of sorting in-place).

Lazily evaluated, does not apply any transformations until return is called.

Debugging

When debugging, to log all the intermediate operations and results, pass true to return:

from([0, 1, 1, 2, 3])
    .map((x) => x + 1)
    .return(true);

Alternatively, you can insert log operation anywhere in the middle of the pipe:

from([1, 2, 3])
    .filter((x) => x > 1)
    .map((x) => x * 2)
    .log()                  // logs [4,6]
    .distinct()
    .return();

API

Arrays support: map, filter, flatMap, distinct, sorted, skip, take, zip, concat, toSet, toMap, toLookup

Objects support: map, filter, toList, listKeys, listValues

Extra helpful functions: id, konst, pair

Arrays

map

from([1, 2, 3])
    .map((x) => x * 2)
    .return();

// [2, 4, 6]

filter

from([1, 2, 3])
    .filter((x) => x % 2 === 0)
    .return();

// [2, 4]

flatMap

from([1, 2, 3])
    .flatMap((x) => [x, x])
    .return();

// [1, 1, 2, 2, 3, 3]

distinct

from([1, 2, 1, 2, 3])
    .distinct()
    .return();

// [1, 2, 3]

sorted

from([1, 5, 4, 2, 3])
    .sorted()
    .return();

// [1, 2, 3, 4, 5]

skip

from([1, 2, 3, 4, 5])
    .skip(2)
    .return();
    
// [3, 4, 5]

take

from([1, 2, 3, 4, 5])
    .take(2)
    .return();
    
// [1, 2]

zip

from([1, 2, 3])
    .zip(['a', 'b'], pair)
    .return();

// [{ fst: 1, snd: 'a' }, { fst: 2, snd: 'b' }, { fst: 3 }]

concat

from([1, 2, 3])
    .concat([4, 5])
    .return();

// [1, 2, 3, 4, 5]

toSet

from(['a', 'b', 'b'])
    .toSet()
    .return();

// { a: 'a', b: 'b' }

toMap

from([
        { name: 'alice', height: 171 },
        { name: 'bob', height: 185 },
        { name: 'joe', height: 168 }
    ])
    .toMap((x) => x.name, (x) => x.height)
    .return();

// { alice: 171, bob: 185, joe: 168 }

toLookup

from([
        { year: 2021, val: 5 },
        { year: 2022, val: 10 },
        { year: 2021, val: 3 }
    ])
    .toLookup((x) => x.year, (x) => x.val)
    .return();

// { 2021: [5, 3], 2022: [10] }

Objects

map

from({
        2021: 5,
        2022: 10,
        2023: 8
    })
    .map((x) => x * 2)
    .return();

// { 2021: 10, 2022: 20, 2023: 16 }

filter

from({
        2021: 5,
        2022: 10,
        2023: 8
    })
    .filter((x) => x > 7)
    .return();

// { 2022: 10, 2023: 8 }

toList

from({ a: 1, b: 2 })
    .toList()
    .return();

// [{ k: 'a', v: 1 }, { k: 'b', v: 2 }]

listKeys

from({
        2021: 5,
        2022: 10,
        2023: 8
    })
    .listKeys()
    .return();

// ['2021', '2022', '2023']

listValues

from({
        2021: 5,
        2022: 10,
        2023: 8
    })
    .listValues()
    .return();

// [5, 10, 8]

Helpers

id

const id = (x) => x;

konst

const konst = (x) => (_) => x;

pair

const pair = (fst, snd) => ({ fst, snd })