@mappedin/mvf-fetch 3.0.0-beta.15

package/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+## [3.0.0-beta.15](https://github.com/MappedIn/mvf/compare/mvf-fetch-v3.0.0-beta.14...mvf-fetch-v3.0.0-beta.15) (2026-09-24)
+
+
+### Build
+
+* **deps:** bump the npm_and_yarn group across 2 directories with 1 update ([#352](https://github.com/MappedIn/mvf/issues/352)) ([a64d7d3](https://github.com/MappedIn/mvf/commit/a64d7d333497dbe3ab6c49b37583f3df21c0f52c))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @mappedin/mvf-annotations bumped to 3.0.0-beta.15
+    * @mappedin/mvf-cms bumped to 3.0.0-beta.15
+    * @mappedin/mvf-connections bumped to 3.0.0-beta.15
+    * @mappedin/mvf-core bumped to 3.0.0-beta.15
+    * @mappedin/mvf-default-style bumped to 3.0.0-beta.15
+    * @mappedin/mvf-entrance-aesthetic bumped to 3.0.0-beta.15
+    * @mappedin/mvf-facade bumped to 3.0.0-beta.15
+    * @mappedin/mvf-floor-images bumped to 3.0.0-beta.15
+    * @mappedin/mvf-floor-stacks bumped to 3.0.0-beta.15
+    * @mappedin/mvf-kinds bumped to 3.0.0-beta.15
+    * @mappedin/mvf-locations bumped to 3.0.0-beta.15
+    * @mappedin/mvf-navigation-flags bumped to 3.0.0-beta.15
+    * @mappedin/mvf-nodes bumped to 3.0.0-beta.15
+    * @mappedin/mvf-outdoors bumped to 3.0.0-beta.15
+    * @mappedin/mvf-tileset bumped to 3.0.0-beta.15
+    * @mappedin/mvf-traversability bumped to 3.0.0-beta.15
+    * @mappedin/mvf-v2 bumped to 2.100.0-final.15
+  * peerDependencies
+    * @mappedin/mvf-core bumped to 3.0.0-beta.15
+    * @mappedin/mvf-v2 bumped to 2.100.0-final.15
+
+## [3.0.0-beta.14](https://github.com/MappedIn/mvf/compare/mvf-fetch-v3.0.0-beta.13...mvf-fetch-v3.0.0-beta.14) (2026-09-21)
+
+
+### Bug Fixes
+
+* **EINT-1520:** remove azure login that is no longer used ([#357](https://github.com/MappedIn/mvf/issues/357)) ([48ebfa8](https://github.com/MappedIn/mvf/commit/48ebfa8d64788b90ce781d8e7a6fde8976678ccb))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @mappedin/mvf-annotations bumped to 3.0.0-beta.14
+    * @mappedin/mvf-cms bumped to 3.0.0-beta.14
+    * @mappedin/mvf-connections bumped to 3.0.0-beta.14
+    * @mappedin/mvf-core bumped to 3.0.0-beta.14
+    * @mappedin/mvf-default-style bumped to 3.0.0-beta.14
+    * @mappedin/mvf-entrance-aesthetic bumped to 3.0.0-beta.14
+    * @mappedin/mvf-facade bumped to 3.0.0-beta.14
+    * @mappedin/mvf-floor-images bumped to 3.0.0-beta.14
+    * @mappedin/mvf-floor-stacks bumped to 3.0.0-beta.14
+    * @mappedin/mvf-kinds bumped to 3.0.0-beta.14
+    * @mappedin/mvf-locations bumped to 3.0.0-beta.14
+    * @mappedin/mvf-navigation-flags bumped to 3.0.0-beta.14
+    * @mappedin/mvf-nodes bumped to 3.0.0-beta.14
+    * @mappedin/mvf-outdoors bumped to 3.0.0-beta.14
+    * @mappedin/mvf-tileset bumped to 3.0.0-beta.14
+    * @mappedin/mvf-traversability bumped to 3.0.0-beta.14
+    * @mappedin/mvf-v2 bumped to 2.100.0-final.14
+  * peerDependencies
+    * @mappedin/mvf-core bumped to 3.0.0-beta.14
+    * @mappedin/mvf-v2 bumped to 2.100.0-final.14
+
+## [3.0.0-beta.13](https://github.com/MappedIn/mvf/compare/mvf-fetch-v3.0.0-beta.12...mvf-fetch-v3.0.0-beta.13) (2026-09-21)
+
+
+### chore
+
+* **mvf-fetch:** Synchronize mvf versions
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @mappedin/mvf-annotations bumped to 3.0.0-beta.13
+    * @mappedin/mvf-cms bumped to 3.0.0-beta.13
+    * @mappedin/mvf-connections bumped to 3.0.0-beta.13
+    * @mappedin/mvf-core bumped to 3.0.0-beta.13
+    * @mappedin/mvf-default-style bumped to 3.0.0-beta.13
+    * @mappedin/mvf-entrance-aesthetic bumped to 3.0.0-beta.13
+    * @mappedin/mvf-facade bumped to 3.0.0-beta.13
+    * @mappedin/mvf-floor-images bumped to 3.0.0-beta.13
+    * @mappedin/mvf-floor-stacks bumped to 3.0.0-beta.13
+    * @mappedin/mvf-kinds bumped to 3.0.0-beta.13
+    * @mappedin/mvf-locations bumped to 3.0.0-beta.13
+    * @mappedin/mvf-navigation-flags bumped to 3.0.0-beta.13
+    * @mappedin/mvf-nodes bumped to 3.0.0-beta.13
+    * @mappedin/mvf-outdoors bumped to 3.0.0-beta.13
+    * @mappedin/mvf-tileset bumped to 3.0.0-beta.13
+    * @mappedin/mvf-traversability bumped to 3.0.0-beta.13
+    * @mappedin/mvf-v2 bumped to 2.100.0-final.13
+  * peerDependencies
+    * @mappedin/mvf-core bumped to 3.0.0-beta.13
+    * @mappedin/mvf-v2 bumped to 2.100.0-final.13
+
+## [3.0.0-beta.12](https://github.com/MappedIn/mvf/compare/mvf-fetch-v3.0.0-beta.11...mvf-fetch-v3.0.0-beta.12) (2026-08-18)
+
+
+### Features
+
+* **mvf-fetch:** add package for range-based MVF zip reads ([#345](https://github.com/MappedIn/mvf/issues/345)) ([55d5a24](https://github.com/MappedIn/mvf/commit/55d5a24b410db4e654701bdc460cbb629ac0fee4))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @mappedin/mvf-annotations bumped to 3.0.0-beta.12
+    * @mappedin/mvf-cms bumped to 3.0.0-beta.12
+    * @mappedin/mvf-connections bumped to 3.0.0-beta.12
+    * @mappedin/mvf-core bumped to 3.0.0-beta.12
+    * @mappedin/mvf-default-style bumped to 3.0.0-beta.12
+    * @mappedin/mvf-entrance-aesthetic bumped to 3.0.0-beta.12
+    * @mappedin/mvf-facade bumped to 3.0.0-beta.12
+    * @mappedin/mvf-floor-images bumped to 3.0.0-beta.12
+    * @mappedin/mvf-floor-stacks bumped to 3.0.0-beta.12
+    * @mappedin/mvf-kinds bumped to 3.0.0-beta.12
+    * @mappedin/mvf-locations bumped to 3.0.0-beta.12
+    * @mappedin/mvf-navigation-flags bumped to 3.0.0-beta.12
+    * @mappedin/mvf-nodes bumped to 3.0.0-beta.12
+    * @mappedin/mvf-outdoors bumped to 3.0.0-beta.12
+    * @mappedin/mvf-tileset bumped to 3.0.0-beta.12
+    * @mappedin/mvf-traversability bumped to 3.0.0-beta.12
+    * @mappedin/mvf-v2 bumped to 2.100.0-final.12
+  * peerDependencies
+    * @mappedin/mvf-core bumped to 3.0.0-beta.12
+    * @mappedin/mvf-v2 bumped to 2.100.0-final.12

package/README.md

@@ -0,0 +1,23 @@
+# MVF Fetch
+
+Isomorphic utilities for efficiently reading published MVF v2/v3 zip archives from the cloud via HTTP Range requests.
+
+This package focuses on extracting and optionally validating individual zip entries. It does not render maps or convert between MVF versions.
+
+## Usage
+
+```ts
+import { createMvfFetcher } from '@mappedin/mvf-fetch';
+import { autoMvfValidator } from '@mappedin/mvf-fetch/validators';
+
+const fetcher = createMvfFetcher({
+  url: async () => ({
+    url: signedZipUrl,
+    cacheKey: `${venueId}:${updatedAt}`,
+  }),
+  validate: autoMvfValidator(),
+});
+
+const version = await fetcher.getVersion();
+const { files } = await fetcher.getEntries(['manifest.geojson', 'floors.geojson']);
+```

package/dist/fetcher.d.ts

@@ -0,0 +1,51 @@
+import { MvfZipSource } from './source.js';
+import type { UrlResolver } from './url/resolver.js';
+import type { FileValidator } from './validate.js';
+import { type ManifestFeatureCollection, type MvfVersion, groupEntriesByVersion } from './version.js';
+import type { ZipIndex } from './zip/index.js';
+import type { FetchFn } from './zip/range.js';
+export interface CreateMvfFetcherOptions {
+    url: UrlResolver;
+    validate?: FileValidator;
+    concurrency?: number;
+    fetchFn?: FetchFn;
+    indexCacheKey?: string;
+    /**
+     * Merge entry ranges separated by at most this many unwanted bytes into one request.
+     * @default 0
+     */
+    maxGapBytes?: number;
+    /** An already-parsed index for this archive, so opening costs no request at all. */
+    index?: ZipIndex;
+}
+export interface FetchResult {
+    version: MvfVersion;
+    files: Record<string, unknown>;
+}
+export interface GetEntriesOptions {
+    allowMissing?: boolean;
+}
+/**
+ * High-level orchestrator for fetching MVF zip entries from the cloud.
+ */
+export declare class MvfFetcher {
+    #private;
+    constructor(options: CreateMvfFetcherOptions);
+    get source(): MvfZipSource;
+    getVersion(): Promise<MvfVersion>;
+    getManifest(): Promise<ManifestFeatureCollection>;
+    getMapId(): Promise<string | undefined>;
+    listEntries(): Promise<string[]>;
+    getEntry(path: string): Promise<unknown | undefined>;
+    getEntries(paths: string[], options?: GetEntriesOptions): Promise<FetchResult>;
+    getFloor(floorId: string): Promise<FetchResult>;
+    getGlobals(): Promise<FetchResult>;
+    getAll(): Promise<FetchResult>;
+    getFloorIds(): Promise<string[]>;
+    groupEntries(): Promise<ReturnType<typeof groupEntriesByVersion>>;
+}
+/**
+ * Creates an {@link MvfFetcher} for reading MVF zip entries from the cloud.
+ */
+export declare function createMvfFetcher(options: CreateMvfFetcherOptions): MvfFetcher;
+//# sourceMappingURL=fetcher.d.ts.map

package/dist/fetcher.js

@@ -0,0 +1,93 @@
+import { MvfZipSource } from './source.js';
+import { validateFetchedFiles } from './validate.js';
+import { detectVersion, extractFloorIds, getFloorEntryPaths, getGlobalPaths, getManifest, getMapIdFromManifest, groupEntriesByVersion, } from './version.js';
+/**
+ * High-level orchestrator for fetching MVF zip entries from the cloud.
+ */
+export class MvfFetcher {
+    #source;
+    #validate;
+    #version = null;
+    #manifest = null;
+    constructor(options) {
+        this.#source = new MvfZipSource({
+            url: options.url,
+            fetchFn: options.fetchFn,
+            indexCacheKey: options.indexCacheKey,
+            concurrency: options.concurrency,
+            maxGapBytes: options.maxGapBytes,
+            index: options.index,
+        });
+        this.#validate = options.validate;
+    }
+    get source() {
+        return this.#source;
+    }
+    async getVersion() {
+        if (this.#version != null) {
+            return this.#version;
+        }
+        this.#version = await detectVersion(this.#source);
+        return this.#version;
+    }
+    async getManifest() {
+        if (this.#manifest != null) {
+            return this.#manifest;
+        }
+        this.#manifest = await getManifest(this.#source);
+        return this.#manifest;
+    }
+    async getMapId() {
+        const manifest = await this.getManifest();
+        return getMapIdFromManifest(manifest);
+    }
+    async listEntries() {
+        return this.#source.listEntries();
+    }
+    async getEntry(path) {
+        const result = await this.getEntries([path], { allowMissing: true });
+        return result.files[path];
+    }
+    async getEntries(paths, options = {}) {
+        const version = await this.getVersion();
+        const files = await this.#source.getEntries(paths, options);
+        await validateFetchedFiles(this.#validate, version, files);
+        return { version, files };
+    }
+    async getFloor(floorId) {
+        const version = await this.getVersion();
+        const availablePaths = await this.#source.listEntries();
+        const paths = getFloorEntryPaths(version, floorId, availablePaths);
+        return this.getEntries(paths, { allowMissing: true });
+    }
+    async getGlobals() {
+        const version = await this.getVersion();
+        const availablePaths = new Set(await this.#source.listEntries());
+        const paths = getGlobalPaths(version).filter((path) => availablePaths.has(path));
+        return this.getEntries(paths, { allowMissing: true });
+    }
+    async getAll() {
+        const version = await this.getVersion();
+        const paths = await this.#source.listEntries();
+        const files = await this.#source.getEntries(paths);
+        await validateFetchedFiles(this.#validate, version, files);
+        return { version, files };
+    }
+    async getFloorIds() {
+        const version = await this.getVersion();
+        const paths = await this.#source.listEntries();
+        return extractFloorIds(version, paths);
+    }
+    async groupEntries() {
+        const version = await this.getVersion();
+        const paths = await this.#source.listEntries();
+        return groupEntriesByVersion(version, paths);
+    }
+}
+/**
+ * Creates an {@link MvfFetcher} for reading MVF zip entries from the cloud.
+ */
+export function createMvfFetcher(options) {
+    return new MvfFetcher(options);
+}
+//# sourceMappingURL=fetcher.js.map

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { createMvfFetcher, MvfFetcher } from './fetcher.js';
+export type { CreateMvfFetcherOptions, FetchResult, GetEntriesOptions } from './fetcher.js';
+export { MvfZipSource } from './source.js';
+export type { GetZipEntriesOptions, MvfZipSourceOptions } from './source.js';
+export { CachedUrlResolver, createIndexCacheKey, resolveUrl, } from './url/resolver.js';
+export type { CachedUrlResolverOptions, ResolvedUrl, UrlResolver } from './url/resolver.js';
+export { detectVersion, extractFloorIds, getFloorEntryPaths, getGlobalPaths, getManifest, getMapIdFromManifest, groupEntriesByVersion, getPerFloorFolders, } from './version.js';
+export type { ManifestFeatureCollection, MvfVersion } from './version.js';
+export { ValidationError, validateFetchedFile, validateFetchedFiles, } from './validate.js';
+export type { FetchedFile, FileValidator } from './validate.js';
+export { coalesceRanges, fetchCoalescedRanges, RangeBufferCache } from './zip/ranges.js';
+export type { ByteRange } from './zip/ranges.js';
+export { computeEntryEstimatedRange, countCoalescedRangesForEntries, decodeZipEntryJson, decompressEntry, extractCompressedBytes, readZipEntryBytes, readZipEntries, } from './zip/entry.js';
+export type { ReadZipEntriesOptions } from './zip/entry.js';
+export { DEFAULT_TAIL_READ_LENGTH, openRemoteZipIndex, parseCentralDirectory, parseEndOfCentralDirectory, } from './zip/index.js';
+export type { ZipEndOfCentralDirectory, ZipEntryMeta, ZipIndex } from './zip/index.js';
+export { fetchByteRange, fetchZipTail, getTotalSize, HttpRangeError, parseContentRange } from './zip/range.js';
+export type { FetchFn, ZipTail } from './zip/range.js';
+export { chunkArray, readUint16LE, readUint32LE, uniquePaths } from './zip/bytes.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+export { createMvfFetcher, MvfFetcher } from './fetcher.js';
+export { MvfZipSource } from './source.js';
+export { CachedUrlResolver, createIndexCacheKey, resolveUrl, } from './url/resolver.js';
+export { detectVersion, extractFloorIds, getFloorEntryPaths, getGlobalPaths, getManifest, getMapIdFromManifest, groupEntriesByVersion, getPerFloorFolders, } from './version.js';
+export { ValidationError, validateFetchedFile, validateFetchedFiles, } from './validate.js';
+export { coalesceRanges, fetchCoalescedRanges, RangeBufferCache } from './zip/ranges.js';
+export { computeEntryEstimatedRange, countCoalescedRangesForEntries, decodeZipEntryJson, decompressEntry, extractCompressedBytes, readZipEntryBytes, readZipEntries, } from './zip/entry.js';
+export { DEFAULT_TAIL_READ_LENGTH, openRemoteZipIndex, parseCentralDirectory, parseEndOfCentralDirectory, } from './zip/index.js';
+export { fetchByteRange, fetchZipTail, getTotalSize, HttpRangeError, parseContentRange } from './zip/range.js';
+export { chunkArray, readUint16LE, readUint32LE, uniquePaths } from './zip/bytes.js';
+//# sourceMappingURL=index.js.map

package/dist/source.d.ts

@@ -0,0 +1,51 @@
+import { type UrlResolver } from './url/resolver.js';
+import { type ZipIndex } from './zip/index.js';
+import type { FetchFn } from './zip/range.js';
+export interface MvfZipSourceOptions {
+    url: UrlResolver;
+    fetchFn?: FetchFn;
+    indexCacheKey?: string;
+    concurrency?: number;
+    /**
+     * Merge entry ranges separated by at most this many unwanted bytes into one request.
+     * Useful when the wanted entries are scattered through the archive.
+     * @default 0
+     */
+    maxGapBytes?: number;
+    /**
+     * An already-parsed index for this archive, so opening costs no request at all.
+     *
+     * The index is plain data, so it survives `structuredClone`: a caller that has
+     * already opened the archive can hand it to a worker, or persist it against
+     * {@link MvfZipSourceOptions.indexCacheKey}, instead of reading the central
+     * directory a second time.
+     */
+    index?: ZipIndex;
+}
+export interface GetZipEntriesOptions {
+    allowMissing?: boolean;
+}
+/**
+ * Low-level source for reading individual entries from a remote MVF zip.
+ */
+export declare class MvfZipSource {
+    #private;
+    constructor(options: MvfZipSourceOptions);
+    get indexCacheKey(): string | undefined;
+    listEntries(): Promise<string[]>;
+    getEntryBytes(path: string): Promise<Uint8Array | undefined>;
+    getEntry<T = unknown>(path: string): Promise<T | undefined>;
+    /**
+     * Reads several entries as decompressed bytes, coalescing their byte ranges.
+     *
+     * Prefer this over calling {@link MvfZipSource.getEntryBytes} per path: that issues one
+     * request per entry, while this reads them in as few requests as their layout allows.
+     * Consumers that need bytes rather than objects — a parser with its own decoder, or a
+     * worker the bytes are posted to — should use this instead of
+     * {@link MvfZipSource.getEntries}, which decodes and discards them.
+     */
+    getEntriesBytes(paths: string[], options?: GetZipEntriesOptions): Promise<Map<string, Uint8Array>>;
+    getEntries(paths: string[], options?: GetZipEntriesOptions): Promise<Record<string, unknown>>;
+    invalidate(): void;
+}
+//# sourceMappingURL=source.d.ts.map

package/dist/source.js

@@ -0,0 +1,112 @@
+import { CachedUrlResolver } from './url/resolver.js';
+import { uniquePaths } from './zip/bytes.js';
+import { decodeZipEntryJson, readZipEntries } from './zip/entry.js';
+import { openRemoteZipIndex } from './zip/index.js';
+/**
+ * Low-level source for reading individual entries from a remote MVF zip.
+ */
+export class MvfZipSource {
+    #urlResolver;
+    #fetchFn;
+    #indexCacheKey;
+    #concurrency;
+    #maxGapBytes;
+    /** Handed in by the caller rather than read from the archive. Survives cache-key changes. */
+    #providedIndex;
+    #index = null;
+    #indexCacheKeyUsed;
+    #pendingIndex = null;
+    constructor(options) {
+        this.#urlResolver = new CachedUrlResolver({ resolver: options.url });
+        this.#fetchFn = options.fetchFn ?? fetch;
+        this.#indexCacheKey = options.indexCacheKey;
+        this.#concurrency = options.concurrency ?? 32;
+        this.#maxGapBytes = options.maxGapBytes ?? 0;
+        this.#providedIndex = options.index ?? null;
+    }
+    get indexCacheKey() {
+        return this.#indexCacheKey ?? this.#urlResolver.cacheKey;
+    }
+    async listEntries() {
+        const index = await this.#getIndex();
+        return Object.keys(index.entries).sort();
+    }
+    async getEntryBytes(path) {
+        const entries = await this.getEntriesBytes([path], { allowMissing: true });
+        return entries.get(path);
+    }
+    async getEntry(path) {
+        const bytes = await this.getEntryBytes(path);
+        if (bytes == null) {
+            return undefined;
+        }
+        return decodeZipEntryJson(bytes);
+    }
+    /**
+     * Reads several entries as decompressed bytes, coalescing their byte ranges.
+     *
+     * Prefer this over calling {@link MvfZipSource.getEntryBytes} per path: that issues one
+     * request per entry, while this reads them in as few requests as their layout allows.
+     * Consumers that need bytes rather than objects — a parser with its own decoder, or a
+     * worker the bytes are posted to — should use this instead of
+     * {@link MvfZipSource.getEntries}, which decodes and discards them.
+     */
+    async getEntriesBytes(paths, options = {}) {
+        const unique = uniquePaths(paths);
+        if (unique.length === 0) {
+            return new Map();
+        }
+        const index = await this.#getIndex();
+        return this.#urlResolver.withAuthRetry((url) => readZipEntries(url, unique, index, {
+            allowMissing: options.allowMissing ?? false,
+            concurrency: this.#concurrency,
+            fetchFn: this.#fetchFn,
+            maxGapBytes: this.#maxGapBytes,
+        }));
+    }
+    async getEntries(paths, options = {}) {
+        const bytesByPath = await this.getEntriesBytes(paths, options);
+        const files = {};
+        for (const [path, bytes] of bytesByPath) {
+            files[path] = decodeZipEntryJson(bytes);
+        }
+        return files;
+    }
+    invalidate() {
+        this.#urlResolver.invalidate();
+        // A provided index is dropped too: invalidate means "trust nothing I was given".
+        this.#providedIndex = null;
+        this.#index = null;
+        this.#indexCacheKeyUsed = undefined;
+        this.#pendingIndex = null;
+    }
+    async #getIndex() {
+        if (this.#providedIndex != null) {
+            return this.#providedIndex;
+        }
+        const cacheKey = this.indexCacheKey;
+        if (this.#index != null && this.#indexCacheKeyUsed === cacheKey) {
+            return this.#index;
+        }
+        if (this.#pendingIndex != null) {
+            return this.#pendingIndex;
+        }
+        const pending = this.#urlResolver
+            .withAuthRetry((url) => openRemoteZipIndex(url, this.#fetchFn))
+            .then((index) => {
+            this.#index = index;
+            this.#indexCacheKeyUsed = cacheKey;
+            return index;
+        })
+            // Clearing on failure too lets a later call retry instead of replaying the rejection.
+            // The identity check keeps a stale open from discarding a newer one after invalidate().
+            .finally(() => {
+            if (this.#pendingIndex === pending) {
+                this.#pendingIndex = null;
+            }
+        });
+        this.#pendingIndex = pending;
+        return pending;
+    }
+}
+//# sourceMappingURL=source.js.map

package/dist/url/resolver.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Result of resolving a signed zip URL.
+ */
+export interface ResolvedUrl {
+    url: string;
+    cacheKey?: string;
+}
+/**
+ * A plain URL string or an async resolver that returns a signed URL.
+ */
+export type UrlResolver = string | (() => Promise<ResolvedUrl | string>);
+export interface CachedUrlResolverOptions {
+    resolver: UrlResolver;
+}
+/**
+ * Normalizes a resolver result into a {@link ResolvedUrl}.
+ */
+export declare function resolveUrl(resolver: UrlResolver): Promise<ResolvedUrl>;
+/**
+ * Wraps a {@link UrlResolver} with URL/index cache invalidation on 401/403.
+ */
+export declare class CachedUrlResolver {
+    #private;
+    constructor(options: CachedUrlResolverOptions);
+    get cacheKey(): string | undefined;
+    getUrl(forceRefresh?: boolean): Promise<string>;
+    invalidate(): void;
+    withAuthRetry<T>(operation: (url: string) => Promise<T>): Promise<T>;
+}
+/**
+ * Creates a cache key for zip index caching.
+ */
+export declare function createIndexCacheKey(resolver: CachedUrlResolver): string | undefined;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/url/resolver.js

@@ -0,0 +1,78 @@
+import { HttpRangeError } from '../zip/range.js';
+/**
+ * Normalizes a resolver result into a {@link ResolvedUrl}.
+ */
+export async function resolveUrl(resolver) {
+    if (typeof resolver === 'string') {
+        return { url: resolver };
+    }
+    const result = await resolver();
+    if (typeof result === 'string') {
+        return { url: result };
+    }
+    return result;
+}
+/**
+ * Wraps a {@link UrlResolver} with URL/index cache invalidation on 401/403.
+ */
+export class CachedUrlResolver {
+    #resolver;
+    #state = null;
+    #pending = null;
+    constructor(options) {
+        this.#resolver = options.resolver;
+    }
+    get cacheKey() {
+        return this.#state?.cacheKey;
+    }
+    async getUrl(forceRefresh = false) {
+        const state = await this.#ensureState(forceRefresh);
+        return state.url;
+    }
+    invalidate() {
+        this.#state = null;
+        this.#pending = null;
+    }
+    async withAuthRetry(operation) {
+        let refreshed = false;
+        while (true) {
+            const url = await this.getUrl(refreshed);
+            try {
+                return await operation(url);
+            }
+            catch (error) {
+                if (!refreshed && error instanceof HttpRangeError && (error.status === 401 || error.status === 403)) {
+                    this.invalidate();
+                    refreshed = true;
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    async #ensureState(forceRefresh) {
+        if (!forceRefresh && this.#state != null) {
+            return this.#state;
+        }
+        if (!forceRefresh && this.#pending != null) {
+            return this.#pending;
+        }
+        this.#pending = resolveUrl(this.#resolver).then((resolved) => {
+            const next = {
+                url: resolved.url,
+                cacheKey: resolved.cacheKey,
+            };
+            this.#state = next;
+            this.#pending = null;
+            return next;
+        });
+        return this.#pending;
+    }
+}
+/**
+ * Creates a cache key for zip index caching.
+ */
+export function createIndexCacheKey(resolver) {
+    return resolver.cacheKey;
+}
+//# sourceMappingURL=resolver.js.map

package/dist/validate.d.ts

@@ -0,0 +1,32 @@
+import type { MvfVersion } from './version.js';
+/**
+ * A fetched MVF zip entry decoded as JSON.
+ */
+export interface FetchedFile {
+    path: string;
+    version: MvfVersion;
+    contents: unknown;
+}
+/**
+ * Validates a single fetched MVF file.
+ *
+ * Implementations should throw when validation fails.
+ */
+export type FileValidator = (file: FetchedFile) => void | Promise<void>;
+/**
+ * Thrown when a fetched MVF file fails validation.
+ */
+export declare class ValidationError extends Error {
+    readonly path: string;
+    readonly cause: unknown;
+    constructor(path: string, cause: unknown);
+}
+/**
+ * Invokes a validator and wraps failures in {@link ValidationError}.
+ */
+export declare function validateFetchedFile(validator: FileValidator | undefined, file: FetchedFile): Promise<void>;
+/**
+ * Validates multiple fetched files sequentially.
+ */
+export declare function validateFetchedFiles(validator: FileValidator | undefined, version: MvfVersion, files: Record<string, unknown>): Promise<void>;
+//# sourceMappingURL=validate.d.ts.map