obitools4/autodoc/docmd/pkg/obiformats/json_writer.md

# JSON Output Module for Biological Sequences (`obiformats`)

This Go package provides utilities to serialize biological sequence data (from `obiseq`) into structured JSON format, supporting batch processing and parallel I/O.

- **`JSONRecord(sequence)`**: Converts a single `BioSequence` into an indented JSON object containing:
  - `"id"`: Sequence identifier.
  - `"sequence"` (optional): Nucleotide/protein sequence string if present.
  - `"qualities"` (optional): Quality scores as a string if available.
  - `"annotations"` (optional): Metadata annotations map.

- **`FormatJSONBatch(batch)`**: Formats a batch of sequences as JSON array elements, returning a `*bytes.Buffer`. Handles comma separation and indentation.

- **`WriteJSON(iterator, file)`**: Writes a stream of sequences to an `io.Writer`, supporting:
  - Parallel workers (configurable via options).
  - Automatic compression (`gzip`/`bgzip`) if enabled.
  - Proper JSON array wrapping: `[`, chunked batches, and final `]`.
  - Atomic ordering to preserve sequence integrity across parallel writes.

- **`WriteJSONToStdout()` / `WriteJSONToFile()`**: Convenience wrappers:
  - Outputs to stdout or a file (with append/truncate control).
  - Supports paired-end data: writes both forward and reverse reads to separate files when configured.

- **Internal helpers**:
  - `_UnescapeUnicodeCharactersInJSON()`: Fixes double-escaped Unicode in JSON output (e.g., `\\u00E9` → `\u00E9`).
  - Uses chunked concurrency with `FileChunk`, ordered by batch number to ensure valid JSON structure.

Designed for high-throughput NGS data pipelines, it ensures correctness and performance while integrating with `obitools4`'s iterator-based processing model.