@jbrowse/cigar-utils 4.1.14

package/esm/cigarRenderedSegments.js

@@ -0,0 +1,84 @@
+import { CIGAR_D, CIGAR_EQ, CIGAR_I, CIGAR_M, CIGAR_N, CIGAR_X, } from './cigarConstants.js';
+// Indels narrower than this (in pixels) are merged into surrounding match
+// context rather than rendered as separate quads. At 1px an indel resolving to
+// a single pixel still renders — small on-screen detail is intentionally kept.
+// The old 2px floor guarded against 1bp-indel aliasing on noisy long reads, but
+// the synteny/dotplot CIGAR fill now fades sub-pixel indels by their true MSAA
+// coverage instead of aliasing, so a genuinely sub-pixel indel fades honestly
+// rather than flickering. A 1bp indel in a whole-chromosome view is far below
+// 1px and still drops out here, as intended.
+const MIN_INDEL_PX = 1;
+/**
+ * Walks pre-parsed (packed int) CIGAR ops in bp-space and fires a callback
+ * for each rendered segment. Small indels (width < MIN_INDEL_PX) are merged
+ * into surrounding context; tiny M segments (both accumulators advance <
+ * bpPerPx) are accumulated before emitting.
+ *
+ * Used by synteny and dotplot GPU renderers so both stay in sync.
+ * Re-exported via @jbrowse/synteny-core for consistent import paths.
+ *
+ * Callback receives bp-space segment boundaries (cumBp, no inter-region
+ * padding). Callers convert to screen positions with hp-math.
+ */
+export function visitCigarRenderedSegments(cigar, startBp1, startBp2, bpPerPx0, bpPerPx1, rev1, rev2, callback) {
+    let continuingFlag = false;
+    let segBp1Start = startBp1;
+    let segBp2Start = startBp2;
+    let bp1 = startBp1;
+    let bp2 = startBp2;
+    for (let j = 0; j < cigar.length; j++) {
+        const packed = cigar[j];
+        const len = packed >>> 4;
+        const op = packed & 0xf;
+        if (!continuingFlag) {
+            segBp1Start = bp1;
+            segBp2Start = bp2;
+        }
+        if (op === CIGAR_M || op === CIGAR_EQ || op === CIGAR_X) {
+            bp1 += len * rev1;
+            bp2 += len * rev2;
+        }
+        else if (op === CIGAR_D || op === CIGAR_N) {
+            bp1 += len * rev1;
+        }
+        else if (op === CIGAR_I) {
+            bp2 += len * rev2;
+        }
+        if (op === CIGAR_D || op === CIGAR_N || op === CIGAR_I) {
+            const relevantBpPerPx = op === CIGAR_I ? bpPerPx1 : bpPerPx0;
+            if (len < relevantBpPerPx * MIN_INDEL_PX) {
+                continuingFlag = true;
+                continue;
+            }
+        }
+        const isNotLast = j < cigar.length - 1;
+        if (Math.abs(bp1 - segBp1Start) <= bpPerPx0 &&
+            Math.abs(bp2 - segBp2Start) <= bpPerPx1 &&
+            isNotLast) {
+            continuingFlag = true;
+        }
+        else {
+            const span1 = Math.abs(bp1 - segBp1Start);
+            const span2 = Math.abs(bp2 - segBp2Start);
+            const resolvedOp = span1 > bpPerPx0 || span2 > bpPerPx1 ? op : CIGAR_M;
+            continuingFlag = false;
+            callback(resolvedOp, segBp1Start, bp1, segBp2Start, bp2);
+        }
+    }
+    // The merge above `continue`s PAST the flush, so a sub-pixel indel as the very
+    // last op leaves the open segment unvisited: the `isNotLast` escape hatch that
+    // forces a final emit is in the branch the `continue` skipped. The tail is
+    // usually a base or two, but it is bounded only by how long a run of sub-pixel
+    // indels the CIGAR ends with — 1000 trailing 1bp deletions at 100bp/px is 10px
+    // of query axis that never reaches the callback, so a clipped block ending in
+    // an indel run lost its trailing location markers, and in transparent-indels
+    // mode its base tile too (a hole, since a tiled feature draws no full-span
+    // base under it).
+    //
+    // Emitted as CIGAR_M rather than through the resolvedOp expression above: every
+    // op merged into this segment was individually judged sub-pixel, so the last
+    // one's kind is the wrong label for a span that may be mostly match.
+    if (continuingFlag) {
+        callback(CIGAR_M, segBp1Start, bp1, segBp2Start, bp2);
+    }
+}

