@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/util/seqUtils.d.ts

@@ -0,0 +1,17 @@
+export declare const complementTable: Record<string, string>;
+export declare function revcom(str: string): string;
+export declare function reverse(str: string): string;
+export declare function complement(str: string): string;
+export type Frame = 1 | 2 | 3 | -1 | -2 | -3;
+export declare function getFrame(start: number, end: number, strand: 1 | -1, phase: 0 | 1 | 2): Frame;
+/**
+ * The start codon the sequence track highlights. Deliberately NOT
+ * `getGeneticCode(1).starts`, which is `['TTG','CTG','ATG']` — NCBI marks the
+ * alternative initiators, but highlighting every TTG and CTG in a reference
+ * sequence would be noise. This is a display convention, not the genetic code.
+ */
+export declare const defaultStarts: string[];
+export declare function stitch(subfeats: {
+    start: number;
+    end: number;
+}[], sequence: string): string;

package/esm/util/seqUtils.js

@@ -0,0 +1,80 @@
+// from bioperl: tr/acgtrymkswhbvdnxACGTRYMKSWHBVDNX/tgcayrkmswdvbhnxTGCAYRKMSWDVBHNX/
+// generated with:
+// perl -MJSON -E '@l = split "","acgtrymkswhbvdnxACGTRYMKSWHBVDNX"; print to_json({ map { my $in = $_; tr/acgtrymkswhbvdnxACGTRYMKSWHBVDNX/tgcayrkmswdvbhnxTGCAYRKMSWDVBHNX/; $in => $_ } @l})'
+export const complementTable = {
+    S: 'S',
+    w: 'w',
+    T: 'A',
+    r: 'y',
+    a: 't',
+    N: 'N',
+    K: 'M',
+    x: 'x',
+    d: 'h',
+    Y: 'R',
+    V: 'B',
+    y: 'r',
+    M: 'K',
+    h: 'd',
+    k: 'm',
+    C: 'G',
+    g: 'c',
+    t: 'a',
+    A: 'T',
+    n: 'n',
+    W: 'W',
+    X: 'X',
+    m: 'k',
+    v: 'b',
+    B: 'V',
+    s: 's',
+    H: 'D',
+    c: 'g',
+    D: 'H',
+    b: 'v',
+    R: 'Y',
+    G: 'C',
+};
+export function revcom(str) {
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const c = str[n - 1 - i];
+        arr[i] = complementTable[c] ?? c;
+    }
+    return arr.join('');
+}
+export function reverse(str) {
+    // index loop rather than [...str] spread: sequences can be large and the
+    // spread's code-point iterator is markedly slower than raw UTF-16 access
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        arr[i] = str[n - 1 - i];
+    }
+    return arr.join('');
+}
+export function complement(str) {
+    const n = str.length;
+    const arr = new Array(n);
+    for (let i = 0; i < n; i++) {
+        const c = str[i];
+        arr[i] = complementTable[c] ?? c;
+    }
+    return arr.join('');
+}
+export function getFrame(start, end, strand, phase) {
+    return strand === 1
+        ? (((start + phase) % 3) + 1)
+        : (-1 * ((end - phase) % 3) - 1);
+}
+/**
+ * The start codon the sequence track highlights. Deliberately NOT
+ * `getGeneticCode(1).starts`, which is `['TTG','CTG','ATG']` — NCBI marks the
+ * alternative initiators, but highlighting every TTG and CTG in a reference
+ * sequence would be noise. This is a display convention, not the genetic code.
+ */
+export const defaultStarts = ['ATG'];
+export function stitch(subfeats, sequence) {
+    return subfeats.map(sub => sequence.slice(sub.start, sub.end)).join('');
+}

package/esm/util/sessionServices.d.ts

