📚 All guides and package documentation.

@finch/core

Finch's tools to create observable streams and operators. This API documentation is intended developers implementing their own services built onto Finch.

🐦 Finch's introduction and getting started guides are intended for everyone.

Installation

npm install -g @finch/core

🐦 Omit -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>;

Implementation | Unit tests

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: When true 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 relative use and include operator options.
• shouldWatch: When true 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>;

Implementation | Unit tests

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: When true 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: When true 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;

Implementation | Unit tests

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;

Implementation | Unit tests

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;

Implementation

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>;

Implementation | Unit tests

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: Yields Watched any time a file is added. Watched is also yielded as files are initially discovered. Provide ignoreInitial if you are not interested in add events for exiting files.
• filterChange: Yields Watched any time a file is changed.
• filterUnlink: Yields Watched any time a file is deleted.
• filterReady: Yields a special { event: 'ready' } value once the watcher has completed initialization. This includes yielding all initial add events.
• ignoreInitial: true by default. Avoid yielding existing files as add 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.

🐦