package/esm/cigarReorient.d.ts

@@ -0,0 +1,2 @@
+export declare function flipCigar(cigar: string): string;
+export declare function swapIndelCigar(cigar: string): string;

package/esm/cigarReorient.js

@@ -0,0 +1,29 @@
+// Reverse a CIGAR's op order and swap insertions<->deletions. Used to view an
+// alignment from the opposite (query<->target) perspective on the reverse
+// strand, where both the direction and the indel sense flip.
+export function flipCigar(cigar) {
+    const ops = [];
+    let len = 0;
+    for (let i = 0, l = cigar.length; i < l; i++) {
+        const c = cigar[i];
+        if (c >= '0' && c <= '9') {
+            len = len * 10 + (c.charCodeAt(0) - 48);
+        }
+        else {
+            ops.push([len, c]);
+            len = 0;
+        }
+    }
+    let result = '';
+    for (let i = ops.length - 1; i >= 0; i--) {
+        const [l, op] = ops[i];
+        result += l;
+        result += op === 'D' ? 'I' : op === 'I' ? 'D' : op;
+    }
+    return result;
+}
+// Swap insertions<->deletions in place, leaving op order untouched. This is the
+// +-strand query<->target perspective flip, where only the indel sense reverses.
+export function swapIndelCigar(cigar) {
+    return cigar.replaceAll(/[DI]/g, op => (op === 'D' ? 'I' : 'D'));
+}

package/esm/cigarToMismatches2.d.ts

@@ -0,0 +1,2 @@
+import type { Mismatch } from './mismatchTypes.ts';
+export declare function cigarToMismatches2(ops: ArrayLike<number>, seq?: string, ref?: string, qual?: Uint8Array): Mismatch[];

package/esm/cigarToMismatches2.js

@@ -0,0 +1,90 @@
+import { CIGAR_D, CIGAR_EQ, CIGAR_H, CIGAR_I, CIGAR_M, CIGAR_N, CIGAR_S, CIGAR_X, } from './cigarConstants.js';
+// Handles packed NUMERIC_CIGAR format from @gmod/bam
+// Format: Uint32Array where each value is (length << 4) | opIndex
+// opIndex is 0-8: M=0, I=1, D=2, N=3, S=4, H=5, P=6, ==7, X=8
+export function cigarToMismatches2(ops, seq, ref, qual) {
+    let roffset = 0;
+    let soffset = 0;
+    const mismatches = [];
+    const hasRefAndSeq = ref && seq;
+    for (let i = 0, l = ops.length; i < l; i++) {
+        const packed = ops[i];
+        const len = packed >>> 4;
+        const op = packed & 0xf;
+        if (op === CIGAR_M || op === CIGAR_EQ) {
+            if (hasRefAndSeq) {
+                for (let j = 0; j < len; j++) {
+                    if ((seq.charCodeAt(soffset + j) | 0x20) !==
+                        (ref.charCodeAt(roffset + j) | 0x20)) {
+                        mismatches.push({
+                            start: roffset + j,
+                            type: 'mismatch',
+                            base: seq[soffset + j],
+                            altbase: ref[roffset + j],
+                            length: 1,
+                        });
+                    }
+                }
+            }
+            soffset += len;
+            roffset += len;
+        }
+        else if (op === CIGAR_I) {
+            mismatches.push({
+                start: roffset,
+                type: 'insertion',
+                insertlen: len,
+                insertedBases: seq?.slice(soffset, soffset + len),
+                length: 0,
+            });
+            soffset += len;
+        }
+        else if (op === CIGAR_D) {
+            mismatches.push({
+                start: roffset,
+                type: 'deletion',
+                length: len,
+            });
+            roffset += len;
+        }
+        else if (op === CIGAR_N) {
+            mismatches.push({
+                start: roffset,
+                type: 'skip',
+                length: len,
+            });
+            roffset += len;
+        }
+        else if (op === CIGAR_X) {
+            for (let j = 0; j < len; j++) {
+                mismatches.push({
+                    start: roffset + j,
+                    type: 'mismatch',
+                    base: seq?.[soffset + j] || 'X',
+                    qual: qual?.[soffset + j],
+                    length: 1,
+                });
+            }
+            soffset += len;
+            roffset += len;
+        }
+        else if (op === CIGAR_H) {
+            mismatches.push({
+                start: roffset,
+                type: 'hardclip',
+                cliplen: len,
+                length: 1,
+            });
+        }
+        else if (op === CIGAR_S) {
+            mismatches.push({
+                start: roffset,
+                type: 'softclip',
+                cliplen: len,
+                length: 1,
+            });
+            soffset += len;
+        }
+    }
+    return mismatches;
+}

