@gmod/tabix 1.4.5 → 1.5.2

package/CHANGELOG.md

@@ -1,89 +1,106 @@
-<a name="1.4.5"></a>
-## [1.4.5](https://github.com/GMOD/tabix-js/compare/v1.4.4...v1.4.5) (2020-04-28)
+<a name="1.5.2"></a>
+## [1.5.2](https://github.com/GMOD/tabix-js/compare/v1.5.1...v1.5.2) (2021-12-15)
+
+
+
+- Change typescript signature of lineCallback from Promise<void> to void
+
+<a name="1.5.1"></a>
+## [1.5.1](https://github.com/GMOD/tabix-js/compare/v1.5.0...v1.5.1) (2021-12-15)
+
+
+
+- Add esm module with less babelification for smaller bundle size
+
+<a name="1.5.0"></a>
+# [1.5.0](https://github.com/GMOD/tabix-js/compare/v1.4.6...v1.5.0) (2020-12-11)
+
+
+
+- Use TextDecoder for chunk decoding for small speedup
+- Use canMergeChunks logic to avoid too large of chunks being used
+- Use time based yield instead of number-of-line based yield
 
+<a name="1.4.6"></a>
 
+## [1.4.6](https://github.com/GMOD/tabix-js/compare/v1.4.5...v1.4.6) (2020-04-30)
+
+- Fix regression with browser only version of tabix-js not being able to parse results in 1.4.5
+
+<a name="1.4.5"></a>
+
+## [1.4.5](https://github.com/GMOD/tabix-js/compare/v1.4.4...v1.4.5) (2020-04-28)
 
 - Remove the filehandle size() call because this is unnecessary and would indicate a corrupt index,
   and because it additionally has a CORS configuration overhead
 
 <a name="1.4.4"></a>
-## [1.4.4](https://github.com/GMOD/tabix-js/compare/v1.4.3...v1.4.4) (2020-04-06)
-
 
+## [1.4.4](https://github.com/GMOD/tabix-js/compare/v1.4.3...v1.4.4) (2020-04-06)
 
 - Fix usage of tabix where start column and end column are the same
 
 <a name="1.4.3"></a>
-## [1.4.3](https://github.com/GMOD/tabix-js/compare/v1.4.2...v1.4.3) (2020-02-04)
-
 
+## [1.4.3](https://github.com/GMOD/tabix-js/compare/v1.4.2...v1.4.3) (2020-02-04)
 
 - Fix optional param for constructor for typescript
 - Update method of calculating fileOffset based IDs using updated @gmod/bgzf-filehandle
 
 <a name="1.4.2"></a>
-## [1.4.2](https://github.com/GMOD/tabix-js/compare/v1.4.1...v1.4.2) (2020-02-01)
-
 
+## [1.4.2](https://github.com/GMOD/tabix-js/compare/v1.4.1...v1.4.2) (2020-02-01)
 
 - Fix usage of renameRefSeqs callback
 
 <a name="1.4.1"></a>
-## [1.4.1](https://github.com/GMOD/tabix-js/compare/v1.4.0...v1.4.1) (2020-02-01)
-
 
+## [1.4.1](https://github.com/GMOD/tabix-js/compare/v1.4.0...v1.4.1) (2020-02-01)
 
 - Remove a runtime dependency on a @types module
 
 <a name="1.4.0"></a>
-# [1.4.0](https://github.com/GMOD/tabix-js/compare/v1.3.2...v1.4.0) (2020-02-01)
-
 
+# [1.4.0](https://github.com/GMOD/tabix-js/compare/v1.3.2...v1.4.0) (2020-02-01)
 
 - Add typescripting of the codebase
 - Drop Node 6 support due to changes in our dependencies
 
 <a name="1.3.2"></a>
-## [1.3.2](https://github.com/GMOD/tabix-js/compare/v1.3.1...v1.3.2) (2019-11-01)
-
 
+## [1.3.2](https://github.com/GMOD/tabix-js/compare/v1.3.1...v1.3.2) (2019-11-01)
 
 - Make <TRA> SVs to ignore their usage of the END= INFO field going with the
   since it refers to the other side of a translocation
 - Make stable fileOffset based IDs
 
 <a name="1.3.1"></a>
