Skip to content

Latest commit

 

History

History
399 lines (282 loc) · 12.8 KB

readme.md

File metadata and controls

399 lines (282 loc) · 12.8 KB
Raw

unified-engine

Build Coverage Downloads Sponsors Backers Chat

unified engine to process multiple files, lettings users configure from the file system.

Contents

What is this?

This package is the engine. It’s what you use underneath when you use remark-cli or a language server. Compared to unified, this deals with multiple files, often from the file system, and with configuration files and ignore files.

When should I use this?

You typically use something that wraps this, such as:

You can use this to make such things.

Install

This package is ESM only. In Node.js (version 14.14+, 16.0+, or 18.0+), install with npm:

npm install unified-engine

Use

The following example processes all files in the current directory with a markdown extension with remark, allows configuration from .remarkrc and package.json files, ignoring files from .remarkignore files, and more.

/**
 * @typedef {import('unified-engine').Callback} Callback
 */

import {engine} from 'unified-engine'
import {remark} from 'remark'

engine(
  {
    processor: remark,
    files: ['.'],
    extensions: ['md', 'markdown', 'mkd', 'mkdn', 'mkdown'],
    pluginPrefix: 'remark',
    rcName: '.remarkrc',
    packageField: 'remarkConfig',
    ignoreName: '.remarkignore',
    color: true
  },
  done
)

/** @type {Callback} */
function done(error) {
  if (error) throw error
}

API

This package exports the identifier engine. There is no default export.

engine(options, callback)

Process files according to options and call callback when done.

options
  • processor (Processor) — unified processor to transform files
  • cwd (string or URL, default: process.cwd()) — directory to search files in, load plugins from, and more
  • files (Array<string|URL|VFile>, optional) — paths or globs to files and directories, virtual files, or URLs, to process
  • extensions (Array<string>, optional) — if files matches directories, include files with extensions
  • streamIn (ReadableStream, default: process.stdin) — stream to read from if no files are found or given
  • filePath (string, optional) — file path to process the given file on streamIn as
  • streamOut (WritableStream, default: process.stdout) — stream to write processed files to
  • streamError (WritableStream, default: process.stderr) — stream to write the report (if any) to
  • out (boolean, default: depends) — whether to write the processed file to streamOut
  • output (boolean or string, default: false) — whether to write successfully processed files, and where to
  • alwaysStringify (boolean, default: false) — whether to always serialize successfully processed files
  • tree (boolean, default: false) — whether to treat both input and output as a syntax tree
  • treeIn (boolean, default: tree) — whether to treat input as a syntax tree
  • treeOut (boolean, default: tree) — whether to treat output as a syntax tree
  • inspect (boolean, default: false) — whether to output a formatted syntax tree
  • rcName (string, optional) — wame of configuration files to load
  • packageField (string, optional) — property at which configuration can be found in package.json files
  • detectConfig (boolean, default: whether rcName or packageField is given) — whether to search for configuration files
  • rcPath (string, optional) — filepath to a configuration file to load
  • settings (Object, optional) — configuration for the parser and compiler of the processor
  • ignoreName (string, optional) — name of ignore files to load
  • detectIgnore (boolean, default: whether ignoreName is given) — whether to search for ignore files
  • ignorePath (string, optional) — filepath to an ignore file to load
  • ignorePathResolveFrom ('dir' or 'cwd', default: 'dir') — resolve patterns in ignorePath from the current working directory or the file’s directory
  • ignorePatterns (Array<string>, optional) — patterns to ignore in addition to ignore files, if any
  • ignoreUnconfigured (boolean, default: false) — ignore files that do not have an associated detected configuration file
  • silentlyIgnore (boolean, default: false) — skip given files if they are ignored
  • plugins (Array|Object, optional) — plugins to use
  • pluginPrefix (string, optional) — optional prefix to use when searching for plugins
  • configTransform (Function, optional) — transform config files from a different schema
  • reporter (string or function, default: import {reporter} from 'vfile-reporter') — reporter to use
  • reporterOptions (Object?, optional) — config to pass to the used reporter
  • color (boolean, default: false) — whether to report with ANSI color sequences
  • silent (boolean, default: false) — report only fatal errors
  • quiet (boolean, default: silent) — do not report successful files
  • frail (boolean, default: false) — call back with an unsuccessful (1) code on warnings as well as errors

function callback(error[, code, context])

Called when processing is complete, either with a fatal error if processing went horribly wrong (probably due to incorrect configuration on your part as a developer), or a status code and the processing context.

Parameters
  • error (Error) — fatal error
  • code (number) — either 0 if successful, or 1 if unsuccessful, the latter occurs if fatal errors happen when processing individual files, or if frail is set and warnings occur
  • context (Object) — processing context, containing internally used information and a files array with the processed files

Plugins

doc/plugins.md describes in detail how plugins can add more files to be processed and handle all transformed files.

Configuration

doc/configure.md describes in detail how configuration files work.

Ignoring

doc/ignore.md describes in detail how ignore files work.

Types

This package is fully typed with TypeScript. It additionally exports the following types:

  • VFileReporterOptions — models options passed to vfile reporters
  • VFileReporter — models the signature accepted as a vfile reporter
  • FileSet — models what is passed to plugins as a second parameter
  • Completer — models file set plugins
  • ResolveFrom — models the enum allowed for options.ignorePathResolveFrom
  • ConfigTransform — models the signature of options.configTransform
  • Preset — models a preset, like Preset from unified but accepts strings
  • Options — models configuration
  • Context — models the third parameter to callback
  • Callback — models the signature of callback

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+, 16.0+, and 18.0+. Our projects sometimes work with older versions, but this is not guaranteed.

Security

unified-engine loads and evaluates configuration files, plugins, and presets from the file system (often from node_modules/). That means code that is on your file system runs. Make sure you trust the workspace where you run unified-engine and be careful with packages from npm and changes made by contributors.

Contribute

See contributing.md in unifiedjs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer