@gmod/bam 1.1.17 → 2.0.0

package/CHANGELOG.md

@@ -1,6 +1,22 @@
-## [1.1.17](https://github.com/GMOD/bam-js/compare/v1.1.16...v1.1.17) (2022-07-18)
+# [2.0.0](https://github.com/GMOD/bam-js/compare/v1.1.18...v2.0.0) (2023-06-08)
+
+
+### Features
+
+* explicit buffer import ([#98](https://github.com/GMOD/bam-js/issues/98)) ([66de9f4](https://github.com/GMOD/bam-js/commit/66de9f4ce30e3ff647d5297f093695e92ec9227c))
+
 
 
+- Add explicit buffer import
+- Remove cross-fetch and object.entries polyfills
+- Improve typescripting
+- Remove chunkSizeLimit and fetchSizeLimit
+
+## [1.1.18](https://github.com/GMOD/bam-js/compare/v1.1.17...v1.1.18) (2022-12-17)
+
+- Use es2015 for nodejs build
+
+## [1.1.17](https://github.com/GMOD/bam-js/compare/v1.1.16...v1.1.17) (2022-07-18)
 
 - Bump devDeps and generic-filehandle to 3.0.0
 
@@ -10,7 +26,8 @@
 
 ## [1.1.15](https://github.com/GMOD/bam-js/compare/v1.1.14...v1.1.15) (2022-03-18)
 
-- Fix for htsget failing with message 'input must be buffer, number, or string, received object'
+- Fix for htsget failing with message 'input must be buffer, number, or string,
+  received object'
 - Speed improvement by caching chunks of features
 
 ## [1.1.14](https://github.com/GMOD/bam-js/compare/v1.1.13...v1.1.14) (2022-03-14)
@@ -25,7 +42,8 @@
 
 ## [1.1.12](https://github.com/GMOD/bam-js/compare/v1.1.11...v1.1.12) (2022-02-17)
 
-- Add blocksForRange method to BamFile class to help stats estimation in JBrowse 2
+- Add blocksForRange method to BamFile class to help stats estimation in JBrowse
+  2
 
 <a name="1.1.11"></a>
 
@@ -45,7 +63,8 @@
 ## [1.1.9](https://github.com/GMOD/bam-js/compare/v1.1.8...v1.1.9) (2021-12-14)
 
 - Add ESM module export in package.json (smaller bundle size for consumers)
-- Cache BAI readFile result for compatibility with node.js native filehandles (which otherwise fail if re-reading the filehandle twice)
+- Cache BAI readFile result for compatibility with node.js native filehandles
+  (which otherwise fail if re-reading the filehandle twice)
 
 <a name="1.1.8"></a>
 
@@ -63,7 +82,8 @@
 
 ## [1.1.6](https://github.com/GMOD/bam-js/compare/v1.1.5...v1.1.6) (2021-02-20)
 
-- Add qualRaw function on records for getting raw qual score array instead of string
+- Add qualRaw function on records for getting raw qual score array instead of
+  string
 
 <a name="1.1.5"></a>
 
@@ -76,7 +96,8 @@
 ## [1.1.4](https://github.com/GMOD/bam-js/compare/v1.1.3...v1.1.4) (2020-12-11)
 
 - Add canMergeBlocks to CSI code (already existed in BAI)
-- Add suggestion from @jrobinso about reg2bins modification for memory saving (Thanks!)
+- Add suggestion from @jrobinso about reg2bins modification for memory saving
+  (Thanks!)
 - Add getHeaderText() method for getting a text string of the header data
 
 <a name="1.1.3"></a>
@@ -115,7 +136,8 @@
 ## [1.0.41](https://github.com/GMOD/bam-js/compare/v1.0.40...v1.0.41) (2020-08-19)
 
 - Add htsget example
-- Support opts object to getHeader allowing things like auth headers to be passed right off the bat
+- Support opts object to getHeader allowing things like auth headers to be
+  passed right off the bat
 
 <a name="1.0.40"></a>
 
@@ -125,14 +147,16 @@
 
 ## [1.0.39](https://github.com/GMOD/bam-js/compare/v1.0.38...v1.0.39) (2020-07-30)
 
-- Don't use origin master in the follow-tags postpublish command for cleaner version publishing
+- Don't use origin master in the follow-tags postpublish command for cleaner
+  version publishing
 
 <a name="1.0.38"></a>
 
 ## [1.0.38](https://github.com/GMOD/bam-js/compare/v1.0.37...v1.0.38) (2020-07-30)
 
 - Direct construction of qual/seq toString
-- Improve performance of the uniqueID calculation for pathological cases where there are tons of bins
+- Improve performance of the uniqueID calculation for pathological cases where
+  there are tons of bins
 
 <a name="1.0.37"></a>
 
@@ -144,31 +168,36 @@
 
 ## [1.0.36](https://github.com/GMOD/bam-js/compare/v1.0.35...v1.0.36) (2020-03-05)
 
-- Adds a shortcut to stop parsing chunks after a record is detected to be outside the requested range while decoding
+- Adds a shortcut to stop parsing chunks after a record is detected to be
+  outside the requested range while decoding
 
 <a name="1.0.35"></a>
 
 ## [1.0.35](https://github.com/GMOD/bam-js/compare/v1.0.34...v1.0.35) (2020-02-04)
 
-- Update scheme used to calculate unique fileOffset based IDs using @gmod/bgzf-filehandle updates
+- Update scheme used to calculate unique fileOffset based IDs using
+  @gmod/bgzf-filehandle updates
 
 <a name="1.0.34"></a>
 
 ## [1.0.34](https://github.com/GMOD/bam-js/compare/v1.0.33...v1.0.34) (2020-01-24)
 
-- Small fix for using id() instead of .get('id') for weird SAM records containing ID field
+- Small fix for using id() instead of .get('id') for weird SAM records
+  containing ID field
 
 <a name="1.0.33"></a>
 
 ## [1.0.33](https://github.com/GMOD/bam-js/compare/v1.0.32...v1.0.33) (2020-01-24)
 
-- Perform decoding of entire chunk up front to aid caching, reverts change in 1.0.29
+- Perform decoding of entire chunk up front to aid caching, reverts change in
+  1.0.29
 
 <a name="1.0.32"></a>
 
 ## [1.0.32](https://github.com/GMOD/bam-js/compare/v1.0.31...v1.0.32) (2019-11-16)
 
-- Add a speed improvement for long reads by pre-allocating sequence/quality scores array
+- Add a speed improvement for long reads by pre-allocating sequence/quality
+  scores array
 
 <a name="1.0.31"></a>
 
@@ -186,7 +215,8 @@
 
 ## [1.0.29](https://github.com/GMOD/bam-js/compare/v1.0.28...v1.0.29) (2019-10-31)
 
-- Decoding of the BAM records at time of use instead of entire chunk decoded up front
+- Decoding of the BAM records at time of use instead of entire chunk decoded up
+  front
 - Alternate chunk merging strategy inspired by igv.js code
 
 <a name="1.0.28"></a>
@@ -239,32 +269,40 @@
 
 ## [1.0.21](https://github.com/GMOD/bam-js/compare/v1.0.20...v1.0.21) (2019-08-06)
 
-- Add a fix for the small chunk unpacking re-seeking in the same bgzf block repeatedly (#35)
+- Add a fix for the small chunk unpacking re-seeking in the same bgzf block
+  repeatedly (#35)
 
 <a name="1.0.20"></a>
 
 ## [1.0.20](https://github.com/GMOD/bam-js/compare/v1.0.19...v1.0.20) (2019-06-06)
 
-- Added a method for smaller chunk unpacking, by modifying the header parsing to return smaller chunks and the bgzf unzipping to respect chunk boundaries (#30)
-- Use fileOffset as bam feature ID which previously was crc32 of the BAM buffer which consequently speeds up processing and allows exact duplicate features
+- Added a method for smaller chunk unpacking, by modifying the header parsing to
+  return smaller chunks and the bgzf unzipping to respect chunk boundaries (#30)
+- Use fileOffset as bam feature ID which previously was crc32 of the BAM buffer
+  which consequently speeds up processing and allows exact duplicate features
 
 ## [1.0.19](https://github.com/GMOD/bam-js/compare/v1.0.18...v1.0.19) (2019-05-30)
 
-- Added lineCount and hasRefSeq functions to BamFile, each accepting a string seqName
+- Added lineCount and hasRefSeq functions to BamFile, each accepting a string
+  seqName
 - Fixed aborting on index retrieval code
 
 ## [1.0.18](https://github.com/GMOD/bam-js/compare/v1.0.17...v1.0.18) (2019-05-01)
 
-- Bump generic-filehandle to 1.0.9 to fix error with using native fetch (global fetch needed to be bound)
-- Bump abortable-promise-cache to 1.0.1 version to fix error with using native fetch and abort signals
+- Bump generic-filehandle to 1.0.9 to fix error with using native fetch (global
+  fetch needed to be bound)
+- Bump abortable-promise-cache to 1.0.1 version to fix error with using native
+  fetch and abort signals
 
 ## [1.0.17](https://github.com/GMOD/bam-js/compare/v1.0.16...v1.0.17) (2019-04-28)
 
-- Fix wrong number of arguments being passed to the readRefSeqs file read() invocation resulting in bad range requests
+- Fix wrong number of arguments being passed to the readRefSeqs file read()
+  invocation resulting in bad range requests
 
 ## [1.0.16](https://github.com/GMOD/bam-js/compare/v1.0.15...v1.0.16) (2019-04-28)
 
-- Added indexCov algorithm to retrieve approximate coverage of the BAM inferred from the size of the BAI linear index bins
+- Added indexCov algorithm to retrieve approximate coverage of the BAM inferred
+  from the size of the BAI linear index bins
 - Fixed abortSignal on read() calls
 - Updated API to allow bamUrl/baiUrl/csiUrl
 
@@ -310,7 +348,8 @@
 ## [1.0.9](https://github.com/GMOD/bam-js/compare/v1.0.8...v1.0.9) (2018-11-16)
 
 - Allow bases other than ACGT to be decoded
-- Make viewAsPairs only resolve pairs on given refSeq unless pairAcrossChr is enabled for query
+- Make viewAsPairs only resolve pairs on given refSeq unless pairAcrossChr is
+  enabled for query
 
 <a name="1.0.8"></a>
 
@@ -328,7 +367,8 @@
 
 ## [1.0.6](https://github.com/GMOD/bam-js/compare/v1.0.5...v1.0.6) (2018-10-19)
 
-- Add bugfix for where bytes for an invalid request returns 0 resulting in pako unzip errors
+- Add bugfix for where bytes for an invalid request returns 0 resulting in pako
+  unzip errors
 
 <a name="1.0.5"></a>
 

package/README.md

@@ -1,35 +1,51 @@
 [![NPM version](https://img.shields.io/npm/v/@gmod/bam.svg?style=flat-square)](https://npmjs.org/package/@gmod/bam)
 [![Coverage Status](https://img.shields.io/codecov/c/github/GMOD/bam-js/master.svg?style=flat-square)](https://codecov.io/gh/GMOD/bam-js/branch/master)
-[![Build Status](https://img.shields.io/github/workflow/status/GMOD/bam-js/Push/master?logo=github&style=flat-query)](https://github.com/GMOD/bam-js/actions?query=branch%3Amaster+workflow%3APush+)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/GMOD/bam-js/push.yml?branch=master)](https://github.com/GMOD/bam-js/actions?query=branch%3Amaster+workflow%3APush+)
 
 ## Install
 
-    $ npm install --save @gmod/bam
+```bash
+$ npm install --save @gmod/bam
+```
 
 ## Usage
 
-```js
-const { BamFile } = require('@gmod/bam') // or import {BamFile} from '@gmod/bam'
+```typescript
+const { BamFile } = require('@gmod/bam')
+// or import {BamFile} from '@gmod/bam'
 
 const t = new BamFile({
   bamPath: 'test.bam',
 })
 
+// note: it's required to first run getHeader before any getRecordsForRange
 var header = await t.getHeader()
 
 // this would get same records as samtools view ctgA:1-50000
-var records = await t.getRecordsForRange('ctgA', 0, 49999)
+var records = await t.getRecordsForRange('ctgA', 0, 50000)
+```
+
+The `bamPath` argument only works on nodejs. In the browser, you should pass
+`bamFilehandle` with a generic-filehandle e.g. `RemoteFile`
+
+```typescript
+const { RemoteFile } = require('generic-filehandle')
+const bam = new BamFile({
+  bamFilehandle: new RemoteFile('yourfile.bam'), // or a full http url
+  baiFilehandle: new RemoteFile('yourfile.bam.bai'), // or a full http url
+})
 ```
 
-Input are 0-based half-open coordinates (note: not the same as samtools view coordinate inputs!)
+Input are 0-based half-open coordinates (note: not the same as samtools view
+coordinate inputs!)
 
 ## Usage with htsget
 
-Since 1.0.41 we support htsget!
+Since 1.0.41 we support usage of the htsget protocol
 
 Here is a small code snippet for this
 
-```js
+```typescript
 const { HtsgetFile } = require('@gmod/bam')
 
 const ti = new HtsgetFile({
@@ -40,62 +56,87 @@ await ti.getHeader()
 const records = await ti.getRecordsForRange(1, 2000000, 2000001)
 ```
 
+Our implementation makes some assumptions about how the protocol is implemented,
+so let us know if it doesn't work for your use case
+
 ## Documentation
 
 ### BAM constructor
 
 The BAM class constructor accepts arguments
 
-- bamPath/bamUrl/bamFilehandle - a string file path to a local file or a class object with a read method
-- csiPath/csiUrl/csiFilehandle - a CSI index for the BAM file, required for long chromosomes greater than 2^29 in length
-- baiPath/baiUrl/baiFilehandle - a BAI index for the BAM file
-- fetchSizeLimit - total size of the number of chunks being fetched at once. default: ~50MB
-- chunkSizeLimit - size limit on any individual chunk. default: ~10MB
-- cacheSize - limit on number of chunks to cache. default: 50
-- yieldThreadTime - the interval at which the code yields to the main thread when it is parsing a lot of data. default: 100ms. Set to 0 to performed no yielding
-
-Note: filehandles implement the Filehandle interface from https://www.npmjs.com/package/generic-filehandle. This module offers the path and url arguments as convenience methods for supplying the LocalFile and RemoteFile
+- `bamPath`/`bamUrl`/`bamFilehandle` - a string file path to a local file or a
+  class object with a read method
+- `csiPath`/`csiUrl`/`csiFilehandle` - a CSI index for the BAM file, required
+  for long chromosomes greater than 2^29 in length
+- `baiPath`/`baiUrl`/`baiFilehandle` - a BAI index for the BAM file
+- `cacheSize` - limit on number of chunks to cache. default: 50
+- `yieldThreadTime` - the interval at which the code yields to the main thread
+  when it is parsing a lot of data. default: 100ms. Set to 0 to performed no
+  yielding
+
+Note: filehandles implement the Filehandle interface from
+https://www.npmjs.com/package/generic-filehandle. This module offers the path
+and url arguments as convenience methods for supplying the LocalFile and
+RemoteFile
 
 ### async getRecordsForRange(refName, start, end, opts)
 
-- refName - a string for the chrom to fetch from
-- start - a 0 based half open start coordinate
-- end - a 0 based half open end coordinate
-- opts.signal - an AbortSignal to indicate stop processing
-- opts.viewAsPairs - re-dispatches requests to find mate pairs. default: false
-- opts.pairAcrossChr - control the viewAsPairs option behavior to pair across chromosomes. default: false
-- opts.maxInsertSize - control the viewAsPairs option behavior to limit distance within a chromosome to fetch. default: 200kb
+Note: you must run getHeader before running getRecordsForRange
 
-### async \*streamRecordsForRange(refName, start, end, opts)
+- `refName` - a string for the chrom to fetch from
+- `start` - a 0-based half open start coordinate
+- `end` - a 0-based half open end coordinate
+- `opts.signal` - an AbortSignal to indicate stop processing
+- `opts.viewAsPairs` - re-dispatches requests to find mate pairs. default: false
+- `opts.pairAcrossChr` - control the viewAsPairs option behavior to pair across
+  chromosomes. default: false
+- `opts.maxInsertSize` - control the viewAsPairs option behavior to limit
+  distance within a chromosome to fetch. default: 200kb
 
-This is a async generator function that takes the same signature as getRecordsForRange but results can be processed using
+### async \*streamRecordsForRange(refName, start, end, opts)
 
-    for await(const chunk of file.streamRecordsForRange(refName, start, end, opts)) {
-    }
+This is a async generator function that takes the same signature as
+`getRecordsForRange` but results can be processed using
+
+```typescript
+for await (const chunk of file.streamRecordsForRange(
+  refName,
+  start,
+  end,
+  opts,
+)) {
+}
+```
 
-The getRecordsForRange simply wraps this process by concatenating chunks into an array
+The `getRecordsForRange` simply wraps this process by concatenating chunks into
+an array
 
 ### async getHeader(opts: {....anything to pass to generic-filehandle opts})
 
-This obtains the header from HtsgetFile or BamFile. Retrieves BAM file and BAI/CSI header if applicable, or API request for refnames from htsget
+This obtains the header from `HtsgetFile` or `BamFile`. Retrieves BAM file and
+BAI/CSI header if applicable, or API request for refnames from htsget
 
 ### async indexCov(refName, start, end)
 
-- refName - a string for the chrom to fetch from
-- start - a 0 based half open start coordinate (optional)
-- end - a 0 based half open end coordinate (optional)
+- `refName` - a string for the chrom to fetch from
+- `start` - a 0-based half open start coordinate (optional)
+- `end` - a 0-based half open end coordinate (optional)
 
-Returns features of the form {start, end, score} containing estimated feature density across 16kb windows in the genome
+Returns features of the form {start, end, score} containing estimated feature
+density across 16kb windows in the genome
 
-### async lineCount(refName)
+### async lineCount(refName: string)
 
-- refName - a string for the chrom to fetch from
+- `refName` - a string for the chrom to fetch from
 
-Returns number of features on refName, uses special pseudo-bin from the BAI/CSI index (e.g. bin 37450 from bai, returning n_mapped from SAM spec pdf) or -1 if refName not exist in sample
+Returns number of features on refName, uses special pseudo-bin from the BAI/CSI
+index (e.g. bin 37450 from bai, returning n_mapped from SAM spec pdf) or -1 if
+refName not exist in sample
 
-### async hasRefSeq(refName)
+### async hasRefSeq(refName: string)
 
-- refName - a string for the chrom to check
+- `refName` - a string for the chrom to check
 
 Returns whether we have this refName in the sample
 
@@ -108,41 +149,51 @@ You can access data feature.get('field') to get the value of a feature attribute
 
 Example
 
-    feature.get('seq_id') // numerical sequence id corresponding to position in the sam header
-    feature.get('start') // 0 based half open start coordinate
-    feature.get('end') // 0 based half open end coordinate
+```typescript
+feature.get('seq_id') // numerical sequence id corresponding to position in the sam header
+feature.get('start') // 0-based half open start coordinate
+feature.get('end') // 0-based half open end coordinate
+```
 
 #### Fields
 
-    feature.get('name') // QNAME
-    feature.get('seq') // feature sequence
-    feature.get('qual') // qualities
-    feature.get('cigar') // cigar string
-    feature.get('MD') // MD string
-    feature.get('SA') // supplementary alignments
-    feature.get('template_length') // TLEN
-    feature.get('length_on_ref') // derived from CIGAR using standard algorithm
+```typescript
+feature.get('name') // QNAME
+feature.get('seq') // feature sequence
+feature.get('qual') // qualities
+feature.get('cigar') // cigar string
+feature.get('MD') // MD string
+feature.get('SA') // supplementary alignments
+feature.get('template_length') // TLEN
+feature.get('length_on_ref') // derived from CIGAR using standard algorithm
+```
 
 #### Flags
 
-    feature.get('flags') // see https://broadinstitute.github.io/picard/explain-flags.html
+```typescript
+feature.get('flags') // see https://broadinstitute.github.io/picard/explain-flags.html
+```
 
 #### Tags
 
 BAM tags such as MD can be obtained via
 
-    feature.get('MD')
+```typescript
+feature.get('MD')
+```
 
 A full list of tags that can be obtained can be obtained via
 
     feature._tags()
 
-The feature format may change in future versions to be more raw data records, but this will be a major version bump
+The feature format may change in future versions to be more raw data records,
+but this will be a major version bump
 
-## License
+#### Note
 
-MIT © [Colin Diesh](https://github.com/cmdcolin)
+The reason that we hide the data behind this ".get" function is that we lazily
+decode records on demand, which can reduce memory consumption.
 
-```
+## License
 
-```
+MIT © [Colin Diesh](https://github.com/cmdcolin)

package/dist/bai.d.ts

@@ -1,26 +1,45 @@
-/// <reference types="node" />
+import VirtualOffset from './virtualOffset';
 import Chunk from './chunk';
-import IndexFile from './indexFile';
 import { BaseOpts } from './util';
+import IndexFile from './indexFile';
 export default class BAI extends IndexFile {
-    baiP?: Promise<Buffer>;
-    parsePseudoBin(bytes: Buffer, offset: number): {
-        lineCount: number;
-    };
-    lineCount(refId: number, opts?: BaseOpts): Promise<any>;
-    fetchBai(opts?: BaseOpts): Promise<Buffer>;
-    _parse(): Promise<{
-        [key: string]: any;
+    setupP?: ReturnType<BAI['_parse']>;
+    lineCount(refId: number, opts?: BaseOpts): Promise<number>;
+    _parse(opts?: BaseOpts): Promise<{
+        bai: boolean;
+        firstDataLine: VirtualOffset | undefined;
+        maxBlockSize: number;
+        indices: {
+            binIndex: {
+                [key: string]: Chunk[];
+            };
+            linearIndex: VirtualOffset[];
+            stats?: {
+                lineCount: number;
+            } | undefined;
+        }[];
+        refCount: number;
     }>;
     indexCov(seqId: number, start?: number, end?: number, opts?: BaseOpts): Promise<{
         start: number;
         end: number;
         score: number;
     }[]>;
-    /**
-     * calculate the list of bins that may overlap with region [beg,end) (zero-based half-open)
-     * @returns {Array[number]}
-     */
-    reg2bins(beg: number, end: number): number[][];
     blocksForRange(refId: number, min: number, max: number, opts?: BaseOpts): Promise<Chunk[]>;
+    parse(opts?: BaseOpts): Promise<{
+        bai: boolean;
+        firstDataLine: VirtualOffset | undefined;
+        maxBlockSize: number;
+        indices: {
+            binIndex: {
+                [key: string]: Chunk[];
+            };
+            linearIndex: VirtualOffset[];
+            stats?: {
+                lineCount: number;
+            } | undefined;
+        }[];
+        refCount: number;
+    }>;
+    hasRefSeq(seqId: number, opts?: BaseOpts): Promise<boolean>;
 }