@fishka/seqio 0.4.0 → 0.5.0

package/README.md

@@ -1,13 +1,16 @@
 # @fishka/seqio
 
-Sequencing I/O — parsers and writers for bioinformatics file formats.
+Part of [fishka.bio](https://fishka.bio) — free browser-based bioinformatics tools.
 
-Currently supports:
+Browser- and Node-compatible sequencing file I/O.
 
-- **ABIF** (`.ab1` / `.abi`) — chromatogram traces produced by ABI Sanger / fragment analysis instruments. Meaning-lossless round-trip (every entry preserved), browser- and Node-compatible.
-- **FASTA / FASTQ / .qual** — text writers (Phred+33), pure and format-agnostic.
+Current API:
 
-Planned: SCF; FASTA/FASTQ reading.
+- **ABIF** (`.ab1` / `.abi`) parser, typed chromatogram view, raw reader/writer,
+  and mutation helpers.
+- **FASTA / FASTQ / .qual** text writers with Phred+33 quality encoding.
+
+Planned: SCF and FASTA/FASTQ readers.
 
 ## Install
 
@@ -15,71 +18,79 @@ Planned: SCF; FASTA/FASTQ reading.
 npm install @fishka/seqio
 ```
 
-## Use
+## ABIF
 
-### Quick parse (typed view + metadata)
+Use `parseAbif()` when you want a ready-to-render chromatogram, base calls, and
+metadata from an `.ab1` file.
 
 ```ts
 import { parseAbif } from '@fishka/seqio/abif';
-// or: import { parseAbif } from '@fishka/seqio';
 
 const result = parseAbif(uint8ArrayOrArrayBuffer, 'sample.ab1');
 
-result.baseCalls?.sequence; // "ACGT..." (preferred/called version, upper-cased)
-result.baseCalls?.confidences; // [40, 38, 41, ...]
-result.baseCalls?.positions; // [13, 25, 38, ...] sample-point peaks
-result.baseCallVariants; // every PBAS version present: [{ version, role: 'called'|'edited', ... }]
-result.chromatogram.data9To12.A; // A-channel int16 trace of the DATA9..12 block
-result.chromatogram.data1To4.A; // A-channel int16 trace of the DATA1..4 block
-result.metadata.sampleName; // SMPL tag
-result.metadata.samplingRate; // SPAC tag (falls back to PLOC-derived spacing)
+result.baseCalls?.sequence; // preferred called sequence, upper-cased
+result.baseCalls?.confidences; // PCON quality scores
+result.baseCalls?.positions; // PLOC peak positions
+result.baseCallVariants; // all PBAS/PCON/PLOC versions found
+result.chromatogram.data9To12.A; // A trace mapped through FWO_
+result.metadata.sampleName;
 ```
 
-### Low-level (entry-by-entry, round-trip)
+Use `readAbif()` / `writeAbif()` when you need entry-level access or want to
+preserve unknown vendor tags during a round trip.
 
 ```ts
 import { readAbif, writeAbif, findEntry, upsertEntry } from '@fishka/seqio/abif';
-import { setSequence, setConfidences, setPositions, setAveragePeakSpacing } from '@fishka/seqio/abif';
+import { setAveragePeakSpacing, setConfidences, setPositions, setSequence } from '@fishka/seqio/abif';
 
 const file = readAbif(bytes);
+
+findEntry(file, 'SMPL', 1);
+const commentPayload = new TextEncoder().encode('basecalled');
+upsertEntry(file, 'CMNT', 1, commentPayload, {
+  elementType: 2,
+  elementSize: 1,
+  elementCount: commentPayload.byteLength,
+});
+
 setSequence(file, 'ACGT...');
-setConfidences(file, [40, 38, 41, ...]);
-setPositions(file, [13, 25, 38, ...]);
+setConfidences(file, [40, 38, 41]);
+setPositions(file, [13, 25, 38]);
 setAveragePeakSpacing(file, 12.5, 'my-basecaller');
+
 const out = writeAbif(file);
 ```
 
-### Text export (FASTA / FASTQ / .qual)
+## FASTA / FASTQ / .qual
 
 ```ts
 import { formatFasta, formatFastq, formatQual, hasUsableQuality } from '@fishka/seqio';
 
 const record = { id: 'sample.ab1', sequence, qualities };
 
-formatFasta(record); // ">sample.ab1\nACGT...\n" (wrapped at 60)
+formatFasta(record); // wrapped at 60 residues by default
 formatFasta(record, { lineWidth: 0 }); // single sequence line
 
-// Phred+33; scores clamped to [0, 93]. Only emit quality when it exists —
-// missing/all-255 PCON should stay FASTA-only rather than invent perfect Q.
 if (hasUsableQuality(qualities)) {
-  formatFastq(record); // "@sample.ab1\nACGT...\n+\n..."
-  formatQual(record); // ">sample.ab1\n40 38 41 ...\n"
+  formatFastq(record); // Phred+33, scores clamped to [0, 93]
+  formatQual(record);
 }
 ```
 
-## Features
-
-- Browser- and Node-compatible (Uint8Array + DataView, no Node Buffer dependency).
-- Meaning-lossless round-trip: every directory entry preserved as a raw payload, so
-  `readAbif(writeAbif(f))` reproduces the same entries. The output is not byte-for-byte
-  identical to the input (payloads are repacked, `dataSize` normalized, MacBinary/padding
-  dropped); a byte-exact layout-preserving writer is a possible future opt-in.
-- MacBinary preamble support.
-- BioPython-compatible declared-vs-computed dataSize clamp.
-- PLOC read/written as unsigned int16 (preserves traces > 32k scans).
-- SPAC accepts both float32 (spec) and long (legacy) element types.
-- PCON/PLOC version fallback when PBAS2 ships without matching PCON2/PLOC2.
-- `ensureRawDataChannels()` helper for older DATA1..8-only files.
+## API
+
+- `parseAbif(input, fileName?)`
+- `readAbif(bytes)`, `writeAbif(file)`, `findEntry()`, `findEntries()`,
+  `upsertEntry()`
+- `getSequence()`, `getConfidences()`, `getPositions()`, `getDataChannel()`,
+  `getChannelMap()`, `getSamplingRate()`
+- `setSequence()`, `setConfidences()`, `setPositions()`,
+  `setAveragePeakSpacing()`, `ensureRawDataChannels()`
+- `formatFasta()`, `formatFastq()`, `formatQual()`, `hasUsableQuality()`
+
+The library uses `Uint8Array` and `DataView`, with no Node `Buffer` dependency.
+ABIF writing is meaning-lossless rather than byte-for-byte layout preserving:
+unknown entries are kept, but payloads may be repacked and padding normalized.
 
 ## License
 

package/dist/abif/index.d.mts

@@ -1,3 +1,5 @@
+declare function tagNameFromInt32(n: number): string;
+
 /**
  * Low-level ABIF file model: a flat list of directory entries with raw
  * payloads. Lossless round-trip is preserved: every entry (including unknown
@@ -60,7 +62,10 @@ interface AbifEntry {
     /**
      * The directory fields exactly as they were on disk — present only when this entry was read from a
      * file (absent for entries synthesized by setters/writeAbif). Lets consumers inspect the real record
-     * without our reconciliation.
+     * without our reconciliation, and lets writeAbif() reuse this entry's original directory slot/offset
+     * verbatim on an unmodified round-trip. Mutate entries only through upsertEntry() — it clears this
+     * field, since a hand-edited entry (payload/elementType/elementSize/elementCount set directly) can no
+     * longer be reproduced from its stale on-disk shape.
      */
     raw?: AbifEntryRaw;
 }
@@ -292,14 +297,13 @@ type AbifDecodedValue = {
     value: Uint8Array;
 };
 
-declare function tagNameFromInt32(n: number): string;
-
 /**
- * Low-level ABIF reader/writer.
- *
- * Round-trip without loss: every directory entry (including unknown vendor
- * tags) is preserved as a raw payload (Uint8Array). The high-level layer
- * (view.ts, parser.ts) provides typed access on top of this.
+ * Raw layer: the ABIF byte<->struct codec. Every directory entry (including unknown
+ * vendor tags) is preserved as a raw payload (Uint8Array), and writeAbif() reproduces
+ * the original bytes exactly for an unmodified round-trip (see its own doc comment).
+ * The domain layer (view.ts, setters.ts, parser.ts, abif-op-*.ts) provides typed,
+ * format-aware access on top of this — this file knows nothing about what any tag
+ * means.
  *
  * ABIF file layout:
  *   [0..3]      "ABIF" magic
@@ -350,14 +354,35 @@ declare function readAbif(bytes: Uint8Array): AbifFile;
 /**
  * Serialize an AbifFile back to a Uint8Array.
  *
- * Layout produced: header (128 B) + directory (N*28 B) + payload block.
- * External payloads are packed tightly in entry order. Payloads <= 4 bytes are
- * stored inline inside their directory entry.
- *
- * Meaning-lossless, not byte-exact: the payload bytes, tag fields and dataSize
- * (= payload length) round-trip, but physical layout does not — payloads are
- * repacked, directory/header padding and any MacBinary preamble are dropped. A
- * byte-exact layout-preserving mode is a possible future opt-in.
+ * Byte-exact on an unmodified round-trip for well-formed records and the tolerated
+ * count/dataSize desyncs readAbif() accepts: readAbif() followed right back by
+ * writeAbif(), with nothing touched in between, reproduces the original bytes
+ * exactly (a MacBinary-wrapped input round-trips its ABIF payload byte-exact, but
+ * the preamble itself is never re-added — see the AGENTS.md note on why). The one
+ * exception is a genuinely invalid negative `dataSize`/`numElements` field (readAbif
+ * tolerates these defensively, falling back to a computed size, but never treats them
+ * as verbatim-eligible on write — see the byteLength check below) — such an entry
+ * round-trips meaning-lossless (correct payload/content) but its declared dataSize
+ * field gets normalized to the real payload length rather than reproducing the
+ * original garbage value.
+ *
+ * This works by keeping every entry whose payload size hasn't changed since it was
+ * read (`entry.raw` present — upsertEntry() clears it on any mutation — and
+ * `payload.byteLength === raw.dataSize`) at its exact original directory slot and
+ * file offset, writing the *original* on-disk numElements/dataSize/offset-or-inline-
+ * padding instead of the reconciled/current ones. A new or resized entry is appended
+ * past the highest byte offset still known to hold preserved content (every verbatim
+ * entry's span, the directory, and any unreferenced range); only its own directory
+ * record changes, so every other entry's bytes stay untouched. A resized/removed
+ * entry's *old* span is not itself reserved — nothing points at it anymore, so it is
+ * free to be reused by whatever gets appended next; the output is not padded out to
+ * the original file's true end.
+ *
+ * The directory is kept at its original file offset as long as the entry count
+ * didn't grow (removing entries just shortens it in place; the original directory
+ * padding is only reused when the count is exactly unchanged, since a shorter
+ * directory can't reuse padding sized for more entries). Only a growing entry count
+ * relocates the whole directory to freshly appended space.
  */
 declare function writeAbif(file: AbifFile): Uint8Array;
 /** Find an entry by name+number, or undefined. */
@@ -367,6 +392,11 @@ declare function findEntries(file: AbifFile, name: string): AbifEntry[];
 /**
  * Replace the payload of an existing entry, or append a new one.
  * elementType/elementSize/elementCount must be supplied for new entries.
+ *
+ * This is the required way to mutate an entry read from a file — it clears `.raw`
+ * on replacement so writeAbif() never reuses a now-stale on-disk shape. Setting
+ * `entry.payload`/`elementType`/`elementSize`/`elementCount` directly instead
+ * leaves `.raw` behind and can corrupt the written directory record.
  */
 declare function upsertEntry(file: AbifFile, name: string, number: number, payload: Uint8Array, defaults: {
     elementType: number;
@@ -374,6 +404,86 @@ declare function upsertEntry(file: AbifFile, name: string, number: number, paylo
     elementCount: number;
 }): void;
 
+/**
+ * High-level "parse everything" wrapper around the raw + view layers.
+ *
+ * Returns a single ParsedAbif object with metadata, the FWO_-aware
+ * DATA1..4 / DATA9..12 channel split, basecalls, and decoded directory entries
+ * for diagnostics. Mirrors what typical viewers (chromatogram UIs, sample
+ * inspectors) need from a single file.
+ *
+ * For round-trip authoring (basecallers), prefer {@link readAbif} +
+ * setters from ./setters which operate directly on the raw AbifFile.
+ */
+
+/**
+ * Parse an ABIF file into a high-level view: metadata, channels, basecalls,
+ * and decoded directory entries.
+ *
+ * This is the INTERPRETING layer — it makes convenience choices (FWO_ → "GATC"
+ * fallback, derived samplingRate, preferred/upper-cased PBAS2 baseCalls). It is
+ * not the raw structural truth: for that use {@link readAbif}, which reads the
+ * directory verbatim (raw dataSize/offset/counts, tdir, inline bytes) and makes
+ * no interpretation. `parseAbif` builds on top of it.
+ *
+ * Accepts ArrayBuffer or Uint8Array (Buffer in Node works too — it extends
+ * Uint8Array). The `fileName` argument is informational only; it's preserved
+ * in the result.
+ */
+declare function parseAbif(input: ArrayBuffer | Uint8Array, fileName?: string): ParsedAbif;
+/** True when any channel has at least one signal value. */
+declare function hasSignals(s: ChannelSignals): boolean;
+/** Length of the longest channel in a ChannelSignals bundle. */
+declare function channelMaxLength(s: ChannelSignals): number;
+
+/**
+ * Mutation helpers for AbifFile: write PBAS/PCON/PLOC/SPAC and ensure DATA9..12
+ * are present. Used by basecallers to author ABIF output.
+ */
+
+/** Set PBAS2 (replaces if present). */
+declare function setSequence(file: AbifFile, sequence: string): void;
+/** Set PCON2 (replaces if present). Values clamped to [0, 255]. */
+declare function setConfidences(file: AbifFile, q: ArrayLike<number>): void;
+/**
+ * Set PLOC2 (replaces if present).
+ *
+ * Written as UNSIGNED int16 so positions up to 65535 are preserved on disk
+ * (signed int16 would wrap on traces with > 32k scans).
+ */
+declare function setPositions(file: AbifFile, positions: ArrayLike<number>): void;
+/**
+ * Set SPAC/1, SPAC/2, SPAC/3 — the standard ABIF "average peak spacing" trio
+ * that KB-basecaller writes and downstream tools (BioPython, Sequencher,
+ * KB-aware viewers) expect:
+ *
+ *   - SPAC/1 (float32) — average peak spacing used in last analysis.
+ *   - SPAC/2 (pString) — basecaller name / identifier.
+ *   - SPAC/3 (float32) — average peak spacing computed by the basecaller.
+ *
+ * Both float fields are written with the same value.
+ */
+declare function setAveragePeakSpacing(file: AbifFile, spacing: number, basecallerName: string): void;
+/**
+ * Mean consecutive peak-to-peak distance in scans, from a positions array.
+ * Returns 0 when fewer than 2 positions are present.
+ */
+declare function averagePeakSpacing(positions: ArrayLike<number>): number;
+/**
+ * Ensure DATA9..12 are present in the file. Many downstream consumers
+ * (BioPython-style readers, viewers) read the chromatogram signal from
+ * DATA9..12 by convention — these tags are the raw fluorescence on newer
+ * instruments. Older files that only carry DATA1..8 break those consumers
+ * with a "no signal" error after re-basecalling.
+ *
+ * We populate DATA9..12 by copying DATA1..4 (which on DATA1..8-only files IS
+ * the raw signal). The DATA1..4 tags are left untouched so any tool that
+ * reads them keeps working.
+ *
+ * No-op when DATA9..12 already exist.
+ */
+declare function ensureRawDataChannels(file: AbifFile): void;
+
 /**
  * High-level typed view over an AbifFile.
  *
@@ -461,84 +571,4 @@ declare function getPositions(file: AbifFile): number[] | undefined;
  */
 declare function getSamplingRate(file: AbifFile): number | undefined;
 
-/**
- * Mutation helpers for AbifFile: write PBAS/PCON/PLOC/SPAC and ensure DATA9..12
- * are present. Used by basecallers to author ABIF output.
- */
-
-/** Set PBAS2 (replaces if present). */
-declare function setSequence(file: AbifFile, sequence: string): void;
-/** Set PCON2 (replaces if present). Values clamped to [0, 255]. */
-declare function setConfidences(file: AbifFile, q: ArrayLike<number>): void;
-/**
- * Set PLOC2 (replaces if present).
- *
- * Written as UNSIGNED int16 so positions up to 65535 are preserved on disk
- * (signed int16 would wrap on traces with > 32k scans).
- */
-declare function setPositions(file: AbifFile, positions: ArrayLike<number>): void;
-/**
- * Set SPAC/1, SPAC/2, SPAC/3 — the standard ABIF "average peak spacing" trio
- * that KB-basecaller writes and downstream tools (BioPython, Sequencher,
- * KB-aware viewers) expect:
- *
- *   - SPAC/1 (float32) — average peak spacing used in last analysis.
- *   - SPAC/2 (pString) — basecaller name / identifier.
- *   - SPAC/3 (float32) — average peak spacing computed by the basecaller.
- *
- * Both float fields are written with the same value.
- */
-declare function setAveragePeakSpacing(file: AbifFile, spacing: number, basecallerName: string): void;
-/**
- * Mean consecutive peak-to-peak distance in scans, from a positions array.
- * Returns 0 when fewer than 2 positions are present.
- */
-declare function averagePeakSpacing(positions: ArrayLike<number>): number;
-/**
- * Ensure DATA9..12 are present in the file. Many downstream consumers
- * (BioPython-style readers, viewers) read the chromatogram signal from
- * DATA9..12 by convention — these tags are the raw fluorescence on newer
- * instruments. Older files that only carry DATA1..8 break those consumers
- * with a "no signal" error after re-basecalling.
- *
- * We populate DATA9..12 by copying DATA1..4 (which on DATA1..8-only files IS
- * the raw signal). The DATA1..4 tags are left untouched so any tool that
- * reads them keeps working.
- *
- * No-op when DATA9..12 already exist.
- */
-declare function ensureRawDataChannels(file: AbifFile): void;
-
-/**
- * High-level "parse everything" wrapper around the raw + view layers.
- *
- * Returns a single ParsedAbif object with metadata, the FWO_-aware
- * DATA1..4 / DATA9..12 channel split, basecalls, and decoded directory entries
- * for diagnostics. Mirrors what typical viewers (chromatogram UIs, sample
- * inspectors) need from a single file.
- *
- * For round-trip authoring (basecallers), prefer {@link readAbif} +
- * setters from ./setters which operate directly on the raw AbifFile.
- */
-
-/**
- * Parse an ABIF file into a high-level view: metadata, channels, basecalls,
- * and decoded directory entries.
- *
- * This is the INTERPRETING layer — it makes convenience choices (FWO_ → "GATC"
- * fallback, derived samplingRate, preferred/upper-cased PBAS2 baseCalls). It is
- * not the raw structural truth: for that use {@link readAbif}, which reads the
- * directory verbatim (raw dataSize/offset/counts, tdir, inline bytes) and makes
- * no interpretation. `parseAbif` builds on top of it.
- *
- * Accepts ArrayBuffer or Uint8Array (Buffer in Node works too — it extends
- * Uint8Array). The `fileName` argument is informational only; it's preserved
- * in the result.
- */
-declare function parseAbif(input: ArrayBuffer | Uint8Array, fileName?: string): ParsedAbif;
-/** True when any channel has at least one signal value. */
-declare function hasSignals(s: ChannelSignals): boolean;
-/** Length of the longest channel in a ChannelSignals bundle. */
-declare function channelMaxLength(s: ChannelSignals): number;
-
 export { type AbifBaseCallRole, type AbifBaseCallVariant, type AbifBaseCalls, type AbifByteRange, type AbifChromatogramBundle, type AbifDataChannelRole, type AbifDecodedValue, type AbifDirEntry, type AbifDirectory, type AbifEntry, type AbifEntryRaw, type AbifFile, type AbifMetadata, type ChannelSignals, type Chromatogram, ENTRY_SIZE, HEADER_SIZE, type ParsedAbif, averagePeakSpacing, channelMaxLength, dataChannelRole, ensureRawDataChannels, findEntries, findEntry, getChannelMap, getConfidences, getDataChannel, getFwo, getPositions, getReverseComplemented, getSamplingRate, getSequence, hasData9To12Block, hasSignals, isFwoPermutation, parseAbif, readAbif, setAveragePeakSpacing, setConfidences, setPositions, setSequence, tagNameFromInt32, upsertEntry, writeAbif };