jbrowse-plugin-protein3d 0.4.11 → 0.4.13

package/src/ProteinView/loadStructureData.ts

@@ -0,0 +1,36 @@
+import { addStructureFromData } from './addStructureFromData'
+import { addStructureFromURL } from './addStructureFromURL'
+import { extractPerResidueConfidence } from './extractPerResidueConfidence'
+import { extractStructureSequences } from './extractStructureSequences'
+
+import type { PluginContext } from 'molstar/lib/mol-plugin/context'
+
+export interface StructureData {
+  sequences?: string[]
+  confidence?: number[]
+}
+
+/**
+ * Loads a structure (from inline data or a URL) into the given Molstar plugin
+ * and pulls out its per-chain sequences and per-residue confidence. Pure with
+ * respect to the model — it only touches the plugin and returns plain data, so
+ * callers own the decision of whether/where to store the result.
+ */
+export async function loadStructureData({
+  structure,
+  plugin,
+}: {
+  structure: { data?: string; url?: string }
+  plugin: PluginContext
+}): Promise<StructureData> {
+  const { model } = structure.data
+    ? await addStructureFromData({ data: structure.data, plugin })
+    : structure.url
+      ? await addStructureFromURL({ url: structure.url, plugin })
+      : { model: undefined }
+  const sequences = model ? extractStructureSequences(model) : undefined
+  const confidence = model
+    ? extractPerResidueConfidence(model, sequences?.[0]?.length)
+    : undefined
+  return { sequences, confidence }
+}

package/src/ProteinView/model.ts

@@ -5,16 +5,14 @@ import SettingsIcon from '@mui/icons-material/Settings'
 import Visibility from '@mui/icons-material/Visibility'
 import { autorun } from 'mobx'
 
-import { addStructureFromData } from './addStructureFromData'
-import { addStructureFromURL } from './addStructureFromURL'
 import {
   COLOR_SCHEMES,
   COLOR_SCHEME_VALUES,
   type ProteinColorScheme,
   applyColorTheme,
 } from './applyColorTheme'
-import { extractPerResidueConfidence } from './extractPerResidueConfidence'
-import { extractStructureSequences } from './extractStructureSequences'
+import { loadStructureData } from './loadStructureData'
+import { makeStructureLoader } from './structureLoader'
 import Structure from './structureModel'
 import { superposeStructures } from './superposeStructures'
 import { type AlignmentAlgorithm, DEFAULT_ALIGNMENT_ALGORITHM } from './types'
