fix(internal): improve safeStringify function to handle circular references more effectively

[rallu]

Fixes #960

What is the current behavior?

Very slow processing of safeStringify

What is the new behavior?

On my test processing time reduced from 89000ms to 1ms.

---

Summary by cubic

Improved safeStringify to correctly handle circular references and run dramatically faster. The replacer now tracks the traversal stack and marks cycles as "[Circular]" while respecting toJSON; observed time drops from ~89s to ~1ms.

• Refactors
  • Replaced deep-copy recursion with a stack-based circular check in the replacer.
  • Removed manual object reconstruction; rely on JSON.stringify for traversal.
  • Apply toJSON safely before detecting cycles.

^{Written for commit e67421f. Summary will update on new commits.}

Summary by CodeRabbit

• Bug Fixes

  • Improved serialization to more reliably handle circular and complex data structures.

• Chores

  • Added release metadata for a patch update.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: e67421f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@voltagent/internal	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

📝 Walkthrough

Walkthrough

Reworks the safe-stringify replacer to use an explicit traversal stack tracking this, inline toJSON() handling, and stack-based circular detection returning "[Circular]". Stops cloning/rebuilding objects and returns original values after checks. Adds a patch changeset for the package. No public signatures changed.

Changes

Cohort / File(s)	Summary
Stringify performance & logic packages/internal/src/utils/safe-stringify.ts	Replaced replacer with stack-based traversal tracking this; inlined toJSON() handling with early returns for non-objects; switched circular detection to stack checks (returning "[Circular]") and limited use of seen; removed object-cloning/reconstruction and now returns original values after checks.
Release metadata .changeset/tall-numbers-cheer.md	Added a changeset marking a patch release for @voltagent/internal describing the safeStringify circular-ref handling fix.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I hop through stacks and check each nest,
No copies made — I pass the test.
I sniff a toJSON, I skip the loop,
I flag a circle, then kindly stoop.
Hoppity-hop, the stringify's blessed.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: improving safeStringify to handle circular references more effectively, which is the primary objective of this PR.
Description check	✅ Passed	The description covers key requirements: links the issue (#960), explains current vs new behavior, shows performance improvement, and includes auto-generated summary. All critical sections are present.
Linked Issues check	✅ Passed	The PR successfully addresses the core requirement from #960: improving safeStringify performance and circular reference handling. The stack-based approach replaces inefficient deep recursion, achieving dramatic speedup (89s to 1ms).
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the safeStringify optimization objective: refactoring the replacer logic in safe-stringify.ts and adding a changeset entry. No unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@packages/internal/src/utils/safe-stringify.ts`:
- Around line 46-58: The code calls value.toJSON() then immediately uses value
with stack.includes and seen.add, which throws when toJSON returns a primitive;
update the branch in safeStringify so after calling value = value.toJSON() you
re-check that value is non-null and typeof value === "object" before using
stack.includes or seen.add; i.e., guard both the stack.includes(value) and
seen.add(value) calls (and any circular-reference logic) with the same
object-type check to avoid adding primitives to the WeakSet.

[cubic-dev-ai]

No issues found across 1 file

[omeraplak]

Hey @rallu ,
Thank you so much! I'll release it soon 🔥

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/internal/src/utils/safe-stringify.ts">

<violation number="1" location="packages/internal/src/utils/safe-stringify.ts:47">
P2: Missing post-toJSON object guard allows WeakSet on primitives, throwing in safeStringify.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}