@@ -0,0 +1,29 @@
+import type { DialogHost, NotificationSink, PaletteHost, RpcHost, SessionServices } from './types/services.ts';
+import type { IAnyStateTreeNode } from '@jbrowse/mobx-state-tree';
+/**
+ * #api core/util
+ * The services a session offers that cost nothing application-shaped to name.
+ * Prefer one of the narrower accessors below, which say which of them the
+ * calling module actually uses.
+ */
+export declare function getSessionServices(node: IAnyStateTreeNode): SessionServices;
+/**
+ * #api core/util
+ * The host's RPC entry point, for a module that issues RPCs and nothing else.
+ */
+export declare function getRpcHost(node: IAnyStateTreeNode): RpcHost;
+/**
+ * #api core/util
+ * Where a display puts a message it cannot draw itself.
+ */
+export declare function getNotificationSink(node: IAnyStateTreeNode): NotificationSink;
+/**
+ * #api core/util
+ * Where a display puts a dialog it cannot mount itself.
+ */
+export declare function getDialogHost(node: IAnyStateTreeNode): DialogHost;
+/**
+ * #api core/util
+ * The colors to draw with, and the args that rebuild them in a worker.
+ */
+export declare function getPaletteHost(node: IAnyStateTreeNode): PaletteHost;

package/esm/util/sessionServices.js

@@ -0,0 +1,46 @@
+import { cachedParent, findParentThatIs } from './parentWalk.js';
+import { isSessionServices } from './types/services.js';
+// `getSession(self).notify(...)` and `getNotificationSink(self).notify(...)`
+// find the same object; the difference is what the calling module then has in
+// its type graph, which is the whole session interface in the first case and
+// four function signatures in the second. The return annotations are therefore
+// deliberate rather than inferred — widening one back to `SessionServices`
+// would undo the point of the accessor.
+const sessionServicesCache = new WeakMap();
+/**
+ * #api core/util
+ * The services a session offers that cost nothing application-shaped to name.
+ * Prefer one of the narrower accessors below, which say which of them the
+ * calling module actually uses.
+ */
+export function getSessionServices(node) {
+    return cachedParent(sessionServicesCache, node, () => findParentThatIs(node, isSessionServices), 'no session model found!');
+}
+/**
+ * #api core/util
+ * The host's RPC entry point, for a module that issues RPCs and nothing else.
+ */
+export function getRpcHost(node) {
+    return getSessionServices(node);
+}
+/**
+ * #api core/util
+ * Where a display puts a message it cannot draw itself.
+ */
+export function getNotificationSink(node) {
+    return getSessionServices(node);
+}
+/**
+ * #api core/util
+ * Where a display puts a dialog it cannot mount itself.
+ */
+export function getDialogHost(node) {
+    return getSessionServices(node);
+}
+/**
+ * #api core/util
+ * The colors to draw with, and the args that rebuild them in a worker.
+ */
+export function getPaletteHost(node) {
+    return getSessionServices(node);
+}

package/esm/util/sessionSharing.d.ts

@@ -0,0 +1,38 @@
+export declare function b64PadSuffix(b64: string): string;
+/**
+ * Decode and inflate a url-safe base64 to a string
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ */
+export declare function fromUrlSafeB64(b64: string): Promise<string>;
+/**
+ * Compress and encode a string as url-safe base64
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ */
+export declare function toUrlSafeB64(str: string): Promise<string>;
+/**
+ * The `?session=` value prefixes, named here because this module is what
+ * produces them. The decoder half (jbrowse-web's SessionLoader) has its own
+ * list covering the two prefixes nothing here writes (`spec-`, `local-`).
+ */
+export declare const SHARE_PREFIX = "share-";
+export declare const ENCODED_PREFIX = "encoded-";
+export declare const JSON_PREFIX = "json-";
+/**
+ * Joins a configured `shareURL` with one of the share service's two endpoints.
+ * A plain `${shareURL}share` silently produced `https://host/api/v1share` for
+ * the (natural) configured value without a trailing slash, and the 404 that
+ * followed read as "the share service is down". An empty shareURL is left
+ * alone: web honors an explicit empty string as "resolve relative to the page".
+ */
+export declare function shareEndpoint(shareURL: string, path: 'share' | 'load'): string;
+export type SessionShareMode = 'short' | 'long' | 'json';
+export interface EncodedSessionParam {
+    sessionParam: string;
+    password?: string;
+    plaintext?: string;
+}
+export declare function encodeSessionParam(mode: SessionShareMode, session: unknown, options: {
+    shareURL: string;
+    referer: string;
+}): Promise<EncodedSessionParam>;
+export declare function readSessionFromDynamo(loadUrl: string, sessionQueryParam: string, password: string, signal?: AbortSignal): Promise<string>;

