@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/pluggableElementTypes/models/saveTrackFileTypes/types.d.ts

@@ -1,11 +1,19 @@
-import type { AbstractSessionModel, Feature } from '@jbrowse/core/util';
+import type { AbstractSessionModel, Feature, StatusCallback, StopToken } from '@jbrowse/core/util';
 export interface FileTypeExporter {
     name: string;
     extension: string;
     helpText?: string;
+    /**
+     * The stop token and status callback are the pair every RPC on the export
+     * path already carries. Most writers are string assembly and ignore both;
+     * GenBank fetches the ORIGIN sequence, and without them closing the dialog
+     * left a whole-gene read running with nothing waiting on it.
+     */
     callback: (arg: {
         features: Feature[];
         session: AbstractSessionModel;
         assemblyName: string;
+        stopToken?: StopToken;
+        statusCallback?: StatusCallback;
     }) => Promise<string> | string;
 }

package/esm/pluggableElementTypes/models/saveTrackFileTypes/util.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The feature fields these writers spend on a column of their own — position,
+ * identity, a link to a parent — and therefore do not repeat as an
+ * attribute/qualifier. GenBank adds `name`, which GFF3 keeps so it can retitle
+ * it to `Name`.
+ */
+export declare const coreFeatureFields: Set<string>;
+/**
+ * Column 6 of BED and column 7 of GFF3 are the same three tokens over the same
+ * 1/-1/0 a feature carries, so the convention gets one definition.
+ */
+export declare function formatStrand(strand: number | undefined): "+" | "-" | ".";
+/**
+ * Render an attribute value: an array joins on a comma, an object goes through
+ * JSON, anything else stringifies. Returns undefined for a value with nothing
+ * in it, so a caller can drop the attribute rather than write it empty.
+ *
+ * `encode` is the format's escaping, applied to each leaf — GFF3
+ * percent-encodes its delimiters, GenBank doubles quotes instead.
+ */
+export declare function formatAttributeValue(obj: unknown, encode?: (str: string) => string): string | undefined;

package/esm/pluggableElementTypes/models/saveTrackFileTypes/util.js

@@ -0,0 +1,51 @@
+/**
+ * The feature fields these writers spend on a column of their own — position,
+ * identity, a link to a parent — and therefore do not repeat as an
+ * attribute/qualifier. GenBank adds `name`, which GFF3 keeps so it can retitle
+ * it to `Name`.
+ */
+export const coreFeatureFields = new Set([
+    'uniqueId',
+    'id',
+    'refName',
+    'source',
+    'type',
+    'start',
+    'end',
+    'strand',
+    'parent',
+    'parentId',
+    'score',
+    'subfeatures',
+    'phase',
+]);
+/**
+ * Column 6 of BED and column 7 of GFF3 are the same three tokens over the same
+ * 1/-1/0 a feature carries, so the convention gets one definition.
+ */
+export function formatStrand(strand) {
+    return strand === 1 ? '+' : strand === -1 ? '-' : '.';
+}
+/**
+ * Render an attribute value: an array joins on a comma, an object goes through
+ * JSON, anything else stringifies. Returns undefined for a value with nothing
+ * in it, so a caller can drop the attribute rather than write it empty.
+ *
+ * `encode` is the format's escaping, applied to each leaf — GFF3
+ * percent-encodes its delimiters, GenBank doubles quotes instead.
+ */
+export function formatAttributeValue(obj, encode = str => str) {
+    if (obj === null || obj === undefined) {
+        return undefined;
+    }
+    if (Array.isArray(obj)) {
+        const items = obj
+            .map(o => formatAttributeValue(o, encode))
+            .filter(o => o !== undefined);
+        return items.length > 0 ? items.join(',') : undefined;
+    }
+    if (typeof obj === 'object') {
+        return encode(JSON.stringify(obj));
+    }
+    return encode(String(obj));
+}

