Object Graph Serializer

Build a utility that safely serializes JavaScript objects containing circular references to JSON strings.

Requirements

Your task is to implement a function that serializes JavaScript objects to JSON format, with special handling for circular references. Unlike JSON.stringify() which throws a TypeError when encountering circular references, your implementation should detect and handle them gracefully.

The function should:

• Accept an object as input and return a JSON string
• Detect when an object references itself (directly or indirectly)
• Replace circular references with the string "[Circular]" by default
• Support custom replacement values for circular references

Implementation

@generates

API

/**
 * Serializes a JavaScript object to a JSON string, handling circular references.
 * @param {any} value - The value to serialize
 * @param {string|null} [circularValue] - Optional custom value to use for circular references
 * @returns {string} The JSON string representation
 */
function serialize(value, circularValue) {
  // Implementation here
}

module.exports = { serialize };

Test Cases

Basic circular reference detection

• Given an object with a direct self-reference, the circular property should be replaced with "[Circular]" @test
• Given an object with an indirect circular reference (A -> B -> A), the circular property should be replaced with "[Circular]" @test

Custom circular value

• Given an object with a circular reference and circularValue set to "CYCLE", the circular property should be replaced with "CYCLE" @test
• Given an object with a circular reference and circularValue set to null, the circular property should be replaced with JSON null @test

Dependencies { .dependencies }

safe-stable-stringify { .dependency }

Provides safe JSON serialization with circular reference handling.

@satisfied-by