doc fixes and adjustments

This commit is contained in:
Conduitry 2018-03-09 09:48:55 -05:00
parent cb30b15d8e
commit ea009d5e43
2 changed files with 18 additions and 12 deletions

18
API.md
View File

@ -2,21 +2,21 @@ The API consists of two classes, `File` and `Defiler`.
A `File` represents a physical file on the disk, or a virtual file with no particular corresponding file in the file system, or a partially or fully transformed physical or virtual file.
A `Defiler` represents a set of watched files on the disk, plus a set of virtual files, plus a transform to execute on them.
A `Defiler` represents a set of watched files on the disk, plus a set of virtual files, plus the operations to perform on them.
# `File`
## Constructor
### `new File(path)`
### `new File()`
A new `File` instance to serve as the representation of a physical file, a virtual file, or a transformed file. `path` is the relative path to the file, from some understood root. The past is always separated by forward slashes, regardless of platform.
A new `File` instance to serve as the representation of a physical file, a virtual file, or a transformed file.
## Properties
### `path`
The file's path can be retrieved or updated by getting and setting `path`. Updating `dir`, `filename`, or `ext` also update this.
The relative path to the file, from some understood root. The path is always separated by forward slashes, regardless of platform. Updating `dir`, `filename`, or `ext` also updates this.
### `paths`
@ -42,11 +42,13 @@ The `fs.Stats` of the file.
The file's contents can be updated by getting or setting `bytes`, which is a `Buffer`.
Don't mutate this property. This causes various unwanted effects. Instead, assign it a new `Buffer` instance.
### `text`
The file's contents can also be updated by getting or setting `text`, which is a string.
Mutations to the `bytes` `Buffer` will not be reflected in `text`, but reassigning the entire `bytes` or `text` properties will keep the other in sync.
Reassigning the entire `bytes` or `text` properties will keep the other in sync.
### `enc`
@ -85,7 +87,9 @@ A `Map` of original relative paths to `File` instances for the transformed files
### `exec()`
Start the Defiler running. Returns a promise that resolves when the initial wave of processing is complete.
Start the `Defiler` running.
Returns a `Promise` that resolves when the initial wave of processing is complete.
### `get(path)`
@ -103,7 +107,7 @@ When used in your transform, this will also register the file being transformed
Manually insert a virtual `File`, running it through the transform.
- `file` - the `File` object (or plain old JavaScript object) representing the virtual file to add
- `file` - the `File` instance (or plain old JavaScript object) representing the virtual file to add
For convenience, you can call this with a POJO, and a new `File` instance will be created for you with properties `Object.assign`ed from the object.

View File

@ -4,9 +4,11 @@
Defiler's concept of a file is something that can come from one of two places: a physical file on the disk, or a virtual file that is generated by your code. These two types of files differ very slightly in how they are treated, but for the most part Defiler handles them both the same.
`File`s have a `path` field containing the relative path to the file, as well as `dir`, `filename`, and `ext` fields containing portions of the path. All of these can be updated and keep the others in sync. `paths` contains an array of all historical paths this `File` instance has had since its creation.
`File`s have a `path` property containing the relative path to the file, as well as `dir`, `filename`, and `ext` properties containing portions of the path. All of these can be updated and keep the others in sync. `paths` contains an array of all historical paths this `File` instance has had since its creation.
`File`s also have `text` and `bytes` fields, containing string and `Buffer` representations of the file's contents. Either can be updated and keeps the other in sync (with some restrictions). The `enc` field specifies the encoding to be used when converting between `text` and `bytes`, and can be changed.
For physical files, the `stats` property contains the `fs.Stats` object retrieved for the original file.
`File`s also have `text` and `bytes` properties, containing string and `Buffer` representations of the file's contents. Either can be updated and keeps the other in sync. (You shouldn't mutate `bytes`, only reassign it.) The `enc` property specifies the encoding to be used when converting between `text` and `bytes`, and can be changed.
See the [API docs](API.md#file) for more information.
@ -14,7 +16,7 @@ See the [API docs](API.md#file) for more information.
Every file (physical and virtual) is run through the transform function you register with Defiler. The transform mutates the object representing the file in-place, and returns a promise indicating when it's finished.
The transform is called, for each file, with an object containing `defiler` (the `Defiler` instance) and `file` (the `File` instance). The transform should mutate the `file` object as it sees fit. It can also take whichever actions it wishes based on the file (including, for example, writing output to disk). Files' paths can be changed as they're transformed, but the main way to refer to them will continue to be by their original path (see [dependence](#dependence)).
The transform is called, for each file, with an object containing `defiler` (the `Defiler` instance) and `file` (the `File` instance). The transform should mutate the `file` object as it sees fit. It can also take whichever actions it wishes based on the file (including, for example, writing output to disk). Files' paths can be changed as they're transformed, but the main way to refer to them from other files will continue to be by their original path (see [dependence](#dependence)).
## Dependence
@ -30,13 +32,13 @@ See the [API docs](API.md#getpath) for more information.
During the transform's processing of a file, you can also create virtual files, which don't directly correspond one-to-one with physical files. The `Defiler` instance has a `defiler.add(file)` method, which you can pass a `File` instance to (or a POJO, which will be turned into a `File`). The virtual file will run through the transform and will thereafter be treated pretty much like a physical file. In particular, you can make other files depend on it with `defiler.get(path)`.
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 get created. 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`.
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`.
## 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 accepts one argument, an object containing `defiler`. 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.
It's beneficial to write multiple smaller generators, rather than one monolithic ones. This helps ensure that unneeded recalculation is not done when a file changes.
It's beneficial to write multiple smaller generators, rather than a single large one. This helps ensure that unneeded recalculation is not done when a file changes.
# Usage