From caf72f0af38b59256662ecb18697a2d8790cb83c Mon Sep 17 00:00:00 2001 From: Conduitry Date: Fri, 29 Jun 2018 00:52:38 -0400 Subject: [PATCH] update docs --- API.md | 8 ++++---- GUIDE.md | 4 ++++ 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/API.md b/API.md index 640b978..faa6fd0 100644 --- a/API.md +++ b/API.md @@ -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)` diff --git a/GUIDE.md b/GUIDE.md index 4c6fafd..7033759 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -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.