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)

Transparently supply default values for JavaScript Objects.

Install

npm install @status/defaults

yarn add @status/defaults

Usage

Defaults exposes a function, wrapDefaults, that receives your object and any options;

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

const wrapped = wrapDefaults({
  wrap: myObject,
  /** options explained below */
});

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 { wrapDefaults } from '@status/defaults';

const wrapped = wrapDefaults({
  wrap: myObject,
  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 { wrapDefaults } from '@status/defaults';

const wrapped = wrapDefaults({
  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 = wrapDefaults({
  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 = wrapDefaults({
  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]);

Using 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.

Option	Default Value	Description
wrap	{}	The object to wrap
shallowCopy	true	Only create shallow copies of `defaultValue` objects
setUndefined	false	Set undefined values with `defaultValue`
defaultValue	undefined	The value to return if resolved value is undefined
setCriteria	() => false	Function that can override value to be set with the `defaultValue`
execute	false	If true and `defaultValue` is a function it will be executed and the result returned
noCopy	false	Indicates if non-primitive default values should be returned as-is
reuseMapKey	true	If true and default value is a Map the key will be reused, otherwise shallowCopy rules apply

Override

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

const aboveZero = wrapDefaults({
  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 = wrapDefaults({ defaultValue: [], setUndefined: true });
const prop = 'prop';

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

Examples

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

const charCount = wrapDefaults({
  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 = wrapDefaults({ defaultValue: [] });

myObj.ifNotExistsWillStillHaveArray.forEach(...);

@status/defaults