package/esm/cigarWalkStart.d.ts

@@ -0,0 +1,4 @@
+export declare function cigarWalkBp1(p11: number, p12: number, strand: number): number;
+export declare function cigarWalkBp2(p21: number, p22: number, strand: number): number;
+export declare function cigarWalkRev1(p11: number, p12: number, strand: number): -1 | 1;
+export declare function cigarWalkRev2(p21: number, p22: number, strand: number): number;

package/esm/cigarWalkStart.js

@@ -0,0 +1,54 @@
+// Where a comparative feature's CIGAR walk begins, and which way each axis
+// steps — the four arguments `visitCigarRenderedSegments` cannot derive for
+// itself, since it is handed bare coordinates. Named for the parameters they
+// feed: `bp1`/`rev1` are the anchor axis, `bp2`/`rev2` the mate.
+//
+// Both comparative views project a feature into the same four cumBp lanes: p11
+// -> p12 is the anchor's span in the DRAWN direction (their workers swap the
+// two for a reverse-strand feature so a ribbon crosses and a dotplot line runs
+// anti-diagonal), and p21 -> p22 is the mate's, always start -> end.
+//
+// That swap is exactly what makes the walk's start corner not the (p11, p21)
+// one. PAF writes a '-' strand `cg` in ANCHOR-FORWARD order with the mate
+// walking backward, so op 0 sits at (anchor start, mate end) — which after the
+// swap is (p12, p22). Beginning at (p11, p21) and stepping backward instead
+// traverses the same line and lands on the same endpoints, so the drawn shape's
+// extent is right and only the interior is wrong: every indel comes out
+// mirrored through the block's centre. `clipSyntenyFeature` documents the same
+// failure from the other side ("a deletion lands at its mirror-image position"),
+// and the dotplot shipped it for real.
+//
+// Region orientation is read off the endpoints rather than assumed — an axis
+// showing a reversed displayed region (auto-diagonalize flips query regions)
+// lays out with cumBp decreasing, and that is independent of strand. Strand
+// decides only which END the walk starts from.
+//
+// FOUR SCALARS, not one object, and that is measured:
+// `plugins/dotplot-view/benches/cigarWalkStart.bench.ts` A/Bs the two against
+// the loop that calls them. Returning `{bp1, bp2, rev1, rev2}` costs 1.43-1.46x
+// on the derivation in isolation — V8 does not scalar-replace it — and shows as
+// ~1.07x against a 1.02 control on a realistic geometry pass. These come back at
+// or below the control on the same rows. Same shape and same reason as
+// `dotplotProject.ts`'s `cumBpToPxH`/`cumBpToPxV`, which sit in the loop next
+// door. Recomputing the strand test in each is what buys that; it is two
+// compares.
+//
+// **Call them behind the caller's own draw-detail gate**, not above it. A
+// feature too narrow to walk is drawn as one flat line and never asks where its
+// CIGAR would have started, and at whole-genome zoom that is nearly all of them
+// — the worker ships CIGARs within 8x zoom headroom that the geometry builder is
+// then too zoomed out to walk. Hoisting the derivation above the gate, which is
+// how both call sites had it, cost the same bench 1.26x (0.794 the other way) at
+// 98% flat.
+export function cigarWalkBp1(p11, p12, strand) {
+    return strand === -1 ? p12 : p11;
+}
+export function cigarWalkBp2(p21, p22, strand) {
+    return strand === -1 ? p22 : p21;
+}
+export function cigarWalkRev1(p11, p12, strand) {
+    return (strand === -1 ? p12 < p11 : p11 < p12) ? 1 : -1;
+}
+export function cigarWalkRev2(p21, p22, strand) {
+    return (p21 < p22 ? 1 : -1) * (strand === -1 ? -1 : 1);
+}

