map-gl-offline 0.1.0-alpha.0

package/dist/utils/constants.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Application-wide constants
+ * Centralizes magic numbers and configuration values
+ */
+export declare const DB_NAME = "offline-map-db";
+export declare const DB_VERSION = 2;
+export declare const STORE_NAMES: {
+    readonly REGIONS: "regions";
+    readonly TILES: "tiles";
+    readonly STYLES: "styles";
+    readonly SPRITES: "sprites";
+    readonly GLYPHS: "glyphs";
+    readonly FONTS: "fonts";
+};
+export declare const DOWNLOAD_DEFAULTS: {
+    readonly BATCH_SIZE: 10;
+    readonly MAX_CONCURRENCY: 5;
+    readonly MAX_RETRIES: 3;
+    readonly TIMEOUT: 10000;
+    readonly RETRY_DELAY: 1000;
+};
+export declare const TILE_CONFIG: {
+    readonly MIN_ZOOM: 0;
+    readonly MAX_ZOOM: 24;
+    readonly DEFAULT_EXTENSION: "pbf";
+    readonly SUPPORTED_EXTENSIONS: readonly ["pbf", "mvt", "png", "jpg", "jpeg", "webp"];
+};
+export declare const GLYPH_CONFIG: {
+    readonly DEFAULT_RANGES: readonly ["0-255"];
+    readonly COMPREHENSIVE_RANGES: readonly ["0-255", "256-511", "512-767", "768-1023", "1024-1279", "1280-1535", "1536-1791", "1792-2047", "2048-2303", "2304-2559", "2560-2815", "2816-3071", "3072-3327", "3328-3583", "3584-3839", "3840-4095", "4096-4351", "4352-4607", "4608-4863", "11904-12031", "12032-12255", "12288-12543", "12544-12799", "19968-20223", "20224-20479", "40960-42127", "44032-55203", "63744-64255", "65280-65535"];
+};
+export declare const STORAGE_CONFIG: {
+    readonly DEFAULT_EXPIRY: number;
+    readonly MIN_AVAILABLE_SPACE: number;
+    readonly WARNING_THRESHOLD: 0.9;
+};
+export declare const CONTENT_TYPES: {
+    readonly VECTOR_TILE: "application/vnd.mapbox-vector-tile";
+    readonly PROTOBUF: "application/x-protobuf";
+    readonly JSON: "application/json";
+    readonly PNG: "image/png";
+    readonly JPEG: "image/jpeg";
+    readonly WEBP: "image/webp";
+};
+export declare const URL_SCHEMES: {
+    readonly IDB: "idb://";
+    readonly HTTP: "http://";
+    readonly HTTPS: "https://";
+};
+export declare const GZIP_MAGIC_BYTES: {
+    readonly FIRST: 31;
+    readonly SECOND: 139;
+};
+export declare const RESOURCE_TYPES: {
+    readonly TILE: "tile";
+    readonly GLYPH: "glyph";
+    readonly SPRITE: "sprite";
+    readonly FONT: "font";
+    readonly STYLE: "style";
+    readonly TILEJSON: "tilesjson";
+};
+export declare const MAP_PROVIDERS: {
+    readonly AUTO: "auto";
+    readonly MAPBOX: "mapbox";
+    readonly MAPLIBRE: "maplibre";
+    readonly CARTO: "carto";
+    readonly MAPTILER: "maptiler";
+};
+export declare const VALIDATION_PATTERNS: {
+    readonly TILE_URL: RegExp;
+    readonly STYLE_ID: RegExp;
+    readonly REGION_ID: RegExp;
+};
+export declare const ERROR_MESSAGES: {
+    readonly NO_STYLE: "Style must be downloaded before adding a region";
+    readonly NO_STYLE_ID: "No style ID found for region";
+    readonly NO_STYLE_URL: "Region must have a styleUrl";
+    readonly INVALID_BOUNDS: "Invalid bounds specified";
+    readonly INVALID_ZOOM: "Invalid zoom levels specified";
+    readonly INSUFFICIENT_STORAGE: "Insufficient storage space for download";
+    readonly TILE_VALIDATION_FAILED: "Tile validation failed";
+    readonly NETWORK_ERROR: "Network error occurred during download";
+};
+export declare const SUCCESS_MESSAGES: {
+    readonly TILES_DOWNLOADED: "Tiles downloaded successfully";
+    readonly STYLE_DOWNLOADED: "Style downloaded successfully";
+    readonly REGION_ADDED: "Region added successfully";
+    readonly REGION_DELETED: "Region deleted successfully";
+    readonly CLEANUP_COMPLETE: "Cleanup completed successfully";
+};
+export type StoreName = (typeof STORE_NAMES)[keyof typeof STORE_NAMES];
+export type TileExtension = (typeof TILE_CONFIG.SUPPORTED_EXTENSIONS)[number];
+export type ResourceType = (typeof RESOURCE_TYPES)[keyof typeof RESOURCE_TYPES];
+export type MapProvider = (typeof MAP_PROVIDERS)[keyof typeof MAP_PROVIDERS];

