jbrowse-plugin-msaview 3.6.0 → 3.7.0

package/dist/utils/blastCache.d.ts

@@ -13,6 +13,8 @@ export interface CachedBlastResult {
     searchProgram?: SearchProgram;
     /** absent on phmmer rows, which are aligned by the search itself */
     msaAlgorithm?: MsaAlgorithm;
+    /** absent on rows saved before it was recorded */
+    maxHits?: number;
     msa: string;
     tree: string;
     treeMetadata: string;
@@ -23,11 +25,33 @@ export interface CachedBlastResult {
     transcriptName?: string;
     geneName?: string;
 }
-export declare function saveBlastResult({ proteinSequence, blastDatabase, msaAlgorithm, searchProgram, msa, tree, treeMetadata, rid, geneId, transcriptId, transcriptName, geneName, }: {
+/**
+ * One history row per distinct search. Every input that changes the stored
+ * alignment is in the key, or re-running the query with another aligner or hit
+ * count overwrites the earlier row. A part added later is left out at its old
+ * value so rows saved before it still resolve: phmmer keys are prefixed and
+ * blastp keys are not, and the hit count appears only when it is not the
+ * default.
+ */
+export declare function createCacheKey({ proteinSequence, blastDatabase, msaAlgorithm, searchProgram, transcriptId, maxHits, }: {
     proteinSequence: string;
     blastDatabase: BlastDatabase | PhmmerDatabase;
     msaAlgorithm?: MsaAlgorithm;
     searchProgram?: SearchProgram;
+    transcriptId?: string;
+    maxHits?: number;
+}): string;
+/**
+ * Record a finished search in the history. Best effort: the alignment is
+ * already in hand, and a browser refusing the write must not turn it into a
+ * failed launch.
+ */
+export declare function saveBlastResult({ proteinSequence, blastDatabase, msaAlgorithm, searchProgram, maxHits, msa, tree, treeMetadata, rid, geneId, transcriptId, transcriptName, geneName, }: {
+    proteinSequence: string;
+    blastDatabase: BlastDatabase | PhmmerDatabase;
+    msaAlgorithm?: MsaAlgorithm;
+    searchProgram?: SearchProgram;
+    maxHits?: number;
     msa: string;
     tree: string;
     treeMetadata: string;
@@ -36,6 +60,6 @@ export declare function saveBlastResult({ proteinSequence, blastDatabase, msaAlg
     transcriptId?: string;
     transcriptName?: string;
     geneName?: string;
-}): Promise<CachedBlastResult>;
+}): Promise<CachedBlastResult | undefined>;
 export declare function getAllCachedResults(): Promise<CachedBlastResult[]>;
 export declare function deleteCachedResult(id: string): Promise<void>;

package/dist/utils/blastCache.js

@@ -1,4 +1,5 @@
-import { createDbOpener } from './idb';
+import { defaultMaxHits } from '../LaunchMsaView/components/BlastQuery/consts';
+import { bestEffort, createDbOpener } from './idb';
 const DB_NAME = 'jbrowse-msaview-blast-cache';
 const STORE_NAME = 'blast-results';
 const DB_VERSION = 2;
@@ -16,46 +17,57 @@ const getDB = createDbOpener(DB_NAME, DB_VERSION, (db, oldVersion) => {
         db.createObjectStore(STORE_NAME, { keyPath: 'id' });
     }
 });
-function createCacheKey({ proteinSequence, blastDatabase, msaAlgorithm, searchProgram, transcriptId, }) {
+/**
+ * One history row per distinct search. Every input that changes the stored
+ * alignment is in the key, or re-running the query with another aligner or hit
+ * count overwrites the earlier row. A part added later is left out at its old
+ * value so rows saved before it still resolve: phmmer keys are prefixed and
+ * blastp keys are not, and the hit count appears only when it is not the
+ * default.
+ */
+export function createCacheKey({ proteinSequence, blastDatabase, msaAlgorithm, searchProgram, transcriptId, maxHits, }) {
     const idPart = transcriptId ? `:${transcriptId}` : '';
-    // phmmer keys are prefixed and blastp keys are left exactly as they were, so
-    // results cached before phmmer existed still resolve
-    if (searchProgram === 'phmmer') {
-        return `phmmer:${blastDatabase}${idPart}:${proteinSequence}`;
-    }
-    // msaAlgorithm is part of the key because the stored msa/tree are produced by
-    // it — without it, re-running the same query under a different algorithm
-    // overwrites the earlier result and drops it from the history list
-    return `${blastDatabase}:${msaAlgorithm}${idPart}:${proteinSequence}`;
+    const hitsPart = maxHits === undefined || maxHits === defaultMaxHits ? '' : `:n${maxHits}`;
+    return searchProgram === 'phmmer'
+        ? `phmmer:${blastDatabase}${idPart}${hitsPart}:${proteinSequence}`
+        : `${blastDatabase}:${msaAlgorithm}${idPart}${hitsPart}:${proteinSequence}`;
 }
-export async function saveBlastResult({ proteinSequence, blastDatabase, msaAlgorithm, searchProgram, msa, tree, treeMetadata, rid, geneId, transcriptId, transcriptName, geneName, }) {
-    const db = await getDB();
-    const id = createCacheKey({
-        proteinSequence,
-        blastDatabase,
-        msaAlgorithm,
-        searchProgram,
-        transcriptId,
-    });
-    const entry = {
-        id,
-        proteinSequence,
-        blastDatabase,
-        msaAlgorithm,
-        searchProgram,
-        msa,
-        tree,
-        treeMetadata,
-        rid,
-        timestamp: Date.now(),
-        geneId,
-        transcriptId,
-        transcriptName,
-        geneName,
-    };
-    await db.put(STORE_NAME, entry);
-    await evictOldest(db);
-    return entry;
+/**
+ * Record a finished search in the history. Best effort: the alignment is
+ * already in hand, and a browser refusing the write must not turn it into a
+ * failed launch.
+ */
+export function saveBlastResult({ proteinSequence, blastDatabase, msaAlgorithm, searchProgram, maxHits, msa, tree, treeMetadata, rid, geneId, transcriptId, transcriptName, geneName, }) {
+    return bestEffort('BLAST history write', async () => {
+        const db = await getDB();
+        const entry = {
+            id: createCacheKey({
+                proteinSequence,
+                blastDatabase,
+                msaAlgorithm,
+                searchProgram,
+                transcriptId,
+                maxHits,
+            }),
+            proteinSequence,
+            blastDatabase,
+            msaAlgorithm,
+            searchProgram,
+            maxHits,
+            msa,
+            tree,
+            treeMetadata,
+            rid,
+            timestamp: Date.now(),
+            geneId,
+            transcriptId,
+            transcriptName,
+            geneName,
+        };
+        await db.put(STORE_NAME, entry);
+        await evictOldest(db);
+        return entry;
+    }, undefined);
 }
 /**
  * Drop the oldest rows until the store is back at MAX_CACHED_RESULTS.

package/dist/utils/blastCache.test.js

@@ -1,29 +1,33 @@
-import { afterEach, beforeEach, expect, test, vi } from 'vitest';
-import { getAllCachedResults, saveBlastResult } from './blastCache';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { createCacheKey, getAllCachedResults, saveBlastResult, } from './blastCache';
 // An in-memory stand-in for the one object store this module opens. Only the
 // idb calls blastCache makes are implemented; anything else would be untested
 // scaffolding.
-const { rows } = vi.hoisted(() => ({
+const { rows, store } = vi.hoisted(() => ({
     rows: new Map(),
+    store: { refuses: false },
 }));
-vi.mock('./idb', () => ({
-    createDbOpener: () => () => Promise.resolve({
-        put: (_store, value) => {
-            rows.set(value.id, value);
-            return Promise.resolve(value.id);
-        },
-        count: () => Promise.resolve(rows.size),
-        getAll: () => Promise.resolve([...rows.values()]),
-        transaction: () => ({
-            store: {
-                delete: (id) => {
-                    rows.delete(id);
-                    return Promise.resolve();
-                },
+vi.mock('./idb', async (importOriginal) => ({
+    ...(await importOriginal()),
+    createDbOpener: () => () => store.refuses
+        ? Promise.reject(new DOMException('site data blocked', 'SecurityError'))
+        : Promise.resolve({
+            put: (_store, value) => {
+                rows.set(value.id, value);
+                return Promise.resolve(value.id);
             },
-            done: Promise.resolve(),
+            count: () => Promise.resolve(rows.size),
+            getAll: () => Promise.resolve([...rows.values()]),
+            transaction: () => ({
+                store: {
+                    delete: (id) => {
+                        rows.delete(id);
+                        return Promise.resolve();
+                    },
+                },
+                done: Promise.resolve(),
+            }),
         }),
-    }),
 }));
 function save(n) {
     return saveBlastResult({
@@ -38,6 +42,7 @@ function save(n) {
 }
 beforeEach(() => {
     rows.clear();
+    store.refuses = false;
     // strictly increasing, so "oldest" is unambiguous -- 55 saves in one
     // millisecond would otherwise all carry the same timestamp
     let clock = 1;
@@ -70,3 +75,25 @@ test('re-saving the same query overwrites its row rather than growing the store'
     await save(0);
     expect(rows.size).toBe(50);
 });
+// the alignment is already in hand by the time it is saved, so a browser that
+// refuses the write must not turn a finished search into a failed launch
+test('a store that refuses the write does not fail the save', async () => {
+    vi.spyOn(console, 'warn').mockImplementation(() => { });
+    store.refuses = true;
+    await expect(save(1)).resolves.toBeUndefined();
+});
+describe('createCacheKey', () => {
+    const base = {
+        proteinSequence: 'MKV',
+        blastDatabase: 'uniprotkb_swissprot',
+        msaAlgorithm: 'clustalo',
+    };
+    test('a different hit count is a different row', () => {
+        expect(createCacheKey({ ...base, maxHits: 50 })).not.toBe(createCacheKey({ ...base, maxHits: 500 }));
+    });
+    // rows saved before the hit count was in the key must still resolve
+    test('the default hit count keeps the key it always had', () => {
+        expect(createCacheKey({ ...base, maxHits: 100 })).toBe('uniprotkb_swissprot:clustalo:MKV');
+        expect(createCacheKey(base)).toBe('uniprotkb_swissprot:clustalo:MKV');
+    });
+});

package/dist/utils/domainCache.d.ts

@@ -4,5 +4,5 @@ interface CachedDomain {
     matches: DomainMatch[];
 }
 export declare function getCachedDomains(accessions: string[]): Promise<(CachedDomain | undefined)[]>;
-export declare function saveDomains(entries: CachedDomain[]): Promise<void>;
+export declare function saveDomains(entries: CachedDomain[]): Promise<void | undefined>;
 export {};

package/dist/utils/domainCache.js

@@ -1,4 +1,4 @@
-import { createDbOpener } from './idb';
+import { bestEffort, createDbOpener } from './idb';
 const DB_NAME = 'jbrowse-msaview-domain-cache';
 const STORE_NAME = 'domains';
 const DB_VERSION = 1;
@@ -7,18 +7,22 @@ const getDB = createDbOpener(DB_NAME, DB_VERSION, db => {
         db.createObjectStore(STORE_NAME, { keyPath: 'accession' });
     }
 });
-export async function getCachedDomains(accessions) {
-    const db = await getDB();
-    const tx = db.transaction(STORE_NAME, 'readonly');
-    const results = await Promise.all(accessions.map(accession => tx.store.get(accession)));
-    await tx.done;
-    return results;
+export function getCachedDomains(accessions) {
+    return bestEffort('domain cache read', async () => {
+        const db = await getDB();
+        const tx = db.transaction(STORE_NAME, 'readonly');
+        const results = await Promise.all(accessions.map(accession => tx.store.get(accession)));
+        await tx.done;
+        return results;
+    }, []);
 }
-export async function saveDomains(entries) {
-    const db = await getDB();
-    const tx = db.transaction(STORE_NAME, 'readwrite');
-    for (const entry of entries) {
-        await tx.store.put(entry);
-    }
-    await tx.done;
+export function saveDomains(entries) {
+    return bestEffort('domain cache write', async () => {
+        const db = await getDB();
+        const tx = db.transaction(STORE_NAME, 'readwrite');
+        for (const entry of entries) {
+            await tx.store.put(entry);
+        }
+        await tx.done;
+    }, undefined);
 }

package/dist/utils/ebiJobDispatcher.d.ts

@@ -21,6 +21,17 @@ export declare function submitEbiJob({ tool, params, signal, }: {
     params: Record<string, string>;
     signal?: AbortSignal;
 }): Promise<string>;
+/**
+ * A status check that could not reach EBI at all says nothing about the job, so
+ * it is not a reason to abandon one. A job the server has accepted keeps running
+ * whatever happens to the poller's connection, and EBI's cluster has answered
+ * status checks with a 502 for ten minutes on jobs that then finished (see
+ * docs/blast.md).
+ *
+ * So the poll gives up only once checks have failed without a break for this
+ * long: an endpoint that has genuinely gone away must not be polled forever.
+ */
+export declare const STATUS_FAILURE_BUDGET_MS: number;
 export declare function waitForEbiJob({ tool, jobId, intervalSeconds, onCountdown, signal, }: {
     tool: string;
     jobId: string;

package/dist/utils/ebiJobDispatcher.js

@@ -35,17 +35,16 @@ export async function submitEbiJob({ tool, params, signal, }) {
 /**
  * A status check that could not reach EBI at all says nothing about the job, so
  * it is not a reason to abandon one. A job the server has accepted keeps running
- * whatever happens to the poller's connection, and the poll is the long part: an
- * alignment of a hundred sequences runs for minutes and is checked every ten
- * seconds, so a single blip anywhere in that window used to throw away a job
- * that went on to finish.
+ * whatever happens to the poller's connection, and EBI's cluster has answered
+ * status checks with a 502 for ten minutes on jobs that then finished (see
+ * docs/blast.md).
  *
- * Consecutive failures still end it, because an endpoint that has genuinely gone
- * away must not be polled forever.
+ * So the poll gives up only once checks have failed without a break for this
+ * long: an endpoint that has genuinely gone away must not be polled forever.
  */
-const MAX_CONSECUTIVE_STATUS_FAILURES = 5;
+export const STATUS_FAILURE_BUDGET_MS = 15 * 60 * 1000;
 export async function waitForEbiJob({ tool, jobId, intervalSeconds = 10, onCountdown, signal, }) {
-    let consecutiveFailures = 0;
+    let failingSince;
     await pollLoop({
         intervalSeconds,
         onCountdown,
@@ -61,14 +60,14 @@ export async function waitForEbiJob({ tool, jobId, intervalSeconds = 10, onCount
                 if (isAbortError(e)) {
                     throw e;
                 }
-                consecutiveFailures += 1;
-                if (consecutiveFailures >= MAX_CONSECUTIVE_STATUS_FAILURES) {
-                    throw new Error(`Could not reach EBI to check ${tool} job ${jobId} after ${consecutiveFailures} tries`, { cause: e });
+                failingSince ??= Date.now();
+                if (Date.now() - failingSince >= STATUS_FAILURE_BUDGET_MS) {
+                    throw new Error(`Could not reach EBI to check ${tool} job ${jobId} for ${Math.round(STATUS_FAILURE_BUDGET_MS / 60_000)} minutes`, { cause: e });
                 }
-                console.warn(`[msaview] EBI status check ${consecutiveFailures} failed, retrying:`, e);
+                console.warn('[msaview] EBI status check failed, retrying:', e);
                 return false;
             }
-            consecutiveFailures = 0;
+            failingSince = undefined;
             // exact match, not includes(): a job whose status is ERROR must not be
             // able to poll forever waiting for a FINISHED that will never arrive
             if (status === 'FINISHED') {

package/dist/utils/ebiJobDispatcher.test.js

@@ -1,15 +1,22 @@
 import { afterEach, describe, expect, test, vi } from 'vitest';
-import { waitForEbiJob } from './ebiJobDispatcher';
+import { STATUS_FAILURE_BUDGET_MS, waitForEbiJob } from './ebiJobDispatcher';
 // A long alignment is polled every ten seconds for minutes, so the chance of one
 // failed status check somewhere in that window is not small -- and the job is
 // running at EBI regardless of what happens to the poller's connection.
 describe('waitForEbiJob', () => {
     afterEach(() => {
         vi.unstubAllGlobals();
+        vi.useRealTimers();
+        vi.restoreAllMocks();
     });
-    const statuses = (seq) => {
+    // each status check lands `minutesPerCheck` after the last, so a long outage
+    // is minutes of clock rather than minutes of test
+    const statuses = (seq, minutesPerCheck = 0) => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.spyOn(console, 'warn').mockImplementation(() => { });
         let i = 0;
         vi.stubGlobal('fetch', () => {
+            vi.setSystemTime(Date.now() + minutesPerCheck * 60_000);
             const next = seq[Math.min(i++, seq.length - 1)];
             return next instanceof Error
                 ? Promise.reject(next)
@@ -44,9 +51,16 @@ describe('waitForEbiJob', () => {
         ]);
         await expect(wait()).resolves.toBeUndefined();
     });
+    test('ten minutes of failed checks do not abandon a job that then finishes', async () => {
+        const outage = Array.from({ length: 10 }, () => new Error('HTTP 502'));
+        statuses(['RUNNING', ...outage, 'FINISHED'], 1);
+        await expect(wait()).resolves.toBeUndefined();
+    });
     test('an endpoint that has genuinely gone away is not polled forever', async () => {
-        statuses([new TypeError('Failed to fetch')]);
+        statuses([new TypeError('Failed to fetch')], 1);
+        const start = Date.now();
         await expect(wait()).rejects.toThrow(/Could not reach EBI/);
+        expect(Date.now() - start).toBeGreaterThanOrEqual(STATUS_FAILURE_BUDGET_MS);
     });
     test('a job EBI reports as failed still ends the poll immediately', async () => {
         statuses(['ERROR']);

package/dist/utils/eutils.d.ts

@@ -1,5 +1,7 @@
 export declare const NCBI_TOOL = "jbrowse-plugin-msaview";
 export declare const NCBI_EMAIL = "colin.diesh@gmail.com";
+type Endpoint = 'efetch' | 'esearch' | 'esummary';
+export declare function eutilsUrl(endpoint: Endpoint, params: Record<string, string>): string;
 export declare function efetchUrl(params: Record<string, string>): string;
 /**
  * The same request as a POST body. An `id` list of a few hundred accessions
@@ -10,3 +12,15 @@ export declare function efetchPost(params: Record<string, string>): readonly ["h
     readonly method: "POST";
     readonly body: URLSearchParams;
 }];
+/**
+ * eutils allows 3 requests a second without an API key and answers a burst
+ * over that with no `Access-Control-Allow-Origin`, which the browser reports as
+ * a CORS failure. Every eutils request takes the next start slot, so however
+ * many callers ask at once the requests go out under the limit.
+ */
+export declare const EUTILS_SPACING_MS = 350;
+export declare function eutilsText(url: string, init?: RequestInit): Promise<string>;
+export declare function eutilsJson<T>(url: string, init?: RequestInit): Promise<T>;
+/** Text lifted out of eutils XML still carries its escapes: `5&apos;-3&apos;`. */
+export declare function decodeXmlEntities(text: string): string;
+export {};

package/dist/utils/eutils.js

@@ -1,16 +1,18 @@
+import { jsonfetch, textfetch, timeout } from './fetch';
 // NCBI asks that programmatic E-utilities requests identify themselves with a
 // tool name and contact email so they can reach out before throttling, rather
 // than silently rate-limiting. https://www.ncbi.nlm.nih.gov/books/NBK25497/
 export const NCBI_TOOL = 'jbrowse-plugin-msaview';
 export const NCBI_EMAIL = 'colin.diesh@gmail.com';
 const EUTILS = 'https://eutils.ncbi.nlm.nih.gov/entrez/eutils';
+function identified(params) {
+    return new URLSearchParams({ ...params, tool: NCBI_TOOL, email: NCBI_EMAIL });
+}
+export function eutilsUrl(endpoint, params) {
+    return `${EUTILS}/${endpoint}.fcgi?${identified(params).toString()}`;
+}
 export function efetchUrl(params) {
-    const search = new URLSearchParams({
-        ...params,
-        tool: NCBI_TOOL,
-        email: NCBI_EMAIL,
-    });
-    return `${EUTILS}/efetch.fcgi?${search.toString()}`;
+    return eutilsUrl('efetch', params);
 }
 /**
  * The same request as a POST body. An `id` list of a few hundred accessions
@@ -20,13 +22,45 @@ export function efetchUrl(params) {
 export function efetchPost(params) {
     return [
         `${EUTILS}/efetch.fcgi`,
-        {
-            method: 'POST',
-            body: new URLSearchParams({
-                ...params,
-                tool: NCBI_TOOL,
-                email: NCBI_EMAIL,
-            }),
-        },
+        { method: 'POST', body: identified(params) },
     ];
 }
+/**
+ * eutils allows 3 requests a second without an API key and answers a burst
+ * over that with no `Access-Control-Allow-Origin`, which the browser reports as
+ * a CORS failure. Every eutils request takes the next start slot, so however
+ * many callers ask at once the requests go out under the limit.
+ */
+export const EUTILS_SPACING_MS = 350;
+let nextSlot = 0;
+async function eutilsSlot(signal) {
+    const now = Date.now();
+    const start = Math.max(now, nextSlot);
+    nextSlot = start + EUTILS_SPACING_MS;
+    if (start > now) {
+        await timeout(start - now, signal ?? undefined);
+    }
+}
+export async function eutilsText(url, init) {
+    await eutilsSlot(init?.signal);
+    return textfetch(url, init);
+}
+export async function eutilsJson(url, init) {
+    await eutilsSlot(init?.signal);
+    return jsonfetch(url, init);
+}
+const namedEntities = {
+    amp: '&',
+    apos: "'",
+    gt: '>',
+    lt: '<',
+    quot: '"',
+};
+/** Text lifted out of eutils XML still carries its escapes: `5&apos;-3&apos;`. */
+export function decodeXmlEntities(text) {
+    return text.replaceAll(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, name) => name.startsWith('#x') || name.startsWith('#X')
+        ? String.fromCodePoint(Number.parseInt(name.slice(2), 16))
+        : name.startsWith('#')
+            ? String.fromCodePoint(Number(name.slice(1)))
+            : (namedEntities[name] ?? entity));
+}

package/dist/utils/eutils.test.d.ts

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

package/dist/utils/eutils.test.js

@@ -0,0 +1,31 @@
+import { afterEach, expect, test, vi } from 'vitest';
+import { EUTILS_SPACING_MS, decodeXmlEntities, eutilsText } from './eutils';
+afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+});
+test('decodes the escapes GenPept and taxonomy XML carry', () => {
+    expect(decodeXmlEntities('5'-3' exonuclease')).toBe("5'-3' exonuclease");
+    expect(decodeXmlEntities('A &amp; B &lt;C&gt; &quot;D&quot;')).toBe('A & B <C> "D"');
+    expect(decodeXmlEntities('&#39;&#x41;&unknown;')).toBe("'A&unknown;");
+});
+// a burst over three a second comes back without CORS headers, which the
+// browser reports as a CORS failure for an endpoint that sends ACAO: *
+test('concurrent eutils requests go out spaced under the rate limit', async () => {
+    vi.useFakeTimers();
+    const sentAt = [];
+    vi.stubGlobal('fetch', () => {
+        sentAt.push(Date.now());
+        return Promise.resolve({
+            ok: true,
+            status: 200,
+            text: () => Promise.resolve(''),
+        });
+    });
+    const all = Promise.all([eutilsText('a'), eutilsText('b'), eutilsText('c')]);
+    await vi.advanceTimersByTimeAsync(3 * EUTILS_SPACING_MS);
+    await all;
+    expect(sentAt).toHaveLength(3);
+    expect(sentAt[1] - sentAt[0]).toBeGreaterThanOrEqual(EUTILS_SPACING_MS);
+    expect(sentAt[2] - sentAt[1]).toBeGreaterThanOrEqual(EUTILS_SPACING_MS);
+});

package/dist/utils/idb.d.ts

@@ -2,11 +2,24 @@ import type { DBSchema, IDBPDatabase, OpenDBCallbacks } from 'idb';
 /**
  * Memoized `openDB` for a typed schema, shared by this plugin's caches.
  *
- * The connection promise is cached so callers share one connection, and dropped
- * again if the open fails, so a later call retries instead of replaying the same
- * rejection forever (IndexedDB is unavailable in some private-browsing modes).
+ * Callers share one connection. The opener forgets it whenever it stops being
+ * usable, so the next call opens a fresh one instead of replaying a rejection
+ * or waiting on a dead handle: when the open fails (IndexedDB is unavailable in
+ * some private-browsing modes), when another tab is blocked upgrading the
+ * database and this connection steps aside for it, and when the browser
+ * terminates the connection.
+ *
+ * An open blocked by another tab's older connection rejects rather than waiting
+ * for that tab to close, which may never happen, since a build that predates
+ * `blocking` never steps aside.
  *
  * Passing a DBSchema is what keeps `get`/`getAll` from returning `any`: with an
  * untyped database every cached record reaches the UI unchecked.
  */
 export declare function createDbOpener<T extends DBSchema>(name: string, version: number, upgrade: OpenDBCallbacks<T>['upgrade']): () => Promise<IDBPDatabase<T>>;
+/**
+ * Run a cache operation that the caller can do without. A cache only saves
+ * work, so a read that fails answers `fallback` (a miss) and a write that fails
+ * is skipped: neither may cost the user a search that already finished.
+ */
+export declare function bestEffort<R>(what: string, operation: () => Promise<R>, fallback: R): Promise<R>;

package/dist/utils/idb.js

@@ -2,20 +2,66 @@ import { openDB } from 'idb';
 /**
  * Memoized `openDB` for a typed schema, shared by this plugin's caches.
  *
- * The connection promise is cached so callers share one connection, and dropped
- * again if the open fails, so a later call retries instead of replaying the same
- * rejection forever (IndexedDB is unavailable in some private-browsing modes).
+ * Callers share one connection. The opener forgets it whenever it stops being
+ * usable, so the next call opens a fresh one instead of replaying a rejection
+ * or waiting on a dead handle: when the open fails (IndexedDB is unavailable in
+ * some private-browsing modes), when another tab is blocked upgrading the
+ * database and this connection steps aside for it, and when the browser
+ * terminates the connection.
+ *
+ * An open blocked by another tab's older connection rejects rather than waiting
+ * for that tab to close, which may never happen, since a build that predates
+ * `blocking` never steps aside.
  *
  * Passing a DBSchema is what keeps `get`/`getAll` from returning `any`: with an
  * untyped database every cached record reaches the UI unchecked.
  */
 export function createDbOpener(name, version, upgrade) {
     let dbPromise;
+    const forget = () => {
+        dbPromise = undefined;
+    };
     return () => {
-        dbPromise ??= openDB(name, version, { upgrade }).catch((e) => {
-            dbPromise = undefined;
+        dbPromise ??= new Promise((resolve, reject) => {
+            let gaveUp = false;
+            openDB(name, version, {
+                upgrade,
+                blocked(currentVersion) {
+                    gaveUp = true;
+                    reject(new Error(`${name} is held open at version ${currentVersion} by another tab`));
+                },
+                blocking(_currentVersion, _blockedVersion, event) {
+                    ;
+                    event.target.close();
+                    forget();
+                },
+                terminated: forget,
+            }).then(db => {
+                if (gaveUp) {
+                    db.close();
+                }
+                else {
+                    resolve(db);
+                }
+            }, reject);
+        }).catch((e) => {
+            forget();
             throw e;
         });
         return dbPromise;
     };
 }
+/**
+ * Run a cache operation that the caller can do without. A cache only saves
+ * work, so a read that fails answers `fallback` (a miss) and a write that fails
+ * is skipped: neither may cost the user a search that already finished.
+ */
+export async function bestEffort(what, operation, fallback) {
+    try {
+        return await operation();
+    }
+    catch (e) {
+        console.warn(`[msaview] ${what} failed, continuing without it:`, e);
+        return fallback;
+    }
+}

package/dist/utils/idb.test.d.ts

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