options-stack v1.0.4

options-stack

A tool to help manage subclassable config/options objects

npm install options-stack --save

usage

Suppose you have a base pet options object

const pet = {
  furry: true,
  mammal: true
}

but then there are different types of pets

const dog = { canine: true }
const cat = { feline: true }
const iguana = {
  reptile: true,
  mammal: false,
  furry: false
}

create a new options stack (with an optional root options object)

const options = require('options-stack')(pet);

and add the subclasses to options separately:

options.add('dog', dog)
options.add('cat', cat)
options.add('iguana', iguana)

or, equivalently, lump them together

options.add({
  dog, cat, iguana
})

This package is largely a thinly vieled special use-case of Object.assign on top of an array, and in the second case above, the props are added to the array key by key (order not guaranteed).

Adding additional subtypes whenever/dynamically is fine

options.add('gremlin', {
  mammal: false,
  hydrophobic: true
})

Then access the specific type as necessary:

const dogOpts = options.get('dog');
// { furry: true, mammal: true, canine: true }
const gremlinOpts = options.get('gremlin')
// { furry: true, mammal: false, hydrophobic: true }

Adding a final layer with/upon get is supported:

const stripeOpts = options.get('gremlin', {
  canBeMean: true
})
// { furry: true, mammal: false, hydrophobic: true, canBeMean: true }

If you want to modify the root object post-creation:

options.addRoot({
  gassy: true
})

now

options.get('gremlins').gassy // true
// but..
stripeOpts.gassy //false (not modified by later mutations)

Note that Object.assign is only used to the top (i.e. named) level. Mutations to any property sub-objects will propagate.

const fish = {
  scaly: true
  swims: {in: 'sea'}
};
options.add({fish});
const fishOpts = options.get('fish');
fish.scaly = false;
fishOpts.scaly; // true
fish.swims.in = 'bathtub';
fishOpts.swims.in; // 'bathtub'

The root config/options object is also accessible:

options.get() // { furry: true, mammal: true, gassy: true }

This is also the object returned for any key that does not have any named matches in the stack:

options.get('worm') // { furry: true, mammal: true, gassy: true }

API

where const createStack = require('options-stack')

createStack(rootOptions)

creates a new options stack with rootOptions (optional)

addRoot(extraRootOptions)

adds another layer of root options

add(key, opts)

adds a single layer for the key string

add(multiOpts)

adds multiple layers, one for each key in multiOpts

get(key)

computes and returns the current effective options object for the given key. if !key or no options layers exist in the stack for the given key, then the current effective root options are returned as default