Skip to main content

core/util

Auto-generated from exported functions tagged #api in the source. See imports and re-exports for how to import these from a plugin.

Band

One band of a display's vertical stack — a coverage histogram, an arc strip, a conservation row, a variant lane. The contract is the pair: active is whether the band exists right now (the display pre-ANDs its settings half, showX, with its data half, "some lane has ink"), and height is the stated height when it does. Consumers read pixels through reservedPx or stackBands, never by re-combining the pair — the re-combination is where the reserver and the painter historically drifted.

baseDisplayConfig

The base's entry for this display, hydrated, which a reset returns to and "is this the reader's" compares against: the config.json's, or the one a track the session owns was added with; empty in a session that keeps no base.

import { baseDisplayConfig } from '@jbrowse/core/util/baseDisplayConfig'

// type signature
(self: object) => Record<string, unknown>

boundBandHeight

Bound a band height to its legal range — a config value, a menu choice, or a slider position, i.e. anywhere the number is being stated rather than dragged.

The floor keeps the band operable at its smallest: for a drag-resized band that means keeping the handle grabbable, for a menu-sized one it is the height below which its content stops reading. The ceiling stops a band from swallowing the plot it sits over — every display floors its plot area at 0, so an unbounded band takes the rows to zero height rather than to a scrollbar, and takes the band's own handle off-screen with them.

The bounds differ per band and the rule does not, which is why this takes them rather than each band re-deriving the reasoning — that is how the two clampBandHeights in this repo drifted apart, each ending up with one half of this rule and a doc comment claiming to be the whole of it.

import { boundBandHeight } from '@jbrowse/core/util/bandHeight'

// type signature
(n: number, { min, max }?: BandBounds) => number

canonicalizeViewRefName

Resolve user-authored refName text against the assembly of the view containing node, resolving aliases and casing together. Falls back to the input when the assembly is absent or its aliases have not loaded.

Uses the view's assembly, not the track's, because displayed regions, loaded regions and blocks all carry the refNames the view laid out.

Call it wherever a refName a person wrote is about to be compared against regions, features or blocks, which carry the assembly's canonical name. A refName a display copied off a region is already canonical. One from a session spec, a config slot or a URL is whatever the author typed.

Without it, matching depends on the assembly: chr12 matches on an assembly canonicalized chr12 and matches nothing on one canonicalized 12. The same spec key works on one config and does nothing on the next, with no error.

Resolves through getCanonicalRefName2, which falls back to the input instead of throwing when a spec is read before the alias file has loaded. The getters that read user specs run from the first render.

Takes a refName, not a spec that might hold one. The resolver calls refName.toLowerCase(), so any other value throws once the aliases have loaded, and a caller reading an untyped frozen slot must first check that the value is a refName.

import { canonicalizeViewRefName } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode, refName: string) => string

clampBandHeight

Clamp one resize of a drag-resizable band: boundBandHeight, plus the one rule a resize needs that a stated height does not.

The floor becomes min(bounds.min, current), never the bare bound: a band whose config declares it smaller than the floor must stay where it is. Taking the bare floor instead made the first drag on such a band jump it up to the floor before honoring the delta. A band at or above the floor is unaffected, one below it can still be dragged but never smaller than it already is, and one dragged back past the floor regains it.

The ceiling is not relaxed the same way — a band already over its ceiling is the state the user is trying to escape, so a resize brings it back inside.

ResizeHandle emits one delta per animation frame, so callers driving a drag pass current + distance as the target and read current inside the action — a component computing the target from a rendered height drops every tick that lands before React re-renders.

import { clampBandHeight } from '@jbrowse/core/util/bandHeight'

// type signature
(current: number, target: number, bounds?: BandBounds) => number

getAssemblyHost

The host's assembly manager, for a module that resolves names and nothing else.

Unlike the accessors in sessionServices.ts this one buys the caller no smaller type graph — an AssemblyManager is an MST model a PluginManager built, so naming it costs what naming a session costs. It is here to say which service is wanted, and because that cost is the finding: the assembly manager is the one thing on AbstractSessionModel a third-party host cannot simply implement.

