vfile-message

Create vfile messages.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • VFileMessage(reason[, options])
  • Options
  • Well-known
• Compatibility
• Contribute
• License

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