datocms-structured-text-utils/dist/esm/inspector.d.ts

A set of Typescript types and helpers to work with DatoCMS Structured Text fields.

import { BlockId, Document, Node } from './types';
/**
 * Represents either a Node/Root or a complete DAST Document.
 * This union type ensures type safety when working with either format.
 *
 * @template BlockItemType - Type of block items (defaults to BlockId string)
 * @template InlineBlockItemType - Type of inline block items (defaults to BlockId string)
 */
declare type StructuredTextDocumentOrNode<BlockItemType = BlockId, InlineBlockItemType = BlockId> = Node<BlockItemType, InlineBlockItemType> | Document<BlockItemType, InlineBlockItemType>;
/**
 * Configuration options for the structured text inspector.
 *
 * @template BlockItemType - Type of block items (defaults to BlockId)
 * @template InlineBlockItemType - Type of inline block items (defaults to BlockId)
 */
export interface InspectOptions<BlockItemType = BlockId, InlineBlockItemType = BlockId> {
    /**
     * Custom formatter for block and inlineBlock nodes.
     *
     * This function receives the raw item value and the suggested maximum line width
     * for the content (considering current indentation). The formatter can return:
     * - String: Always treated as single-line content (newlines will be stripped)
     * - TreeNode: Appended as a child node below the block
     * - TreeNode[]: Multiple child nodes appended below the block
     *
     * @param item - The item value (either ID string or full object)
     * @param maxLineWidth - Suggested maximum line width for content (accounting for indentation)
     * @returns String (single-line), TreeNode, or TreeNode[] representation
     *
     * @example
     * ```typescript
     * // Simple string formatting (single-line)
     * const formatter = (item: string, maxWidth: number) => `ID: ${item}`;
     *
     * // TreeNode formatting for complex structures
     * const formatter = (item: MyBlockType, maxWidth: number) => {
     *   if (typeof item === 'string') return `ID: ${item}`;
     *   return {
     *     label: item.title,
     *     nodes: [
     *       { label: `Type: ${item.type}` },
     *       { label: `ID: ${item.id}` }
     *     ]
     *   };
     * };
     * ```
     */
    blockFormatter?: (item: BlockItemType | InlineBlockItemType, maxLineWidth: number) => string | TreeNode | TreeNode[];
    /**
     * Maximum width for the entire inspect output.
     * @default 80
     */
    maxWidth?: number;
}
/**
 * Inspects and renders a structured text document or node as a tree structure.
 * Skips the root node and returns its children directly.
 *
 * @template BlockItemType - Type of block items (defaults to BlockId)
 * @template InlineBlockItemType - Type of inline block items (defaults to BlockId)
 * @param input - The structured text document or node to inspect
 * @param options - Configuration options for the inspector
 * @returns A TreeNode representation of the structure (without root node)
 *
 * @example
 * ```typescript
 * const tree = inspectionTreeNodes(document, {
 *   blockFormatter: (item) => typeof item === 'string' ? item : item.title
 * });
 * console.log(formatAsTree(tree));
 * ```
 */
export declare function inspectionTreeNodes<BlockItemType = BlockId, InlineBlockItemType = BlockId>(input: StructuredTextDocumentOrNode<BlockItemType, InlineBlockItemType>, options?: InspectOptions<BlockItemType, InlineBlockItemType>): TreeNode;
/**
 * Inspects and formats a structured text document or node as a tree string.
 * This is a convenience function that combines inspectionTreeNodes and formatAsTree.
 *
 * @template BlockItemType - Type of block items (defaults to BlockId)
 * @template InlineBlockItemType - Type of inline block items (defaults to BlockId)
 * @param input - The structured text document or node to inspect
 * @param options - Configuration options for the inspector
 * @returns A formatted tree string representation
 *
 * @example
 * ```typescript
 * const treeString = inspect(document, {
 *   blockFormatter: (item) => typeof item === 'string' ? item : item.title
 * });
 * console.log(treeString);
 * ```
 */
export declare function inspect<BlockItemType = BlockId, InlineBlockItemType = BlockId>(input: StructuredTextDocumentOrNode<BlockItemType, InlineBlockItemType>, options?: InspectOptions<BlockItemType, InlineBlockItemType>): string;
export interface TreeNode {
    label: string;
    nodes?: TreeNode[];
}
export declare function formatAsTree(input: TreeNode | string): string;
export {};