1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
# figgy-pudding [](https://npm.im/figgy-pudding) [](https://npm.im/figgy-pudding) [](https://travis-ci.org/zkat/figgy-pudding) [](https://ci.appveyor.com/project/zkat/figgy-pudding) [](https://coveralls.io/github/zkat/figgy-pudding?branch=latest)
[`figgy-pudding`](https://github.com/zkat/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](#example)
* [Features](#features)
* [API](#api)
* [`figgyPudding(spec)`](#figgy-pudding)
* [`PuddingFactory(values)`](#pudding-factory)
* [`opts.get()`](#opts-get)
* [`opts.concat()`](#opts-concat)
* [`opts.toJSON()`](#opts-to-json)
* [`opts.forEach()`](#opts-for-each)
* [`opts[Symbol.iterator]()`](#opts-symbol-iterator)
* [`opts.entries()`](#opts-entries)
* [`opts.keys()`](#opts-keys)
* [`opts.value()`](#opts-values)
### Example
```javascript
// print-package.js
const fetch = require('./fetch.js')
const puddin = require('figgy-pudding')
const PrintOpts = puddin({
json: { default: false }
})
async function printPkg (name, opts) {
// Expected pattern is to call this in every interface function. If `opts` is
// not passed in, it will automatically create an (empty) object for it.
opts = PrintOpts(opts)
const uri = `https://registry.npmjs.com/${name}`
const res = await fetch(uri, opts.concat({
// Add or override any passed-in configs and pass them down.
log: customLogger
}))
// The following would throw an error, because it's not in PrintOpts:
// console.log(opts.log)
if (opts.json) {
return res.json()
} else {
return res.text()
}
}
console.log(await printPkg('figgy', {
// Pass in *all* configs at the toplevel, as a regular object.
json: true,
cache: './tmp-cache'
}))
```
```javascript
// fetch.js
const puddin = require('figgy-pudding')
const FetchOpts = puddin({
log: { default: require('npmlog') },
cache: {}
})
module.exports = async function (..., opts) {
opts = FetchOpts(opts)
}
```
### 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
#### <a name="figgy-pudding"></a> `> 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
```javascript
const MyAppOpts = figgyPudding({
lg: 'log',
log: {
default: () => require('npmlog')
},
cache: {}
})
```
#### <a name="pudding-factory"></a> `> 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
```javascript
const ReqOpts = figgyPudding({
follow: {}
})
const opts = ReqOpts({
follow: true,
log: require('npmlog')
})
opts.follow // => true
opts.log // => Error: ReqOpts does not define `log`
const MoreOpts = figgyPudding({
log: {}
})
MoreOpts(opts).log // => npmlog object (passed in from original plain obj)
MoreOpts(opts).follow // => Error: MoreOpts does not define `follow`
```
#### <a name="opts-get"></a> `> opts.get(key) -> Value`
Gets a value from the options object.
##### Example
```js
const opts = MyOpts(config)
opts.get('foo') // value of `foo`
opts.foo // Proxy-based access through `.get()`
```
#### <a name="opts-concat"></a> `> 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
```js
const opts = MyOpts({x: 1})
opts.get('x') // 1
opts.concat({x: 2}).get('x') // 2
opts.get('x') // 1 (original opts object left intact)
```
#### <a name="opts-to-json"></a> `> 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
```js
const opts = MyOpts({x: 1})
opts.toJSON() // {x: 1}
JSON.stringify(opts) // '{"x":1}'
```
#### <a name="opts-for-each"></a> `> 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
```js
const opts = MyOpts({x: 1, y: 2})
opts.forEach((value, key) => console.log(key, '=', value))
```
#### <a name="opts-entries"></a> `> 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
```js
const opts = MyOpts({x: 1, y: 2})
[...opts({x: 1, y: 2}).entries()] // [['x', 1], ['y', 2]]
```
#### <a name="opts-symbol-iterator"></a> `> 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
```js
const opts = MyOpts({x: 1, y: 2})
[...opts({x: 1, y: 2})] // [['x', 1], ['y', 2]]
for (let [key, value] of opts({x: 1, y: 2})) {
console.log(key, '=', value)
}
```
#### <a name="opts-keys"></a> `> 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
```js
const opts = MyOpts({x: 1, y: 2})
[...opts({x: 1, y: 2}).keys()] // ['x', 'y']
```
#### <a name="opts-values"></a> `> 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
'
```js
const opts = MyOpts({x: 1, y: 2})
[...opts({x: 1, y: 2}).values()] // [1, 2]
```
|
