Snapdragon Utilities

5.0.1 · active · verified Tue Apr 21

snapdragon-util provides a focused collection of utility functions designed to interact with the Abstract Syntax Tree (AST) nodes generated or consumed by the `snapdragon` parser/compiler ecosystem. Key functionalities include robust node type checking (`isNode`), efficient value extraction from nodes (`value`), and critical compiler middleware helpers such as `noop` (for ignoring nodes), `identity` (for direct value appending), `append` (for custom value appending), and `toNoop` (for transforming nodes into empty text nodes without re-indexing). The package is currently at version `5.0.1` and is part of a stable, actively maintained ecosystem primarily targeting Node.js environments. Its core differentiation lies in its tight integration with `snapdragon-node` instances, making it indispensable for extending or customizing `snapdragon`-based parsers and compilers.

Common errors

```
TypeError: util.isNode is not a function
```
cause Attempting to access a utility function as a named ESM import, or `util` itself is `undefined` due to incorrect `require` path.

fix Ensure you are using `const util = require('snapdragon-util');` and accessing functions like `util.isNode`. If using ESM, use `import util from 'snapdragon-util';` and then `util.isNode`.
```
ReferenceError: Node is not defined
```
cause When creating `snapdragon-node` instances to pass to `snapdragon-util` functions, `snapdragon-node` itself has not been imported.

fix Add `const Node = require('snapdragon-node');` at the top of your file before attempting to create `new Node(...)` instances.

Warnings

breaking The `.emit` method was renamed to `.append`. Any code relying on `.emit` will break.
Fix: Replace all calls to `util.emit(node, value)` with `util.append(value)(node)` (if it's a curried function) or simply `util.append(node, value)` depending on how `emit` was used. The new `append` returns a curried function for compiler middleware.
gotcha This package is a CommonJS module. Attempting to use named ESM imports (e.g., `import { isNode } from 'snapdragon-util';`) will result in `undefined` for the imported functions or module not found errors in some environments without a transpilation step.
Fix: Use the CommonJS `require` syntax (`const util = require('snapdragon-util');`) or the default ESM import (`import util from 'snapdragon-util';`) and access utilities as properties of the `util` object (e.g., `util.isNode`).
gotcha Many `snapdragon-util` functions expect instances of `snapdragon-node`. Passing plain JavaScript objects may lead to unexpected behavior or `undefined` returns.
Fix: Ensure that arguments passed to `snapdragon-util` functions are valid `snapdragon-node` instances, typically created with `new Node(...)` from the `snapdragon-node` package.

Install

npm install snapdragon-util npm
yarn add snapdragon-util yarn
pnpm add snapdragon-util pnpm

Imports

util
wrong:
```
const util = require('snapdragon-util').default;
```
correct:
```
import util from 'snapdragon-util';
```
While `snapdragon-util` is a CommonJS module, modern Node.js environments allow importing it using `import util from 'snapdragon-util';`. However, the module primarily exposes its functions via `module.exports`, so named imports like `import { isNode } from 'snapdragon-util'` will not work directly without a transpilation step.
isNode
wrong:
```
import { isNode } from 'snapdragon-util';
```
correct:
```
const util = require('snapdragon-util');
const isNode = util.isNode;
```
Functions are exposed as properties of the default export object in CommonJS. Direct named ESM imports are not supported without bundling/transpilation.
append
wrong:
```
import { append } from 'snapdragon-util';
```
correct:
```
const util = require('snapdragon-util');
const append = util.append;
```
Access `append` via the `util` object from the CommonJS `require`. This function was previously named `.emit`.

Quickstart

Demonstrates basic usage of `snapdragon-util` including node identification, value extraction, and conceptual use of the `append` compiler middleware.

const util = require('snapdragon-util');
const Node = require('snapdragon-node');

// Create a simple AST node
const textNode = new Node({ type: 'text', value: 'Hello' });
const wildcardNode = new Node({ type: 'star', val: '*' });

// Use isNode to check node type
console.log('Is textNode a Snapdragon Node?', util.isNode(textNode));
console.log('Is a plain object a Snapdragon Node?', util.isNode({}));

// Extract value using the value utility
console.log('Value of textNode:', util.value(textNode));
console.log('Value of wildcardNode:', util.value(wildcardNode));

// Example of using 'append' for a compiler (conceptual)
// In a real snapdragon compiler, you'd set this as middleware
const mockCompiler = { output: '' };
const appendGreeting = util.append('Hello World');

// Simulate calling the append middleware with a node and a compiler context
appendGreeting.call(mockCompiler, { type: 'greeting' });
console.log('Mock compiler output after append:', mockCompiler.output);

view raw JSON →