feat(safeJSONParse): add safe JSON parsing utility

[Yeom-JinHo]

Description

This PR introduces a new safeJSONParse utility that provides a non-throwing wrapper around JSON.parse, complementing the existing isJSON predicate.
The goal is to keep validation and transformation clearly separated while giving consumers a type-safe way to parse JSON strings.

Changes

• Added safeJSONParse<T = unknown>(value: unknown): T | null utility

  • Returns the parsed value when value is a string containing valid JSON
  • Returns null when value is not a string or when parsing fails
  • Mirrors JSON.parse semantics (e.g. "null" → null) while never throwing

• Implemented comprehensive runtime tests for safeJSONParse

  • Covers primitives, objects, arrays, nested structures, empty objects/arrays, and large numbers
  • Verifies failure cases for invalid JSON strings and non-string inputs
  • Ensures "null" input is handled as a valid JSON string whose parsed value is null

• Added type-level tests using expectTypeOf

  • Confirms that the generic parameter T is respected (T | null)
  • Verifies narrowing behavior after null checks
  • Asserts the default generic (T = unknown) when no type argument is provided

• Documented safeJSONParse in a dedicated MDX page

  • Usage examples with valid/invalid JSON strings and non-string inputs
  • Demonstrates generic usage with typed shapes (e.g. User)
  • Shows how to combine safeJSONParse with isJSON for clearer validation + parsing flows

Motivation

• Avoid duplicating try { JSON.parse(...) } catch { ... } patterns across the codebase
• Provide a clear separation of concerns:
  • isJSON(value) → “Is this a valid JSON string?” (pure validation)
  • safeJSONParse(value) → “Safely parse this JSON string into a value” (transformation)
• Improve ergonomics and type safety when dealing with unknown or loosely-typed inputs
• Align JSON-related utilities under a consistent API surface, where predicates live in the predicate category and non-throwing helpers live in the utility category

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
es-toolkit	Ready	Preview	Comment	Nov 14, 2025 0:53am

[vercel]

Deployment failed with the following error:

The provided GitHub repository does not contain the requested branch or commit reference. Please ensure the repository is not empty.

[Copilot]

Pull Request Overview

This PR introduces a new safeJSONParse utility function that provides a non-throwing wrapper around JSON.parse, complementing the existing isJSON predicate by separating validation from transformation concerns.

Key changes:

• Added safeJSONParse<T>(value: unknown): T | null utility that returns parsed JSON or null on failure
• Implemented comprehensive runtime and type-level tests covering edge cases and type inference
• Documented the utility with examples in English, Korean, Japanese, and Chinese

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/util/safeJSONParse.ts	Core implementation with comprehensive JSDoc documentation
src/util/safeJSONParse.spec.ts	Runtime tests for valid/invalid inputs and type-level tests using expectTypeOf
src/util/index.ts	Export statement for the new utility
docs/reference/util/safeJSONParse.md	English documentation with usage examples
docs/ko/reference/util/safeJSONParse.md	Korean translation of documentation
docs/ja/reference/util/safeJSONParse.md	Japanese translation of documentation
docs/zh_hans/reference/util/safeJSONParse.md	Simplified Chinese translation of documentation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.97%. Comparing base (175c8f5) to head (90ac267).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1515   +/-   ##
=======================================
  Coverage   99.97%   99.97%           
=======================================
  Files         468      469    +1     
  Lines        4459     4465    +6     
  Branches     1313     1314    +1     
=======================================
+ Hits         4458     4464    +6     
  Misses          1        1           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Yeom-JinHo]

I’m not fully sure if this is the best name for this helper, so I’m open to renaming if you have a better suggestion 🙌🏽