update docs

API.md

@@ -72,8 +72,8 @@ Returns the `Defiler` instance for chaining.
 
 Register a new transform to be applied to all files.
 
-- `transform(file, get(path))` - a transformer function, which is passed a `File` instance to mutate; it is also passed a function `get(path)` which calls the `get(path, dependent)` method (see below) with the appropriate `dependent` (that is, the current file's path), as a convenience. In your function, `this` will be the current `Defiler` instance. The function can return a `Promise` to indicate when it's done
-- `if(file)` - _(optional)_ a function that, if present, will be called with the `File` instance before calling the main `transform`. In your function, `this` will be the current `Defiler` instance. If the function returns `false` or a `Promise` resolving to `false`, the transform is skipped
+- `transform({ defiler, path, file, get })` - a transformer function, which is passed an object containing the `Defiler` instance, the original `path` of the file, the `File` instance to mutate, and a function `get(path)` which calls the `get(path, dependent)` method (see below) with the appropriate `dependent` (that is, the current file's path), as a convenience. The function can return a `Promise` to indicate when it's done
+- `if({ defiler, path, file })` - _(optional)_ a function that, if present, will be called (before calling the main `transform`) with an object containing the `Defiler` instance, the original `path` of the file, and the `File` instance. If the function returns `false` or a `Promise` resolving to `false`, the transform is skipped
 
 Returns the `Defiler` instance for chaining.
 
@@ -82,7 +82,7 @@ Returns the `Defiler` instance for chaining.
 Register a new generated file, not directly sourced from a physical file.
 
 - `path` - the relative path of the file to register the generator for
-- `generator(file, get(path))` - a function that is passed a new `File` instance containing only a path, which it should then mutate; it is also passed a function `get(path)` which calls the `get(path, dependent)` method (see below) with the appropriate `dependent` (that is, the current file's path), as a convenience.  In your function, `this` will be the current `Defiler` instance. The function can return a `Promise` to indicate when it's done
+- `generator({ defiler, file, get })` - a generator function, which is passed an object containing the `Defiler` instance, a new `File` instance to mutate containing only a path, and a function `get(path)` which calls the `get(path, dependent)` method (see below) with the appropriate `dependent` (that is, the current file's path), as a convenience. The function can return a `Promise` to indicate when it's done
 
 Returns the `Defiler` instance for chaining.
 
@@ -94,6 +94,8 @@ Starts the Defiler running. No additional configuration (registering Gazes, tran
 
 - `close` - _(optional)_ whether to immediately close all of the attached Gazes after the initial wave of processing
 
+Returns the `Defiler` instance for chaining.
+
 ## Operation
 
 ### `get(path, dependent)`
@@ -133,18 +135,18 @@ Close all of the attached Gazes.
 
 `Defiler` extends Node's `EventEmitter`, and emits four kinds of events.
 
-### `origFile(origPath, file)`
+### `origFile({ defiler, file })`
 
-An `origFile` event is emitted when the original version of a physical file has been read in. It's emitted with two arguments: the file's original relative path and the `File` instance.
+An `origFile` event is emitted when the original version of a physical file has been read in. It's emitted with an object containing the `Defiler` instance and the `File` instance.
 
-### `file(origPath, file)`
+### `file({ defiler, path, file })`
 
-A `file` event is emitted after all transforms on a file are complete. It's emitted with two arguments: the file's original relative path and the fully transformed `File` instance.
+A `file` event is emitted after all transforms on a file are complete. It's emitted with an object containing the `Defiler` instance, the file's original relative `path`, and the fully transformed `File` instance.
 
-### `deleted(origPath)`
+### `deleted({ defiler, path })`
 
-A `deleted` event is emitted when a watched physical file has been deleted. It's emitted with one argument: the (original) relative path to the file.
+A `deleted` event is emitted when a watched physical file has been deleted. It's emitted with an object containing the `Defiler` instance and the (original) relative `path` to the file.
 
-### `error(origPath, file, err)`
+### `error({ defiler, path, file, error })`
 
-An `error` event is emitted if a file transform or a file generator throws an exception or returns a `Promise` that rejects. It's emitted with three arguments: the file's original relative path, the `File` instance that caused the error, and the thrown error.
+An `error` event is emitted if a file transform or a file generator throws an exception or returns a `Promise` that rejects. It's emitted with an object containing the `Defiler` instance, the file's original relative `path`, the `File` instance that caused the error, and the thrown `error`.

README.md

@@ -34,13 +34,13 @@ If you need some task management, that's outside the scope of this library. Just
 
 ## Documentation
 
-- [api](https://github.com/Conduitry/defiler/blob/master/API.md#readme)
-- [changelog](https://github.com/Conduitry/defiler/blob/master/CHANGELOG.md#readme)
-- [todo](https://github.com/Conduitry/defiler/blob/master/TODO.md#readme)
+- [usage](USAGE.md#readme)
+- [api](API.md#readme)
+- [changelog](CHANGELOG.md#readme)
 - [homepage](https://cndtr.io/defiler/)
 
 ## License
 
 Copyright (c) 2017 Conduitry
 
-- [MIT](https://github.com/Conduitry/defiler/blob/master/LICENSE)
+- [MIT](LICENSE)

TODO.md

@@ -1,5 +0,0 @@
-# TODO
-
-- maybe some sort of way to have parameterized generated files. Not sure how this would look exactly. There could be some files that we want to process in one of two (or more) ways, depending on where they're used from, but we can't tell from the file itself how it should be processed. We could push responsibility for this processing into the transform etc. that needs the processed file, but that doesn't seem ideal, as when one dependency changes that would involve re-processing other unchanged things we've already processed. It might be best if this were a whole separate third type of thing, apart from physical and generated files
-
- - I'm probably leaning away from this being Defiler's responsibility. This is something that can be handled by the consuming project. This 'contextual processing' can be done on-demand, and the values can be cached by storing them directly on the `File` instance. The cache will be automatically invalidated in normal cases, when necessary the instance will already be getting discarded and re-created from the `File` instance for the original file on disk

USAGE.md

@@ -0,0 +1 @@
+TODO