package/esm/util/sessionSharing.js

@@ -0,0 +1,154 @@
+import { aesDecrypt, aesEncrypt } from './crypto.js';
+function bytesToBinaryString(bytes) {
+    return Array.from(bytes, b => String.fromCharCode(b)).join('');
+}
+// from https://stackoverflow.com/questions/1349404/
+// crypto.getRandomValues is available in non-secure contexts per MDN,
+// unlike crypto.subtle which requires HTTPS.
+function generateUID(length) {
+    return window
+        .btoa(bytesToBinaryString(crypto.getRandomValues(new Uint8Array(length * 2))))
+        .replaceAll(/[+/]/g, '')
+        .slice(0, length);
+}
+function getErrorMsg(err) {
+    try {
+        const obj = JSON.parse(err);
+        return obj.message ?? err;
+    }
+    catch {
+        return err;
+    }
+}
+export function b64PadSuffix(b64) {
+    let num;
+    const mo = b64.length % 4;
+    switch (mo) {
+        case 3:
+            num = 1;
+            break;
+        case 2:
+            num = 2;
+            break;
+        case 0:
+            num = 0;
+            break;
+        default:
+            throw new Error('Illegal base64url string!');
+    }
+    return b64 + '='.repeat(num);
+}
+/**
+ * Decode and inflate a url-safe base64 to a string
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ */
+export async function fromUrlSafeB64(b64) {
+    const originalB64 = b64PadSuffix(b64.replaceAll('-', '+').replaceAll('_', '/'));
+    const { inflate } = await import('pako-esm2');
+    const bytes = Uint8Array.from(atob(originalB64), c => c.charCodeAt(0));
+    const inflated = inflate(bytes, undefined);
+    return new TextDecoder('utf8').decode(inflated);
+}
+/**
+ * Compress and encode a string as url-safe base64
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ */
+export async function toUrlSafeB64(str) {
+    const bytes = new TextEncoder().encode(str);
+    const { deflate } = await import('pako-esm2');
+    const deflated = deflate(bytes, undefined);
+    const encoded = btoa(bytesToBinaryString(deflated)).replace(/=+$/, '');
+    return encoded.replaceAll('+', '-').replaceAll('/', '_');
+}
+/**
+ * The `?session=` value prefixes, named here because this module is what
+ * produces them. The decoder half (jbrowse-web's SessionLoader) has its own
+ * list covering the two prefixes nothing here writes (`spec-`, `local-`).
+ */
+export const SHARE_PREFIX = 'share-';
+export const ENCODED_PREFIX = 'encoded-';
+export const JSON_PREFIX = 'json-';
+/**
+ * Joins a configured `shareURL` with one of the share service's two endpoints.
+ * A plain `${shareURL}share` silently produced `https://host/api/v1share` for
+ * the (natural) configured value without a trailing slash, and the 404 that
+ * followed read as "the share service is down". An empty shareURL is left
+ * alone: web honors an explicit empty string as "resolve relative to the page".
+ */
+export function shareEndpoint(shareURL, path) {
+    return shareURL && !shareURL.endsWith('/')
+        ? `${shareURL}/${path}`
+        : `${shareURL}${path}`;
+}
+/**
+ * writes the encrypted session, current datetime, and referer to DynamoDB
+ */
+async function shareSessionToDynamo(session, shareURL, referer) {
+    const sess = await toUrlSafeB64(JSON.stringify(session));
+    const password = generateUID(5);
+    const data = new FormData();
+    data.append('session', await aesEncrypt(sess, password));
+    data.append('dateShared', `${Date.now()}`);
+    data.append('referer', referer);
+    const response = await fetch(shareEndpoint(shareURL, 'share'), {
+        method: 'POST',
+        mode: 'cors',
+        body: data,
+    });
+    if (!response.ok) {
+        throw new Error(getErrorMsg(await response.text()));
+    }
+    const { sessionId } = (await response.json());
+    return { sessionId, password };
+}
+// Encodes a session snapshot into the `?session=` value jbrowse-web decodes:
+// `share-<id>` (uploaded + encrypted), `encoded-<b64>` (compressed inline), or
+// `json-<json>` (plaintext inline). Single source of these prefixes, shared by
+// jbrowse-web's ShareDialog and jbrowse-desktop's ExportToWebDialog so the two
+// producers can't drift from the decoder.
+export async function encodeSessionParam(mode, session, options) {
+    if (mode === 'short') {
+        const { sessionId, password } = await shareSessionToDynamo(session, options.shareURL, options.referer);
+        return { sessionParam: `${SHARE_PREFIX}${sessionId}`, password };
+    }
+    else if (mode === 'json') {
+        // compact in the link (this mode's URL is the longest of the three
+        // already), indented in the dialog's readable-JSON panel
+        return {
+            sessionParam: `${JSON_PREFIX}${JSON.stringify({ session })}`,
+            plaintext: JSON.stringify({ session }, null, 2),
+        };
+    }
+    else {
+        const encoded = await toUrlSafeB64(JSON.stringify(session));
+        return { sessionParam: `${ENCODED_PREFIX}${encoded}` };
+    }
+}
+export async function readSessionFromDynamo(loadUrl, sessionQueryParam, password, signal) {
+    const sessionId = sessionQueryParam.startsWith(SHARE_PREFIX)
+        ? sessionQueryParam.slice(SHARE_PREFIX.length)
+        : sessionQueryParam;
+    // The password never reaches the server — it lives only in the link — so a
+    // link that lost its `&password=` (a chat client that clipped the URL, a
+    // hand-edited link) fetches fine and then fails in the cipher, where the
+    // browser's message is "The operation failed for an operation-specific
+    // reason". Say what actually went wrong instead.
+    if (!password) {
+        throw new Error('This shared session link is missing its "password" URL parameter, which is the only thing that can decrypt it');
+    }
+    const url = `${loadUrl}?sessionId=${encodeURIComponent(sessionId)}`;
+    const response = await fetch(url, { signal });
+    if (!response.ok) {
+        throw new Error(getErrorMsg(await response.text()));
+    }
+    const json = (await response.json());
+    if (typeof json.session !== 'string') {
+        throw new Error('Shared session not found — the link may have expired or the id is wrong');
+    }
+    try {
+        return await aesDecrypt(json.session, password);
+    }
+    catch (e) {
+        throw new Error('Could not decrypt the shared session — the "password" in the link is wrong or the link was truncated', { cause: e });
+    }
+}

