@jbrowse/add-track-core 5.0.0-beta.1 → 5.0.0-beta.11

package/README.md

@@ -21,6 +21,12 @@ plugins loaded rather than from a list somebody has to remember to edit. A
 format the table cannot express is still added the old way, with
 `addAdapterGuesser` — those run later in the chain and win.
 
+`indexCandidates.ts` beside the table holds the other filename question both
+sides ask: the names an index file might be under — htslib's `.csi`, Picard and
+GATK's `reads.bai` beside `reads.bam`. Core probes those candidates over the
+network in `detectIndexLocation`, the CLI with `existsSync` in `siblingSidecar`,
+and neither spells the list itself.
+
 `products/jbrowse-web/src/addTrackFormats.test.ts` is the check over all of it:
 one filename per entry, compared between the app's guesser chain and the CLI.
 

package/esm/formats.d.ts

@@ -60,6 +60,12 @@ export interface FormatEntry {
  * precede their plain counterparts.
  */
 export declare const formats: FormatEntry[];
+/**
+ * The bare filename the format table matches against — the same thing
+ * `@jbrowse/core`'s `getFileName` hands the guesser chain, so a path and a URL
+ * with a presigned query string both reduce to what the regexes expect.
+ */
+export declare function fileNameOf(location: string): string;
 /**
  * The format `fileName` is, or — when `adapterHint` names an adapter type — that
  * adapter's format whatever the filename says. A hint always wins, which is what
@@ -72,8 +78,3 @@ export declare function matchFormat(fileName: string, adapterHint?: string): For
  * adapter — a `.bedmethyl.gz` from a plain `.bed.gz` — so pass it when known.
  */
 export declare function trackTypeForAdapter(adapterType: string, fileName?: string): string | undefined;
-/**
- * The index spelling a location implies: htslib writes `.csi` in place of a
- * `.bai` or a `.tbi` for a reference over 512 Mb, and on request at any size.
- */
-export declare function resolveIndexType(indexName: string | undefined, fallback: 'BAI' | 'TBI'): "BAI" | "CSI" | "TBI";

package/esm/formats.js

@@ -153,6 +153,26 @@ export const formats = [
             indexType: 'TBI',
         },
     },
