keyblade

Fail fast when accessing undefined properties on objects.

Usage no npm install needed!

<script type="module">
  import keyblade from 'https://cdn.skypack.dev/keyblade';
</script>

README

keyblade

npm dependency Status devDependency Status Build Status Coveralls Code Climate npm npm node JavaScript Style Guide

Fail fast when accessing undefined properties on objects.

Installation

This is not the library you need. This is the library you deserve!

npm install keyblade --save

Requires Node v6 or above.

Usage

const { keyblade, UndefinedKeyError } = require('keyblade')

// Object to protect
const unsafe = {
  hello: 'world'
}

console.log(unsafe.hello)
// < 'world'
console.log(unsafe.goodbye)
// < undefined

// Create a protected version (does not modify `unsafe`)
const safe = keyblade(unsafe)

console.log(safe.hello)
// < 'world'
console.log(safe.goodbye)
// < UndefinedKeyError: The key 'goodbye' does not exist on the object.

Note: to ensure interoperability with utilities that use Symbols, checking them has been disabled. This means using util.inspect and JSON.stringify works without issues. I don't know why you would need to stringify a protected object but... you can!

Why do I need deserve it?

Glad you asked! Heard of those wonderful things we call environment variables? They're fun! Even more so when someone forgets to define them.

const env = process.env

const cert = someModuleThatNeedsACertFile(env.CERT_FILE_PATH)

// Later...

// < Error: something about strings or buffers I dunno man..

Of course, you could be all like..

if (!env.CERT_FILE_PATH) throw new Error('No CERT_FILE_PATH specified')

Now repeat that 43 times. Or, you could use keyblade!

const { keyblade } = require('keyblade')
const env = keyblade(process.env)

const cert = someModuleThatNeedsACertFile(env.CERT_FILE_PATH)
// < UndefinedKeyError: The key 'CERT_FILE_PATH' does not exist on the object.

One could even get fancy and customize the error message.

const env = keyblade(process.env, {
  message: (key) => `Environment variable ${key} is not set.`
})

const cert = someModuleThatNeedsACertFile(env.CERT_FILE_PATH)
// < UndefinedKeyError: Environment variable CERT_FILE_PATH is not set.

If you are not a fan of the console.error happening before throwing, you can either customize it:

const env = keyblade(process.env, {
  message: (key) => `Environment variable ${key} is not set.`,
  logBeforeThrow: (message, key) => mylogger.error(message, 'key was ' + key)
})

Or disable it entirely.

const env = keyblade(process.env, {
  message: (key) => `Environment variable ${key} is not set.`,
  logBeforeThrow: false
})

Contributing

npm run scripts

  • npm run test: Runs tests once
  • npm run test-watch: Runs tests in watch-mode
  • npm run lint: Lints the code once
  • npm run lint-watch: Lints the code in watch-mode
  • npm run cover: Runs code coverage using nyc (istanbul)
  • npm run coveralls: Used by coveralls

Author

Jeff Hansen - @Jeffijoe