@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/iupac.js

@@ -0,0 +1,59 @@
+// IUPAC nucleotide ambiguity codes → character classes, for turning a motif like
+// "NGG" or "GGTNACC" into a regex
+const IUPAC_CODES = {
+    A: 'A',
+    C: 'C',
+    G: 'G',
+    T: 'T',
+    R: '[AG]',
+    Y: '[CT]',
+    S: '[GC]',
+    W: '[AT]',
+    K: '[GT]',
+    M: '[AC]',
+    B: '[CGT]',
+    D: '[AGT]',
+    H: '[ACT]',
+    V: '[ACG]',
+    N: '[ACGT]',
+};
+const IUPAC_COMPLEMENT = {
+    A: 'T',
+    T: 'A',
+    C: 'G',
+    G: 'C',
+    R: 'Y',
+    Y: 'R',
+    S: 'S',
+    W: 'W',
+    K: 'M',
+    M: 'K',
+    B: 'V',
+    V: 'B',
+    D: 'H',
+    H: 'D',
+    N: 'N',
+};
+export const IUPAC_MOTIF_REGEX = /^[ACGTRYSWKMBDHVN]+$/;
+export function iupacToRegex(motif) {
+    let out = '';
+    for (const c of motif.toUpperCase()) {
+        out += IUPAC_CODES[c] ?? c;
+    }
+    return out;
+}
+// reverse-complement a motif in IUPAC space, so a minus-strand match can be
+// found directly on the plus-strand sequence
+export function reverseComplementIupac(motif) {
+    let out = '';
+    for (const c of motif.toUpperCase()) {
+        out = (IUPAC_COMPLEMENT[c] ?? c) + out;
+    }
+    return out;
+}
+// A motif that reads the same on both strands (most restriction sites) matches
+// the plus strand and minus strand at identical coordinates, so scanning both
+// would emit every hit twice.
+export function isPalindromic(motif) {
+    return reverseComplementIupac(motif) === motif.toUpperCase();
+}

package/esm/util/jexl.js

@@ -1,50 +1,174 @@
 import { Jexl } from '@jbrowse/jexl';
