array-includes-with-glob^5.2.4

No 3rd party dependencies. All dependencies and devDependencies, checked recursively, are Codsen packages.

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• opts.arrayVsArrayAllMustBeFound
• Match glob patterns without matching letter case
• Handle a glob that matches no array items
• Match a glob against a single string

Purpose

Lodash _.includes checks whether an array contains an exact value:

_.includes(["abcd", "aaa", "bbb"], "bc");
// => false

_.includes(["abcd", "aaa", "bbb"], "abcd");
// => true

array-includes-with-glob adds whole-string wildcard patterns:

includesWithGlob(["something", "anything", "zzz"], "some*");
// => true

API — includesWithGlob()

The main function includesWithGlob() is imported like this:

The function takes two operands and an optional options object:

The function returns a Boolean and does not mutate any input. Read-only tuples and frozen arrays are supported.

The optional input object has the following shape:

API — defaults

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

The exported defaults object is frozen. Changing it cannot alter later calls.

API — version

You can import version:

Pattern syntax

Patterns use a small whole-string grammar:

• * matches zero or more Unicode code points, including / and line breaks.
• Consecutive stars are equivalent to one star.
• A backslash escapes the next character. Use \* for a literal asterisk, \\ for a literal backslash, and \! for a literal leading exclamation mark.
• A leading unescaped ! excludes matching source values.
• All other punctuation, including ?, brackets, braces, and regular-expression operators, is literal.

Patterns are anchored to the complete source value:

includesWithGlob(["something", "zzz", "soothing"], "so*ing");
// => true

includesWithGlob(["something"], "thing");
// => false

Matching walks Unicode code points, so a wildcard never consumes half of a surrogate pair.

Pattern arrays and exclusions

Pattern arrays form one cohesive allow/deny list. An exclusion applies before either "any" or "all" accepts a source value:

includesWithGlob(
  ["index.js", "index.test.js", "theme.css"],
  ["*.js", "*.css", "!*.test.js"],
  { arrayVsArrayAllMustBeFound: "all" },
);
// => true

index.js satisfies *.js, theme.css satisfies *.css, and the excluded index.test.js cannot satisfy either positive pattern. A negative-only list matches when at least one source value is not excluded.

Duplicate patterns do not add requirements or repeated comparison work.

Empty and invalid values

An empty string is matchable data. "" matches "", and * also matches "", whether the value is scalar or wrapped in a singleton array. Empty and holes-only pattern arrays match nothing.

Non-string source-array entries and source holes are skipped lazily. Invalid top-level operands, non-string pattern entries, and invalid option values throw package-owned TypeError messages with stable THROW_ID_* identifiers.

See the any and all example for another array comparison.

Practical usage

object-merge-advanced uses this package for its ignoreKeys, hardMergeKeys, and hardArrayConcatKeys selectors:

mergeAdvanced(
  {
    // first object to merge
    something: "a",
    anything: "b",
    everything: "c",
  },
  {
    // second object to merge
    something: ["a"],
    anything: ["b"],
    everything: "d",
  },
  {
    ignoreKeys: ["*thing"],
  },
);

Here, *thing matches all three clashing keys. The merge keeps their values from the first object.

Permalink to changelogChangelog