Object Property Extractor

Access deep object properties using a string (e.g. "user.country.name")

A lightweight (no dependencies) tool to extract deeply nested values from JS Objects (or Arrays), with optional Fallback.

Similar to Lodash' get function, but with some additional functionality.

Why?

Consider the object

1const data = {
2  user: {
3    name: { first: 'Jango', last: 'Fett' },
4    children: ['Boba', 'Clone 1', 'Clone 2', ...etc],
5    weapons: [
6      { name: 'Blaster', description: 'For shooting stuff' },
7      { name: 'Seismic charge', description: '...BWAAAAAANG' },
8    ],
9  },
10  ...otherProperties,
11}

In Javascript, you call inner object properties via dot notation:

1data.user.name.last // Fett

If you want to access a property dynamically, you can do this:

1const key = "user" 
2return data[key]

However, you can't do this:

1const key = "user.name"
2return data[key]

This tool allows access to deep properties from a single "property path" string.

Installation

1yarn add object-property-extractor
2// OR
3npm install object-property-extractor

Usage

extract( dataObject, propertyString, [fallback] )

1import extract from "object-property-extractor"
2
3// Using the data object above
4extract(data, "user.name.first") // Jango
5
6// With fallback when path not found
7extract(data, "user.age", "Unknown") // Unknown
8
9// Arrays can be accessed by index, as per normal indexing syntax
10extract(data, "user.children[1]") // Boba

Array handling

In addition to accessing array by index (above), if an array consists of objects, then it's possible to extract a single property from each object in the returned array.

For example:

1extract(data, "user.weapons.name")
2// ["Blaster", "Seismic charge"]

Note that this is essentially a shorthand for:
extract(data, "user.weapons").map((weapon) => weapon.name)

Error handling

If a requested property can't be accessed (e.g. incorrect path), the function will throw an error, unless a fallback is provided. So unless you are catching and handling these errors at a higher level, it is recommended to always provided a fallback (null is an acceptable fallback).

Testing

A jest test suite is included in the repo. To run: yarn test

See /test/test.ts for the test cases.

Bug report / Feature requests

Please make an issue in the Github repo: https://github.com/CarlosNZ/object-property-extractor