circular-reference 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 derRaab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# circular-reference
+
+Enables `JSON.stringify()` and `JSON.parse()` for JavaScript objects with circular references.
+
+This library provides two methods that handle circular references by injecting or resolving a special string representation (e.g., `<CircularReference path=''>` refers to the root object):
+
+- `stringifyCircularReferences(data:any, clone=false)` replaces all circular references with a string representation of their paths within the structure. If `clone` is `true`, the function operates on a deep copy of data, leaving the original unchanged.
+
+- `parseCircularReferences(data:any, clone=false)` restores circular references based on the encoded paths. If `clone` is `true`, it modifies a deep copy instead of data directly.
+
+
+## Install
+
+`npm install circular-reference` or use your preferred package manager.
+
+## How to use
+
+### Basic example
+
+```js
+import { parseCircularReferences, stringifyCircularReferences } from "circular-reference";
+
+// Object that references itself
+const objectA = {};
+      objectA.ref = objectA;
+
+// Convert the object to a JSON string
+objectA = stringifyCircularReferences(objectA);
+const objectAString = JSON.stringify(objectA);
+console.log(objectAString);
+/* Output: {"ref":"<CircularReference path=''>"} */
+
+// Restore the same structure from the json string
+const objectB = JSON.parse(objectAString);
+objectB = parseCircularReferences(objectB);
+console.log(objectB.ref === objectB); // true
+```
+**Note:** In Node.js, circular references are displayed using `<ref *X>` notation, whereas browsers will still throw a "Converting circular structure to JSON" error if you try to directly `JSON.stringify()` an unresolved circular object.
+
+### Complex example
+
+```js
+import { parseCircularReferences, stringifyCircularReferences } from "circular-reference";
+
+// Two arrays and two objects
+const array1 = [];
+const array2 = [];
+const object1 = {};
+const object2 = {};
+// Each object references all objects and arrays (including itself)
+object1["array1"] = array1;
+object1["array2"] = array2;
+object1["object1"] = object1;
+object1["object2"] = object2;
+object2["array1"] = array1;
+object2["array2"] = array2;
+object2["object1"] = object1;
+object2["object2"] = object2;
+// Each array references all objects and arrays (including itself)
+array1.push(array1);
+array1.push(array2);
+array1.push(object1);
+array1.push(object2);
+array2.push(array1);
+array2.push(array2);
+array2.push(object1);
+array2.push(object2);
+
+// Save the object as a json string
+stringifyCircularReferences(object1);
+const dataString = JSON.stringify(object1, null, 2);
+console.log(dataString);
+/* Output:
+{
+  "array1": [
+    "<CircularReference path='[\"array1\"]'>",
+    [
+      "<CircularReference path='[\"array1\"]'>",
+      "<CircularReference path='[\"array1\"][1]'>",
+      "<CircularReference path=''>",
+      {
+        "array1": "<CircularReference path='[\"array1\"]'>",
+        "array2": "<CircularReference path='[\"array1\"][1]'>",
+        "object1": "<CircularReference path=''>",
+        "object2": "<CircularReference path='[\"array1\"][1][3]'>"
+      }
+    ],
+    "<CircularReference path=''>",
+    "<CircularReference path='[\"array1\"][1][3]'>"
+  ],
+  "array2": "<CircularReference path='[\"array1\"][1]'>",
+  "object1": "<CircularReference path=''>",
+  "object2": "<CircularReference path='[\"array1\"][1][3]'>"
+}
+*/
+
+// Parse the object again
+const data = JSON.parse(dataString);
+// Resolve the circular references
+parseCircularReferences(data);
+
+// Now you have a clone of the original object with the same structure and values
+console.log(data);
+/* Output in Node.js (browser would throw a "Converting circular structure to JSON" error): 
+<ref *3> {
+  array1: <ref *1> [
+    [Circular *1],
+    <ref *2> [
+      [Circular *1],
+      [Circular *2],
+      [Circular *3],
+      [Object]
+    ],
+    [Circular *3],
+    <ref *4> {
+      array1: [Circular *1],
+      array2: [Array],
+      object1: [Circular *3],
+      object2: [Circular *4]
+    }
+  ],
+  array2: <ref *2> [
+    <ref *1> [
+      [Circular *1],
+      [Circular *2],
+      [Circular *3],
+      [Object]
+    ],
+    [Circular *2],
+    [Circular *3],
+    <ref *4> {
+      array1: [Array],
+      array2: [Circular *2],
+      object1: [Circular *3],
+      object2: [Circular *4]
+    }
+  ],
+  object1: [Circular *3],
+  object2: <ref *4> {
+    array1: <ref *1> [
+      [Circular *1],
+      [Array],
+      [Circular *3],
+      [Circular *4]
+    ],
+    array2: <ref *2> [
+      [Array],
+      [Circular *2],
+      [Circular *3],
+      [Circular *4]
+    ],
+    object1: [Circular *3],
+    object2: [Circular *4]
+  }
+}
+```
+

