Update

GMOD · Aug 30, 2024 · 465c30a · 465c30a
1 parent 2a8772d
commit 465c30a
Show file tree

Hide file tree

Showing 6 changed files with 1,788 additions and 65 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,24 +1,20 @@
 ## [1.5.15](https://github.com/GMOD/tabix-js/compare/v1.5.14...v1.5.15) (2024-08-30)
 
-
-
 ## [1.5.14](https://github.com/GMOD/tabix-js/compare/v1.5.13...v1.5.14) (2024-07-23)
 
-
 ### Reverts
 
-* Revert "Bump to eslint 9" ([9bd49b1](https://github.com/GMOD/tabix-js/commit/9bd49b1132f632b0e7847d9b95cf3cb08c424360))
-
-
+- Revert "Bump to eslint 9"
+  ([9bd49b1](https://github.com/GMOD/tabix-js/commit/9bd49b1132f632b0e7847d9b95cf3cb08c424360))
 
 ## [1.5.13](https://github.com/GMOD/tabix-js/compare/v1.5.12...v1.5.13) (2024-01-09)
 
 - Another fix for abort signal in getLines
 
 ## [1.5.12](https://github.com/GMOD/tabix-js/compare/v1.5.11...v1.5.12) (2024-01-09)
 
-- Add missing abort signal to the @gmod/abortable-promise-cache fetch for tabix chunks
-  (#143)
+- Add missing abort signal to the @gmod/abortable-promise-cache fetch for tabix
+  chunks (#143)
 
 ## [1.5.11](https://github.com/GMOD/tabix-js/compare/v1.5.10...v1.5.11) (2023-07-10)
 

diff --git a/README.md b/README.md
@@ -27,8 +27,8 @@ import { TabixIndexedFile } from '@gmod/tabix'
 You can use tabix-js without NPM also with the tabix-bundle.js. See the example
 directory for usage with script tag [example/index.html](example/index.html)
 
-```
-    <script src="https://unpkg.com/@gmod/tabix/dist/tabix-bundle.js"></script>
+```html
+<script src="https://unpkg.com/@gmod/tabix/dist/tabix-bundle.js"></script>
 ```
 
 ### TabixIndexedFile constructor
@@ -47,10 +47,10 @@ const tbiIndexed = new TabixIndexedFile({
 
 ```
 
-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)
+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)
 
 ```typescript
 // can also open tabix files that have a .csi index
@@ -64,9 +64,15 @@ const csiIndexed = new TabixIndexedFile({
 
 #### 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
+```typescript
+const remoteTbiIndexed = new TabixIndexedFile({
+  url: 'http://yourhost/file.vcf.gz',
+  tbiUrl: 'http://yourhost/file.vcf.gz.tbi', // can also be csiUrl
+})
+```
+
+You can also alternatively supply a filehandle-like object with the
+[generic-filehandle](https://github.com/GMOD/generic-filehandle): example
 
 ```typescript
 // use a remote file or other filehandle, note RemoteFile comes from https://github.com/GMOD/generic-filehandle
@@ -77,9 +83,9 @@ const remoteTbiIndexed = new TabixIndexedFile({
 })
 ```
 
-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
+This works in both the browser and in node.js, but note that in node.js you may
+have to also supply a custom fetch function to the RemoteFile constructor e.g.
+like this
 
 ```typescript
 // for node.js you have to manually supply a fetch function e.g. node-fetch to RemoteFile
@@ -111,8 +117,8 @@ await tbiIndexed.getLines('ctgA', 200, 300, function (line, fileOffset) {
 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
+You can also supply some extra arguments to `getLines` with this format, but
+these are sort of obscure and only used in some circumstances
 
 ```typescript
 const lines = []
@@ -133,41 +139,173 @@ Notes about the returned values of `getLines`:
 - 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.
+- if `getLines` is called with an undefined `end` parameter it gets all lines
+  from start going to the end of the contig e.g.
 
 ```typescript
 const lines = []
 await tbiIndexed.getLines('ctgA', 0, undefined, line=>lines.push(line))`
 console.log(lines)
 ```
 
-### lineCount
+## API (auto-generated)
+
+### TabixIndexedFile
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+##### Table of Contents
+
+- [constructor](#constructor)
+  - [Parameters](#parameters)
+- [getLines](#getlines)
+  - [Parameters](#parameters-1)
+- [getHeaderBuffer](#getheaderbuffer)
+  - [Parameters](#parameters-2)
+- [getHeader](#getheader)
+  - [Parameters](#parameters-3)
+- [getReferenceSequenceNames](#getreferencesequencenames)
+  - [Parameters](#parameters-4)
+- [checkLine](#checkline)
+  - [Parameters](#parameters-5)
+- [lineCount](#linecount)
+  - [Parameters](#parameters-6)
+- [readChunk](#readchunk)
+  - [Parameters](#parameters-7)
+
+#### constructor
+
+##### Parameters
+
+- `args`
+  **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**&#x20;
+
+  - `args.path`
+    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**&#x20;
+  - `args.filehandle` **filehandle?**&#x20;
+  - `args.url`
+    **[url](https://developer.mozilla.org/docs/Web/API/URL/URL)?**&#x20;
+  - `args.tbiPath`
+    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**&#x20;
+  - `args.tbiUrl` **tbiUrl?**&#x20;
+  - `args.tbiFilehandle` **filehandle?**&#x20;
+  - `args.csiPath`
+    **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)?**&#x20;
+  - `args.csiUrl` **csiUrl?**&#x20;
+  - `args.csiFilehandle` **filehandle?**&#x20;
+  - `args.yieldTime`
+    **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)?**
+    yield to main thread after N milliseconds if reading features is taking a
+    long time to avoid hanging main thread (optional, default `500`)
+  - `args.renameRefSeqs`
+    **[function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)?**
+    optional function with sig `string => string` to transform reference
+    sequence names for the purpose of indexing and querying. note that the data
+    that is returned is not altered, just the names of the reference sequences
+    that are used for querying. (optional, default `n=>n`)
+  - `args.chunkCacheSize` (optional, default `5*2**20`)
+
+#### getLines
+
+##### Parameters
+
+- `refName`
+  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**
+  name of the reference sequence
+- `s`
+  **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)
+  |
+  [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))**&#x20;
+- `e`
+  **([number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)
+  |
+  [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined))**&#x20;
+- `opts` **(GetLinesOpts | GetLinesCallback)** callback called for each line in
+  the region. can also pass a object param containing obj.lineCallback,
+  obj.signal, etc
+- `start` start of the region (in 0-based half-open coordinates)
+- `end` end of the region (in 0-based half-open coordinates)
+
+Returns **any** promise that is resolved when the whole read is finished,
+rejected on error
 
-```typescript
-// 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 })
-```
+#### getHeaderBuffer
 
-### getHeader
+get a buffer containing the "header" region of the file, which are the bytes up
+to the first non-meta line
 
-```typescript
-// 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 })
-```
+##### Parameters
 
-#### getHeaderBuffer
+- `opts` **Options** (optional, default `{}`)
 
-```typescript
-// 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 })
-```
+#### getHeader
+
+get a string containing the "header" region of the file, is the portion up to
+the first non-meta line
+
+##### Parameters
+
+- `opts` **Options** (optional, default `{}`)
+
+Returns
+**[Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
+for a string
+
+#### getReferenceSequenceNames
+
+get an array of reference sequence names, in the order in which they occur in
+the file. reference sequence renaming is not applied to these names.
+
+##### Parameters
+
+- `opts` **Options** (optional, default `{}`)
+
+#### checkLine
+
+##### Parameters
+
+- `metadata`
+  **[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
+  metadata object from the parsed index, containing columnNumbers, metaChar, and
+  format
+- `regionRefName`
+  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
+- `regionStart`
+  **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
+  region start coordinate (0-based-half-open)
+- `regionEnd`
+  **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**
+  region end coordinate (0-based-half-open)
+- `line`
+  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
+
+Returns
+**[object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
+like `{startCoordinate, overlaps}`. overlaps is boolean, true if line is a data
+line that overlaps the given region
+
+#### lineCount
+
+return the approximate number of data lines in the given reference sequence
+
+##### Parameters
+
+- `refName`
+  **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)**&#x20;
+- `opts` **Options** (optional, default `{}`)
+- `refSeq` reference sequence name
+
+Returns **any** number of data lines present on that reference sequence
+
+#### readChunk
+
+read and uncompress the data in a chunk (composed of one or more contiguous
+bgzip blocks) of the file
+
+##### Parameters
+
+- `c` **Chunk**&#x20;
+- `opts` **Options** (optional, default `{}`)
 
 ## Academic Use
 

diff --git a/package.json b/package.json
@@ -23,6 +23,7 @@
     "test": "vitest",
     "lint": "eslint --report-unused-disable-directives --max-warnings 0",
     "format": "prettier --write .",
+    "docs": "documentation readme --shallow src/tabixIndexedFile.ts --section TabixIndexedFile",
     "clean": "rimraf dist esm",
     "prebuild": "npm run clean && npm run lint",
     "build:esm": "tsc --target es2018 --outDir esm",
@@ -55,6 +56,7 @@
     "@typescript-eslint/parser": "^8.0.1",
     "@vitest/coverage-v8": "^2.0.5",
     "buffer": "^6.0.3",
+    "documentation": "^14.0.3",
     "eslint": "^9.9.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-prettier": "^5.0.1",

diff --git a/src/chunk.ts b/src/chunk.ts
@@ -20,7 +20,6 @@ export default class Chunk {
   }
 
   toUniqueString() {
-
     return `${this.minv}..${this.maxv} (bin ${
       this.bin
     }, fetchedSize ${this.fetchedSize()})`

diff --git a/src/tabixIndexedFile.ts b/src/tabixIndexedFile.ts
@@ -52,6 +52,12 @@ export default class TabixIndexedFile {
    *
    * @param {filehandle} [args.csiFilehandle]
    *
+   * @param {url} [args.url]
+   *
+   * @param {csiUrl} [args.csiUrl]
+   *
+   * @param {tbiUrl} [args.tbiUrl]
+   *
    * @param {number} [args.yieldTime] yield to main thread after N milliseconds
    * if reading features is taking a long time to avoid hanging main thread
    *