nucleotide-sequence

nucleotide-sequence is a JavaScript/TypeScript library for Node.js and the Browser that provides functions for manipulating and analyzing DNA and RNA sequences. It uses Uint8Array to represent sequences internally.

Installation

npm install nucleotide-sequence

Basic Usage

import { Seq, Translation, Alignment } from 'nucleotide-sequence';

// Initialize and read a sequence
const dna = new Seq('DNA').read('ATGCGTACGTTAG');

// Reverse Complement
const revComp = dna.reverseComplement();
console.log(revComp.sequence());

// Translation to Amino Acids (NCBI Table 1)
const protein = Translation.translate(dna);

// Pairwise Sequence Alignment (Smith-Waterman)
const ref = new Seq().read('ATGCGTACGT');
const result = Alignment.smithWaterman(dna, ref, { match: 2, mismatch: -1 });
console.log(`Alignment Score: ${result.score}`);

API Reference

Seq

The core class for wrapping and manipulating nucleotide sequences.

• read(sequence: string): Parses a string into a Uint8Array sequence, ignoring whitespace.
• static readFASTA(content: string): Parses a FASTA string and returns an array of Seq objects. Loads all records into memory; not suitable for gigabyte-scale genomic assemblies.
• static readFASTQ(content: string): Parses a FASTQ string and returns an array of Seq objects.
• reverseComplement(): Returns a new Seq object containing the reverse complement, supporting IUPAC degenerate bases.
• kmers(k: number): Returns a Generator yielding Uint8Array subarrays of length k. Yields strand-specific, overlapping substrings (not canonical k-mers).
• gcContent(): Computes the global GC percentage (0.0 to 1.0) based on exact G/C/S bases. Degenerate bases like 'N' are ignored.
• gcSkew(windowSize?: number): Calculates (G-C)/(G+C) across sliding windows.
• hammingDistance(other: Seq): Computes the Hamming distance between two sequences of equal length.
• meltingTemperatureNN(naConc?, kConc?, trisConc?, mgConc?, dNTPs?, seqConc?): Computes primer Melting Temperature (Tm) using the SantaLucia (1998) Nearest-Neighbor parameters. Corrects for monovalent cations (Na, K, Tris). The Mg²⁺ formula is a generic proxy coefficient and NOT the rigorous Owczarzy 2008 correction.
• molecularWeight({ phosphorylated?: boolean }): Computes mass using explicit exact IUPAC atomic masses (C, H, N, O, P). Perfectly mirrors Biopython's molecular weight algorithm for 5'-phosphorylated DNA/RNA, and provides exactly derived $HPO_3$ analytical subtraction for 5'-OH sequences.

Parsers

• static parseFASTAStream(stream: AsyncIterable<Buffer> | ReadableStream): Parses FASTA asynchronously, emitting Sequence events. O(chunk-size) memory bound.
• static parseFASTQEvents(stream: AsyncIterable<Buffer> | ReadableStream): Parses FASTQ asynchronously, validating strict sequence vs quality length bounds immediately. O(chunk-size) memory bound.

Translation

• static translate(seq: Seq, tableId?: number): Translates a DNA/RNA sequence into an amino acid string using NCBI Translation Tables. Supports Standard (1), Vertebrate Mitochondrial (2), and Bacterial/Archaeal/Plant Plastid (11).
• static findOpenReadingFrames(seq: Seq, minCodons?: number, tableId?: number): Scans all 6 biological reading frames (1, 2, 3 and -1, -2, -3) extracting nested structural ORFs. Supports alternative initiation codons under appropriate tables.

Alignment

• static smithWaterman(query: Seq, reference: Seq, options?: AlignmentOptions): Performs local pairwise sequence alignment. Memory scales $O(\min(m, n))$ during score-only operations, allowing extreme sequence disparities.
• static needlemanWunsch(query: Seq, reference: Seq, options?: AlignmentOptions): Performs global pairwise sequence alignment via dynamic programming. Note: Alignments utilize configurable integer match/mismatch scores and affine gap penalties.

CrisprScoring

• static findSpacers(seq: Seq, pam?: string, spacerLength?: number): Identifies structural Protospacer Adjacent Motifs (PAMs) on both strands via regex. Does not evaluate chromatin accessibility.
• static calculateOnTargetScoreProxy(spacer: string): Calculates an on-target efficiency score proxy based on a simplified positional weight matrix. This is NOT a published Rule Set 2/Azimuth score.
• static calculateCFDScoreProxy(guide: string, offTarget: string): Calculates an off-target cutting proxy using static positional penalties. This is NOT the published Doench CFD model.

SubstringSearch

• constructor(query: Seq, reference: Seq): Initializes an exact substring search tool.
• top(limit?: number): Returns ungapped matches tolerant to N wildcards using an $O(M \times N)$ sliding window. Highly optimal for short amplicons and plasmids, but intractable for mapping short reads to whole genomes.

FormatSAM

• static parse(samContent: string): Parses Sequence Alignment/Map (SAM) text into an array of structured SAMRecord objects. Extracts standard fields but does not process bitwise FLAG semantics or CIGAR clipping operations.

Parallel

Requires the optional peer dependency zeroworker.

• static align(query: Seq, references: Seq[], options?: AlignmentOptions): Distributes pairwise alignments across a multithreaded Web Worker pool using zeroworker.
• static kmerCount(seq: Seq, k: number, chunks?: number): Computes k-mer frequencies using a Web Worker pool.

License

MIT License