vfile utility to check if a file passes a test.

• What is this?
• When should I use this?
• Install
• Use
• API
  • convert(check)
  • is(file, check?)
  • Assert
  • Check
  • CheckFields
  • CheckFile
• Types
• Compatibility
• Contribute
• License

This package is a small utility that checks that a file is a certain file.

Use this small utility if you find yourself repeating code for checking files.

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

npm install vfile-is

In Deno with esm.sh:

import {is} from 'https://esm.sh/vfile-is@3'

In browsers with esm.sh:

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

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

is(undefined, '.js') // => false
is({}, '.js') // => false

is(new VFile({path: 'index.js'}), '.js') // => true
is(new VFile({path: 'index.js'}), '.md') // => false
is(new VFile({path: 'index.js'}), 'index.js') // => true
is(new VFile({path: 'index.js'}), 'readme.md') // => false
is(new VFile({path: 'index.js'}), '*.js') // => true
is(new VFile({path: 'index.js'}), '*.md') // => false

is(new VFile({path: 'index.js'}), {stem: 'index'}) // => true
is(new VFile({path: 'index.js'}), {stem: 'readme'}) // => false

is(new VFile({path: 'index.js'}), {stem: {prefix: 'in'}}) // => true
is(new VFile({path: 'index.js'}), {stem: {prefix: 're'}}) // => false
is(new VFile({path: 'index.js'}), {stem: {suffix: 'ex'}}) // => true
is(new VFile({path: 'index.js'}), {stem: {suffix: 'me'}}) // => false

This package exports the identifiers convert and is. There is no default export.

Create an assertion from check.

• check (Check, optional) — check

Assertion (Assert).

Check if file is a specific file.

Converts check to an assertion and calls that assertion with file. If you’re doing a lot of checks, use convert.

• file (unknown) — file to check (typically VFile)
• check (Check, optional) — check

Whether file is a file and matches check (boolean).

Check that a file is a vfile and passes a test (TypeScript type).

• file (unknown) — file to check (typically VFile)

Whether file is a file and matches a bound check (boolean).

Different ways to check for a specific file (TypeScript type).

• if check is a glob string, checks if that glob matches file.path
• if check is a normal string, checks if that is file.basename or file.extname
• if check is a function, checks whether that yields true when called
• if check is a normal object, checks if the given file matches the CheckFields
• if check is an array, all tests in it must pass

type Check =
  | Array<CheckFields | CheckFile | string | null | undefined>
  | CheckFields
  | CheckFile
  | string
  | null
  | undefined

Object describing fields to values (TypeScript type).

Each key is a field in the file and each value is:

• boolean — whether the field exists or not
• object — start (prefix) and/or end (suffix) of the field
• string — exact value of that field

type FieldPartial = {
  prefix?: string | null | undefined
  suffix?: string | null | undefined
}

type CheckFields = Record<
  string,
  FieldPartial | boolean | string | null | undefined
>

Check if a file passes a custom test (TypeScript type).

• file (VFile) — file to check

Whether the test passed for this file (boolean, optional).

This package is fully typed with TypeScript. It exports the additional types Assert, Check, CheckFields, and CheckFile.

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-is@^3, compatible with Node.js 16.

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.

MIT © Titus Wormer