Use with Symbol-keyed circular references

[joshkel]

We have a set of JavaScript objects that have circular references and cross-references. We use Symbol keys for these references so that they're skipped by normal object key iteration; that lets them work with code like JSON.stringify.

const Parent = Symbol('parent');
const Owner = Symbol('owner');

const entity = {
  name: 'Entity A',
  children: []
};
entity.children.push({ name: 'Entity A1', [Parent]: entity });
entity.children.push({ name: 'Entity A2',, [Parent]: entity });

const obj = {
  entity,
  items: [
    { name: 'Item for Entity A1', [Owner]: entity.children[0] },
    { name: 'Item for Entity A2', [Owner]: entity.children[1] },
  ]
};

In the past, this use of Symbol keys worked with Immer (because Immer skipped symbol keys), but recent updates to Immer have changed things. I can't complain about this, because this usage is unsupported by Immer, but I'm looking at Mutative as an alternative solution. I have four questions.

First, are circular references generally and officially supported? (Based on #8, it looks like the answer is no, but I didn't see this addressed in the docs.)

Second, are non-unidirectional trees (i.e., trees with more than one path from the root to a tree node) generally supported?

Third, if circular references and non-unidirectional trees aren't generally, officially supported, then are they at least expected to work with non-enumerable (symbol) keys? In my experiments, using Mutative passes my test suite, so the answer is at least "Somewhat yes", but which of the following is it?

a. It's purely by chance that this works. It will likely fail in the future. I should not use Mutative like this.
b. It isn't officially supported, but Mutative's handling of symbol keys is by design and doesn't anticipate changes, so I'm welcome to try it out.
c. Use of symbol keys and non-enumerable keys for non-unidirectional references is fully supported.

Fourth, can the mark feature help here? I admit I'm having a little trouble understanding marking from reading that guide. If I understand correctly, it might help, although I would need to know the object's key (to distinguish between the symbol-keyed cross-references and the "real" objects) as well as the value. Could that be added as an enhancement to Mutative?

Thanks, and sorry for all the questions. I've enjoyed reading about Mutative - very impressive work.

[unadlib]

Hi, thanks a lot for the detailed write-up and the concrete example – this is exactly the kind of context that makes these questions much easier to reason about.

Let me go through your questions one by one.

---

1. Circular references

Mutative conceptually treats the state it manages as a tree / DAG, not as a general object graph with arbitrary cycles. Circular references are not something we aim to support as a feature.

When enableAutoFreeze is turned on, Mutative will in development mode:

• freeze the produced state, and
• run a circular-reference check while traversing the structure.

Important detail for your use case:
the current circular-reference checker only follows “regular” keys (string / number property names in the usual iteration), and does not walk the links stored under your Symbol keys. That means:

• a cycle that is visible via normal keys → will be detected and cause an error in dev;
• a cycle that only exists via symbol-keyed properties → is not detected today.

So from Mutative’s point of view, your state is still “supposed to be” acyclic – it’s just that the dev-time guardrails don’t see the loops encoded purely via symbols yet.

---

2. Non-unidirectional trees (shared nodes / multiple parents)

Having more than one path from the root to the same node without introducing a cycle (i.e. a DAG with shared nodes) is something Mutative handles, but with an important caveat:

Clarification: When the same object is referenced from multiple paths in the base state, Mutative creates independent drafts for each path. This means:

const obj = {};
obj.color1 = obj.color2 = { name: 'Red' };

const result = create(obj, (draft) => {
  draft.color1 === draft.color2;  // false - different drafts!
  draft.color1.name = 'Blue';
  draft.color2.name;  // still 'Red'
});

result.color1 === result.color2;  // false
// { color1: { name: 'Blue' }, color2: { name: 'Red' } }

This behavior is by design and matches Immer's behavior (see Immer's test: "supports a base state with multiple references to an object").

If you need to preserve or create shared references in the result, you can do so explicitly:

const result = create(obj, (draft) => {
  draft.color1.name = 'Blue';
  draft.color2 = draft.color1;  // Explicitly share
});
// Now result.color1 === result.color2  ✅

So:

• Shared nodes in base state: Each path gets its own independent draft. Mutations through one path do not reflect in other paths.
• Manually assigned shared references: ✅ Supported — assigning draft.x = draft.y creates shared references in the result.
• Real cycles: Not supported, and (for normal keys) actively detected in dev when auto-freeze is enabled.

In your example, if we ignore the symbol-keyed links, the structure that Mutative "sees" is a regular tree: obj → entity → children[] and obj → items[]. The extra Parent / Owner links are what turn it into a cyclic graph, but only via symbols.

---

