legal-markdown-js/dist/core/utils/object-flattener.d.ts

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

/**
 * @fileoverview Object Flattening Utilities for Frontmatter Merge
 *
 * This module provides utilities to flatten hierarchical objects into dot notation
 * and reconstruct them back to nested objects. Used for granular frontmatter merging
 * where individual properties can be compared and merged independently.
 *
 * Features:
 * - Flatten nested objects to dot notation (e.g., {a: {b: 1}} → {"a.b": 1})
 * - Unflatten dot notation back to nested objects
 * - Handle arrays as atomic values
 * - Preserve null/undefined values
 * - Type-safe operations
 *
 * @example
 * ```typescript
 * import { flattenObject, unflattenObject } from './object-flattener';
 *
 * const nested = {
 *   config: {
 *     level: "high",
 *     options: {
 *       debug: true
 *     }
 *   },
 *   items: [1, 2, 3]
 * };
 *
 * const flattened = flattenObject(nested);
 * // {
 * //   "config.level": "high",
 * //   "config.options.debug": true,
 * //   "items": [1, 2, 3]
 * // }
 *
 * const restored = unflattenObject(flattened);
 * // Back to original nested structure
 * ```
 */
/**
 * Converts a hierarchical object to dot notation
 *
 * Recursively traverses object properties and creates flat keys using dot notation.
 * Arrays are treated as atomic values and not flattened.
 *
 * @param obj - Object to flatten
 * @param prefix - Current prefix for nested properties (used internally)
 * @param visited - WeakSet for circular reference detection (used internally)
 * @param startTime - Start timestamp for timeout detection (used internally)
 * @param timeoutMs - Maximum execution time in milliseconds (default: 5000ms)
 * @returns Flattened object with dot notation keys
 * @throws Error if operation times out or circular reference detected
 *
 * @example
 * ```typescript
 * const nested = {
 *   client: {
 *     name: "Acme Corp",
 *     contact: {
 *       email: "contact@acme.com"
 *     }
 *   },
 *   tags: ["legal", "contract"]
 * };
 *
 * const result = flattenObject(nested);
 * // {
 * //   "client.name": "Acme Corp",
 * //   "client.contact.email": "contact@acme.com",
 * //   "tags": ["legal", "contract"]
 * // }
 * ```
 */
export declare function flattenObject(obj: any, prefix?: string, visited?: WeakSet<object>, startTime?: number, timeoutMs?: number): Record<string, any>;
/**
 * Reconstructs a hierarchical object from dot notation
 *
 * Takes a flattened object with dot notation keys and rebuilds the nested structure.
 * Handles type coercion and creates intermediate objects as needed.
 *
 * @param flattened - Flattened object with dot notation keys
 * @returns Reconstructed nested object
 *
 * @example
 * ```typescript
 * const flattened = {
 *   "config.database.host": "localhost",
 *   "config.database.port": 5432,
 *   "config.debug": true,
 *   "items": ["a", "b", "c"]
 * };
 *
 * const result = unflattenObject(flattened);
 * // {
 * //   config: {
 * //     database: {
 * //       host: "localhost",
 * //       port: 5432
 * //     },
 * //     debug: true
 * //   },
 * //   items: ["a", "b", "c"]
 * // }
 * ```
 */
export declare function unflattenObject(flattened: Record<string, any>): any;
/**
 * Validates that flattening and unflattening are reversible
 *
 * Utility function for testing that ensures the flatten/unflatten operations
 * preserve the original object structure (with some limitations for arrays).
 *
 * @param original - Original object to test
 * @returns True if operations are reversible, false otherwise
 *
 * @example
 * ```typescript
 * const obj = { a: { b: { c: 1 } } };
 * console.log(isReversible(obj)); // true
 *
 * const objWithArray = { items: [1, 2, 3], config: { debug: true } };
 * console.log(isReversible(objWithArray)); // true
 * ```
 */
export declare function isReversible(original: any): boolean;
/**
 * Gets all dot notation paths from an object
 *
 * Returns all possible dot notation paths that would be created by flattening,
 * useful for validation and debugging.
 *
 * @param obj - Object to get paths from
 * @returns Array of dot notation paths
 *
 * @example
 * ```typescript
 * const obj = {
 *   user: {
 *     profile: {
 *       name: "John"
 *     },
 *     settings: {
 *       theme: "dark"
 *     }
 *   }
 * };
 *
 * const paths = getObjectPaths(obj);
 * // ["user.profile.name", "user.settings.theme"]
 * ```
 */
export declare function getObjectPaths(obj: any, prefix?: string, timeoutMs?: number): string[];
//# sourceMappingURL=object-flattener.d.ts.map