package/esm/util/sessionStorage.d.ts

@@ -0,0 +1 @@
+export declare const sessionStorageAvailable: () => boolean, sessionStorageGetItem: (key: string) => string | undefined, sessionStorageSetItem: (key: string, value: string) => boolean, sessionStorageRemoveItem: (key: string) => boolean;

package/esm/util/sessionStorage.js

@@ -0,0 +1,15 @@
+// sessionStorage, guarded exactly as localStorage is — see webStorage.ts for
+// the three ways a Web Storage store fails.
+//
+// This store holds the internet-account access tokens, which is a per-tab cache
+// of something the user can always be asked for again. So a store that refuses
+// to be read or written costs an extra auth prompt, and a throw out of
+// `storeToken` takes the whole auth flow down instead — in the embedded
+// products, on someone else's page, which is where third-party storage is
+// blocked in the first place.
+//
+// Deliberately no `sessionStorageSetJSON` / `…GetJSON` twins: jbrowse-web's
+// session mirror is the other caller, and it *wants* the quota throw so it can
+// tell the user its autosave has stopped working.
+import { guardedSessionStorage } from './webStorage.js';
+export const { available: sessionStorageAvailable, getItem: sessionStorageGetItem, setItem: sessionStorageSetItem, removeItem: sessionStorageRemoveItem, } = guardedSessionStorage;

