Converting circular structure to json ошибка

The Javascript error “TypeError: Converting circular structure to JSON” happens when you try to stringify a Javascript object that contains a reference to itself. Fix this by either removing the circular reference or by using a 3rd party library to stringify the object.

Javascript comes with a lot of cool built-in stuff. One thing of particular usefulness is the JSON group of functions, specifically JSON.stringify(). It allows you to take almost any Javascript object and turn it into a string representation of itself. That string representation is called JSON, or “Javascript Object Notation”, and is one of the most, if not the most popular data serialization formats in use on the web today.

Unfortunately, however, it can’t do everything. I said “almost” any Javascript object for a reason – if you try to serialize an object that contains a reference to itself, JSON.stringify() will explode. Well, it won’t explode, but it’ll barf out a nasty looking error message for you.

Here’s an example of exactly that:

const foo = {};
foo.bar = "baz";
foo.thing = foo;
console.log(JSON.stringify(foo));

Seems innocent enough, right? All we did was created an object called foo, assigned a member called bar the value of baz, then added another property called thing, and assigned it the value of… foo. You can do that, right? Wrong.

If you try to do this, you’ll get the following verbose (but helpful) error:

/home/user/main.js:5
console.log(JSON.stringify(foo));
                 ^
TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'Object'
    --- property 'thing' closes the circle
    at JSON.stringify (<anonymous>)
    at Object.<anonymous> (/home/user/main.js:5:18)
    at Module._compile (node:internal/modules/cjs/loader:1103:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1157:10)
    at Module.load (node:internal/modules/cjs/loader:981:32)
    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:77:12)
    at node:internal/main/run_main_module:17:47

Woah! What’s all that mean? Well, what it’s complaining about is, the object contains a reference to itself. In programming, this is what’s known as a “circular reference”. It’s called that since, if you were to draw out the dependency tree on paper, it would make a circle. Hence, circular reference. Make sense?

Now, how do we fix this problem? Granted, our example above is contrived and extremely simple. In real life, you’ll probably have no idea where the circular reference is. We’ll get to how to handle that a bit later. But first, let’s look at what to do if you’re reasonably sure you know where the problem is.

Fix 1: remove the circular reference

Again, this one is easy, and is only suited for situations where you know exactly where the problem lies. In our example, the problem is on the highlighted line below:

const foo = {};
foo.bar = "baz";
foo.thing = foo;
console.log(JSON.stringify(foo));

That’s the place where we’re introducing the circular reference. What we’re doing is, we’re assigning the thing property of the foo object a reference to… the foo object. You can see how this would be a problem. The JSON.stringify() method gets to this, and ends up doing infinite recursion. If you remember back to your intro to programming class, this is a problem.

So how do we fix this? I don’t want to blow your mind, but I might have to: we’re going to just not do that. That’s right. We’re just going to not do the thing that is causing the problem. Observe:

const foo = {};
foo.bar = "baz";
console.log(JSON.stringify(foo));
// => {"bar":"baz"}

Ta-da! I know, I know. If it were that simple, you’d have done it already.

Let’s now look at a couple solutions that will be more useful for a more complicated scenario.

Fix 2: use the flatted package

If you’re in a situation where you’re getting the “TypeError: Converting circular structure to JSON” error and you’re not sure where it’s originating, chill out. It’s (current year) and someone has already solved this problem for you. All you have to do is use their solution instead.

The first 3rd party solution we’ll look at is the flatted package. You can install it with the following command:

Once installed, we can add it to our example like so:

const { stringify } = require('flatted');
const foo = {};
foo.bar = "baz";
foo.thing = foo;
console.log(stringify(foo));
// => [{"bar":"1","thing":"0"},"baz"]

What we did here is we imported the stringify function from flatted and used it instead of the JSON.stringify() function. Flatted’s implementation knows how to handle infinite recursion. As you can see, the output is… a little weird. It took the foo object and turned it into an array.

Essentially, this is what’s happening: the first element {"bar":"1", "thing":"0"} is an object that represents the foo object. But, each property is instead the index of the thing it references within the outer array object. This allows for circular references. Since our “thing” property was the offending circular reference, you can see the index it’s referencing is 0, which is the index of the foo object representation. Hence, our circular reference is “flattened” out (or “flatted” if you will).

This output may not work directly with your application, since it’s weird. You’ll have to adjust the code that uses the JSON representation to work with this new format, if you choose to use it.

Fix 3: use the @ungap/structured-clone/json pacakge

Next up we have the npm package @ungap/structured-clone. It’s got a lot of other stuff in there, but the thing we’re interested in is the stringify function located within @ungap/structured-clone/json. We can install it with the following npm command:

npm install @ungap/structured-clone

Once installed, we can import it into our example and use it like this:

const { stringify } = require('@ungap/structured-clone/json');
const foo = {};
foo.bar = "baz";
foo.thing = foo;
console.log(stringify(foo));
// => [[2,[[1,2],[3,0]]],[0,"bar"],[0,"baz"],[0,"thing"]]

Spoiler alert: I have no idea how to make sense of the output. I don’t use this package, so if you want to figure out why it looks like that and how to use it,