suaveplan/openspec/specs/json/spec.md

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%.