jbrowse-plugin-msaview 3.4.0 → 3.5.0

package/src/MsaViewPanel/storedData.test.ts

@@ -0,0 +1,196 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+import { loadStoredData, storeDataToIndexedDB } from './afterCreateAutoruns'
+import {
+  generateDataStoreId,
+  retrieveMsaData,
+  storeMsaData,
+} from './msaDataStore'
+
+import type { JBrowsePluginMsaViewModel } from './model'
+import type { MsaDataPayload } from './msaDataStore'
+
+// IndexedDB itself is msaDataStore.test.ts's subject; what is under test here is
+// which writes these two autoruns decide to make.
+vi.mock('./msaDataStore', () => ({
+  cleanupOldData: vi.fn(),
+  generateDataStoreId: vi.fn(),
+  retrieveMsaData: vi.fn(),
+  storeMsaData: vi.fn(),
+}))
+
+const mockRetrieve = vi.mocked(retrieveMsaData)
+const mockStore = vi.mocked(storeMsaData)
+const mockGenerateId = vi.mocked(generateDataStoreId)
+
+const MSA = '>a\nMK'
+const NEW_ID = 'msa-generated'
+
+function makeModel(over: Record<string, unknown> = {}) {
+  const model = {
+    dataStoreId: undefined as string | undefined,
+    rows: [] as string[][],
+    data: {} as MsaDataPayload,
+    msaFilehandle: undefined,
+    treeFilehandle: undefined,
+    isStoringData: false,
+    lastStoredData: undefined as MsaDataPayload | undefined,
+    loadingStoredData: false,
+    error: undefined as unknown,
+    setDataStoreId(arg?: string) {
+      model.dataStoreId = arg
+    },
+    setIsStoringData(arg: boolean) {
+      model.isStoringData = arg
+    },
+    setLastStoredData(arg?: MsaDataPayload) {
+      model.lastStoredData = arg
+    },
+    setLoadingStoredData(arg: boolean) {
+      model.loadingStoredData = arg
+    },
+    setError(arg: unknown) {
+      model.error = arg
+    },
+    setMSA(arg: string) {
+      model.data.msa = arg
+    },
+    setTree(arg: string) {
+      model.data.tree = arg
+    },
+    setTreeMetadata(arg: string) {
+      model.data.treeMetadata = arg
+    },
+    ...over,
+  }
+  return model as typeof model & JBrowsePluginMsaViewModel
+}
+
+const settle = () => new Promise(res => setTimeout(res, 0))
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  mockGenerateId.mockReturnValue(NEW_ID)
+  mockStore.mockResolvedValue(true)
+})
+
+describe('restoring a view from IndexedDB', () => {
+  test('a row that is still there is applied and recorded as stored', async () => {
+    mockRetrieve.mockResolvedValue({
+      msa: MSA,
+      tree: '(a);',
+      treeMetadata: '{}',
+    })
+    const model = makeModel({ dataStoreId: 'msa-1' })
+
+    loadStoredData(model)
+    await settle()
+
+    expect(model.data.msa).toBe(MSA)
+    expect(model.error).toBeUndefined()
+    // recorded, so the store autorun does not write the restored data straight
+    // back out again
+    expect(model.lastStoredData).toEqual({
+      msa: MSA,
+      tree: '(a);',
+      treeMetadata: '{}',
+    })
+    model.rows = [['a', 'MK']]
+    storeDataToIndexedDB(model)
+    expect(mockStore).not.toHaveBeenCalled()
+  })
+
+  // the row expires or the user clears site data, and the view used to reopen as
+  // a blank import form with no hint that anything had been lost
+  test('a row that is gone says so, in words that name the policy', async () => {
+    mockRetrieve.mockResolvedValue(undefined)
+    const model = makeModel({ dataStoreId: 'msa-1' })
+
+    loadStoredData(model)
+    await settle()
+
+    expect(model.error).toBeInstanceOf(Error)
+    expect((model.error as Error).message).toMatch(/7 days/)
+    // the id names nothing now, so it goes -- otherwise react-msaview's "Return
+    // to import form" lands straight back on this error
+    expect(model.dataStoreId).toBeUndefined()
+  })
+})
+
+describe('keeping IndexedDB up to date', () => {
+  test('the first alignment is written under a fresh id', async () => {
+    const model = makeModel({ rows: [['a', 'MK']], data: { msa: MSA } })
+
+    storeDataToIndexedDB(model)
+    await settle()
+
+    expect(mockStore).toHaveBeenCalledWith(NEW_ID, { msa: MSA })
+    expect(model.dataStoreId).toBe(NEW_ID)
+    expect(model.isStoringData).toBe(false)
+  })
+
+  // react-msaview's "calculate neighbor-joining tree" replaces data.tree long
+  // after the first write; the row used to keep the alignment's original tree
+  // forever, so a reopened session restored a picture the user had replaced
+  test('an edit after the first write updates the existing row', async () => {
+    const model = makeModel({
+      dataStoreId: 'msa-1',
+      rows: [['a', 'MK']],
+      data: { msa: MSA, tree: '(a);' },
+      lastStoredData: { msa: MSA, tree: '(a);' },
+    })
+
+    storeDataToIndexedDB(model)
+    expect(mockStore).not.toHaveBeenCalled()
+
+    model.data.tree = '(a:0.1);'
+    storeDataToIndexedDB(model)
+    await settle()
+
+    expect(mockStore).toHaveBeenCalledWith('msa-1', {
+      msa: MSA,
+      tree: '(a:0.1);',
+      treeMetadata: undefined,
+    })
+    expect(model.dataStoreId).toBe('msa-1')
+  })
+
+  // a browser that refuses IndexedDB (private mode) answers every write the same
+  // way, and the autorun reruns on its own isStoringData flag -- so a write that
+  // is not recorded as attempted is a write that retries forever
+  test('a write that fails is not retried on the same data', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    mockStore.mockResolvedValue(false)
+    const model = makeModel({ rows: [['a', 'MK']], data: { msa: MSA } })
+
+    storeDataToIndexedDB(model)
+    await settle()
+    expect(model.dataStoreId).toBeUndefined()
+
+    storeDataToIndexedDB(model)
+    await settle()
+    expect(mockStore).toHaveBeenCalledTimes(1)
+  })
+
+  test('a view reading from a filehandle stores nothing, since the file is the source', () => {
+    storeDataToIndexedDB(
+      makeModel({
+        rows: [['a', 'MK']],
+        data: { msa: MSA },
+        msaFilehandle: { uri: 'msa.fa', locationType: 'UriLocation' },
+      }),
+    )
+    expect(mockStore).not.toHaveBeenCalled()
+  })
+
+  test('a write already in flight is not duplicated', () => {
+    storeDataToIndexedDB(
+      makeModel({
+        rows: [['a', 'MK']],
+        data: { msa: MSA },
+        isStoringData: true,
+      }),
+    )
+    expect(mockStore).not.toHaveBeenCalled()
+  })
+})

