deep-read v1.0.1

deep-read

deep-read is a helper function that makes it easier to read properties from deeply nested data structures. It operates in a safe way, meaning that it doesn't throw errors at all, even when reading property from null or undefined entry. Additionally, it allows to find certain array element by specifying an optional predicate function or matching object.
See Usage section for more details.

Installation

$ npm install deep-read

Usage

Consider the following example. We have a bookstore that sells many books and each book has a single author.

const deepRead = require('deep-read');

const bookstore = {
  books: [
    {
      id: 1,
      title: 'Romeo and Juliet',
      author: {
        id: 1,
        name: 'William Shakespeare'
      }
    },
    {
      id: 2,
      title: 'The Double',
      author: {
        id: 2,
        name: 'Fyodor Dostoevsky'
      }
    },
    {
      id: 3,
      title: 'Fahrenheit 451',
      author: {
        id: 3,
        name: 'Ray Bradbury'
      }
    }
  ]
};

// Allows to read nested property.
deepRead(bookstore).books[1].author.name.retrieve(); // -> 'Fyodor Dostoevsky'

// Does not throw when reading from non-existent properties.
deepRead(bookstore).books[100].author.name.retrieve(); // -> undefined

// Allows to find array element by matching object.
deepRead(bookstore).books({ id: 3 }).name.retrieve(); // -> 'Fahrenheit 451'

// Allows to find array element by predicate function.
deepRead(bookstore)
  .books((book) => book.author.name === 'William Shakespeare')
  .name
  .retrieve(); // -> 'Romeo and Juliet'

Retrieving properties with reserved names

Currently these property names are reserved and return functions to perform certain action:

• get
• retrieve

These functions don't have get and retrieve methods at the moment, therefore it's not possible to retrieve a property with reserved name using this short syntax:

const deepRead = require('deep-read');

const nestedObject = {
  test: {
    get: 1,
    retrieve: 2
  }
};

deepRead(nestedObject).test.get.retrieve(); // -> Will throw TypeError
deepRead(nestedObject).test.retrieve.retrieve(); // -> Will throw TypeError

However, you can retrieve them by using get method like that:

deepRead(nestedObject).test.get('get').retrieve(); // -> 1
deepRead(nestedObject).test.get('retrieve').retrieve(); // -> 2