diff --git a/README.md b/README.md
index 8fbc9e1..0050155 100644
--- a/README.md
+++ b/README.md
@@ -14,57 +14,80 @@
* [Features](#features)
* [API](#api)
* [`figgyPudding(spec)`](#figgy-pudding)
- * [`Opts(values)`](#opts)
+ * [`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
-const puddin = require('figgyPudding')
+// print-package.js
+const fetch = require('./fetch.js')
+const puddin = require('figgy-pudding')
-const RequestOpts = puddin({
- follow: {
- default: true
- },
- streaming: {
- default: false
- },
- log: {
- default: require('npmlog')
- }
+const PrintOpts = puddin({
+ json: { default: false }
})
-const MyAppOpts = puddin({
- log: {
- default: require('npmlog')
- },
- cache: {
- default: './cache'
+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()
}
-})
-
-function start (opts) {
- opts = MyAppOpts(opts)
- initCache(opts.get('cache'))
- opts.get('streaming') // => undefined
- reqStuff('https://npm.im/figgy-pudding', opts)
}
-function reqStuff (uri, opts) {
- opts = RequestOpts(opts)
- require('request').get(uri, opts) // can't see `cache`
+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
+* hide options from layer that didn't ask for it
+* shared multi-layer options
+* make sure `opts` argument is available
+* default values
+* key aliases
+* arbitrary key filter functions
+* key/value iteration
+* serialization
### API
-#### `> figgyPudding({ key: { default: val } | String }, [opts])`
+#### `> figgyPudding({ key: { default: val } | String }, [opts]) -> PuddingFactory`
Defines an Options constructor that can be used to collect only the needed
options.
@@ -87,7 +110,7 @@ const MyAppOpts = figgyPudding({
})
```
-#### `> Opts(...providers)`
+#### `> PuddingFactory(...providers) -> FiggyPudding{}`
Instantiates an options object defined by `figgyPudding()`, which uses
`providers`, in order, to find requested properties.
@@ -112,17 +135,17 @@ const opts = ReqOpts({
log: require('npmlog')
})
-opts.get('follow') // => true
-opts.get('log') // => Error: ReqOpts does not define `log`
+opts.follow // => true
+opts.log // => Error: ReqOpts does not define `log`
const MoreOpts = figgyPudding({
log: {}
})
-MoreOpts(opts).get('log') // => npmlog object (passed in from original plain obj)
-MoreOpts(opts).get('follow') // => Error: MoreOpts does not define `follow`
+MoreOpts(opts).log // => npmlog object (passed in from original plain obj)
+MoreOpts(opts).follow // => Error: MoreOpts does not define `follow`
```
-#### `> opts.get(key)`
+#### `> opts.get(key) -> Value`
Gets a value from the options object.
@@ -131,9 +154,10 @@ Gets a value from the options object.
```js
const opts = MyOpts(config)
opts.get('foo') // value of `foo`
+opts.foo // Proxy-based access through `.get()`
```
-#### `> opts.concat(...moreProviders)`
+#### `> 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
@@ -147,3 +171,84 @@ opts.get('x') // 1
opts.concat({x: 2}).get('x') // 2
opts.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
+
+```js
+const opts = MyOpts({x: 1})
+opts.toJSON() // {x: 1}
+JSON.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
+
+```js
+const opts = MyOpts({x: 1, y: 2})
+opts.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
+
+```js
+const opts = MyOpts({x: 1, y: 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
+
+```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)
+}
+```
+
+#### `> 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']
+```
+
+#### `> 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]
+```