42 lines
1.7 KiB
Markdown
42 lines
1.7 KiB
Markdown
# Proposal: enterprise-json
|
|
|
|
## Summary
|
|
|
|
Add `@suaveplan/json` to `universal/data/json` — a safe, enterprise-grade JSON
|
|
utility package with prototype-pollution protection, circular-reference
|
|
detection, and OTel instrumentation.
|
|
|
|
## Motivation
|
|
|
|
Raw `JSON.parse` / `JSON.stringify` calls are littered across application code
|
|
with no shared protection against:
|
|
|
|
- **Prototype pollution** — keys like `__proto__`, `constructor`, `prototype`
|
|
can silently mutate the prototype chain.
|
|
- **Circular references** — `JSON.stringify` throws an unformatted error that
|
|
leaks internal stack frames.
|
|
- **Untyped failures** — errors from `JSON.parse` are unstructured `SyntaxError`
|
|
instances with no stable code or OTel trace attachment.
|
|
|
|
## What ships
|
|
|
|
| Export | Description |
|
|
|---------------|-------------------------------------------------------------------|
|
|
| `safeParse` | `JSON.parse` with forbidden-key reviver + structured `JsonError` |
|
|
| `safeStringify` | `JSON.stringify` with circular-ref detection + structured error |
|
|
| `tryParse` | `safeParse` wrapped in try/catch → returns `undefined` on failure |
|
|
| `isValidJSON` | Boolean validity check (handles `null` literal correctly) |
|
|
| `getStringifySize` | UTF-8 byte size of the JSON representation |
|
|
|
|
## Non-goals
|
|
|
|
- Full JSON5 / JSONC support (separate package if needed).
|
|
- Schema validation (use `zod` directly or `@suaveplan/validation`).
|
|
|
|
## Acceptance criteria
|
|
|
|
- 100% Istanbul coverage on all 4 thresholds.
|
|
- 100% docs coverage (`bun run docs:check`).
|
|
- Green `bunx turbo lint typecheck test --filter=@suaveplan/json`.
|
|
- Published to Verdaccio at `0.1.0`.
|