-export default function JexlF() {
+import { randomColor } from './color/index.js';
+import { colord } from './colord.js';
+import { jexlFeatureProxy, unwrapFeature } from './simpleFeature.js';
+export default function JexlF( /* config?: any*/) {
     const j = new Jexl();
+    // Memoize compilation on the instance itself. A compiled Expression closes
+    // over this instance's grammar (its registered functions), so the cache
+    // belongs here and is naturally per-instance — there is no shared cache that
+    // could bind an expression to the wrong instance's functions.
+    const rawCompile = j.compile.bind(j);
+    const cache = new Map();
+    j.compile = (code) => {
+        let expr = cache.get(code);
+        if (expr === undefined) {
+            expr = rawCompile(code);
+            cache.set(code, expr);
+        }
+        return expr;
+    };
+    // someday will make sure all of configs callbacks are added in, including
+    // ones passed in
+    // below are core functions
     j.addFunction('get', (feature, data) => feature.get(data));
-    j.addFunction('parent', (feature) => feature.parent?.());
-    j.addFunction('id', (feature) => feature.id());
-    j.addFunction('cast', (arg) => arg);
-    j.addFunction('log', (thing) => {
-        console.log(thing);
-        return thing;
+    // on a jexlFeatureProxy `feature.parent`/`feature.id` are data values (jexl
+    // has no member-call syntax, and `id` is a real data field e.g. GFF3 `ID=`),
+    // so unwrap to the underlying feature to reach its methods. The parent comes
+    // back wrapped so `parent(feature).type` reads like `feature.parent.type`
+    j.addFunction('parent', (feature) => {
+        const p = unwrapFeature(feature).parent?.();
+        return p ? jexlFeatureProxy(p) : undefined;
     });
+    j.addFunction('id', (feature) => unwrapFeature(feature).id());
+    // let user cast a jexl type into a javascript type
+    j.addFunction('cast', (arg) => arg);
+    // math
+    // addfunction added in jexl 2.3 but types/jexl still on 2.2
+    /** #jexlFunction Math functions | max(0, 2) */
     j.addFunction('max', Math.max);
+    /** #jexlFunction Math functions | min(0, 2) */
     j.addFunction('min', Math.min);
+    /** #jexlFunction Math functions | sqrt(4) */
     j.addFunction('sqrt', Math.sqrt);
+    /** #jexlFunction Math functions | ceil(0.5) */
     j.addFunction('ceil', Math.ceil);
+    /** #jexlFunction Math functions | floor(0.5) */
     j.addFunction('floor', Math.floor);
+    /** #jexlFunction Math functions | round(0.5) */
     j.addFunction('round', Math.round);
+    /** #jexlFunction Math functions | abs(-0.5) */
     j.addFunction('abs', Math.abs);
+    /** #jexlFunction Math functions | log10(50000) */
     j.addFunction('log10', Math.log10);
+    /** #jexlFunction Math functions | parseInt('2') */
     j.addFunction('parseInt', Number.parseInt);
+    /** #jexlFunction Math functions | parseFloat('2.054') */
     j.addFunction('parseFloat', Number.parseFloat);
-    j.addFunction('split', (s, char) => s.split(char));
-    j.addFunction('join', (k, ...args) => [...args].filter(f => !!f).join(k));
+    // string
+    /** #jexlFunction String functions | charAt('abc', 2) | c */
     j.addFunction('charAt', (s, index) => s.charAt(index));
+    /** #jexlFunction String functions | charCodeAt(' ', 0) | 32 */
     j.addFunction('charCodeAt', (s, index) => s.charCodeAt(index));
+    /** #jexlFunction String functions | codePointAt(' ', 0) | 32 */
     j.addFunction('codePointAt', (s, pos) => s.codePointAt(pos));
-    j.addFunction('includes', (s, search) => s.includes(search));
+    /** #jexlFunction String functions | startsWith('kittycat', 'kit') | true */
     j.addFunction('startsWith', (s, search, len) => s.startsWith(search, len));
+    /** #jexlFunction String functions | endsWith('kittycat', 'cat') | true */
     j.addFunction('endsWith', (s, search, len) => s.endsWith(search, len));
-    j.addFunction('padEnd', (s, len, pad) => s.padEnd(len, pad));
+    /** #jexlFunction String functions | padStart('cat', 8, 'kitty') | kittycat */
     j.addFunction('padStart', (s, len, fill) => s.padStart(len, fill));
-    j.addFunction('repeat', (s, count) => s.repeat(count));
+    /** #jexlFunction String functions | padEnd('kitty', 8, 'cat') | kittycat */
+    j.addFunction('padEnd', (s, len, pad) => s.padEnd(len, pad));
+    /** #jexlFunction String functions | replace('kittycat', 'cat', '') | kitty */
     j.addFunction('replace', (s, match, sub) => s.replace(match, sub));
+    /** #jexlFunction String functions | replaceAll('kittycatcat', 'cat', '') | kitty */
     j.addFunction('replaceAll', (s, match, sub) => s.replaceAll(match, sub));
+    /** #jexlFunction String functions | slice('kittycat', 5) | cat */
     j.addFunction('slice', (s, start, end) => s.slice(start, end));
-    j.addFunction('startsWith', (s, search, pos) => s.startsWith(search, pos));
+    /** #jexlFunction String functions | substring('kittycat', 0, 5) | kitty */
     j.addFunction('substring', (s, start, end) => s.substring(start, end));
-    j.addFunction('toLowerCase', (s) => s.toLowerCase());
-    j.addFunction('toUpperCase', (s) => s.toUpperCase());
-    j.addFunction('jsonParse', (s) => JSON.parse(s));
+    /** #jexlFunction String functions | trim('  kitty ') | kitty, whitespace trimmed */
     j.addFunction('trim', (s) => s.trim());
-    j.addFunction('trimEnd', (s) => s.trimEnd());
+    /** #jexlFunction String functions | trimStart('  kitty ') | kitty, starting whitespace trimmed */
     j.addFunction('trimStart', (s) => s.trimStart());
+    /** #jexlFunction String functions | trimEnd('  kitty ') | kitty, ending whitespace trimmed */
+    j.addFunction('trimEnd', (s) => s.trimEnd());
+    /** #jexlFunction String functions | toUpperCase('kitty') | KITTY */
+    j.addFunction('toUpperCase', (s) => s.toUpperCase());
+    /** #jexlFunction String functions | toLowerCase('KITTY') | kitty */
+    j.addFunction('toLowerCase', (s) => s.toLowerCase());
+    /**
+     * #jexlFunction String functions | split('KITTY KITTY', ' ') | ['KITTY', 'KITTY']
+     * #jexlFunction String functions | split(feature.notThere, ' ') | [''], an absent value is read as the empty string rather than throwing
+     */
+    // TOTAL, unlike its siblings above, and deliberately: `split` is the one
+    // string function that is routinely composed with itself, and the inner call
+    // supplies the outer one's argument. The catalog's own recipe for UCSC's
+    // `bigRmskBed` is `split(split(feature.name,'#')[1],'/')[0]`, where a feature
+    // whose name carries no `#` makes the inner call return `['name']` and index
+    // [1] `undefined` — so a bare `s.split(char)` threw a TypeError from INSIDE a
+    // config callback. That is not a recoverable error at the call site: it took
+    // out a whole LinearMultiRowFeatureDisplay (banner: "Cannot read properties
+    // of undefined (reading 'split')") even though the resolver evaluating it
+    // wraps each feature in a try/catch meant to cost one row and not the track.
+    //
+    // `String(s ?? '')` rather than a guard returning `[]`, so absent behaves
+    // exactly like the empty string already does: `split('', '#')` is `['']`
+    // today, and now so is `split(undefined, '#')`. Composed, that turns the
+    // recipe above into an empty partition value for a nameless feature, which
+    // is what its consumer already treats as "no row assignment". Non-strings
+    // coerce too, so splitting a numeric attribute works instead of throwing.
+    // `s: unknown`, not `string`, because the annotation is the only place that
+    // said otherwise: jexl is untyped at the call site, so every one of these
+    // takes whatever the expression evaluated to. Declaring it honestly is what
+    // makes the coercion below type-check rather than read as dead defensiveness.
+    j.addFunction('split', (s, char) => String(s ?? '').split(char));
+    /** #jexlFunction String functions | join('-', 'a', 'b', '', 'c') | a-b-c, joins truthy args with the separator */
+    j.addFunction('join', (k, ...args) => [...args].filter(f => !!f).join(k));
+    /** #jexlFunction String functions | includes('kittycat', 'cat') | true */
+    j.addFunction('includes', (s, search) => s.includes(search));
+    /** #jexlFunction String functions | repeat('ab', 3) | ababab */
+    j.addFunction('repeat', (s, count) => s.repeat(count));
+    /** #jexlFunction String functions | jsonParse('{"a":1}') | parses a JSON string */
+    j.addFunction('jsonParse', (s) => JSON.parse(s));
+    /**
+     * #jexlFunction Feature operations - getTag | getTag(feature, 'MD') | fetches MD string from BAM or CRAM feature
+     * #jexlFunction Feature operations - getTag | getTag(feature, 'HP') | fetches haplotype tag from BAM or CRAM feature
+     */
     j.addFunction('getTag', (feature, s) => {
+        // BAM features expose a targeted `getTag` that walks the tag block and
+        // decodes only the requested tag; `get('tags')` decodes every tag on the
+        // read (a Record allocation plus NM/AS/ms/de/… — often ~10 per read) to
+        // answer one, and this runs per feature on colour/label callbacks like
+        // `jexl:getTag(feature,'HP')`. Same duck-typing as
+        // `@jbrowse/modifications-utils`' getTag(), which core cannot import (that
+        // package depends on core). Unwrap first: on a jexlFeatureProxy every
+        // unknown property forwards to `feature.get()`, so `feature.getTag` would
+        // read a data field rather than the method. CRAM/synteny features have no
+        // accessor and keep the full-tags path, including its fallback to a
+        // top-level field of that name for features carrying no tags at all.
+        const target = unwrapFeature(feature);
+        if (target.getTag) {
+            return target.getTag(s);
+        }
         const tags = feature.get('tags');
         return tags ? tags[s] : feature.get(s);
     });
+    // color helpers
+    /** #jexlFunction Color functions | randomColor(feature.type) | deterministic color from a string (e.g. a feature type) */
+    j.addFunction('randomColor', randomColor);
+    // These take and return CSS color *strings*, not Colord objects: a config
+    // `jexl:` expression has no way to construct a Colord, and a color slot
+    // holding one resolves to the invalid-color sentinel rather than a color. So
+    // both ends are strings, which also keeps them composable with each other.
+    /** #jexlFunction Color functions | alpha('green', 0.5) | a color at 50% opacity */
+    j.addFunction('alpha', (color, n) => colord(color).alpha(n).toRgbString());
+    /** #jexlFunction Color functions | hsl('#ff0000') | converts a color to its HSL form */
+    j.addFunction('hsl', (color) => colord(color).toHslString());
+    /** #jexlFunction Color functions | colorString('green') | normalizes a color name or value to a hex string */
+    j.addFunction('colorString', (color) => colord(color).toHex());
+    // interpolate applies a scale function to a value. It is intentionally not
+    // tagged for the jexl catalog: a config `jexl:` string has no way to supply
+    // the scale function argument, so it is not usable from config callbacks.
+    j.addFunction('interpolate', (count, scale) => scale(count));
+    // logging
+    /** #jexlFunction Console logging | log(feature) | console.logs output and returns value */
+    j.addFunction('log', (thing) => {
+        console.log(thing); // eslint-disable-line no-console
+        return thing;
+    });
+    /** #jexlFunction Binary operators | feature.flags & 2 | bitwise and to check if BAM or CRAM feature flags has 2 set */
     j.addBinaryOp('&', 15, (a, b) => a & b);
     return j;
 }

package/esm/util/jexlFilters.d.ts

@@ -0,0 +1,75 @@
+import { getConf } from '../configuration/getConf.ts';
+import type { Reversible } from '../ui/filterMenuItems.ts';
+/**
+ * The two-tier feature-filter contract, shared by every display offering a
+ * "Filter by..." row. Two tiers because the setting has two authors:
+ *
+ * - the **`jexlFilters` config slot** on `baseLinearDisplayConfigSchema`, which
+ *   an admin declares in a track config. It stores expressions **unprefixed**,
+ *   because config-slot values are deferred-evaluation and a stored `jexl:` is
+ *   what marks a slot as a callback — so the prefix goes on at read time, in
+ *   `configuredJexlFilters`.
+ * - the **`jexlFiltersSetting` display property**, which the dialog writes and
+ *   which stores them already prefixed (the runtime convention). Set — *even to
+ *   an empty list* — it replaces the config tier entirely, which is what makes
+ *   "clear the filters an admin declared" expressible.
+ *
+ * Every display implemented one half of this and a different half each:
+ * `LinearBasicDisplay` had both tiers, `LDDisplay` had the slot alone, and the
+ * multi-sample variant displays had a property literally named `jexlFilters`
+ * that shadowed the inherited slot, so a config filter on one of those tracks
+ * was read by nothing and reported no error. Neither of the last two prefixed,
+ * so a filter following the slot's own documented convention reached
+ * `stringToJexlExpression` unprefixed and threw inside the worker.
+ */
+export interface JexlFilterSource {
+    /**
+     * The dialog's override, `jexl:`-prefixed. `undefined` means "follow the
+     * config slot"; an empty array means "the user cleared them".
+     */
+    jexlFiltersSetting?: readonly string[];
+    /**
+     * The config tier, `jexl:`-prefixed — in practice
+     * `configuredJexlFilters(self)`. A member rather than a read this module does
+     * itself, so the two things that consume this contract off a **duck-typed**
+     * model — LD's structural menu builder and its shape test — need no live
+     * config node to answer a count with.
+     */
+    configuredFilters: () => string[];
+}
+/**
+ * The writing half, for the dialog and the menu's clear row. Separate from
+ * {@link JexlFilterSource} because a display declares `activeFilters()` in an
+ * earlier `.views()` block than the `.actions()` block declaring its setter, so
+ * requiring the setter to *read* the filters would put the two in an order MST
+ * cannot satisfy.
+ */
+export interface JexlFilterModel extends JexlFilterSource {
+    setJexlFilters: (filters?: string[]) => void;
+}
+/**
+ * What the `jexlFilters` config slot alone declares, `jexl:`-prefixed. The slot
+ * stores them unprefixed and every runtime consumer wants them prefixed, so the
+ * prefixing happens once, here — this is what a display's `configuredFilters`
+ * member is.
+ */
+export declare function configuredJexlFilters(self: Parameters<typeof getConf>[0]): string[];
+/**
+ * The filters actually applied, `jexl:`-prefixed — the single source of truth
+ * for the worker (via `rpcProps`), for the "Filter by..." dialog (so config
+ * filters show up and are editable), and for the narrowing count below.
+ */
+export declare function activeJexlFilters(self: JexlFilterSource): string[];
+/**
+ * The `Reversible` a display declares for its jexl filters.
+ *
+ * The count is whether the override **differs from the configured baseline**,
+ * not the number of expressions: a filter an admin declared is not something
+ * the user narrowed, and "Clear all filters" could not undo it anyway. It
+ * counts in both directions when they differ — narrowing further, and (emptied
+ * over a slot that declares filters) widening past what the config asked for.
+ *
+ * No per-item row: a list of jexl expressions has no recovery to name beyond
+ * restoring the config default, which the group clear already is.
+ */
+export declare function jexlFilterNarrowing(self: JexlFilterModel): Reversible;

package/esm/util/jexlFilters.js

@@ -0,0 +1,49 @@
+// own module, not the configuration barrel: that barrel re-exports modules
+// which import this one, and a value import back into it is the cycle shape
+// `openFeatureWidget` documents
+import { getConf } from '../configuration/getConf.js';
+import { ensureJexlPrefix } from './jexlStrings.js';
+/**
+ * What the `jexlFilters` config slot alone declares, `jexl:`-prefixed. The slot
+ * stores them unprefixed and every runtime consumer wants them prefixed, so the
+ * prefixing happens once, here — this is what a display's `configuredFilters`
+ * member is.
+ */
+export function configuredJexlFilters(self) {
+    return getConf(self, 'jexlFilters').map(ensureJexlPrefix);
+}
+/**
+ * The filters actually applied, `jexl:`-prefixed — the single source of truth
+ * for the worker (via `rpcProps`), for the "Filter by..." dialog (so config
+ * filters show up and are editable), and for the narrowing count below.
+ */
+export function activeJexlFilters(self) {
+    const { jexlFiltersSetting } = self;
+    return jexlFiltersSetting ? [...jexlFiltersSetting] : self.configuredFilters();
+}
+/**
+ * The `Reversible` a display declares for its jexl filters.
+ *
+ * The count is whether the override **differs from the configured baseline**,
+ * not the number of expressions: a filter an admin declared is not something
+ * the user narrowed, and "Clear all filters" could not undo it anyway. It
+ * counts in both directions when they differ — narrowing further, and (emptied
+ * over a slot that declares filters) widening past what the config asked for.
+ *
+ * No per-item row: a list of jexl expressions has no recovery to name beyond
+ * restoring the config default, which the group clear already is.
+ */
+export function jexlFilterNarrowing(self) {
+    const override = self.jexlFiltersSetting;
+    const configured = self.configuredFilters();
+    return {
+        count: override !== undefined &&
+            (override.length !== configured.length ||
+                override.some((f, i) => ensureJexlPrefix(f) !== configured[i]))
+            ? 1
+            : 0,
+        clear: () => {
+            self.setJexlFilters(undefined);
+        },
+    };
+}

package/esm/util/jexlStrings.d.ts

@@ -1 +1,22 @@
-export declare function stringToJexlExpression(str: string, jexl?: any): any;
+export interface JexlExpression {
+    eval(context?: Record<string, unknown>): unknown;
+    _exprStr?: string;
+}
+export interface JexlInstance {
+    compile(code: string): JexlExpression;
+}
+/** The `jexl:` prefix marks a config value as a deferred callback expression. */
+export declare const JEXL_PREFIX = "jexl:";
+export declare function isJexl(str: unknown): str is string;
+/** Add the `jexl:` prefix unless the string already carries it. */
+export declare function ensureJexlPrefix(code: string): string;
+/**
+ * Compile a `jexl:...` string to an Expression. Compilation is memoized on the
+ * jexl instance (see `createJexlInstance`), so this is a thin prefix-stripping
+ * wrapper.
+ *
+ * @param str - string of code like `jexl:...`
+ * @param jexl - the instance whose registered functions the expression may call
+ *   (`pluginManager.jexl` on eval paths)
+ */
+export declare function stringToJexlExpression(str: string, jexl: JexlInstance): JexlExpression;

package/esm/util/jexlStrings.js

@@ -1,17 +1,24 @@
-import createJexlInstance from "./jexl.js";
-const compilationCache = {};
+/** The `jexl:` prefix marks a config value as a deferred callback expression. */
+export const JEXL_PREFIX = 'jexl:';
+export function isJexl(str) {
+    return typeof str === 'string' && str.startsWith(JEXL_PREFIX);
+}
+/** Add the `jexl:` prefix unless the string already carries it. */
+export function ensureJexlPrefix(code) {
+    return isJexl(code) ? code : `${JEXL_PREFIX}${code}`;
+}
+/**
+ * Compile a `jexl:...` string to an Expression. Compilation is memoized on the
+ * jexl instance (see `createJexlInstance`), so this is a thin prefix-stripping
+ * wrapper.
+ *
+ * @param str - string of code like `jexl:...`
+ * @param jexl - the instance whose registered functions the expression may call
+ *   (`pluginManager.jexl` on eval paths)
+ */
 export function stringToJexlExpression(str, jexl) {
-    const cacheKey = `nosig|${str}`;
-    if (!compilationCache[cacheKey]) {
-        const match = str.startsWith('jexl:');
-        if (!match) {
-            throw new Error('string does not appear to be in jexl format');
-        }
-        const code = str.split('jexl:')[1];
-        const compiled = jexl
-            ? jexl.compile(code)
-            : createJexlInstance().compile(code);
-        compilationCache[cacheKey] = compiled;
+    if (!isJexl(str)) {
+        throw new Error('string does not appear to be in jexl format');
     }
-    return compilationCache[cacheKey];
+    return jexl.compile(str.slice(JEXL_PREFIX.length));
 }

package/esm/util/layouts/GranularRectLayout.d.ts

@@ -1,37 +1,25 @@
-import type { BaseLayout, RectTuple, Rectangle, SerializedLayout } from './BaseLayout.ts';
-export default class GranularRectLayout<T> implements BaseLayout<T> {
+export default class GranularRectLayout {
     private pitchX;
     private pitchY;
     private hardRowLimit;
     private bitmap;
     private rectangles;
-    maxHeightReached: boolean;
     private maxHeight;
-    private displayMode;
-    private pTotalHeight;
-    constructor({ pitchX, pitchY, maxHeight, hardRowLimit, displayMode, }?: {
+    /**
+     * pitchX - layout grid pitch in the X direction
+     * pitchY - layout grid pitch in the Y direction
+     * maxHeight - maximum layout height in pixels, default 10000
+     */
+    constructor({ pitchX, pitchY, maxHeight, hardRowLimit, }?: {
         pitchX?: number;
         pitchY?: number;
         maxHeight?: number;
-        displayMode?: string;
         hardRowLimit?: number;
     });
-    addRect(id: string, left: number, right: number, height: number, data?: T, serializableData?: T, startingRow?: number): number | null;
-    collides(rect: Rectangle<T>, top: number): boolean;
-    addRectToBitmap(rect: Rectangle<T>): void;
-    discardRange(left: number, right: number): void;
-    hasSeen(id: string): boolean;
-    getByCoord(x: number, y: number): string | Record<string, T> | undefined;
-    getByID(id: string): RectTuple | undefined;
-    getDataByID(id: string): T | undefined;
-    getSerializableDataByID(id: string): T | undefined;
-    cleanup(): void;
-    getTotalHeight(): number;
-    get totalHeight(): number;
-    getRectangles(): Map<string, RectTuple>;
-    serializeRegion(region: {
-        start: number;
-        end: number;
-    }): SerializedLayout;
-    toJSON(): SerializedLayout;
+    /**
+     * @returns top position for the rect, or Null if laying
+     *  out the rect would exceed maxHeight
+     */
+    addRect(id: string, left: number, right: number, height: number): number | null;
+    private getOrCreateRow;
 }