§ Quick Take

import { strict as assert } from "assert";
import includesWithGlob from "array-includes-with-glob";

assert.equal(
  includesWithGlob(["xc", "yc", "zc"], "*c"),
  true
);
// (all 3)

assert.equal(
  includesWithGlob(["xc", "yc", "zc"], "*a"),
  false
);
// (none found)

assert.equal(
  includesWithGlob(
    ["something", "anything", "zzz"],
    "some*"
  ),
  true
);
// (1 hit)

§ How it works

Lodash _.includes can tell, does an array contain given string among its elements:

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

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

This library is a supercharged version of the Lodash _.includes, letting you to put wildcards:

includesWithGlob(["xc", "yc", "zc"], "*c");
// => true (all 3)

includesWithGlob(["xc", "yc", "zc"], "*a");
// => false (none found)

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

Wildcard means zero or more Unicode characters.

You can also do fancy things like a wildcard in the middle of a string, or multiple wildcards in a string:

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

This library will tolerate non-string values in the source array; it will skip those values.

This library is astral-character friendly, supports all Unicode characters (including emoji) and doesn't mutate the input.

You can also query multiple values and request that ANY (default behaviour) or ALL (optional setting) should be found in the source, to yield a result "true". See examples below.

§ API

includesWithGlob(
source, // input - an array of strings or a single string
whatToFind, // what to look for - can contain wildcards, "*"'s, can be array of strings or a single string
options
);

§ API - Input

Input argumentTypeObligatory?Description
sourceA string or array of stringsyesSource string or array of strings
whatToFindA string or array of stringsyesWhat to look for. Can contain wildcards. Can be one string or array of strings
optionsPlain objectnoOptions object. See below for its API.

None of the input arguments is mutated.

Options object's keyValueDefaultDescription
arrayVsArrayAllMustBeFoundany or allanyWhen a source (the first argument) is array, and what to look for (the second argument) is also array, you can have the match performed two ways: any setting will return true if any of the second argument array's elements are found in the source array. all setting will return true only if all elements within the second argument are found within the source array.

§ Options object examples

var arrayIncludesWithGlob = require("array-includes-with-glob");
var source = ["aaa", "bbb", "ccc"];
var whatToLookFor = ["a*", "d*"];

var res1 = arrayIncludesWithGlob(source, whatToLookFor);
console.log("res1 = " + res1);
// => res1 = true, because at one element, 'a*' was found in source (it was its first element)

var res2 = arrayIncludesWithGlob(source, whatToLookFor, {
arrayVsArrayAllMustBeFound: "all",
});
console.log("res2 = " + res2);
// => res2 = false, because not all elements were found in source: 'd*' was not present in source!

§ Practical usage

It's very useful tackling options' objects — for example, object-merge-advanced can skip certain keys upon request. That request, technically, is an array, it may or may not contain globs, and this program processes all that:

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

In the example above, we need to run a check through all keys of the first object and check, are any covered by the ignoreKeys array. If so, those keys would not get merged and keep their values.

§ API - Output

TypeDescription
BooleanReturns true if at least one stringToFind is found, else false.

§ Conditions when this library will throw

This library will throw an error if:

  • any of inputs are missing
  • any of inputs are of the wrong type

Also, if first input argument, a source array, is an empty array or empty string, the result will always be false.

§ Licence

MIT opens in a new tab

Copyright © 2010–2020 Roy Revelt and other contributors

Related packages:

📦 array-of-arrays-into-ast 1.9.50
turns an array of arrays of data into a nested tree of plain objects
📦 array-pull-all-with-glob 4.12.72
pullAllWithGlob - like _.pullAll but pulling stronger, with globs
📦 array-of-arrays-sort-by-col 2.12.13
sort array of arrays by column, rippling the sorting outwards from that column
📦 array-group-str-omit-num-char 2.1.48
Groups array of strings by omitting number characters
📦 arrayiffy-if-string 3.11.38
Put non-empty strings into arrays, turn empty-ones into empty arrays. Bypass everything else.