Skip to main content

@jbrowse/core (configuration)

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

applyConfSettings

Write a settings bag — a session spec's track entry, a share link, an agent call — onto a config. Each key names a member: a slot or a channel is written whole, as setConf writes it, so null resets it (ADR-146); a namespace's object names members inside it, at any depth, and the ones it leaves out keep their values. The config's own lift and checks run over the bag first, and each namespace's over its part, so a shorthand or a legacy key reads the same here as in config.json. A key the config does not declare is reported for the caller to route or refuse, and a declared key whose write throws costs that key alone.

import { applyConfSettings } from '@jbrowse/core/configuration'

// type signature
(target: AnyConfigurationModel | { configuration: AnyConfigurationModel; }, settings: Record<string, unknown>) => ConfSettingsReport

arraySlotUnion

The ConfigurationSchemaUnion an array slot's entries answer to, read off the slot's MST type, or undefined for any other slot.

import { arraySlotUnion } from '@jbrowse/core/configuration'

// type signature
(slotType: IAnyType) => ConfigurationSchemaUnionMetadata | undefined

ConfigurationSchemaUnion

A list entry that is one of several configuration schemas, each keyed by the type it answers to: types.array(ConfigurationSchemaUnion('Step', { filter, bin })). The keys are the vocabulary, the snapshot's type picks the member, and a type naming no member is refused in every build — where a bare types.union would load it as its first member. Each member is an explicitlyTyped, closed schema named by its key, so a key belonging to another member is named on a load and refused on a write rather than dropped; one that is not throws here.

import { ConfigurationSchemaUnion } from '@jbrowse/core/configuration'

// type signature
<const MEMBERS extends Record<string, AnyConfigurationSchemaType>>(name: string, members: MEMBERS) => ConfigurationSchemaUnionType<MEMBERS>

declaredSnapshot

A snapshot as type lifts it, without the keys it does not declare: the config half of an entry that also holds its owner's keys, as a MultiWiggleAdapter subadapter holds its row's name and color.

import { declaredSnapshot } from '@jbrowse/core/configuration'

// type signature
(type: IAnyType, snapshot: Record<string, unknown>) => Record<string, unknown>

evaluateForFeature

A config value as feature reads it: a jexl: callback evaluated against the feature, anything else as written.

import { evaluateForFeature } from '@jbrowse/core/configuration'

// type signature
(value: unknown, feature: Feature, jexl: JexlInstance) => unknown

getConf

Reads a configuration value from a track or display state model: exactly readConfObject(model.configuration, path), with the same slot-name check.

import { getConf } from '@jbrowse/core/configuration'

// type signature
(model: { configuration: AnyConfigurationModel; }) => AnyConfigurationSnapshot

hydrateTrackConfig

Hydrate a plain track config, such as a session.tracks entry, into a live config node, dispatching on its type to find the schema. A plain entry holds only what was authored: a slot at its default is absent and preProcessSnapshot has not run.

Returns undefined when no plugin registered the type or create rejects the config, which has never been validated; callers fall back to the plain object. Hydrating one entry twice returns one node. A shown track resolves to the session's working copy instead (ADR-032), which has the same content.

import { hydrateTrackConfig } from '@jbrowse/core/configuration'

// type signature
(pluginManager: PluginManager, config: Record<string, unknown>) => AnyConfigurationModel | undefined

liftPlot

A draft as the display's config would hold it, through the schema's own lift and checks: a shorthand becomes its object, a default falls off, and what a config file is refused for throws, a key outside the plot included. The draft writes over the plot as a settings bag does: a setting it leaves out stays, null resets one, an object declaring writes: 'whole' replaces the setting, and any other object takes the members it names, a null member resetting that member. Under whole the draft is the plot entire. The node is never attached, so nothing on the display is touched; a display reads its typed members off it. The draft is copied first, since MST freezes what it creates from.

import { liftPlot } from '@jbrowse/core/configuration'

// type signature
(conf: AnyConfigurationModel, draft: Plot, options?: PlotWriteOptions) => AnyConfigurationModel

mergeConfSettings

Two settings bags for one schema as one, over written after under the way applyConfSettings writes a bag: a namespace's object merges member by member at any depth, a bare value its shorthand lifts included, and a slot or a channel takes over's value whole. Each side's retired spellings lift first, at every depth, so a bag's own retired name still beats the other's current one; over's namespace members lift against under as their base, so they replace only the entries they name in a list under writes. For combining snapshots before any config node exists, as a track's displayDefaults folds into its displays.

import { mergeConfSettings } from '@jbrowse/core/configuration'

// type signature
(schema: unknown, under: Record<string, unknown>, over: Record<string, unknown>) => { [x: string]: unknown; }

