@gmod/tabix 3.6.0 → 3.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmod/tabix",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "packageManager": "pnpm@11.15.1",
   "description": "Read Tabix-indexed files, supports both .tbi and .csi indexes",
   "type": "module",
@@ -52,7 +52,7 @@
   ],
   "dependencies": {
     "@gmod/bgzf-filehandle": "^6.3.2",
-    "@gmod/shared-read-cache": "^1.4.1",
+    "@gmod/shared-read-cache": "^1.4.4",
     "@jbrowse/quick-lru": "^7.3.5",
     "generic-filehandle2": "^2.2.1"
   },

package/src/indexFile.ts

@@ -1,6 +1,7 @@
 import { unzip } from '@gmod/bgzf-filehandle'
+import { SharedReadCache } from '@gmod/shared-read-cache'
 
-import { optimizeChunks, throwIfAborted } from './util.ts'
+import { optimizeChunks } from './util.ts'
 
 import type Chunk from './chunk.ts'
 import type VirtualOffset from './virtualOffset.ts'
@@ -51,14 +52,11 @@ export interface IndexData {
 
 export default abstract class IndexFile {
   public filehandle: GenericFilehandle
-  private parseP?: Promise<IndexData>
   /**
-   * The signal `parseP` was started under, while it is still in flight. The
-   * index is parsed once and shared by every query against the file, so without
-   * this the first query to arrive would own a read all the others depend on —
-   * see {@link parse}.
+   * The parsed index, as a shared read — see {@link parse}. One entry, never
+   * evicted, which is what a memo is.
    */
-  private parseSignal?: AbortSignal
+  private parseCache = new SharedReadCache<string, IndexData>({})
 
   constructor({ filehandle }: { filehandle: GenericFilehandle }) {
     this.filehandle = filehandle
@@ -158,75 +156,38 @@ export default abstract class IndexFile {
     return optimizeChunks(chunks, this.lowestOffset(ba, min, indexData))
   }
 
-  // SYNC: ~/src/gmod/bam-js/src/indexFile.ts parse — same owner-signal
-  // tracking and one-attempt retry, and the same reasoning below.
+  // SYNC: ~/src/gmod/bam-js/src/indexFile.ts parse — same shape and the same
+  // reasoning below.
   /**
    * Parse the index, or join the parse already running.
    *
    * The index is downloaded and parsed once for the life of this object, so it
    * is the one read here that is shared between queries — and therefore the one
    * place a cancellation can leak from the query that asked for it to a query
-   * that did not. `_parse` hands `opts` straight to `readIndexBytes`, so
-   * without this the first query to arrive owns a read every other query
-   * depends on: when it pans away, every concurrent query fails with its abort.
+   * that did not. `_parse` hands `opts` straight to `readIndexBytes`, so a bare
+   * memoized promise makes the first query to arrive the owner of a read every
+   * other query depends on: when it pans away, every concurrent query fails
+   * with its abort.
    *
-   * A caller that joined someone else's parse and saw it fail because *they*
-   * aborted starts over rather than inheriting the failure — once, then
-   * propagates. Bounding it at one attempt is what jbrowse's
-   * `RemoteFileWithRangeCache.joinChunk` does with the same retry one layer
-   * down, and for the reason it gives: the pathological case becomes one
-   * duplicate parse rather than a recursion whose depth depends on how the
-   * aborts interleave.
+   * The same cache `ChunkCache` uses, for the same reason and with the same
+   * rule: the parse runs under a signal of its own and is cancelled only once
+   * every caller waiting on it has given up, so one query's abort is reported
+   * to that query alone and a bystander gets the parse already in flight rather
+   * than having to re-read the index. A rejection is dropped rather than
+   * cached, so a transient failure does not poison the index for the life of
+   * the file.
    *
-   * A retry rather than the reference count `ChunkCache` uses, because the
-   * index is parsed once for the life of the object: there is no repeated waste
-   * to recover, and this is a dozen lines against restructuring the memo.
-   * `@gmod/bam`'s `IndexFile` and `@gmod/cram`'s `CraiIndex` make the same
-   * split for the same reason.
+   * The fill is per call rather than on the cache so that the caller who starts
+   * the parse has its `onProgress` reach `readIndexBytes` — the index is a
+   * whole-file read, and a determinate "downloading index" bar is what that
+   * callback exists for.
    *
    * @internal
    */
-  async parse(opts: Options = {}, retried = false): Promise<IndexData> {
-    throwIfAborted(opts.signal)
-    const pending = this.parseP
-    if (!pending) {
-      return this.startParse(opts)
-    }
-
-    // read before awaiting: the owner is forgotten as soon as the parse settles
-    const ownerSignal = this.parseSignal
-    try {
-      return await pending
-    } catch (e) {
-      if (retried || !ownerSignal?.aborted || opts.signal?.aborted) {
-        throw e
-      }
-      return this.parse(opts, true)
-    }
-  }
-
-  private startParse(opts: Options) {
-    const pending = this._parse(opts)
-    this.parseP = pending
-    this.parseSignal = opts.signal
-    // Drop a rejection rather than keeping it, so one transient failure does not
-    // poison the index for the lifetime of the file. Both branches are
-    // identity-checked so a retry started after this settles is not cleared by
-    // the attempt it already replaced.
-    pending.then(
-      () => {
-        if (this.parseP === pending) {
-          this.parseSignal = undefined
-        }
-      },
-      () => {
-        if (this.parseP === pending) {
-          this.parseP = undefined
-          this.parseSignal = undefined
-        }
-      },
+  parse(opts: Options = {}): Promise<IndexData> {
+    return this.parseCache.get('index', opts.signal, signal =>
+      this._parse({ ...opts, signal }),
     )
-    return pending
   }
 
   /** @internal */

package/src/tabixIndexedFile.ts

@@ -4,7 +4,7 @@ import { LocalFile, RemoteFile } from 'generic-filehandle2'
 
 import CSI from './csi.ts'
 import TBI from './tbi.ts'
-import { optimizeChunks, throwIfAborted } from './util.ts'
+import { optimizeChunks } from './util.ts'
 
 import type Chunk from './chunk.ts'
 import type IndexFile from './indexFile.ts'
@@ -277,14 +277,14 @@ export default class TabixIndexedFile {
   private filehandle: GenericFilehandle
   private index: IndexFile
   public chunkCache: SharedReadCache<Chunk, ReadChunk>
-  private headerP?: Promise<{ header: string; skippedLines: string[] }>
   /**
-   * The signal `headerP` was started under, while it is still in flight. The
-   * header is parsed once and shared by every caller, so without this the first
-   * one to arrive would own a read all the others depend on — see
-   * {@link getParsedHeader}.
+   * The parsed header, as a shared read — see {@link getParsedHeader}. One
+   * entry, never evicted, which is what a memo is.
    */
-  private headerSignal?: AbortSignal
+  private headerCache = new SharedReadCache<
+    string,
+    { header: string; skippedLines: string[] }
+  >({})
 
   constructor({
     path,
@@ -641,58 +641,24 @@ export default class TabixIndexedFile {
    * charge of a read every later caller joins: when it aborted, they failed
    * with its cancellation, their own signals untouched.
    *
-   * A caller that joined someone else's parse and saw it fail because *they*
-   * aborted starts over rather than inheriting the failure — once, then
-   * propagates. Same bounded retry, and the same reasoning, as
-   * `IndexFile.parse`.
+   * The same cache the chunk reads use, and the same rule: the parse runs under
+   * a signal of its own and is cancelled only once every caller waiting on it
+   * has given up, so one caller's abort is reported to that caller alone and a
+   * bystander gets the parse already in flight. There is no retry here because
+   * there is nothing to retry — the parse a bystander joined is not cancelled by
+   * someone else's abort. A rejection is dropped rather than cached, so a
+   * transient failure does not poison the header for the life of the file.
+   *
+   * The fill is per call rather than on the cache, so the caller that starts the
+   * parse has its `onProgress` reach the index download inside `getMetadata`.
    *
    * SYNC: ~/src/gmod/bam-js/src/bamFile.ts getHeader — same shape for the same
    * reason, on the header rather than the index.
    */
-  private async getParsedHeader(
-    opts: Options = {},
-    retried = false,
-  ): Promise<{ header: string; skippedLines: string[] }> {
-    throwIfAborted(opts.signal)
-    const pending = this.headerP
-    if (!pending) {
-      return this.startHeaderParse(opts)
-    }
-
-    // read before awaiting: the owner is forgotten as soon as the parse settles
-    const ownerSignal = this.headerSignal
-    try {
-      return await pending
-    } catch (e) {
-      if (retried || !ownerSignal?.aborted || opts.signal?.aborted) {
-        throw e
-      }
-      return this.getParsedHeader(opts, true)
-    }
-  }
-
-  private startHeaderParse(opts: Options) {
-    const pending = this.parseHeader(opts)
-    this.headerP = pending
-    this.headerSignal = opts.signal
-    // Drop a rejection rather than keeping it, so one transient failure does not
-    // poison the header for the lifetime of the file. Both branches are
-    // identity-checked so a retry started after this settles is not cleared by
-    // the attempt it already replaced.
-    pending.then(
-      () => {
-        if (this.headerP === pending) {
-          this.headerSignal = undefined
-        }
-      },
-      () => {
-        if (this.headerP === pending) {
-          this.headerP = undefined
-          this.headerSignal = undefined
-        }
-      },
+  private getParsedHeader(opts: Options = {}) {
+    return this.headerCache.get('header', opts.signal, signal =>
+      this.parseHeader({ ...opts, signal }),
     )
-    return pending
   }
 
   /**