vfile-is

library3.0.0jsnpmunverified

vfile-is is a utility package within the unified/vfile ecosystem, designed to facilitate checking properties of `vfile` objects. It allows developers to assert whether a virtual file matches specific criteria, supporting a range of tests including glob patterns against `file.path`, direct string matches against `file.basename` or `file.extname`, custom predicate functions, or object-based comparisons against various `vfile` fields like `stem`, `extname`, or `basename`. The current stable version is 3.0.0, which mandates Node.js 16 or newer and is ESM-only. The package maintains a steady release cadence, often aligning with updates to the core `vfile` library. Its key differentiators include its integration with the `vfile` standard, offering a streamlined API (`is` and `convert`) for robust and composable file testing, which helps in building unified-based tools by providing a consistent way to filter or categorize files.

serialization

npm install vfile-is

github ↗package ↗

INSTALL

IMPORT

SIG · VFILE-IS

vfile-is

serializationjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

✓ import { is } from 'vfile-is'

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

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

convert

✓ import { convert } from 'vfile-is'

✗ import convert from 'vfile-is'

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

VFile

✓ import { VFile } from 'to-vfile'

✗ import { VFile } from '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.

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))

Debug

Known issues

breakingVersion 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.

affects: >=3.0.0

breakingSince 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).

affects: >=2.0.0

breakingVersion 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.

affects: >=3.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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

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

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'`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

vfilerequiredCore object type that vfile-is operates on. Crucial for any practical use of the library.

to-vfileoptionalUsed to create VFile instances from actual files, as demonstrated in the quickstart. Often used alongside vfile-is.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/vfile/vfile-is ↗

packagehttps://www.npmjs.com/package/vfile-is ↗