package/esm/pluggableElementTypes/models/uriMatchesDomains.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Whether a URL falls under one of an internet account's `domains` entries —
+ * i.e. whether that account's credentials should be attached to it.
+ *
+ * This was a plain `uri.includes(domain)` over the whole URI, which is not a
+ * containment test at all: `https://evil.example.com/?x=drive.google.com`
+ * matched a Google Drive account, and jbrowse-web reads session specs (tracks
+ * and all) out of the URL, so a link could aim someone's Drive token at a
+ * server of the link author's choosing. `evil-dropbox.com` matched too.
+ *
+ * An entry is one of two shapes, told apart by whether it contains a `/`:
+ *
+ * - **a host** (`dropbox.com`, `localhost:8080`) — matches that host and its
+ *   subdomains, on a dot boundary. Both defaulted account types spell their
+ *   domains this way.
+ * - **a URL prefix** (`https://data.mylab.org/reads/`, `mylab.org/reads`) — the
+ *   scheme is optional, and the match runs to a path-segment boundary, so
+ *   `/reads` does not match `/readsets`. This is the shape RpcManager's
+ *   ephemeral HTTP Basic accounts store (origin + the file's directory), and
+ *   the shape a config uses to scope an account to part of a server.
+ *
+ * The query string and fragment are never consulted under either shape: they
+ * are the caller's data, not the server's identity.
+ *
+ * A URI that is not absolute matches nothing. Callers hold a `baseUri` for
+ * those and are expected to resolve first (`resolveUriLocation`) — matching a
+ * relative path against a host could only ever succeed by accident.
+ */
+export declare function uriMatchesDomains(uri: string, domains: string[]): boolean;

package/esm/pluggableElementTypes/models/uriMatchesDomains.js

@@ -0,0 +1,62 @@
+/**
+ * Whether a URL falls under one of an internet account's `domains` entries —
+ * i.e. whether that account's credentials should be attached to it.
+ *
+ * This was a plain `uri.includes(domain)` over the whole URI, which is not a
+ * containment test at all: `https://evil.example.com/?x=drive.google.com`
+ * matched a Google Drive account, and jbrowse-web reads session specs (tracks
+ * and all) out of the URL, so a link could aim someone's Drive token at a
+ * server of the link author's choosing. `evil-dropbox.com` matched too.
+ *
+ * An entry is one of two shapes, told apart by whether it contains a `/`:
+ *
+ * - **a host** (`dropbox.com`, `localhost:8080`) — matches that host and its
+ *   subdomains, on a dot boundary. Both defaulted account types spell their
+ *   domains this way.
+ * - **a URL prefix** (`https://data.mylab.org/reads/`, `mylab.org/reads`) — the
+ *   scheme is optional, and the match runs to a path-segment boundary, so
+ *   `/reads` does not match `/readsets`. This is the shape RpcManager's
+ *   ephemeral HTTP Basic accounts store (origin + the file's directory), and
+ *   the shape a config uses to scope an account to part of a server.
+ *
+ * The query string and fragment are never consulted under either shape: they
+ * are the caller's data, not the server's identity.
+ *
+ * A URI that is not absolute matches nothing. Callers hold a `baseUri` for
+ * those and are expected to resolve first (`resolveUriLocation`) — matching a
+ * relative path against a host could only ever succeed by accident.
+ */
+export function uriMatchesDomains(uri, domains) {
+    let url;
+    try {
+        url = new URL(uri);
+    }
+    catch {
+        return false;
+    }
+    // `host` carries the port and `hostname` does not, so an entry can name
+    // either `localhost:8080` or `localhost` and mean it
+    const hosts = [url.hostname.toLowerCase(), url.host.toLowerCase()];
+    // paths, unlike hosts, are case-sensitive, so these are compared as written
+    const prefixable = [
+        `${url.origin}${url.pathname}`,
+        `${url.host}${url.pathname}`,
+    ];
+    return domains.some(domain => {
+        if (!domain) {
+            return false;
+        }
+        if (domain.includes('/')) {
+            return prefixable.some(candidate => candidate.startsWith(domain) &&
+                (domain.endsWith('/') ||
+                    candidate.length === domain.length ||
+                    candidate[domain.length] === '/'));
+        }
+        // A leading dot is the cookie-domain spelling of "and its subdomains",
+        // which is what this branch does anyway. It read as a substring under the
+        // old `includes` test and so worked; taken literally here it is a hostname
+        // no URL can have, and the account would have gone quietly unused.
+        const lower = domain.toLowerCase().replace(/^\./, '');
+        return hosts.some(host => host === lower || host.endsWith(`.${lower}`));
+    });
+}

package/esm/pluggableElementTypes/renderers/util/serializableFilterChain.d.ts

@@ -1,21 +1,22 @@
-type FilterExpression = (...args: Record<string, any>[] | any[]) => boolean;
+import type { JexlExpression, JexlInstance } from '../../../util/jexlStrings.ts';
 interface Filter {
     string: string;
-    expr: FilterExpression;
+    expr: JexlExpression;
 }
 export type SerializedFilterChain = string[];
 export default class SerializableFilterChain {
     filterChain: Filter[];
     constructor({ filters, jexl, }: {
         filters: SerializedFilterChain;
-        jexl?: unknown;
+        jexl: JexlInstance;
     });
-    passes(...args: any[]): boolean;
+    passes(feature: unknown, extraContext?: Record<string, unknown>): boolean;
     toJSON(): {
         filters: string[];
     };
     static fromJSON(json: {
         filters: SerializedFilterChain;
+        jexl: JexlInstance;
     }): SerializableFilterChain;
 }
 export {};

package/esm/pluggableElementTypes/renderers/util/serializableFilterChain.js

@@ -1,4 +1,5 @@
-import { stringToJexlExpression } from "../../../util/jexlStrings.js";
+import { stringToJexlExpression } from '../../../util/jexlStrings.js';
+import { buildJexlContext } from '../../../util/simpleFeature.js';
 export default class SerializableFilterChain {
     filterChain;
     constructor({ filters, jexl, }) {
@@ -6,17 +7,26 @@ export default class SerializableFilterChain {
             .map(f => f.trim())
             .filter(f => !!f)
             .map(inputFilter => {
-            if (typeof inputFilter === 'string') {
-                const expr = stringToJexlExpression(inputFilter, jexl);
-                return { expr, string: inputFilter };
-            }
-            throw new Error(`invalid inputFilter string "${inputFilter}"`);
+            const expr = stringToJexlExpression(inputFilter, jexl);
+            return { expr, string: inputFilter };
         });
     }
-    passes(...args) {
-        for (const entry of this.filterChain) {
-            if (!entry.expr.eval({ feature: args[0] })) {
-                return false;
+    // `feature` is the filter subject; `extraContext` supplies any additional
+    // named bindings the expression may reference. Both go through the same
+    // context builder as config-slot evaluation, so a Feature is exposed
+    // identically (proxy + `get()`), regardless of which path evaluates it.
+    //
+    // an empty chain skips context construction entirely: passes() runs once per
+    // feature in the render admission path, and the unfiltered case would
+    // otherwise allocate a spread, a context object, and a feature proxy per
+    // feature only to admit it
+    passes(feature, extraContext) {
+        if (this.filterChain.length > 0) {
+            const context = buildJexlContext({ ...extraContext, feature });
+            for (const entry of this.filterChain) {
+                if (!entry.expr.eval(context)) {
+                    return false;
+                }
             }
         }
         return true;

package/esm/pluginDefinitions.d.ts

@@ -0,0 +1,198 @@
+/**
+ * What a plugin definition is, and everything that can be answered by looking
+ * at one — its url, its name, whether two describe the same plugin.
+ *
+ * Kept apart from PluginLoader, which pulls in ReExports (effectively all of
+ * core) to be able to run a plugin. Inspecting a definition must not cost that:
+ * the plugin store resolves definitions and would otherwise import core's
+ * config layer back into itself.
+ */
+export interface UMDLocPluginDefinition {
+    umdLoc: {
+        uri: string;
+        baseUri?: string;
+    };
+    name: string;
+    integrity?: string;
+}
+export interface UMDUrlPluginDefinition {
+    umdUrl: string;
+    name: string;
+    integrity?: string;
+}
+export interface LegacyUMDPluginDefinition {
+    url: string;
+    name: string;
+    integrity?: string;
+}
+export type UMDPluginDefinition = UMDLocPluginDefinition | UMDUrlPluginDefinition;
+export interface ESMLocPluginDefinition {
+    esmLoc: {
+        uri: string;
+        baseUri?: string;
+    };
+    name?: string;
+}
+export interface ESMUrlPluginDefinition {
+    esmUrl: string;
+    name?: string;
+}
+export type ESMPluginDefinition = ESMLocPluginDefinition | ESMUrlPluginDefinition;
+export interface CJSPluginDefinition {
+    cjsUrl: string;
+    name?: string;
+}
+/**
+ * A plugin named by its plugin-store entry rather than by a url — the query
+ * ("MsaView, for this JBrowse") instead of a precomputed answer ("these exact
+ * bytes"). `resolveStorePluginRefs` (util/pluginStore.ts) turns one into a
+ * concrete, version-pinned, integrity-carrying definition against the published
+ * manifest, so a definition in this shape never reaches PluginLoader.
+ *
+ * It exists for the population nobody can revisit. A config at a permanent url
+ * — jbrowse.org/ucsc/hg38, the ~50k genark hubs — names its plugins once and is
+ * then read for years by whatever JBrowse loads it. A url there is an answer
+ * computed on the day the config was generated, and the only answer that keeps
+ * working is the store's mutable `latest/` path: no integrity hash, and the same
+ * bytes for every host. A store name defers both decisions to load time.
+ *
+ * The value is the store's `name` — the same string a url-bearing entry puts in
+ * `name`, and the UMD global the bundle defines. NOT the npm package. A config
+ * at a permanent url must name something that cannot be renamed out from under
+ * it, and the npm package is owned by npm and the plugin's author: a scope move
+ * strands every config that named it, which is the mistake naming a url makes,
+ * one level up. The store owns its `name`, so it can point one at a different
+ * package without touching a config. See jbrowse-plugin-list ADR 0008.
+ */
+export interface StorePluginDefinition {
+    storePlugin: string;
+    name?: string;
+}
+/**
+ * `storePlugin` also rides along on the url-bearing forms, in both directions.
+ * A config can carry a ref *and* a url — the ref for a JBrowse that resolves it,
+ * the url for one that does not — which is what lets a config generator start
+ * emitting refs before every host reading it understands them. And resolution
+ * keeps the field on what it produces, so a resolved definition still records
+ * which store entry it came from and `samePlugin` can match it against a ref.
+ *
+ * On a resolved definition `storePlugin` and `name` hold the same string, since
+ * both are the store's `name`. They are still distinct fields: `name` is what
+ * `loadUMDPlugin` looks up on `globalThis`, and `storePlugin` is the assertion
+ * that the manifest is where this came from.
+ */
+export type PluginDefinition = (UMDUrlPluginDefinition | UMDLocPluginDefinition | LegacyUMDPluginDefinition | ESMLocPluginDefinition | ESMUrlPluginDefinition | CJSPluginDefinition | StorePluginDefinition) & {
+    storePlugin?: string;
+};
+export declare function isUMDPluginDefinition(def: PluginDefinition): def is UMDPluginDefinition | LegacyUMDPluginDefinition;
+export declare function isESMPluginDefinition(def: PluginDefinition): def is ESMPluginDefinition;
+export declare function isCJSPluginDefinition(def: PluginDefinition): def is CJSPluginDefinition;
+/**
+ * Whether a definition names a store entry to resolve. Deliberately not part of
+ * the CJS/ESM/UMD trio `assertSingleKind` counts: those are loaders, and a ref
+ * is not one. A ref names *which plugin*, and pairing it with a url is the
+ * supported migration shape rather than the two-loaders ambiguity that guard
+ * exists to refuse.
+ */
+export declare function isStorePluginDefinition(def: PluginDefinition): def is PluginDefinition & {
+    storePlugin: string;
+};
+/** The store entry a definition names, resolved or not. */
+export declare function storePluginName(def: PluginDefinition): string | undefined;
+export declare const vendoredPluginNames: Set<string>;
+/**
+ * Desktop's half of the same list — a plugin one product bundles and another does
+ * not, which the shared set above cannot express.
+ *
+ * Blat is in Desktop's corePlugins but deliberately not Web's: Web is where
+ * cold-load bundle size is paid, and BLAT is niche. So Desktop's bundled copy is
+ * the only one that ships. It is what gives BLAT on a genome the user opened
+ * from their own disk, where no config names any plugin, and it is the copy that
+ * reaches UCSC through the main-process `blatFetch` bridge and the CAPTCHA-solve
+ * window. Web has to load the external entry to have BLAT at all.
+ *
+ * Naming it drops a config's `plugins[]` entry for Blat before Desktop's loader
+ * sees it, so a config that carries one does not install a second copy beside
+ * the bundled one and append its Tools menu items twice. Nothing carries one
+ * today: jb2hubs stamps `sequence.metadata.blatDb`, which names the UCSC db an
+ * assembly is searchable under and says nothing about loading a plugin. The
+ * entry is a guard for the UMD build (`plugins/blat/scripts/build-umd.ts`),
+ * which a config can name and which is how Web would pick BLAT up.
+ *
+ * It lives here beside the shared set rather than in jbrowse-desktop because the
+ * two are read together — a surface consulting one and not the other offers an
+ * install the loader then drops, which is what Desktop's plugin store and global
+ * plugins dialog both did.
+ */
+export declare const desktopVendoredPluginNames: string[];
+export declare function dropVendoredPlugins(defs: PluginDefinition[], alsoVendored?: Iterable<string>): PluginDefinition[];
+export declare function pluginDescriptionString(d: PluginDefinition): string;
+/**
+ * The url a definition loads from, or undefined when it names no loader at all.
+ * Comparisons between definitions go through this rather than `pluginUrl`, whose
+ * 'unknown url' placeholder is display text: two unloadable definitions are not
+ * the same plugin just because neither has a url.
+ */
+export declare function maybePluginUrl(d: PluginDefinition): string | undefined;
+export declare function pluginUrl(d: PluginDefinition): string;
+/**
+ * Whether a definition loads from exactly `url` — the question behind "which
+ * definition is this loaded plugin", "is this one in the session's list", "which
+ * entry does an uninstall remove".
+ *
+ * The two undefined guards are the whole point, and both were live as
+ * `pluginUrl(d) === url` comparisons. A definition naming no loader reads back as
+ * the literal `'unknown url'`, so any two of them compared equal: approving one
+ * marked every other unloadable definition trusted, and removing one filtered
+ * every other unloadable one out of the config. And the url side is absent for a
+ * core or global plugin (no install url was recorded), which must match no
+ * definition rather than the first url-less one.
+ */
+export declare function isPluginUrl(d: PluginDefinition, url: string | undefined): boolean;
+export declare function pluginName(definition: PluginDefinition): string | undefined;
+export declare function pluginDefinitionMetadata(definition: PluginDefinition): {
+    name: string | undefined;
+    url: string;
+};
+/**
+ * How to name a definition to a person — a crash marker saying what was
+ * loading, a warning listing what a host did not pass in.
+ *
+ * A ref that has not been resolved yet has no url and often no `name`, and
+ * everything here used to fall through to `pluginUrl`'s 'unknown url' for it:
+ * a marker naming nothing, which is the difference between a banner the user
+ * can act on and one that says only that something went wrong.
+ */
+export declare function pluginLabel(definition: PluginDefinition): string;
+/**
+ * Whether two definitions describe the same plugin. They can without being
+ * identical — a UMD name+url in a config, an esmUrl in the global list, a store
+ * ref in one and the pinned definition it resolves to in the other — so a
+ * shared store package, a shared name, or a shared url is each enough. All
+ * three are optional (an ESM definition carries no name, an unloadable one no
+ * url, a hand-written one no package), and a missing field never matches: two
+ * definitions are not the same plugin just because neither names one.
+ *
+ * The store name is checked first because it is the only one of the three that
+ * survives resolution intact. A ref and its resolved form share it; they share
+ * no url, and a *bare* ref has no `name` until the manifest supplies one — so
+ * this clause is doing work even though a resolved definition's `storePlugin`
+ * and `name` agree.
+ *
+ * This is the single answer to "is this plugin already installed" — dedupe
+ * across plugin sources, the plugin store's installed-check — so those cannot
+ * drift apart and disagree about what is a duplicate.
+ */
+export declare function samePlugin(a: PluginDefinition, b: PluginDefinition): boolean;
+/**
+ * The candidates no definition in `existing` already describes — `dedupePlugins`
+ * across two lists whose first one is already settled, for a source loaded after
+ * another rather than merged with it.
+ */
+export declare function pluginsNotIn(candidates: PluginDefinition[], existing: PluginDefinition[]): PluginDefinition[];
+/**
+ * Drops later definitions that name a plugin an earlier one already did, so the
+ * first source listed wins: a config's own (version-pinned) entry takes
+ * precedence over the same plugin from the user's global list.
+ */
+export declare function dedupePlugins(plugins: PluginDefinition[]): PluginDefinition[];