zealit v2.4.1

Prevent getting nonexistent property by throwing a ReferenceError, using ES6 proxies. In other words, throw an error if reading an object property that doesn't exist.

Avoid typo or incomplete renaming/refactor. Usefull to combine with Object.freeze to declare constants.

Usage

const zealit = require('zealit')

const ref = { foo: true, bar: undefined }
ref.foo // true
ref.bar // undefined
ref.baz // undefined

// default behavior
const zealed = zealit(ref)
zealed.foo // true
zealed.bar // undefined, no Error thrown
zealed.baz // throws a ReferenceError

// "freeze" option
const myConstants = zealit({
    PI: 3.14159265,
    nbMsInOneDay: 1000 * 60 * 60 * 24,
}, { freeze: true })
myConstants.PI // 3.14159265
myConstants.Pi // throws a ReferenceError
myConstants.nbMsInOneDay = 39 // throws a TypeError

// "ignore" option
const foo = zealit({}, { ignore: 'bar' })
foo.bar // undefined, no Error thrown
foo.baz // throws a ReferenceError

// "clone" option
const bar = { baz: { yo: 1 } }
const baz = zealit(bar, { clone: true })
bar.baz.YO // undefined as bar was deeply cloned by zealit
baz.baz.YO // throws a ReferenceError

// "strict" option
const foo = zealit({ x: undefined }, { strict: false })
foo.x // undefined, no Error thrown
foo.y // throws a ReferenceError
const bar = zealit({ x: undefined }, { strict: true })
bar.x // throws a ReferenceError
bar.y // throws a ReferenceError

Methods and options

zealit(obj, option)

Updates obj recursively and returns a zealed version of the object.

• obj <any> Any JavaScript primitive or Object
• option <Object>
  • freeze <boolean> If true, the object is freezed as the same time via Object.freeze. If provided, this local option will take precedence over the global option.
  • ignore <String|Array> Properties to ignore, no exception will be thrown for these properties as they keep behaving like vanilla JavaScript properties. The current zealed object will not throw exception for properties listed locally nor properties of the global list zealit.option.ignore
  • catch <boolean|Function> to override the default behavior (throwing a ReferenceError). If provided, this local option will take precedence over the global option.
    • fn(err): calls fn function with the ReferenceError as argument in place of throw ReferenceError
    • false: throw ReferenceError (default behavior)
    • true: doesn't throw ReferenceError
  • disable <boolean> If true, zealit does nothing. If provided, this local option will take precedence over the global option.
  • strict <boolean> If true, zealit throws a ReferenceError if property exists with the undefined value.

zealit.option

Object to expose global options, applies to all zealed objects.

• freeze <boolean> If true, zealit will freeze objects as the same time via Object.freeze. Defaults to false. If provided, the local option will take precedence over this global option.

  zealit.option.freeze = true
  const foo = zealit({ bar: true })
  foo.bar = false // throws a TypeError

• ignore <Array> Properties to ignore, no exception will be thrown for these properties as they keep behaving like vanilla JavaScript properties. Applies to all zealed objects, even those was instancied before an update of zealit.option.ignore

  const foo = zealit({ bar: true })
  foo.baz // throws a ReferenceError
  
  zealit.option.ignore.push('bar')
  foo.baz // undefined

• catch <boolean|Function> to override the default behavior (throwing a ReferenceError). If provided, the local option will take precedence over this global option.

  • fn(err): calls fn function with the ReferenceError as argument in place of throw ReferenceError
  • false: throw ReferenceError (default behavior)
  • true: doesn't throw ReferenceError

    const foo = zealit({ bar: true })
    zealit.option.catch = (err) => { console.log('gotcha', err) }
    foo.baz // return undefined and console.log('gotcha', ReferenceError)

• disable <boolean> If true, zealit does nothing, simply return obj itself.

  zealit.option.disable = true
  const foo = { bar: true }
  
  // same thing
  const baz = zealit(foo)
  const baz = foo

• strict <boolean> If true, zealit throws a ReferenceError if property has the undefined value, even if property exists. By default, zealit throws a ReferenceError only if property doesn't exist.

  zealit.option.strict = true
  const foo = zealit({ bar: undefined })
  foo.bar // throws a ReferenceError

Installation

Using npm:

$ npm install zealit --save

In Node.js:

const zealit = require('zealit')

Todo

• explain limitation (Promise, .length, lodash, hidden properties)
• more documentation about "clone" option (lose hidden properties vs update and keep those)
• option to rezeal a property
• test with more node version (v6.7.0 at the moment)
• option to disable recursion?