array-pull-all-with-glob^7.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

• Match removal patterns without regard to letter case
• Remove values that match any of several patterns
• Remove every value with the catch-all glob
• Pass one removal pattern as a string

Purpose

array-pull-all-with-glob returns a new array without strings that match the supplied removal patterns. Patterns match complete strings, and * is the wildcard operator.

Use it when exact removal is not enough. For example, email-comb uses this package when it applies CSS class and ID whitelists.

The package does not mutate the source array or the pattern array. It preserves the order and duplicates of every retained string.

API — pull()

The main function pull() is imported like this:

interface Opts {
  caseSensitive: boolean;
}

declare function pull(
  strArr: readonly string[],
  toBeRemoved: string | readonly string[],
  opts?: Partial<Opts> | null,
): string[];

pull() returns a new mutable string[]. A no-match result and an empty-source result are also fresh arrays.

Values are removed when any supplied pattern predicate returns true. The function does not deduplicate retained values:

import { strict as assert } from "node:assert";

import { pull } from "array-pull-all-with-glob";

const source = Object.freeze(["keep", "temp-1", "keep", "temp-2"]);
const patterns = Object.freeze(["temp-*"]);
const result = pull(source, patterns);

assert.deepEqual(result, ["keep", "keep"]);
assert.deepEqual(source, ["keep", "temp-1", "keep", "temp-2"]);
assert.notEqual(result, source);

Removal-pattern grammar

Patterns use a small whole-string wildcard grammar:

• * matches zero or more Unicode code points. It can cross directory separators and line breaks. Consecutive stars such as ** and *** behave like one star.
• A backslash escapes the following character. Use \* in the pattern to match a literal asterisk and \\ to match a literal backslash.
• A leading ! negates that one pattern predicate. Escape it as \! when the source string begins with a literal exclamation mark.
• Every other character is literal. Question marks, brackets, braces, and constructs such as @(one|two) have no special pattern meaning.

Patterns are anchored to the complete string. A wildcard also crosses / and newline characters:

import { strict as assert } from "node:assert";

import { pull } from "array-pull-all-with-glob";

assert.deepEqual(
  pull(["src/main.js", "src/nested/main.js", "src/main.ts"], "src/*.js"),
  ["src/main.ts"],
);

assert.deepEqual(pull(["top\nbottom", "top-middle-bottom"], "top*bottom"), []);

Escape literal pattern characters

JavaScript string syntax also uses backslashes. String.raw makes the intended pattern easier to read:

import { strict as assert } from "node:assert";

import { pull } from "array-pull-all-with-glob";

assert.deepEqual(
  pull(["file*", "file-1"], String.raw`file\*`),
  ["file-1"],
);

assert.deepEqual(
  pull(["!draft", "draft"], String.raw`\!draft`),
  ["draft"],
);

Combine multiple patterns

Each pattern is evaluated separately, and matching any predicate removes the source value. Pattern arrays therefore use scalar OR semantics.

A negative pattern is not a veto that protects values matched by a positive pattern. For example, the following list removes every value:

import { strict as assert } from "node:assert";

import { pull } from "array-pull-all-with-glob";

assert.deepEqual(
  pull(["keep.js", "main.js", "notes.txt"], ["*.js", "!keep.js"]),
  [],
);

*.js removes both JavaScript filenames. The scalar pattern !keep.js returns true for every value other than keep.js, so it also removes notes.txt.

To express include-and-exclude filesystem glob rules, use a filesystem glob library before calling pull() or construct the final removal list explicitly.

Case sensitivity

Matching is case-sensitive by default:

Omitting caseSensitive, setting it to undefined, passing an empty options object, or passing null as opts retains the true default. Only an explicit false enables case-insensitive matching.

Case-insensitive matching uses one-code-point uppercase comparisons. It is not locale-aware and does not apply multi-code-point or astral case folding. For example, Ä matches ä, but ß does not match SS:

import { strict as assert } from "node:assert";

import { pull } from "array-pull-all-with-glob";

assert.deepEqual(
  pull(["Ärger", "ß", "notes.txt"], ["ärger", "SS"], {
    caseSensitive: false,
  }),
  ["ß", "notes.txt"],
);

Here are all defaults in one place for copying:

Readonly TypeScript inputs

Readonly inputs do not require casts. The return type remains mutable:

import { pull } from "array-pull-all-with-glob";

const source = ["keep", "remove"] as const;
const patterns = ["remove"] as const;

const result = pull(source, patterns, null);
// result: string[]

result.push("another value");

The function has no separate runtime validation layer. Pass values that satisfy the declared string-array contract; values outside that contract can raise ordinary JavaScript errors.

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:

Permalink to changelogChangelog