legal-markdown-js/dist/core/parsers/yaml-parser.d.ts

Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version

/**
 * YAML Front Matter Parser for Legal Markdown Documents
 *
 * This module provides functionality to parse YAML front matter from Legal Markdown
 * documents, extracting metadata and configuration options for document processing.
 * It handles both valid and invalid YAML gracefully, with options for strict error
 * handling when needed.
 *
 * Features:
 * - YAML front matter parsing with js-yaml library
 * - Graceful error handling for malformed YAML
 * - Metadata extraction and validation
 * - Content separation from front matter
 * - YAML serialization utilities
 * - Metadata output configuration extraction
 *
 * @example
 * ```typescript
 * import { parseYamlFrontMatter } from './yaml-parser.js';
 *
 * const content = `---
 * title: Legal Agreement
 * date: 2024-01-01
 * parties:
 *   - name: Company A
 *     role: Provider
 * ---
 * # Agreement Content
 * This is the document content.`;
 *
 * const result = parseYamlFrontMatter(content);
 * console.log(result.metadata.title); // "Legal Agreement"
 * console.log(result.content); // "# Agreement Content\nThis is the document content."
 * ```
 *
 * @module
 */
import { YamlParsingResult } from '../../types/index.js';
import type { YamlValue } from '../../types/index.js';
/**
 * Parses YAML Front Matter from a markdown document
 *
 * Extracts and parses YAML metadata from the beginning of a document,
 * separated by triple dashes (---). The parser handles malformed YAML
 * gracefully unless strict error handling is enabled.
 *
 * @param {string} content - The content of the document to parse
 * @param {boolean} [throwOnError=false] - Whether to throw errors on invalid YAML
 * @returns {YamlParsingResult} Object containing the content without YAML and the parsed metadata
 * @throws {Error} When throwOnError is true and YAML parsing fails
 * @example
 * ```typescript
 * // Basic usage with valid YAML
 * const content = `---
 * title: Contract
 * version: 1.0
 * ---
 * # Contract Content`;
 *
 * const result = parseYamlFrontMatter(content);
 * // result.metadata = { title: "Contract", version: 1.0 }
 * // result.content = "# Contract Content"
 *
 * // Usage with error handling
 * const malformedContent = `---
 * title: Contract
 * invalid: yaml: content
 * ---
 * # Content`;
 *
 * const safeResult = parseYamlFrontMatter(malformedContent, false);
 * // Returns original content with empty metadata
 *
 * const strictResult = parseYamlFrontMatter(malformedContent, true);
 * // Throws Error: "Invalid YAML Front Matter: ..."
 * ```
 */
export declare function parseYamlFrontMatter(content: string, throwOnError?: boolean): YamlParsingResult;
declare function getYamlDepth(value: unknown, currentDepth?: number): number;
/**
 * Serializes metadata to YAML format
 *
 * Converts a JavaScript object to YAML string format using js-yaml library.
 * Handles serialization errors gracefully by returning an empty string and
 * logging the error to the console.
 *
 * @param {Record<string, any>} metadata - The metadata object to serialize
 * @returns {string} YAML string representation of the metadata
 * @example
 * ```typescript
 * const metadata = {
 *   title: "Legal Agreement",
 *   date: "2024-01-01",
 *   parties: [
 *     { name: "Company A", role: "Provider" },
 *     { name: "Company B", role: "Client" }
 *   ]
 * };
 *
 * const yamlString = serializeToYaml(metadata);
 * console.log(yamlString);
 * // Output:
 * // title: Legal Agreement
 * // date: '2024-01-01'
 * // parties:
 * //   - name: Company A
 * //     role: Provider
 * //   - name: Company B
 * //     role: Client
 * ```
 */
export declare function serializeToYaml(metadata: Record<string, YamlValue>): string;
/**
 * Extracts specific metadata output configuration
 *
 * Parses document metadata to extract configuration options for metadata output,
 * including file paths, formats, and inclusion settings. This function looks for
 * specially named metadata fields that control how processed metadata is exported.
 *
 * @param {Record<string, any>} metadata - The document metadata to extract configuration from
 * @returns {Object} Configuration object for metadata output
 * @returns {string} [returns.yamlOutput] - Path for YAML metadata output file
 * @returns {string} [returns.jsonOutput] - Path for JSON metadata output file
 * @returns {string} [returns.outputPath] - General output path for metadata files
 * @returns {boolean} [returns.includeOriginal] - Whether to include original metadata in output
 * @example
 * ```typescript
 * const metadata = {
 *   title: "Contract",
 *   "meta-yaml-output": "contract-metadata.yml",
 *   "meta-json-output": "contract-metadata.json",
 *   "meta-output-path": "./output/",
 *   "meta-include-original": true
 * };
 *
 * const config = extractMetadataOutputConfig(metadata);
 * console.log(config);
 * // Output:
 * // {
 * //   yamlOutput: "contract-metadata.yml",
 * //   jsonOutput: "contract-metadata.json",
 * //   outputPath: "./output/",
 * //   includeOriginal: true
 * // }
 * ```
 */
export declare function extractMetadataOutputConfig(metadata: Record<string, YamlValue>): {
    yamlOutput?: string;
    jsonOutput?: string;
    outputPath?: string;
    includeOriginal?: boolean;
};
/**
 * Processes `@today` references in YAML content before parsing.
 *
 * Replaces `@today` references with properly formatted date strings that are valid YAML.
 * Supports arithmetic operations like `@today+365` or `@today-30` and format specifiers.
 * This prevents YAML parsing errors when `@today` is used in frontmatter.
 *
 * @private
 * @param {string} yamlContent - The raw YAML content containing `@today` references.
 * @returns {string} YAML content with `@today` references replaced by actual dates.
 * @example
 * ```typescript
 * const yamlContent = `
 * title: Document
 * date: "@today"
 * deadline: "@today+365"
 * start_date: "@today-30[long]"
 * `;
 *
 * const processed = processDateReferencesInYaml(yamlContent);
 * // Returns:
 * // title: Document
 * // date: "2024-01-15"
 * // deadline: "2025-01-15"
 * // start_date: "December 16, 2023"
 * ```
 */
declare function processDateReferencesInYaml(yamlContent: string): string;
/**
 * Formats a date for YAML compatibility
 *
 * @private
 * @param {Date} date - The date to format
 * @param {string} format - Format specification
 * @returns {string} Formatted date string
 */
declare function formatDateForYaml(date: Date, format: string): string;
export { getYamlDepth as _getYamlDepth, processDateReferencesInYaml as _processDateReferencesInYaml, formatDateForYaml as _formatDateForYaml, };
//# sourceMappingURL=yaml-parser.d.ts.map