package/dist/utils/download.d.ts

@@ -0,0 +1,52 @@
+import type { DownloadProgress } from '@/types';
+export type FetchResourceResult = {
+    type: 'json';
+    data: unknown;
+    contentType: string;
+    contentEncoding?: string;
+} | {
+    type: 'image' | 'pbf' | 'other';
+    data: ArrayBuffer;
+    contentType: string;
+    contentEncoding?: string;
+};
+export declare function fetchResource(url: string): Promise<{
+    type: 'image' | 'pbf';
+    data: ArrayBuffer;
+}>;
+/**
+ * Enhanced fetch with retry logic and timeout
+ */
+export declare function fetchResourceWithRetry(url: string, options?: {
+    retries?: number;
+    retryDelay?: number;
+    timeout?: number;
+}): Promise<FetchResourceResult>;
+/**
+ * Enhanced fetch with retry logic and timeout that returns Response object
+ */
+export declare function fetchWithRetry(url: string, options?: {
+    retries?: number;
+    retryDelay?: number;
+    timeout?: number;
+}): Promise<Response>;
+/**
+ * Process items in batches with concurrency control
+ */
+export declare function processBatch<T, R>(items: T[], processor: (item: T) => Promise<R>, options?: {
+    batchSize?: number;
+    onProgress?: (completed: number, total: number) => void;
+    onError?: (error: Error, item: T) => void;
+}): Promise<R[]>;
+/**
+ * Create a progress tracker
+ */
+export declare function createProgressTracker(total: number): {
+    progress: DownloadProgress;
+    update: (increment?: number, currentItem?: string, error?: string) => void;
+    getProgress: () => DownloadProgress;
+};
+/**
+ * Validate resource data
+ */
+export declare function validateResource(data: ArrayBuffer, type: string): boolean;