package/dist/index.d.mts

@@ -0,0 +1,5 @@
+declare const parseCircularReferences: (data: Object, clone?: boolean) => void;
+
+declare const stringifyCircularReferences: (data: Object, clone?: boolean) => Object;
+
+export { parseCircularReferences, stringifyCircularReferences };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+declare const parseCircularReferences: (data: Object, clone?: boolean) => void;
+
+declare const stringifyCircularReferences: (data: Object, clone?: boolean) => Object;
+
+export { parseCircularReferences, stringifyCircularReferences };

package/dist/index.js

@@ -0,0 +1,181 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  parseCircularReferences: () => parseCircularReferences,
+  stringifyCircularReferences: () => stringifyCircularReferences
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/path.ts
+var createPathSegmentFromArrayIndex = (index) => {
+  return "[" + index + "]";
+};
+var createPathSegmentFromObjectKey = (key) => {
+  return '["' + key + '"]';
+};
+var joinPath = (pathSegments) => {
+  return pathSegments.join("");
+};
+
+// src/reference.ts
+var PATH_PREFIX = "<CircularReference path='";
+var PATH_SUFFIX = "'>";
+var stringifyReferencePath = (path) => {
+  return PATH_PREFIX + path + PATH_SUFFIX;
+};
+var parseReferencePath = (reference) => {
+  let pathStartIndexOf = reference.indexOf(PATH_PREFIX);
+  if (pathStartIndexOf === -1) {
+    return null;
+  }
+  pathStartIndexOf += PATH_PREFIX.length;
+  const pathEndIndexOf = reference.lastIndexOf(PATH_SUFFIX);
+  if (pathEndIndexOf === -1) {
+    return null;
+  }
+  return reference.substring(pathStartIndexOf, pathEndIndexOf);
+};
+
+// src/parse.ts
+var collectObjectPaths = (parentObj, objPathMap, path) => {
+  if (typeof parentObj !== "object") {
+    return;
+  }
+  objPathMap.set(parentObj, joinPath(path));
+  if (Array.isArray(parentObj)) {
+    for (let i = 0; i < parentObj.length; i++) {
+      collectObjectPaths(parentObj[i], objPathMap, path.concat([createPathSegmentFromArrayIndex(i)]));
+    }
+    return;
+  }
+  for (const key in parentObj) {
+    collectObjectPaths(parentObj[key], objPathMap, path.concat([createPathSegmentFromObjectKey(key)]));
+  }
+};
+var parseRecursion = (parentObj, objReferenceMap, pathObjectMap, path, unresolvedReferences) => {
+  if (typeof parentObj !== "object") {
+    return;
+  }
+  let reference = stringifyReferencePath(joinPath(path));
+  objReferenceMap.set(parentObj, reference);
+  if (Array.isArray(parentObj)) {
+    for (let i = 0; i < parentObj.length; i++) {
+      const childObject = parentObj[i];
+      if (objReferenceMap.has(childObject)) {
+        parentObj[i] = objReferenceMap.get(childObject);
+        continue;
+      }
+      if (typeof childObject === "string") {
+        const path2 = parseReferencePath(childObject);
+        if (path2 !== null) {
+          const referenceObject = pathObjectMap.get(path2);
+          if (referenceObject) {
+            parentObj[i] = referenceObject;
+          } else {
+            unresolvedReferences.push(childObject);
+          }
+        }
+        continue;
+      }
+      parseRecursion(childObject, objReferenceMap, pathObjectMap, path.concat([createPathSegmentFromArrayIndex(i)]), unresolvedReferences);
+    }
+    return;
+  }
+  for (const key in parentObj) {
+    const childObject = parentObj[key];
+    if (objReferenceMap.has(childObject)) {
+      parentObj[key] = objReferenceMap.get(childObject);
+      continue;
+    }
+    if (typeof childObject === "string") {
+      const path2 = parseReferencePath(childObject);
+      if (path2 !== null) {
+        const referenceObject = pathObjectMap.get(path2);
+        if (referenceObject) {
+          parentObj[key] = referenceObject;
+        } else {
+          unresolvedReferences.push(childObject);
+        }
+      }
+      continue;
+    }
+    parseRecursion(childObject, objReferenceMap, pathObjectMap, path.concat([createPathSegmentFromObjectKey(key)]), unresolvedReferences);
+  }
+};
+var parseCircularReferences = (data, clone = false) => {
+  if (clone) {
+    data = structuredClone(data);
+  }
+  let unresolvedReferencesLength = -1;
+  let unresolvedReferences = [];
+  while (unresolvedReferencesLength !== unresolvedReferences.length) {
+    unresolvedReferencesLength = unresolvedReferences.length;
+    unresolvedReferences = [];
+    const objPathMap = /* @__PURE__ */ new Map();
+    collectObjectPaths(data, objPathMap, []);
+    const pathObjectMap = /* @__PURE__ */ new Map();
+    for (const [object, path] of objPathMap) {
+      pathObjectMap.set(path, object);
+    }
+    parseRecursion(data, /* @__PURE__ */ new Map(), pathObjectMap, [], unresolvedReferences);
+  }
+};
+
+// src/stringify.ts
+var stringifyRecursion = (parentObj, objReferenceMap, path) => {
+  if (typeof parentObj !== "object") {
+    return;
+  }
+  let reference = stringifyReferencePath(joinPath(path));
+  objReferenceMap.set(parentObj, reference);
+  if (Array.isArray(parentObj)) {
+    for (let i = 0; i < parentObj.length; i++) {
+      const childObject = parentObj[i];
+      if (objReferenceMap.has(childObject)) {
+        parentObj[i] = objReferenceMap.get(childObject);
+        continue;
+      }
+      stringifyRecursion(childObject, objReferenceMap, path.concat([createPathSegmentFromArrayIndex(i)]));
+    }
+    return;
+  }
+  for (const key in parentObj) {
+    const childObject = parentObj[key];
+    if (objReferenceMap.has(childObject)) {
+      parentObj[key] = objReferenceMap.get(childObject);
+      continue;
+    }
+    stringifyRecursion(childObject, objReferenceMap, path.concat([createPathSegmentFromObjectKey(key)]));
+  }
+};
+var stringifyCircularReferences = (data, clone = false) => {
+  if (clone) {
+    data = structuredClone(data);
+  }
+  stringifyRecursion(data, /* @__PURE__ */ new Map(), []);
+  return data;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseCircularReferences,
+  stringifyCircularReferences
+});

