# `parsers/json` — JSON parsers

## Purpose

Parses JSON-array input documents into the same `Record<string, unknown>[]`
row shape produced by the CSV / XLSX parsers, so the canonical
`ImportService` can branch on `format` and call a uniform parse function.
The strict `parseJson` rejects non-array input with a deterministic error
string; the high-level `parseJsonWithHeaders` wraps `parseJson` to
produce the `{ headers, rows, totalRows }` shape consumed by the route
preview pipeline.

Scalar elements in the input array (numbers, strings, `null`) are
wrapped as `{ value: scalar }` rather than dropped, so the row count
agrees with the input array length and the resulting rows still satisfy
`Record<string, unknown>`.

## Features

- `parseJson` — strict array parsing; throws on non-array input.
- `parseJsonWithHeaders` — header-aware result shape; tolerant of
  single-object inputs (wraps them in a one-element array).
- Header inference unions keys across heterogeneous rows.

## Usage: Basic Example

```ts
import { parseJson } from "@suaveplan/api-plugin-import";
const rows = parseJson('[{"a":1},{"a":2}]'); // [{ a: 1 }, { a: 2 }]
```

## Usage: Advanced Example

```ts
import { parseJsonWithHeaders } from "@suaveplan/api-plugin-import";

const { headers, rows, totalRows } = parseJsonWithHeaders(
    '[{"a":1,"b":2},{"a":3,"c":4}]'
);
// headers: ["a","b","c"]
// rows:    [{ a: 1, b: 2 }, { a: 3, c: 4 }]
// totalRows: 2
```

## API Reference

- `parseJson(data: string): Record<string, unknown>[]` — throws `Error("JSON data must be an array")` on non-array input.
- `parseJsonWithHeaders(content: string): CsvParseResult` — header-aware variant.

## Implementation Notes

- `parseJson` uses `JSON.parse` directly — invalid JSON syntax surfaces
  as the native `SyntaxError` from the runtime, which is what the
  service catches and re-throws as `IMPORT.PROCESSING_FAILED`.
- `parseJsonWithHeaders` wraps single-object inputs in a one-element
  array so the route's `format: "json"` branch never has to special-case
  shape — the field is always `rows[]`.
- Scalar wrapping uses the literal key `value`; consumers that need a
  different key can map the result post-parse.