@genome-spy/core 0.77.0 → 0.79.0

package/dist/src/data/sources/lazy/tabixSource.js

@@ -3,16 +3,32 @@ import {
     activateExprRefProps,
     withoutExprRef,
 } from "../../../paramRuntime/paramUtils.js";
-import addBaseUrl from "../../../utils/addBaseUrl.js";
+import { attachDescriptorFieldsToData } from "../urlDescriptor.js";
+import UrlDescriptorController from "../urlDescriptorController.js";
+import UrlDescriptorState, {
+    updateUrlDescriptorState,
+} from "../urlDescriptorState.js";
 import SingleAxisWindowedSource from "./singleAxisWindowedSource.js";
 
 /**
  * @template T
+ * @template P
  * @abstract
  */
 export default class TabixSource extends SingleAxisWindowedSource {
-    /** @type {import("@gmod/tabix").TabixIndexedFile} */
-    #tbiIndex;
+    /**
+     * @typedef {object} TabixHandle
+     * @prop {import("@gmod/tabix").TabixIndexedFile} tbiIndex
+     * @prop {Record<string, import("../../../spec/channel.js").Scalar>} [fields]
+     * @prop {P} parserContext
+     * @prop {string} url
+     */
+
+    /** @type {UrlDescriptorState<TabixHandle>} */
+    #descriptorState = new UrlDescriptorState();
+
+    /** @type {UrlDescriptorController} */
+    #urlDescriptors;
 
     /**
      * @param {import("../../../spec/data.js").TabixData} params
@@ -41,7 +57,7 @@ export default class TabixSource extends SingleAxisWindowedSource {
                     props.has("indexUrl") ||
                     props.has("addChrPrefix")
                 ) {
-                    this.#initialize().then(() => this.reloadLastDomain());
+                    this.#reloadIfCurrentDomainNeedsData();
                 } else if (props.has("windowSize")) {
                     this.reloadLastDomain();
                 }
@@ -50,6 +66,12 @@ export default class TabixSource extends SingleAxisWindowedSource {
             { batchMode: "whenPropagated" }
         );
 
+        this.#urlDescriptors = new UrlDescriptorController(this, {
+            getUrl: () => this.params.url,
+            getIndexUrl: () => this.params.indexUrl,
+            onChange: () => this.#reloadIfCurrentDomainNeedsData(),
+        });
+
         if (!withoutExprRef(this.params.url)) {
             throw new Error("No URL provided for TabixSource");
         }
@@ -60,48 +82,93 @@ export default class TabixSource extends SingleAxisWindowedSource {
     }
 
     #initialize() {
-        this.initializedPromise = new Promise((resolve, reject) => {
-            Promise.all([
-                import("@gmod/tabix"),
-                import("generic-filehandle2"),
-            ]).then(async ([{ TabixIndexedFile }, { RemoteFile }]) => {
-                const withBase = (/** @type {string} */ uri) =>
-                    new RemoteFile(addBaseUrl(uri, this.view.getBaseUrl()));
-
-                const url = withoutExprRef(this.params.url);
-                const indexUrl =
-                    withoutExprRef(this.params.indexUrl) ?? url + ".tbi";
+        this.initializedPromise = this.#doInitialize();
+        return this.initializedPromise;
+    }
+
+    /**
+     * Refreshes active descriptors and reloads the current domain only if the
+     * current loaded data does not cover the new active descriptor set.
+     */
+    async #reloadIfCurrentDomainNeedsData() {
+        try {
+            await this.#initialize();
+
+            if (
+                !this.isDataReadyForDomain({
+                    [this.channel]: this.scaleResolution.getDomain(),
+                })
+            ) {
+                this.reloadLastDomain();
+            }
+        } catch {
+            // Initialization has already updated the loading status.
+        }
+    }
+
+    async #doInitialize() {
+        await updateUrlDescriptorState({
+            controller: this.#urlDescriptors,
+            state: this.#descriptorState,
+            clearData: () => this.load(),
+            setLoadingStatus: (status, detail) =>
+                this.setLoadingStatus(status, detail),
+            loadModules: async () => {
+                const { TabixIndexedFile, RemoteFile } =
+                    await loadTabixModules();
                 const addChrPrefix = withoutExprRef(this.params.addChrPrefix);
 
-                this.#tbiIndex = new TabixIndexedFile({
-                    filehandle: withBase(url),
-                    tbiFilehandle: withBase(indexUrl),
-                    renameRefSeqs:
-                        addChrPrefix === true
-                            ? (refSeq) => "chr" + refSeq
-                            : addChrPrefix
-                              ? (refSeq) => addChrPrefix + refSeq
-                              : undefined,
-                });
-
-                try {
-                    this.setLoadingStatus("loading");
-                    const header = await this.#tbiIndex.getHeader();
-                    await this._handleHeader(header);
-                    this.setLoadingStatus("complete");
-                    resolve();
-                } catch (e) {
-                    this.load();
-                    this.setLoadingStatus(
-                        "error",
-                        `${withoutExprRef(this.params.url)}: ${e.message}`
-                    );
-                    reject(e);
-                }
-            });
+                const renameRefSeqs =
+                    addChrPrefix === true
+                        ? (/** @type {string} */ refSeq) => "chr" + refSeq
+                        : addChrPrefix
+                          ? (/** @type {string} */ refSeq) =>
+                                addChrPrefix + refSeq
+                          : undefined;
+
+                return { TabixIndexedFile, RemoteFile, renameRefSeqs };
+            },
+            createHandle: (
+                descriptor,
+                { TabixIndexedFile, RemoteFile, renameRefSeqs }
+            ) =>
+                this.#createHandle(
+                    descriptor,
+                    TabixIndexedFile,
+                    RemoteFile,
+                    renameRefSeqs
+                ),
         });
