# json

## Purpose

Safe JSON parse/stringify surface for the Suaveplan monorepo. Wraps the platform `JSON` global with prototype-pollution defense, AbortSignal handling, structured `JsonError` codes registered under the `JSON.*` namespace, OpenTelemetry spans, and a `tryParse` / `isValidJSON` / `getStringifySize` ergonomic layer that the platform global does not provide.

**Package path:** `universal/data/json`
**Landed:** 2026-04-20

## Requirements

- **R1** The package MUST expose `safeParse<T>(text, options?)` that parses JSON
  and throws `JsonError(PARSE.FAILED)` on invalid syntax.
- **R2** `safeParse` MUST reject keys in the `forbiddenKeys` list (default:
  `__proto__`, `constructor`, `prototype`) with `JsonError(PARSE.PROTOTYPE_POLLUTION)`.
- **R3** `safeParse` MUST accept an `AbortSignal` and throw `JsonError(PARSE.FAILED)`
  when the signal is already aborted before parsing begins.
- **R4** The package MUST expose `safeStringify(value, options?)` that stringifies
  and throws `JsonError(STRINGIFY.CIRCULAR)` on circular references.
- **R5** `safeStringify` MUST allow DAG sharing (same object at multiple
  non-cyclic paths) without throwing.
- **R6** `safeStringify` MUST accept an `AbortSignal` and throw
  `JsonError(STRINGIFY.FAILED)` when the signal is already aborted.
- **R7** `safeStringify` MUST throw `JsonError(STRINGIFY.FAILED)` for any
  non-circular, non-`JsonError` exception from `JSON.stringify` (e.g. `BigInt`).
- **R8** The package MUST expose `tryParse<T>(text, options?)` that returns
  `undefined` instead of throwing.
- **R9** The package MUST expose `isValidJSON(text)` that returns `true` for the
  `"null"` literal (not `false` as a naïve `tryParse() !== undefined` check
  would yield).
- **R10** The package MUST expose `getStringifySize(value)` returning UTF-8
  byte length of `JSON.stringify(value)`.
- **R11** `safeParse` and `safeStringify` MUST emit OpenTelemetry spans via
  `@opentelemetry/api`.
- **R12** All error codes MUST be registered under the `JSON.*` namespace via
  `defineCodes` from `@suaveplan/error`.
- **R13** Istanbul coverage on all 4 thresholds: 100%.
- **R14** Docs coverage: 100%.