@finch/core
Finch's tools to create observable streams and operators. This API documentation is intended developers implementing their own services built onto Finch.
Installation
npm install -g @finch/core
-g
flag to install within the current directory.
API
Finch does not expose TypeScript typings. But, the API below is documented using them for clarity.
createStream
🐦 Stability: 2 - Stable (added in 1.0.0)
type OperatorDefinition = {
continueOnError: boolean;
debug: boolean;
include: string;
name: string;
off: string;
params: Record<string, any>;
retryCount: number;
retryWait: number;
use: string;
};
type Options = {
continueOnError?: boolean;
definitions: OperatorDefinition[];
resolveFrom: string;
shouldWatch?: boolean;
};
function createStream(options: Options): Rx.Observable<any>;
Description
This is Finch's white rabbit and magician's hat. Provides an Observable for a single stream definition. A stream definition is composed of one or more operator definitions.
See the stream schema for more information.
Options
-
continueOnError
: Whentrue
it enables an operator to error without terminating the stream. This is useful to prevent unexpected edge cases in operators from terminating streams. -
definitions
: An array of operator definitions. -
resolveFrom
: An absolute pathname used to resolve relativeuse
andinclude
operator options. -
shouldWatch
: Whentrue
it causes the streams to restart when one of its dependencies changes.
Implementation Details
- When watching, all stream definitions are re-resolved whenever any definition changes.
- A stream is executed in a separate process. It's vital to keep operator definitions JSON serializable.
createStreamFromPath
🐦 Stability: 2 - Stable (added in 1.0.0)
type Options = {
continueOnError?: boolean;
pathname: string;
shouldWatch?: boolean;
};
function createStreamFromPath(options: Options): Rx.Observable<any>;
Description
Provides an Observable composing one or more streams together. Stream definitions, read from files, are then piped through createStream
. This Observable is the basis for the start
command of @finch/cli
.
Options
-
continueOnError
: Whentrue
it enables an operator to error without terminating the stream. This is useful to prevent unexpected edge cases in operators from terminating streams. See the operators guide for more information. -
pathname
: A filename, dirname, or glob pattern to watch. Must be absolute an path. -
shouldWatch
: Whentrue
it causes a couple handy behaviors.- Streams will restart when their file or a file of one of their dependencies changes.
- New streams will start when watching a any dirname or some glob patterns.
Implementation Details
By design one stream will not affect another stream.
- An error in one stream will not terminate the outer Observable when there is a possibility for multiple streams to be running.
- Restarting one stream will not restart other streams.
- Each stream is run in a separate child process for isolation and multithreading.
EMPTY
🐦 Stability: 2 - Stable (added in 1.0.0)
function EMPTY(): string;
Description
Finch operators selectively return the result of calling this function. The value acts as a sentinel value which signals to the stream that propagation of the value
provided to the operator should terminate at that operator.
This enables operators to act as filters which gracefully reject specific value
values.
The return value of this function should be treated as opaque. Do not base any logic on the return value itself; it's a Finch implementation detail.
localNameOf
🐉 Stability: 1 - Experimental (added in 1.0.0)
function localNameOf(filename: string): string;
Description
This is a utility helper which extracts a standardized and version of a filename in the Finch source tree. The return value is useful for prefixing logging and error messages.
Finch revisions are expected to introduce breaking changes.
toRegExp
🐦 Stability: 2 - Stable (added in 1.0.0)
function toRegExp(pattern: string): RegExp;
Description
This helper converts a serialized regular expression into a true regular expression.
watchFiles
🐦 Stability: 2 - Stable (added in 1.0.0)
type Ready = {
event: "ready";
};
type Watched = {
event: "add" | "change" | "unlink";
filename: string;
present: boolean;
};
type Options = {
filterAdd: boolean;
filterChange: boolean;
filterReady: boolean;
filterUnlink: boolean;
ignoreInitial: boolean;
pathnames: Array<string | glob>;
};
function watchFiles(options: Options): Rx.Observable<Ready | Watched>;
Description
Provides an Observable which yields events when files are added, changed, or removed.
Options
-
pathnames
: Array of actual pathnames or glob patterns to watch. Each member must be absolute an path. -
filterAdd
: YieldsWatched
any time a file is added.Watched
is also yielded as files are initially discovered. ProvideignoreInitial
if you are not interested in add events for exiting files. -
filterChange
: YieldsWatched
any time a file is changed. -
filterUnlink
: YieldsWatched
any time a file is deleted. -
filterReady
: Yields a special{ event: 'ready' }
value once the watcher has completed initialization. This includes yielding all initialadd
events. -
ignoreInitial
:true
by default. Avoid yielding existing files asadd
events when initializing the watcher.
Implementation Details
filterAdd
, filterChange
, and filterUnlink
have intelligent default behavior:
- Opt into receiving all events by configuring none of the above.
- Opt into specific events by configuring any of the options.
-
filterReady
has no affect on values of other filter operators.
Dot files, node_modules
directories, package.json
, and package-lock.json
files are automatically ignored while resolving glob patterns. There is no way to change this behavior.
The watcher uses the FINCH_STABILITY_THRESHOLD
environment value to determine how many milliseconds a filesize must remain stable before considering the file's addition or removal complete.
watchFiles
uses Chokidar extensively.