@minecraft/creator-tools
Version:
Minecraft Creator Tools command line and libraries.
127 lines (126 loc) • 5.83 kB
TypeScript
/**
* # JsonUtilities - Comment-Preserving JSON Handling
*
* This module provides centralized utilities for parsing and stringifying JSON
* while preserving C-style comments (// and /* *\/).
*
* ## Key Concepts
*
* - Uses the `comment-json` library which stores comments as Symbol properties
* - Comments are attached to the parsed object and survive mutations
* - To preserve comments during round-trip, you must:
* 1. Parse once with `parseJsonWithComments()`
* 2. Mutate the returned object (don't create a new one)
* 3. Stringify with `stringifyJsonWithComments()`
*
* ## Important Limitations
*
* - Array reassignment loses comments - use `commentJson.assign()` or in-place mutations
* - Copying objects with spread/Object.assign loses comment symbols
* - The parsed object must be retained to preserve comments
*
* ## Usage Pattern
*
* ```typescript
* // Parse and cache the result
* const obj = JsonUtilities.parseJsonWithComments(jsonString);
*
* // Modify properties directly on the parsed object
* obj.someProperty = "new value";
*
* // Stringify preserves comments
* const output = JsonUtilities.stringifyJsonWithComments(obj);
* ```
*/
import * as commentJson from "comment-json";
export type { CommentJSONValue, CommentObject, CommentToken } from "comment-json";
export declare const CommentArrayClass: typeof commentJson.CommentArray;
/**
* Parses a JSON string while preserving comments.
* The returned object contains Symbol properties that store comment metadata.
*
* @param jsonString The JSON string to parse (may contain // and /* *\/ comments)
* @param fixContent If true, applies Utilities.fixJsonContentForCommentJson to handle
* trailing commas and other non-standard JSON before parsing
* @returns The parsed object with comment metadata preserved as Symbol properties
*/
export declare function parseJsonWithComments(jsonString: string, fixContent?: boolean): commentJson.CommentJSONValue;
/**
* Stringifies an object to JSON, preserving any comments stored as Symbol properties.
*
* @param value The object to stringify (should be one returned from parseJsonWithComments
* or created with comment-json utilities to have comments)
* @param space Indentation (default: 2 spaces)
* @returns JSON string with comments restored in their original positions
*/
export declare function stringifyJsonWithComments(value: unknown, space?: string | number): string;
/**
* Assigns properties from source to target while preserving comment metadata.
* Use this instead of Object.assign or spread to maintain comments.
*
* @param target The target object to assign properties to
* @param source The source object to copy properties from
* @param keys Optional array of keys to assign. If not provided, all keys are assigned.
* @returns The target object with properties and comments from source
*/
export declare function assignJsonPreservingComments<T, S>(target: T, source: S, keys?: readonly (string | number)[]): T;
/**
* Checks if two JSON strings are semantically equal (same data, ignoring whitespace/formatting).
* This does NOT consider comments - it only compares the actual data values.
*
* @param contentA First JSON string
* @param contentB Second JSON string
* @returns true if the JSON data is semantically equivalent
*/
export declare function jsonContentsSemanticallyEqual(contentA: string, contentB: string): boolean;
/**
* Compares two JSON objects for semantic equality, ignoring comment metadata.
* Use this when you have already-parsed objects and want to check if their
* actual data (not comments) is the same.
*
* @param objA First object (may have comment metadata)
* @param objB Second object (may have comment metadata)
* @returns true if the JSON data is semantically equivalent
*/
export declare function jsonObjectsSemanticallyEqual(objA: unknown, objB: unknown): boolean;
/**
* Merges new values into an existing comment-json object, preserving comments.
* This is the recommended way to update a JSON object while keeping its comments.
*
* @param original The original parsed object with comments
* @param updates An object containing the properties to update
* @returns The original object with updates applied (mutates in place)
*/
export declare function mergeJsonPreservingComments<T extends object>(original: T, updates: Partial<T>): T;
/**
* Creates a deep clone of a comment-json object, preserving comments.
* Use this when you need a copy that retains comment metadata.
*
* @param obj The object to clone
* @returns A new object with the same data and comments
*/
export declare function cloneJsonWithComments<T>(obj: T): T;
/**
* Checks if an object was parsed with comment-json and contains comment metadata.
*
* @param obj The object to check
* @returns true if the object has comment Symbol properties
*/
export declare function hasCommentMetadata(obj: unknown): boolean;
/**
* Default export providing all JsonUtilities functions as a namespace-like object.
* This allows both `import JsonUtilities from "./JsonUtilities"` and
* `import { parseJsonWithComments } from "./JsonUtilities"` usage patterns.
*/
declare const JsonUtilities: {
parseJsonWithComments: typeof parseJsonWithComments;
stringifyJsonWithComments: typeof stringifyJsonWithComments;
assignJsonPreservingComments: typeof assignJsonPreservingComments;
mergeJsonPreservingComments: typeof mergeJsonPreservingComments;
jsonContentsSemanticallyEqual: typeof jsonContentsSemanticallyEqual;
jsonObjectsSemanticallyEqual: typeof jsonObjectsSemanticallyEqual;
cloneJsonWithComments: typeof cloneJsonWithComments;
hasCommentMetadata: typeof hasCommentMetadata;
CommentArrayClass: typeof commentJson.CommentArray;
};
export default JsonUtilities;