-## [1.3.1](https://github.com/GMOD/tabix-js/compare/v1.3.0...v1.3.1) (2019-10-06)
-
 
+## [1.3.1](https://github.com/GMOD/tabix-js/compare/v1.3.0...v1.3.1) (2019-10-06)
 
 - Small refactor of `filehandle.read()` to make it more robust
 
 <a name="1.3.0"></a>
+
 # [1.3.0](https://github.com/GMOD/tabix-js/compare/v1.2.0...v1.3.0) (2019-08-08)
 
 - Add ability to pass an AbortSignal from an AbortController to `getLines()`
 
 <a name="1.2.0"></a>
-# [1.2.0](https://github.com/GMOD/tabix-js/compare/v1.1.8...v1.2.0) (2019-07-05)
-
 
+# [1.2.0](https://github.com/GMOD/tabix-js/compare/v1.1.8...v1.2.0) (2019-07-05)
 
 - Add ability for `getLines` to be open-ended. With no `end`, getlines continues
-until the end of the sequence.
+  until the end of the sequence.
 
 <a name="1.1.8"></a>
-## [1.1.8](https://github.com/GMOD/tabix-js/compare/v1.1.7...v1.1.8) (2019-06-06)
-
 
+## [1.1.8](https://github.com/GMOD/tabix-js/compare/v1.1.7...v1.1.8) (2019-06-06)
 
 - Add a fix for a bgzf unzipping thing that could result in duplicate features being returned
 
-
 ## [1.1.7](https://github.com/GMOD/tabix-js/compare/v1.1.6...v1.1.7) (2019-06-04)
 
-
-
 - Removed chunk merging from header file parsing which now results in smaller bgzf unzip calls being streamed out to clients
 
 ## [1.1.6](https://github.com/GMOD/tabix-js/compare/v1.1.5...v1.1.6) (2019-05-31)
@@ -124,7 +141,6 @@ until the end of the sequence.
 
 ## [1.0.1](https://github.com/GMOD/tabix-js/compare/v1.0.0...v1.0.1) (2018-09-15)
 
-
 - Add renameRefSeqs handling
 - Fix some blocksForRange
 

package/README.md