package/dist/index.mjs

@@ -0,0 +1,153 @@
+// src/path.ts
+var createPathSegmentFromArrayIndex = (index) => {
+  return "[" + index + "]";
+};
+var createPathSegmentFromObjectKey = (key) => {
+  return '["' + key + '"]';
+};
+var joinPath = (pathSegments) => {
+  return pathSegments.join("");
+};
+
+// src/reference.ts
+var PATH_PREFIX = "<CircularReference path='";
+var PATH_SUFFIX = "'>";
+var stringifyReferencePath = (path) => {
+  return PATH_PREFIX + path + PATH_SUFFIX;
+};
+var parseReferencePath = (reference) => {
+  let pathStartIndexOf = reference.indexOf(PATH_PREFIX);
+  if (pathStartIndexOf === -1) {
+    return null;
+  }
+  pathStartIndexOf += PATH_PREFIX.length;
+  const pathEndIndexOf = reference.lastIndexOf(PATH_SUFFIX);
+  if (pathEndIndexOf === -1) {
+    return null;
+  }
+  return reference.substring(pathStartIndexOf, pathEndIndexOf);
+};
+
+// src/parse.ts
+var collectObjectPaths = (parentObj, objPathMap, path) => {
+  if (typeof parentObj !== "object") {
+    return;
+  }
+  objPathMap.set(parentObj, joinPath(path));
+  if (Array.isArray(parentObj)) {
+    for (let i = 0; i < parentObj.length; i++) {
+      collectObjectPaths(parentObj[i], objPathMap, path.concat([createPathSegmentFromArrayIndex(i)]));
+    }
+    return;
+  }
+  for (const key in parentObj) {
+    collectObjectPaths(parentObj[key], objPathMap, path.concat([createPathSegmentFromObjectKey(key)]));
+  }
+};
+var parseRecursion = (parentObj, objReferenceMap, pathObjectMap, path, unresolvedReferences) => {
+  if (typeof parentObj !== "object") {
+    return;
+  }
+  let reference = stringifyReferencePath(joinPath(path));
+  objReferenceMap.set(parentObj, reference);
+  if (Array.isArray(parentObj)) {
+    for (let i = 0; i < parentObj.length; i++) {
+      const childObject = parentObj[i];
+      if (objReferenceMap.has(childObject)) {
+        parentObj[i] = objReferenceMap.get(childObject);
+        continue;
+      }
+      if (typeof childObject === "string") {
+        const path2 = parseReferencePath(childObject);
+        if (path2 !== null) {
+          const referenceObject = pathObjectMap.get(path2);
+          if (referenceObject) {
+            parentObj[i] = referenceObject;
+          } else {
+            unresolvedReferences.push(childObject);
+          }
+        }
+        continue;
+      }
+      parseRecursion(childObject, objReferenceMap, pathObjectMap, path.concat([createPathSegmentFromArrayIndex(i)]), unresolvedReferences);
+    }
+    return;
+  }
+  for (const key in parentObj) {
+    const childObject = parentObj[key];
+    if (objReferenceMap.has(childObject)) {
+      parentObj[key] = objReferenceMap.get(childObject);
+      continue;
+    }
+    if (typeof childObject === "string") {
+      const path2 = parseReferencePath(childObject);
+      if (path2 !== null) {
+        const referenceObject = pathObjectMap.get(path2);
+        if (referenceObject) {
+          parentObj[key] = referenceObject;
+        } else {
+          unresolvedReferences.push(childObject);
+        }
+      }
+      continue;
+    }
+    parseRecursion(childObject, objReferenceMap, pathObjectMap, path.concat([createPathSegmentFromObjectKey(key)]), unresolvedReferences);
+  }
+};
+var parseCircularReferences = (data, clone = false) => {
+  if (clone) {
+    data = structuredClone(data);
+  }
+  let unresolvedReferencesLength = -1;
+  let unresolvedReferences = [];
+  while (unresolvedReferencesLength !== unresolvedReferences.length) {
+    unresolvedReferencesLength = unresolvedReferences.length;
+    unresolvedReferences = [];
+    const objPathMap = /* @__PURE__ */ new Map();
+    collectObjectPaths(data, objPathMap, []);
+    const pathObjectMap = /* @__PURE__ */ new Map();
+    for (const [object, path] of objPathMap) {
+      pathObjectMap.set(path, object);
+    }
+    parseRecursion(data, /* @__PURE__ */ new Map(), pathObjectMap, [], unresolvedReferences);
+  }
+};
+
+// src/stringify.ts
+var stringifyRecursion = (parentObj, objReferenceMap, path) => {
+  if (typeof parentObj !== "object") {
+    return;
+  }
+  let reference = stringifyReferencePath(joinPath(path));
+  objReferenceMap.set(parentObj, reference);
+  if (Array.isArray(parentObj)) {
+    for (let i = 0; i < parentObj.length; i++) {
+      const childObject = parentObj[i];
+      if (objReferenceMap.has(childObject)) {
+        parentObj[i] = objReferenceMap.get(childObject);
+        continue;
+      }
+      stringifyRecursion(childObject, objReferenceMap, path.concat([createPathSegmentFromArrayIndex(i)]));
+    }
+    return;
+  }
+  for (const key in parentObj) {
+    const childObject = parentObj[key];
+    if (objReferenceMap.has(childObject)) {
+      parentObj[key] = objReferenceMap.get(childObject);
+      continue;
+    }
+    stringifyRecursion(childObject, objReferenceMap, path.concat([createPathSegmentFromObjectKey(key)]));
+  }
+};
+var stringifyCircularReferences = (data, clone = false) => {
+  if (clone) {
+    data = structuredClone(data);
+  }
+  stringifyRecursion(data, /* @__PURE__ */ new Map(), []);
+  return data;
+};
+export {
+  parseCircularReferences,
+  stringifyCircularReferences
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "circular-reference",
+  "version": "0.1.0",
+  "description": "Tiny util to stringify and parse circular references in objects.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "./dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "example": "ts-node src/examples.ts",
+    "lint": "tsc",
+    "test": "ts-node src/index.test.ts",
+    "release": "npx changeset publish"
+  },
+  "keywords": [
+    "circular",
+    "reference"
+  ],
+  "author": "derRaab",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/derRaab/circular-reference-js"
+  },
+  "devDependencies": {
+    "ts-node": "^10.9.2",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  }
+}