+    }
 
-        return this.initializedPromise;
+    /**
+     * @param {import("../urlDescriptor.js").UrlDescriptor} descriptor
+     * @param {typeof import("@gmod/tabix").TabixIndexedFile} TabixIndexedFile
+     * @param {typeof import("generic-filehandle2").RemoteFile} RemoteFile
+     * @param {((refSeq: string) => string) | undefined} renameRefSeqs
+     * @returns {Promise<TabixHandle>}
+     */
+    async #createHandle(
+        descriptor,
+        TabixIndexedFile,
+        RemoteFile,
+        renameRefSeqs
+    ) {
+        const tbiIndex = new TabixIndexedFile({
+            filehandle: new RemoteFile(descriptor.url),
+            tbiFilehandle: new RemoteFile(
+                descriptor.indexUrl ?? descriptor.url + ".tbi"
+            ),
+            renameRefSeqs,
+        });
+        const header = await tbiIndex.getHeader();
+
+        return {
+            tbiIndex,
+            fields: descriptor.fields,
+            parserContext: await this._createParser(header, tbiIndex),
+            url: descriptor.url,
+        };
     }
 
     /**
@@ -111,51 +178,67 @@ export default class TabixSource extends SingleAxisWindowedSource {
      */
     async loadInterval(interval) {
         await this.initializedPromise;
-        const featureChunks = await this.discretizeAndLoad(
+        const handles = this.#descriptorState.handles;
+        const featureChunksByHandle = await this.discretizeAndLoad(
             interval,
-            async (discreteInterval, signal) => {
-                /** @type {string[]} */
-                const lines = [];
-
-                await this.#tbiIndex.getLines(
-                    discreteInterval.chrom,
-                    discreteInterval.startPos,
-                    discreteInterval.endPos,
-                    {
-                        lineCallback: (line) => {
-                            lines.push(line);
-                        },
-                        signal,
-                    }
-                );
-
-                return this._parseFeatures(lines);
-            }
+            async (discreteInterval, signal) =>
+                await Promise.all(
+                    handles.map(async (handle) => {
+                        /** @type {string[]} */
+                        const lines = [];
+
+                        await handle.tbiIndex.getLines(
+                            discreteInterval.chrom,
+                            discreteInterval.startPos,
+                            discreteInterval.endPos,
+                            {
+                                lineCallback: (line) => {
+                                    lines.push(line);
+                                },
+                                signal,
+                            }
+                        );
+
+                        return /** @type {[TabixHandle, T[]]} */ ([
+                            handle,
+                            attachDescriptorFieldsToData(
+                                this._parseFeatures(
+                                    lines,
+                                    handle.parserContext
+                                ),
+                                handle.fields
+                            ),
+                        ]);
+                    })
+                )
         );
 
-        if (featureChunks) {
-            this.publishData(featureChunks);
+        if (featureChunksByHandle) {
+            this.#publishHandleData(handles, featureChunksByHandle);
         }
     }
 
     /**
      * @param {string} header
+     * @param {import("@gmod/tabix").TabixIndexedFile} tbiIndex
      * @protected
+     * @returns {Promise<P>}
      */
-    async _handleHeader(header) {
-        //
+    async _createParser(header, tbiIndex) {
+        return /** @type {P} */ (undefined);
     }
 
     /**
      * Read a prefix of the Tabix file and decode it as text.
      *
+     * @param {import("@gmod/tabix").TabixIndexedFile} tbiIndex
      * @returns {Promise<string>}
      * @protected
      */
-    async _readFilePrefix() {
-        const { maxBlockSize } = await this.#tbiIndex.getMetadata();
-        const tbiIndex = /** @type {any} */ (this.#tbiIndex);
-        const compressedPrefix = await tbiIndex.filehandle.read(
+    async _readFilePrefix(tbiIndex) {
+        const { maxBlockSize } = await tbiIndex.getMetadata();
+        const tabixIndex = /** @type {any} */ (tbiIndex);
+        const compressedPrefix = await tabixIndex.filehandle.read(
             maxBlockSize,
             0
         );
@@ -167,10 +250,58 @@ export default class TabixSource extends SingleAxisWindowedSource {
      * @abstract
      * @protected
      * @param {string[]} lines
+     * @param {P} parserContext
      * @returns {T[]}
      */
-    _parseFeatures(lines) {
+    _parseFeatures(lines, parserContext) {
         // Override me
         return [];
     }
+
+    /**
+     * @param {TabixHandle[]} handles
+     * @param {[TabixHandle, T[]][][]} featureChunksByHandle
+     */
+    #publishHandleData(handles, featureChunksByHandle) {
+        this.reset();
+
+        for (const [handleIndex, handle] of handles.entries()) {
+            // Preserve physical file boundaries so downstream transforms can
+            // reset schema-dependent state for each partition.
+            this.beginBatch({ type: "file", url: handle.url });
+
+            for (const featureChunks of featureChunksByHandle) {
+                const [chunkHandle, data] = featureChunks[handleIndex];
+                if (chunkHandle !== handle) {
+                    throw new Error("Tabix feature chunks are out of order.");
+                }
+
+                for (const datum of data) {
+                    this._propagate(datum);
+                }
+            }
+        }
+
+        this.complete();
+        this.#descriptorState.markLoaded();
+    }
+
+    /**
+     * @param {import("./singleAxisLazySource.js").DataReadinessRequest} request
+     * @returns {boolean}
+     */
+    isDataReadyForDomain(request) {
+        return (
+            this.#descriptorState.activeSetLoaded &&
+            super.isDataReadyForDomain(request)
+        );
+    }
+}
+
+async function loadTabixModules() {
+    const [{ TabixIndexedFile }, { RemoteFile }] = await Promise.all([
+        import("@gmod/tabix"),
+        import("generic-filehandle2"),
+    ]);
+    return { TabixIndexedFile, RemoteFile };
 }

package/dist/src/data/sources/lazy/tabixTsvSource.d.ts

@@ -27,11 +27,10 @@ export function extractTabixTsvColumnsFromFirstLine(text: string): string[] | un
  */
 export function parseTabixTsvLines(lines: string[], columns: string[], parse?: import("../../../spec/data.js").Parse | null | undefined): Record<string, any>[];
 /**
- * @extends {TabixSource<Record<string, any>>}
+ * @extends {TabixSource<Record<string, any>, string[]>}
  */
-export default class TabixTsvSource extends TabixSource<Record<string, any>> {
+export default class TabixTsvSource extends TabixSource<Record<string, any>, string[]> {
     constructor(params: import("../../../spec/data.js").TabixData, view: import("../../../view/view.js").default);
-    #private;
 }
 import TabixSource from "./tabixSource.js";
 //# sourceMappingURL=tabixTsvSource.d.ts.map

package/dist/src/data/sources/lazy/tabixTsvSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tabixTsvSource.d.ts","sourceRoot":"","sources":["../../../../../src/data/sources/lazy/tabixTsvSource.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,+CAHW,MAAM,GACJ,MAAM,EAAE,GAAG,SAAS,CAsBhC;AAED;;;;;;;;GAQG;AACH,0DAHW,MAAM,GACJ,MAAM,EAAE,GAAG,SAAS,CAkBhC;AAED;;;;;;GAMG;AACH,0CAJW,MAAM,EAAE,WACR,MAAM,EAAE,UACR,OAAO,uBAAuB,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,yBAgClE;AAED;;GAEG;AACH;;;CA8CC;wBApJuB,kBAAkB"}
+{"version":3,"file":"tabixTsvSource.d.ts","sourceRoot":"","sources":["../../../../../src/data/sources/lazy/tabixTsvSource.js"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,+CAHW,MAAM,GACJ,MAAM,EAAE,GAAG,SAAS,CAsBhC;AAED;;;;;;;;GAQG;AACH,0DAHW,MAAM,GACJ,MAAM,EAAE,GAAG,SAAS,CAkBhC;AAED;;;;;;GAMG;AACH,0CAJW,MAAM,EAAE,WACR,MAAM,EAAE,UACR,OAAO,uBAAuB,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,yBAgClE;AAED;;GAEG;AACH;;CAgDC;wBAtJuB,kBAAkB"}

package/dist/src/data/sources/lazy/tabixTsvSource.js

@@ -102,51 +102,53 @@ export function parseTabixTsvLines(lines, columns, parse) {
 }
 
 /**
- * @extends {TabixSource<Record<string, any>>}
+ * @extends {TabixSource<Record<string, any>, string[]>}
  */
 export default class TabixTsvSource extends TabixSource {
-    /** @type {string[] | undefined} */
-    #columns;
-
     get label() {
         return "tabixSource";
     }
 
     /**
      * @param {string} header
+     * @param {import("@gmod/tabix").TabixIndexedFile} tbiIndex
+     * @returns {Promise<string[]>}
      */
-    async _handleHeader(header) {
+    async _createParser(header, tbiIndex) {
         const params =
             /** @type {import("../../../spec/data.js").TabixTsvData} */ (
                 this.params
             );
         const columns = withoutExprRef(params.columns);
-        this.#columns = columns ?? extractTabixTsvColumns(header);
+        let fileColumns = columns ?? extractTabixTsvColumns(header);
 
-        if (!this.#columns?.length) {
-            this.#columns = extractTabixTsvColumnsFromFirstLine(
-                await this._readFilePrefix()
+        if (!fileColumns?.length) {
+            fileColumns = extractTabixTsvColumnsFromFirstLine(
+                await this._readFilePrefix(tbiIndex)
             );
         }
 
-        if (!this.#columns?.length) {
+        if (!fileColumns?.length) {
             throw new Error(
                 "No columns available for Tabix TSV source. Provide data.lazy.columns or a tabix header line such as #chrom\\tstart\\tend, or a plain first row such as chrom\\tstart\\tend."
             );
         }
+
+        return fileColumns;
     }
 
     /**
      * @param {string[]} lines
+     * @param {string[] | undefined} columns
      */
-    _parseFeatures(lines) {
+    _parseFeatures(lines, columns) {
         const params =
             /** @type {import("../../../spec/data.js").TabixTsvData} */ (
                 this.params
             );
         return parseTabixTsvLines(
             lines,
-            this.#columns ?? [],
+            columns ?? [],
             withoutExprRef(params.parse)
         );
     }

package/dist/src/data/sources/lazy/vcfSource.d.ts

@@ -1,9 +1,13 @@
 /**
- * @extends {TabixSource<import("./vcfTypes.js").ParsedVariant>}
+ * @extends {TabixSource<import("./vcfTypes.js").ParsedVariant, import("@gmod/vcf").default>}
  */
-export default class VcfSource extends TabixSource<import("./vcfTypes.js").ParsedVariant> {
+export default class VcfSource extends TabixSource<import("./vcfTypes.js").ParsedVariant, import("@gmod/vcf").default> {
     constructor(params: import("../../../spec/data.js").TabixData, view: import("../../../view/view.js").default);
-    #private;
+    /**
+     * @param {string} header
+     * @returns {Promise<import("@gmod/vcf").default>}
+     */
+    _createParser(header: string): Promise<import("@gmod/vcf").default>;
 }
 import TabixSource from "./tabixSource.js";
 //# sourceMappingURL=vcfSource.d.ts.map

package/dist/src/data/sources/lazy/vcfSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vcfSource.d.ts","sourceRoot":"","sources":["../../../../../src/data/sources/lazy/vcfSource.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;;;CAgCC;wBAtCuB,kBAAkB"}
+{"version":3,"file":"vcfSource.d.ts","sourceRoot":"","sources":["../../../../../src/data/sources/lazy/vcfSource.js"],"names":[],"mappings":"AAGA;;GAEG;AACH;;IAKI;;;OAGG;IACH,sBAHW,MAAM,GACJ,OAAO,CAAC,OAAO,WAAW,EAAE,OAAO,CAAC,CAMhD;CAkBJ;wBArCuB,kBAAkB"}

package/dist/src/data/sources/lazy/vcfSource.js

@@ -2,31 +2,30 @@ import TabixSource from "./tabixSource.js";
 import { registerBuiltInLazyDataSource } from "./lazyDataSourceRegistry.js";
 
 /**
- * @extends {TabixSource<import("./vcfTypes.js").ParsedVariant>}
+ * @extends {TabixSource<import("./vcfTypes.js").ParsedVariant, import("@gmod/vcf").default>}
  */
 export default class VcfSource extends TabixSource {
-    /** @type {import("@gmod/vcf").default} */
-    #tbiVCFParser;
-
     get label() {
         return "vcfSource";
     }
 
     /**
      * @param {string} header
+     * @returns {Promise<import("@gmod/vcf").default>}
      */
-    async _handleHeader(header) {
+    async _createParser(header) {
         const VCFParser = (await import("@gmod/vcf")).default;
         // @ts-ignore - There's something wrong with the type definition
-        this.#tbiVCFParser = new VCFParser({ header });
+        return new VCFParser({ header });
     }
 
     /**
      * @param {string[]} lines
+     * @param {import("@gmod/vcf").default} parser
      */
-    _parseFeatures(lines) {
+    _parseFeatures(lines, parser) {
         return lines.map((line) => {
-            const parsed = this.#tbiVCFParser.parseLine(line);
+            const parsed = parser.parseLine(line);
             delete parsed.GENOTYPES;
             // @ts-ignore
             parsed.SAMPLES = parsed.SAMPLES();

package/dist/src/data/sources/urlDescriptor.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Expands a URL spec into concrete descriptors, resolves relative URLs against
+ * the view base URL, deduplicates the result, and enforces `maxValues`.
+ *
+ * @param {UrlDescriptorOptions} options
+ * @returns {Promise<UrlDescriptor[]>}
+ */
+export function normalizeUrlDescriptors(options: UrlDescriptorOptions): Promise<UrlDescriptor[]>;
+/**
+ * Expands a URL spec that is expected to resolve to exactly one descriptor.
+ * Sources that still support only one remote file use this to fail before
+ * constructing file handles.
+ *
+ * @param {UrlDescriptorOptions} options
+ * @param {string} sourceName
+ * @returns {Promise<UrlDescriptor>}
+ */
+export function normalizeSingleUrlDescriptor(options: UrlDescriptorOptions, sourceName: string): Promise<UrlDescriptor>;
+/**
+ * Subscribes to expressions that affect URL expansion. Sources call this in
+ * addition to `activateExprRefProps` because template values are nested under
+ * `url.values` and therefore are not top-level data source properties.
+ *
+ * @param {{
+ *   url: UrlSourceRef | SingleUrlSourceRef | MultiUrlSourceRef | unknown,
+ *   indexUrl?: IndexUrlSourceRef | unknown,
+ *   paramRuntime: UrlExpressionRuntime,
+ *   listener: () => void,
+ *   registerDisposer?: (disposer: () => void) => void,
+ * }} options
+ */
+export function watchUrlDescriptorExpressions(options: {
+    url: UrlSourceRef | SingleUrlSourceRef | MultiUrlSourceRef | unknown;
+    indexUrl?: IndexUrlSourceRef | unknown;
+    paramRuntime: UrlExpressionRuntime;
+    listener: () => void;
+    registerDisposer?: (disposer: () => void) => void;
+}): void;
+/**
+ * Creates a mutating attacher for descriptor fields. Descriptor fields are
+ * source context from URL expansion, such as `{ sample: "S1" }`. Source-loaded
+ * datums are fresh objects, so mutating them avoids per-row cloning while still
+ * detecting ambiguous source metadata.
+ *
+ * @param {Record<string, Scalar>} [fields]
+ * @returns {(datum: Record<string, any>) => Record<string, any>}
+ */
+export function createDescriptorFieldAttacher(fields?: Record<string, Scalar>): (datum: Record<string, any>) => Record<string, any>;
+/**
+ * Attaches descriptor fields to a loaded datum.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} datum
+ * @param {Record<string, Scalar>} [fields]
+ * @returns {T}
+ */
+export function attachDescriptorFields<T extends Record<string, any>>(datum: T, fields?: Record<string, Scalar>): T;
+/**
+ * @template {Record<string, any>} T
+ * @param {T[]} data
+ * @param {Record<string, Scalar>} [fields]
+ * @returns {T[]}
+ */
+export function attachDescriptorFieldsToData<T extends Record<string, any>>(data: T[], fields?: Record<string, Scalar>): T[];
+/**
+ * Runs a per-descriptor load operation and converts configured failures into
+ * skipped results.
+ *
+ * @template T
+ * @param {UrlDescriptor} descriptor
+ * @param {() => Promise<T>} load
+ * @returns {Promise<T | undefined>}
+ */
+export function loadUrlDescriptorOrSkip<T>(descriptor: UrlDescriptor, load: () => Promise<T>): Promise<T | undefined>;
+/**
+ * Returns a stable key for comparing URL descriptors independently of their
+ * position in a descriptor array.
+ *
+ * @param {UrlDescriptor} descriptor
+ */
+export function urlDescriptorKey(descriptor: UrlDescriptor): string;
+/**
+ * @typedef {import("../../spec/channel.js").Scalar} Scalar
+ * @typedef {import("../../spec/data.js").UrlSourceRef} UrlSourceRef
+ * @typedef {import("../../spec/data.js").SingleUrlSourceRef} SingleUrlSourceRef
+ * @typedef {import("../../spec/data.js").MultiUrlSourceRef} MultiUrlSourceRef
+ * @typedef {import("../../spec/data.js").IndexUrlSourceRef} IndexUrlSourceRef
+ * @typedef {import("../../spec/data.js").UrlTemplate} UrlTemplate
+ * @typedef {import("../../spec/data.js").IndexUrlTemplate} IndexUrlTemplate
+ * @typedef {import("../../spec/parameter.js").ExprRef} ExprRef
+ * @typedef {() => unknown} ExpressionFunction
+ * @typedef {ExpressionFunction & { subscribe?: (listener: () => void) => () => void }} SubscribableExpressionFunction
+ * @typedef {{
+ *     createExpression: (expr: string) => SubscribableExpressionFunction,
+ *     watchExpression?: (
+ *         expr: string,
+ *         listener: () => void,
+ *         options?: {
+ *             scopeOwned?: boolean,
+ *             registerDisposer?: (disposer: () => void) => void
+ *         }
+ *     ) => SubscribableExpressionFunction,
+ * }} UrlExpressionRuntime
+ */
+/**
+ * @typedef {object} UrlDescriptor
+ * @prop {string} url
+ * @prop {string} [indexUrl]
+ * @prop {Record<string, Scalar>} [fields]
+ * @prop {"error" | "skip"} [onLoadError]
+ */
+/**
+ * @typedef {object} UrlDescriptorOptions
+ * @prop {UrlSourceRef | SingleUrlSourceRef | MultiUrlSourceRef | unknown} url
+ * @prop {IndexUrlSourceRef | unknown} [indexUrl]
+ * @prop {string} [baseUrl]
+ * @prop {UrlExpressionRuntime} [paramRuntime]
+ */
+/**
+ * Thrown when URL expansion resolves more distinct descriptors than the spec
+ * allows. Sources may handle this as an intentional empty data state.
+ */
+export class UrlLimitExceededError extends Error {
+    /**
+     * @param {number} count
+     * @param {number} maxValues
+     */
+    constructor(count: number, maxValues: number);
+    /** @type {number} */
+    count: number;
+    /** @type {number} */
+    maxValues: number;
+}
+export type Scalar = import("../../spec/channel.js").Scalar;
+export type UrlSourceRef = import("../../spec/data.js").UrlSourceRef;
+export type SingleUrlSourceRef = import("../../spec/data.js").SingleUrlSourceRef;
+export type MultiUrlSourceRef = import("../../spec/data.js").MultiUrlSourceRef;
+export type IndexUrlSourceRef = import("../../spec/data.js").IndexUrlSourceRef;
+export type UrlTemplate = import("../../spec/data.js").UrlTemplate;
+export type IndexUrlTemplate = import("../../spec/data.js").IndexUrlTemplate;
+export type ExprRef = import("../../spec/parameter.js").ExprRef;
+export type ExpressionFunction = () => unknown;
+export type SubscribableExpressionFunction = ExpressionFunction & {
+    subscribe?: (listener: () => void) => () => void;
+};
+export type UrlExpressionRuntime = {
+    createExpression: (expr: string) => SubscribableExpressionFunction;
+    watchExpression?: (expr: string, listener: () => void, options?: {
+        scopeOwned?: boolean;
+        registerDisposer?: (disposer: () => void) => void;
+    }) => SubscribableExpressionFunction;
+};
+export type UrlDescriptor = {
+    url: string;
+    indexUrl?: string;
+    fields?: Record<string, Scalar>;
+    onLoadError?: "error" | "skip";
+};
+export type UrlDescriptorOptions = {
+    url: UrlSourceRef | SingleUrlSourceRef | MultiUrlSourceRef | unknown;
+    indexUrl?: IndexUrlSourceRef | unknown;
+    baseUrl?: string;
+    paramRuntime?: UrlExpressionRuntime;
+};
+//# sourceMappingURL=urlDescriptor.d.ts.map

package/dist/src/data/sources/urlDescriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlDescriptor.d.ts","sourceRoot":"","sources":["../../../../src/data/sources/urlDescriptor.js"],"names":[],"mappings":"AAgFA;;;;;;GAMG;AACH,iDAHW,oBAAoB,GAClB,OAAO,CAAC,aAAa,EAAE,CAAC,CAapC;AAED;;;;;;;;GAQG;AACH,sDAJW,oBAAoB,cACpB,MAAM,GACJ,OAAO,CAAC,aAAa,CAAC,CAQlC;AAED;;;;;;;;;;;;GAYG;AACH,uDARW;IACN,GAAG,EAAE,YAAY,GAAG,kBAAkB,GAAG,iBAAiB,GAAG,OAAO,CAAC;IACrE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC;IACvC,YAAY,EAAE,oBAAoB,CAAC;IACnC,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACnD,QAgBH;AAED;;;;;;;;GAQG;AACH,uDAHW,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAoC/D;AAED;;;;;;;GAOG;AACH,uCALmC,CAAC,SAAtB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAE,SACvB,CAAC,WACD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpB,CAAC,CAIb;AAED;;;;;GAKG;AACH,6CALmC,CAAC,SAAtB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAE,QACvB,CAAC,EAAE,WACH,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpB,CAAC,EAAE,CAYf;AAoBD;;;;;;;;GAQG;AACH,wCALa,CAAC,cACH,aAAa,QACb,MAAM,OAAO,CAAC,CAAC,CAAC,GACd,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAWlC;AAED;;;;;GAKG;AACH,6CAFW,aAAa,UAUvB;AAlQD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AAEH;;;;;;GAMG;AAEH;;;GAGG;AACH;IAOI;;;OAGG;IACH,mBAHW,MAAM,aACN,MAAM,EAShB;IAjBD,qBAAqB;IACrB,OADW,MAAM,CACX;IAEN,qBAAqB;IACrB,WADW,MAAM,CACP;CAcb;qBA9DY,OAAO,uBAAuB,EAAE,MAAM;2BACtC,OAAO,oBAAoB,EAAE,YAAY;iCACzC,OAAO,oBAAoB,EAAE,kBAAkB;gCAC/C,OAAO,oBAAoB,EAAE,iBAAiB;gCAC9C,OAAO,oBAAoB,EAAE,iBAAiB;0BAC9C,OAAO,oBAAoB,EAAE,WAAW;+BACxC,OAAO,oBAAoB,EAAE,gBAAgB;sBAC7C,OAAO,yBAAyB,EAAE,OAAO;iCACzC,MAAM,OAAO;6CACb,kBAAkB,GAAG;IAAE,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CAAE;mCACzE;IACN,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,8BAA8B,CAAC;IACnE,eAAe,CAAC,EAAE,CACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,IAAI,EACpB,OAAO,CAAC,EAAE;QACN,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,gBAAgB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;KACpD,KACA,8BAA8B,CAAC;CACvC;;SAKM,MAAM;eACN,MAAM;aACN,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;kBACtB,OAAO,GAAG,MAAM;;;SAKhB,YAAY,GAAG,kBAAkB,GAAG,iBAAiB,GAAG,OAAO;eAC/D,iBAAiB,GAAG,OAAO;cAC3B,MAAM;mBACN,oBAAoB"}