package/esm/csOps.d.ts

@@ -0,0 +1,47 @@
+import type { MismatchCallback } from './mismatchCallback.ts';
+/** An operation of the minimap2 `cs` grammar. */
+export type CsOp = ':' | '=' | '*' | '+' | '-' | '~';
+/**
+ * Walk a minimap2 `cs` difference string
+ * (https://github.com/lh3/minimap2#cs), calling `callback` once per operation.
+ *
+ * Short form is `:N` match run, `*ab` substitution (ref base a, query base b),
+ * `+seq` insertion, `-seq` deletion; long form adds `=SEQ` match runs; `~ab12cd`
+ * is a 12 bp intron between the given splice motifs. A character belonging to
+ * none of those is skipped, so a truncated or extended string still walks to the
+ * end rather than throwing.
+ *
+ * `refLen`/`queryLen` are the bases the operation consumes on each sequence, and
+ * `[seqStart, seqEnd)` bounds its operand *within `cs`* — the bases for `=`/`+`/
+ * `-`, the two substituted bases for `*`, the digits for `:`, the whole motif
+ * for `~`. Offsets rather than a substring because the mismatch walk runs per
+ * feature per frame, and only two of six ops ever need the text.
+ *
+ * **One walker, because four disagreed.** This replaces a copy in each of
+ * `csToCigar`, `flipCs`, `forEachCsMismatch` and the (now removed) `visitCsOps`,
+ * and every one of the divergences was silent: two of them dropped `~` and then
+ * mis-scanned the rest of the string, one ignored `=SEQ` entirely and so never
+ * advanced the reference across a long-form match run, and the three that
+ * scanned `+`/`-` operands disagreed on where one ends.
+ */
+export declare function forEachCsOp(cs: string, callback: (op: CsOp, refLen: number, queryLen: number, seqStart: number, seqEnd: number) => void): void;
+/**
+ * Rewrite a cs string from the target perspective to the query perspective (for
+ * a synteny view anchored on the query assembly): `*ab` -> `*ba`, `+seq` ->
+ * `-seq`, `-seq` -> `+seq`, match runs unchanged.
+ *
+ * Undefined when the string states something the query perspective cannot: an
+ * intron is a gap in the *reference*, and flipped it becomes a gap in the query
+ * with no sequence to write for it, which cs has no way to express. Callers fall
+ * back to the CIGAR there, the same as they already do for reverse-strand
+ * alignments (which additionally need a reverse-complement).
+ */
+export declare function flipCs(cs: string): string | undefined;
+/**
+ * Walk a cs string and drive a {@link MismatchCallback} (the contract BAM/CRAM
+ * features use), emitting per-base substitutions with their real query base plus
+ * insertions, deletions and introns. Offsets are relative to the reference
+ * (feature) start; `windowStart`/`windowEnd` (also reference-relative) clip the
+ * output.
+ */
+export declare function forEachCsMismatch(cs: string, callback: MismatchCallback, windowStart?: number, windowEnd?: number): void;

package/esm/csOps.js

