feat(safeJSONParse): add safe JSON parsing utility

docs/ja/reference/util/safeJSONParse.md

@@ -0,0 +1,177 @@
+# safeJSONParse
+
+エラーをスローせずに JSON 文字列を安全にパースします。
+
+```typescript
+const result = safeJSONParse(value);
+```
+
+## 使用法
+
+### `safeJSONParse(value)`
+
+JSON 文字列を安全にパースしたい場合に `safeJSONParse` を使用してください。`JSON.parse` 例外を発生させるリスクなくパースできます。値が有効な JSON を含む文字列の場合、パースされた結果を返します。そうでない場合、`safeJSONParse` は `null` を返します。
+
+ユーザー入力、緩く型付けされたデータ、または値が常に有効な JSON 文字列であるという保証がない信頼できないソースを扱う際に特に便利です。
+
+```typescript
+import { safeJSONParse } from 'es-toolkit/util';
+
+// 有効な JSON 文字列
+safeJSONParse('{"name":"JinHo","age":29}'); // { name: "JinHo", age: 29 }
+safeJSONParse('[1, 2, 3]'); // [1, 2, 3]
+safeJSONParse('"hello world"'); // "hello world"
+safeJSONParse('42'); // 42
+safeJSONParse('true'); // true
+safeJSONParse('false'); // false
+safeJSONParse('null'); // null (有効な JSON ですが、パースされた値が null)
+
+// 無効な JSON 文字列
+safeJSONParse('invalid json'); // null
+safeJSONParse('{"unclosed": "object"'); // null
+safeJSONParse('[1,2,'); // null
+safeJSONParse('undefined'); // null
+safeJSONParse(''); // null
+
+// 文字列でない値
+safeJSONParse({ name: 'JinHo' }); // null
+safeJSONParse([1, 2, 3]); // null
+safeJSONParse(42); // null
+safeJSONParse(true); // null
+safeJSONParse(null); // null
+safeJSONParse(undefined); // null
+```
+
+### ジェネリックを使用した型安全なパース
+
+ジェネリックパラメータ `T` を使用して、パースされた JSON 値の期待される形状を記述できます:
+
+```typescript
+import { safeJSONParse } from 'es-toolkit/util';
+
+type User = {
+  id: number;
+  name: string;
+  isAdmin: boolean;
+};
+
+const raw = '{"id":1,"name":"JinHo","isAdmin":false}';
+
+const user = safeJSONParse<User>(raw);
+// user: User | null
+
+if (user !== null) {
+  // user はここで User に型が絞り込まれます
+  console.log(user.id); // number
+  console.log(user.name); // string
+  console.log(user.isAdmin); // boolean
+}
+```
+
+型引数を提供しない場合、戻り値の型はデフォルトで `unknown | null` になります:
+
+```typescript
+const result = safeJSONParse('{"name": "JinHo"}');
+// result: unknown | null
+```
+
+`safeJSONParse` を独自の型ガード(例: `isJSONObject`, `isJSONValue`)と組み合わせて、パースされた構造をさらに検証できます。
+
+### isJSON と一緒に使用する
+
+`safeJSONParse` は `isJSON` 述語を補完するように設計されています:
+
+- 値が有効な JSON 文字列かどうかを確認するだけの場合は `isJSON(value)` を使用してください。
+- JSON 文字列を実際にパースして結果を操作したい場合は `safeJSONParse(value)` を使用してください。
+
+```typescript
+import { isJSON } from 'es-toolkit/predicate';
+import { safeJSONParse } from 'es-toolkit/util';
+
+function parseIfJson(input: unknown) {
+  if (!isJSON(input)) {
+    // input は有効な JSON 文字列ではありません
+    return null;
+  }
+
+  // input は string 型に絞り込まれます
+  const parsed = safeJSONParse(input);
+
+  // parsed は JSON 値(または予期しないことが発生した場合は null)です
+  return parsed;
+}
+```
+
+### 実用的な例
+
+#### API レスポンスのパース
+
+```typescript
+import { safeJSONParse } from 'es-toolkit/util';
+
+type ApiResponse = {
+  success: boolean;
+  payload?: unknown;
+};
+
+function handleApiResponse(responseBody: unknown) {
+  const data = safeJSONParse<ApiResponse>(responseBody);
+
+  if (data === null) {
+    return {
+      success: false,
+      error: 'レスポンス本文が有効な JSON ではありません',
+    };
+  }
+
+  if (!data.success) {
+    return {
+      success: false,
+      error: 'API が失敗を報告しました',
+    };
+  }
+
+  return {
+    success: true,
+    payload: data.payload,
+  };
+}
+```
+
+#### ユーザー入力のパース
+
+```typescript
+import { safeJSONParse } from 'es-toolkit/util';
+
+function tryParseUserConfig(input: unknown) {
+  const config = safeJSONParse<Record<string, unknown>>(input);
+
+  if (config === null) {
+    return {
+      isValid: false,
+      config: null,
+      error: '入力が有効な JSON ではありません',
+    };
+  }
+
+  return {
+    isValid: true,
+    config,
+    error: null,
+  };
+}
+```
+
+::: info "null" 文字列に関する注意
+
+入力が文字列 `"null"` の場合、`safeJSONParse("null")` は実際のパースされた値であるため `null` を返します。これは純粋に戻り値だけではパース失敗と区別できません。2つのケースを区別する必要がある場合は、`isJSON` と `safeJSONParse` を組み合わせるか、カスタム結果型を導入してください。
+
+:::
+
+#### パラメータ
+
+- `value` (`unknown`): JSON としてパースする値です。
+
+#### 戻り値
+
+(`T | null`): `value` が有効な JSON を含む文字列の場合、パースされた JSON 値。そうでない場合、`null`。