package/esm/util/setStackTraceLimit.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface ErrorConstructor {
+        stackTraceLimit: number;
+    }
+}
+export declare function setStackTraceLimit(): void;

package/esm/util/setStackTraceLimit.js

@@ -0,0 +1,20 @@
+// V8 records only the top 10 frames of any Error by default, and the RPC,
+// React and MST plumbing can consume all 10 before reaching JBrowse code —
+// truncating bug reports right above the actual fault. 50 gets through the
+// wrappers. Costs ~34µs extra per Error constructed, which is irrelevant here:
+// JBrowse throws exceptionally, not as control flow (MST's typecheck failures
+// are plain objects, not Errors).
+//
+// Only *applications* should call this. It mutates a global, so the embeddable
+// products (@jbrowse/react-app, react-linear-genome-view, ...) must not impose
+// it on their host page. Worker entry points are fair game: that scope is ours,
+// and a worker error's stack is captured in the worker, so the limit has to be
+// raised there to have any effect on it.
+//
+// No-op outside V8 — firefox and safari have no equivalent knob and ignore the
+// assignment.
+export function setStackTraceLimit() {
+    // setting this V8-only property is the entire point; engines without it ignore it
+    // eslint-disable-next-line unicorn/no-nonstandard-builtin-properties
+    Error.stackTraceLimit = 50;
+}

package/esm/util/simpleFeature.d.ts

@@ -1,17 +1,82 @@
+/**
+ * Abstract feature object
+ */
 export interface Feature {
+    /**
+     * Get a piece of data about the feature.  All features must have
+     * 'start' and 'end', but everything else is optional.
+     */
     get(name: 'refName'): string;
+    get(name: 'name' | 'type' | 'id' | 'source'): string | undefined;
     get(name: 'start' | 'end'): number;
+    get(name: 'phase'): 0 | 1 | 2 | undefined;
+    get(name: 'strand'): -1 | 0 | 1 | undefined;
+    get(name: 'score'): number | undefined;
     get(name: 'subfeatures'): Feature[] | undefined;
-    get(name: string): any;
+    get(name: string): unknown;
+    /**
+     * Get the unique ID of this feature.
+     */
     id(): string;
+    /**
+     * Get this feature's parent feature, or undefined if none.
+     */
     parent?: () => Feature | undefined;
+    /**
+     * Get an array of child features, or undefined if none.
+     */
     children?: () => Feature[] | undefined;
+    /**
+     * Convert to JSON
+     */
     toJSON(): SimpleFeatureSerialized;
 }
+declare const featureTarget: unique symbol;
+interface MaybeProxiedFeature {
+    [featureTarget]?: Feature;
+}
 export declare function isFeature(thing: unknown): thing is Feature;
