Unist Generated Node Checker

3.0.0 · active · verified Sun Apr 19

unist-util-generated is a utility within the unified ecosystem designed to determine if a unist node is 'generated.' A generated node is one that did not originate from the source text of the document but was rather programmatically created or modified, lacking explicit positional information. This is particularly useful for tools like linters, which might want to skip generated content to avoid reporting false positives to human authors. The package is currently stable at version 3.0.0 and adheres to a semantic versioning release cadence, with major versions often coinciding with shifts in Node.js compatibility or module system adoption. Its primary differentiator is its focused role in identifying synthetic content within unist trees, complementing other utilities like unist-util-position for retrieving positional data and unist-util-stringify-position for displaying it.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use `require()` to import an ESM-only package.

fix Change `const { generated } = require('unist-util-generated')` to `import { generated } from 'unist-util-generated'`.
```
SyntaxError: Named export 'generated' not found. The requested module 'unist-util-generated' does not provide an export named 'default'
```
cause Attempting to use a default import for a package that only provides named exports.

fix Change `import generated from 'unist-util-generated'` to `import { generated } from 'unist-util-generated'`.
```
TypeError: unist_util_generated_1.generated is not a function
```
cause Incorrect CommonJS-style access (e.g., after `require`) or a bundling issue where the named export is not correctly exposed.

fix Verify that your module system is correctly configured for ESM and that you are using the named import syntax: `import { generated } from 'unist-util-generated'`.

Warnings

breaking Version 3.0.0 updated the minimum required Node.js version to 16. Older Node.js environments will not be supported.
Fix: Ensure your project is running on Node.js 16 or newer. Update your Node.js environment if necessary.
breaking The package transitioned to being ESM-only in v2.0.0, which was reinforced by using `export` maps in v3.0.0. This means `require()` statements will no longer work.
Fix: Migrate your codebase to use ES Modules (ESM) with `import` statements. For example, `import { generated } from 'unist-util-generated'`.
breaking With the adoption of `export` maps in v3.0.0, direct access to private APIs or internal paths within the package is no longer supported and will likely break.
Fix: Always import symbols directly from the main package entry point, e.g., `import { generated } from 'unist-util-generated'`. Avoid referencing internal file paths.
gotcha The `generated` function expects a unist `Node` object. Passing non-object values or objects without a `position` property will lead to unexpected results, typically evaluating as generated.
Fix: Ensure the input `node` conforms to the unist `Node` interface, particularly if you expect a specific `generated` outcome based on its positional data. Nodes without a `position` property are considered generated.

Install

npm install unist-util-generated npm
yarn add unist-util-generated yarn
pnpm add unist-util-generated pnpm

Imports

generated
wrong:
```
const generated = require('unist-util-generated')
```
correct:
```
import { generated } from 'unist-util-generated'
```
The package is ESM-only since v2.0.0. A named import is required as there is no default export.
generated (via dynamic import)
wrong:
```
import generated from 'unist-util-generated'
```
correct:
```
const { generated } = await import('unist-util-generated')
```
While direct `import` statements are preferred at the top level, dynamic imports allow for conditional loading. Remember there is no default export.

Quickstart

This quickstart demonstrates how to use `unist-util-generated` to check if various unist nodes are considered 'generated.' It illustrates that nodes lacking any `position` property, or those with empty `start` and `end` position objects, are flagged as generated, while nodes with valid line/column data are not.

import { generated } from 'unist-util-generated'
import type { Node } from 'unist'

// A completely empty object is considered generated as it lacks positional info.
const node1: Node = {}
console.log('Node 1 (empty object):', generated(node1))

// A node with empty start/end positions is also generated.
const node2: Node = {position: {start: {}, end: {}}}
console.log('Node 2 (empty position):', generated(node2))

// A node with complete positional information is NOT generated.
const node3: Node = {
  position: {start: {line: 1, column: 1}, end: {line: 1, column: 2}}
}
console.log('Node 3 (full position):', generated(node3))

// Example with a typical unist node structure
interface TextNode extends Node {
  type: 'text';
  value: string;
}

const originalTextNode: TextNode = {
  type: 'text',
  value: 'Hello',
  position: {
    start: {line: 1, column: 1, offset: 0},
    end: {line: 1, column: 6, offset: 5}
  }
}
console.log('Original text node:', generated(originalTextNode))

const programmaticallyAddedNode: TextNode = {
  type: 'text',
  value: 'World'
  // No position info, so it's generated
}
console.log('Programmatically added node:', generated(programmaticallyAddedNode))

view raw JSON →