hast-util-whitespace: Inter-Element Whitespace Check

Common errors

• TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for .../hast-util-whitespace/index.ts

  cause Trying to import an ESM-only TypeScript package directly in a CommonJS context or an incorrectly configured Node.js environment.
  fix Ensure your project is configured for ESM by setting `"type": "module"` in your `package.json` or by using `.mjs` file extensions. Also, make sure your Node.js version meets the package requirements (16+ for v3).

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../hast-util-whitespace/index.js from ... not supported.

  cause Attempting to use `require()` to import `hast-util-whitespace`, which is an ESM-only package.
  fix Switch to using `import` statements for `hast-util-whitespace`: `import { whitespace } from 'hast-util-whitespace';`. Ensure your project supports ESM.

• TypeError: The 'thing' argument must be a string or a hast Node

  cause An invalid type (e.g., `null`, `undefined`, a number, or an element node that isn't a `Text` node) was passed to the `whitespace` function.
  fix Verify that the value you are passing to `whitespace` is either a string or a HAST `Text` node. Version 3.0.0 introduced stricter validation.

• SyntaxError: Named export 'whitespace' not found. The requested module 'hast-util-whitespace' does not provide an export named 'whitespace'

  cause This error can occur if you're using an older Node.js version that doesn't fully support the `exports` field in `package.json` correctly or if you're trying to import a non-existent named export.
  fix Ensure you are running Node.js 16+ for `hast-util-whitespace@3`. Also, confirm that you are using the correct named import `{ whitespace }` as there is no default export.

Warnings

• breaking Version 3.0.0 of `hast-util-whitespace` requires Node.js version 16 or higher. Older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js environment to version 16 or newer. If this is not possible, you must remain on `hast-util-whitespace@^2`.
• breaking Version 3.0.0 changed to use the `exports` field in `package.json`, which implies that internal/private APIs should not be accessed directly. Only documented public exports should be used.
  Fix: Ensure you are importing only the public `whitespace` function. Avoid direct imports from subpaths or undocumented files within the package.
• breaking As of version 3.0.0, the `whitespace` function strictly validates its input, only accepting valid HAST `Node` objects (specifically `Text` nodes) or strings. Passing other types will result in a `TypeError`.
  Fix: Ensure that the `thing` argument passed to `whitespace` is either a string or a `hast` Node (typically a `Text` node). Review any code that might pass `null`, `undefined`, or other non-string/non-node values.
• breaking Version 2.0.0 transitioned to being an ESM-only package. It no longer supports CommonJS `require()` syntax.
  Fix: Refactor your codebase to use ECMAScript Modules (ESM) `import` statements. If your project is strictly CommonJS, you must remain on `hast-util-whitespace@^1`.
• gotcha This utility is highly niche, specifically checking for 'inter-element whitespace' as defined by HTML specifications, not general whitespace. Misunderstanding this specific definition can lead to unexpected results when trying to identify all whitespace in an HTML tree.
  Fix: Familiarize yourself with the HTML specification's definition of 'inter-element whitespace' to ensure this utility aligns with your intended use case. For general whitespace checks, you might need custom logic or other utilities.

Install

• npm install hast-util-whitespace npm
• yarn add hast-util-whitespace yarn
• pnpm add hast-util-whitespace pnpm

Imports

• whitespace
  wrong:

  const { whitespace } = require('hast-util-whitespace')

  correct:

  import { whitespace } from 'hast-util-whitespace'

  This package is ESM-only since v2 and has no default export. For v3, Node.js 16+ is required for full compatibility with its `exports` map.

Quickstart

Demonstrates how to use the `whitespace` function to identify inter-element whitespace in both HAST text nodes and raw strings, showcasing various input types.

import { whitespace } from 'hast-util-whitespace';
import type { Text, Element } from 'hast';

// Example 1: An element node is not inter-element whitespace
const elementNode: Element = {
  type: 'element',
  tagName: 'div',
  properties: {},
  children: []
};
console.log('Is elementNode whitespace?', whitespace(elementNode)); // => false

// Example 2: A text node containing only inter-element whitespace characters
const whitespaceTextNode: Text = {
  type: 'text',
  value: '\t  \n'
};
console.log('Is whitespaceTextNode whitespace?', whitespace(whitespaceTextNode)); // => true

// Example 3: A text node containing both whitespace and non-whitespace
const mixedTextNode: Text = {
  type: 'text',
  value: '  text\f'
};
console.log('Is mixedTextNode whitespace?', whitespace(mixedTextNode)); // => false

// Example 4: A string containing only inter-element whitespace characters
console.log('Is "\t  \n" whitespace?', whitespace('\t  \n')); // => true

// Example 5: A string containing non-whitespace characters
console.log('Is "hello" whitespace?', whitespace('hello')); // => false