@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/io/index.js

@@ -1,9 +1,8 @@
-import isNode from 'detect-node';
 import { BlobFile, LocalFile } from 'generic-filehandle2';
-import { RemoteFileWithRangeCache } from "./RemoteFileWithRangeCache.js";
-import { isElectron } from "../index.js";
-import { getBlob, getFileFromCache } from "../tracks.js";
-import { AuthNeededError, isRootModelWithInternetAccounts, isUriLocation, } from "../types/index.js";
+import { isElectron, isNode } from '../environment.js';
+import { getBlob, getFileFromCache } from '../tracks.js';
+import { AuthNeededError, isRootModelWithInternetAccounts, isUriLocation, } from '../types/index.js';
+import { CachedFilehandle, RemoteFileWithRangeCache, } from './RemoteFileWithRangeCache.js';
 function isLocalPathLocation(location) {
     return 'localPath' in location;
 }
@@ -13,71 +12,177 @@ function isBlobLocation(location) {
 function isFileHandleLocationLocal(location) {
     return 'handleId' in location;
 }
+/** if a UriLocation has a baseUri, resolves its uri with respect to that base */
 export function resolveUriLocation(location) {
     return location.baseUri
         ? { ...location, uri: new URL(location.uri, location.baseUri).href }
         : location;
 }
+/**
+ * The local path a `file:` URI or a bare absolute path names, or undefined for
+ * anything else. A Windows URL parses as `/C:/data/x.bam`, whose leading slash
+ * is part of the URL grammar rather than the path, and a host is a network
+ * share: `\\server\share\x.bam` is `file://server/share/x.bam`.
+ */
+function uriToLocalPath(uri) {
+    if (uri.startsWith('/') || /^[a-z]:[\\/]/i.test(uri)) {
+        return uri;
+    }
+    if (!uri.startsWith('file:')) {
+        return undefined;
+    }
+    try {
+        const { host, pathname } = new URL(uri);
+        const decoded = decodeURIComponent(pathname);
+        return host && host !== 'localhost'
+            ? `//${host}${decoded}`
+            : /^\/[a-z]:/i.test(decoded)
+                ? decoded.slice(1)
+                : decoded;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function openLocation(location, pluginManager) {
     if (isLocalPathLocation(location)) {
         if (!location.localPath) {
             throw new Error('No local path provided');
         }
         if (isNode || isElectron) {
-            return new LocalFile(location.localPath);
+            // Same chunk cache the remote path has always had. A local read is not
+            // free — desktop re-read every byte of every pan — and the layer above
+            // does not care where the bytes came from.
+            return new CachedFilehandle(new LocalFile(location.localPath), `file://${location.localPath}`);
         }
         else {
             throw new Error("can't use local files in the browser");
         }
     }
     if (isBlobLocation(location)) {
+        // special case where blob is not directly stored on the model, use a getter
         const blob = getBlob(location.blobId);
         if (!blob) {
             throw new Error(`file ("${location.name}") was opened locally from a previous session. To restore it, go to track settings and reopen the file`);
         }
-        return new BlobFile(blob);
+        // keyed on the blobId rather than anything derived from the Blob: two
+        // handles for the same session-stored blob should share chunks, and two
+        // unrelated blobs must not
+        return new CachedFilehandle(new BlobFile(blob), `blob://${location.blobId}`);
     }
     if (isFileHandleLocationLocal(location)) {
+        // FileHandleLocation uses an in-memory cache of File objects
+        // The cache is populated asynchronously via ensureFileHandleReady
         const file = getFileFromCache(location.handleId);
         if (!file) {
             throw new Error(`file ("${location.name}") requires permission. Please reopen the file from track settings`);
         }
-        return new BlobFile(file);
+        return new CachedFilehandle(new BlobFile(file), `filehandle://${location.handleId}`);
     }
     if (isUriLocation(location)) {
+        // Check for empty string
         if (!location.uri) {
             throw new Error('No URI provided');
         }
+        // Resolve any relative URLs to absolute URLs. Before *choosing* the account
+        // and not only before opening: an account is matched on the location's host
+        // or URL prefix, which a uri relative to a baseUri does not carry yet — so
+        // a config that names its files relative to itself found no account at all
+        // and read every one of them unauthenticated.
         const absoluteLocation = resolveUriLocation(location);
+        // A file: URI or a bare absolute path names a file on this machine. A
+        // config.json opened from disk resolves `uri: 'reads.bam'` against its own
+        // directory to file:///dir/reads.bam, and a session built over MCP writes
+        // `uri: '/dir/reads.bam'` with no baseUri at all; fetched, either is a 404.
+        const localPath = uriToLocalPath(absoluteLocation.uri);
+        if (localPath !== undefined && (isNode || isElectron)) {
+            return openLocation({ localPath, locationType: 'LocalPathLocation' });
+        }
+        // If there is a plugin manager, we can try internet accounts
         if (pluginManager) {
-            const internetAccount = getInternetAccount(location, pluginManager);
+            const internetAccount = getInternetAccount(absoluteLocation, pluginManager);
+            // If an internetAccount was found, use it to open the location
             if (internetAccount) {
                 return internetAccount.openLocation(absoluteLocation);
             }
         }
+        // Otherwise fall back on usual open
         return new RemoteFileWithRangeCache(absoluteLocation.uri, {
             fetch: checkAuthNeededFetch,
         });
     }
     throw new Error('invalid fileLocation');
 }
+/**
+ * Open a tabix-style index (TBI or CSI) and return it under the correct
+ * filehandle key for `new TabixIndexedFile(...)`. Centralizes the CSI-vs-TBI
+ * branch so callers can't mismatch the two — e.g. writing `=== 'CSI'` on both
+ * the csi and tbi lines, which silently yields no index at all.
+ */
+export function openTabixIndexFilehandle(location, indexType, pluginManager) {
+    const filehandle = openLocation(location, pluginManager);
+    return indexType === 'CSI'
+        ? { csiFilehandle: filehandle }
+        : { tbiFilehandle: filehandle };
+}
+/**
+ * A fetch that presents `location`'s credentials — and only for urls that
+ * credential covers.
+ *
+ * An account's own fetcher signs whatever url it is handed: the location it was
+ * built from decides which token to mint, not where the token may go. That is
+ * fine for a caller holding one url, which is what `openLocation` is, and wrong
+ * for one that fetches urls a *server* names. Htsget is the second kind — a
+ * ticket request answers with data-block urls that can point anywhere — and it
+ * had no way to ask whether a given url was still in scope.
+ *
+ * So ask here. Every url other than the one the fetcher was requested for goes
+ * back through the account's `handlesLocation`, which is the same
+ * `uriMatchesDomains` test that chose the account in the first place. Both
+ * directions matter: `domains` entries scope to a path as well as a host
+ * (`data.mylab.org/private`, and the origin-plus-directory form every ephemeral
+ * HTTP Basic account is minted with), and one account routinely spans several
+ * hosts (Dropbox lists seven). An origin comparison is wrong for both.
+ *
+ * Anything out of scope gets a plain fetch rather than `checkAuthNeededFetch`:
+ * a 401 from a url the config never named should not raise a credential prompt
+ * for a host the server picked.
+ */
 export function getFetcher(location, pluginManager) {
     if (!isUriLocation(location)) {
         throw new Error(`Not a valid UriLocation: ${JSON.stringify(location)}`);
     }
     if (pluginManager) {
-        const internetAccount = getInternetAccount(location, pluginManager);
+        // resolved for the same reason openLocation resolves before matching
+        const absoluteLocation = resolveUriLocation(location);
+        const internetAccount = getInternetAccount(absoluteLocation, pluginManager);
         if (internetAccount) {
-            return internetAccount.getFetcher(location);
+            const authorized = internetAccount.getFetcher(absoluteLocation);
+            return (input, init) => {
+                const url = typeof input === 'string' ? input : input.url;
+                // The requested url passes on identity, so a location matched by
+                // something other than `domains` — the same-app-origin exception a
+                // relative uri needs — still authenticates the file it was resolved for
+                return url === absoluteLocation.uri ||
+                    internetAccount.handlesLocation({
+                        uri: url,
+                        locationType: 'UriLocation',
+                    })
+                    ? authorized(input, init)
+                    : fetch(input, init);
+            };
         }
     }
     return checkAuthNeededFetch;
 }
 function getInternetAccount(location, pluginManager) {
     const { rootModel } = pluginManager;
+    // If there is an appRootModel, use it to find the internetAccount
     if (rootModel && isRootModelWithInternetAccounts(rootModel)) {
         return rootModel.findAppropriateInternetAccount(location);
     }
+    // If there is no appRootModel, but there is pre-auth, create a temporary
+    // internetAccount. This is typical in a worker.
     if (location.internetAccountPreAuthorization) {
         if (!location.internetAccountPreAuthorization.authInfo.token) {
             throw new Error('Failed to obtain token from internet account. Try reloading the page');
@@ -91,6 +196,9 @@ function getInternetAccount(location, pluginManager) {
     }
     return undefined;
 }
+// This fetch throws a special error if the response is "401" and includes a
+// "WWW-Authenticate: Basic" header. This is so downstream code can retry if
+// needed with HTTP Basic authentication included
 async function checkAuthNeededFetch(url, opts) {
     const response = await fetch(url, opts);
     if (response.status === 401 &&
@@ -99,4 +207,4 @@ async function checkAuthNeededFetch(url, opts) {
     }
     return response;
 }
-export { RemoteFileWithRangeCache } from "./RemoteFileWithRangeCache.js";
+export { CachedFilehandle, RemoteFileWithRangeCache, } from './RemoteFileWithRangeCache.js';

package/esm/util/isDataCurrent.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether the key held data was committed under still equals the key a fetch
+ * issued now would carry. Keys are values compared structurally, so a stamp
+ * that kept its identity short-circuits on `===`, and an `undefined`-valued
+ * field or a fieldless class instance is still a distinct state — the two
+ * shapes `JSON.stringify` flattened. An `undefined` loaded key is nothing
+ * fetched yet, so never current.
+ */
+export declare function isDataCurrent(loaded: unknown, current: unknown): boolean;

package/esm/util/isDataCurrent.js

@@ -0,0 +1,12 @@
+import { compareStructural } from 'mobx';
+/**
+ * Whether the key held data was committed under still equals the key a fetch
+ * issued now would carry. Keys are values compared structurally, so a stamp
+ * that kept its identity short-circuits on `===`, and an `undefined`-valued
+ * field or a fieldless class instance is still a distinct state — the two
+ * shapes `JSON.stringify` flattened. An `undefined` loaded key is nothing
+ * fetched yet, so never current.
+ */
+export function isDataCurrent(loaded, current) {
+    return loaded !== undefined && compareStructural(loaded, current);
+}

package/esm/util/isTextEntryFocused.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether the user is typing into a text field, for a document-level shortcut
+ * that must leave that field's own keys alone: ctrl+z undoing typing rather
+ * than the session, ctrl+arrow moving the caret rather than the view. A
+ * `<textarea>` counts, which the multiline config and JSON editors render.
+ */
+export declare function isTextEntryFocused(): boolean;

package/esm/util/isTextEntryFocused.js

@@ -0,0 +1,16 @@
+/**
+ * Whether the user is typing into a text field, for a document-level shortcut
+ * that must leave that field's own keys alone: ctrl+z undoing typing rather
+ * than the session, ctrl+arrow moving the caret rather than the view. A
+ * `<textarea>` counts, which the multiline config and JSON editors render.
+ */
+export function isTextEntryFocused() {
+    const el = document.activeElement;
+    if (!(el instanceof HTMLElement)) {
+        return false;
+    }
+    const tag = el.tagName.toUpperCase();
+    // coerced: isContentEditable is declared boolean but is undefined in jsdom,
+    // so the raw expression returns undefined for an ordinary focused element
+    return tag === 'INPUT' || tag === 'TEXTAREA' || !!el.isContentEditable;
+}

package/esm/util/isWebWorker.js

@@ -1,4 +1,3 @@
 export function isWebWorker() {
-    return (typeof WorkerGlobalScope !== 'undefined' &&
-        self instanceof WorkerGlobalScope);
+    return 'WorkerGlobalScope' in globalThis;
 }

package/esm/util/iupac.d.ts

@@ -0,0 +1,4 @@
+export declare const IUPAC_MOTIF_REGEX: RegExp;
+export declare function iupacToRegex(motif: string): string;
+export declare function reverseComplementIupac(motif: string): string;
+export declare function isPalindromic(motif: string): boolean;

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,177 @@
 import { Jexl } from '@jbrowse/jexl';
-export default function JexlF() {
+import { categoricalColor } from '../ui/colors.js';
+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();
+    // 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('max', Math.max);
-    j.addFunction('min', Math.min);
+    j.addFunction('id', (feature) => unwrapFeature(feature).id());
+    /**
+     * #jexlFunction Feature operations - getInherited | getInherited(feature, 'gene_biotype') | the attribute from the feature, or from its nearest ancestor that has it, so a CDS reads its gene's value
+     */
+    j.addFunction('getInherited', (feature, name) => {
+        let cur = unwrapFeature(feature);
+        while (cur !== undefined) {
+            const value = cur.get(name);
+            if (value !== undefined) {
+                return value;
+            }
+            cur = cur.parent?.();
+        }
+        return undefined;
+    });
+    // let user cast a jexl type into a javascript type
+    j.addFunction('cast', (arg) => arg);
+    // jexl's own list-aware min and max take varargs too; a Math.min
+    // registration would replace them
+    /**
+     * #jexlFunction Math functions | max(0, 2)
+     * #jexlFunction Math functions | min(feature.INFO.AF)
+     * #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);
+    /** #jexlFunction Color functions | categoricalColor(getInherited(feature, 'biotype'), ['protein_coding']) | a palette color per value: the values listed take the palette (an optional third argument) in order, any other value a stable color no listed value paints, a missing one grey */
+    j.addFunction('categoricalColor', categoricalColor);
+    // 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/jexlFilterRows.d.ts

@@ -0,0 +1,89 @@
+import type { AstNode, Subject } from '@jbrowse/jexl';
+export type JexlFilterFieldType = 'number' | 'text' | 'flag';
+export type JexlFilterField = {
+    label: string;
+    /** unset for a field whose values may be numbers or text */
+    type?: JexlFilterFieldType;
+    group?: string;
+    description?: string;
+    /** holds several values per feature, so a comparison asks whether any does */
+    multi?: boolean;
+    values?: string[];
+} & ({
+    path: string[];
+} | {
+    call: string;
+});
+export interface FieldChoice {
+    key: string;
+    label: string;
+    type?: JexlFilterFieldType;
+    subject: Subject;
+    group?: string;
+    description?: string;
+    multi?: boolean;
+    values?: string[];
+}
+export type RowOp = '>' | '>=' | '<' | '<=' | '==' | '!=' | 'in' | '~' | 'set' | '!set';
+export declare const OPERATORS: Record<JexlFilterFieldType | 'any', {
+    op: RowOp;
+    label: string;
+}[]>;
+export interface ConditionRow {
+    kind: 'condition';
+    id: number;
+    line?: number;
+    field?: FieldChoice;
+    op: RowOp;
+    value: string | string[];
+}
+export interface TextRow {
+    kind: 'text';
+    id: number;
+    line?: number;
+    text: string;
+}
+export type FilterRow = ConditionRow | TextRow;
+/**
+ * Rows keep the index of the stored line they came from until one of that
+ * line's rows changes, so an untouched line is written back byte-identical.
+ */
+export interface FilterRows {
+    lines: readonly string[];
+    rows: FilterRow[];
+}
+interface Parser {
+    parse: (text: string) => AstNode | null;
+}
+export declare function resolveFields(fields: readonly JexlFilterField[]): {
+    key: string;
+    label: string;
+    type: JexlFilterFieldType | undefined;
+    group: string | undefined;
+    description: string | undefined;
+    multi: boolean | undefined;
+    values: string[] | undefined;
+    subject: Subject;
+}[];
+/**
+ * The columns an adapter's metadata describes as `{column: description}`, as
+ * a BigBed's autoSql does, less those `fields` already lists. Any other
+ * metadata describes none.
+ */
+export declare function describedColumns(metadata: unknown, fields: readonly JexlFilterField[]): JexlFilterField[];
+/** A field typed into the picker rather than chosen, read as a dotted path. */
+export declare function typedField(text: string): FieldChoice;
+export declare function stripJexlPrefix(line: string): string;
+export declare function readFilterRows(lines: readonly string[], parser: Parser, choices: readonly FieldChoice[]): FilterRows;
+export declare function addRow(state: FilterRows): FilterRows;
+export declare function replaceRow(state: FilterRows, row: FilterRow): FilterRows;
+export declare function removeRow(state: FilterRows, id: number): FilterRows;
+export declare function withField(row: ConditionRow, field: FieldChoice): ConditionRow;
+export declare function withOp(row: ConditionRow, op: RowOp): ConditionRow;
+/**
+ * The stored filters: an untouched line as it was, and every row of an edited
+ * line as a line of its own, which is equivalent because lines AND together.
+ * Rows left incomplete are dropped.
+ */
+export declare function writeFilterRows({ lines, rows }: FilterRows): string[];
+export {};