unified-engine

Engine to process multiple files with unified

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
unified-engine
49510.1.09 days ago6 years agoMinified + gzip package size for unified-engine in KB

Readme

unified-engine
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
unified engine to process multiple files, lettings users configure from the file system.

Contents

*   [`engine(options, callback)`](#engineoptions-callback)

What is this?

This package is the engine. It’s what you use underneath when you use remark-cliremark-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:
— create CLIs
— create Gulp plugins
— create language servers
You can use this to make such things.

Install

This package is ESM onlyesm. In Node.js (version 14.14+ or 16.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 configurationconfigure 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 callbackcallback when done.
optionsoptions
— unified processor to transform files
  • cwdcwd (string or URL, default: process.cwd())
— directory to search files in, load plugins from, and more
— paths or globs to files and directories, virtual files, or URLs, to
process
— if `files` matches directories, include files with `extensions`
— stream to read from if no files are found or given
— file path to process the given file on `streamIn` as
— stream to write processed files to
— stream to write the report (if any) to
  • outout (boolean, default: depends)
— whether to write the processed file to `streamOut`
— whether to write successfully processed files, and where to
— whether to always serialize successfully processed files
— whether to treat both input and output as a syntax tree
— whether to treat input as a syntax tree
— whether to treat output as a syntax tree
— whether to output a formatted syntax tree
— name of configuration files to load
— property at which configuration can be found in `package.json` files
`packageField` is given)
— whether to search for configuration files
— filepath to a configuration file to load
— configuration for the parser and compiler of the processor
— name of ignore files to load
is given)
— whether to search for ignore files
— filepath to an ignore file to load
default: `'dir'`)
— resolve patterns in `ignorePath` from the current working directory or the
file’s directory
— patterns to ignore in addition to ignore files, if any
— ignore files that do not have an associated detected configuration file
— skip given files if they are ignored
— plugins to use
— optional prefix to use when searching for plugins
— transform config files from a different schema
`import {reporter} from 'vfile-reporter'`)
— reporter to use
— config to pass to the used reporter
— whether to report with ANSI color sequences
— report only fatal errors
— do not report successful files
— 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`][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.mdplugins describes in detail how plugins can add more files to be processed and handle all transformed files.

Configuration

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

Ignoring

doc/ignore.mdignore 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+ or 16.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.mdcontributing in unifiedjs/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MITlicense © Titus Wormerauthor