@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'
function applyConfSettings(
target: AnyConfigurationModel | { configuration: AnyConfigurationModel },
settings: Record<string, unknown>,
): ConfSettingsReportarraySlotUnion
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'
function arraySlotUnion(
slotType: IAnyType,
): ConfigurationSchemaUnionMetadata | undefinedcanonicalSpelling
A settings bag as its schema spells it, at every depth of the sub-schemas
it declares: a bare value as the object its shorthand lifts it into, and
a retired spelling as the members that replaced it. Two bags combine
member by member only in this form; merged raw, a bare mark: "line"
replaces a whole mark object where it meant its type. The bag itself,
by identity, when it already spells everything so.
import { canonicalSpelling } from '@jbrowse/core/configuration'
function canonicalSpelling(
schema: ConfigurationSchemaMetadata,
snapshot: Record<string, unknown>,
): Record<string, unknown>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'
function ConfigurationSchemaUnion<
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'
function declaredSnapshot(
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'
function evaluateForFeature(
value: unknown,
feature: Feature,
jexl: JexlInstance,
): unknowngetConf
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'
function getConf(model: {
configuration: AnyConfigurationModel
}): AnyConfigurationSnapshothydrateTrackConfig
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'
function hydrateTrackConfig(
pluginManager: PluginManager,
config: Record<string, unknown>,
): TrackConfigNode | undefinedkeyedValueInForce
A sub-schema's snapshot as drawn: a keyed object's field in force where
the snapshot leaves out a declared default that names values, as the
multi-row display's rows.field is type (keyedInForce). Any other
value is returned as given.
import { keyedValueInForce } from '@jbrowse/core/configuration'
function keyedValueInForce(
node: AnyConfigurationModel | undefined,
value: unknown,
): unknownkeyedWritesAt
The keyed writes schema declares on the object at path (ADR-257), as
rows declares its arrangement keyed by field; undefined elsewhere.
import { keyedWritesAt } from '@jbrowse/core/configuration'
function keyedWritesAt(
schema: unknown,
path: readonly string[],
): KeyedWrites | undefinedliftPlot
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'
function liftPlot(
conf: AnyConfigurationModel,
draft: Plot,
options?: PlotWriteOptions,
): AnyConfigurationModelmergeConfSettings
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'
function mergeConfSettings(
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'
function parsePlot(text: string, keys: readonly string[]): PlotPlot
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.
import type { Plot } from '@jbrowse/core/configuration'
type Plot = Record<string, unknown>PlotExample
A worked example of a display's plot: the text it fills the editor with, and what it does.
import type { PlotExample } from '@jbrowse/core/configuration'
interface PlotExample {
plot: string
description: string
}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'
function plotKeysOf(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'
function plotList<T extends IAnyType>(type: T): TplotOf
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, and a keyed object its field's declared default, since they are what is drawn.
import { plotOf } from '@jbrowse/core/configuration'
function plotOf(conf: AnyConfigurationModel): PlotPlotWriteOptions
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.
import type { PlotWriteOptions } from '@jbrowse/core/configuration'
interface PlotWriteOptions {
whole?: boolean
}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 keyed
object back at its declared default included. 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'
function plotWrites(
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'
function preProcessConfigSnapshot(
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. A sub-schema reads as its
snapshot, so the types refuse a path ending on one, and a read names the
member, as ['labels', 'name', 'show'] does.
import { readConfObject } from '@jbrowse/core/configuration'
function readConfObject(
confObject: AnyConfigurationModel,
): AnyConfigurationSnapshotrefuseOnWrite
What a schema's own preProcessSnapshot does with a value it refuses that
no declared rule can name: a write throws notice, and a config loading
names it once on the console and loads without it.
import { refuseOnWrite } from '@jbrowse/core/configuration'
function refuseOnWrite(notice: string): voidrefusingUndeclaredKeys
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'
function refusingUndeclaredKeys<T>(write: () => T): TrequirementProblems
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'
function requirementProblems(
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'
function setConf<
CONFMODEL extends AnyConfigurationModel,
const SLOT extends
| ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>
| ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> =
ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>,
>(
target: CONFMODEL | { configuration: CONFMODEL },
slotPath: SLOT,
value: unknown,
): voidwritesWholeAt
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'
function writesWholeAt(schema: unknown, path: readonly string[]): booleanRelated links
- Developer guide: Configuration schema