README.md

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

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.