@jbrowse/core 4.3.0 → 5.0.0-beta.10

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,40 @@
+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}
+ *
+ * A truncated input rejects rather than inflating to a prefix: a link cut short
+ * in transit has to say so, not fail later as a JSON syntax error.
+ */
+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 for a session carried by or behind the link.
+ * The decoder half (jbrowse-web's SessionLoader) has its own list covering
+ * `spec-` and `local-` too.
+ */
+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';
+export interface EncodedSessionParam {
+    sessionParam: string;
+    password?: 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);
+}
+async function transformBytes(bytes, transform) {
+    const stream = new Response(bytes).body.pipeThrough(transform);
+    return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+/**
+ * Decode and inflate a url-safe base64 to a string
+ * See {@link https://en.wikipedia.org/wiki/Base64#URL_applications}
+ *
+ * A truncated input rejects rather than inflating to a prefix: a link cut short
+ * in transit has to say so, not fail later as a JSON syntax error.
+ */
+export async function fromUrlSafeB64(b64) {
+    try {
+        const bytes = Uint8Array.from(atob(b64PadSuffix(b64.replaceAll('-', '+').replaceAll('_', '/'))), c => c.charCodeAt(0));
+        return new TextDecoder().decode(await transformBytes(bytes, new DecompressionStream('deflate')));
+    }
+    catch (e) {
+        throw new Error('This session is incomplete or damaged, which is how a link cut short in transit arrives. A short link survives being sent where a long one may not.', { cause: e });
+    }
+}
+/**
+ * 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 deflated = await transformBytes(new TextEncoder().encode(str), new CompressionStream('deflate'));
+    const encoded = btoa(bytesToBinaryString(deflated)).replace(/=+$/, '');
+    return encoded.replaceAll('+', '-').replaceAll('/', '_');
+}
+/**
+ * The `?session=` value prefixes for a session carried by or behind the link.
+ * The decoder half (jbrowse-web's SessionLoader) has its own list covering
+ * `spec-` and `local-` too.
+ */
+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) or `encoded-<b64>` (compressed 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. The decoder also reads `json-{"session":…}`, which nothing here
+// writes: it is the form a person writes by hand.
+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 {
+        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/shapeNameList.d.ts

@@ -0,0 +1,2 @@
+/** The shape names in range order: what an unlisted `range` hands out. */
+export declare const SHAPE_NAMES: ('circle' | 'triangle-down' | 'diamond')[];

package/esm/util/shapeNameList.js

@@ -0,0 +1,6 @@
+/** The shape names in range order: what an unlisted `range` hands out. */
+export const SHAPE_NAMES = [
+    'circle',
+    'triangle-down',
+    'diamond',
+];

package/esm/util/shapeNames.d.ts

@@ -0,0 +1,7 @@
+import type { ShapeName } from './markEncodingTypes.ts';
+/**
+ * #api
+ * The `point` mark's painter code for each shape an encoding can name.
+ */
+export declare const SHAPE_CODES: Record<ShapeName, number>;
+export { SHAPE_NAMES } from './shapeNameList.ts';

package/esm/util/shapeNames.js

@@ -0,0 +1,11 @@
+import { GLYPH_DIAMOND, GLYPH_DISC, GLYPH_TRIANGLE, } from '@jbrowse/render-core/shaders/pointMarkConsts';
+/**
+ * #api
+ * The `point` mark's painter code for each shape an encoding can name.
+ */
+export const SHAPE_CODES = {
+    circle: GLYPH_DISC,
+    'triangle-down': GLYPH_TRIANGLE,
+    diamond: GLYPH_DIAMOND,
+};
+export { SHAPE_NAMES } from './shapeNameList.js';

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,66 @@ export interface SimpleFeatureSerializedNoId {
     end: number;
     refName: string;
     type?: string;
+    strand?: number;
+    name?: string;
+    id?: string | number;
+    uniqueId?: string;
+    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 {};