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.js';
 *
 * 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
 * ```
 */
/**
 * Numeric typed array constructors (Issue #141)
 * These types should be treated as atomic values during flattening/merging
 */
export declare const NUMERIC_TYPED_ARRAY_TYPES: readonly [Int8ArrayConstructor, Uint8ArrayConstructor, Uint8ClampedArrayConstructor, Int16ArrayConstructor, Uint16ArrayConstructor, Int32ArrayConstructor, Uint32ArrayConstructor, Float32ArrayConstructor, Float64ArrayConstructor];
/**
 * Checks if a value is a Buffer instance
 * Handles Node.js Buffer availability check
 *
 * @param value - Value to check
 * @returns True if value is a Buffer instance
 */
export declare function isBuffer(value: unknown): boolean;
/**
 * Checks if a value is a BigInt typed array
 * Handles BigInt typed array availability and TypeScript type compatibility
 *
 * @param value - Value to check
 * @returns True if value is a BigInt typed array
 */
export declare function isBigIntTypedArray(value: unknown): boolean;
/**
 * Checks if a value should be treated as atomic (not flattened)
 *
 * Atomic values include primitives, arrays, and special object types like Date, RegExp,
 * Error, Buffer, and typed arrays. These should not be recursively flattened because
 * they have special semantics that would be lost during flattening.
 *
 * @param value - Value to check
 * @returns True if value should be treated as atomic, false if it should be flattened
 *
 * @example
 * ```typescript
 * isAtomicValue(null);           // true (primitive)
 * isAtomicValue([1, 2, 3]);      // true (array)
 * isAtomicValue(new Date());     // true (special object type)
 * isAtomicValue({ a: 1 });       // false (plain object - should flatten)
 * ```
 */
declare function isAtomicValue(value: unknown): boolean;
/**
 * Converts a hierarchical object to dot notation
 *
 * Recursively traverses object properties and creates flat keys using dot notation.
 * Arrays and special object types (Date, RegExp, Error, Buffer, etc.) 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"],
 *   created: new Date("2025-01-15")
 * };
 *
 * const result = flattenObject(nested);
 * // {
 * //   "client.name": "Acme Corp",
 * //   "client.contact.email": "contact@acme.com",
 * //   "tags": ["legal", "contract"],
 * //   "created": Date object (preserved, not flattened)
 * // }
 * ```
 */
export declare function flattenObject(obj: unknown, prefix?: string, visited?: WeakSet<object>, startTime?: number, timeoutMs?: number): Record<string, unknown>;
/**
 * 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, unknown>): unknown;
/**
 * 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: unknown): 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: unknown, prefix?: string, timeoutMs?: number): string[];
export { isAtomicValue as _isAtomicValue };
//# sourceMappingURL=object-flattener.d.ts.map