package/dist/utils/errorHandling.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Error handling utilities
+ * Provides consistent error handling patterns across the application
+ */
+/**
+ * Error types for categorization
+ */
+export declare enum ErrorType {
+    /** Network-related errors */
+    NETWORK = "NETWORK",
+    /** Storage/IndexedDB errors */
+    STORAGE = "STORAGE",
+    /** Validation errors */
+    VALIDATION = "VALIDATION",
+    /** Parsing/Format errors */
+    PARSE = "PARSE",
+    /** Quota exceeded errors */
+    QUOTA = "QUOTA",
+    /** Unknown errors */
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Categorized error with additional context
+ */
+export declare class CategorizedError extends Error {
+    readonly type: ErrorType;
+    readonly originalError?: unknown | undefined;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, type: ErrorType, originalError?: unknown | undefined, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Categorize an error based on its properties
+ */
+export declare function categorizeError(error: unknown): ErrorType;
+/**
+ * Get user-friendly error message based on error type
+ */
+export declare function getUserErrorMessage(error: unknown): string;
+/**
+ * Safely execute a function and return a result or error
+ */
+export declare function safeExecute<T>(fn: () => Promise<T>, context?: string): Promise<{
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: CategorizedError;
+}>;
+/**
+ * Log error with appropriate level based on error type
+ */
+export declare function logError(error: unknown, context?: string): void;
+/**
+ * Check if error is retryable
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Aggregate multiple errors into a summary
+ */
+export declare function aggregateErrors(errors: Array<{
+    url: string;
+    error: string;
+}>): {
+    total: number;
+    byType: Record<ErrorType, number>;
+    summary: string;
+};

package/dist/utils/formatUtils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Formats bytes to human readable format
+ */
+export declare function formatBytes(bytes: number, decimals?: number): string;
+/**
+ * Formats a timestamp to a readable date string
+ */
+export declare function formatDate(timestamp: number): string;
+/**
+ * Formats a duration in milliseconds to human readable format
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Calculates percentage with proper formatting
+ */
+export declare function formatPercentage(value: number, total: number, decimals?: number): string;
+/**
+ * Formats a number with commas for thousands separator
+ */
+export declare function formatNumber(num: number): string;
+/**
+ * Truncates text to specified length with ellipsis
+ */
+export declare function truncateText(text: string, maxLength: number): string;

package/dist/utils/formatting.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Formatting utilities for the offline manager
+ */
+/**
+ * Format bytes to human readable string
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Format date to human readable string
+ */
+export declare function formatDate(date: number | Date): string;
+/**
+ * Format date and time to human readable string
+ */
+export declare function formatDateTime(timestamp: number): string;
+/**
+ * Format duration in milliseconds to human readable string
+ */
+export declare function formatDuration(milliseconds: number): string;
+/**
+ * Format number with thousands separator
+ */
+export declare function formatNumber(num: number): string;
+/**
+ * Format percentage
+ */
+export declare function formatPercentage(value: number, total: number): string;
+/**
+ * Format coordinates to a readable string
+ */
+export declare function formatCoordinates(bounds: [[number, number], [number, number]]): string;

package/dist/utils/icons.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Tabler Icons utility for the offline map manager
+ * Provides consistent icon usage throughout the application using inline SVG strings
+ */
+/**
+ * Configuration for icon rendering
+ */
+interface IconConfig {
+    size?: number;
+    color?: string;
+    className?: string;
+    style?: string;
+}
+/**
+ * Available icons in the application
+ */
+export declare const icons: {
+    mapPin: (config?: IconConfig) => string;
+    focus: (config?: IconConfig) => string;
+    download: (config?: IconConfig) => string;
+    trash: (config?: IconConfig) => string;
+    eye: (config?: IconConfig) => string;
+    refresh: (config?: IconConfig) => string;
+    cleaning: (config?: IconConfig) => string;
+    plus: (config?: IconConfig) => string;
+    x: (config?: IconConfig) => string;
+    check: (config?: IconConfig) => string;
+    checkCircle: (config?: IconConfig) => string;
+    alertTriangle: (config?: IconConfig) => string;
+    fileText: (config?: IconConfig) => string;
+    clock: (config?: IconConfig) => string;
+    cloud: (config?: IconConfig) => string;
+    deviceMobile: (config?: IconConfig) => string;
+    deviceFloppy: (config?: IconConfig) => string;
+    settings: (config?: IconConfig) => string;
+    map: (config?: IconConfig) => string;
+    moon: (config?: IconConfig) => string;
+    sun: (config?: IconConfig) => string;
+    upload: (config?: IconConfig) => string;
+    infoCircle: (config?: IconConfig) => string;
+};
+/**
+ * Utility type for icon names
+ */
+export type IconName = keyof typeof icons;
+/**
+ * Helper function to get an icon by name
+ */
+export declare function getIcon(name: IconName, config?: IconConfig): string;
+export {};

package/dist/utils/idbFetchHandler.d.ts

@@ -0,0 +1,2 @@
+export declare function idbFetchHandler(url: string, init?: RequestInit): Promise<Response>;
+export declare function listTileKeysInIDB(styleId: string, sourceId: string, zoom: number): Promise<string[]>;

package/dist/utils/index.d.ts

@@ -0,0 +1,13 @@
+export * from './asyncUtils';
+export * from './download';
+export * from './formatting';
+export * from './icons';
+export * from './idbFetchHandler';
+export * from './styleProviderUtils';
+export * from './styleUtils';
+export * from './cleanupCompressedTiles';
+export * from './logger';
+export * from './constants';
+export * from './errorHandling';
+export * from './validation';
+export * from './performance';

package/dist/utils/logger.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Centralized logging utility with configurable log levels
+ * Following the project guidelines: only console.warn and console.error in production
+ */
+export declare enum LogLevel {
+    ERROR = 0,
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3
+}
+declare class Logger {
+    private level;
+    private isDevelopment;
+    setLevel(level: LogLevel): void;
+    getLevel(): LogLevel;
+    /**
+     * Log error messages (always shown)
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Log warning messages (shown in production)
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log info messages (development only)
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log debug messages (development only, verbose)
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log success messages
+     */
+    success(message: string, ...args: unknown[]): void;
+    /**
+     * Create a scoped logger with a prefix
+     */
+    scope(prefix: string): ScopedLogger;
+}
+declare class ScopedLogger {
+    private prefix;
+    private logger;
+    constructor(prefix: string, logger: Logger);
+    error(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+    success(message: string, ...args: unknown[]): void;
+}
+export declare const logger: Logger;
+export { ScopedLogger };

package/dist/utils/performance.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Performance monitoring utilities
+ * Track and measure application performance
+ */
+import { formatBytes, formatDuration } from './formatting';
+export { formatBytes, formatDuration };
+/**
+ * Performance metric data
+ */
+export interface PerformanceMetric {
+    /** Operation name */
+    name: string;
+    /** Start timestamp in milliseconds */
+    startTime: number;
+    /** End timestamp in milliseconds */
+    endTime?: number;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Download performance statistics
+ */
+export interface DownloadPerformance {
+    /** Total items downloaded */
+    totalItems: number;
+    /** Total bytes downloaded */
+    totalBytes: number;
+    /** Total time in milliseconds */
+    totalTime: number;
+    /** Average download speed in bytes/second */
+    averageSpeed: number;
+    /** Average time per item in milliseconds */
+    averageTimePerItem: number;
+    /** Fastest download time in milliseconds */
+    fastestItem?: number;
+    /** Slowest download time in milliseconds */
+    slowestItem?: number;
+    /** Success rate percentage */
+    successRate: number;
+}
+/**
+ * Storage performance monitor
+ */
+export interface StorageMetrics {
+    /** Current usage in bytes */
+    used: number;
+    /** Total quota in bytes */
+    quota: number;
+    /** Usage percentage */
+    usagePercentage: number;
+    /** Available space in bytes */
+    available: number;
+    /** Estimated items that can be stored */
+    estimatedCapacity?: number;
+}
+/**
+ * Performance timer for measuring operation duration
+ */
+export declare class PerformanceTimer {
+    private metrics;
+    /**
+     * Start timing an operation
+     * @param name - Operation name
+     * @param metadata - Optional metadata to store with the metric
+     */
+    start(name: string, metadata?: Record<string, unknown>): void;
+    /**
+     * Stop timing an operation and return the duration
+     * @param name - Operation name
+     * @returns Duration in milliseconds, or undefined if not started
+     */
+    stop(name: string): number | undefined;
+    /**
+     * Get a metric by name
+     * @param name - Operation name
+     * @returns Metric data or undefined
+     */
+    getMetric(name: string): PerformanceMetric | undefined;
+    /**
+     * Get all completed metrics
+     * @returns Array of completed metrics
+     */
+    getAllMetrics(): PerformanceMetric[];
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+    /**
+     * Get summary statistics
+     */
+    getSummary(): {
+        total: number;
+        totalDuration: number;
+        averageDuration: number;
+        fastest: PerformanceMetric | null;
+        slowest: PerformanceMetric | null;
+    };
+}
+/**
+ * Download performance tracker
+ */
+export declare class DownloadPerformanceTracker {
+    private items;
+    /**
+     * Record a download
+     * @param size - Size in bytes
+     * @param time - Time taken in milliseconds
+     * @param success - Whether the download succeeded
+     */
+    recordDownload(size: number, time: number, success?: boolean): void;
+    /**
+     * Get performance statistics
+     */
+    getStats(): DownloadPerformance;
+    /**
+     * Get human-readable speed
+     */
+    getFormattedSpeed(): string;
+    /**
+     * Clear all recorded downloads
+     */
+    clear(): void;
+}
+/**
+ * Get current storage metrics
+ */
+export declare function getStorageMetrics(): Promise<StorageMetrics>;
+/**
+ * Monitor operation performance with automatic timing
+ * @param name - Operation name
+ * @param operation - Async operation to monitor
+ * @param metadata - Optional metadata
+ * @returns Operation result and performance metric
+ */
+export declare function monitorPerformance<T>(name: string, operation: () => Promise<T>, metadata?: Record<string, unknown>): Promise<{
+    result: T;
+    metric: PerformanceMetric;
+}>;
+/**
+ * Create a rate limiter for controlling request frequency
+ */
+export declare class RateLimiter {
+    private maxConcurrent;
+    private delayMs;
+    private queue;
+    private activeRequests;
+    constructor(maxConcurrent?: number, delayMs?: number);
+    /**
+     * Execute an operation with rate limiting
+     * @param operation - Async operation to execute
+     * @returns Operation result
+     */
+    execute<T>(operation: () => Promise<T>): Promise<T>;
+    /**
+     * Get current queue length
+     */
+    getQueueLength(): number;
+    /**
+     * Get number of active requests
+     */
+    getActiveCount(): number;
+}

package/dist/utils/styleProviderUtils.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Style Provider Detection and Handling Utilities
+ * Supports both Mapbox GL and MapLibre GL styles
+ */
+import type { BaseStyle, StyleProvider } from '../types/style';
+/**
+ * Detect the style provider based on the style URL or content
+ */
+export declare function detectStyleProvider(styleUrl: string, style?: BaseStyle): StyleProvider;
+/**
+ * Extract access token from Mapbox style URL
+ */
+export declare function extractAccessToken(styleUrl: string): string | null;
+/**
+ * Validate if a style URL requires authentication
+ */
+export declare function requiresAuthentication(styleUrl: string, provider: StyleProvider): boolean;
+/**
+ * Normalize style URL for consistent processing
+ */
+export declare function normalizeStyleUrl(styleUrl: string, accessToken?: string): string;
+/**
+ * Process style sources for offline compatibility
+ */
+export declare function processStyleSources(style: BaseStyle, provider: StyleProvider, accessToken?: string): BaseStyle;
+/**
+ * Enhanced style validation for different providers
+ */
+export declare function validateStyleForProvider(style: BaseStyle, provider: StyleProvider): {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+};
+/**
+ * Get default style configuration for a provider
+ */
+export declare function getDefaultStyleConfig(provider: StyleProvider): {
+    requiresAuth: boolean;
+    defaultSources: string[];
+    supportedFormats: string[];
+    maxZoom: number;
+};

package/dist/utils/styleUtils.d.ts

@@ -0,0 +1,35 @@
+import type { MapboxStyle } from '../types/style';
+/**
+ * Patches a MapboxStyle for offline use by replacing URLs with IndexedDB references
+ */
+export declare function patchStyleForOffline(style: MapboxStyle, downloadId: string, maxZoom?: number, tileExtension?: string): MapboxStyle;
+/**
+ * Validates if a region configuration is valid
+ */
+export declare function validateRegion(region: unknown): boolean;
+/**
+ * Calculates the bounding box area in square degrees
+ */
+export declare function calculateBBoxArea(bounds: [[number, number], [number, number]]): number;
+/**
+ * Estimates the number of tiles for a given region and zoom range
+ */
+export declare function estimateTileCount(bounds: [[number, number], [number, number]], minZoom: number, maxZoom: number): number;
+/**
+ * Extracts all fontstacks from a style object and generates all glyph URLs for a set of Unicode ranges.
+ * @param style The style JSON object
+ * @param glyphsUrlTemplate The glyphs URL template from the style (e.g. .../fonts/{fontstack}/{range}.pbf)
+ * @param ranges Optional array of ranges (default: [0-255, 256-511, ..., 61440-61695])
+ */
+export declare function generateGlyphUrlsFromStyle(style: {
+    layers?: Array<{
+        layout?: {
+            [key: string]: unknown;
+        };
+    }>;
+}, glyphsUrlTemplate: string, ranges?: Array<[number, number]>): string[];
+/**
+ * Extract tile coordinates from a tile URL
+ * e.g., "https://tiles-a.basemaps.cartocdn.com/vectortiles/carto.streets/v1/0/0/0.mvt" -> "0/0/0.mvt"
+ */
+export declare function extractTileKey(url: string): string;