Package Exports

array-includes-with-glob

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (array-includes-with-glob) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

array-includes-with-glob

like _.includes but with wildcards

Install

npm i array-includes-with-glob

Consume:

// Consume as CommonJS require:
const arrayIncludesWithGlob = require("array-includes-with-glob");
// or tap the original ES Modules source:
import arrayIncludesWithGlob from "array-includes-with-glob";

Here's what you'll get:

Type	Key in `package.json`	Path	Size
Main export - CommonJS version, transpiled to ES5, contains `require` and `module.exports`	`main`	`dist/array-includes-with-glob.cjs.js`	3 KB
ES module build that Webpack/Rollup understands. Untranspiled ES6 code with `import`/`export`.	`module`	`dist/array-includes-with-glob.esm.js`	3 KB
UMD build for browsers, transpiled, minified, containing `iife`'s and has all dependencies baked-in	`browser`	`dist/array-includes-with-glob.umd.js`	2 KB

⬆ back to top

How it works
API
Conditions when this library will throw
Contributing
Licence

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.

⬆ back to top

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
);

⬆ back to top

API - Input

Input argument	Type	Obligatory?	Description
`source`	A string or array of strings	yes	Source string or array of strings
`whatToFind`	A string or array of strings	yes	What to look for. Can contain wildcards. Can be one string or array of strings
`options`	Plain object	no	Options object. See below for its API.

None of the input arguments is mutated.

Options object's key	Value	Default	Description
`{`
`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.
`}`

⬆ back to top

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!

⬆ back to top

Practical usage

I need this library for my other libraries when I'm working with plain objects, and I want to let users whitelist certain keys of those objects. For example, object-merge-advanced can skip the overwrite of any keys upon request. That request technically, is an array, like ['*thing'] in the example below:

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.

⬆ back to top

API - Output

Type	Description
Boolean	Returns `true` if at least one `stringToFind` is found, else `false`.

⬆ back to top

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.

⬆ back to top

Contributing

If you want a new feature in this package or you would like us to change some of its functionality, raise an issue on this repo.
If you tried to use this library but it misbehaves, or you need advice setting it up, and its readme doesn't make sense, just document it and raise an issue on this repo.
If you would like to add or change some features, just fork it, hack away, and file a pull request. We'll do our best to merge it quickly. Prettier is enabled, so you don't need to worry about the code style.

⬆ back to top

Licence

MIT License (MIT)