parsePlot

Parses the text as a plot and throws on a key the display's plot lacks. The schema parses the values after that.

import { parsePlot } from '@jbrowse/core/configuration'

// type signature
(text: string, keys: readonly string[]) => Plot

Plot

A display's plot settings as written: a key left out is left alone, and null resets that setting. Untyped, since a value may be a shorthand the schema lifts, and the schema is what judges it.

PlotExample

A worked example of a display's plot: the text it fills the editor with, and what it does.

plotKeysOf

A display's plot settings, what "Edit plot..." edits and an agent reads as its plot: every slot, sub-schema and list its config declares with plot, in the order it declares them.

import { plotKeysOf } from '@jbrowse/core/configuration'

// type signature
(conf: AnyConfigurationModel) => string[]

plotList

Marks a list of sub-schemas as a plot setting, as plot: true marks a slot or a sub-schema; an MST array type has no options in which to set the flag.

import { plotList } from '@jbrowse/core/configuration'

// type signature
<T extends IAnyType>(type: T) => T

plotOf

A display's plot as declared, defaults left off. A list sitting at a default it shares with no other display, a default plot's marks, shows its entries, since they are what is drawn.

import { plotOf } from '@jbrowse/core/configuration'

// type signature
(conf: AnyConfigurationModel) => Plot

PlotWriteOptions

How a draft is written to the plot. By default it patches, as a settings bag does; whole takes it for the whole plot, as the "Edit plot..." text is.

plotWrites

What applying a draft writes: each setting whose lifted value differs from the plot, as the lifted value, and null for one it resets. A value spelled another way but lifting to the same setting writes nothing, and a retired spelling writes the settings it lifts into. Under whole, a setting the draft leaves out writes its reset. Throws a refusal before anything is written.

import { plotWrites } from '@jbrowse/core/configuration'

// type signature
(conf: AnyConfigurationModel, draft: Plot, options?: PlotWriteOptions) => Record<string, unknown>

preProcessConfigSnapshot

A snapshot as a write to type admits it: the lift and checks setConf applies, so a dialog or a validator rejects what an edit would reject, an undeclared key included. Throws what the schema's preProcessSnapshot throws.

import { preProcessConfigSnapshot } from '@jbrowse/core/configuration'

// type signature
(type: IAnyType, snapshot: unknown) => Record<string, unknown>

readConfObject

Read the value at a path of a live config node, such as a track's configuration, evaluating a jexl: callback with args.

The types reject a snapshot, because a snapshot omits a slot at its default. A session.tracks entry is one (TrackConfigEntry): read its trackId and type directly, and a slot through a helper that supplies the default, such as getConfAssemblyNamesOrNone.

import { readConfObject } from '@jbrowse/core/configuration'

// type signature
(confObject: AnyConfigurationModel) => AnyConfigurationSnapshot

refusingUndeclaredKeys

Runs write as a write: a closed schema created inside it refuses a key it does not declare, at any depth, where a config loading only names the key on the console. setConf, a settings bag and a plot draft write this way, so a typo in an edit is an error and a config written for another version still draws.

import { refusingUndeclaredKeys } from '@jbrowse/core/configuration'

// type signature
<T>(write: () => T) => T

requirementProblems

The requires entries of a configuration schema that snapshot does not meet, as a config file or getSnapshot spells it: a slot left off reads as its default, so a when value that is the default fires for an absent slot, which is what the generated JSON Schema's if does.

import { requirementProblems } from '@jbrowse/core/configuration'

// type signature
(type: IAnyType, snapshot: Record<string, unknown>) => RequirementProblem[]

setConf

Write counterpart to getConf, and it takes the same path: a slot name, or an array naming a sub-schema's member at any depth — setConf(self, ['encoding', 'y', 'scale', 'domainMin'], 5). Takes the display or track model, or a config node directly.

A path ending on a slot writes that slot; one ending on a sub-schema replaces the whole object, so a channel's members (a facet's field and its domain) move together. On a concrete schema an unknown slot name is a compile error, and setSlot refuses one at runtime (ADR-052). A wrong value type throws at runtime; null or undefined resets the slot to its default (ADR-146).

import { setConf } from '@jbrowse/core/configuration'

// type signature
<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(target: CONFMODEL | { configuration: CONFMODEL; }, slotPath: SLOT, value: unknown) => void

writesWholeAt

Whether schema writes the object at path whole: a channel, which declares writes: 'whole', where a namespace merges member by member. False for a path the schema does not declare.

import { writesWholeAt } from '@jbrowse/core/configuration'

// type signature
(schema: unknown, path: readonly string[]) => boolean

Developer guide: Configuration schema