ast-contains-only-empty-space^4.2.2

No dependencies whatsoever. This package declares no dependencies or devDependencies.

Permalink to InstallationInstallation

Permalink to Quick TakeQuick Take

Permalink to ExamplesExamples

• Non-object values
• Non-plain objects
• Report completion statistics
• Compose progress into a caller's range
• Various

Purpose

This package checks whether a value consists entirely of whitespace strings and empty containers. It is useful for deciding whether a branch of a parsed HTML, CSS, or other abstract syntax tree contains meaningful content.

API — empty()

The main function empty() is imported like this:

The function takes a value and an optional reporting-options object:

The function returns true only when every inspected value is empty according to the rules below. It returns false as soon as it finds meaningful content. It does not mutate the input.

What counts as empty

These values are empty:

• a string for which JavaScript’s trim() returns an empty string;
• an empty array or plain object; and
• an array or plain object whose recursively inspected contents are all empty.

Every other leaf is meaningful and makes the result false. This includes numbers, Booleans, bigints, null, undefined, symbols, functions, boxed primitives, Date, Map, Set, and class instances. A value keeps the same meaning at the root and when nested inside a container.

empty({ nodes: [" \n", { value: "\t" }] });
// => true

empty({ nodes: [" ", { count: 0 }] });
// => false

empty({ value: null });
// => false

Arrays and objects

Arrays are inspected through their own indexed slots. The function never calls the array’s iterator, so replacing, deleting, or poisoning Symbol.iterator does not change the result. A sparse hole is meaningful and returns false; an inherited numeric property does not fill it. Non-index string properties, symbol properties, and non-enumerable extra properties on an array are ignored.

Plain objects contribute their own enumerable string-keyed properties. Symbol-keyed and non-enumerable properties are ignored, but the presence of Symbol.iterator or Symbol.toStringTag metadata does not hide ordinary properties. Null-prototype and cross-realm records are supported.

Traversal is iterative, so deeply nested input does not consume the JavaScript call stack. A cycle is meaningful and returns false. When several paths refer to the same completed array or object, that shared container is inspected only once.

Options

The exported defaults object is frozen. Passing explicit undefined for an option uses its default value.

Progress and completion reports

reportProgressFunc receives the configured start value, sampled monotonic intermediate values for sufficiently large traversals, and the configured end value. Use reportProgressFuncFrom and reportProgressFuncTo when this scan is one stage of a wider operation.

reportCompletionFunc runs once after a valid scan, including an early false result. It receives these frozen statistics:

Reporting is observational. Exceptions thrown by either callback are ignored and cannot change the Boolean result. Clock failures likewise do not affect the result; unavailable elapsed time is reported as 0.

const progress = [];
let completion;

const result = empty([" ", { nested: "\n" }], {
  reportProgressFunc: (percentageDone) => {
    progress.push(percentageDone);
  },
  reportProgressFuncFrom: 20,
  reportProgressFuncTo: 80,
  reportCompletionFunc: (stats) => {
    completion = stats;
  },
});

// result === true
// progress[0] === 20
// progress[progress.length - 1] === 80
// completion.uniqueContainersVisited === 2

Invalid options

The options argument must be a plain object, null, or undefined. Unknown own enumerable string-keyed option properties, invalid callbacks, non-finite range endpoints, a start greater than the end, and an overflowing range span throw a package-owned TypeError or RangeError. Each message starts with ast-contains-only-empty-space/empty(): [THROW_ID_XX].

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.

Types

This TypeScript package exports CompletionStats, InputOpts, and Opts:

import type {
  CompletionStats,
  InputOpts,
  Opts,
} from "ast-contains-only-empty-space";

API — version

You can import version:

Permalink to changelogChangelog