feat(smartjson): Implement stableOneWayStringify: deterministic, cycle-safe JSON for hashing/comparisons; update docs and tests

readme.md

@@ -21,9 +21,10 @@ pnpm add @push.rocks/smartjson
 ✨ **Type-Safe JSON Operations** - Full TypeScript support with proper typing  
 🎯 **Class Instance Serialization** - Fold and unfold class instances to/from JSON  
 🔐 **Buffer & Binary Support** - Seamless handling of Buffers and Typed Arrays  
-📊 **JSON Lines Support** - Parse and compare JSONL data streams  
+📊 **JSON Lines Support** - Parse, stringify and compare JSONL data streams  
 🎨 **Pretty Printing** - Beautiful formatted JSON output  
 ⚡ **Stable Stringification** - Consistent key ordering for reliable comparisons  
+♻️ **Circular Reference Handling** - Safe one-way stringify for objects with cycles  
 🔍 **Deep Equality Checks** - Compare complex objects and JSON structures  
 🌐 **Base64 Encoding** - Built-in base64 JSON encoding/decoding  
 
@@ -67,6 +68,40 @@ const prettyJson = smartjson.stringifyPretty({
 });
 ```
 
+### Safe One-Way Stringification (New in v5.1.0)
+
+Handle circular references and unserializable values safely for hashing and comparisons:
+
+```typescript
+// Create objects with circular references
+const objA = { name: 'A' };
+const objB = { name: 'B', ref: objA };
+objA['ref'] = objB; // Circular reference!
+
+// Normal stringify would throw, but stableOneWayStringify handles it
+const safeJson = smartjson.stableOneWayStringify(objA);
+// Circular references are replaced with "__cycle__"
+
+// Perfect for object hashing
+const hash1 = crypto.createHash('sha256')
+  .update(smartjson.stableOneWayStringify(complexObject))
+  .digest('hex');
+
+// Handles unserializable values gracefully
+const objWithGetter = {
+  normal: 'value',
+  get throwing() { throw new Error('Cannot serialize!'); }
+};
+const safe = smartjson.stableOneWayStringify(objWithGetter);
+// Throwing getters are replaced with "__unserializable__"
+
+// Custom key ordering for consistent hashes
+const ordered = smartjson.stableOneWayStringify(
+  { z: 1, a: 2 },
+  ['a', 'z'] // Specify key order
+);
+```
+
 ### Base64 JSON Encoding
 
 Encode JSON data as base64 for safe transmission:
@@ -311,6 +346,7 @@ class AppConfig extends Smartjson {
 
 - `parse(jsonString: string): any` - Parse JSON with automatic buffer handling
 - `stringify(obj: any, simpleOrderArray?: string[], options?: Options): string` - Convert to JSON with stable ordering
+- `stableOneWayStringify(obj: any, simpleOrderArray?: string[], options?: Options): string` - Safe stringify with circular reference handling (one-way, for hashing/comparison)
 - `stringifyPretty(obj: any): string` - Pretty print JSON with 2-space indentation
 - `stringifyBase64(obj: any): string` - Encode JSON as base64
 - `parseBase64(base64String: string): any` - Decode base64 JSON
@@ -336,7 +372,8 @@ class AppConfig extends Smartjson {
 2. **Enable pretty printing** only for debugging (it's slower)
 3. **Cache base64 encodings** when repeatedly sending the same data
 4. **Use JSON Lines** for streaming large datasets
-5. **Avoid circular references** in objects being serialized
+5. **Use stableOneWayStringify** for objects with circular references (for hashing/caching)
+6. **Prefer regular stringify** for round-trip serialization without cycles
 
 ## Migration Guide