Neutrino Packing Machine

    unified-engine
    TypeScript icon, indicating that this package has built-in type declarations

    10.1.0 • Public • Published

    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+ 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 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) — name 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+ 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.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

    Install

    npm i unified-engine

    DownloadsWeekly Downloads

    164,400

    Version

    10.1.0

    License

    MIT

    Unpacked Size

    109 kB

    Total Files

    49

    Last publish

    Collaborators

    • wooorm