+/**
+ * Recover the underlying feature from a jexlFeatureProxy, or return a raw
+ * feature untouched. Needed by callers that want the feature's methods
+ * (`id()`, `parent()`) rather than the data value the proxy resolves a
+ * property to.
+ */
+export declare function unwrapFeature(feature: Feature & MaybeProxiedFeature): Feature;
+/**
+ * Wrap a feature so jexl callbacks can read attributes as plain properties
+ * (`feature.score`) instead of `get(feature,'score')`. Since jexl has no
+ * member-call syntax, attributes resolve to values: any property (including
+ * `id`, i.e. a data field such as a GFF3 `ID=`) is forwarded to
+ * `feature.get(name)` where a SimpleFeature keeps its data. Exceptions:
+ * `parent` resolves to the parent feature (re-wrapped so `feature.parent.type`
+ * works), `uniqueId` to the feature's identity (`id()`) so it reads the same
+ * whether or not the feature happens to keep a uniqueId in its data, and
+ * `get`/`toJSON` stay callable methods so the legacy
+ * `get(feature,'x')`/`getTag(feature,'x')` forms and serialization still work.
+ * The `parent`/`id` jexl functions unwrap the proxy (see jexl.ts).
+ */
+export declare function jexlFeatureProxy(feature: Feature & MaybeProxiedFeature): Feature;
+/**
+ * Build the variable bindings a jexl callback evaluates against, wrapping any
+ * `Feature`-valued entry in `jexlFeatureProxy` (so `x.attr` reads directly while
+ * `get(x,'attr')` still works) and passing everything else through untouched.
+ *
+ * The single context-construction path shared by config-slot evaluation
+ * (`evaluateJexl`) and the filter chain (`SerializableFilterChain`), so which
+ * variables a callback can reference — and how a feature is exposed — never
+ * depends on which call site invoked it.
+ */
+export declare function buildJexlContext(args: Record<string, unknown>): Record<string, unknown>;
 export interface SimpleFeatureArgs {
+    /** key-value data, must include 'start' and 'end' */
     data: Record<string, unknown>;
+    /** optional parent feature */
     parent?: Feature;
+    /**
+     * unique identifier, stringified. the serialized form
+     * (SimpleFeatureSerialized) carries it as `uniqueId` instead
+     */
     id: string | number;
 }
 export interface SimpleFeatureSerializedNoId {
@@ -21,24 +86,67 @@ export interface SimpleFeatureSerializedNoId {
     end: number;
     refName: string;
     type?: string;
+    strand?: number;
+    name?: string;
+    id?: string | number;
+    uniqueId?: string;
+    __jbrowsefmt?: Record<string, unknown>;
+    mate?: {
+        refName: string;
+        start: number;
+        end: number;
+        [key: string]: unknown;
+    };
     subfeatures?: SimpleFeatureSerializedNoId[];
 }
 export interface SimpleFeatureSerialized extends SimpleFeatureSerializedNoId {
-    subfeatures?: SimpleFeatureSerializedNoId[];
     uniqueId: string;
 }
+/**
+ * Simple implementation of a feature object.
+ */
 export default class SimpleFeature implements Feature {
     private data;
     private subfeatures?;
     private parentHandle?;
     private uniqueId;
+    /**
+     * @param args - SimpleFeature args
+     *
+     * Note: args.data.subfeatures can be an array of these same args,
+     * which will be inflated to more instances of this class.
+     */
     constructor(args: SimpleFeatureArgs | SimpleFeatureSerialized);
-    get(name: string): any;
-    set(name: string, val: any): void;
+    private inflateSubfeatures;
+    /**
+     * Get a piece of data about the feature.  All features must have
+     * 'start' and 'end', but everything else is optional.
+     */
+    get(name: 'refName'): string;
+    get(name: 'name' | 'type' | 'id' | 'source'): string | undefined;
+    get(name: 'start' | 'end'): number;
+    get(name: 'phase'): 0 | 1 | 2 | undefined;
+    get(name: 'strand'): -1 | 0 | 1 | undefined;
+    get(name: 'score'): number | undefined;
+    get(name: 'subfeatures'): Feature[] | undefined;
+    get(name: string): unknown;
+    /**
+     * Get an array listing which data keys are present in this feature.
+     */
     tags(): string[];
+    /**
+     * Get the unique ID of this feature.
+     */
     id(): string;
+    /**
+     * Get this feature's parent feature, or undefined if none.
+     */
     parent(): Feature | undefined;
+    /**
+     * Get an array of child features, or undefined if none.
+     */
     children(): Feature[] | undefined;
     toJSON(): SimpleFeatureSerialized;
     static fromJSON(json: SimpleFeatureSerialized): SimpleFeature;
 }
+export {};