import { getAssemblyHost } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => AssemblyHost

getContainingDisplay

Returns the display model that contains the given node. Throws if the node has no containing display.

import { getContainingDisplay } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => AbstractDisplayModel

getContainingTrack

Returns the track model that contains the given node. Throws if the node has no containing track.

import { getContainingTrack } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => AbstractTrackModel

getContainingView

Returns the view model that contains the given node. Throws if the node has no containing view.

import { getContainingView } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => AbstractViewModel

getDialogHost

Where a display puts a dialog it cannot mount itself.

import { getDialogHost } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => DialogHost

getEnv

Returns the MST environment for a node, which carries the pluginManager.

import { getEnv } from '@jbrowse/core/util'

// type signature
(obj: IAnyStateTreeNode) => { pluginManager: PluginManager; }

getNotificationSink

Where a display puts a message it cannot draw itself.

import { getNotificationSink } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => NotificationSink

getPaletteHost

The colors to draw with, and the args that rebuild them in a worker.

import { getPaletteHost } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => PaletteHost

getRenderingServices

Everything a display needs of its host in order to draw a region: the assemblies, the RPC entry point and the colors.

import { getRenderingServices } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => RenderingServices

getRpcHost

The host's RPC entry point, for a module that issues RPCs and nothing else.

import { getRpcHost } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => RpcHost

getSession

Returns the JBrowse session model for any node in the state tree. Throws if the node has no session ancestor.

import { getSession } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => AbstractSessionModel

getSessionServices

The services a session offers that cost nothing application-shaped to name. Prefer one of the narrower accessors below, which say which of them the calling module actually uses.

import { getSessionServices } from '@jbrowse/core/util'

// type signature
(node: IAnyStateTreeNode) => SessionServices

launchOrReplaceView

addOrReplaceView for view types whose state model may be lazily loaded; the synchronous addOrReplaceView requires it loaded already.

import { launchOrReplaceView } from '@jbrowse/core/util'

// type signature
(args: { session: AbstractViewContainer; typeName: string; initialState?: Record<string, unknown> | undefined; replacing?: AbstractViewModel | undefined; }) => Promise<AbstractViewModel>

reservedPx

The pixels a band takes from the plot below it: 0 when off, the (optionally bound) stated height when on. This is the single spelling of "off spends 0 px".

import { reservedPx } from '@jbrowse/core/util/bandLayout'

// type signature
(band: Band) => number

runLazyAfterAttach

Run a display's afterAttach body from a module loaded on demand, so the autorun installers stay out of the display's eager bundle.

One policy for the gap the await opens: a node torn down before the module lands installs nothing, and a module that fails to load is reported where the user can see it rather than onto the display's own error slot — that slot is what reload() clears, and nothing would re-run the install behind it. Three displays hand-rolled this IIFE and each drew the lines differently.

import { runLazyAfterAttach } from '@jbrowse/core/util/lazyAfterAttach'

// type signature
<Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>) => void

scaleBandHeights

Heights after growing or shrinking a stack of bands by distance px in all: the one rule every whole-stack resize uses. Each band takes its share of the height it has above floor, so the tall bands give and take the most, and none goes below floor, or below its own height if it already sits under it (the clampBandHeight rule). Whole pixels, rounded by largest remainder, so the stack moves by exactly the rounded distance.

import { scaleBandHeights } from '@jbrowse/core/util/bandHeight'

// type signature
(heights: number[], distance: number, floor?: number) => number[]

stackBands

Fold an ordered set of bands into tops and a bottom. The order is the argument, so a display states its band order exactly once. Reserve, paint and pick all call this function, so the reserved and painted positions cannot disagree.

Only the fold is shared; the rest stays in each display. Per-lane iteration runs this once per lane, sticky-vs-scrolling is a property of how the result is projected to the screen, and a band drawn outside its reservation (an overlay) carries its own draw rect beside the stack.

import { stackBands } from '@jbrowse/core/util/bandLayout'

// type signature
<K extends string>(order: readonly K[], bands: Record<K, Band>) => BandStack<K>