Package Exports

@status/defaults

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@status/defaults) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Defaults

npm (scoped) GitHub Travis (.org)

Supply default values for JavaScript Objects using ES2015 Proxy.

Install

npm install @status/defaults

yarn add @status/defaults

Usage

You may invoke the Proxy yourself, passing Defaults as the handler.

import { Defaults } from '@status/defaults';

const wrapped = new Proxy(myObject, new Defaults());

Defaults default is undefined, which makes it rather useless, so supplying your own default is a good idea.

Additionally, it accepts a function that can be used to determine if a default value should be used instead of the value being set. Returning true, or any truthy value, will result in your default value being set.

import { Defaults } from '@status/defaults';

const wrapped = new Proxy(
  myObject,
  new Defaults({
    defaultValue: 0,
    setCriteria: (value, _property, _myObject) => value < 0,
  })
);

wrapped.belowZero = -35;

expect(wrapped.belowZero).to.equal(0);

Be aware that while defaults are supplied for undefined values they are not set. This behavior can be modified.

import { Defaults } from '@status/defaults';

const wrapped = new Proxy(
  {},
  new Defaults({
    defaultValue: 0,
    setUndefined: true,
  })
);

expect(wrapped.notThere).to.equal(0);

Using complex content as a default is possible, but only shallow copies are made.

const complex = new Proxy(
  {},
  new Defaults({
    defaultValue: [[2.345, 43.53]],
    setUndefined: true,
  })
);

expect(complex.point1).to.not.equal(complex.point2);
expect(complex.point1[0]).to.equal(complex.point2[0]);

This can be changed by passing shallowCopy as false. ShallowCopy has no effect when using primitive values.

const complex = new Proxy(
  {},
  new Defaults({
    defaultValue: [[2.345, 43.53]],
    setUndefined: true,
    shallowCopy: false,
  })
);

expect(complex.point1).to.not.equal(complex.point2);
expect(complex.point1[0]).to.not.equal(complex.point2[0]);

For convenience, Defaults has a static wrap method.

import { Defaults } from '@status/defaults';

const wrapped = Defaults.wrap({
  wrap: myObject,
  defaultValue: 0,
  shallowCopy: false,
  setUndefined: true,
  setCriteria: v => v < 0,
});

Or a wrapDefaults helper function:

import { wrapDefaults } from '@status/defaults';

const wrapped = wrapDefaults({
  wrap: myObject,
  defaultValue: 0,
  shallowCopy: false,
  setUndefined: true,
  setCriteria: v => v < 0,
});

Using either static wrap or wrapDefaults helper will add a type for unwrapDefaults method, which, when invoked, returns the original unwrapped object.

import { wrapDefaults } from '@status/defaults';

class Person {}

const person = new Person();
const defaults = wrapDefaults({ wrap: person });
const unwrapped = defaults.unwrapDefaults();

expect(person).to.not.equal(defaults);
expect(unwrapped).to.equal(person);

Defaults can also wrap arrays.

import { wrapDefaults } from '@status/defaults';

const array = wrapDefaults({
  wrap: [] as number[],
  defaultValue: 7,
  setCriteria: v => v < 7,
  setUndefined: true,
});

expect(array[0]).to.equal(7);

array.push(1);

expect(array[1]).to.equal(7);

`Defaults` defaults

All options have default values.

wrap: {}
shallowCopy: true
setUndefined: false
defaultValue: undefined
setCriteria: () => false

Override

You may override your defined criteria should you really need to set a value that would fail.

const aboveZero = Defaults.wrap({
  defaultValue: 0,
  setCriteria: v => v < 0,
});

aboveZero.notAnymore = { ignoreDefaultCriteria: true, value: -345 };

console.log(aboveZero);
// => { notAnymore: -345 }

Info

Determining if a property exists on an object is unaffected when using Defaults, even when using setUndefined.

const wrapped = Defaults.wrap({ defaultValue: [], setUndefined: true });
const prop = 'prop';

expect(prop in wrapped).to.be.false;

Examples

import { Defaults } from '@status/defaults';

const charCount = Defaults.wrap({
  defaultValue: 0,
  setCriteria: v => v < 0,
});

const sentence = 'something wicked this way comes';

// do this (using Defaults)
for (const char of sentence) {
  charCount[char]++;
}

// instead of this (without Defaults)
for (const char of sentence) {
  if (!(char in charCount)) {
    charCount[char] = 0;
  }

  charCount[char]++;
}

Ever done something like this?

const myObj = { prop1: [] };


(myObj.propMaybeExists || []).forEach(...);

Use defaults instead.

const myObj = Defaults.wrap({ defaultValue: [] });

myObj.ifNotExistsWillStillHaveArray.forEach(...);

Caveats

In a Node environment, if you enabled setUndefined and console.log(myWrappedObject) you will have additional properties due to this bug.

inspect
[Symbol(nodejs.util.inspect.custom)]
[Symbol(Symbol.toStringTag)]
[Symbol(Symbol.iterator)]

As far as I'm aware this only happens when inspecting and is just something we'll have to ignore.

@status/defaults