@@ -0,0 +1,152 @@
+import { DELETION_TYPE, INSERTION_TYPE, MISMATCH_TYPE, SKIP_TYPE, } from './mismatchCallback.js';
+function isDigit(code) {
+    return code >= 48 && code <= 57;
+}
+function isBaseChar(ch) {
+    return ch !== undefined && /[A-Za-z]/.test(ch);
+}
+function scanBases(cs, start) {
+    let i = start;
+    while (i < cs.length && isBaseChar(cs[i])) {
+        i++;
+    }
+    return i;
+}
+function scanDigits(cs, start) {
+    let i = start;
+    let value = 0;
+    while (i < cs.length && isDigit(cs.charCodeAt(i))) {
+        value = value * 10 + (cs.charCodeAt(i) - 48);
+        i++;
+    }
+    return { value, next: i };
+}
+/**
+ * Walk a minimap2 `cs` difference string
+ * (https://github.com/lh3/minimap2#cs), calling `callback` once per operation.
+ *
+ * Short form is `:N` match run, `*ab` substitution (ref base a, query base b),
+ * `+seq` insertion, `-seq` deletion; long form adds `=SEQ` match runs; `~ab12cd`
+ * is a 12 bp intron between the given splice motifs. A character belonging to
+ * none of those is skipped, so a truncated or extended string still walks to the
+ * end rather than throwing.
+ *
+ * `refLen`/`queryLen` are the bases the operation consumes on each sequence, and
+ * `[seqStart, seqEnd)` bounds its operand *within `cs`* — the bases for `=`/`+`/
+ * `-`, the two substituted bases for `*`, the digits for `:`, the whole motif
+ * for `~`. Offsets rather than a substring because the mismatch walk runs per
+ * feature per frame, and only two of six ops ever need the text.
+ *
+ * **One walker, because four disagreed.** This replaces a copy in each of
+ * `csToCigar`, `flipCs`, `forEachCsMismatch` and the (now removed) `visitCsOps`,
+ * and every one of the divergences was silent: two of them dropped `~` and then
+ * mis-scanned the rest of the string, one ignored `=SEQ` entirely and so never
+ * advanced the reference across a long-form match run, and the three that
+ * scanned `+`/`-` operands disagreed on where one ends.
+ */
+export function forEachCsOp(cs, callback) {
+    let i = 0;
+    while (i < cs.length) {
+        const c = cs[i];
+        if (c === ':') {
+            const { value, next } = scanDigits(cs, i + 1);
+            callback(':', value, value, i + 1, next);
+            i = next;
+        }
+        else if (c === '=') {
+            const next = scanBases(cs, i + 1);
+            const len = next - i - 1;
+            callback('=', len, len, i + 1, next);
+            i = next;
+        }
+        else if (c === '*') {
+            callback('*', 1, 1, i + 1, Math.min(i + 3, cs.length));
+            i += 3;
+        }
+        else if (c === '+' || c === '-') {
+            const next = scanBases(cs, i + 1);
+            const len = next - i - 1;
+            callback(c, c === '-' ? len : 0, c === '+' ? len : 0, i + 1, next);
+            i = next;
+        }
+        else if (c === '~') {
+            // the length sits between two 2-base splice motifs
+            const { value, next } = scanDigits(cs, i + 3);
+            const end = Math.min(next + 2, cs.length);
+            callback('~', value, 0, i + 1, end);
+            i = end;
+        }
+        else {
+            i++;
+        }
+    }
+}
+/**
+ * Rewrite a cs string from the target perspective to the query perspective (for
+ * a synteny view anchored on the query assembly): `*ab` -> `*ba`, `+seq` ->
+ * `-seq`, `-seq` -> `+seq`, match runs unchanged.
+ *
+ * Undefined when the string states something the query perspective cannot: an
+ * intron is a gap in the *reference*, and flipped it becomes a gap in the query
+ * with no sequence to write for it, which cs has no way to express. Callers fall
+ * back to the CIGAR there, the same as they already do for reverse-strand
+ * alignments (which additionally need a reverse-complement).
+ */
+export function flipCs(cs) {
+    // The one op with no query-perspective form, and cs writes it nowhere else —
+    // operands are base letters. Answered before the walk so the rewrite below is
+    // total.
+    if (cs.includes('~')) {
+        return undefined;
+    }
+    let result = '';
+    forEachCsOp(cs, (op, refLen, _queryLen, seqStart, seqEnd) => {
+        if (op === ':') {
+            result += `:${refLen}`;
+        }
+        else if (op === '=') {
+            result += `=${cs.slice(seqStart, seqEnd)}`;
+        }
+        else if (op === '*') {
+            result += `*${cs[seqStart + 1] ?? ''}${cs[seqStart] ?? ''}`;
+        }
+        else {
+            result += `${op === '+' ? '-' : '+'}${cs.slice(seqStart, seqEnd)}`;
+        }
+    });
+    return result;
+}
+/**
+ * Walk a cs string and drive a {@link MismatchCallback} (the contract BAM/CRAM
+ * features use), emitting per-base substitutions with their real query base plus
+ * insertions, deletions and introns. Offsets are relative to the reference
+ * (feature) start; `windowStart`/`windowEnd` (also reference-relative) clip the
+ * output.
+ */
+export function forEachCsMismatch(cs, callback, windowStart, windowEnd) {
+    const lo = windowStart ?? Number.NEGATIVE_INFINITY;
+    const hi = windowEnd ?? Number.POSITIVE_INFINITY;
+    let ref = 0;
+    forEachCsOp(cs, (op, refLen, queryLen, seqStart, seqEnd) => {
+        if (op === '*') {
+            if (ref >= lo && ref < hi) {
+                callback(MISMATCH_TYPE, ref, 1, cs[seqStart + 1] ?? '', -1, 0, 0);
+            }
+        }
+        else if (op === '+') {
+            if (ref >= lo && ref <= hi) {
+                const seq = cs.slice(seqStart, seqEnd);
+                callback(INSERTION_TYPE, ref, queryLen, seq, -1, 0, queryLen);
+            }
+        }
+        else if (op === '-' || op === '~') {
+            if (ref < hi && ref + refLen > lo) {
+                // an intron is a reference gap the read skips rather than deletes, and
+                // the two draw differently
+                const type = op === '-' ? DELETION_TYPE : SKIP_TYPE;
+                callback(type, ref, refLen, '', -1, 0, 0);
+            }
+        }
+        ref += refLen;
+    });
+}

