update docs

This commit is contained in:
Conduitry 2018-06-29 00:52:38 -04:00
parent 1ce9174b84
commit caf72f0af3
2 changed files with 8 additions and 4 deletions

8
API.md
View File

@ -94,7 +94,7 @@ Returns a `Promise` that resolves when the initial wave of processing is complet
### `get(path)`
Wait for a file or array of files to be ready and retrieve the `File` instance.
Wait for a file to be ready and retrieve the `File` instance.
- `path` - the path to wait for to become available and to then return
@ -114,13 +114,13 @@ Returns a `Promise` resolving to an array of `File` instances.
### `get(filter)`
Wait for all _physical_ files whose paths match a given filter function and retrieve the `File` instances.
Wait for all files whose paths match a given filter function and retrieve the `File` instances.
- `filter(path)` - a function that will be passed a path and should return a boolean
Returns a `Promise` resolving to an array of matching `File` instances.
Returns a `Promise` resolving to an array of matching `File` instances, sorted by their (original) paths.
Note that only the paths of _physical_ files will be checked with your filter function. Once the initial wave of processing is complete, any new files matching the filter will also cause the generator or transform to be re-run.
This will return physical and virtual files. Once the initial wave of processing is complete, any new files matching the filter will also cause the generator or transform to be re-run.
### `add(file)`

View File

@ -37,6 +37,8 @@ The `defiler.get(path)` method, when used inside the transform, lets you depend
The `defiler.get` method can also be passed an array of (original) paths, in which case it will return a `Promise` resolving to an array of `File` instances (or `undefined`s).
It can also be passed a filter function, which should accept a path and return a boolean. In this case `defiler.get` will return a `Promise` resolving to an array of all `File` instances whose (original) paths match the filter.
See the [API docs](API.md#getpath) for more information.
## Virtual files
@ -45,6 +47,8 @@ During the transform's processing of a file, you can also create virtual files,
Since Defiler has no way of knowing which virtual files will be created from transforming which files, when `defiler.get` is used to request a file that doesn't exist yet, Defiler waits until it does. Requesting a file that's never going to exist would cause a deadlock, so Defiler resolves this as a generalization of the above-mentioned deadlock resolution: If it ever happens that every in-process action is waiting for some other transformed file to exist, Defiler will resolve each of those pending `Promise`s returned by `defiler.get` to `undefined`.
Similarly when retrieving files by a filter, there's no way to know which files will eventually exist. So Defiler will wait until all of the in-progress actions depend on filter responses or other in-progress files, at which point Defiler will resolve each pending filter `Promise` to the array of matching files that have been already completed in that moment.
## Generators
Generators are an independent way of interacting with the Defiler instance, for things that do not fit well into the main transform. Each generator is a function that will be called without arguments. A generator would typically call `defiler.get` and/or `defiler.add` to retrieve dependencies and write new virtual files. Automatic dependence handling also works here, so when one of the files retrieved by `defiler.get` changes, that generator will be re-run.