@jbrowse/product-core 4.3.0 → 5.0.0-beta.10

package/esm/sessionUrl.js

@@ -0,0 +1,66 @@
+import { ENCODED_PREFIX, JSON_PREFIX, fromUrlSafeB64, toUrlSafeB64, } from '@jbrowse/core/util';
+import { getShareableSessionSnapshot } from './Session/shareableSnapshot.js';
+/**
+ * Serialize a live session into a compact, URL-safe string for a query param or
+ * hash fragment. Deflated then base64url-encoded, so it survives a URL intact
+ * and stays far smaller than raw JSON.
+ *
+ * Not a plain `getSnapshot`: a workspace arrangement turned on by the sender's
+ * preference is not in the snapshot, so a raw one renders as a classic stack
+ * for whoever opens the link. `getShareableSessionSnapshot` stamps it first.
+ *
+ * The session travels but the config does not — the receiving app supplies its
+ * own assembly/tracks. Put the result somewhere the server never sees (the hash
+ * fragment) if it may be long: a query string can exceed the request-line limit
+ * and get a 414, which is why jbrowse-web moved its own there.
+ *
+ * Carries `ENCODED_PREFIX`, the same `?session=encoded-…` value jbrowse-web's
+ * SessionLoader decodes, so a link built by an embedded product opens in
+ * jbrowse.org/jb2 and vice versa. The format is `encodeSessionParam`'s `long`
+ * mode; sessionUrl.test.ts asserts the two stay byte-identical.
+ */
+export async function encodeSessionToUrl(session) {
+    const snap = getShareableSessionSnapshot(session);
+    return `${ENCODED_PREFIX}${await toUrlSafeB64(JSON.stringify(snap))}`;
+}
+function isSessionSnapshot(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        'name' in value &&
+        typeof value.name === 'string');
+}
+// A clipped `json-` link still parses up to the cut, so without this the
+// recipient reads JSON.parse's "Unterminated string in JSON at position 813"
+function parseJsonParam(json) {
+    try {
+        return JSON.parse(json)?.session;
+    }
+    catch (e) {
+        throw new Error("This link's session JSON is incomplete, which is how a link cut short in transit arrives. A short link survives being sent where a long one may not.", { cause: e });
+    }
+}
+async function parseEncodedParam(value) {
+    return JSON.parse(await fromUrlSafeB64(value.startsWith(ENCODED_PREFIX)
+        ? value.slice(ENCODED_PREFIX.length)
+        : value));
+}
+/**
+ * Inverse of {@link encodeSessionToUrl}, and of the `json-` form jbrowse-web's
+ * share dialog writes. Accepts an `encoded-` value with or without its prefix,
+ * so a raw `?session=` value from either app passes straight through.
+ *
+ * Throws on anything that isn't a decodable session — a truncated link, or a
+ * `share-`/`spec-` param an embedded product doesn't handle — so a host can
+ * fall back to its own declarative launch state instead of opening a
+ * half-built session.
+ */
+export async function decodeSessionFromUrl(value) {
+    const parsed = value.startsWith(JSON_PREFIX)
+        ? parseJsonParam(value.slice(JSON_PREFIX.length))
+        : await parseEncodedParam(value);
+    if (!isSessionSnapshot(parsed)) {
+        throw new Error('not a session snapshot: no "name"');
+    }
+    return parsed;
+}

package/esm/sessionUtils.d.ts

@@ -0,0 +1,74 @@
+import type { HydratedForms } from './Session/hydratedForms.ts';
+import type { PluginDefinition } from '@jbrowse/core/pluginDefinitions';
+import type { IAnyStateTreeNode, IAnyType } from '@jbrowse/mobx-state-tree';
+export interface DroppedSessionNode {
+    type?: string;
+    configuration?: string;
+}
+export declare function filterSessionInPlace(node: IAnyStateTreeNode, type: IAnyType, dropped?: DroppedSessionNode[]): DroppedSessionNode[];
+export interface NonPortableLocation {
+    locationType: string;
+    name: string;
+    trackId?: string;
+    trackName?: string;
+}
+export interface WebPortabilityReport {
+    nonPortable: NonPortableLocation[];
+    portable: boolean;
+}
+export declare function analyzeWebPortability(snapshot: unknown): WebPortabilityReport;
+export interface TrackSnapshot {
+    trackId: string;
+    [key: string]: unknown;
+}
+export interface WebExportInput {
+    assemblies?: AssemblySnapshot[];
+    tracks?: TrackSnapshot[];
+    plugins?: PluginDefinition[];
+    connections?: unknown[];
+    configuration?: {
+        sourceConfigUrl?: string;
+        webExportUrl?: string;
+    };
+    defaultSession?: Record<string, unknown>;
+}
+export interface AssemblySnapshot {
+    name: string;
+    [key: string]: unknown;
+}
+export interface HostedBaseConfig {
+    assemblies?: AssemblySnapshot[];
+    tracks?: TrackSnapshot[];
+    internetAccounts?: {
+        internetAccountId?: string;
+    }[];
+    plugins?: PluginDefinition[];
+    connections?: unknown[];
+    configuration?: {
+        shareURL?: string;
+    };
+    [key: string]: unknown;
+}
+export interface HostedBase {
+    config: HostedBaseConfig;
+    forms: HydratedForms;
+}
+export interface WebExportPlan {
+    strategy: 'hostedConfigBase' | 'selfContained';
+    configUrl?: string;
+    webBaseUrl: string;
+    session: Record<string, unknown>;
+    droppedTracks: string[];
+    blockingFiles: string[];
+    selfContainedReason?: SelfContainedReason;
+    droppedTextIndexes: string[];
+    revertedAssemblies: string[];
+    unavailableAccounts: string[];
+}
+export type SelfContainedReason = 'noSourceConfig' | 'baseUnreachable' | 'assembliesNotInBase';
+export declare function planWebExport(snapshot: WebExportInput, base?: HostedBase): WebExportPlan;
+export declare const DEFAULT_WEB_BASE_URL = "https://jbrowse.org/code/jb2/latest/";
+export declare function buildWebExportUrl(plan: Pick<WebExportPlan, 'webBaseUrl' | 'configUrl'>, sessionParam: string, options?: {
+    password?: string;
+    exportedFrom?: string;
+}): string;