{"id":15829,"library":"snapdragon-util","title":"Snapdragon Utilities","description":"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.","status":"active","version":"5.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/here-be/snapdragon-util","tags":["javascript","capture","compile","compiler","convert","match","parse","parser","plugin"],"install":[{"cmd":"npm install snapdragon-util","lang":"bash","label":"npm"},{"cmd":"yarn add snapdragon-util","lang":"bash","label":"yarn"},{"cmd":"pnpm add snapdragon-util","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core functionality of many utilities relies on operating with or producing instances of `snapdragon-node` objects.","package":"snapdragon-node","optional":false}],"imports":[{"note":"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.","wrong":"const util = require('snapdragon-util').default;","symbol":"util","correct":"import util from 'snapdragon-util';"},{"note":"Functions are exposed as properties of the default export object in CommonJS. Direct named ESM imports are not supported without bundling/transpilation.","wrong":"import { isNode } from 'snapdragon-util';","symbol":"isNode","correct":"const util = require('snapdragon-util');\nconst isNode = util.isNode;"},{"note":"Access `append` via the `util` object from the CommonJS `require`. This function was previously named `.emit`.","wrong":"import { append } from 'snapdragon-util';","symbol":"append","correct":"const util = require('snapdragon-util');\nconst append = util.append;"}],"quickstart":{"code":"const util = require('snapdragon-util');\nconst Node = require('snapdragon-node');\n\n// Create a simple AST node\nconst textNode = new Node({ type: 'text', value: 'Hello' });\nconst wildcardNode = new Node({ type: 'star', val: '*' });\n\n// Use isNode to check node type\nconsole.log('Is textNode a Snapdragon Node?', util.isNode(textNode));\nconsole.log('Is a plain object a Snapdragon Node?', util.isNode({}));\n\n// Extract value using the value utility\nconsole.log('Value of textNode:', util.value(textNode));\nconsole.log('Value of wildcardNode:', util.value(wildcardNode));\n\n// Example of using 'append' for a compiler (conceptual)\n// In a real snapdragon compiler, you'd set this as middleware\nconst mockCompiler = { output: '' };\nconst appendGreeting = util.append('Hello World');\n\n// Simulate calling the append middleware with a node and a compiler context\nappendGreeting.call(mockCompiler, { type: 'greeting' });\nconsole.log('Mock compiler output after append:', mockCompiler.output);","lang":"javascript","description":"Demonstrates basic usage of `snapdragon-util` including node identification, value extraction, and conceptual use of the `append` compiler middleware."},"warnings":[{"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.","message":"The `.emit` method was renamed to `.append`. Any code relying on `.emit` will break.","severity":"breaking","affected_versions":"<5.0.0"},{"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`).","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that arguments passed to `snapdragon-util` functions are valid `snapdragon-node` instances, typically created with `new Node(...)` from the `snapdragon-node` package.","message":"Many `snapdragon-util` functions expect instances of `snapdragon-node`. Passing plain JavaScript objects may lead to unexpected behavior or `undefined` returns.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"Attempting to access a utility function as a named ESM import, or `util` itself is `undefined` due to incorrect `require` path.","error":"TypeError: util.isNode is not a function"},{"fix":"Add `const Node = require('snapdragon-node');` at the top of your file before attempting to create `new Node(...)` instances.","cause":"When creating `snapdragon-node` instances to pass to `snapdragon-util` functions, `snapdragon-node` itself has not been imported.","error":"ReferenceError: Node is not defined"}],"ecosystem":"npm"}