package/esm/csToCigar.d.ts

@@ -0,0 +1 @@
+export declare function csToCigar(cs: string): string;

package/esm/csToCigar.js

@@ -0,0 +1,43 @@
+import { forEachCsOp } from './csOps.js';
+// Convert a minimap2 `cs` difference string to a standard CIGAR: matches -> `=`,
+// substitutions -> `X`, insertions -> `I`, deletions -> `D`, introns -> `N`.
+// Sequence bases are dropped so the result reorients with the same
+// flipCigar/swapIndelCigar helpers as a `cg` CIGAR. The grammar itself is
+// forEachCsOp's; this is only the op mapping.
+export function csToCigar(cs) {
+    const ops = [];
+    function push(len, op) {
+        if (len > 0) {
+            const last = ops[ops.length - 1];
+            if (last?.[1] === op) {
+                last[0] += len;
+            }
+            else {
+                ops.push([len, op]);
+            }
+        }
+    }
+    forEachCsOp(cs, (op, refLen, queryLen) => {
+        if (op === '*') {
+            push(1, 'X');
+        }
+        else if (op === '+') {
+            push(queryLen, 'I');
+        }
+        else if (op === '-') {
+            push(refLen, 'D');
+        }
+        else if (op === '~') {
+            push(refLen, 'N');
+        }
+        else {
+            push(refLen, '=');
+        }
+    });
+    let result = '';
+    for (const [len, op] of ops) {
+        result += len;
+        result += op;
+    }
+    return result;
+}

package/esm/getNextRefPos.d.ts

