39 lines
2.1 KiB
Markdown
39 lines
2.1 KiB
Markdown
# 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%.
|