VFile Property Checker

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/vfile-is/index.js from ... not supported.

  cause Attempting to import `vfile-is` using CommonJS `require()` syntax in a non-ESM context.
  fix Update your import statements to use ES module syntax (e.g., `import { is } from 'vfile-is'`). Ensure your project's `package.json` includes `"type": "module"` if running in Node.js.

• ReferenceError: VFile is not defined

  cause The `VFile` class, which is a core dependency type for `vfile-is`, was not imported or is not accessible within the current scope.
  fix Import `VFile` from `to-vfile` (e.g., `import { VFile } from 'to-vfile'`) or directly from `vfile` if `to-vfile` is not needed for file creation.

• TypeError: is is not a function

  cause The `is` function was imported incorrectly, most commonly as a default import when it is a named export, or incorrectly destructured from a CommonJS `require` call.
  fix Ensure `is` is imported as a named export: `import { is } from 'vfile-is'`.

Warnings

• breaking Version 3.0.0 and newer requires Node.js 16 or later. Running in older Node.js environments will result in runtime errors.
  Fix: Upgrade your Node.js environment to version 16 or newer. Consider using nvm or volta for easy version management.
• breaking Since version 2.0.0, vfile-is is an ESM-only package. Attempting to import it using CommonJS `require()` syntax will result in an `ERR_REQUIRE_ESM` error.
  Fix: Switch to ES module `import` syntax (e.g., `import { is } from 'vfile-is'`). Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extensions).
• breaking Version 3.0.0 introduced an `exports` map in its `package.json`. If you were previously using undocumented or non-standard internal import paths, they might now be inaccessible or have changed.
  Fix: Only use documented public APIs and import paths as specified in the package's official documentation or `exports` field.
• gotcha The `check` parameter in `is()` and `convert()` is highly polymorphic, accepting various types like strings (for path, basename, extname, globs), functions, objects (for field-specific checks), or arrays of these types. Misunderstanding how different input types are interpreted can lead to unexpected filtering or incorrect matches.
  Fix: Carefully consult the API documentation for the `Check` type to understand the expected behavior for each input format when defining file tests.

Install

• npm install vfile-is npm
• yarn add vfile-is yarn
• pnpm add vfile-is pnpm

Imports

• is
  wrong:

  const is = require('vfile-is').is

  correct:

  import { is } from 'vfile-is'

  vfile-is is ESM-only since v2.0.0; CommonJS require statements will result in an ERR_REQUIRE_ESM error.
• convert
  wrong:

  import convert from 'vfile-is'

  correct:

  import { convert } from 'vfile-is'

  There is no default export; 'convert' must be imported as a named export. It returns an assertion function.
• VFile
  wrong:

  import { VFile } from 'vfile'

  correct:

  import { VFile } from 'to-vfile'

  While 'vfile' directly exports VFile, 'to-vfile' is commonly used for creating VFile instances from file paths, as shown in the example, and is often paired with vfile-is.

Quickstart

Demonstrates various ways to check VFile properties using `is()`, including path, extension, globs, object-based field assertions, and how to create reusable assertion functions with `convert()`.

import {VFile} from 'to-vfile'
import {is, convert} from 'vfile-is'

// Basic checks for non-VFile inputs
console.log('Is undefined a JS file?', is(undefined, '.js'))
console.log('Is empty object a JS file?', is({}, '.js'))

// Create VFile instances for testing
const jsFile = new VFile({path: 'src/index.js', value: 'console.log("hello");'})
const mdFile = new VFile({path: 'docs/readme.md', value: '# Readme'})
const txtFile = new VFile({basename: 'notes.txt', value: 'Some notes.'})


// Checking path and extension
console.log('Is src/index.js a JS file?', is(jsFile, '.js'))
console.log('Is src/index.js an MD file?', is(jsFile, '.md'))
console.log('Does src/index.js match src/index.js?', is(jsFile, 'src/index.js'))

// Checking with globs
console.log('Does src/index.js match *.js?', is(jsFile, '*.js'))
console.log('Does src/index.js match src/*.js?', is(jsFile, 'src/*.js'))

// Checking with object fields
console.log('Does src/index.js have stem \'index\'?', is(jsFile, {stem: 'index'}))
console.log('Does readme.md have stem \'readme\'?', is(mdFile, {stem: 'readme'}))
console.log('Does notes.txt have extname \'.txt\'?', is(txtFile, {extname: '.txt'}))

// Checking with nested object fields (prefix/suffix)
console.log('Does index.js have stem starting with \'in\'?', is(jsFile, {stem: {prefix: 'in'}}))
console.log('Does index.js have stem ending with \'ex\'?', is(jsFile, {stem: {suffix: 'ex'}}))

// Combining multiple checks in an array (all must pass)
console.log('Is readme.md an MD file AND has stem \'readme\'?', is(mdFile, [{extname: '.md'}, {stem: 'readme'}]))
console.log('Is src/index.js a JS file AND in src/ directory?', is(jsFile, ['.js', 'src/*.js']))

// Using convert for reusable assertion functions
const isMdReadme = convert([{extname: '.md'}, {stem: 'readme'}])
console.log('Using converted assertion for readme.md:', isMdReadme(mdFile))
console.log('Using converted assertion for index.js:', isMdReadme(jsFile))