@@ -0,0 +1,31 @@
+/**
+ * #api
+ * Maps read-sequence positions to reference-sequence positions via the CIGAR,
+ * invoking the callback for each. Handles both packed Uint32Array and unpacked
+ * number[] CIGAR formats.
+ *
+ * **Driven by the POSITIONS, not by the read bases.** This used to run an inner
+ * loop over every base an op spans, testing `positions[currPos] === readPos + j`
+ * — so it was O(read length) to find something O(positions) in size. On the full
+ * extent of `200x.longread.mod.bam` that is 43.7 Mbp of read sequence scanned to
+ * place 0.84M modification calls. Within one op the read-to-reference offset is
+ * a constant, so each position's answer is one addition and the ops only have to
+ * be walked once: O(positions + ops).
+ * `plugins/alignments/benches/cigarWalkShape.bench.ts` prices it at **1.17x on
+ * the whole per-read modification pipeline**, of which this walk is 45%.
+ *
+ * **1.17x is the whole of it, and does not grow on a cleaner alignment.** The
+ * first reading of that gap was that the op loop caps it — these reads carry
+ * 7,000 ops apiece, and neither shape avoids the op loop. `cigarOpDensity.bench.ts`
+ * sweeps op density over a 5,000x range and the ratio stays between 1.10x and
+ * 1.18x, so that reading was wrong: what this phase is bound by is the per-CALL
+ * work both shapes share — the callback, the ML lookup, the compare, the write —
+ * not the traversal that differs. Changing how the scan is shaped therefore has a
+ * low ceiling here, however lopsided the iteration counts look.
+ *
+ * `positions` must be ASCENDING, which every caller's producer guarantees. The
+ * one behaviour that changed with the shape: a REPEATED position used to be
+ * dropped and to block every position after it (the per-base loop could match at
+ * most one position per base offset), and now emits once per occurrence.
+ */
+export declare function getNextRefPos(cigarOps: ArrayLike<number>, positions: number[], callback: (ref: number, idx: number) => void): void;

package/esm/getNextRefPos.js

@@ -0,0 +1,69 @@
+// get relative reference sequence positions for positions given relative to
+// the read sequence
+import { CIGAR_D, CIGAR_EQ, CIGAR_I, CIGAR_M, CIGAR_N, CIGAR_S, CIGAR_X, } from './cigarConstants.js';
+/**
+ * #api
+ * Maps read-sequence positions to reference-sequence positions via the CIGAR,
+ * invoking the callback for each. Handles both packed Uint32Array and unpacked
+ * number[] CIGAR formats.
+ *
+ * **Driven by the POSITIONS, not by the read bases.** This used to run an inner
+ * loop over every base an op spans, testing `positions[currPos] === readPos + j`
+ * — so it was O(read length) to find something O(positions) in size. On the full
+ * extent of `200x.longread.mod.bam` that is 43.7 Mbp of read sequence scanned to
+ * place 0.84M modification calls. Within one op the read-to-reference offset is
+ * a constant, so each position's answer is one addition and the ops only have to
+ * be walked once: O(positions + ops).
+ * `plugins/alignments/benches/cigarWalkShape.bench.ts` prices it at **1.17x on
+ * the whole per-read modification pipeline**, of which this walk is 45%.
+ *
+ * **1.17x is the whole of it, and does not grow on a cleaner alignment.** The
+ * first reading of that gap was that the op loop caps it — these reads carry
+ * 7,000 ops apiece, and neither shape avoids the op loop. `cigarOpDensity.bench.ts`
+ * sweeps op density over a 5,000x range and the ratio stays between 1.10x and
+ * 1.18x, so that reading was wrong: what this phase is bound by is the per-CALL
+ * work both shapes share — the callback, the ML lookup, the compare, the write —
+ * not the traversal that differs. Changing how the scan is shaped therefore has a
+ * low ceiling here, however lopsided the iteration counts look.
+ *
+ * `positions` must be ASCENDING, which every caller's producer guarantees. The
+ * one behaviour that changed with the shape: a REPEATED position used to be
+ * dropped and to block every position after it (the per-base loop could match at
+ * most one position per base offset), and now emits once per occurrence.
+ */
+export function getNextRefPos(cigarOps, positions, callback) {
+    const l2 = positions.length;
+    if (l2 === 0) {
+        return;
+    }
+    let readPos = 0;
+    let refPos = 0;
+    let currPos = 0;
+    for (let i = 0, l = cigarOps.length; i < l && currPos < l2; i++) {
+        const packed = cigarOps[i];
+        const len = packed >>> 4;
+        const op = packed & 0xf;
+        if (op === CIGAR_S || op === CIGAR_I) {
+            // Consumes read but not reference: skip the positions that land in it.
+            const readEnd = readPos + len;
+            while (currPos < l2 && positions[currPos] < readEnd) {
+                currPos++;
+            }
+            readPos = readEnd;
+        }
+        else if (op === CIGAR_D || op === CIGAR_N) {
+            refPos += len;
+        }
+        else if (op === CIGAR_M || op === CIGAR_X || op === CIGAR_EQ) {
+            const readEnd = readPos + len;
+            // Constant across the op, so placing a position is one add.
+            const delta = refPos - readPos;
+            while (currPos < l2 && positions[currPos] < readEnd) {
+                callback(positions[currPos] + delta, currPos);
+                currPos++;
+            }
+            readPos = readEnd;
+            refPos += len;
+        }
+    }
+}