+    {
+        // `.bedGraph` is UCSC's own spelling and what bedGraphToBigWig is pointed
+        // at, so it turns up far more often than the `.bg` short form below
+        regex: /\.bedgraph\.b?gz$/i,
+        spec: {
+            kind: 'indexed',
+            adapterType: 'BedGraphTabixAdapter',
+            locField: 'bedGraphGzLocation',
+            suffix: '.tbi',
+            indexType: 'TBI',
+        },
+    },
+    {
+        regex: /\.bedgraph$/i,
+        spec: {
+            kind: 'single',
+            adapterType: 'BedGraphAdapter',
+            locField: 'bedGraphLocation',
+        },
+    },
     {
         regex: /\.bg\.b?gz$/i,
         spec: {
@@ -247,6 +267,18 @@ export const formats = [
             locField: 'twoBitLocation',
         },
     },
+    {
+        // the pattern `jbrowse add-assembly` has always inferred `--type
+        // chromSizes` from, so a file that names a genome on the command line names
+        // one in a config. The bare `.sizes` below stays refused: it is nobody's
+        // convention, and a genome with no sequence is too easy to reach by accident
+        regex: /\.chrom\.sizes$/i,
+        spec: {
+            kind: 'single',
+            adapterType: 'ChromSizesAdapter',
+            locField: 'chromSizesLocation',
+        },
+    },
     { regex: /\.sizes$/i, spec: { kind: 'unsupported' } },
     {
         regex: /trackData\.jsonz?$/i,
@@ -321,19 +353,19 @@ export const formats = [
         },
     },
     {
-        // an all-vs-all PAF looks like any `.paf`; the assembly list and the PanSN
+        // a multi-genome PAF looks like any `.paf`; the assembly list and the PanSN
         // mapping come from its add-track form
         spec: {
             kind: 'single',
-            adapterType: 'AllVsAllPAFAdapter',
+            adapterType: 'MultiGenomePAFAdapter',
             locField: 'pafLocation',
         },
     },
     {
-        // likewise an all-vs-all PIF against a pairwise one
+        // likewise a multi-genome PIF against a pairwise one
         spec: {
             kind: 'indexed',
-            adapterType: 'AllVsAllIndexedPAFAdapter',
+            adapterType: 'MultiGenomeIndexedPAFAdapter',
             locField: 'pifGzLocation',
             suffix: '.tbi',
             indexType: 'TBI',
@@ -354,6 +386,14 @@ export const formats = [
         },
     },
 ];
+/**
+ * The bare filename the format table matches against — the same thing
+ * `@jbrowse/core`'s `getFileName` hands the guesser chain, so a path and a URL
+ * with a presigned query string both reduce to what the regexes expect.
+ */
+export function fileNameOf(location) {
+    return (location.replaceAll('\\', '/').split('/').at(-1)?.split(/[?#]/)[0] ?? '');
+}
 function matchesRegex(fileName, regex) {
     return Array.isArray(regex)
         ? regex.every(r => r.test(fileName))
@@ -382,10 +422,3 @@ export function trackTypeForAdapter(adapterType, fileName) {
         ? entry.trackType
         : adapterTypesToTrackTypeMap[adapterType];
 }
-/**
- * The index spelling a location implies: htslib writes `.csi` in place of a
- * `.bai` or a `.tbi` for a reference over 512 Mb, and on request at any size.
- */
-export function resolveIndexType(indexName, fallback) {
-    return indexName?.toUpperCase().endsWith('CSI') ? 'CSI' : fallback;
-}

package/esm/index.d.ts

@@ -1,2 +1,4 @@
-export { type AdapterSpec, type FormatEntry, type Sidecar, formats, matchFormat, resolveIndexType, trackTypeForAdapter, } from './formats.ts';
+export { type AdapterSpec, type FormatEntry, type Sidecar, fileNameOf, formats, matchFormat, trackTypeForAdapter, } from './formats.ts';
+export { indexCandidateNames, indexSpellings, resolveIndexType, sidecarCandidateNames, } from './indexCandidates.ts';
+export { type LooseTrackInput, isLooseTrackConfig } from './looseTrackConfig.ts';
 export { adapterTypesToTrackTypeMap } from './trackTypes.generated.ts';

package/esm/index.js

@@ -1,2 +1,4 @@
-export { formats, matchFormat, resolveIndexType, trackTypeForAdapter, } from './formats.js';
+export { fileNameOf, formats, matchFormat, trackTypeForAdapter, } from './formats.js';
+export { indexCandidateNames, indexSpellings, resolveIndexType, sidecarCandidateNames, } from './indexCandidates.js';
+export { isLooseTrackConfig } from './looseTrackConfig.js';
 export { adapterTypesToTrackTypeMap } from './trackTypes.generated.js';

package/esm/indexCandidates.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Every conventional spelling of an index file, for the docs that describe this
+ * behavior — the prose form of the list {@link indexCandidateNames} builds.
+ */
+export declare const indexSpellings: {
+    name: string;
+    writtenBy: string;
+}[];
+/**
+ * The names a sidecar with this suffix might be under beside `location`, best
+ * guess first — the conventional one, then htslib's `.csi`, then the stripped
+ * form Picard and GATK write.
+ *
+ * The guard on the stripped spelling is load-bearing: `replace` hands back the
+ * subject unchanged when the pattern does not match, so a name carrying no
+ * extension at all would offer the data file as its own index.
+ */
+export declare function sidecarCandidateNames(location: string, suffix: string): [string, ...string[]];
+/**
+ * The index filenames worth looking for beside `fileName`, best guess first.
+ *
+ * One data file has several names its index might carry, and picking only the
+ * first left everyone else with a missing-file error naming a path they never
+ * wrote. Empty for a file type that carries no sibling index (BigWig, BigBed,
+ * hic), which is how a caller knows not to go looking.
+ */
+export declare function indexCandidateNames(fileName: string): string[];
+/**
+ * The index spelling a location implies: htslib writes `.csi` in place of a
+ * `.bai` or a `.tbi` for a reference over 512 Mb, and on request at any size.
+ */
+export declare function resolveIndexType(indexName: string | undefined, fallback: 'BAI' | 'TBI'): "BAI" | "CSI" | "TBI";

package/esm/indexCandidates.js

@@ -0,0 +1,71 @@
+/**
+ * Every conventional spelling of an index file, for the docs that describe this
+ * behavior — the prose form of the list {@link indexCandidateNames} builds.
+ */
+export const indexSpellings = [
+    {
+        name: '`<file>.tbi`, `<file>.bai`, `<file>.crai`',
+        writtenBy: 'samtools, tabix',
+    },
+    {
+        name: '`<file>.csi`',
+        writtenBy: 'htslib, for a reference over 512 Mb and on request at any size',
+    },
+    {
+        name: '`reads.bai` beside `reads.bam`',
+        writtenBy: 'Picard, GATK',
+    },
+];
+// Per-suffix because the alternatives are: a `.crai` has no CSI form, and
+// stripping the extension off `calls.vcf.gz` would name `calls.vcf.tbi`, which
+// nothing writes. A `.fai`/`.gzi` has neither and so is absent here.
+const ALTERNATE_SPELLINGS = {
+    '.bai': { csi: true, stripped: true },
+    '.crai': { stripped: true },
+    '.tbi': { csi: true },
+};
+/**
+ * The names a sidecar with this suffix might be under beside `location`, best
+ * guess first — the conventional one, then htslib's `.csi`, then the stripped
+ * form Picard and GATK write.
+ *
+ * The guard on the stripped spelling is load-bearing: `replace` hands back the
+ * subject unchanged when the pattern does not match, so a name carrying no
+ * extension at all would offer the data file as its own index.
+ */
+export function sidecarCandidateNames(location, suffix) {
+    const { csi, stripped } = ALTERNATE_SPELLINGS[suffix] ?? {};
+    const strippedName = location.replace(/\.[^./\\]+$/, suffix);
+    return [
+        `${location}${suffix}`,
+        ...(csi ? [`${location}.csi`] : []),
+        ...(stripped && strippedName !== location ? [strippedName] : []),
+    ];
+}
+// The tabix family is spelled by its compression, not its content: a `.gz` here
+// is a bgzipped VCF/GFF/BED/SAM, all of which index the same two ways, and
+// `.bgz` is the same file under the name htslib's own tools give it.
+const INDEX_SUFFIXES = [
+    [/\.bam$/i, '.bai'],
+    [/\.cram$/i, '.crai'],
+    [/\.b?gz$/i, '.tbi'],
+];
+/**
+ * The index filenames worth looking for beside `fileName`, best guess first.
+ *
+ * One data file has several names its index might carry, and picking only the
+ * first left everyone else with a missing-file error naming a path they never
+ * wrote. Empty for a file type that carries no sibling index (BigWig, BigBed,
+ * hic), which is how a caller knows not to go looking.
+ */
+export function indexCandidateNames(fileName) {
+    const suffix = INDEX_SUFFIXES.find(([re]) => re.test(fileName))?.[1];
+    return suffix ? sidecarCandidateNames(fileName, suffix) : [];
+}
+/**
+ * The index spelling a location implies: htslib writes `.csi` in place of a
+ * `.bai` or a `.tbi` for a reference over 512 Mb, and on request at any size.
+ */
+export function resolveIndexType(indexName, fallback) {
+    return indexName?.toUpperCase().endsWith('CSI') ? 'CSI' : fallback;
+}

package/esm/looseTrackConfig.d.ts

@@ -0,0 +1,13 @@
+export interface LooseTrackInput {
+    uri: string;
+    index?: string;
+    baseUri?: string;
+    [key: string]: unknown;
+}
+/**
+ * A track written as a data file with no `adapter`, the form
+ * `expandLooseTrackConfig` expands.
+ */
+export declare function isLooseTrackConfig(snap: unknown): snap is LooseTrackInput & {
+    trackId?: string;
+};

package/esm/looseTrackConfig.js

@@ -0,0 +1,11 @@
+/**
+ * A track written as a data file with no `adapter`, the form
+ * `expandLooseTrackConfig` expands.
+ */
+export function isLooseTrackConfig(snap) {
+    return (typeof snap === 'object' &&
+        snap !== null &&
+        !Array.isArray(snap) &&
+        typeof snap.uri === 'string' &&
+        !('adapter' in snap));
+}

package/esm/trackTypes.generated.js

@@ -6,8 +6,6 @@
  * fall back to `FeatureTrack`.
  */
 export const adapterTypesToTrackTypeMap = {
-    AllVsAllIndexedPAFAdapter: 'SyntenyTrack',
-    AllVsAllPAFAdapter: 'SyntenyTrack',
     BamAdapter: 'AlignmentsTrack',
     BedAdapter: 'FeatureTrack',
     BedGraphAdapter: 'QuantitativeTrack',
@@ -29,7 +27,7 @@ export const adapterTypesToTrackTypeMap = {
     FromConfigAdapter: 'FeatureTrack',
     FromConfigRegionsAdapter: 'ReferenceSequenceTrack',
     FromConfigSequenceAdapter: 'ReferenceSequenceTrack',
-    GCContentAdapter: 'QuantitativeTrack',
+    GCContentAdapter: 'GCContentTrack',
     Gff3Adapter: 'FeatureTrack',
     Gff3TabixAdapter: 'FeatureTrack',
     GtfAdapter: 'FeatureTrack',
@@ -43,6 +41,9 @@ export const adapterTypesToTrackTypeMap = {
     MCScanAnchorsAdapter: 'SyntenyTrack',
     MCScanBlocksAdapter: 'SyntenyTrack',
     MCScanSimpleAnchorsAdapter: 'SyntenyTrack',
+    MultiGenomeIndexedPAFAdapter: 'SyntenyTrack',
+    MultiGenomePAFAdapter: 'SyntenyTrack',
+    MultiPairwiseSyntenyAdapter: 'SyntenyTrack',
     MultiWiggleAdapter: 'MultiQuantitativeTrack',
     NCListAdapter: 'FeatureTrack',
     PAFAdapter: 'SyntenyTrack',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/add-track-core",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.11",
   "type": "module",
   "description": "The file-format table the add-track guessers and the CLI both read — no framework deps",
   "keywords": [