or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-unist-builder

Hyperscript interface for creating unist syntax trees with ease

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/unist-builder@4.0.x

To install, run

npx @tessl/cli install tessl/npm-unist-builder@4.0.0

index.mddocs/

Unist Builder

Unist Builder is a utility library that provides a hyperscript interface for creating unist (Universal Syntax Tree) nodes with ease. It offers a simple function u that allows developers to build syntax trees programmatically using a concise, functional API similar to React's createElement or Vue's h function.

Package Information

  • Package Name: unist-builder
  • Package Type: npm
  • Language: JavaScript (with TypeScript support)
  • Installation: npm install unist-builder

Core Imports

import { u } from "unist-builder";

For CommonJS:

const { u } = require("unist-builder");

Basic Usage

import { u } from "unist-builder";

// Create a simple tree structure
const tree = u('root', [
  u('subtree', { id: 1 }),
  u('subtree', { id: 2 }, [
    u('node', [
      u('leaf', 'leaf 1'), 
      u('leaf', 'leaf 2')
    ]),
    u('leaf', { id: 3 }, 'leaf 3'),
    u('void', { id: 4 })
  ])
]);

console.dir(tree, { depth: undefined });

Capabilities

Node Builder Function

The core u function builds unist nodes using a hyperscript-like interface, automatically determining node structure based on parameters.

/**
 * Build a unist node with hyperscript-like syntax
 * @param {string} type - Node type
 * @param {Props | ChildrenOrValue} [props] - Properties or children/value
 * @param {ChildrenOrValue} [value] - Children array or string value
 * @returns {Node} Built unist node
 */
function u(type, props, value);

// Function overloads:
// u(type) → {type: T} (void node)
// u(type, props) → {type: T} & P (node with properties)
// u(type, value) → {type: T, value: string} (literal node)
// u(type, props, value) → {type: T, value: string} & P (literal with props)
// u(type, children) → {type: T, children: C} (parent node)
// u(type, props, children) → {type: T, children: C} & P (parent with props)

Usage Examples:

import { u } from "unist-builder";

// Void node (only type)
const voidNode = u('paragraph');
// Result: { type: 'paragraph' }

// Literal node (with value)
const textNode = u('text', 'Hello world');
// Result: { type: 'text', value: 'Hello world' }

// Parent node (with children)
const parentNode = u('paragraph', [
  u('text', 'Hello '),
  u('emphasis', [u('text', 'world')])
]);
// Result: { type: 'paragraph', children: [...] }

// Node with properties
const nodeWithProps = u('link', { url: 'https://example.com' }, [
  u('text', 'Click here')
]);
// Result: { type: 'link', url: 'https://example.com', children: [...] }

// Literal with properties
const literalWithProps = u('code', { lang: 'javascript' }, 'console.log("hi")');
// Result: { type: 'code', lang: 'javascript', value: 'console.log("hi")' }

Parameter Resolution Logic

The u function automatically determines the intended node structure:

  • Second parameter is string or array: Treated as value (string) or children (array)
  • Second parameter is object: Treated as props (properties)
  • Third parameter (when present): Treated as value (string) or children (array)

Node Types

The function creates different unist node types based on the parameters provided:

  • Void nodes: Nodes with only a type property
  • Literal nodes: Nodes with type and value properties
  • Parent nodes: Nodes with type and children properties
  • Hybrid nodes: Nodes with additional custom properties

Types

/**
 * Union type for node children or value
 * @typedef {Array<Node> | string} ChildrenOrValue
 */

/**
 * Additional properties to assign to nodes
 * @typedef {Record<string, unknown>} Props
 */

/**
 * Base unist node type (from @types/unist)
 * @typedef {Object} Node
 * @property {string} type - Node type
 * @property {string} [value] - Node value (for literal nodes)
 * @property {Array<Node>} [children] - Child nodes (for parent nodes)
 */

TypeScript Support

The package includes full TypeScript support with generic type inference:

import { u } from "unist-builder";
import type { ChildrenOrValue, Props } from "unist-builder";

// Type-safe node creation with inference
const typedNode = u('paragraph', [
  u('text', 'Hello'),
  u('emphasis', [u('text', 'world')])
]);

// Custom properties with type safety
interface LinkProps extends Props {
  url: string;
  title?: string;
}

const linkNode = u('link', { url: 'https://example.com' } as LinkProps, [
  u('text', 'Example Link')
]);