@mappedin/mvf-fetch 3.0.0-beta.15

package/dist/validate.js

@@ -0,0 +1,39 @@
+/**
+ * Thrown when a fetched MVF file fails validation.
+ */
+export class ValidationError extends Error {
+    path;
+    cause;
+    constructor(path, cause) {
+        super(`Validation failed for ${path}`);
+        this.path = path;
+        this.cause = cause;
+        this.name = 'ValidationError';
+    }
+}
+/**
+ * Invokes a validator and wraps failures in {@link ValidationError}.
+ */
+export async function validateFetchedFile(validator, file) {
+    if (validator == null) {
+        return;
+    }
+    try {
+        await validator(file);
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            throw error;
+        }
+        throw new ValidationError(file.path, error);
+    }
+}
+/**
+ * Validates multiple fetched files sequentially.
+ */
+export async function validateFetchedFiles(validator, version, files) {
+    for (const [path, contents] of Object.entries(files)) {
+        await validateFetchedFile(validator, { path, version, contents });
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/validators/index.d.ts

@@ -0,0 +1,9 @@
+import type { FileValidator } from '../validate.js';
+/**
+ * Creates a validator that delegates to the v2 or v3 adapter based on file version.
+ */
+export declare function autoMvfValidator(): FileValidator;
+export { assembleV2ParsedMvfFromFiles, createV2FileValidator, validateAssembledV2Files, validateAssembledV2ParsedMvf, } from './v2.js';
+export { createV3FileValidator } from './v3.js';
+export { V3_EXTENSIONS } from './v3-extensions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/validators/index.js

@@ -0,0 +1,20 @@
+import { createV2FileValidator } from './v2.js';
+import { createV3FileValidator } from './v3.js';
+/**
+ * Creates a validator that delegates to the v2 or v3 adapter based on file version.
+ */
+export function autoMvfValidator() {
+    const validateV2 = createV2FileValidator();
+    const validateV3 = createV3FileValidator();
+    return async (file) => {
+        if (file.version === '2.0.0') {
+            await validateV2(file);
+            return;
+        }
+        await validateV3(file);
+    };
+}
+export { assembleV2ParsedMvfFromFiles, createV2FileValidator, validateAssembledV2Files, validateAssembledV2ParsedMvf, } from './v2.js';
+export { createV3FileValidator } from './v3.js';
+export { V3_EXTENSIONS } from './v3-extensions.js';
+//# sourceMappingURL=index.js.map

package/dist/validators/v2.d.ts

@@ -0,0 +1,19 @@
+import type { ParsedMVF } from '@mappedin/mvf-v2/no-validator';
+import type { FileValidator } from '../validate.js';
+/**
+ * Best-effort per-file validation for MVF v2 zip entries.
+ */
+export declare function createV2FileValidator(): FileValidator;
+/**
+ * Assembles a v2 {@link ParsedMVF} object from path-keyed decoded zip entries.
+ */
+export declare function assembleV2ParsedMvfFromFiles(files: Record<string, unknown>): ParsedMVF;
+/**
+ * Validates a fully assembled MVF v2 bundle.
+ */
+export declare function validateAssembledV2ParsedMvf(parsed: ParsedMVF): void;
+/**
+ * Validates path-keyed decoded v2 entries as a complete MVF bundle.
+ */
+export declare function validateAssembledV2Files(files: Record<string, unknown>): void;
+//# sourceMappingURL=v2.d.ts.map

package/dist/validators/v2.js

@@ -0,0 +1,69 @@
+import { getMvfValidationErrors, validateMvf } from '@mappedin/mvf-v2';
+const FILE_EXTENSION = /\.json|\.geojson$/;
+function isRecord(value) {
+    return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+function assertGeoJsonFeatureCollection(path, contents) {
+    if (!isRecord(contents) || contents.type !== 'FeatureCollection') {
+        throw new Error(`${path} must be a GeoJSON FeatureCollection`);
+    }
+}
+/**
+ * Best-effort per-file validation for MVF v2 zip entries.
+ */
+export function createV2FileValidator() {
+    return (file) => {
+        if (file.version !== '2.0.0') {
+            return;
+        }
+        if (!isRecord(file.contents)) {
+            throw new Error(`${file.path} must decode to a JSON object`);
+        }
+        if (file.path.endsWith('.geojson')) {
+            assertGeoJsonFeatureCollection(file.path, file.contents);
+        }
+        if (file.path.endsWith('.json') && file.path !== 'connection.json') {
+            if (Array.isArray(file.contents)) {
+                return;
+            }
+            if (!isRecord(file.contents)) {
+                throw new Error(`${file.path} must decode to a JSON object or array`);
+            }
+        }
+    };
+}
+/**
+ * Assembles a v2 {@link ParsedMVF} object from path-keyed decoded zip entries.
+ */
+export function assembleV2ParsedMvfFromFiles(files) {
+    const parsed = {};
+    for (const [path, contents] of Object.entries(files)) {
+        if (path.includes('/')) {
+            const [folder, fileName] = path.split('/');
+            if (folder == null || fileName == null) {
+                continue;
+            }
+            const floorId = fileName.replace(FILE_EXTENSION, '');
+            const folderRecord = (parsed[folder] ??= {});
+            folderRecord[floorId] = contents;
+            continue;
+        }
+        parsed[path] = contents;
+    }
+    return parsed;
+}
+/**
+ * Validates a fully assembled MVF v2 bundle.
+ */
+export function validateAssembledV2ParsedMvf(parsed) {
+    if (!validateMvf(parsed)) {
+        throw new Error(getMvfValidationErrors(parsed).join('\n') || 'Invalid MVF v2 bundle');
+    }
+}
+/**
+ * Validates path-keyed decoded v2 entries as a complete MVF bundle.
+ */
+export function validateAssembledV2Files(files) {
+    validateAssembledV2ParsedMvf(assembleV2ParsedMvfFromFiles(files));
+}
+//# sourceMappingURL=v2.js.map

package/dist/validators/v3-extensions.d.ts

@@ -0,0 +1,10 @@
+import type { IntegrityError } from '@mappedin/mvf-core/errors';
+import type { MVFExtension } from '@mappedin/mvf-core/extension';
+import type { TSchema } from '@sinclair/typebox';
+type UnknownV3Extension = MVFExtension<TSchema, TSchema[], IntegrityError | unknown>;
+/**
+ * Standard MVF v3 extensions used to validate fetched zip entries.
+ */
+export declare const V3_EXTENSIONS: UnknownV3Extension[];
+export {};
+//# sourceMappingURL=v3-extensions.d.ts.map

package/dist/validators/v3-extensions.js

@@ -0,0 +1,42 @@
+import { AnnotationsExtension } from '@mappedin/mvf-annotations';
+import { CMSExtension } from '@mappedin/mvf-cms';
+import { ConnectionsExtension } from '@mappedin/mvf-connections';
+import { FloorsExtension } from '@mappedin/mvf-core/floors';
+import { GeometryExtension } from '@mappedin/mvf-core/geometry';
+import { ManifestExtension } from '@mappedin/mvf-core/manifest';
+import { DefaultStyleExtension } from '@mappedin/mvf-default-style';
+import { EntranceAestheticExtension } from '@mappedin/mvf-entrance-aesthetic';
+import { FacadeExtension } from '@mappedin/mvf-facade';
+import { FloorImagesExtension } from '@mappedin/mvf-floor-images';
+import { FloorStackExtension } from '@mappedin/mvf-floor-stacks';
+import { KindsExtension } from '@mappedin/mvf-kinds';
+import { LocationsExtension } from '@mappedin/mvf-locations';
+import { NavigationFlagsExtension } from '@mappedin/mvf-navigation-flags';
+import { NodesExtension } from '@mappedin/mvf-nodes';
+import { OutdoorsExtension } from '@mappedin/mvf-outdoors';
+import { TilesetExtension } from '@mappedin/mvf-tileset';
+import { TraversabilityExtension } from '@mappedin/mvf-traversability';
+/**
+ * Standard MVF v3 extensions used to validate fetched zip entries.
+ */
+export const V3_EXTENSIONS = [
+    ManifestExtension,
+    FloorsExtension,
+    GeometryExtension,
+    NavigationFlagsExtension,
+    NodesExtension,
+    ConnectionsExtension,
+    KindsExtension,
+    TraversabilityExtension,
+    DefaultStyleExtension,
+    FloorStackExtension,
+    OutdoorsExtension,
+    TilesetExtension,
+    FloorImagesExtension,
+    FacadeExtension,
+    AnnotationsExtension,
+    LocationsExtension,
+    CMSExtension,
+    EntranceAestheticExtension,
+];
+//# sourceMappingURL=v3-extensions.js.map

package/dist/validators/v3.d.ts

@@ -0,0 +1,11 @@
+import type { IntegrityError } from '@mappedin/mvf-core/errors';
+import type { MVFExtension } from '@mappedin/mvf-core/extension';
+import type { TSchema } from '@sinclair/typebox';
+import type { FileValidator } from '../validate.js';
+type UnknownV3Extension = MVFExtension<TSchema, TSchema[], IntegrityError | unknown>;
+/**
+ * Creates a per-file validator for MVF v3 zip entries using extension schemas.
+ */
+export declare function createV3FileValidator(extensions?: readonly UnknownV3Extension[]): FileValidator;
+export {};
+//# sourceMappingURL=v3.d.ts.map

package/dist/validators/v3.js

@@ -0,0 +1,47 @@
+import { ValidationContext } from '@mappedin/mvf-core/test-utils';
+import { V3_EXTENSIONS } from './v3-extensions.js';
+const jsonDecode = (bytes) => JSON.parse(new TextDecoder().decode(bytes));
+const encodeJson = (value) => new TextEncoder().encode(JSON.stringify(value));
+const PROBE_BYTES = new Uint8Array([123, 125]);
+function findExtensionForPath(path, extensions) {
+    for (const extension of extensions) {
+        try {
+            const partial = extension.fromBundle(path, PROBE_BYTES, jsonDecode);
+            if (partial !== undefined) {
+                return extension;
+            }
+        }
+        catch {
+            return extension;
+        }
+    }
+    return undefined;
+}
+const validationContexts = new Map(V3_EXTENSIONS.map((extension) => [extension.name, ValidationContext.fromExtension(extension)]));
+/**
+ * Creates a per-file validator for MVF v3 zip entries using extension schemas.
+ */
+export function createV3FileValidator(extensions = V3_EXTENSIONS) {
+    return (file) => {
+        if (file.version !== '3.0.0') {
+            return;
+        }
+        const extension = findExtensionForPath(file.path, extensions);
+        if (extension == null) {
+            throw new Error(`No MVF v3 extension registered for path: ${file.path}`);
+        }
+        const partial = extension.fromBundle(file.path, encodeJson(file.contents), jsonDecode);
+        if (partial == null) {
+            throw new Error(`Failed to decode MVF v3 partial for path: ${file.path}`);
+        }
+        const context = validationContexts.get(extension.name);
+        if (context == null) {
+            throw new Error(`Missing validation context for extension: ${extension.name}`);
+        }
+        const validator = context.createValidator(extension.schema);
+        if (!validator.Check(partial)) {
+            throw new Error(validator.ShortError(partial) ?? `Invalid MVF v3 file: ${file.path}`);
+        }
+    };
+}
+//# sourceMappingURL=v3.js.map

package/dist/version.d.ts

@@ -0,0 +1,53 @@
+import type { MvfZipSource } from './source.js';
+/**
+ * Supported published MVF manifest versions.
+ */
+export type MvfVersion = '2.0.0' | '3.0.0';
+export interface ManifestFeatureCollection {
+    type: 'FeatureCollection';
+    features: Array<{
+        properties: {
+            version?: string;
+            mapId?: string;
+            map?: string;
+            name?: string;
+        };
+    }>;
+}
+/**
+ * Reads and parses `manifest.geojson` from the zip source.
+ */
+export declare function getManifest(source: MvfZipSource): Promise<ManifestFeatureCollection>;
+/**
+ * Detects the MVF version from `manifest.geojson`.
+ */
+export declare function detectVersion(source: MvfZipSource): Promise<MvfVersion>;
+/**
+ * Returns the map identifier from the manifest, when present.
+ */
+export declare function getMapIdFromManifest(manifest: ManifestFeatureCollection): string | undefined;
+/**
+ * Returns global file paths for the given MVF version.
+ */
+export declare function getGlobalPaths(version: MvfVersion): readonly string[];
+/**
+ * Returns per-floor folder prefixes for the given MVF version.
+ */
+export declare function getPerFloorFolders(version: MvfVersion): readonly string[];
+/**
+ * Builds the per-floor entry paths that exist in the zip for a floor id.
+ */
+export declare function getFloorEntryPaths(version: MvfVersion, floorId: string, availablePaths: Iterable<string>): string[];
+/**
+ * Groups zip entry paths by MVF version-specific categories.
+ */
+export declare function groupEntriesByVersion(version: MvfVersion, paths: Iterable<string>): {
+    globals: string[];
+    perFloor: Record<string, string[]>;
+    other: string[];
+};
+/**
+ * Extracts floor ids present in the zip index for the detected MVF version.
+ */
+export declare function extractFloorIds(version: MvfVersion, paths: Iterable<string>): string[];
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,154 @@
+const V2_GLOBAL_FILES = [
+    'manifest.geojson',
+    'map.geojson',
+    'floor.geojson',
+    'mapstack.geojson',
+    'mapstack.json',
+    'floorstack.json',
+    'node.geojson',
+    'connection.json',
+    'styles.json',
+    'shapes.json',
+    'tileset.json',
+    'location.json',
+    'category.json',
+    'navigationFlags.json',
+    'annotation-symbols.json',
+];
+const V2_PER_FLOOR_FOLDERS = [
+    'space',
+    'obstruction',
+    'entrance',
+    'annotation',
+    'textAreas',
+    'shapeInstances',
+    'modelInstances',
+    'window',
+    'area',
+    'floorImages',
+];
+const V3_GLOBAL_FILES = [
+    'manifest.geojson',
+    'floors.geojson',
+    'floor-stacks.json',
+    'outdoors.json',
+    'connections.json',
+    'default-style.json',
+    'tileset.json',
+    'navigationFlags.json',
+    'annotation-symbols.json',
+    'locations.json',
+    'location.json',
+    'location-categories.json',
+    'location-instances.json',
+];
+const V3_PER_FLOOR_FOLDERS = [
+    'geometry',
+    'kinds',
+    'walkable',
+    'nonwalkable',
+    'annotations',
+    'entrance-aesthetic',
+    'facade',
+    'floorImages',
+    'nodes',
+];
+function parseManifestVersion(manifest) {
+    const version = manifest.features[0]?.properties.version;
+    if (version === '2.0.0' || version === '3.0.0') {
+        return version;
+    }
+    throw new Error(`Unsupported MVF manifest version: ${String(version)}`);
+}
+/**
+ * Reads and parses `manifest.geojson` from the zip source.
+ */
+export async function getManifest(source) {
+    const manifest = await source.getEntry('manifest.geojson');
+    if (manifest == null) {
+        throw new Error('manifest.geojson is missing from the MVF zip.');
+    }
+    return manifest;
+}
+/**
+ * Detects the MVF version from `manifest.geojson`.
+ */
+export async function detectVersion(source) {
+    const manifest = await getManifest(source);
+    return parseManifestVersion(manifest);
+}
+/**
+ * Returns the map identifier from the manifest, when present.
+ */
+export function getMapIdFromManifest(manifest) {
+    const properties = manifest.features[0]?.properties;
+    return properties?.mapId ?? properties?.map;
+}
+/**
+ * Returns global file paths for the given MVF version.
+ */
+export function getGlobalPaths(version) {
+    return version === '2.0.0' ? V2_GLOBAL_FILES : V3_GLOBAL_FILES;
+}
+/**
+ * Returns per-floor folder prefixes for the given MVF version.
+ */
+export function getPerFloorFolders(version) {
+    return version === '2.0.0' ? V2_PER_FLOOR_FOLDERS : V3_PER_FLOOR_FOLDERS;
+}
+/**
+ * Builds the per-floor entry paths that exist in the zip for a floor id.
+ */
+export function getFloorEntryPaths(version, floorId, availablePaths) {
+    const available = new Set(availablePaths);
+    const folders = getPerFloorFolders(version);
+    const paths = [];
+    for (const folder of folders) {
+        for (const extension of ['json', 'geojson']) {
+            const candidate = `${folder}/${floorId}.${extension}`;
+            if (available.has(candidate)) {
+                paths.push(candidate);
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * Groups zip entry paths by MVF version-specific categories.
+ */
+export function groupEntriesByVersion(version, paths) {
+    const allPaths = [...paths];
+    const globals = new Set();
+    const perFloor = {};
+    const other = [];
+    for (const path of allPaths) {
+        if (getGlobalPaths(version).includes(path)) {
+            globals.add(path);
+            continue;
+        }
+        const perFloorMatch = path.match(/^([^/]+)\/(.+)\.(json|geojson)$/);
+        if (perFloorMatch != null) {
+            const [, folder, floorId] = perFloorMatch;
+            if (folder != null && floorId != null && getPerFloorFolders(version).includes(folder)) {
+                const floorPaths = perFloor[floorId] ?? [];
+                floorPaths.push(path);
+                perFloor[floorId] = floorPaths;
+                continue;
+            }
+        }
+        other.push(path);
+    }
+    return {
+        globals: [...globals],
+        perFloor,
+        other,
+    };
+}
+/**
+ * Extracts floor ids present in the zip index for the detected MVF version.
+ */
+export function extractFloorIds(version, paths) {
+    const grouped = groupEntriesByVersion(version, paths);
+    return Object.keys(grouped.perFloor).sort();
+}
+//# sourceMappingURL=version.js.map

package/dist/zip/bytes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reads a little-endian unsigned 16-bit integer from a byte array.
+ */
+export declare function readUint16LE(bytes: Uint8Array, offset: number): number;
+/**
+ * Reads a little-endian unsigned 32-bit integer from a byte array.
+ */
+export declare function readUint32LE(bytes: Uint8Array, offset: number): number;
+/**
+ * Deduplicates paths while preserving order.
+ */
+export declare function uniquePaths(paths: string[]): string[];
+/**
+ * Splits an array into fixed-size chunks.
+ */
+export declare function chunkArray<T>(items: T[], chunkSize: number): T[][];
+//# sourceMappingURL=bytes.d.ts.map

package/dist/zip/bytes.js

@@ -0,0 +1,36 @@
+/**
+ * Reads a little-endian unsigned 16-bit integer from a byte array.
+ */
+export function readUint16LE(bytes, offset) {
+    return (bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8);
+}
+/**
+ * Reads a little-endian unsigned 32-bit integer from a byte array.
+ */
+export function readUint32LE(bytes, offset) {
+    return (((bytes[offset] ?? 0) |
+        ((bytes[offset + 1] ?? 0) << 8) |
+        ((bytes[offset + 2] ?? 0) << 16) |
+        ((bytes[offset + 3] ?? 0) << 24)) >>>
+        0);
+}
+/**
+ * Deduplicates paths while preserving order.
+ */
+export function uniquePaths(paths) {
+    return [...new Set(paths)];
+}
+/**
+ * Splits an array into fixed-size chunks.
+ */
+export function chunkArray(items, chunkSize) {
+    if (chunkSize <= 0) {
+        throw new Error('chunkSize must be greater than 0');
+    }
+    const chunks = [];
+    for (let i = 0; i < items.length; i += chunkSize) {
+        chunks.push(items.slice(i, i + chunkSize));
+    }
+    return chunks;
+}
+//# sourceMappingURL=bytes.js.map

package/dist/zip/entry.d.ts

@@ -0,0 +1,52 @@
+import { type ZipEntryMeta, type ZipIndex } from './index.js';
+import { type FetchFn } from './range.js';
+import { type ByteRange } from './ranges.js';
+export declare const LOCAL_EXTRA_FIELD_PAD = 1024;
+export interface ReadZipEntriesOptions {
+    allowMissing?: boolean;
+    concurrency?: number;
+    fetchFn?: FetchFn;
+    /**
+     * Merge entry ranges separated by at most this many unwanted bytes into one request.
+     * @default 0
+     */
+    maxGapBytes?: number;
+}
+interface ExtractCompressedResult {
+    compressed: Uint8Array;
+    remainingRange?: ByteRange;
+}
+/**
+ * Computes the initial byte range to fetch for a zip entry local header and payload.
+ */
+export declare function computeEntryEstimatedRange(entryPath: string, meta: ZipEntryMeta, totalSize: number): ByteRange;
+/**
+ * Extracts compressed entry bytes from a fetched buffer covering the entry header region.
+ */
+export declare function extractCompressedBytes(buffer: Uint8Array, bufferAbsoluteStart: number, entryPath: string, meta: ZipEntryMeta): ExtractCompressedResult;
+/**
+ * Reads the compressed bytes for a single zip entry via HTTP Range.
+ */
+export declare function readZipEntryBytes(url: string, entryPath: string, index: ZipIndex, fetchFn?: FetchFn): Promise<Uint8Array>;
+/**
+ * Decompresses a zip entry payload.
+ */
+export declare function decompressEntry(compressed: Uint8Array, meta: ZipEntryMeta): Uint8Array;
+/**
+ * Reads and decompresses multiple zip entries, coalescing adjacent HTTP Range requests.
+ */
+export declare function readZipEntries(url: string, entryPaths: string[], index: ZipIndex, options?: ReadZipEntriesOptions): Promise<Map<string, Uint8Array>>;
+/**
+ * Returns the coalesced HTTP Range count for a batch of entry paths.
+ * Useful for testing and diagnostics.
+ */
+export declare function countCoalescedRangesForEntries(entryPaths: string[], index: ZipIndex, maxGapBytes?: number): {
+    rawRanges: number;
+    coalescedRanges: number;
+};
+/**
+ * Decodes zip entry bytes as UTF-8 JSON.
+ */
+export declare function decodeZipEntryJson<T = unknown>(raw: Uint8Array): T;
+export {};
+//# sourceMappingURL=entry.d.ts.map