@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/locString.js

@@ -1,57 +1,89 @@
-const COORD_REGEX = /^(-?\d+)(?:(?:\.\.|[-–])(-?\d+))?(\.\.|[-–])?$/;
+import { BP_QUANTITY_SOURCE, parseBpString } from './bpUtils.js';
+import { toLocale } from './numericUtils.js';
+import { shorten } from './stringUtils.js';
+// Thrown when the input doesn't resolve to any known refName. Callers
+// (e.g. the LGV locstring path) catch this to fall back to alternative
+// interpretations like "refname start end" triplets — string-matching
+// the error message would be brittle.
+export class UnknownRefNameError extends Error {
+    name = 'UnknownRefNameError';
+}
+// matches coordinate strings: "100", "100-200", "100..200", "100.." (open-ended).
+// Each coordinate may carry a metric unit suffix, so "34M-35M" and "1.5kb..2kb"
+// parse too; the numbers are converted eagerly here and nothing downstream ever
+// sees the shorthand. Assembled locStrings are always plain digits, so this is
+// a spelling the parser accepts and the formatter never emits.
+// groups: [1]=start [2]=end (if range) [3]=trailing separator (if open-ended)
+const COORD_REGEX = new RegExp(String.raw `^(${BP_QUANTITY_SOURCE})(?:(?:\.\.|[-–])(${BP_QUANTITY_SOURCE}))?(\.\.|[-–])?$`, 'i');
+// matches optional "{assemblyName}" prefix followed by the rest of the location
+// groups: [1]=assemblyName (without braces) [2]=remainder
 const ASSEMBLY_REGEX = /^(?:\{([^}]+)\})?(.+)/;
 function parseCoords(suffix, locString) {
+    // strip commas before matching so regex only needs to handle plain digits
     const match = COORD_REGEX.exec(suffix.replaceAll(',', ''));
-    if (!match) {
+    const [, startStr, endStr, trailing] = match ?? [];
+    const start = startStr === undefined ? undefined : parseBpString(startStr);
+    if (start === undefined) {
         throw new Error(`could not parse range "${suffix}" on location "${locString}"`);
     }
-    const [, startStr, endStr, trailing] = match;
-    const start = +startStr;
-    return { start, end: endStr ? +endStr : trailing ? undefined : start };
+    return {
+        start,
+        end: endStr ? parseBpString(endStr) : trailing ? undefined : start,
+    };
 }
 export function parseLocStringOneBased(locString, isValidRefName) {
     if (!locString) {
         throw new Error('no location string provided, could not parse');
     }
+    // handle reverse strand notation e.g. "chr1:1-100[rev]"
     let reversed = false;
     if (locString.endsWith('[rev]')) {
         reversed = true;
         locString = locString.slice(0, -5);
     }
     locString = locString.replaceAll(/\s/g, '');
+    // extract optional assembly name in braces e.g. "{hg19}chr1:1-100"
     const assemblyMatch = ASSEMBLY_REGEX.exec(locString);
     if (!assemblyMatch) {
         throw new Error(`invalid location string: "${locString}"`);
     }
     const [, assemblyName, location] = assemblyMatch;
+    // reject empty braces e.g. "{}chr1:1-100"
     if (!assemblyName && location.startsWith('{}')) {
         throw new Error(`no assembly name was provided in location "${location}"`);
     }
+    // refNames can contain colons (see SAM spec), so find the last colon to split
     const lastColonIdx = location.lastIndexOf(':');
+    // no colon means just a refName with no coordinates e.g. "chr1"
     if (lastColonIdx === -1) {
         if (isValidRefName(location, assemblyName)) {
             return { assemblyName, refName: location, reversed };
         }
-        throw new Error(`Unknown feature or sequence "${location}"`);
+        throw new UnknownRefNameError(`Unknown feature or sequence "${location}"`);
     }
+    // split into refName (prefix) and coordinate part (suffix) at the last colon
     const prefix = location.slice(0, lastColonIdx);
     const suffix = location.slice(lastColonIdx + 1);
     const prefixValid = isValidRefName(prefix, assemblyName);
     const locationValid = isValidRefName(location, assemblyName);
+    // both interpretations valid is ambiguous e.g. refName "chr1:1" and "chr1" both exist
     if (prefixValid && locationValid) {
         throw new Error(`ambiguous location string: "${locString}"`);
     }
+    // the colon is part of the refName, not a coordinate separator
     if (locationValid) {
         return { assemblyName, refName: location, reversed };
     }
+    // standard case: prefix is refName, suffix is coordinates
     if (prefixValid) {
+        // colon with no suffix means just refName e.g. "chr1:"
         if (!suffix) {
             return { assemblyName, refName: prefix, reversed };
         }
         const coords = parseCoords(suffix, locString);
         return { assemblyName, refName: prefix, reversed, ...coords };
     }
-    throw new Error(`unknown reference sequence name in location "${locString}"`);
+    throw new UnknownRefNameError(`unknown reference sequence name in location "${locString}"`);
 }
 export function parseLocString(locString, isValidRefName) {
     const parsed = parseLocStringOneBased(locString, isValidRefName);
@@ -60,3 +92,142 @@ export function parseLocString(locString, isValidRefName) {
     }
     return parsed;
 }
+/**
+ * Assemble a 1-based "locString" from an interbase genomic location
+ * @param region - Region
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0, end: 100 })
+ * // ↳ 'chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ assemblyName: 'hg19', refName: 'chr1', start: 0, end: 100 })
+ * // ↳ '{hg19}chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1' })
+ * // ↳ 'chr1'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0 })
+ * // ↳ 'chr1:1..'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', end: 100 })
+ * // ↳ 'chr1:1..100'
+ * ```
+ * @example
+ * ```ts
+ * assembleLocString({ refName: 'chr1', start: 0, end: 1 })
+ * // ↳ 'chr1:1'
+ * ```
+ */
+export function assembleLocString(region) {
+    return assembleLocStringWith(region, toLocale);
+}
+/**
+ * Same as {@link assembleLocString}, but with the coordinates left unformatted:
+ * no thousand separators, and never affected by the `numberGrouping` display
+ * preference. Use this wherever the result is compared, keyed on, or parsed
+ * rather than read — block keys, dedup buckets, locStrings handed back to
+ * `parseLocString` — both because it is faster (block calculations assemble a
+ * great many of these) and because a display convention shifting under an
+ * identity string is a correctness bug, not a cosmetic one.
+ */
+export function assembleLocStringRaw(region) {
+    return assembleLocStringWith(region);
+}
+/**
+ * One space-separated string for a set of regions — what the header of a
+ * multi-region view says it is showing, and what an export of those regions
+ * labels itself with.
+ *
+ * The assembly name appears only when the regions disagree about it: naming it
+ * on every one of a dozen same-assembly blocks is noise, and dropping it where
+ * they differ loses the only thing telling them apart.
+ */
+export function assembleLocStrings(regions) {
+    const sameAssembly = regions.every(r => r.assemblyName === regions[0].assemblyName);
+    return regions
+        .map(r => assembleLocString({
+        ...r,
+        assemblyName: sameAssembly ? undefined : r.assemblyName,
+    }))
+        .join(' ');
+}
+function assembleLocStringWith(region, cb = (n) => n) {
+    const { assemblyName, refName, start, end, reversed } = region;
+    const assemblyNameString = assemblyName ? `{${assemblyName}}` : '';
+    let startString;
+    if (start !== undefined) {
+        startString = `:${cb(start + 1)}`;
+    }
+    else if (end !== undefined) {
+        startString = ':1';
+    }
+    else {
+        startString = '';
+    }
+    let endString;
+    if (end !== undefined) {
+        endString = start !== undefined && start + 1 === end ? '' : `..${cb(end)}`;
+    }
+    else {
+        endString = start !== undefined ? '..' : '';
+    }
+    let rev = '';
+    if (reversed) {
+        rev = '[rev]';
+    }
+    return `${assemblyNameString}${refName}${startString}${endString}${rev}`;
+}
+export function compareLocs(locA, locB) {
+    const assemblyComp = locA.assemblyName || locB.assemblyName
+        ? (locA.assemblyName || '').localeCompare(locB.assemblyName || '')
+        : 0;
+    if (assemblyComp) {
+        return assemblyComp;
+    }
+    const refComp = locA.refName || locB.refName
+        ? (locA.refName || '').localeCompare(locB.refName || '')
+        : 0;
+    if (refComp) {
+        return refComp;
+    }
+    if (locA.start !== undefined && locB.start !== undefined) {
+        const startComp = locA.start - locB.start;
+        if (startComp) {
+            return startComp;
+        }
+    }
+    if (locA.end !== undefined && locB.end !== undefined) {
+        const endComp = locA.end - locB.end;
+        if (endComp) {
+            return endComp;
+        }
+    }
+    return 0;
+}
+export function compareLocStrings(a, b, isValidRefName) {
+    const locA = parseLocString(a, isValidRefName);
+    const locB = parseLocString(b, isValidRefName);
+    return compareLocs(locA, locB);
+}
+/**
+ * A cursor/coordinate readout: `{assembly}chr1:1,234`, with the refName
+ * shortened and the coordinate locale-grouped. The *display* counterpart to
+ * {@link assembleLocString} — this one is for showing a single position to a
+ * user, never for a location string that will be parsed back.
+ */
+export function stringify({ refName, coord, assemblyName, oob, }, useAssemblyName) {
+    return [
+        assemblyName && useAssemblyName ? `{${assemblyName}}` : '',
+        refName
+            ? `${shorten(refName)}:${toLocale(coord)}${oob ? ' (out of bounds)' : ''}`
+            : '',
+    ].join('');
+}

package/esm/util/locStringsToRegions.d.ts

@@ -0,0 +1,10 @@
+import type { Region } from './types/data.ts';
+export interface RefNameSource {
+    isValidRefName: (refName: string) => boolean;
+    getCanonicalRefName2: (refName: string) => string;
+    regions?: readonly {
+        refName: string;
+        end: number;
+    }[];
+}
+export declare function locStringsToRegions(locStrings: string, assembly: RefNameSource, assemblyName: string): Region[];

package/esm/util/locStringsToRegions.js

@@ -0,0 +1,35 @@
+import { parseLocString } from './locString.js';
+// Parses locstrings a user wrote -- into a dialog's region field, or into a
+// display's `clusterRegion` in a session -- to the regions a fetch runs over.
+// Throws on an unparsable ref name or an empty range, so a caller surfaces the
+// typo rather than quietly running over something else. Whitespace separates
+// regions, so a multi-region rubberband selection round-trips through a field,
+// and a setting can name more than one locus.
+//
+// A bare refName means the whole contig, so its length is required, not a
+// fallback: defaulting a missing length to 0 turned "this contig has no length
+// on record" into "empty region", which reads as the user having typed a bad
+// range.
+export function locStringsToRegions(locStrings, assembly, assemblyName) {
+    return locStrings
+        .trim()
+        .split(/\s+/)
+        .map(locString => {
+        const parsed = parseLocString(locString, refName => assembly.isValidRefName(refName));
+        const refName = assembly.getCanonicalRefName2(parsed.refName);
+        // scans rather than calling the assembly's getRegionForRefName, because
+        // `RefNameSource` is a narrow duck type several fakes satisfy — growing it
+        // a method to save a scan over a list this reads once per typed locstring
+        // is the wrong trade
+        const refLength = assembly.regions?.find(r => r.refName === refName)?.end;
+        if (refLength === undefined) {
+            throw new Error(`no length on record for "${refName}"`);
+        }
+        const start = Math.max(parsed.start ?? 0, 0);
+        const end = Math.min(parsed.end ?? refLength, refLength);
+        if (end <= start) {
+            throw new Error(`empty region: "${locString}"`);
+        }
+        return { assemblyName, refName, start, end };
+    });
+}

package/esm/util/localStorage.d.ts

@@ -0,0 +1,36 @@
+export declare const localStorageAvailable: () => boolean, localStorageGetItem: (key: string) => string | undefined, localStorageSetItem: (key: string, value: string) => boolean, localStorageRemoveItem: (key: string) => boolean;
+/**
+ * Call `fn` whenever `key` changes — in another tab, or here via
+ * {@link notifyLocalStorageKey}. Returns the unsubscribe.
+ *
+ * `fn` takes no argument on purpose: it is told that the key changed, and reads
+ * the store itself. A payload would be a second copy of the value, and a
+ * `clear()` has none to hand over.
+ */
+export declare function subscribeToLocalStorageKey(key: string, fn: () => void): () => void;
+/** Announce a write made in this tab, which `storage` never reports back. */
+export declare function notifyLocalStorageKey(key: string): void;
+export declare function localStorageGetNumber(key: string, defaultVal: number): number;
+export declare function localStorageGetJSON<T>(key: string, defaultVal: T): T;
+/**
+ * The list of strings at `key` — absent, unreadable, malformed, or holding
+ * anything else all read as empty.
+ *
+ * The element filter is the part {@link localStorageGetJSON} cannot do: a
+ * stored array of the wrong element type parses fine and then behaves as a list
+ * of values that match nothing, which looks the same as an empty list except
+ * that it is never noticed. Three keys wanted exactly this and each spelled it
+ * out — hidden facet columns, trusted plugin URLs, and the desktop safe-mode
+ * marker, which additionally has to survive the bare `1` older builds wrote
+ * there.
+ */
+export declare function localStorageGetStringArray(key: string): string[];
+/**
+ * Writes `val` as JSON, except when it is null/undefined — those are skipped
+ * rather than stored, so a tri-state setting whose "unset" value means "follow
+ * the config" leaves whatever was there instead of pinning `null` over it.
+ */
+export declare function localStorageSetJSON(key: string, val: unknown): void;
+export declare function localStorageGetBoolean(key: string, defaultVal: boolean): boolean;
+export declare function localStorageSetBoolean(key: string, value: boolean): void;
+export declare function localStorageSetNumber(key: string, value: number): void;

package/esm/util/localStorage.js

@@ -0,0 +1,137 @@
+// localStorage: the guarded primitives from webStorage.ts (read that file for
+// the three ways a Web Storage store fails and why every accessor here is
+// total), plus the typed reads and the key subscription, which only this store
+// has callers for.
+import { guardedLocalStorage } from './webStorage.js';
+export const { available: localStorageAvailable, getItem: localStorageGetItem, setItem: localStorageSetItem, removeItem: localStorageRemoveItem, } = guardedLocalStorage;
+// Watchers of a key, and the one `storage` listener they share.
+//
+// Two different events reach them, which is why this is not simply a `storage`
+// listener at each call site. Another TAB writing the key raises `storage` —
+// but never in the tab that wrote it, so a write from THIS tab reaches nobody
+// and has to be announced by hand. Missing that half is what let two components
+// on one key show different values until one of them remounted.
+//
+// Announcing is deliberately not folded into localStorageSetItem. A writer
+// that persists from an autorun over its own state would, if its write called
+// its own subscriber back, re-enter that autorun and write again, forever. A
+// writer says when its write is news.
+const listeners = new Map();
+// Installed on the first subscription rather than at module scope, so importing
+// this file from a worker or a test never touches `window`.
+let storageListenerInstalled = false;
+function installStorageListener() {
+    if (storageListenerInstalled || typeof window === 'undefined') {
+        return;
+    }
+    storageListenerInstalled = true;
+    window.addEventListener('storage', e => {
+        // sessionStorage raises the same event on the same window, and jbrowse-web
+        // mirrors whole sessions into it
+        if (e.storageArea !== window.localStorage) {
+            return;
+        }
+        if (e.key === null) {
+            // a clear(): a factory reset, a test's teardown. Every key at once
+            for (const k of [...listeners.keys()]) {
+                notifyLocalStorageKey(k);
+            }
+        }
+        else if (listeners.has(e.key)) {
+            notifyLocalStorageKey(e.key);
+        }
+    });
+}
+/**
+ * Call `fn` whenever `key` changes — in another tab, or here via
+ * {@link notifyLocalStorageKey}. Returns the unsubscribe.
+ *
+ * `fn` takes no argument on purpose: it is told that the key changed, and reads
+ * the store itself. A payload would be a second copy of the value, and a
+ * `clear()` has none to hand over.
+ */
+export function subscribeToLocalStorageKey(key, fn) {
+    installStorageListener();
+    let set = listeners.get(key);
+    if (!set) {
+        set = new Set();
+        listeners.set(key, set);
+    }
+    set.add(fn);
+    return () => {
+        set.delete(fn);
+        if (!set.size) {
+            listeners.delete(key);
+        }
+    };
+}
+/** Announce a write made in this tab, which `storage` never reports back. */
+export function notifyLocalStorageKey(key) {
+    for (const fn of listeners.get(key) ?? []) {
+        fn();
+    }
+}
+export function localStorageGetNumber(key, defaultVal) {
+    const stored = localStorageGetItem(key);
+    // rejected before the coercion rather than after it: `+''` is 0, so an entry
+    // written as the empty string would otherwise read back as a real 0 instead
+    // of falling back. isFinite rather than !isNaN so 'Infinity' falls back too —
+    // every one of these is a pixel width or a base-pair count.
+    if (!stored) {
+        return defaultVal;
+    }
+    const parsed = +stored;
+    return Number.isFinite(parsed) ? parsed : defaultVal;
+}
+export function localStorageGetJSON(key, defaultVal) {
+    const stored = localStorageGetItem(key);
+    if (stored) {
+        try {
+            return JSON.parse(stored);
+        }
+        catch (e) {
+            console.warn(`Invalid localStorage value for ${key}:`, stored, e);
+        }
+    }
+    return defaultVal;
+}
+/**
+ * The list of strings at `key` — absent, unreadable, malformed, or holding
+ * anything else all read as empty.
+ *
+ * The element filter is the part {@link localStorageGetJSON} cannot do: a
+ * stored array of the wrong element type parses fine and then behaves as a list
+ * of values that match nothing, which looks the same as an empty list except
+ * that it is never noticed. Three keys wanted exactly this and each spelled it
+ * out — hidden facet columns, trusted plugin URLs, and the desktop safe-mode
+ * marker, which additionally has to survive the bare `1` older builds wrote
+ * there.
+ */
+export function localStorageGetStringArray(key) {
+    const parsed = localStorageGetJSON(key, []);
+    return Array.isArray(parsed) ? parsed.filter(x => typeof x === 'string') : [];
+}
+/**
+ * Writes `val` as JSON, except when it is null/undefined — those are skipped
+ * rather than stored, so a tri-state setting whose "unset" value means "follow
+ * the config" leaves whatever was there instead of pinning `null` over it.
+ */
+export function localStorageSetJSON(key, val) {
+    if (val !== undefined && val !== null) {
+        localStorageSetItem(key, JSON.stringify(val));
+    }
+}
+export function localStorageGetBoolean(key, defaultVal) {
+    const stored = localStorageGetJSON(key, defaultVal);
+    // falls back rather than coercing when the key holds something that is not a
+    // boolean (an older build's format, a hand-edited value). `Boolean(null)` is
+    // false, which would silently override a `true` default — which is what most
+    // of these are.
+    return typeof stored === 'boolean' ? stored : defaultVal;
+}
+export function localStorageSetBoolean(key, value) {
+    localStorageSetItem(key, JSON.stringify(value));
+}
+export function localStorageSetNumber(key, value) {
+    localStorageSetItem(key, JSON.stringify(value));
+}

package/esm/util/makeAssembly.d.ts

@@ -0,0 +1,54 @@
+export interface MakeAssemblyOptions {
+    /** URL to a FASTA (`.fa`/`.fasta`, optionally bgzipped) or a `.2bit` file */
+    fastaUri: string;
+    /** defaults to the file's base name, e.g. `hg38.fa.gz` -> `hg38` */
+    name?: string;
+    faiUri?: string;
+    gziUri?: string;
+    aliases?: string[];
+    refNameAliasesUri?: string;
+}
+/** true when a string names a sequence file (vs. a hub name like `hg38`) */
+export declare function isSequenceUri(uri: string): boolean;
+/** strip path and sequence extension: `.../hg19.fa.gz` -> `hg19` */
+export declare function assemblyNameFromUri(uri: string): string;
+/**
+ * Build an assembly config for a sequence file (indexed FASTA, bgzipped FASTA,
+ * or `.2bit`) — the boilerplate you'd otherwise write by hand. In the common
+ * case it is the flat `{ name, uri }` shorthand: jbrowse-core's assembly config
+ * picks the concrete adapter type (`IndexedFastaAdapter`/`BgzipFastaAdapter`/
+ * `TwoBitAdapter`) from the extension, derives the `.fai`/`.gzi` siblings, and
+ * fills in the `ReferenceSequenceTrack` at load time, so no adapter-type
+ * knowledge lives here. A non-sibling index (`faiUri`/`gziUri`) widens `sequence`
+ * to its adapter form, the only shape with a slot for the override.
+ * `refNameAliasesUri` points at a tab-separated aliases file (as UCSC publishes)
+ * so a track whose reference names differ from the sequence (e.g. a BAM using
+ * `chr1` against a `1`-named reference) still lines up.
+ */
+export declare function makeAssembly(opts: MakeAssemblyOptions): {
+    name: string;
+    aliases: string[];
+    sequence: {
+        type: string;
+        trackId: string;
+        adapter: {
+            uri: string;
+            faiLocation?: {
+                uri: string;
+            } | undefined;
+            gziLocation?: {
+                uri: string;
+            } | undefined;
+        };
+    };
+    refNameAliases?: {
+        uri: string;
+    } | undefined;
+} | {
+    name: string;
+    aliases: string[];
+    uri: string;
+    refNameAliases?: {
+        uri: string;
+    } | undefined;
+};

package/esm/util/makeAssembly.js

@@ -0,0 +1,52 @@
+// sequence extensions core's own guesser recognizes (plugins/sequence)
+const SEQUENCE_EXT_RE = /\.(fa|fasta|fas|fna|mfa|2bit)(\.b?gz)?$/i;
+function cleanUri(uri) {
+    return uri.split(/[?#]/)[0] ?? uri;
+}
+/** true when a string names a sequence file (vs. a hub name like `hg38`) */
+export function isSequenceUri(uri) {
+    return SEQUENCE_EXT_RE.test(cleanUri(uri));
+}
+/** strip path and sequence extension: `.../hg19.fa.gz` -> `hg19` */
+export function assemblyNameFromUri(uri) {
+    const file = cleanUri(uri).split('/').at(-1) ?? uri;
+    return file.replace(SEQUENCE_EXT_RE, '');
+}
+/**
+ * Build an assembly config for a sequence file (indexed FASTA, bgzipped FASTA,
+ * or `.2bit`) — the boilerplate you'd otherwise write by hand. In the common
+ * case it is the flat `{ name, uri }` shorthand: jbrowse-core's assembly config
+ * picks the concrete adapter type (`IndexedFastaAdapter`/`BgzipFastaAdapter`/
+ * `TwoBitAdapter`) from the extension, derives the `.fai`/`.gzi` siblings, and
+ * fills in the `ReferenceSequenceTrack` at load time, so no adapter-type
+ * knowledge lives here. A non-sibling index (`faiUri`/`gziUri`) widens `sequence`
+ * to its adapter form, the only shape with a slot for the override.
+ * `refNameAliasesUri` points at a tab-separated aliases file (as UCSC publishes)
+ * so a track whose reference names differ from the sequence (e.g. a BAM using
+ * `chr1` against a `1`-named reference) still lines up.
+ */
+export function makeAssembly(opts) {
+    const { fastaUri, name = assemblyNameFromUri(fastaUri), faiUri, gziUri, aliases = [], refNameAliasesUri, } = opts;
+    return {
+        name,
+        aliases,
+        // flat { name, uri } shorthand; a non-sibling index has no home there, so it
+        // widens to the sequence.adapter form (the bare uri still infers the type)
+        ...(faiUri || gziUri
+            ? {
+                sequence: {
+                    type: 'ReferenceSequenceTrack',
+                    trackId: `${name}-ReferenceSequenceTrack`,
+                    adapter: {
+                        uri: fastaUri,
+                        ...(faiUri ? { faiLocation: { uri: faiUri } } : {}),
+                        ...(gziUri ? { gziLocation: { uri: gziUri } } : {}),
+                    },
+                },
+            }
+            : { uri: fastaUri }),
+        ...(refNameAliasesUri
+            ? { refNameAliases: { uri: refNameAliasesUri } }
+            : {}),
+    };
+}

package/esm/util/makeTrackId.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build a track id from a track name, shared by the add-track workflows so the
+ * slug rule lives in one place. `timestamp` defaults to now but can be pinned so
+ * a batch of tracks shares it; `index` then disambiguates ids within that batch
+ * when several files share a name. Admin-vs-session is not encoded in the id —
+ * it follows from where the session stores the track (`sessionTracks` vs the
+ * base config), which is also what drives the selector's "Session tracks" group
+ * (see generateHierarchy).
+ */
+export declare function makeTrackId({ name, timestamp, index, }: {
+    name: string;
+    timestamp?: number;
+    index?: number;
+}): string;

package/esm/util/makeTrackId.js

@@ -0,0 +1,14 @@
+/**
+ * Build a track id from a track name, shared by the add-track workflows so the
+ * slug rule lives in one place. `timestamp` defaults to now but can be pinned so
+ * a batch of tracks shares it; `index` then disambiguates ids within that batch
+ * when several files share a name. Admin-vs-session is not encoded in the id —
+ * it follows from where the session stores the track (`sessionTracks` vs the
+ * base config), which is also what drives the selector's "Session tracks" group
+ * (see generateHierarchy).
+ */
+export function makeTrackId({ name, timestamp = Date.now(), index, }) {
+    const slug = name.trim().toLowerCase().replaceAll(' ', '_');
+    const suffix = index === undefined ? '' : `-${index}`;
+    return `${slug}-${timestamp}${suffix}`;
+}