package/esm/index.d.ts

@@ -0,0 +1,24 @@
+export { CIGAR_D, CIGAR_EQ, CIGAR_H, CIGAR_I, CIGAR_INDEL_MASK, CIGAR_M, CIGAR_M_EQ_MASK, CIGAR_N, CIGAR_P, CIGAR_S, CIGAR_X, } from './cigarConstants.ts';
+export { CHAR_FROM_CODE, SEQRET, SEQRET_NUMERIC_DECODER, } from './bamSeqDecoder.ts';
+export { encodeSeqNumeric } from './bamSeqEncoder.ts';
+export { flipCigar, swapIndelCigar } from './cigarReorient.ts';
+export { csToCigar } from './csToCigar.ts';
+export { flipCs, forEachCsMismatch, forEachCsOp } from './csOps.ts';
+export type { CsOp } from './csOps.ts';
+export { orientAlignment } from './orientAlignment.ts';
+export { pafIdentity } from './pafIdentity.ts';
+export { DELETION_TYPE, HARDCLIP_TYPE, INSERTION_TYPE, MISMATCH_TYPE, SKIP_TYPE, SOFTCLIP_TYPE, } from './mismatchCallback.ts';
+export type { MismatchCallback, MismatchWindow } from './mismatchCallback.ts';
+export { visitCigarRenderedSegments } from './cigarRenderedSegments.ts';
+export { cigarWalkBp1, cigarWalkBp2, cigarWalkRev1, cigarWalkRev2, } from './cigarWalkStart.ts';
+export { cigarToMismatches2 } from './cigarToMismatches2.ts';
+export { mdToMismatches2 } from './mdToMismatches2.ts';
+export { getNextRefPos } from './getNextRefPos.ts';
+export { numericCigarHasSkip } from './numericCigarHasSkip.ts';
+export { numericCigarToString } from './numericCigarToString.ts';
+export { connectionEndpointBps, readLeadingBodyDir, readLeadingBp, readTrailingBodyDir, readTrailingBp, } from './readEndpoints.ts';
+export { clipLengthAtStartOfReadNumeric, featurizeSA, featurizeSAEntries, getClip, getLength, getLengthOnRef, getLengthSansClipping, getMismatches, parseCigar2, parseCigar2Typed, parseCigar, splitSA, } from './mismatchParser.ts';
+export type { ClipMismatch, DeletionMismatch, InsertionMismatch, Mismatch, SNPMismatch, SkipMismatch, } from './mismatchTypes.ts';
+export { buildReadVsRefFeatures } from './buildReadVsRefFeatures.ts';
+export type { ReadVsRefFeature, ReadVsRefFeatures, ReadVsRefInput, ReadVsRefMate, } from './buildReadVsRefFeatures.ts';
+export { SAM_FLAG_DUPLICATE, SAM_FLAG_FAILS_QC, SAM_FLAG_FIRST_IN_PAIR, SAM_FLAG_MATE_REVERSE, SAM_FLAG_MATE_UNMAPPED, SAM_FLAG_PAIRED, SAM_FLAG_PROPER_PAIR, SAM_FLAG_REVERSE, SAM_FLAG_SECONDARY, SAM_FLAG_SECOND_IN_PAIR, SAM_FLAG_SUPPLEMENTARY, SAM_FLAG_UNMAPPED, samFlagDescriptions, samFlagLabels, samFlagNames, } from './samFlags.ts';