{"id":12354,"library":"vfile-is","title":"VFile Property Checker","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/vfile/vfile-is","tags":["javascript","vfile","vfile-util","util","utility","virtual","file","text","processing","typescript"],"install":[{"cmd":"npm install vfile-is","lang":"bash","label":"npm"},{"cmd":"yarn add vfile-is","lang":"bash","label":"yarn"},{"cmd":"pnpm add vfile-is","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core object type that vfile-is operates on. Crucial for any practical use of the library.","package":"vfile","optional":false},{"reason":"Used to create VFile instances from actual files, as demonstrated in the quickstart. Often used alongside vfile-is.","package":"to-vfile","optional":true}],"imports":[{"note":"vfile-is is ESM-only since v2.0.0; CommonJS require statements will result in an ERR_REQUIRE_ESM error.","wrong":"const is = require('vfile-is').is","symbol":"is","correct":"import { is } from 'vfile-is'"},{"note":"There is no default export; 'convert' must be imported as a named export. It returns an assertion function.","wrong":"import convert from 'vfile-is'","symbol":"convert","correct":"import { convert } from 'vfile-is'"},{"note":"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.","wrong":"import { VFile } from 'vfile'","symbol":"VFile","correct":"import { VFile } from 'to-vfile'"}],"quickstart":{"code":"import {VFile} from 'to-vfile'\nimport {is, convert} from 'vfile-is'\n\n// Basic checks for non-VFile inputs\nconsole.log('Is undefined a JS file?', is(undefined, '.js'))\nconsole.log('Is empty object a JS file?', is({}, '.js'))\n\n// Create VFile instances for testing\nconst jsFile = new VFile({path: 'src/index.js', value: 'console.log(\"hello\");'})\nconst mdFile = new VFile({path: 'docs/readme.md', value: '# Readme'})\nconst txtFile = new VFile({basename: 'notes.txt', value: 'Some notes.'})\n\n\n// Checking path and extension\nconsole.log('Is src/index.js a JS file?', is(jsFile, '.js'))\nconsole.log('Is src/index.js an MD file?', is(jsFile, '.md'))\nconsole.log('Does src/index.js match src/index.js?', is(jsFile, 'src/index.js'))\n\n// Checking with globs\nconsole.log('Does src/index.js match *.js?', is(jsFile, '*.js'))\nconsole.log('Does src/index.js match src/*.js?', is(jsFile, 'src/*.js'))\n\n// Checking with object fields\nconsole.log('Does src/index.js have stem \\'index\\'?', is(jsFile, {stem: 'index'}))\nconsole.log('Does readme.md have stem \\'readme\\'?', is(mdFile, {stem: 'readme'}))\nconsole.log('Does notes.txt have extname \\'.txt\\'?', is(txtFile, {extname: '.txt'}))\n\n// Checking with nested object fields (prefix/suffix)\nconsole.log('Does index.js have stem starting with \\'in\\'?', is(jsFile, {stem: {prefix: 'in'}}))\nconsole.log('Does index.js have stem ending with \\'ex\\'?', is(jsFile, {stem: {suffix: 'ex'}}))\n\n// Combining multiple checks in an array (all must pass)\nconsole.log('Is readme.md an MD file AND has stem \\'readme\\'?', is(mdFile, [{extname: '.md'}, {stem: 'readme'}]))\nconsole.log('Is src/index.js a JS file AND in src/ directory?', is(jsFile, ['.js', 'src/*.js']))\n\n// Using convert for reusable assertion functions\nconst isMdReadme = convert([{extname: '.md'}, {stem: 'readme'}])\nconsole.log('Using converted assertion for readme.md:', isMdReadme(mdFile))\nconsole.log('Using converted assertion for index.js:', isMdReadme(jsFile))","lang":"typescript","description":"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()`."},"warnings":[{"fix":"Upgrade your Node.js environment to version 16 or newer. Consider using nvm or volta for easy version management.","message":"Version 3.0.0 and newer requires Node.js 16 or later. Running in older Node.js environments will result in runtime errors.","severity":"breaking","affected_versions":">=3.0.0"},{"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).","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Only use documented public APIs and import paths as specified in the package's official documentation or `exports` field.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Carefully consult the API documentation for the `Check` type to understand the expected behavior for each input format when defining file tests.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `vfile-is` using CommonJS `require()` syntax in a non-ESM context.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/vfile-is/index.js from ... not supported."},{"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.","cause":"The `VFile` class, which is a core dependency type for `vfile-is`, was not imported or is not accessible within the current scope.","error":"ReferenceError: VFile is not defined"},{"fix":"Ensure `is` is imported as a named export: `import { is } from 'vfile-is'`.","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.","error":"TypeError: is is not a function"}],"ecosystem":"npm"}