package/src/MsaViewPanel/structureConnection.ts

@@ -31,29 +31,3 @@ export function isProteinView(view: unknown): view is ProteinView {
 export function getProteinViews(views: { type: string }[]): ProteinView[] {
   return (views as unknown[]).filter(isProteinView)
 }
-
-/**
- * Helper to convert gapped MSA column to ungapped position for a specific row
- */
-export function gappedToUngappedPosition(
-  sequence: string,
-  gappedPosition: number,
-): number | undefined {
-  if (gappedPosition < 0 || gappedPosition >= sequence.length) {
-    return undefined
-  }
-
-  let ungapped = 0
-  for (let i = 0; i < gappedPosition; i++) {
-    if (sequence[i] !== '-') {
-      ungapped++
-    }
-  }
-
-  // If the position itself is a gap, return undefined
-  if (sequence[gappedPosition] === '-') {
-    return undefined
-  }
-
-  return ungapped
-}

package/src/MsaViewPanel/util.ts

@@ -16,6 +16,81 @@ export function hasQueryRow(model: { rows: string[][]; querySeqName: string }) {
   return model.rows.some(r => r[0] === model.querySeqName)
 }
 
+/**
+ * The transcript a launch was started from, as it is stored: plain JSON.
+ *
+ * blastParams and orthologParams are frozen snapshot properties, so a Feature
+ * instance put in one lives only as long as the tab. A reloaded session hands
+ * back the JSON the instance serialized to, and `.get()` on that threw --
+ * minutes after the EBI job the reload resubmitted had finally come back.
+ */
+export type TranscriptRef = Record<string, unknown> | LiveFeature
+
+interface LiveFeature {
+  toJSON: () => Record<string, unknown>
+}
+
+/**
+ * Read the transcript's fields whichever shape it arrived in: a caller inside
+ * the session may still hand over a live Feature.
+ */
+export function transcriptFields(transcript?: TranscriptRef) {
+  if (!transcript) {
+    return {}
+  }
+  return typeof (transcript as LiveFeature).toJSON === 'function'
+    ? (transcript as LiveFeature).toJSON()
+    : (transcript as Record<string, unknown>)
+}
+
+function str(val: unknown) {
+  return typeof val === 'string' ? val : undefined
+}
+
+/** what a transcript is called, preferring its name over its id */
+export function transcriptName(transcript?: TranscriptRef) {
+  const fields = transcriptFields(transcript)
+  return str(fields.name) ?? str(fields.id)
+}
+
+export interface QueryRowModel {
+  querySeqName: string
+  querySeqOffset: number
+  seqPosToVisibleCol: (rowName: string, seqPos: number) => number | undefined
+  visibleColToSeqPos: (
+    rowName: string,
+    visibleCol: number,
+  ) => number | undefined
+}
+
+/**
+ * The visible column showing residue `proteinPos` (0-based) of the transcript,
+ * or undefined when the query row does not carry that residue or react-msaview
+ * is hiding its column.
+ *
+ * Two things separate the transcript from the row. `querySeqOffset` is the
+ * trimming — a pasted BLAST alignment carries the aligned region, not the whole
+ * protein. And the row can simply stop short: react-msaview answers one column
+ * past the end for a position it does not have, which would light the last
+ * column for every residue beyond the row, so the round trip back through
+ * visibleColToSeqPos is what rejects those.
+ */
+export function transcriptPosToVisibleCol(
+  model: QueryRowModel,
+  proteinPos: number,
+) {
+  const { querySeqName, querySeqOffset } = model
+  const seqPos = proteinPos - querySeqOffset
+  if (seqPos < 0) {
+    return undefined
+  }
+  const col = model.seqPosToVisibleCol(querySeqName, seqPos)
+  return col !== undefined &&
+    model.visibleColToSeqPos(querySeqName, col) === seqPos
+    ? col
+    : undefined
+}
+
 export function hasHoverPosition(
   hovered: unknown,
 ): hovered is { hoverPosition: { coord: number; refName: string } } {

package/src/utils/blastCache.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest'
+
+import { getAllCachedResults, saveBlastResult } from './blastCache'
+
+import type { CachedBlastResult } 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(() => ({
+  rows: new Map<string, { id: string; timestamp: number }>(),
+}))
+
+vi.mock('./idb', () => ({
+  createDbOpener: () => () =>
+    Promise.resolve({
+      put: (_store: string, value: { id: string }) => {
+        rows.set(value.id, value as { id: string; timestamp: number })
+        return Promise.resolve(value.id)
+      },
+      count: () => Promise.resolve(rows.size),
+      getAll: () => Promise.resolve([...rows.values()]),
+      transaction: () => ({
+        store: {
+          delete: (id: string) => {
+            rows.delete(id)
+            return Promise.resolve()
+          },
+        },
+        done: Promise.resolve(),
+      }),
+    }),
+}))
+
+function save(n: number) {
+  return saveBlastResult({
+    proteinSequence: `SEQ${n}`,
+    blastDatabase: 'uniprotkb_swissprot',
+    msaAlgorithm: 'clustalo',
+    msa: '>a\nMK',
+    tree: '(a);',
+    treeMetadata: '{}',
+    rid: `job-${n}`,
+  })
+}
+
+beforeEach(() => {
+  rows.clear()
+  // strictly increasing, so "oldest" is unambiguous -- 55 saves in one
+  // millisecond would otherwise all carry the same timestamp
+  let clock = 1
+  vi.spyOn(Date, 'now').mockImplementation(() => clock++)
+})
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+test('a store at the cap loses nothing', async () => {
+  for (let i = 0; i < 50; i++) {
+    await save(i)
+  }
+  expect(rows.size).toBe(50)
+})
+
+// Every row holds a whole alignment and its tree, so an unbounded store grows
+// until the browser refuses writes to it and the user never learns why.
+test('going over the cap drops the oldest results and keeps the newest 50', async () => {
+  for (let i = 0; i < 55; i++) {
+    await save(i)
+  }
+  expect(rows.size).toBe(50)
+  const rids = (await getAllCachedResults()).map(
+    (r: CachedBlastResult) => r.rid,
+  )
+  expect(rids.at(0)).toBe('job-54')
+  expect(rids.at(-1)).toBe('job-5')
+})
+
+test('re-saving the same query overwrites its row rather than growing the store', async () => {
+  for (let i = 0; i < 50; i++) {
+    await save(i)
+  }
+  await save(0)
+  expect(rows.size).toBe(50)
+})

package/src/utils/blastCache.ts

@@ -6,12 +6,19 @@ import type {
   PhmmerDatabase,
   SearchProgram,
 } from '../LaunchMsaView/components/BlastQuery/consts'
-import type { DBSchema } from 'idb'
+import type { DBSchema, IDBPDatabase } from 'idb'
 
 const DB_NAME = 'jbrowse-msaview-blast-cache'
 const STORE_NAME = 'blast-results'
 const DB_VERSION = 2
 
+/**
+ * How many results the history keeps. Every row holds a whole alignment and its
+ * tree — megabytes each — so an unbounded store grows until the browser starts
+ * refusing writes to it, and the user never sees why.
+ */
+const MAX_CACHED_RESULTS = 50
+
 export interface CachedBlastResult {
   id: string
   proteinSequence: string
@@ -134,9 +141,35 @@ export async function saveBlastResult({
     geneName,
   }
   await db.put(STORE_NAME, entry)
+  await evictOldest(db)
   return entry
 }
 
+/**
+ * Drop the oldest rows until the store is back at MAX_CACHED_RESULTS.
+ *
+ * `count` first so the common save reads no values at all: without a timestamp
+ * index the oldest have to be found by loading every row, and each one is an
+ * entire alignment. Failing to evict must not fail the save — the result is
+ * already in hand and losing it to a housekeeping error would be the worse
+ * outcome.
+ */
+async function evictOldest(db: IDBPDatabase<BlastCacheDB>) {
+  try {
+    if ((await db.count(STORE_NAME)) <= MAX_CACHED_RESULTS) {
+      return
+    }
+    const all = await db.getAll(STORE_NAME)
+    const doomed = all
+      .toSorted((a, b) => a.timestamp - b.timestamp)
+      .slice(0, all.length - MAX_CACHED_RESULTS)
+    const tx = db.transaction(STORE_NAME, 'readwrite')
+    await Promise.all([...doomed.map(e => tx.store.delete(e.id)), tx.done])
+  } catch (e) {
+    console.warn('Failed to evict old BLAST cache entries:', e)
+  }
+}
+
 export async function getAllCachedResults() {
   const db = await getDB()
   const results = await db.getAll(STORE_NAME)

package/src/utils/browserAlign.test.ts

@@ -0,0 +1,102 @@
+import { expect, test } from 'vitest'
+
+import {
+  alignInBrowser,
+  alignToQuery,
+  mergeOnQuery,
+  parseFastaRecords,
+} from './browserAlign'
+
+test('an identical target sits residue for residue under the query', () => {
+  const { matched, inserts } = alignToQuery('MKWVTFISLL', 'MKWVTFISLL')
+  expect(matched.join('')).toBe('MKWVTFISLL')
+  expect(inserts.every(i => i === '')).toBe(true)
+})
+
+test('a deletion in the target is a gap under the query', () => {
+  const { matched, inserts } = alignToQuery(
+    'MKWVTFISLLFLFSSAYS',
+    'MKWVTLLFLFSSAYS',
+  )
+  expect(matched.join('').replaceAll('-', '')).toBe('MKWVTLLFLFSSAYS')
+  expect(matched.filter(c => c === '-')).toHaveLength(3)
+  expect(inserts.every(i => i === '')).toBe(true)
+})
+
+test('an insertion in the target lands between two query residues', () => {
+  const query = 'MKWVTFISLLFLFSSAYS'
+  const target = 'MKWVTFISLLGGGGFLFSSAYS'
+  const { matched, inserts } = alignToQuery(query, target)
+  expect(matched.join('')).toBe(query)
+  expect(inserts.join('|')).toBe('|'.repeat(10) + 'GGGG' + '|'.repeat(8))
+})
+
+test('end gaps are free, so a domain-only target is not dragged across the flanks', () => {
+  const query = 'AAAAAAAAAAMKWVTFISLLFLFSSAYSAAAAAAAAAA'
+  const target = 'MKWVTFISLLFLFSSAYS'
+  const { matched, inserts } = alignToQuery(query, target)
+  expect(matched.join('')).toBe('----------MKWVTFISLLFLFSSAYS----------')
+  expect(inserts.every(i => i === '')).toBe(true)
+})
+
+test('a target that overhangs the query puts the overhang in the end inserts', () => {
+  const query = 'MKWVTFISLLFLFSSAYS'
+  const target = 'PPPPMKWVTFISLLFLFSSAYSQQQQ'
+  const { matched, inserts } = alignToQuery(query, target)
+  expect(matched.join('')).toBe(query)
+  expect(inserts[0]).toBe('PPPP')
+  expect(inserts.at(-1)).toBe('QQQQ')
+})
+
+test('merging pads every row to the longest insert at each query position', () => {
+  const query = { name: 'q', sequence: 'MKWVTF' }
+  const rows = mergeOnQuery(query, [
+    {
+      name: 'a',
+      alignment: alignToQuery(query.sequence, 'MKWGGVTF'),
+    },
+    {
+      name: 'b',
+      alignment: alignToQuery(query.sequence, 'MKWGVTF'),
+    },
+    {
+      name: 'c',
+      alignment: alignToQuery(query.sequence, 'MKWVTF'),
+    },
+  ])
+  expect(rows.map(r => r.sequence)).toEqual([
+    'MKW--VTF',
+    'MKWGGVTF',
+    'MKWG-VTF',
+    'MKW--VTF',
+  ])
+  expect(new Set(rows.map(r => r.sequence.length)).size).toBe(1)
+})
+
+test('alignInBrowser returns FASTA with the query first and every row the same length', async () => {
+  const progress: string[] = []
+  const fasta = await alignInBrowser({
+    query: { name: 'QUERY', sequence: 'MEEPQSDPSVEPPLSQETFSDLWKLLPENNV' },
+    targets: [
+      { name: 'a', sequence: 'MEEPQSDPSVEPPLSQETFSDLWKLLPENNV' },
+      { name: 'b', sequence: 'MEPQSDPSVEPPLSQETFSDLW' },
+      { name: 'c', sequence: 'SQETFSDLWKLLPENNVXXXXX' },
+    ],
+    onProgress: s => progress.push(s),
+  })
+  const records = parseFastaRecords(fasta)
+  expect(records.map(r => r.name)).toEqual(['QUERY', 'a', 'b', 'c'])
+  const lengths = fasta
+    .split('\n')
+    .filter(l => !l.startsWith('>'))
+    .map(l => l.length)
+  expect(new Set(lengths).size).toBe(1)
+  expect(progress.length).toBeGreaterThan(0)
+})
+
+test('parseFastaRecords strips gaps and stops, and keeps the first header token', () => {
+  expect(parseFastaRecords('>a desc\nMK-W*\nVT\n>b\nMM')).toEqual([
+    { name: 'a', sequence: 'MKWVT' },
+    { name: 'b', sequence: 'MM' },
+  ])
+})