array-includes-with-glob open source npm package

Installation

Choose the installation type:

Quick Take

Examples

opts.arrayVsArrayAllMustBeFound

Purpose

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)

API — `includesWithGlob()`

The main function includesWithGlob() is imported like this:

It’s a function which takes three input arguments, third-one optional:

Input argument	Type	Obligatory	Description
	`source` Type: A string or array of strings Obligatory: yes
`source`	A string or array of strings	yes	Source string or array of strings

	`whatToFind` Type: A string or array of strings Obligatory: yes
`whatToFind`	A string or array of strings	yes	What to look for. Can contain wildcards. Can be one string or array of strings

	`options` Type: Plain object Obligatory: no
`options`	Plain object	no	Options object. See below for its API.

None of the input arguments will be mutated by this program, we have unit tests to prove that.

The optional options object has the following shape:

Key	Value	Default	Description
	`arrayVsArrayAllMustBeFound` Default: `any`
`arrayVsArrayAllMustBeFound`	`any` or `all`	`any`	When 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.

	`caseSensitive` Default: `true`
`caseSensitive`	boolean	`true`	Passed directly to matcher

The function returns a boolean.

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.

API — `version`

You can import version:

Wildcards

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 its example.

Practical usage

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.

Changelog

Open Changelog

array-includes-with-glob5.0.23