@@ -32,25 +30,6 @@ const PERSISTED_SETTINGS = [
 import type { Instance } from '@jbrowse/mobx-state-tree'
 import type { PluginContext } from 'molstar/lib/mol-plugin/context'
 
-async function loadStructureData({
-  structure,
-  plugin,
-}: {
-  structure: { data?: string; url?: string }
-  plugin: PluginContext
-}) {
-  const { model } = structure.data
-    ? await addStructureFromData({ data: structure.data, plugin })
-    : structure.url
-      ? await addStructureFromURL({ url: structure.url, plugin })
-      : { model: undefined }
-  const sequences = model ? extractStructureSequences(model) : undefined
-  const confidence = model
-    ? extractPerResidueConfidence(model, sequences?.[0]?.length)
-    : undefined
-  return { sequences, confidence }
-}
-
 export interface ProteinViewInitState {
   structures?: {
     url?: string
@@ -420,30 +399,10 @@ function stateModelFactory() {
           }),
         )
 
-        addDisposer(
-          self,
-          autorun(async () => {
-            const { structures, molstarPluginContext } = self
-            if (molstarPluginContext) {
-              for (const structure of structures) {
-                if (!structure.loadedToMolstar) {
-                  try {
-                    structure.setStructureData(
-                      await loadStructureData({
-                        structure,
-                        plugin: molstarPluginContext,
-                      }),
-                    )
-                    structure.setLoadedToMolstar(true)
-                  } catch (e) {
-                    self.setError(e)
-                    console.error(e)
-                  }
-                }
-              }
-            }
-          }),
-        )
+        // Load structures into Molstar as they appear or whenever the plugin
+        // context changes. See makeStructureLoader for why the autorun body is
+        // synchronous and how it guards against duplicate/stale loads.
+        addDisposer(self, autorun(makeStructureLoader(self)))
       },
     }))
     .views(self => ({

package/src/ProteinView/structureLoader.test.ts

@@ -0,0 +1,102 @@
+import { types } from '@jbrowse/mobx-state-tree'
+import { beforeEach, expect, test, vi } from 'vitest'
+
+import { loadStructureData } from './loadStructureData'
+import { makeStructureLoader } from './structureLoader'
+
+import type { StructureLoaderHost } from './structureLoader'
+
+vi.mock('./loadStructureData', () => ({ loadStructureData: vi.fn() }))
+const mockLoad = vi.mocked(loadStructureData)
+
+// Minimal stand-ins matching only the surface makeStructureLoader touches, so
+// the test exercises the loader's guard logic without molstar/structureModel.
+const TestStructure = types
+  .model('TestStructure', {})
+  .volatile(() => ({
+    loadedToMolstar: false,
+    sequences: undefined as string[] | undefined,
+  }))
+  .actions(self => ({
+    setStructureData(d: { sequences?: string[] }) {
+      self.sequences = d.sequences
+    },
+    setLoadedToMolstar(v: boolean) {
+      self.loadedToMolstar = v
+    },
+  }))
+
+const TestHost = types
+  .model('TestHost', { structures: types.array(TestStructure) })
+  .volatile(() => ({
+    molstarPluginContext: undefined as object | undefined,
+    errors: [] as unknown[],
+  }))
+  .actions(self => ({
+    setPlugin(p: object) {
+      self.molstarPluginContext = p
+    },
+    setError(e: unknown) {
+      self.errors.push(e)
+    },
+  }))
+
+function setup(plugin: object) {
+  const host = TestHost.create({ structures: [{}] })
+  host.setPlugin(plugin)
+  const load = makeStructureLoader(host as unknown as StructureLoaderHost)
+  return { host, load, structure: host.structures[0]! }
+}
+
+const tick = () => new Promise<void>(resolve => setTimeout(resolve, 0))
+
+beforeEach(() => {
+  mockLoad.mockReset()
+})
+
+test('loads a pending structure and marks it loaded', async () => {
+  mockLoad.mockResolvedValue({ sequences: ['ABC'] })
+  const { load, structure } = setup({})
+  load()
+  expect(mockLoad).toHaveBeenCalledTimes(1)
+  await tick()
+  expect(structure.loadedToMolstar).toBe(true)
+  expect(structure.sequences).toEqual(['ABC'])
+})
+
+test('does not start a second load while one is in flight', () => {
+  mockLoad.mockReturnValue(new Promise(() => {}))
+  const { load } = setup({})
+  load()
+  load()
+  expect(mockLoad).toHaveBeenCalledTimes(1)
+})
+
+test('discards a stale-plugin result and reloads into the current plugin', async () => {
+  const pluginA = { id: 'A' }
+  const pluginB = { id: 'B' }
+  let resolveFirst: (v: { sequences?: string[] }) => void = () => {}
+  mockLoad
+    .mockImplementationOnce(() => new Promise(res => (resolveFirst = res)))
+    .mockResolvedValueOnce({ sequences: ['B'] })
+
+  const { host, load, structure } = setup(pluginA)
+  load() // starts loading into pluginA
+  host.setPlugin(pluginB) // plugin swapped while loading
+  resolveFirst({ sequences: ['A'] }) // pluginA result arrives, now stale
+  await tick()
+
+  expect(structure.sequences).toEqual(['B'])
+  expect(structure.loadedToMolstar).toBe(true)
+  expect(mockLoad).toHaveBeenCalledTimes(2)
+})
+
+test('reports load errors and leaves the structure unloaded', async () => {
+  const err = new Error('boom')
+  mockLoad.mockRejectedValue(err)
+  const { host, load, structure } = setup({})
+  load()
+  await tick()
+  expect(host.errors).toContain(err)
+  expect(structure.loadedToMolstar).toBe(false)
+})

package/src/ProteinView/structureLoader.ts

@@ -0,0 +1,74 @@
+import { isAlive } from '@jbrowse/mobx-state-tree'
+
+import { loadStructureData } from './loadStructureData'
+
+import type StructureModel from './structureModel'
+import type { IAnyStateTreeNode, Instance } from '@jbrowse/mobx-state-tree'
+import type { PluginContext } from 'molstar/lib/mol-plugin/context'
+
+type StructureInstance = Instance<typeof StructureModel>
+
+export type StructureLoaderHost = IAnyStateTreeNode & {
+  readonly molstarPluginContext: PluginContext | undefined
+  readonly structures: StructureInstance[]
+  setError: (error: unknown) => void
+}
+
+/**
+ * Builds the body of the autorun that loads structures into Molstar.
+ *
+ * The returned callback is synchronous on purpose: MobX only tracks
+ * observables read before the first `await`, so an async autorun body would
+ * stop reacting to later structures/plugin changes. Instead it reads its
+ * dependencies synchronously and dispatches a guarded fire-and-forget load for
+ * each structure that is neither loaded nor already loading. The guards handle
+ * the lifecycle hazards of an external GPU resource:
+ *
+ *   - a non-observable in-flight Set stops a re-entrant run (a new structure
+ *     pushed, or the plugin swapped mid-load) from starting a duplicate load of
+ *     the same structure;
+ *   - a load whose plugin was replaced or whose model was destroyed while
+ *     awaiting has its result discarded rather than written into a torn-down
+ *     plugin;
+ *   - if the plugin was merely swapped (e.g. a view remount), the structure is
+ *     reloaded into the current plugin so it isn't left stranded unloaded.
+ */
+export function makeStructureLoader(host: StructureLoaderHost) {
+  const loadingStructures = new Set<StructureInstance>()
+
+  function loadInto(structure: StructureInstance, plugin: PluginContext) {
+    loadingStructures.add(structure)
+    loadStructureData({ structure, plugin })
+      .then(data => {
+        const current = isAlive(structure)
+          ? host.molstarPluginContext
+          : undefined
+        if (current === plugin) {
+          structure.setStructureData(data)
+          structure.setLoadedToMolstar(true)
+        }
+        loadingStructures.delete(structure)
+        if (current && current !== plugin && !structure.loadedToMolstar) {
+          loadInto(structure, current)
+        }
+      })
+      .catch((e: unknown) => {
+        loadingStructures.delete(structure)
+        if (isAlive(host)) {
+          host.setError(e)
+          console.error(e)
+        }
+      })
+  }
+
+  return function loadPendingStructures() {
+    const { structures, molstarPluginContext } = host
+    if (molstarPluginContext) {
+      for (const structure of structures) {
+        if (!structure.loadedToMolstar && !loadingStructures.has(structure)) {
+          loadInto(structure, molstarPluginContext)
+        }
+      }
+    }
+  }
+}

package/src/fetchUtils.test.ts

@@ -0,0 +1,27 @@
+import { expect, test } from 'vitest'
+
+import { timeout } from './fetchUtils'
+
+test('timeout resolves after the delay', async () => {
+  await expect(timeout(1)).resolves.toBeUndefined()
+})
+
+test('timeout rejects immediately if the signal is already aborted', async () => {
+  const controller = new AbortController()
+  controller.abort()
+  await expect(timeout(10_000, controller.signal)).rejects.toThrow()
+})
+
+test('timeout rejects when the signal aborts mid-wait', async () => {
+  const controller = new AbortController()
+  const p = timeout(10_000, controller.signal)
+  controller.abort()
+  await expect(p).rejects.toThrow()
+})
+
+test('timeout preserves a custom Error abort reason', async () => {
+  const controller = new AbortController()
+  const reason = new Error('dialog closed')
+  controller.abort(reason)
+  await expect(timeout(10_000, controller.signal)).rejects.toBe(reason)
+})

package/src/fetchUtils.ts

@@ -18,6 +18,26 @@ export async function jsonfetch<T = unknown>(
   return response.json()
 }
 
-export function timeout(time: number) {
-  return new Promise(res => setTimeout(res, time))
+function abortError(signal: AbortSignal) {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error('Aborted', { cause: signal.reason })
+}
+
+export function timeout(time: number, signal?: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError(signal))
+    } else {
+      const id = setTimeout(resolve, time)
+      signal?.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(id)
+          reject(abortError(signal))
+        },
+        { once: true },
+      )
+    }
+  })
 }

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.4.11'
+export const version = '0.4.13'