@@ -1,9 +1,9 @@
 # @gmod/tabix
 
 [![NPM version](https://img.shields.io/npm/v/@gmod/tabix.svg?style=flat-square)](https://npmjs.org/package/@gmod/tabix)
-[![Build Status](https://img.shields.io/travis/GMOD/tabix-js/master.svg?style=flat-square)](https://travis-ci.org/GMOD/tabix-js)
-[![Greenkeeper badge](https://badges.greenkeeper.io/GMOD/tabix-js.svg)](https://greenkeeper.io/)
-[![codecov](https://codecov.io/gh/GMOD/tabix-js/branch/master/graph/badge.svg)](https://codecov.io/gh/GMOD/tabix-js)
+[![Coverage Status](https://img.shields.io/codecov/c/github/GMOD/tabix-js/master.svg?style=flat-square)](https://codecov.io/gh/GMOD/tabix-js/branch/master)
+[![Build Status](https://img.shields.io/github/workflow/status/GMOD/tabix-js/Push/master?logo=github&style=flat-query)](https://github.com/GMOD/tabix-js/actions?query=branch%3Amaster+workflow%3APush+)
+
 
 
 Read Tabix-indexed files using either .tbi or .csi indexes.
@@ -14,60 +14,157 @@ Read Tabix-indexed files using either .tbi or .csi indexes.
 
 ## Usage
 
+
+### Importing the module
+
 ```js
+
+// import with require in node.js
 const {TabixIndexedFile} = require('@gmod/tabix')
 
-const tbiIndexed = new TabixIndexedFile({ path: 'path/to/my/file.gz' })
-// by default, assumes tabix index at path/to/my/file.gz.tbi.
-// can also provide `tbiPath` if the TBI is named differently
+// or with es6 imports, this will also give typescript types
+import {TabixIndexedFile} from '@gmod/tabix'
+```
+
+
+### TabixIndexedFile constructor
+
+
+Basic usage of TabixIndexedFile under node.js supplies a path and optionally a tbiPath to the constructor. If no tbiPath is supplied, it assumes that the path+'.tbi' is the location of the tbiPath.
 
+```
+// basic usage under node.js provides a file path on the filesystem to bgzipped file
+// it assumes the tbi file is path+'.tbi' if no tbiPath is supplied
+const tbiIndexed = new TabixIndexedFile({
+    path: 'path/to/my/file.gz'
+    tbiPath: 'path/to/my/file.gz.tbi'
+})
+
+```
+
+You can also use CSI indexes. Note also the usage of the renameRefSeqs callback. The renameRefSeqs callback makes it so that you can use file.getLines('1',0,100,...) even when the file itself contains names like 'chr1' (can also do the reverse by customizing the renameRefSeqs callback)
+
+```
 // can also open tabix files that have a .csi index
-// also trims chr off the chr names
+// note also usage of renameRefSeqs callback to trim chr off the chr names
 const csiIndexed = new TabixIndexedFile({
   path: 'path/to/my/file.gz',
   csiPath: 'path/to/my/file.gz.csi'
-  renameRefSeqs: (refSeq) => { return refSeq.replace('chr','') }
+  renameRefSeqs: refSeq => refSeq.replace('chr','')
 })
+```
+
+#### TabixIndexedFile constructor with remote files
 
+
+The basic usage of fetching remote files is done by supplying a [generic-filehandle](https://github.com/GMOD/generic-filehandle) module RemoteFile filehandle, as seen below
+
+
+```
 // use a remote file or other filehandle, note RemoteFile comes from https://github.com/GMOD/generic-filehandle
 const {RemoteFile} = require('generic-filehandle')
 const remoteTbiIndexed = new TabixIndexedFile({
   filehandle: new RemoteFile('http://yourhost/file.vcf.gz'),
   tbiFilehandle: new RemoteFile('http://yourhost/file.vcf.gz.tbi') // can also be csiFilehandle
 })
+```
+
+
+This works in both the browser and in node.js, but note that in node.js you have to also supply a custom fetch function to the RemoteFile constructor e.g. like this
+
+
+```
+// for node.js you have to manually supply a fetch function e.g. node-fetch to RemoteFile
+const fetch = require('node-fetch')
+const remoteTbiIndexedForNodeJs = new TabixIndexedFile({
+  filehandle: new RemoteFile('http://yourhost/file.vcf.gz', {fetch}),
+  tbiFilehandle: new RemoteFile('http://yourhost/file.vcf.gz.tbi', {fetch}) // can also be csiFilehandle
+})
+```
+
+
+### getLines
+
+
+The basic function this module provides is just called `getLines` and it returns text contents from the tabix file (it unzips the bgzipped data) and supplies it to a callback that you provide one line at a time.
+
+
+Important: the `start` and `end` values that are supplied to `getLines` are 0-based half-open coordinates. This is different from the 1-based values that are supplied to the tabix command line tool
 
+
+```
 // iterate over lines in the specified region
 const lines = []
-await tbiIndexed.getLines('ctgA',200,300, (line, fileOffset) => lines.push(line))
-// alternative API usage
+await tbiIndexed.getLines('ctgA',200,300, function(line, fileOffset) {
+    lines.push(line)
+})
+
+```
+
+After running this, your `lines` array would contain an array of lines from the file that match your query range
+
+
+You can also supply some extra arguments to getLines with this format, but these are sort of obscure and only used in some circumstances
+
+
+```
+const lines = []
 const aborter = new AbortController()
 await tbiIndexed.getLines('ctgA',200,300, {
   lineCallback: (line, fileOffset) => lines.push(line),
   signal: aborter.signal // an optional AbortSignal from an AbortController
 })
-// lines is now an array of strings, which are data lines.
-// commented (meta) lines are skipped.
-// line strings do not include any trailing whitespace characters.
-// the callback is also called with a `fileOffset`,
-// which gives the virtual file offset where the line is found in the file
 
+```
+
+After running the above demo, lines is now an array of strings, containing the lines from the tabix file
+
+Notes about the returned values of `getLines`:
+
+- commented (meta) lines are skipped.
+- line strings do not include any trailing whitespace characters.
+- the callback is also called with a `fileOffset` that can be used to uniquely identify lines based on their virtual file offset where the line is found in the file
+- if getLines is called with an undefined `end` parameter it gets all lines from start going to the end of the contig e.g.
+
+```
+const lines = []
+await tbiIndexed.getLines('ctgA', 0, undefined, line=>lines.push(line))`
+console.log(lines)
+```
+
+
+
+
+### lineCount
+
+
+```
 // get the approximate number of data lines in the
 // file for the given reference sequence, excluding header, comment, and whitespace lines
+// uses the extra bin from tabix
 const numLines = await tbiIndexed.lineCount('ctgA')
 // or const numLines = await tbiIndexed.lineCount('ctgA', { signal: aborter.signal })
 
+```
+
+
+### getHeader
+
+```
 // get the "header text" string from the file, which is the first contiguous
 // set of lines in the file that all start with a "meta" character (usually #)
 const headerText = await tbiIndexed.getHeader()
 // or const headerText = await tbiIndexed.getHeader({ signal: aborter.signal })
+```
 
+#### getHeaderBuffer
+
+```
 // or if you want a nodejs Buffer object instead, there is getHeaderBuffer()
 const headerBuffer = await tbiIndexed.getHeaderBuffer()
 // or const headerBuffer = await tbiIndexed.getHeaderBuffer({ signal: aborter.signal })
 ```
 
-You may also use e.g. `tbiIndexed.getLines('ctgA', 200, undefined, lineCallback)`
-to get all lines starting at 200 and going to the end of ctgA.
 
 ## Academic Use
 

package/dist/chunk.js

@@ -1,66 +1,37 @@
 "use strict";
-
-var _interopRequireDefault = require("@babel/runtime-corejs2/helpers/interopRequireDefault");
-
-var _Object$defineProperty = require("@babel/runtime-corejs2/core-js/object/define-property");
-
-_Object$defineProperty(exports, "__esModule", {
-  value: true
-});
-
-exports.default = void 0;
-
-var _classCallCheck2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/classCallCheck"));
-
-var _createClass2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/createClass"));
-
-var _defineProperty2 = _interopRequireDefault(require("@babel/runtime-corejs2/helpers/defineProperty"));
-
+Object.defineProperty(exports, "__esModule", { value: true });
 // little class representing a chunk in the index
-var Chunk = /*#__PURE__*/function () {
-  /**
-   * @param {VirtualOffset} minv
-   * @param {VirtualOffset} maxv
-   * @param {number} bin
-   * @param {number} [fetchedSize]
-   */
-  function Chunk(minv, maxv, bin) {
-    var fetchedSize = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : undefined;
-    (0, _classCallCheck2.default)(this, Chunk);
-    (0, _defineProperty2.default)(this, "minv", void 0);
-    (0, _defineProperty2.default)(this, "maxv", void 0);
-    (0, _defineProperty2.default)(this, "bin", void 0);
-    (0, _defineProperty2.default)(this, "_fetchedSize", void 0);
-    this.minv = minv;
-    this.maxv = maxv;
-    this.bin = bin;
-    this._fetchedSize = fetchedSize;
-  }
-
-  (0, _createClass2.default)(Chunk, [{
-    key: "toUniqueString",
-    value: function toUniqueString() {
-      return "".concat(this.minv, "..").concat(this.maxv, " (bin ").concat(this.bin, ", fetchedSize ").concat(this.fetchedSize(), ")");
+var Chunk = /** @class */ (function () {
+    /**
+     * @param {VirtualOffset} minv
+     * @param {VirtualOffset} maxv
+     * @param {number} bin
+     * @param {number} [fetchedSize]
+     */
+    function Chunk(minv, maxv, bin, fetchedSize) {
+        if (fetchedSize === void 0) { fetchedSize = undefined; }
+        this.minv = minv;
+        this.maxv = maxv;
+        this.bin = bin;
+        this._fetchedSize = fetchedSize;
     }
-  }, {
-    key: "toString",
-    value: function toString() {
-      return this.toUniqueString();
-    }
-  }, {
-    key: "compareTo",
-    value: function compareTo(b) {
-      return this.minv.compareTo(b.minv) || this.maxv.compareTo(b.maxv) || this.bin - b.bin;
-    }
-  }, {
-    key: "fetchedSize",
-    value: function fetchedSize() {
-      if (this._fetchedSize !== undefined) return this._fetchedSize;
-      return this.maxv.blockPosition + (1 << 16) - this.minv.blockPosition;
-    }
-  }]);
-  return Chunk;
-}();
-
+    Chunk.prototype.toUniqueString = function () {
+        return "".concat(this.minv, "..").concat(this.maxv, " (bin ").concat(this.bin, ", fetchedSize ").concat(this.fetchedSize(), ")");
+    };
+    Chunk.prototype.toString = function () {
+        return this.toUniqueString();
+    };
+    Chunk.prototype.compareTo = function (b) {
+        return (this.minv.compareTo(b.minv) ||
+            this.maxv.compareTo(b.maxv) ||
+            this.bin - b.bin);
+    };
+    Chunk.prototype.fetchedSize = function () {
+        if (this._fetchedSize !== undefined) {
+            return this._fetchedSize;
+        }
+        return this.maxv.blockPosition + (1 << 16) - this.minv.blockPosition;
+    };
+    return Chunk;
+}());
 exports.default = Chunk;
-//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJzb3VyY2VzIjpbIi4uL3NyYy9jaHVuay50cyJdLCJuYW1lcyI6WyJDaHVuayIsIm1pbnYiLCJtYXh2IiwiYmluIiwiZmV0Y2hlZFNpemUiLCJ1bmRlZmluZWQiLCJfZmV0Y2hlZFNpemUiLCJ0b1VuaXF1ZVN0cmluZyIsImIiLCJjb21wYXJlVG8iLCJibG9ja1Bvc2l0aW9uIl0sIm1hcHBpbmdzIjoiOzs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFFQTtJQUNxQkEsSztBQU1uQjs7Ozs7O0FBTUEsaUJBQ0VDLElBREYsRUFFRUMsSUFGRixFQUdFQyxHQUhGLEVBS0U7QUFBQSxRQURBQyxXQUNBLHVFQURjQyxTQUNkO0FBQUE7QUFBQTtBQUFBO0FBQUE7QUFBQTtBQUNBLFNBQUtKLElBQUwsR0FBWUEsSUFBWjtBQUNBLFNBQUtDLElBQUwsR0FBWUEsSUFBWjtBQUNBLFNBQUtDLEdBQUwsR0FBV0EsR0FBWDtBQUNBLFNBQUtHLFlBQUwsR0FBb0JGLFdBQXBCO0FBQ0Q7Ozs7cUNBRWdCO0FBQ2YsdUJBQVUsS0FBS0gsSUFBZixlQUF3QixLQUFLQyxJQUE3QixtQkFDRSxLQUFLQyxHQURQLDJCQUVpQixLQUFLQyxXQUFMLEVBRmpCO0FBR0Q7OzsrQkFFVTtBQUNULGFBQU8sS0FBS0csY0FBTCxFQUFQO0FBQ0Q7Ozs4QkFFU0MsQyxFQUFVO0FBQ2xCLGFBQ0UsS0FBS1AsSUFBTCxDQUFVUSxTQUFWLENBQW9CRCxDQUFDLENBQUNQLElBQXRCLEtBQ0EsS0FBS0MsSUFBTCxDQUFVTyxTQUFWLENBQW9CRCxDQUFDLENBQUNOLElBQXRCLENBREEsSUFFQSxLQUFLQyxHQUFMLEdBQVdLLENBQUMsQ0FBQ0wsR0FIZjtBQUtEOzs7a0NBRWE7QUFDWixVQUFJLEtBQUtHLFlBQUwsS0FBc0JELFNBQTFCLEVBQXFDLE9BQU8sS0FBS0MsWUFBWjtBQUNyQyxhQUFPLEtBQUtKLElBQUwsQ0FBVVEsYUFBVixJQUEyQixLQUFLLEVBQWhDLElBQXNDLEtBQUtULElBQUwsQ0FBVVMsYUFBdkQ7QUFDRCIsInNvdXJjZXNDb250ZW50IjpbImltcG9ydCBWaXJ0dWFsT2Zmc2V0IGZyb20gJy4vdmlydHVhbE9mZnNldCdcblxuLy8gbGl0dGxlIGNsYXNzIHJlcHJlc2VudGluZyBhIGNodW5rIGluIHRoZSBpbmRleFxuZXhwb3J0IGRlZmF1bHQgY2xhc3MgQ2h1bmsge1xuICBwdWJsaWMgbWludjogVmlydHVhbE9mZnNldFxuICBwdWJsaWMgbWF4djogVmlydHVhbE9mZnNldFxuICBwdWJsaWMgYmluOiBudW1iZXJcbiAgcHVibGljIF9mZXRjaGVkU2l6ZT86IG51bWJlclxuXG4gIC8qKlxuICAgKiBAcGFyYW0ge1ZpcnR1YWxPZmZzZXR9IG1pbnZcbiAgICogQHBhcmFtIHtWaXJ0dWFsT2Zmc2V0fSBtYXh2XG4gICAqIEBwYXJhbSB7bnVtYmVyfSBiaW5cbiAgICogQHBhcmFtIHtudW1iZXJ9IFtmZXRjaGVkU2l6ZV1cbiAgICovXG4gIGNvbnN0cnVjdG9yKFxuICAgIG1pbnY6IFZpcnR1YWxPZmZzZXQsXG4gICAgbWF4djogVmlydHVhbE9mZnNldCxcbiAgICBiaW46IG51bWJlcixcbiAgICBmZXRjaGVkU2l6ZSA9IHVuZGVmaW5lZCxcbiAgKSB7XG4gICAgdGhpcy5taW52ID0gbWludlxuICAgIHRoaXMubWF4diA9IG1heHZcbiAgICB0aGlzLmJpbiA9IGJpblxuICAgIHRoaXMuX2ZldGNoZWRTaXplID0gZmV0Y2hlZFNpemVcbiAgfVxuXG4gIHRvVW5pcXVlU3RyaW5nKCkge1xuICAgIHJldHVybiBgJHt0aGlzLm1pbnZ9Li4ke3RoaXMubWF4dn0gKGJpbiAke1xuICAgICAgdGhpcy5iaW5cbiAgICB9LCBmZXRjaGVkU2l6ZSAke3RoaXMuZmV0Y2hlZFNpemUoKX0pYFxuICB9XG5cbiAgdG9TdHJpbmcoKSB7XG4gICAgcmV0dXJuIHRoaXMudG9VbmlxdWVTdHJpbmcoKVxuICB9XG5cbiAgY29tcGFyZVRvKGI6IENodW5rKSB7XG4gICAgcmV0dXJuIChcbiAgICAgIHRoaXMubWludi5jb21wYXJlVG8oYi5taW52KSB8fFxuICAgICAgdGhpcy5tYXh2LmNvbXBhcmVUbyhiLm1heHYpIHx8XG4gICAgICB0aGlzLmJpbiAtIGIuYmluXG4gICAgKVxuICB9XG5cbiAgZmV0Y2hlZFNpemUoKSB7XG4gICAgaWYgKHRoaXMuX2ZldGNoZWRTaXplICE9PSB1bmRlZmluZWQpIHJldHVybiB0aGlzLl9mZXRjaGVkU2l6ZVxuICAgIHJldHVybiB0aGlzLm1heHYuYmxvY2tQb3NpdGlvbiArICgxIDw8IDE2KSAtIHRoaXMubWludi5ibG9ja1Bvc2l0aW9uXG4gIH1cbn1cbiJdfQ==

package/dist/csi.d.ts

@@ -63,10 +63,9 @@ export default class CSI extends IndexFile {
     parsePseudoBin(bytes: Buffer, offset: number): {
         lineCount: number;
     };
-    blocksForRange(refName: string, beg: number, end: number, opts?: Options): Promise<Chunk[]>;
+    blocksForRange(refName: string, min: number, max: number, opts?: Options): Promise<Chunk[]>;
     /**
      * 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[];
+    reg2bins(beg: number, end: number): number[][];
 }