mapex

Ultimate Javascript object mapping tool

Installation

yarn add mapex

npm install mapex

Quick Start

Consider a typical blog post. The API response for a single post might look something like this:

{
  "id": "123",
  "author": {
    "id": "1",
    "name": "Paul"
  },
  "title": "My awesome blog post",
  "comments": [
    {
      "id": "324",
      "commenter": {
        "id": "2",
        "name": "Nicole"
      }
    }
  ]
}

We have two nested entity types within our article: users and comments. Using various schema, we can normalize all three entity types down:

import mapex from "mapex";
mapex(
  {
    $result: "article",
    // define user schema
    user: {},
    // define comment schema
    comment: {
      // define commenter follows user schema
      commenter: "user",
    },
    // define article schema
    article: {
      author: "user",
      // define comments array follow comment schema
      comments: "comment",
    },
  },
  data
);

Now, normalizedData will be:

const output = {
  $result: "123",
  article: {
    123: {
      id: "123",
      author: "1",
      title: "My awesome blog post",
      comments: ["324"],
    },
  },
  user: {
    1: { id: "1", name: "Paul" },
    2: { id: "2", name: "Nicole" },
  },
  comment: {
    324: { id: "324", commenter: "2" },
  },
};

API

mapex(schema, data)

mapex(schema)

Root schema attributes

const schema = {
  // A name of schema that use to parse input data
  $result: "subSchema1",
  // A definition of sub schema
  subSchema1: {},
  subSchema2: {},
};

Sub schema attributes

$name

A prop name of entity collection in output object

mapex(
  {
    $result: "article",
    article: {
      $name: "articles",
    },
  },
  {
    id: 1,
  }
);

Output

{
  "$result": 1,
  "articles": { "id": 1 }
}

$id

Indicate which entity property is id, $id can be string or Function

mapex(
  {
    $result: "article",
    article: {
      $id: "_id",
    },
  },
  {
    _id: 1,
  }
);

Output

{
  "$result": 1,
  "article": { "_id": 1 }
}

$value

Indicate entity property values follow the given schema.

mapex(
  {
    $result: "item",
  },
  { firstThing: { id: 1 }, secondThing: { id: 2 } }
);

{
  "$result": { "firstThing": 1, "secondThing": 2 },
  "item": { "1": { "id": 1 }, "2": { "id": 2 } }
}

$type

Indicate the property which is schema name.

mapex(
  {
    $result: "user",
    user: {
      $type: "roleId",
      1: "mod",
      2: "admin",
    },
    mod: {},
    admin: {},
  },
  [
    { id: 1, roleId: 1 },
    { id: 2, roleId: 2 },
    { id: 3, roleId: 1 },
  ]
);

const output = {
  $result: [1, 2, 3],
  mod: {
    1: { id: 1, roleId: 1 },
    3: { id: 3, roleId: 1 },
  },
  admin: {
    2: { id: 2, roleId: 2 },
  },
  // no user collection generated
};

$default

Use with $type attribute, if entity does not present $type property, $default schema will be used

mapex(
  {
    $result: "user",
    user: {
      $type: "roleId",
      $default: "guest",
      1: "mod",
      2: "admin",
    },
    mod: {},
    admin: {},
    guest: {},
  },
  [
    { id: 1, roleId: 1 },
    { id: 2, roleId: 2 },
    { id: 3, roleId: 1 },
    // no roleId presents, this entity will follow 'guest' schema
    { id: 4 },
  ]
);

$desc

Use with $type attribute. if $desc = true, a union entity collection will be added.

mapex(
  {
    $result: "user",
    user: {
      $type: "roleId",
      $desc: true,
      1: "mod",
      2: "admin",
    },
    mod: {},
    admin: {},
  },
  [
    { id: 1, roleId: 1 },
    { id: 2, roleId: 2 },
    { id: 3, roleId: 1 },
  ]
);

const output = {
  $result: [1, 2, 3],
  mod: {
    1: { id: 1, roleId: 1 },
    3: { id: 3, roleId: 1 },
  },
  admin: {
    2: { id: 2, roleId: 2 },
  },
  user: {
    1: "mod",
    3: "mod",
    2: "admin",
  },
};

If you want to customize user entity collection, just pass $desc as a function.

mapex(
  {
    $result: "user",
    user: {
      $type: "roleId",
      $desc(id, schema, entity) {
        return `${schema}_${id}`;
      },
      1: "mod",
      2: "admin",
    },
    mod: {},
    admin: {},
  },
  [
    { id: 1, roleId: 1 },
    { id: 2, roleId: 2 },
    { id: 3, roleId: 1 },
  ]
);

const output = {
  $result: [1, 2, 3],
  mod: {
    1: { id: 1, roleId: 1 },
    3: { id: 3, roleId: 1 },
  },
  admin: {
    2: { id: 2, roleId: 2 },
  },
  user: {
    mod_1: "mod",
    mod_3: "mod",
    admin_2: "admin",
  },
};

$process(entity)

Advanced usage

Process tree nodes

mapex(
  {
    $result: "node",
    node: {
      children: "node",
    },
  },
  {
    id: 1,
    name: "root",
    children: [
      {
        id: 2,
        name: "node 1",
        children: [
          { id: 4, name: "node 1.1" },
          { id: 5, name: "node 1.2" },
        ],
      },
      { id: 3, name: "node 2" },
    ],
  }
);

Output

_ = {
  $result: 1,
  node: {
    1: { id: 1, name: "root", children: [2, 3] },
    2: { id: 2, name: "node 1", children: [4, 5] },
    3: { id: 3, name: "node 2" },
    4: { id: 4, name: "node 1.1" },
    5: { id: 5, name: "node 1.2" },
  },
};

Dependencies

None.