vfile-message

Build
Coverage
Downloads
Size

Create vfile messages.

Contents

What is this?

This package provides a (lint) message format.

When should I use this?

In most cases,
you can use file.message from VFile itself,
but in some cases you might not have a file,
and still want to emit warnings or errors,
in which case this can be used directly.

Install

This package is ESM only.
In Node.js (version 16+),
install with npm:

npm install vfile-message

In Deno with esm.sh:

import {VFileMessage} from 'https://esm.sh/vfile-message@4'

In browsers with esm.sh:

<script type="module">
  import {VFileMessage} from 'https://esm.sh/vfile-message@4?bundle'
</script>

Use

import {VFileMessage} from 'vfile-message'

const message = new VFileMessage(
  'Unexpected unknown word `braavo`, did you mean `bravo`?',
  {place: {column: 8, line: 1}, ruleId: 'typo', source: 'spell'}
)

console.log(message)

Yields:

[1:8: Unexpected unknown word `braavo`, did you mean `bravo`?] {
  reason: 'Unexpected unknown word `braavo`, did you mean `bravo`?',
  line: 1,
  column: 8,
  ancestors: undefined,
  cause: undefined,
  fatal: undefined,
  place: {line: 1, column: 8},
  ruleId: 'typo',
  source: 'spell'
}

API

This package exports the identifier VFileMessage.
There is no default export.
It exports the additional TypeScript type Options.

VFileMessage(reason[, options])

Create a message for reason.

🪦 Note: also has obsolete signatures.

Parameters
  • reason (string)
    — reason for message (should use markdown)
  • options (Options, optional)
    — configuration.
Extends

Error.

Returns

Instance of VFileMessage.

Fields
  • ancestors (Array<Node> or undefined)
    — stack of (inclusive) ancestor nodes surrounding the message
  • cause (Error or undefined)
    — original error cause of the message
  • column (number or undefined)
    — starting column of message
  • fatal (boolean or undefined)
    — state of problem; true: error, file not usable; false: warning,
    change may be needed; undefined: info, change likely not needed
  • line (number or undefined)
    — starting line of message
  • place (Point, Position
    or undefined)
    — place of message
  • reason (string)
    — reason for message (should use markdown)
  • ruleId (string or undefined, example: 'my-rule')
    — category of message
  • source (string or undefined, example: 'my-package')
    — namespace of message

Options

Configuration (TypeScript type).

Fields
  • ancestors (Array<Node>, optional)
    — stack of (inclusive) ancestor nodes surrounding the message
  • cause (Error, optional)
    — original error cause of the message
  • place (Point or Position,
    optional)
    — place of message
  • ruleId (string, optional, example: 'my-rule')
    — category of message
  • source (string, optional, , example: 'my-package')
    — namespace of who sent the message

Well-known

It’s OK to store custom data directly on the VFileMessage, some of those are
handled by utilities.
The following fields are documented and typed here.

Fields
  • actual (string, optional)
    — specify the source value that’s being reported, which is deemed incorrect
  • expected (Array<string>, optional)
    — suggest acceptable values that can be used instead of actual
  • url (string, optional)
    — link to docs for the message (this must be an absolute URL that can be
    passed as x to new URL(x))
  • note (string, optional)
    — long form description of the message (you should use markdown)

Compatibility

Projects maintained by the unified collective are compatible with maintained
versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, vfile-message@^4,
compatible with Node.js 16.

Contribute

See contributing.md in vfile/.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

Definitions