docs: document native next caveat for lazy proxies

[membphis]

Summary

• call out in README that native next is not proxy-aware on qjson lazy proxies
• add migration-guide guidance for replacing next patterns with qjson.len, qjson.pairs, qjson.ipairs, or qjson.materialize

Testing

• git diff --check
• cargo test --release --no-default-features

Summary by CodeRabbit

Documentation

• Updated README and migration guide with comprehensive guidance on handling table iteration with qjson proxies
• Clarified limitations when using native Lua iteration mechanisms with proxy objects
• Documented recommended alternatives: use qjson.pairs, qjson.ipairs, qjson.len, or qjson.materialize for proper iteration and table operations

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6aff6eea-f9a6-4253-953f-9fd01ff277b9

📥 Commits

Reviewing files that changed from the base of the PR and between cf87fd4 and 4865d30.

📒 Files selected for processing (2)

• README.md
• docs/migrating-from-cjson.md

---

📝 Walkthrough

Walkthrough

This PR adds documentation guidance about a known limitation: Lua's native next(t) function is not proxy-aware for qjson lazy table proxies. The changes direct users to use qjson-provided alternatives (qjson.pairs, qjson.ipairs, qjson.len, or qjson.materialize) when iterating or checking table emptiness.

Changes

Proxy next() limitation documentation

Layer / File(s)	Summary
Proxy next() limitation guidance README.md, docs/migrating-from-cjson.md	README adds a "Native next caveat" section warning that native next() is not proxy-aware and recommending qjson helpers. Migration guide adds an API-mapping row and a dedicated section with before/after examples showing how to replace next-based iteration and emptiness checks with qjson.pairs, qjson.ipairs, and qjson.len.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related issues

• Add qjson.next helper for lazy proxy migration #115: Addresses the same proxy-limitation gap identified in the issue; the migration guide's recommended alternatives (qjson.pairs, qjson.ipairs, qjson.len, qjson.materialize) align with the proposal to improve migration guidance for code relying on native next() iteration patterns.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: documenting the native next caveat for lazy proxies in qjson.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
E2e Test Quality Review	✅ Passed	This is documentation-only (README.md + docs/migrating-from-cjson.md changes). The E2E test quality check does not apply as there are no code, test, or implementation changes to review.
Security Check	✅ Passed	Documentation-only PR (+41 lines in README/migration guide); no code modifications, credential exposure, sensitive logging, or security-relevant logic changes detected across all seven categories.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/next-caveat

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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