3. Symbol keys, circular references, and how “supported” this is

Mutative does support Symbol-keyed properties by default:

• if you read/write a symbol key on a draft, you’ll see that key/value on the next state as well;
• symbol keys are part of the normal shallow-copy / drafting process, not treated as “out of band” data.

That’s a deliberate design choice – we want Mutative to behave like plain JavaScript objects as much as possible here.

In your particular pattern (back-references stored under Parent / Owner symbols), things currently “work” because of the combination of:

1. Symbol keys are first-class in the drafting / finalization process, so those references are preserved; and
2. The circular-reference checker used by enableAutoFreeze currently doesn’t follow symbol-keyed edges, so cycles that only go through symbol properties are not reported.

Given the three options you listed:

a. Purely by chance, likely to fail in the future.
b. Not officially supported, but Mutative’s handling of symbol keys is by design and not expected to change arbitrarily, so you’re welcome to try it.
c. Symbol keys + non-unidirectional references are fully supported.

The most accurate description is:

(b) – with a big asterisk about circular graphs.

More concretely:

• Using symbol keys themselves is supported and intentional. We don’t plan to suddenly “drop” symbol-keyed properties in future versions.
• Using symbol keys as a way to hide circular references from the circular-reference checker is not something we want to rely on as a public guarantee. We may extend the checker in the future to also follow symbol keys, in which case cycles like the ones in your example would start throwing in dev when enableAutoFreeze is enabled. If we do extend the circular-reference checker to symbol keys as well, that will surface such cycles earlier in development rather than silently allowing them.

So I’d recommend treating your current pattern as:

• “Reasonable and likely to keep working in the short term”,
• but still “use at your own risk” in the sense that we reserve the right to treat symbol-key cycles the same as any other cycles if/when we tighten the circular-reference checks.

If we make that kind of change, it would be clearly called out in the changelog as a behavioral change.

---

4. Can mark help, and could it be key-aware?

mark is designed to let you tell Mutative how to treat certain subtrees during drafting:

• return mutable → Mutative will not draft/freeze that value; you keep the original reference and manage it yourself;
• return immutable (optionally with a custom shallow-copy function) → Mutative treats that as a self-contained immutable node and copies it using your custom logic.

The important bits for your scenario:

• The mark callback currently receives the value (target) and a helpers object ({ mutable, immutable, ... }).
• It does not receive the parent/key/path, so you can’t distinguish “this object when reached via Parent” vs “the same object when reached via a normal field” purely inside mark.

That said, you can still use mark to help:

4.1 Fencing off the “graphy” parts

If you want to clearly separate “tree-like state managed by Mutative” from “graph-like links that you manage yourself”, you can mark certain nodes as mutable based on their shape or markers:

const mark = (target, { mutable }) => {
  if (target && (Parent in target || Owner in target)) {
    // Don’t draft or freeze this object (or anything under it).
    // You’re responsible for managing its graph, including cycles.
    return mutable;
  }
};

Now Mutative will:

• stop recursing at those objects;
• not freeze them even when enableAutoFreeze is on;
• not try to interpret the cycles under them at all.

This doesn’t magically “support” circular references, but it makes the boundary explicit: within the marked region, you fully own the graph semantics.

4.2 Key-aware mark as a potential enhancement

You’re right that in some cases, being able to tell which key we arrived through would make this cleaner – for example, to treat Parent/Owner symbol links differently from the main structural fields.

We don’t currently pass that information into mark, largely to keep the API simple and the traversal fast, but something like:

mark(target, helpers, { parent, key, path })

is a reasonable enhancement to consider. It would let you express policies like “when I see this object under the Parent symbol, treat it as mutable, but elsewhere treat it normally” in a straightforward way.

No promises or timeline here, but your use case is exactly the kind of scenario we’d look at if we add key/path context to mark.

---

TL;DR

• Circular references: not supported; in dev + enableAutoFreeze we detect cycles via normal keys, but cycles that exist only via symbol keys aren’t currently caught.
• Non-unidirectional trees / shared nodes: supported as long as there are no cycles along the paths Mutative sees.
• Symbol keys: first-class citizens; Mutative drafts and copies symbol-keyed properties by default. Using them as “hidden” back-references currently works, but using them to encode circular graphs should still be treated as an implementation detail, not a guaranteed feature.
• mark: can help you fence off graph-like regions (e.g., anything that carries your Parent / Owner symbols) and say “Mutative, don’t manage this part”. A key-aware mark is a plausible future enhancement and your feedback here is very helpful.

And absolutely no need to apologize for the number of questions — this is a great, real-world example, and clarifying these edges makes the library better for everyone.