Note: pending imminent deprecation

This module will be deprecated once npm v7 is released. Please do not rely on it more than absolutely necessary (ie, only if you are depending on it for use with npm v6 internal dependencies).

---

figgy-pudding

figgy-pudding is a small JavaScript library for managing and composing cascading options objects -- hiding what needs to be hidden from each layer, without having to do a lot of manual munging and passing of options.

The God Object is Dead!

Now Bring Us Some Figgy Pudding!

Install

$ npm install figgy-pudding

Table of Contents

• Example
• Features
• API
  • figgyPudding(spec)
  • PuddingFactory(values)
    • opts.get()
    • opts.concat()
    • opts.toJSON()
    • opts.forEach()
    • opts[Symbol.iterator]()
    • opts.entries()
    • opts.keys()
    • opts.value()

Example

1// print-package.js
2const fetch = require('./fetch.js')
3const puddin = require('figgy-pudding')
4
5const PrintOpts = puddin({
6  json: { default: false }
7})
8
9async function printPkg (name, opts) {
10  // Expected pattern is to call this in every interface function. If `opts` is
11  // not passed in, it will automatically create an (empty) object for it.
12  opts = PrintOpts(opts)
13  const uri = `https://registry.npmjs.com/${name}`
14  const res = await fetch(uri, opts.concat({
15    // Add or override any passed-in configs and pass them down.
16    log: customLogger
17  }))
18  // The following would throw an error, because it's not in PrintOpts:
19  // console.log(opts.log)
20  if (opts.json) {
21    return res.json()
22  } else {
23    return res.text()
24  }
25}
26
27console.log(await printPkg('figgy', {
28  // Pass in *all* configs at the toplevel, as a regular object.
29  json: true,
30  cache: './tmp-cache'
31}))

1// fetch.js
2const puddin = require('figgy-pudding')
3
4const FetchOpts = puddin({
5  log: { default: require('npmlog') },
6  cache: {}
7})
8
9module.exports = async function (..., opts) {
10  opts = FetchOpts(opts)
11}

Features

• hide options from layer that didn't ask for it
• shared multi-layer options
• make sure opts argument is available
• transparent key access like normal keys, through a Proxy. No need for.get()!
• default values
• key aliases
• arbitrary key filter functions
• key/value iteration
• serialization
• 100% test coverage using tap --100

API

> figgyPudding({ key: { default: val } | String }, [opts]) -> PuddingFactory

Defines an Options constructor that can be used to collect only the needed options.

An optional default property for specs can be used to specify default values if nothing was passed in.

If the value for a spec is a string, it will be treated as an alias to that other key.

Example

1const MyAppOpts = figgyPudding({
2  lg: 'log',
3  log: {
4    default: () => require('npmlog')
5  },
6  cache: {}
7})

> PuddingFactory(...providers) -> FiggyPudding{}

Instantiates an options object defined by figgyPudding(), which uses providers, in order, to find requested properties.

Each provider can be either a plain object, a Map-like object (that is, one with a .get() method) or another figgyPudding Opts object.

When nesting Opts objects, their properties will not become available to the new object, but any further nested Opts that reference that property will be able to read from their grandparent, as long as they define that key. Default values for nested Opts parents will be used, if found.

Example

1const ReqOpts = figgyPudding({
2  follow: {}
3})
4
5const opts = ReqOpts({
6  follow: true,
7  log: require('npmlog')
8})
9
10opts.follow // => true
11opts.log // => Error: ReqOpts does not define `log`
12
13const MoreOpts = figgyPudding({
14  log: {}
15})
16MoreOpts(opts).log // => npmlog object (passed in from original plain obj)
17MoreOpts(opts).follow // => Error: MoreOpts does not define `follow`

> opts.get(key) -> Value

Gets a value from the options object.

Example

1const opts = MyOpts(config)
2opts.get('foo') // value of `foo`
3opts.foo // Proxy-based access through `.get()`

> opts.concat(...moreProviders) -> FiggyPudding{}

Creates a new opts object of the same type as opts with additional providers. Providers further to the right shadow providers to the left, with properties in the original opts being shadows by the new providers.

Example

1const opts = MyOpts({x: 1})
2opts.get('x') // 1
3opts.concat({x: 2}).get('x') // 2
4opts.get('x') // 1 (original opts object left intact)

> opts.toJSON() -> Value

Converts opts to a plain, JSON-stringifiable JavaScript value. Used internally by JavaScript to get JSON.stringify() working.

Only keys that are readable by the current pudding type will be serialized.

Example

1const opts = MyOpts({x: 1})
2opts.toJSON() // {x: 1}
3JSON.stringify(opts) // '{"x":1}'

> opts.forEach((value, key, opts) => {}, thisArg) -> undefined

Iterates over the values of opts, limited to the keys readable by the current pudding type. thisArg will be used to set the this argument when calling the fn.

Example

1const opts = MyOpts({x: 1, y: 2})
2opts.forEach((value, key) => console.log(key, '=', value))

> opts.entries() -> Iterator<[[key, value], ...]>

Returns an iterator that iterates over the keys and values in opts, limited to the keys readable by the current pudding type. Each iteration returns an array of [key, value].

Example

1const opts = MyOpts({x: 1, y: 2})
2[...opts({x: 1, y: 2}).entries()] // [['x', 1], ['y', 2]]

> opts[Symbol.iterator]() -> Iterator<[[key, value], ...]>

Returns an iterator that iterates over the keys and values in opts, limited to the keys readable by the current pudding type. Each iteration returns an array of [key, value]. Makes puddings work natively with JS iteration mechanisms.

Example

1const opts = MyOpts({x: 1, y: 2})
2[...opts({x: 1, y: 2})] // [['x', 1], ['y', 2]]
3for (let [key, value] of opts({x: 1, y: 2})) {
4  console.log(key, '=', value)
5}

> opts.keys() -> Iterator<[key, ...]>

Returns an iterator that iterates over the keys in opts, limited to the keys readable by the current pudding type.

Example

1const opts = MyOpts({x: 1, y: 2})
2[...opts({x: 1, y: 2}).keys()] // ['x', 'y']

> opts.values() -> Iterator<[value, ...]>

Returns an iterator that iterates over the values in opts, limited to the keys readable by the current pudding type.

Example

'

1const opts = MyOpts({x: 1, y: 2})
2[...opts({x: 1, y: 2}).values()] // [1, 2]