Skip to content
This repository has been archived by the owner on Aug 13, 2020. It is now read-only.

Latest commit

 

History

History
118 lines (96 loc) · 3.81 KB

README.md

File metadata and controls

118 lines (96 loc) · 3.81 KB

Strongly-typed function to get a nested & potentially null/undefined property value.


npm version Build Status Coverage Status Greenkeeper badge

Install

npm install typed-get-prop --save

Usage

import { getProp } from 'typed-get-prop';

const movie: Movie = {
  title: 'The Matrix',
  year: 1999
  cast: [
    {
      name: 'Keanu Reeves',
      characters: [{
        name: 'Neo'
      }]
    },
    {
      name: 'Carrie-Anne Moss',
      characters: [{
        name: 'Trinity'
      }]
    }
  ]
};

const year = getProp(movie, 'year'); // number | undefined
const trinity = getProp(movie, 'cast', 1, 'characters', 0, 'name'); // string | undefined

Why do I need this?

  1. Because getting a nested property value can be error-prone when parent properties can be null or undefined.

    const movie: Movie = {
      title: 'Fight Club',
      year: 1999
    };
    
    // Next line will error because `cast` is optional and undefined
    const leadActor = movie.cast[0];
    
    // Using getProp will simply return undefined rather than erroring
    const leadActor = getProp(movie, 'cast', 0);
  2. Unlike most (if not all?) other property getter libraries on NPM, typed-get-prop will complain at design/compile-time if you try to access a property of a typed object that doesn't exist in the model.

    const movie: Movie = {
      title: 'The Matrix',
      year: 1999
      cast: [
        {
          name: 'Keanu Reeves',
          characters: [{
            name: 'Neo'
          }]
        }
      ]
    };
    
    // Next line will error at design/compile-time because `actors` isn't a property on the Movie type. It should be `cast`.
    const leadActor = getProp(movie, 'actors', 0);
  3. Again, unlike other property getter libraries, typed-get-prop will correctly infer types of properties.

    const movie: Movie = {
      title: 'The Matrix',
      year: 1999
      cast: [
        {
          name: 'Keanu Reeves',
          characters: [{
            name: 'Neo'
          }]
        }
      ]
    };
    
    const year = getProp(movie, 'year'); // year is number | undefined at design-time

Comparison with other npm libraries

Library Typesafe Supports older browsers Doesn't mutates Object.prototype Doesn't swallow exceptions indiscriminately
get-typed-prop
nevernull
telvis
ts-optchain ❌ Only via a custom compiler & transform
@smartlyio/safe-navigation
safe-ts
lonely-operation

Contributing

Got an issue or a feature request? Log it.

Pull-requests are also welcome.