@gmod/gbz-base 0.0.1

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Colin Diesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The test graphs under test/data derive from the gbwt-rs test data
+(https://github.com/jltsiren/gbwt-rs, MIT License, Copyright (c) Jouni Sirén),
+converted with unmodified gbz-base (https://github.com/jltsiren/gbz-base, MIT).

package/README.md

@@ -0,0 +1,125 @@
+# @gmod/gbz-base
+
+A pure TypeScript reader for [gbz-base](https://github.com/jltsiren/gbz-base)
+pangenome databases (`.gbz.db`). It answers the same subgraph queries as
+`gbz-base query`, reading only the SQLite pages a query touches, so a
+multi-gigabyte database on an HTTP server is queried through range requests
+without downloading it or compiling anything to WebAssembly.
+
+No SQLite library is involved. The reader walks the SQLite b-trees directly
+(rowid lookups, index seeks, overflow chains) and decodes the GBWT node records
+the same way gbwt-rs does. Databases are produced by unmodified upstream
+`gbz-base construct`.
+
+## Usage
+
+```ts
+import { RemoteFile } from 'generic-filehandle2'
+import { GBZBase, subgraphInInterval } from '@gmod/gbz-base'
+
+const db = await GBZBase.open(
+  new RemoteFile('https://example.org/graph.gbz.db'),
+)
+const subgraph = await subgraphInInterval(
+  db,
+  { sample: 'GRCh38', contig: 'chr6' },
+  31500000,
+  31501000,
+  { context: 0, haplotypes: 'all' },
+)
+const { nodes, edges, paths } = subgraph.toJSON(true)
+```
+
+`paths[0]` is the reference interval, named `GRCh38#0#chr6[start-end]`. Every
+other entry is one haplotype's walk through the subgraph with a `cigar` relative
+to the reference, computed like upstream: a node-length-weighted LCS, with the
+diverging stretches scored using vg's match, mismatch and gap parameters.
+
+Any object with `read(length, position)` and `stat()` works as a source, so
+`LocalFile`, `RemoteFile` and `BlobFile` from `generic-filehandle2` all do.
+Pages are fetched in blocks (64 KiB by default, `blockSize` in the open options)
+and cached.
+
+The command line mirrors the upstream tool for the query types it supports:
+
+```
+gbz-base-query graph.gbz.db --sample GRCh38 --contig chr6 --interval 31500000..31501000 --cigar
+gbz-base-query https://host/graph.gbz.db --contig chrM --offset 1000 --context 50 --stats
+```
+
+`--stats` reports how many range requests a query made and how many bytes they
+carried.
+
+## Naming haplotypes
+
+Upstream gbz-base cannot say which haplotype a subgraph path belongs to, so it
+emits `unknown#N`. This package adds that with two side tables that a small Rust
+tool writes into an existing database, built on the unmodified upstream crates:
+
+```
+cd tools/haplotype-index && cargo build --release
+./target/release/gbz-haplotype-index --interval 4096 graph.gbz graph.gbz.db
+./target/release/gbz-haplotype-index --interval 4096 --from-db graph.gbz.db
+```
+
+The second form walks the paths through the database's own node records, so
+a database whose GBZ is no longer at hand can still be augmented; the two
+forms write identical tables.
+
+`HaplotypeSamples` holds one GBWT position every `--interval` bp along every
+path in both orientations, with the path handle and the forward coordinate of
+that node, and `HaplotypeLengths` holds each path's length. The upstream `query`
+binary keeps working on the augmented database.
+
+At query time `subgraph.identifyPaths()` loads the samples for the window's node
+range in one index scan, chains each haplotype's fragments to the next through
+the private nodes between them, and walks at most one interval past the window
+for a chain that met no sample inside it. `subgraph.alignments()` then gives one
+record per fragment: PanSN name, strand, haplotype interval in that contig's
+coordinates, reference interval, and a CIGAR clipped to the fragment's own
+reference span. `toJSON(cigar, { names: 'resolved' })` names the paths the same
+way. On the command line, `--resolve` and `--alignments`.
+
+The tests check every resolved fragment against an independent backward walk
+through the bidirectional GBWT to the path's recorded start position.
+
+## Fidelity
+
+`test/data/oracle/` holds JSON written by upstream `gbz-base query` for the
+queries listed in `queries.txt`, over databases built from gbwt-rs's test graphs
+(`micb-kir3dl1.gbz`, a 46-sample HPRC slice; `example.gbz`; `example-v3.gbz`).
+The test suite requires this library's output to be deep equal to every one of
+them, CIGAR strings included. `generate.sh` regenerates the oracle with an
+upstream binary.
+
+Not ported: snarl extension (`--snarls`, `--between`), GFA output, GAF-base.
+
+CIGARs are computed by matching each shared node to its earliest usable
+occurrence on the reference walk, which is weight-optimal whenever every shared
+node can be placed in order; the Myers-based weighted LCS from gbwt-rs runs only
+for the fragments where that fails (inversions, repeats). The two can pick
+different equal-weight alignments only when the reference walk repeats a node.
+
+## Measured
+
+Against a 134 MB HPRC chr20 `.gbz.db` served over HTTPS,
+`--sample GRCh38 --contig chr20`:
+
+| window | context | nodes | haplotype fragments | range requests | bytes read | time  |
+| ------ | ------- | ----- | ------------------- | -------------- | ---------- | ----- |
+| 500 bp | 0       | 17    | 11                  | 7              | 459 KB     | 1.4 s |
+| 10 kb  | 0       | 627   | 1021                | 8              | 524 KB     | 2.1 s |
+| 100 kb | 0       | 2051  | 3673                | 13             | 852 KB     | 1.7 s |
+| 10 kb  | 100 bp  | 1086  | 35                  | 9              | 590 KB     | 0.8 s |
+
+Most of the wall time in the small queries is sequential request latency, not
+decoding.
+
+## Footnote
+
+Started from ideas at MemPanG 26! Earlier work considered WASM cross compilation
+of the rust code but gbwt-rs and simple-sds serialize `usize` at native width,
+so their wasm32 builds misread files written on 64-bit hosts, and the maintainer
+declined a 32-bit port. wasm64 fixes that for gbwt-rs but cannot carry gbz-base,
+whose bundled SQLite has no wasm64 libc. A TypeScript reader has neither problem
+and runs in a JBrowse RPC worker with the file access layer JBrowse already has.

package/bin/query.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../dist/cli.js'
+
+main(process.argv.slice(2)).catch(error => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+  process.exit(1)
+})

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,140 @@
+import { LocalFile, RemoteFile } from 'generic-filehandle2';
+import { GBZBase, formatPathName } from "./db.js";
+import { subgraphAroundNodes, subgraphAtOffset, subgraphInInterval } from "./query.js";
+const USAGE = `Usage: gbz-base-query [options] graph.gbz.db
+
+  --sample STR         sample name (default: generic path)
+  --contig STR         contig name (required for --offset and --interval)
+  --haplotype INT      haplotype number (default: 0)
+  -o, --offset INT     sequence offset
+  -i, --interval A..B  half-open sequence interval
+  -n, --node INT       node identifier (may repeat)
+  --context INT        context length in bp (default: 100)
+  --limit INT          safety limit for the number of nodes
+  --haplotypes SEL     all, distinct, reference-only or none (default: all)
+  --cigar              output CIGAR strings for the haplotypes
+  --resolve            name haplotypes from the HaplotypeSamples table
+  --alignments         print one alignment record per haplotype fragment instead of the subgraph
+  --block-size INT     bytes fetched per range request (default: 65536)
+  --stats              print fetch statistics to stderr
+`;
+function parseArgs(argv) {
+    const args = {
+        file: '',
+        haplotype: 0,
+        nodes: [],
+        context: 100,
+        haplotypes: 'all',
+        cigar: false,
+        resolve: false,
+        alignments: false,
+        blockSize: 65536,
+        stats: false,
+    };
+    const next = (i) => {
+        const value = argv[i + 1];
+        if (value === undefined) {
+            throw new Error(`${argv[i]} needs a value`);
+        }
+        return value;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--sample':
+                args.sample = next(i++);
+                break;
+            case '--contig':
+                args.contig = next(i++);
+                break;
+            case '--haplotype':
+                args.haplotype = Number(next(i++));
+                break;
+            case '-o':
+            case '--offset':
+                args.offset = Number(next(i++));
+                break;
+            case '-i':
+            case '--interval': {
+                const [a, b] = next(i++).split('..');
+                args.interval = [Number(a), Number(b)];
+                break;
+            }
+            case '-n':
+            case '--node':
+                args.nodes.push(Number(next(i++)));
+                break;
+            case '--context':
+                args.context = Number(next(i++));
+                break;
+            case '--limit':
+                args.limit = Number(next(i++));
+                break;
+            case '--haplotypes':
+                args.haplotypes = next(i++);
+                break;
+            case '--cigar':
+                args.cigar = true;
+                break;
+            case '--resolve':
+                args.resolve = true;
+                break;
+            case '--alignments':
+                args.alignments = true;
+                args.resolve = true;
+                break;
+            case '--block-size':
+                args.blockSize = Number(next(i++));
+                break;
+            case '--stats':
+                args.stats = true;
+                break;
+            case '--format':
+                next(i++);
+                break;
+            case '-h':
+            case '--help':
+                process.stdout.write(USAGE);
+                process.exit(0);
+                break;
+            default:
+                if (arg.startsWith('-')) {
+                    throw new Error(`Unknown option ${arg}`);
+                }
+                args.file = arg;
+        }
+    }
+    if (!args.file) {
+        throw new Error(USAGE);
+    }
+    return args;
+}
+export async function main(argv) {
+    const args = parseArgs(argv);
+    const source = /^https?:\/\//.test(args.file) ? new RemoteFile(args.file) : new LocalFile(args.file);
+    const db = await GBZBase.open(source, { blockSize: args.blockSize });
+    const opts = { context: args.context, haplotypes: args.haplotypes, ...(args.limit === undefined ? {} : { limit: args.limit }) };
+    const query = { contig: args.contig ?? '', haplotype: args.haplotype, ...(args.sample === undefined ? {} : { sample: args.sample }) };
+    const subgraph = args.nodes.length > 0
+        ? await subgraphAroundNodes(db, args.nodes, opts)
+        : args.interval
+            ? await subgraphInInterval(db, query, args.interval[0], args.interval[1], opts)
+            : args.offset !== undefined
+                ? await subgraphAtOffset(db, query, args.offset, opts)
+                : undefined;
+    if (!subgraph) {
+        throw new Error('Query type must be specified using --offset, --interval or --node');
+    }
+    if (args.resolve) {
+        await subgraph.identifyPaths();
+    }
+    const output = args.alignments
+        ? subgraph.alignments().map(a => ({ ...a, name: a.name ? formatPathName(a.name, a.name.fragment) : undefined, start: undefined }))
+        : subgraph.toJSON(args.cigar, { names: args.resolve ? 'resolved' : 'anonymous' });
+    process.stdout.write(`${JSON.stringify(output)}\n`);
+    if (args.stats) {
+        const { fetches, bytesFetched } = db.sqlite.pager;
+        const { orderedAlignments, lcsAlignments, identificationSteps, identificationFetches } = subgraph.stats;
+        process.stderr.write(`Subgraph contains ${subgraph.nodeCount} nodes and ${subgraph.pathCount} paths; ${fetches} fetches, ${bytesFetched} bytes; ${orderedAlignments} ordered + ${lcsAlignments} lcs alignments; identification ${identificationSteps} steps, ${identificationFetches} lookups\n`);
+    }
+}

package/dist/db.d.ts

@@ -0,0 +1,72 @@
+import type { ByteSource } from './filehandle.ts';
+import { GbwtRecord } from './gbwt/record.ts';
+import type { Pos } from './gbwt/record.ts';
+import { SqliteDatabase } from './sqlite/database.ts';
+import type { PagerOptions } from './sqlite/pager.ts';
+export interface PathName {
+    sample: string;
+    contig: string;
+    haplotype: number;
+    fragment: number;
+}
+export declare const GENERIC_SAMPLE = "_gbwt_ref";
+export declare const SCHEMA_VERSION = "GBZ-base version 4";
+export declare class SchemaVersionError extends Error {
+    readonly found: string | undefined;
+    name: string;
+    constructor(found: string | undefined);
+}
+export declare function formatPathName(name: PathName, end: number): string;
+export interface HaplotypeSample {
+    node: number;
+    offset: number;
+    pathHandle: number;
+    orientation: 'forward' | 'reverse';
+    pathOffset: number;
+}
+export interface GbzPath {
+    handle: number;
+    fwStart: Pos;
+    revStart: Pos;
+    name: PathName;
+    isIndexed: boolean;
+}
+export declare class GbzRecord {
+    readonly handle: number;
+    readonly edges: Pos[];
+    readonly bwt: Uint8Array;
+    readonly encodedSequence: Uint8Array;
+    readonly next: number | undefined;
+    readonly sequenceLen: number;
+    private decoded;
+    constructor(handle: number, edges: Pos[], bwt: Uint8Array, encodedSequence: Uint8Array, next: number | undefined);
+    get id(): number;
+    get orientation(): import("./gbwt/node.ts").Orientation;
+    get sequence(): string;
+    successors(): number[];
+    gbwt(): GbwtRecord;
+}
+export declare class GBZBase {
+    readonly sqlite: SqliteDatabase;
+    private tagCache;
+    private pathCache;
+    private constructor();
+    static open(source: ByteSource, opts?: PagerOptions): Promise<GBZBase>;
+    tags(): Promise<Map<string, string>>;
+    tag(key: string): Promise<string | undefined>;
+    getRecord(handle: number): Promise<GbzRecord | undefined>;
+    paths(): Promise<GbzPath[]>;
+    getPath(handle: number): Promise<GbzPath | undefined>;
+    findPath(name: PathName): Promise<GbzPath | undefined>;
+    pathsForSample(sample: string): Promise<GbzPath[]>;
+    get hasHaplotypeIndex(): boolean;
+    haplotypeSampleInterval(): Promise<number | undefined>;
+    private sampleFromRow;
+    haplotypeSamplesInRange(minHandle: number, maxHandle: number): Promise<HaplotypeSample[]>;
+    haplotypeSampleAt(node: number, offset: number): Promise<HaplotypeSample | undefined>;
+    haplotypeLength(pathHandle: number): Promise<number | undefined>;
+    indexedPosition(pathHandle: number, pathOffset: number): Promise<{
+        pathOffset: number;
+        pos: Pos;
+    } | undefined>;
+}

package/dist/db.js

@@ -0,0 +1,208 @@
+import { GbwtRecord, decompressEdges } from "./gbwt/record.js";
+import { ENDMARKER, nodeId, nodeOrientation } from "./gbwt/node.js";
+import { decodeSequence, encodedSequenceLength } from "./gbwt/sequence.js";
+import { SqliteDatabase } from "./sqlite/database.js";
+export const GENERIC_SAMPLE = '_gbwt_ref';
+export const SCHEMA_VERSION = 'GBZ-base version 4';
+export class SchemaVersionError extends Error {
+    found;
+    name = 'SchemaVersionError';
+    constructor(found) {
+        super(found === undefined
+            ? `not a gbz-base database: its Tags table has no version`
+            : `unsupported database schema "${found}"; this reader understands "${SCHEMA_VERSION}"`);
+        this.found = found;
+    }
+}
+export function formatPathName(name, end) {
+    return `${name.sample}#${name.haplotype}#${name.contig}[${name.fragment}-${end}]`;
+}
+export class GbzRecord {
+    handle;
+    edges;
+    bwt;
+    encodedSequence;
+    next;
+    sequenceLen;
+    decoded;
+    constructor(handle, edges, bwt, encodedSequence, next) {
+        this.handle = handle;
+        this.edges = edges;
+        this.bwt = bwt;
+        this.encodedSequence = encodedSequence;
+        this.next = next;
+        this.sequenceLen = encodedSequenceLength(encodedSequence);
+    }
+    get id() {
+        return nodeId(this.handle);
+    }
+    get orientation() {
+        return nodeOrientation(this.handle);
+    }
+    get sequence() {
+        this.decoded ??= decodeSequence(this.encodedSequence);
+        return this.decoded;
+    }
+    successors() {
+        return this.edges.filter(e => e.node !== ENDMARKER).map(e => e.node);
+    }
+    gbwt() {
+        if (this.edges.length === 0) {
+            throw new Error(`GBWT record for handle ${this.handle} is empty`);
+        }
+        return new GbwtRecord(this.edges, this.bwt);
+    }
+}
+function num(value, what) {
+    if (typeof value !== 'number') {
+        throw new Error(`${what} is not a number in the database`);
+    }
+    return value;
+}
+function str(value, what) {
+    if (typeof value !== 'string') {
+        throw new Error(`${what} is not text in the database`);
+    }
+    return value;
+}
+function blob(value, what) {
+    if (!(value instanceof Uint8Array)) {
+        throw new Error(`${what} is not a blob in the database`);
+    }
+    return value;
+}
+function rowToPath(rowid, values) {
+    return {
+        handle: rowid,
+        fwStart: { node: num(values[1], 'Paths.fw_node'), offset: num(values[2], 'Paths.fw_offset') },
+        revStart: { node: num(values[3], 'Paths.rev_node'), offset: num(values[4], 'Paths.rev_offset') },
+        name: {
+            sample: str(values[5], 'Paths.sample'),
+            contig: str(values[6], 'Paths.contig'),
+            haplotype: num(values[7], 'Paths.haplotype'),
+            fragment: num(values[8], 'Paths.fragment'),
+        },
+        isIndexed: num(values[9], 'Paths.is_indexed') !== 0,
+    };
+}
+export class GBZBase {
+    sqlite;
+    tagCache;
+    pathCache;
+    constructor(sqlite) {
+        this.sqlite = sqlite;
+    }
+    static async open(source, opts = {}) {
+        const sqlite = await SqliteDatabase.open(source, opts);
+        for (const table of ['Tags', 'Nodes', 'Paths', 'ReferenceIndex']) {
+            sqlite.rootPage(table);
+        }
+        const db = new GBZBase(sqlite);
+        const version = await db.tag('version');
+        if (version !== SCHEMA_VERSION) {
+            throw new SchemaVersionError(version);
+        }
+        return db;
+    }
+    tags() {
+        this.tagCache ??= (async () => {
+            const tags = new Map();
+            for await (const { values } of this.sqlite.scan('Tags')) {
+                tags.set(str(values[0], 'Tags.key'), str(values[1], 'Tags.value'));
+            }
+            return tags;
+        })();
+        return this.tagCache;
+    }
+    async tag(key) {
+        return (await this.tags()).get(key);
+    }
+    async getRecord(handle) {
+        const row = await this.sqlite.byRowid('Nodes', handle);
+        if (!row) {
+            return undefined;
+        }
+        const next = row[4];
+        return new GbzRecord(handle, decompressEdges(blob(row[1], 'Nodes.edges')), blob(row[2], 'Nodes.bwt'), blob(row[3], 'Nodes.sequence'), typeof next === 'number' ? next : undefined);
+    }
+    paths() {
+        this.pathCache ??= (async () => {
+            const paths = [];
+            for await (const { rowid, values } of this.sqlite.scan('Paths')) {
+                paths.push(rowToPath(rowid, values));
+            }
+            return paths;
+        })();
+        return this.pathCache;
+    }
+    async getPath(handle) {
+        const row = await this.sqlite.byRowid('Paths', handle);
+        return row ? rowToPath(handle, row) : undefined;
+    }
+    async findPath(name) {
+        const candidates = (await this.paths()).filter(p => p.name.sample === name.sample &&
+            p.name.contig === name.contig &&
+            p.name.haplotype === name.haplotype &&
+            p.name.fragment <= name.fragment);
+        return candidates.sort((a, b) => b.name.fragment - a.name.fragment)[0];
+    }
+    async pathsForSample(sample) {
+        return (await this.paths()).filter(p => p.name.sample === sample);
+    }
+    get hasHaplotypeIndex() {
+        return this.sqlite.has('HaplotypeSamples') && this.sqlite.has('HaplotypeLengths');
+    }
+    async haplotypeSampleInterval() {
+        const value = await this.tag('haplotype_index_interval');
+        return value === undefined ? undefined : Number(value);
+    }
+    sampleFromRow(values) {
+        return {
+            node: num(values[0], 'HaplotypeSamples.node_handle'),
+            offset: num(values[1], 'HaplotypeSamples.node_offset'),
+            pathHandle: num(values[2], 'HaplotypeSamples.path_handle'),
+            orientation: num(values[3], 'HaplotypeSamples.orientation') === 0 ? 'forward' : 'reverse',
+            pathOffset: num(values[4], 'HaplotypeSamples.path_offset'),
+        };
+    }
+    async haplotypeSamplesInRange(minHandle, maxHandle) {
+        const samples = [];
+        for await (const key of this.sqlite.indexScanFrom('HaplotypeSamples', [minHandle, 0])) {
+            const node = num(key[0], 'HaplotypeSamples.node_handle');
+            if (node > maxHandle) {
+                break;
+            }
+            const row = await this.sqlite.byRowid('HaplotypeSamples', num(key[2], 'HaplotypeSamples rowid'));
+            if (row) {
+                samples.push(this.sampleFromRow(row));
+            }
+        }
+        return samples;
+    }
+    async haplotypeSampleAt(node, offset) {
+        const key = await this.sqlite.indexSeekLE('HaplotypeSamples', [node, offset]);
+        if (!key || key[0] !== node || key[1] !== offset) {
+            return undefined;
+        }
+        const row = await this.sqlite.byRowid('HaplotypeSamples', num(key[2], 'HaplotypeSamples rowid'));
+        return row ? this.sampleFromRow(row) : undefined;
+    }
+    async haplotypeLength(pathHandle) {
+        const row = await this.sqlite.byRowid('HaplotypeLengths', pathHandle);
+        return row ? num(row[1], 'HaplotypeLengths.length') : undefined;
+    }
+    async indexedPosition(pathHandle, pathOffset) {
+        const key = await this.sqlite.indexSeekLE('ReferenceIndex', [pathHandle, pathOffset]);
+        if (!key || key[0] !== pathHandle) {
+            return undefined;
+        }
+        const row = await this.sqlite.byRowid('ReferenceIndex', num(key[2], 'ReferenceIndex rowid'));
+        if (!row) {
+            throw new Error('ReferenceIndex row referenced by its index is missing');
+        }
+        return {
+            pathOffset: num(row[1], 'ReferenceIndex.path_offset'),
+            pos: { node: num(row[2], 'ReferenceIndex.node_handle'), offset: num(row[3], 'ReferenceIndex.node_offset') },
+        };
+    }
+}

package/dist/filehandle.d.ts

@@ -0,0 +1,6 @@
+export interface ByteSource {
+    read(length: number, position: number): Promise<Uint8Array>;
+    stat(): Promise<{
+        size: number;
+    }>;
+}

package/dist/filehandle.js

@@ -0,0 +1 @@
+export {};

package/dist/gbwt/bytecode.d.ts

@@ -0,0 +1,20 @@
+export declare class ByteCodeReader {
+    private bytes;
+    offset: number;
+    constructor(bytes: Uint8Array);
+    get done(): boolean;
+    byte(): number | undefined;
+    int(): number | undefined;
+}
+export interface Run {
+    value: number;
+    len: number;
+}
+export declare class RunReader {
+    private source;
+    private sigma;
+    private threshold;
+    constructor(bytes: Uint8Array, sigma: number);
+    next(): Run | undefined;
+    [Symbol.iterator](): Generator<Run, void, unknown>;
+}

package/dist/gbwt/bytecode.js

@@ -0,0 +1,70 @@
+export class ByteCodeReader {
+    bytes;
+    offset = 0;
+    constructor(bytes) {
+        this.bytes = bytes;
+    }
+    get done() {
+        return this.offset >= this.bytes.length;
+    }
+    byte() {
+        const value = this.bytes[this.offset];
+        if (value === undefined) {
+            return undefined;
+        }
+        this.offset += 1;
+        return value;
+    }
+    int() {
+        let shift = 1;
+        let result = 0;
+        while (this.offset < this.bytes.length) {
+            const value = this.bytes[this.offset];
+            this.offset += 1;
+            result += (value & 0x7f) * shift;
+            shift *= 128;
+            if ((value & 0x80) === 0) {
+                return result;
+            }
+        }
+        return undefined;
+    }
+}
+const RLE_THRESHOLD = 255;
+const RLE_UNIVERSE = 256;
+export class RunReader {
+    source;
+    sigma;
+    threshold;
+    constructor(bytes, sigma) {
+        this.source = new ByteCodeReader(bytes);
+        this.sigma = sigma === 0 ? Number.MAX_SAFE_INTEGER : sigma;
+        this.threshold = this.sigma < RLE_THRESHOLD ? Math.floor(RLE_UNIVERSE / this.sigma) : 0;
+    }
+    next() {
+        if (this.sigma >= RLE_THRESHOLD) {
+            const value = this.source.int();
+            const len = this.source.int();
+            return value === undefined || len === undefined ? undefined : { value, len: len + 1 };
+        }
+        const byte = this.source.byte();
+        if (byte === undefined) {
+            return undefined;
+        }
+        const value = byte % this.sigma;
+        let len = Math.floor(byte / this.sigma) + 1;
+        if (len === this.threshold) {
+            const extra = this.source.int();
+            if (extra === undefined) {
+                return undefined;
+            }
+            len += extra;
+        }
+        return { value, len };
+    }
+    *[Symbol.iterator]() {
+        for (let run = this.next(); run !== undefined; run = this.next()) {
+            yield run;
+        }
+    }
+}