@fishka/seqio 0.6.1 → 0.8.0

package/dist/index.d.mts

@@ -1,32 +1,88 @@
 export { AbifBaseCallRole, AbifBaseCallVariant, AbifBaseCalls, AbifByteRange, AbifChromatogramBundle, AbifDataChannelRole, AbifDecodedValue, AbifDirEntry, AbifDirectory, AbifEntry, AbifEntryRaw, AbifFile, AbifMetadata, ChannelSignals, Chromatogram, CropAbifOptions, CropAbifRange, ENTRY_SIZE, HEADER_SIZE, ParsedAbif, averagePeakSpacing, channelMaxLength, cropAbif, dataChannelRole, ensureRawDataChannels, findEntries, findEntry, getChannelMap, getConfidences, getConfidencesForVersion, getDataChannel, getFwo, getPositions, getPositionsForVersion, getReverseComplemented, getSamplingRate, getSequence, getSequenceForVersion, hasData9To12Block, hasSignals, insertEntrySorted, isFwoPermutation, parseAbif, readAbif, setAveragePeakSpacing, setConfidences, setPositions, setSequence, tagNameFromInt32, upsertEntry, writeAbif } from './abif/index.mjs';
 
 /**
- * FASTA / FASTQ / .qual text serialization.
+ * Content-based file-format detection.
  *
- * Pure, format-level writers: they turn a sequence plus optional per-base Phred
- * quality into text. No coupling to any binary format — callers build records
- * from ABIF basecalls (PBAS/PCON), alignments, consensus, etc.
+ * Sniffs the bytes, never the file extension: binary magic first (ABIF at offset 0, or at
+ * 128 behind a MacBinary preamble; SCF's ".scf" magic), then the first non-blank line for
+ * the text formats. Text signatures are matched on the leading line's content (a keyword
+ * like `LOCUS`, or the first character `>` / `;` / `@`), so a mislabeled or extension-less
+ * file still resolves.
+ */
+/** A format {@link detectFormat} can recognize. Some are detected before their reader ships. */
+type SeqFileFormat = 'abif' | 'scf' | 'fasta' | 'fastq' | 'genbank' | 'embl' | 'swissprot' | 'clustal' | 'stockholm' | 'phylip' | 'nexus' | 'msf' | 'pir' | 'gff' | 'sam' | 'bam' | 'gfa' | 'unknown';
+/**
+ * Detect the sequencing file format from its content. Returns 'unknown' when no signature
+ * matches (empty input, or a leading line that is neither a known magic nor a recognized
+ * text marker).
+ */
+declare function detectFormat(bytes: Uint8Array): SeqFileFormat;
+
+/**
+ * The common "a sequence with a name" record produced by every reader that extracts
+ * sequences for downstream picking/export (GenBank, EMBL, Swiss-Prot, the alignment
+ * formats, …). Data only — same shape as {@link FastaRecord}, so all readers feed one
+ * uniform list regardless of source format.
+ */
+interface SeqRecord {
+    /** Identifier (accession/version/locus/name, per the source format's convention). */
+    id: string;
+    /** Free-text description/definition when the format carries one. */
+    description?: string;
+    /**
+     * Residues with line wrapping removed. Case is preserved as written; alignment gap
+     * characters ('-', '.') are kept (an aligned row is stored verbatim, not de-gapped).
+     */
+    sequence: string;
+}
+/** Build a {@link SeqRecord}, dropping an empty description so records compare cleanly. */
+declare function makeSeqRecord(id: string, description: string, sequence: string): SeqRecord;
+
+/**
+ * EMBL / Swiss-Prot (UniProtKB) flat-file reader — sequence extraction only.
+ *
+ * Both formats share one container: two-letter line-type codes in columns 0–1, an `SQ`
+ * line that introduces the sequence, indented sequence lines (residues + trailing position
+ * counters), and `//` between records. UniProtKB is historically derived from the EMBL
+ * format, so a single scanner serves both; they differ only in which field is the id:
+ *   - EMBL: the `ID` line's accession, suffixed with the sequence version (`SV n` → `.n`),
+ *     falling back to `AC`.
+ *   - Swiss-Prot: the primary `AC` accession (the `ID` line is the entry name), falling
+ *     back to that entry name.
+ * Description comes from the `DE` line(s), joined. Feature tables (`FT`) and all other codes
+ * are skipped — this is the sequence-reading path only.
  *
- * Quality is encoded as Phred+33 (Sanger / Illumina 1.8+). Scores are clamped
- * to [0, {@link MAX_PHRED}]: the upper bound is the largest value representable
- * as Phred+33 ('~' = ASCII 126 = 93 + 33). Callers must NOT feed quality for
- * reads that lack it — gate on {@link hasUsableQuality} and emit FASTA only,
- * rather than letting the 255 "no quality" sentinel clamp to a perfect '~'.
+ * Deliberately lenient (see AGENTS.md): never throws. No `SQ` block → empty sequence; a
+ * missing `//` between records flushes the previous one when the next `ID` appears; a
+ * truncated final record is flushed at EOF. Residue case is preserved as written.
+ */
+
+/** Read EMBL flat files (`.embl`/`.dat`): id = accession.version from the ID line. */
+declare function parseEmbl(input: string | Uint8Array): SeqRecord[];
+/** Read UniProtKB/Swiss-Prot flat files (`.dat`/`.txt`): id = primary AC accession. */
+declare function parseSwissprot(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * Record + option types for the FASTA / FASTQ / .qual family.
+ *
+ * These carry the sequence's data only — the residues and (FASTQ) the per-base
+ * Phred scores. A file's line wrapping and newline style are cosmetic: the readers
+ * discard them and the writers re-impose a chosen width. The same record shape is
+ * used symmetrically for reading and writing, so parse → edit → write round-trips
+ * the data (not the exact bytes).
  */
-/** Largest Phred score representable as Phred+33 ('~' = ASCII 126 = 93 + 33). */
-declare const MAX_PHRED = 93;
 /** A FASTA record: identifier, optional description, and residues. */
 interface FastaRecord {
-    /** Identifier written after '>', up to the first space. */
+    /** Identifier: the header text up to the first whitespace (the '>' is not included). */
     id: string;
-    /** Optional free text after the id on the header line. */
+    /** Free text after the id on the header line; absent when the header is just an id. */
     description?: string;
-    /** Residues, written verbatim (case and gaps preserved). */
+    /** Residues with all line breaks/whitespace removed; case and gap chars ('-', '.') preserved. */
     sequence: string;
 }
 /** A FASTQ record: a {@link FastaRecord} plus one Phred score per residue. */
 interface FastqRecord extends FastaRecord {
-    /** Per-base Phred scores; must be one per residue in {@link FastaRecord.sequence}. */
+    /** Per-base Phred scores decoded from the quality line (Phred+33), one per residue. */
     qualities: readonly number[];
 }
 /** A .qual record: identifier, optional description, and per-base Phred scores. */
@@ -40,6 +96,58 @@ interface WrapOptions {
     /** Residues (FASTA) or scores (.qual) per line; <= 0 writes one line. Default 60. */
     lineWidth?: number;
 }
+
+/**
+ * FASTA / FASTQ / .qual text codec: readers (parseFasta / parseFastq) and writers
+ * (formatFasta / formatFastq / formatQual).
+ *
+ * Text formats have no on-disk container, so there is no separate raw layer — this
+ * one file is the codec (the `<family>-format.ts` analog of `abif-format.ts`).
+ *
+ * Data only: the readers keep residues and per-base Phred scores and drop cosmetic
+ * formatting (line wrapping, blank lines, `\r\n` vs `\n`); the writers re-impose a
+ * chosen wrap width. Quality is Phred+33 (Sanger / Illumina 1.8+); scores are clamped
+ * to [0, {@link MAX_PHRED}] on write ('~' = ASCII 126 = 93 + 33).
+ */
+
+/** Largest Phred score representable as Phred+33 ('~' = ASCII 126 = 93 + 33). */
+declare const MAX_PHRED = 93;
+/**
+ * Parse FASTA text (or bytes) into records. Deliberately lenient — it never refuses a
+ * file: blank lines and legacy ';' comment lines are ignored, residue lines are
+ * concatenated with inner whitespace stripped (case and gaps preserved), and any stray
+ * text before the first '>' header is skipped. id = the header up to the first
+ * whitespace, description = the remainder.
+ */
+declare function parseFasta(input: string | Uint8Array): FastaRecord[];
+/**
+ * Parse FASTQ text (or bytes) into records with decoded Phred+33 qualities.
+ *
+ * Handles multi-line records: the sequence runs to the '+' separator, then the quality
+ * runs until it has as many chars as the sequence has residues. Length — not "the next
+ * line starting with @" — terminates the quality block, because a quality character can
+ * itself be '@' (Phred 31) or '+' (Phred 10); this is the one subtlety the spec calls
+ * out (Cock et al. 2010).
+ *
+ * Deliberately lenient — it never refuses a file, and never lets one malformed record
+ * cost a *following* one. A stray line where a '@' header is expected is skipped (resync
+ * at the next '@'); a record with no '+' separator (truncated, or the next record starts)
+ * keeps its sequence with unknown quality; a short/over-long or out-of-range quality is
+ * reconciled to the residue count in {@link makeFastq}. The sequence — what callers
+ * actually pick — is always preserved intact, for every record.
+ *
+ * Cross-record safety comes from recognizing a real next-record header structurally: a
+ * line beginning '@' is the next header (not this record's quality) when a '+' separator
+ * follows its sequence before any other '@' — see {@link startsRecord}. This is exact for
+ * strict 4-line FASTQ (the real-world norm, where a quality line is followed only by the
+ * next '@' header or EOF) and preserves every following record even when a quality block is
+ * badly truncated. The one accepted blind spot is a deliberate trade-off: '@' and '+' are
+ * both valid Phred+33 characters, so in *wrapped* multi-line quality a continuation line
+ * that begins '@' and is later followed (before the next header) by one beginning '+' is
+ * misread as a header. That pattern is vanishingly rare, and favoring "never drop the next
+ * record's sequence on truncated input" over it is the right call for this parser's use.
+ */
+declare function parseFastq(input: string | Uint8Array): FastqRecord[];
 /** Serialize one or more records to FASTA text (trailing newline included). */
 declare function formatFasta(records: FastaRecord | readonly FastaRecord[], options?: WrapOptions): string;
 /** Serialize one or more records to FASTQ text, Phred+33 (trailing newline included). */
@@ -53,4 +161,152 @@ declare function formatQual(records: QualRecord | readonly QualRecord[], options
  */
 declare function hasUsableQuality(qualities?: readonly number[]): boolean;
 
-export { type FastaRecord, type FastqRecord, MAX_PHRED, type QualRecord, type WrapOptions, formatFasta, formatFastq, formatQual, hasUsableQuality };
+/**
+ * GenBank / GenPept flat-file reader — sequence extraction only.
+ *
+ * Reads the sequence(s) and their identity out of GenBank flat files (`.gb`/`.gbk`/`.gbff`,
+ * and the protein `.gp` variant). One file may hold many records, each ending in `//`. We
+ * take what a "pick a sequence" caller needs and skip the rest:
+ *   - id: VERSION (accession.version) if present, else ACCESSION, else the LOCUS name.
+ *   - description: DEFINITION (its continuation lines joined).
+ *   - sequence: the ORIGIN block, with the leading base counters and spacing stripped.
+ * Feature-table parsing (locations, /translation, join/complement) is intentionally out of
+ * scope here — this is the sequence-reading path, not a full annotation model.
+ *
+ * Deliberately lenient (see AGENTS.md): never throws. A record with no ORIGIN yields an
+ * empty sequence rather than an error; a missing `//` between records (or a truncated final
+ * record) still yields every record whose LOCUS was seen. Sequence case is preserved as
+ * written (GenBank ORIGIN is conventionally lowercase).
+ */
+
+declare function parseGenbank(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * GFA (Graphical Fragment Assembly, `.gfa`) reader — sequence extraction.
+ *
+ * Assembly / pangenome graphs. Only Segment (`S`) lines carry sequence; links, paths, jumps and
+ * containments are graph topology and hold none. Both dialects are supported by field position:
+ *
+ *   GFA1:  S <name> <sequence> [tags…]
+ *   GFA2:  S <sid>  <slen>     <sequence> [tags…]
+ *
+ * GFA2 inserts an integer segment length between the name and the sequence, so when the field after
+ * the name is a bare integer AND another field follows, the sequence is that next field; otherwise
+ * it's the field right after the name (GFA1). A `*` sequence (a segment declared without residues)
+ * is skipped — there's nothing to pick. Lenient: never throws; malformed lines are ignored.
+ */
+
+declare function parseGfa(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * GFF3 (`.gff`/`.gff3`) reader — sequence extraction.
+ *
+ * A GFF3 file is annotation (feature coordinates), which carries NO sequence — except when it
+ * embeds a FASTA section after a `##FASTA` directive. This reader returns the records of that
+ * embedded FASTA and nothing else; a GFF with no `##FASTA` section yields `[]` (there is no
+ * sequence to pick). Feature lines are never turned into sequence.
+ */
+
+declare function parseGff(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * Multiple-sequence-alignment readers — one aligned row = one record.
+ *
+ * Covers the common alignment formats: Clustal (`.aln`), Stockholm (`.sto`/`.stk`),
+ * PHYLIP (`.phy`), NEXUS (`.nex`) and GCG/MSF (`.msf`). Each returns the alignment's rows
+ * as {@link SeqRecord}s: `id` = the taxon/sequence name, `sequence` = that row **with its
+ * gap characters preserved** (an aligned row is data; de-gapping is a caller's choice).
+ * Only line spacing and wrap are removed. No description field — these formats don't carry
+ * a per-row one.
+ *
+ * Deliberately lenient (see AGENTS.md): never throws, best-effort on malformed input, and
+ * always returns every row it can. Interleaved blocks are accumulated by name.
+ */
+
+/** Read a Clustal (`.aln`) alignment. Also handles the Clustal-format output of MUSCLE, MAFFT, etc. */
+declare function parseClustal(input: string | Uint8Array): SeqRecord[];
+/** Read a Stockholm (`.sto`/`.stk`) alignment; multiple `//`-separated alignments are all returned. */
+declare function parseStockholm(input: string | Uint8Array): SeqRecord[];
+/**
+ * Read a PHYLIP (`.phy`) alignment. Supports relaxed (whitespace-delimited names) interleaved
+ * and single-block layouts — the common modern output (RAxML/PhyML/aligners). The first line is
+ * `<ntax> <nchar>`; the next `ntax` non-blank lines carry names + the first block; any further
+ * non-blank lines are interleaved continuation, appended round-robin and clipped at `nchar` so a
+ * stray line can't overrun residues into another taxon.
+ *
+ * Limitation: multi-line *sequential* PHYLIP (each taxon's whole sequence spanning consecutive
+ * lines before the next taxon) is read as interleaved and would be misassigned; it is rare next to
+ * interleaved output. Single-line sequential (one line per taxon) reads correctly.
+ */
+declare function parsePhylip(input: string | Uint8Array): SeqRecord[];
+/**
+ * Read a NEXUS (`.nex`) DATA/CHARACTERS block's MATRIX. Handles interleaved matrices (names
+ * repeat across blocks), space-grouped rows, and a final row that closes the matrix with `;`.
+ *
+ * Not resolved (kept verbatim / unsupported): `FORMAT MATCHCHAR=.` — a `.` meaning "same residue
+ * as the first taxon here" is left literal rather than substituted; and label-less matrices
+ * (`FORMAT LABELS=NO`, relying on TAXLABELS order) whose rows carry no name are skipped.
+ */
+declare function parseNexus(input: string | Uint8Array): SeqRecord[];
+/** Read a GCG/MSF (`.msf`) alignment (the sequence blocks after the header's `//`). */
+declare function parseMsf(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * PIR / NBRF (`.pir`) reader — sequence extraction.
+ *
+ * A PIR record is: a header `>XX;identifier` (the two-letter code XX is the sequence type —
+ * P1/F1 protein, DL/DC DNA, RL/RC RNA, N1/N3 nucleotide, XX other), a free-text title line,
+ * then the residues, terminated by `*`. One file may hold many records.
+ *   - id: the identifier after the `;` (or the whole header when there is no `;`).
+ *   - description: the title line.
+ *   - sequence: the residues with spacing removed and the single trailing `*` terminator dropped.
+ *
+ * Deliberately lenient (see AGENTS.md): never throws; a truncated record (no `*`) keeps its
+ * residues; the first line after a header is taken as the title.
+ */
+
+declare function parsePir(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * BAM (`.bam`) reader — read-sequence extraction from the binary alignment format.
+ *
+ * BAM is the binary twin of SAM. On disk it is BGZF-compressed (a gzip stream of concatenated
+ * blocks); this reader expects the INFLATED bytes — starting with the "BAM\1" magic. The caller
+ * peels the gzip/BGZF wrapper first (a gzip decompressor decodes BGZF's concatenated members), so
+ * this stays a synchronous, dependency-free binary parser.
+ *
+ * Semantics mirror the SAM reader exactly (see {@link parseSam}): one sequence per read (secondary
+ * 0x100 / supplementary 0x800 skipped), reverse-strand sequence stored verbatim (reference-forward),
+ * id = read name (+ /1,/2 for paired mates), description = "RNAME:POS (+/-)" or "unmapped". Records
+ * without a stored sequence (l_seq = 0) are skipped. Lenient: on any truncation or garble it stops
+ * and returns what it parsed cleanly, never throwing.
+ */
+
+declare function parseBam(bytes: Uint8Array): SeqRecord[];
+
+/**
+ * SAM (`.sam`) reader — read-sequence extraction.
+ *
+ * SAM is a read-alignment format: one record per alignment, tab-delimited, with 11 mandatory
+ * fields (QNAME FLAG RNAME POS MAPQ CIGAR RNEXT PNEXT TLEN SEQ QUAL). This reader returns each
+ * record's read sequence — field 10, `SEQ`. Records whose SEQ is `*` (sequence not stored) are
+ * skipped: there's nothing to pick.
+ *
+ * The sequence is returned VERBATIM as written. For a reverse-strand alignment (FLAG bit 0x10) SAM
+ * already stores the reverse complement (reference-forward orientation), so that reference-oriented
+ * sequence is what you get — it is deliberately not un-flipped to the original read orientation.
+ *
+ * One sequence per read: secondary (FLAG 0x100) and supplementary (0x800) alignments are skipped —
+ * they re-map the same read (a duplicate, or a hard-clipped split fragment), which would pollute a
+ * "pick the sequences" list. What's kept is the read's SEQ from its primary (or unmapped) record —
+ * i.e. the sequence as SAM stores it, which for a hard-clipped primary alignment omits the clipped
+ * flanks rather than reconstructing the original full read.
+ *
+ * `@`-prefixed lines are skipped as headers — the SAM spec's QNAME charset `[!-?A-~]` excludes '@'
+ * (0x40) precisely so a read name can never be confused with a header. Lenient: never throws; lines
+ * with fewer than 11 fields are ignored rather than rejected.
+ */
+
+declare function parseSam(input: string | Uint8Array): SeqRecord[];
+
+export { type FastaRecord, type FastqRecord, MAX_PHRED, type QualRecord, type SeqFileFormat, type SeqRecord, type WrapOptions, detectFormat, formatFasta, formatFastq, formatQual, hasUsableQuality, makeSeqRecord, parseBam, parseClustal, parseEmbl, parseFasta, parseFastq, parseGenbank, parseGfa, parseGff, parseMsf, parseNexus, parsePhylip, parsePir, parseSam, parseStockholm, parseSwissprot };

package/dist/index.d.ts

@@ -1,32 +1,88 @@
 export { AbifBaseCallRole, AbifBaseCallVariant, AbifBaseCalls, AbifByteRange, AbifChromatogramBundle, AbifDataChannelRole, AbifDecodedValue, AbifDirEntry, AbifDirectory, AbifEntry, AbifEntryRaw, AbifFile, AbifMetadata, ChannelSignals, Chromatogram, CropAbifOptions, CropAbifRange, ENTRY_SIZE, HEADER_SIZE, ParsedAbif, averagePeakSpacing, channelMaxLength, cropAbif, dataChannelRole, ensureRawDataChannels, findEntries, findEntry, getChannelMap, getConfidences, getConfidencesForVersion, getDataChannel, getFwo, getPositions, getPositionsForVersion, getReverseComplemented, getSamplingRate, getSequence, getSequenceForVersion, hasData9To12Block, hasSignals, insertEntrySorted, isFwoPermutation, parseAbif, readAbif, setAveragePeakSpacing, setConfidences, setPositions, setSequence, tagNameFromInt32, upsertEntry, writeAbif } from './abif/index.js';
 
 /**
- * FASTA / FASTQ / .qual text serialization.
+ * Content-based file-format detection.
  *
- * Pure, format-level writers: they turn a sequence plus optional per-base Phred
- * quality into text. No coupling to any binary format — callers build records
- * from ABIF basecalls (PBAS/PCON), alignments, consensus, etc.
+ * Sniffs the bytes, never the file extension: binary magic first (ABIF at offset 0, or at
+ * 128 behind a MacBinary preamble; SCF's ".scf" magic), then the first non-blank line for
+ * the text formats. Text signatures are matched on the leading line's content (a keyword
+ * like `LOCUS`, or the first character `>` / `;` / `@`), so a mislabeled or extension-less
+ * file still resolves.
+ */
+/** A format {@link detectFormat} can recognize. Some are detected before their reader ships. */
+type SeqFileFormat = 'abif' | 'scf' | 'fasta' | 'fastq' | 'genbank' | 'embl' | 'swissprot' | 'clustal' | 'stockholm' | 'phylip' | 'nexus' | 'msf' | 'pir' | 'gff' | 'sam' | 'bam' | 'gfa' | 'unknown';
+/**
+ * Detect the sequencing file format from its content. Returns 'unknown' when no signature
+ * matches (empty input, or a leading line that is neither a known magic nor a recognized
+ * text marker).
+ */
+declare function detectFormat(bytes: Uint8Array): SeqFileFormat;
+
+/**
+ * The common "a sequence with a name" record produced by every reader that extracts
+ * sequences for downstream picking/export (GenBank, EMBL, Swiss-Prot, the alignment
+ * formats, …). Data only — same shape as {@link FastaRecord}, so all readers feed one
+ * uniform list regardless of source format.
+ */
+interface SeqRecord {
+    /** Identifier (accession/version/locus/name, per the source format's convention). */
+    id: string;
+    /** Free-text description/definition when the format carries one. */
+    description?: string;
+    /**
+     * Residues with line wrapping removed. Case is preserved as written; alignment gap
+     * characters ('-', '.') are kept (an aligned row is stored verbatim, not de-gapped).
+     */
+    sequence: string;
+}
+/** Build a {@link SeqRecord}, dropping an empty description so records compare cleanly. */
+declare function makeSeqRecord(id: string, description: string, sequence: string): SeqRecord;
+
+/**
+ * EMBL / Swiss-Prot (UniProtKB) flat-file reader — sequence extraction only.
+ *
+ * Both formats share one container: two-letter line-type codes in columns 0–1, an `SQ`
+ * line that introduces the sequence, indented sequence lines (residues + trailing position
+ * counters), and `//` between records. UniProtKB is historically derived from the EMBL
+ * format, so a single scanner serves both; they differ only in which field is the id:
+ *   - EMBL: the `ID` line's accession, suffixed with the sequence version (`SV n` → `.n`),
+ *     falling back to `AC`.
+ *   - Swiss-Prot: the primary `AC` accession (the `ID` line is the entry name), falling
+ *     back to that entry name.
+ * Description comes from the `DE` line(s), joined. Feature tables (`FT`) and all other codes
+ * are skipped — this is the sequence-reading path only.
  *
- * Quality is encoded as Phred+33 (Sanger / Illumina 1.8+). Scores are clamped
- * to [0, {@link MAX_PHRED}]: the upper bound is the largest value representable
- * as Phred+33 ('~' = ASCII 126 = 93 + 33). Callers must NOT feed quality for
- * reads that lack it — gate on {@link hasUsableQuality} and emit FASTA only,
- * rather than letting the 255 "no quality" sentinel clamp to a perfect '~'.
+ * Deliberately lenient (see AGENTS.md): never throws. No `SQ` block → empty sequence; a
+ * missing `//` between records flushes the previous one when the next `ID` appears; a
+ * truncated final record is flushed at EOF. Residue case is preserved as written.
+ */
+
+/** Read EMBL flat files (`.embl`/`.dat`): id = accession.version from the ID line. */
+declare function parseEmbl(input: string | Uint8Array): SeqRecord[];
+/** Read UniProtKB/Swiss-Prot flat files (`.dat`/`.txt`): id = primary AC accession. */
+declare function parseSwissprot(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * Record + option types for the FASTA / FASTQ / .qual family.
+ *
+ * These carry the sequence's data only — the residues and (FASTQ) the per-base
+ * Phred scores. A file's line wrapping and newline style are cosmetic: the readers
+ * discard them and the writers re-impose a chosen width. The same record shape is
+ * used symmetrically for reading and writing, so parse → edit → write round-trips
+ * the data (not the exact bytes).
  */
-/** Largest Phred score representable as Phred+33 ('~' = ASCII 126 = 93 + 33). */
-declare const MAX_PHRED = 93;
 /** A FASTA record: identifier, optional description, and residues. */
 interface FastaRecord {
-    /** Identifier written after '>', up to the first space. */
+    /** Identifier: the header text up to the first whitespace (the '>' is not included). */
     id: string;
-    /** Optional free text after the id on the header line. */
+    /** Free text after the id on the header line; absent when the header is just an id. */
     description?: string;
-    /** Residues, written verbatim (case and gaps preserved). */
+    /** Residues with all line breaks/whitespace removed; case and gap chars ('-', '.') preserved. */
     sequence: string;
 }
 /** A FASTQ record: a {@link FastaRecord} plus one Phred score per residue. */
 interface FastqRecord extends FastaRecord {
-    /** Per-base Phred scores; must be one per residue in {@link FastaRecord.sequence}. */
+    /** Per-base Phred scores decoded from the quality line (Phred+33), one per residue. */
     qualities: readonly number[];
 }
 /** A .qual record: identifier, optional description, and per-base Phred scores. */
@@ -40,6 +96,58 @@ interface WrapOptions {
     /** Residues (FASTA) or scores (.qual) per line; <= 0 writes one line. Default 60. */
     lineWidth?: number;
 }
+
+/**
+ * FASTA / FASTQ / .qual text codec: readers (parseFasta / parseFastq) and writers
+ * (formatFasta / formatFastq / formatQual).
+ *
+ * Text formats have no on-disk container, so there is no separate raw layer — this
+ * one file is the codec (the `<family>-format.ts` analog of `abif-format.ts`).
+ *
+ * Data only: the readers keep residues and per-base Phred scores and drop cosmetic
+ * formatting (line wrapping, blank lines, `\r\n` vs `\n`); the writers re-impose a
+ * chosen wrap width. Quality is Phred+33 (Sanger / Illumina 1.8+); scores are clamped
+ * to [0, {@link MAX_PHRED}] on write ('~' = ASCII 126 = 93 + 33).
+ */
+
+/** Largest Phred score representable as Phred+33 ('~' = ASCII 126 = 93 + 33). */
+declare const MAX_PHRED = 93;
+/**
+ * Parse FASTA text (or bytes) into records. Deliberately lenient — it never refuses a
+ * file: blank lines and legacy ';' comment lines are ignored, residue lines are
+ * concatenated with inner whitespace stripped (case and gaps preserved), and any stray
+ * text before the first '>' header is skipped. id = the header up to the first
+ * whitespace, description = the remainder.
+ */
+declare function parseFasta(input: string | Uint8Array): FastaRecord[];
+/**
+ * Parse FASTQ text (or bytes) into records with decoded Phred+33 qualities.
+ *
+ * Handles multi-line records: the sequence runs to the '+' separator, then the quality
+ * runs until it has as many chars as the sequence has residues. Length — not "the next
+ * line starting with @" — terminates the quality block, because a quality character can
+ * itself be '@' (Phred 31) or '+' (Phred 10); this is the one subtlety the spec calls
+ * out (Cock et al. 2010).
+ *
+ * Deliberately lenient — it never refuses a file, and never lets one malformed record
+ * cost a *following* one. A stray line where a '@' header is expected is skipped (resync
+ * at the next '@'); a record with no '+' separator (truncated, or the next record starts)
+ * keeps its sequence with unknown quality; a short/over-long or out-of-range quality is
+ * reconciled to the residue count in {@link makeFastq}. The sequence — what callers
+ * actually pick — is always preserved intact, for every record.
+ *
+ * Cross-record safety comes from recognizing a real next-record header structurally: a
+ * line beginning '@' is the next header (not this record's quality) when a '+' separator
+ * follows its sequence before any other '@' — see {@link startsRecord}. This is exact for
+ * strict 4-line FASTQ (the real-world norm, where a quality line is followed only by the
+ * next '@' header or EOF) and preserves every following record even when a quality block is
+ * badly truncated. The one accepted blind spot is a deliberate trade-off: '@' and '+' are
+ * both valid Phred+33 characters, so in *wrapped* multi-line quality a continuation line
+ * that begins '@' and is later followed (before the next header) by one beginning '+' is
+ * misread as a header. That pattern is vanishingly rare, and favoring "never drop the next
+ * record's sequence on truncated input" over it is the right call for this parser's use.
+ */
+declare function parseFastq(input: string | Uint8Array): FastqRecord[];
 /** Serialize one or more records to FASTA text (trailing newline included). */
 declare function formatFasta(records: FastaRecord | readonly FastaRecord[], options?: WrapOptions): string;
 /** Serialize one or more records to FASTQ text, Phred+33 (trailing newline included). */
@@ -53,4 +161,152 @@ declare function formatQual(records: QualRecord | readonly QualRecord[], options
  */
 declare function hasUsableQuality(qualities?: readonly number[]): boolean;
 
-export { type FastaRecord, type FastqRecord, MAX_PHRED, type QualRecord, type WrapOptions, formatFasta, formatFastq, formatQual, hasUsableQuality };
+/**
+ * GenBank / GenPept flat-file reader — sequence extraction only.
+ *
+ * Reads the sequence(s) and their identity out of GenBank flat files (`.gb`/`.gbk`/`.gbff`,
+ * and the protein `.gp` variant). One file may hold many records, each ending in `//`. We
+ * take what a "pick a sequence" caller needs and skip the rest:
+ *   - id: VERSION (accession.version) if present, else ACCESSION, else the LOCUS name.
+ *   - description: DEFINITION (its continuation lines joined).
+ *   - sequence: the ORIGIN block, with the leading base counters and spacing stripped.
+ * Feature-table parsing (locations, /translation, join/complement) is intentionally out of
+ * scope here — this is the sequence-reading path, not a full annotation model.
+ *
+ * Deliberately lenient (see AGENTS.md): never throws. A record with no ORIGIN yields an
+ * empty sequence rather than an error; a missing `//` between records (or a truncated final
+ * record) still yields every record whose LOCUS was seen. Sequence case is preserved as
+ * written (GenBank ORIGIN is conventionally lowercase).
+ */
+
+declare function parseGenbank(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * GFA (Graphical Fragment Assembly, `.gfa`) reader — sequence extraction.
+ *
+ * Assembly / pangenome graphs. Only Segment (`S`) lines carry sequence; links, paths, jumps and
+ * containments are graph topology and hold none. Both dialects are supported by field position:
+ *
+ *   GFA1:  S <name> <sequence> [tags…]
+ *   GFA2:  S <sid>  <slen>     <sequence> [tags…]
+ *
+ * GFA2 inserts an integer segment length between the name and the sequence, so when the field after
+ * the name is a bare integer AND another field follows, the sequence is that next field; otherwise
+ * it's the field right after the name (GFA1). A `*` sequence (a segment declared without residues)
+ * is skipped — there's nothing to pick. Lenient: never throws; malformed lines are ignored.
+ */
+
+declare function parseGfa(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * GFF3 (`.gff`/`.gff3`) reader — sequence extraction.
+ *
+ * A GFF3 file is annotation (feature coordinates), which carries NO sequence — except when it
+ * embeds a FASTA section after a `##FASTA` directive. This reader returns the records of that
+ * embedded FASTA and nothing else; a GFF with no `##FASTA` section yields `[]` (there is no
+ * sequence to pick). Feature lines are never turned into sequence.
+ */
+
+declare function parseGff(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * Multiple-sequence-alignment readers — one aligned row = one record.
+ *
+ * Covers the common alignment formats: Clustal (`.aln`), Stockholm (`.sto`/`.stk`),
+ * PHYLIP (`.phy`), NEXUS (`.nex`) and GCG/MSF (`.msf`). Each returns the alignment's rows
+ * as {@link SeqRecord}s: `id` = the taxon/sequence name, `sequence` = that row **with its
+ * gap characters preserved** (an aligned row is data; de-gapping is a caller's choice).
+ * Only line spacing and wrap are removed. No description field — these formats don't carry
+ * a per-row one.
+ *
+ * Deliberately lenient (see AGENTS.md): never throws, best-effort on malformed input, and
+ * always returns every row it can. Interleaved blocks are accumulated by name.
+ */
+
+/** Read a Clustal (`.aln`) alignment. Also handles the Clustal-format output of MUSCLE, MAFFT, etc. */
+declare function parseClustal(input: string | Uint8Array): SeqRecord[];
+/** Read a Stockholm (`.sto`/`.stk`) alignment; multiple `//`-separated alignments are all returned. */
+declare function parseStockholm(input: string | Uint8Array): SeqRecord[];
+/**
+ * Read a PHYLIP (`.phy`) alignment. Supports relaxed (whitespace-delimited names) interleaved
+ * and single-block layouts — the common modern output (RAxML/PhyML/aligners). The first line is
+ * `<ntax> <nchar>`; the next `ntax` non-blank lines carry names + the first block; any further
+ * non-blank lines are interleaved continuation, appended round-robin and clipped at `nchar` so a
+ * stray line can't overrun residues into another taxon.
+ *
+ * Limitation: multi-line *sequential* PHYLIP (each taxon's whole sequence spanning consecutive
+ * lines before the next taxon) is read as interleaved and would be misassigned; it is rare next to
+ * interleaved output. Single-line sequential (one line per taxon) reads correctly.
+ */
+declare function parsePhylip(input: string | Uint8Array): SeqRecord[];
+/**
+ * Read a NEXUS (`.nex`) DATA/CHARACTERS block's MATRIX. Handles interleaved matrices (names
+ * repeat across blocks), space-grouped rows, and a final row that closes the matrix with `;`.
+ *
+ * Not resolved (kept verbatim / unsupported): `FORMAT MATCHCHAR=.` — a `.` meaning "same residue
+ * as the first taxon here" is left literal rather than substituted; and label-less matrices
+ * (`FORMAT LABELS=NO`, relying on TAXLABELS order) whose rows carry no name are skipped.
+ */
+declare function parseNexus(input: string | Uint8Array): SeqRecord[];
+/** Read a GCG/MSF (`.msf`) alignment (the sequence blocks after the header's `//`). */
+declare function parseMsf(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * PIR / NBRF (`.pir`) reader — sequence extraction.
+ *
+ * A PIR record is: a header `>XX;identifier` (the two-letter code XX is the sequence type —
+ * P1/F1 protein, DL/DC DNA, RL/RC RNA, N1/N3 nucleotide, XX other), a free-text title line,
+ * then the residues, terminated by `*`. One file may hold many records.
+ *   - id: the identifier after the `;` (or the whole header when there is no `;`).
+ *   - description: the title line.
+ *   - sequence: the residues with spacing removed and the single trailing `*` terminator dropped.
+ *
+ * Deliberately lenient (see AGENTS.md): never throws; a truncated record (no `*`) keeps its
+ * residues; the first line after a header is taken as the title.
+ */
+
+declare function parsePir(input: string | Uint8Array): SeqRecord[];
+
+/**
+ * BAM (`.bam`) reader — read-sequence extraction from the binary alignment format.
+ *
+ * BAM is the binary twin of SAM. On disk it is BGZF-compressed (a gzip stream of concatenated
+ * blocks); this reader expects the INFLATED bytes — starting with the "BAM\1" magic. The caller
+ * peels the gzip/BGZF wrapper first (a gzip decompressor decodes BGZF's concatenated members), so
+ * this stays a synchronous, dependency-free binary parser.
+ *
+ * Semantics mirror the SAM reader exactly (see {@link parseSam}): one sequence per read (secondary
+ * 0x100 / supplementary 0x800 skipped), reverse-strand sequence stored verbatim (reference-forward),
+ * id = read name (+ /1,/2 for paired mates), description = "RNAME:POS (+/-)" or "unmapped". Records
+ * without a stored sequence (l_seq = 0) are skipped. Lenient: on any truncation or garble it stops
+ * and returns what it parsed cleanly, never throwing.
+ */
+
+declare function parseBam(bytes: Uint8Array): SeqRecord[];
+
+/**
+ * SAM (`.sam`) reader — read-sequence extraction.
+ *
+ * SAM is a read-alignment format: one record per alignment, tab-delimited, with 11 mandatory
+ * fields (QNAME FLAG RNAME POS MAPQ CIGAR RNEXT PNEXT TLEN SEQ QUAL). This reader returns each
+ * record's read sequence — field 10, `SEQ`. Records whose SEQ is `*` (sequence not stored) are
+ * skipped: there's nothing to pick.
+ *
+ * The sequence is returned VERBATIM as written. For a reverse-strand alignment (FLAG bit 0x10) SAM
+ * already stores the reverse complement (reference-forward orientation), so that reference-oriented
+ * sequence is what you get — it is deliberately not un-flipped to the original read orientation.
+ *
+ * One sequence per read: secondary (FLAG 0x100) and supplementary (0x800) alignments are skipped —
+ * they re-map the same read (a duplicate, or a hard-clipped split fragment), which would pollute a
+ * "pick the sequences" list. What's kept is the read's SEQ from its primary (or unmapped) record —
+ * i.e. the sequence as SAM stores it, which for a hard-clipped primary alignment omits the clipped
+ * flanks rather than reconstructing the original full read.
+ *
+ * `@`-prefixed lines are skipped as headers — the SAM spec's QNAME charset `[!-?A-~]` excludes '@'
+ * (0x40) precisely so a read name can never be confused with a header. Lenient: never throws; lines
+ * with fewer than 11 fields are ignored rather than rejected.
+ */
+
+declare function parseSam(input: string | Uint8Array): SeqRecord[];
+
+export { type FastaRecord, type FastqRecord, MAX_PHRED, type QualRecord, type SeqFileFormat, type SeqRecord, type WrapOptions, detectFormat, formatFasta, formatFastq, formatQual, hasUsableQuality, makeSeqRecord, parseBam, parseClustal, parseEmbl, parseFasta, parseFastq, parseGenbank, parseGfa, parseGff, parseMsf, parseNexus, parsePhylip, parsePir, parseSam, parseStockholm, parseSwissprot };