update docs

This commit is contained in:
Conduitry 2018-03-20 09:14:48 -04:00
parent 073ed1e8e0
commit 84584b9e54
3 changed files with 10 additions and 7 deletions

13
API.md
View File

@ -54,22 +54,25 @@ The assumed encoding for the file. Defaults to `'utf8'`. Must be one of Node.js'
## Constructor
### `new Defiler({ dir, read = true, enc = 'utf8', watch = true, debounce = 10, transform, generators = [] })`
### `new Defiler({ dir, filter, read = true, enc = 'utf8', watch = true, debounce = 10, transform, generators = [] })`
A new `Defiler` instance to represent a collection of physical files and virtual files, a transform to run on them, and additional generators.
- Directory configuration
- Input configuration
- `dir` - the directory to watch
- `filter({ path, stats })` - _(optional)_ a function to decide whether a given file or directory should be considered by Defiler. It's passed an object containing the file or directory's relative `path` and its `stats`. It should return `true` or `false` (or a `Promise` resolving to one of those). Returning `false` for a directory means that none of its contents will be included. You can use `stats.isFile()` and `stats.isDirectory()` to determine whether this is a file or a directory
- `read` - _(optional)_ whether to actually read in the contents of the files in the directory. Defaults to `true`. If `false`, the files will still be run through the transform, but they will have null `bytes` and `text`
- `enc` - _(optional)_ encoding to use for files read in from the directory. Defaults to `'utf8'`. This can also be changed for individual files (see [`file.enc`](#enc))
- Can also be a function `read({ path, stats })`, which should return `true` or `false` (or a `Promise` resolving to one of those), allowing whether each file is read in to be decided individually
- `enc` - _(optional)_ encoding to use for files read in from the directory. Defaults to `'utf8'`
- Can also be a function `enc({ path, stats, bytes })`, which should return an encoding name (or a `Promise` resolving to one), allowing the encoding on each file to be decided individually
- `watch` - _(optional)_ whether to actually watch the directory for changes. Defaults to `true`. If `false`, the files will still be run through the transform, but any changes to them will not be
- `debounce` - _(optional)_ The length of the timeout in milliseconds to use to debounce incoming events from `fs.watch`. Defaults to 10. Multiple events are often emitted for a single change, and events can also be emitted before `fs.stat` reports the changes. Defiler will wait until `debounce` milliseconds have passed since the last `fs.watch` event for a file before handling it. The default of 10ms Works On My Machine
- `debounce` - _(optional)_ length of timeout in milliseconds to use to debounce incoming events from `fs.watch`. Defaults to 10. Multiple events are often emitted for a single change, and events can also be emitted before `fs.stat` reports the changes. Defiler will wait until `debounce` milliseconds have passed since the last `fs.watch` event for a file before handling it. The default of 10ms Works On My Machine
- Transform configuration
- `transform({ defiler, file })` - a transform function, which is passed an object containing the `Defiler` instance and the `File` instance to mutate. The transform function can return a `Promise` to indicate when it's done
- Generator configuration
- `generators` - _(optional)_ an array of generator functions, each of the form `generator({ defiler })`. Each generator is passed an object containing the `Defiler` instance. Each generator function can return a `Promise` to indicate when it's done
- Resolver configuration
- `resolver(base, path)` - _(optional)_ a function that will be used to resolve the paths passed to `defiler.get` and `defiler.add` from the transform. This will be passed two arguments, `base` (the path of the file being transformed) and `path` (the path passed to `defiler.get`/`defiler.add`), and should return the resolved (original) path to look up
- `resolver(base, path)` - _(optional)_ a function that will be used to resolve the paths passed to `defiler.get` and `defiler.add` from the transform. This will be passed two arguments, `base` (the path of the file being transformed) and `path` (the path passed to `defiler.get`/`defiler.add`), and should return the resolved path to use
## Properties

View File

@ -12,7 +12,7 @@
# v0.13.2
- If a file change event comes in during the first wave of processing, don't wait for another event after the first wave to trigger the second wave, and instead start it immediately upon finishing the first.
- If a file change event comes in during the first wave of processing, don't wait for another event after the first wave to trigger the second wave, and instead start it immediately upon finishing the first
# v0.13.1

View File

@ -54,7 +54,7 @@ First, [create a new `Defiler` instance](API.md#defiler), initializing it with t
Then, call its [`exec()` method](API.md#exec) to set everything in motion. This returns a `Promise` that will resolve when the initial wave of processing has completed.
Useful things available on the `Defiler` instance for you to use in the transform or the generators are:
Useful things available on the `Defiler` instance for you to use in the transform, in the generators, or elsewhere are:
- [`defiler.paths`](API.md#paths) - a `Set` of the paths of all of the physical files
- [`defiler.files`](API.md#files) - a `Map` of original paths to the transformed `File` instances