or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-management.mdindex.mdplugin-system.mdprocessing-pipeline.md
tile.json

tessl/npm-unified

Parse, inspect, transform, and serialize content through syntax trees

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/unified@11.0.x

To install, run

npx @tessl/cli install tessl/npm-unified@11.0.0

index.mddocs/

Unified

Unified is a comprehensive content processing framework that enables developers to parse, inspect, transform, and serialize content through syntax trees using a unified architecture. It serves as the foundation for multiple content processing ecosystems including remark (Markdown), rehype (HTML), and retext (natural language), offering a plugin-based architecture that allows for complex content transformations through a unified interface.

Package Information

  • Package Name: unified
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install unified

Core Imports

import { unified } from "unified";

For CommonJS:

const { unified } = require("unified");

For TypeScript with types:

import { unified } from "unified";
import type { 
  Processor, 
  Plugin, 
  Transformer, 
  Compiler, 
  Parser,
  Data,
  Settings 
} from "unified";

Basic Usage

import { unified } from "unified";

// Create a processor
const processor = unified()
  .use(someParser)      // Configure parser
  .use(someTransformer) // Add transformers
  .use(someCompiler);   // Configure compiler

// Process content (async)
const result = await processor.process("input content");
console.log(String(result)); // Processed output

// Or synchronously
const syncResult = processor.processSync("input content");
console.log(String(syncResult));

Architecture

Unified is built around several key components:

  • Processor: Core processing engine that manages the transformation pipeline
  • Plugin System: Extensible architecture for parsers, transformers, and compilers
  • VFile Integration: Rich file handling with metadata throughout the pipeline
  • Processing Phases: Three-phase pipeline (parse → run → stringify) with precise control
  • Configuration Management: Data and settings management across all plugins
  • Type Safety: Full TypeScript support with extensible interfaces

Capabilities

Core Processing Pipeline

Complete content processing through parse, transform, and stringify phases with both synchronous and asynchronous support.

// Main processor creation
function unified(): Processor;

// Core processing methods
parse<Tree extends Node = Node>(file?: Compatible): Tree;
stringify<Tree extends Node = Node, Result = CompileResults>(
  tree: Tree, 
  file?: Compatible
): Result;
run<HeadTree extends Node = Node, TailTree extends Node = Node>(
  tree: HeadTree, 
  file?: Compatible, 
  done?: RunCallback<TailTree>
): Promise<TailTree>;
runSync<HeadTree extends Node = Node, TailTree extends Node = Node>(
  tree: HeadTree, 
  file?: Compatible
): TailTree;
process<Result = CompileResults>(
  file?: Compatible, 
  done?: ProcessCallback<VFileWithOutput<Result>>
): Promise<VFileWithOutput<Result>>;
processSync<Result = CompileResults>(
  file?: Compatible
): VFileWithOutput<Result>;

Processing Pipeline

Plugin System

Flexible plugin architecture supporting parsers, transformers, compilers, and presets with configuration management.

use(plugin: Plugin, ...parameters: unknown[]): Processor;
use(preset: Preset): Processor;
use(list: PluggableList): Processor;

interface Plugin<Parameters extends Array<unknown> = []> {
  (this: Processor, ...parameters: Parameters): Transformer | void;
}

interface Preset {
  plugins?: PluggableList;
  settings?: Settings;
}

Plugin System

Configuration & Data Management

Processor configuration, data storage, and state management with freezing capabilities.

data(): Data;
data<Key extends keyof Data>(key: Key): Data[Key];
data<Key extends keyof Data>(key: Key, value: Data[Key]): Processor;
data(dataset: Data): Processor;

freeze(): Processor;

// Legacy processor creation (deprecated)
copy(): Processor;

Configuration Management

Types

Core Types

interface Processor<
  ParseTree = Node,
  HeadTree = Node,
  TailTree = Node,
  CompileTree = Node,
  CompileResult = Value
> {
  // Processor methods defined above
}

interface Data {
  settings?: Settings;
  [key: string]: unknown;
}

interface Settings {
  [key: string]: unknown;
}

type Compatible = string | Buffer | VFile | {toString(): string};
type Value = string | Uint8Array;

Callback Types

type ProcessCallback<File extends VFile = VFile> = (
  error?: Error,
  file?: File
) => void;

type RunCallback<Tree extends Node = Node> = (
  error?: Error,
  tree?: Tree,
  file?: VFile
) => void;

type TransformCallback<Output extends Node = Node> = (
  error?: Error,
  tree?: Output,
  file?: VFile
) => void;

Plugin Architecture Types

type Parser<Tree extends Node = Node> = (
  document: string,
  file: VFile
) => Tree;

type Compiler<Tree extends Node = Node, Result = Value> = (
  tree: Tree,
  file: VFile
) => Result;

type Transformer<Input extends Node = Node, Output extends Node = Input> = (
  tree: Input,
  file: VFile,
  next?: TransformCallback<Output>
) => Output | Error | Promise<Output> | void;

Extended Types

type Pluggable = Plugin | PluginTuple | Preset;
type PluggableList = Array<Pluggable>;
type PluginTuple<Parameters extends Array<unknown> = []> = [
  Plugin<Parameters>,
  ...Parameters
];

interface CompileResultMap {
  Uint8Array: Uint8Array;
  string: string;
}

type CompileResults = CompileResultMap[keyof CompileResultMap];

// VFile with result handling
type VFileWithOutput<Result = CompileResults> = VFile & {
  value: Result extends string | Uint8Array ? Result : never;
  result?: Result extends string | Uint8Array ? never : Result;
};

Type Augmentation

Extend unified interfaces for custom compiler results and shared data:

// Augment CompileResultMap for custom results
declare module "unified" {
  interface CompileResultMap {
    ReactNode: ReactNode; // For rehype-react
    CustomResult: CustomType; // Custom compiler result
  }
}

// Augment Data interface for shared plugin data
declare module "unified" {
  interface Data {
    htmlVoidElements?: Array<string>;
    customConfig?: CustomConfigType;
  }
}

// Augment Settings for parser/compiler options
declare module "unified" {
  interface Settings {
    bullet?: "*" | "+" | "-";
    emphasis?: "*" | "_";
    customSetting?: string;
  }
}