CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-unified

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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;
  }
}
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/unified@11.0.x
Publish Source
CLI
Badge
tessl/npm-unified badge