docs/ko/reference/util/safeJSONParse.md

@@ -0,0 +1,177 @@
+# safeJSONParse
+
+에러를 던지지 않고 JSON 문자열을 안전하게 파싱해요.
+
+```typescript
+const result = safeJSONParse(value);
+```
+
+## 사용법
+
+### `safeJSONParse(value)`
+
+JSON 문자열을 안전하게 파싱하고 싶을 때 `safeJSONParse`를 사용하세요. `JSON.parse` 예외를 발생시킬 위험 없이 파싱할 수 있어요. 값이 유효한 JSON을 포함한 문자열이면 파싱된 결과를 반환하고, 그렇지 않으면 `safeJSONParse`는 `null`을 반환해요.
+
+사용자 입력, 느슨하게 타입이 지정된 데이터, 또는 값이 항상 유효한 JSON 문자열이라는 보장이 없는 신뢰할 수 없는 소스를 다룰 때 특히 유용해요.
+
+```typescript
+import { safeJSONParse } from 'es-toolkit/util';
+
+// 유효한 JSON 문자열들
+safeJSONParse('{"name":"JinHo","age":29}'); // { name: "JinHo", age: 29 }
+safeJSONParse('[1, 2, 3]'); // [1, 2, 3]
+safeJSONParse('"hello world"'); // "hello world"
+safeJSONParse('42'); // 42
+safeJSONParse('true'); // true
+safeJSONParse('false'); // false
+safeJSONParse('null'); // null (유효한 JSON이지만 파싱된 값이 null)
+
+// 유효하지 않은 JSON 문자열들
+safeJSONParse('invalid json'); // null
+safeJSONParse('{"unclosed": "object"'); // null
+safeJSONParse('[1,2,'); // null
+safeJSONParse('undefined'); // null
+safeJSONParse(''); // null
+
+// 문자열이 아닌 값들
+safeJSONParse({ name: 'JinHo' }); // null
+safeJSONParse([1, 2, 3]); // null
+safeJSONParse(42); // null
+safeJSONParse(true); // null
+safeJSONParse(null); // null
+safeJSONParse(undefined); // null
+```
+
+### 제네릭을 사용한 타입 안전한 파싱
+
+제네릭 파라미터 `T`를 사용해서 파싱된 JSON 값의 예상 형태를 설명할 수 있어요:
+
+```typescript
+import { safeJSONParse } from 'es-toolkit/util';
+
+type User = {
+  id: number;
+  name: string;
+  isAdmin: boolean;
+};
+
+const raw = '{"id":1,"name":"JinHo","isAdmin":false}';
+
+const user = safeJSONParse<User>(raw);
+// user: User | null
+
+if (user !== null) {
+  // user는 여기서 User로 타입이 좁혀져요
+  console.log(user.id); // number
+  console.log(user.name); // string
+  console.log(user.isAdmin); // boolean
+}
+```
+
+타입 인자를 제공하지 않으면 반환 타입은 기본적으로 `unknown | null`이에요:
+
+```typescript
+const result = safeJSONParse('{"name": "JinHo"}');
+// result: unknown | null
+```
+
+`safeJSONParse`를 자신만의 타입 가드(예: `isJSONObject`, `isJSONValue`)와 함께 사용해서 파싱된 구조를 더 검증할 수 있어요.
+
+### isJSON과 함께 사용하기
+
+`safeJSONParse`는 `isJSON` 타입 가드를 보완하도록 설계되었어요:
+
+- 값이 유효한 JSON 문자열인지 확인만 하려면 `isJSON(value)`를 사용하세요.
+- JSON 문자열을 실제로 파싱하고 결과를 사용하고 싶을 때는 `safeJSONParse(value)`를 사용하세요.
+
+```typescript
+import { isJSON } from 'es-toolkit/predicate';
+import { safeJSONParse } from 'es-toolkit/util';
+
+function parseIfJson(input: unknown) {
+  if (!isJSON(input)) {
+    // input은 유효한 JSON 문자열이 아니에요
+    return null;
+  }
+
+  // input은 이제 string 타입으로 좁혀져요
+  const parsed = safeJSONParse(input);
+
+  // parsed는 JSON 값(또는 예상치 못한 일이 발생하면 null)이에요
+  return parsed;
+}
+```
+
+### 실용적인 예시
+
+#### API 응답 파싱
+
+```typescript
+import { safeJSONParse } from 'es-toolkit/util';
+
+type ApiResponse = {
+  success: boolean;
+  payload?: unknown;
+};
+
+function handleApiResponse(responseBody: unknown) {
+  const data = safeJSONParse<ApiResponse>(responseBody);
+
+  if (data === null) {
+    return {
+      success: false,
+      error: '응답 본문이 유효한 JSON이 아니에요',
+    };
+  }
+
+  if (!data.success) {
+    return {
+      success: false,
+      error: 'API가 실패를 보고했어요',
+    };
+  }
+
+  return {
+    success: true,
+    payload: data.payload,
+  };
+}
+```
+
+#### 사용자 입력 파싱
+
+```typescript
+import { safeJSONParse } from 'es-toolkit/util';
+
+function tryParseUserConfig(input: unknown) {
+  const config = safeJSONParse<Record<string, unknown>>(input);
+
+  if (config === null) {
+    return {
+      isValid: false,
+      config: null,
+      error: '입력이 유효한 JSON이 아니에요',
+    };
+  }
+
+  return {
+    isValid: true,
+    config,
+    error: null,
+  };
+}
+```
+
+::: info "null" 문자열에 대한 참고
+
+입력이 문자열 `"null"`일 때, `safeJSONParse("null")`은 실제 파싱된 값이기 때문에 `null`을 반환해요. 이것은 순수하게 반환 값만으로는 파싱 실패와 구별할 수 없어요. 두 경우를 구별해야 한다면 `isJSON`과 `safeJSONParse`를 함께 사용하거나 커스텀 결과 타입을 도입하세요.
+
+:::
+
+#### 파라미터
+
+- `value` (`unknown`): JSON으로 파싱할 값이에요.
+
+#### 반환 값
+
+(`T | null`): `value`가 유효한 JSON을 포함한 문자열이면 파싱된 JSON 값, 그렇지 않으면 `null`이에요.