map-gl-offline 0.8.6 → 0.8.8

package/README.md

@@ -137,10 +137,71 @@ await offlineManager.cleanupExpiredRegions();
 await offlineManager.setupAutoCleanup({ intervalHours: 24, maxAge: 30 });
 ```
 
+### Multi-region downloads (global overview + city detail)
+
+For app shipping use cases — a low-zoom basemap of the world, plus high-zoom detail in the cities your users actually visit — set `multipleRegions: true` on each region so the manager reuses the shared style/sprites/glyphs across downloads. The exported `BoundingBox` type keeps city lists from being widened to `number[][]`, so you can write the bounds inline without `as` casts.
+
+```typescript
+import mapboxgl from 'mapbox-gl';
+import {
+  OfflineMapManager,
+  type BoundingBox,
+  type DownloadRegionProgress,
+} from 'map-gl-offline';
+
+const offlineManager = new OfflineMapManager();
+const STYLE_URL = 'mapbox://styles/mapbox/standard';
+
+const opts = {
+  accessToken: mapboxgl.accessToken, // `string | null` is accepted — no cast needed
+  onProgress: ({ phase, percentage, message }: DownloadRegionProgress) =>
+    console.log(`[${phase}] ${percentage.toFixed(1)}% ${message ?? ''}`),
+};
+
+// 1) Whole planet, low zoom only (~5,500 tiles/source) — countries, major cities
+await offlineManager.downloadRegion(
+  {
+    id: 'global-overview',
+    name: 'Global overview',
+    bounds: [[-180, -85.0511], [180, 85.0511]], // ±85.0511° = Web Mercator cutoff
+    minZoom: 0,
+    maxZoom: 6,
+    styleUrl: STYLE_URL,
+    multipleRegions: true,
+  },
+  opts,
+);
+
+// 2) High-detail per city — tight bbox per place your users actually go
+const cities: Array<{ id: string; name: string; bounds: BoundingBox }> = [
+  { id: 'nyc',    name: 'New York', bounds: [[-74.05, 40.68], [-73.90, 40.82]] },
+  { id: 'london', name: 'London',   bounds: [[-0.25, 51.43],  [0.02, 51.57]]  },
+];
+
+for (const city of cities) {
+  await offlineManager.downloadRegion(
+    {
+      id: city.id,
+      name: city.name,
+      bounds: city.bounds,
+      minZoom: 6,   // overlaps the overview's maxZoom — clean handoff, no seam
+      maxZoom: 14,  // street-level detail
+      styleUrl: STYLE_URL,
+      multipleRegions: true,
+    },
+    opts,
+  );
+}
+```
+
+> **Don't download the whole globe at high zoom.** The tile count quadruples per zoom level — `minZoom: 0, maxZoom: 15` for the whole planet is ~1.4 billion tiles per source, which will blow past IndexedDB quota and may violate provider TOS. The two-tier setup above gives countries-everywhere plus streets-where-it-matters for a few thousand tiles total.
+
 ### Sparse-source detection
 
 For composite styles (e.g. Mapbox Standard) that reference sparse tilesets like `indoor-v3` or `landmark-pois-v1`, the tile downloader probes start/middle/end tiles per source and drops any that return majority-404. Disable with `tileOptions: { probeSourcesBeforeDownload: false }`.
 
+Three Mapbox Standard sub-tilesets are sparse-by-design across the planet — `mapbox.indoor-v3`, `mapbox.landmark-pois-v1`, `mapbox.procedural-buildings-v1`. Since 0.8.8 these are hard-skipped **before** the probe step so no network request is issued (and no 404s land in devtools). Opt out with `tileOptions: { skipKnownSparseSources: false }` to run them through the probe path instead.
+
 ### Recovering from an incompatible DB
 
 If another app on the same origin has created `offline-map-db` at a newer version, `dbPromise` throws a typed error. Offer a reset UX:

package/dist/index.esm.js

@@ -160,6 +160,23 @@ const MAPBOX_API = {
     MODELS_PATH: '/models/v1',
     PROTOCOL: 'mapbox://',
 };
+/**
+ * Mapbox Standard sub-tilesets that are sparse-by-design across the planet.
+ * These only have tiles where the underlying feature (indoor venues, landmark
+ * POIs, 3D procedural buildings) actually exists, and return 404 for nearly
+ * every other coordinate. The tile downloader pre-skips any source whose tile
+ * URL templates reference one of these tileset IDs, so we never issue probe
+ * or download requests for them — eliminating the 404 noise in devtools.
+ *
+ * Matching is done against the tileset segment of the tile URL template
+ * (e.g. `https://api.mapbox.com/v4/mapbox.indoor-v3/{z}/{x}/{y}.vector.pbf`
+ * or `mapbox://mapbox.indoor-v3`).
+ */
+const MAPBOX_STANDARD_SPARSE_TILESETS = [
+    'mapbox.indoor-v3',
+    'mapbox.landmark-pois-v1',
+    'mapbox.procedural-buildings-v1',
+];
 // Map Providers
 const MAP_PROVIDERS = {
     AUTO: 'auto',
@@ -6124,6 +6141,26 @@ const getExpiredResourceCount = () => cleanupService.getExpiredResourceCount();
 const cleanupExpiredTiles = (styleId) => cleanupService.cleanupExpiredTiles(styleId);
 
 const tileLogger = logger.scope('TileService');
+/**
+ * Match a tile-URL template against the known-sparse Mapbox Standard
+ * sub-tilesets. Catches:
+ *   - `mapbox://<tileset>` — original style source URL.
+ *   - `.../v4/<tileset>.json...` — resolved TileJSON URL produced when the
+ *     library resolves a `mapbox://` source URL into an HTTPS one.
+ *   - `.../v4/<tileset>/{z}/{x}/{y}...` — resolved tile-template URL.
+ */
+function urlReferencesKnownSparseTileset(template) {
+    return MAPBOX_STANDARD_SPARSE_TILESETS.some(tileset => {
+        if (template.includes(`mapbox://${tileset}`))
+            return true;
+        // `/v4/<tileset>` followed by `/` (tile template) or `.` (e.g. `.json`)
+        const idx = template.indexOf(`/${tileset}`);
+        if (idx === -1)
+            return false;
+        const next = template[idx + tileset.length + 1];
+        return next === '/' || next === '.';
+    });
+}
 /**
  * Service for managing offline map tiles
  * Handles downloading, storing, and retrieving map tiles from IndexedDB
@@ -6141,7 +6178,7 @@ class TileService {
      */
     async downloadTiles(region, style, styleId, options = {}) {
         const db = await this.db;
-        const { onProgress, batchSize = 10, maxRetries = 3, skipExisting = true, timeout = 10000, retryDelay = 1000, priorityZoomLevels = [], storageQuotaCheck = true, validateTiles = false, compressTiles = false, bandwidthLimit, probeSourcesBeforeDownload = true, } = options;
+        const { onProgress, batchSize = 10, maxRetries = 3, skipExisting = true, timeout = 10000, retryDelay = 1000, priorityZoomLevels = [], storageQuotaCheck = true, validateTiles = false, compressTiles = false, bandwidthLimit, probeSourcesBeforeDownload = true, skipKnownSparseSources = true, } = options;
         const startTime = Date.now();
         let totalSize = 0;
         let downloadedTiles = 0;
@@ -6245,6 +6282,16 @@ class TileService {
                 tileLogger.debug(`Skipping source ${sourceId}: no tiles array`);
                 continue;
             }
+            // Pre-skip Mapbox Standard sparse sub-tilesets (indoor-v3 etc.) before
+            // issuing any network request. They 404 for nearly every coord in a
+            // typical region; the downstream probe step would catch them, but the
+            // probe itself logs 404s in devtools. Matching here keeps the console
+            // clean.
+            if (skipKnownSparseSources &&
+                tiles.some(template => urlReferencesKnownSparseTileset(template))) {
+                tileLogger.info(`Skipping source "${sourceId}" — references a known sparse Mapbox Standard sub-tileset (no probe/download issued)`);
+                continue;
+            }
             const sourceMinZ = Math.ceil(sourceConfig.minzoom ?? region.minZoom);
             const sourceMaxZ = Math.floor(sourceConfig.maxzoom ?? region.maxZoom);
             let coordsForSource = tileCoords.filter(coord => coord.z >= sourceMinZ && coord.z <= sourceMaxZ);
@@ -7022,7 +7069,8 @@ var tileService$1 = /*#__PURE__*/Object.freeze({
     downloadTiles: downloadTiles,
     getTileAnalytics: getTileAnalytics,
     getTileStats: getTileStats,
-    tileService: tileService
+    tileService: tileService,
+    urlReferencesKnownSparseTileset: urlReferencesKnownSparseTileset
 });
 
 const glyphLogger = logger.scope('GlyphService');
@@ -11365,7 +11413,7 @@ class PanelRenderer extends BaseComponent {
                         try {
                             const { loadStyleById } = await Promise.resolve().then(function () { return styleService; });
                             const styleEntry = await loadStyleById(region.styleId);
-                            accessToken = styleEntry?.accessToken;
+                            accessToken = styleEntry?.accessToken ?? undefined;
                         }
                         catch {
                             panelLogger.warn('Could not retrieve access token from stored style');
@@ -13977,5 +14025,5 @@ class OfflineManagerControl {
     }
 }
 
-export { AnalyticsService, CONTENT_TYPES, CategorizedError, CleanupService, DB_NAME, DB_VERSION, DOWNLOAD_DEFAULTS, ERROR_MESSAGES, ErrorType, FontService, GLYPH_BLOCK_SIZE, GLYPH_CONFIG, GZIP_MAGIC_BYTES, GlyphService, ImportExportService, LogLevel, MAPBOX_API, MAPBOX_CACHE_TTL, MAPBOX_CLASSIC_STYLES, MAP_PROVIDERS, MAX_GLYPH_CODEPOINT, MaintenanceService, ModelService, OfflineManagerControl, OfflineMapDBVersionError, OfflineMapManager, RESOURCE_TYPES, RegionService, ResourceService, STORAGE_CONFIG, STORE_NAMES, STYLE_CONFIG, SUCCESS_MESSAGES, ScopedLogger, SpriteService, TILE_CONFIG, TileService, URL_SCHEMES, VALIDATION_PATTERNS, applyProxy, categorizeError, cleanupCompressedTiles, cleanupExpiredTiles, cleanupOldFonts, cleanupOldGlyphs, cleanupOldModels, cleanupOldSprites, cleanupOldStyles, cleanupOldTiles, cleanupService, clearAllCaches, configureLogger, configureProxy, configureSqlJs, convertStyleForServiceWorker, countCompressedTiles, createProgressTracker, createTileKey, dbPromise, OfflineMapManager as default, deleteStyleById, deleteStyles, deriveTileExtension, detectCssPrefix, detectStyleProvider, downloadFonts, downloadGlyphs, downloadModels, downloadSprites, downloadStyleWithProvider, downloadStyles, downloadTiles, escapeHtml$1 as escapeHtml, extractAccessToken, extractAllFontNames, extractFontNamesFromTextField, extractTileExtensionFromUrl, fetchResourceWithRetry, fetchWithRetry, fontService, formatBytes, formatDate, generateGlyphUrlsFromStyle, getExpiredResourceCount, getFontAnalytics, getFontStats, getGlyphAnalytics, getGlyphStats, getIcon, getModel, getModelStats, getRegionAnalytics, getSpriteAnalytics, getSpriteStats, getSqlJs, getStyleStats, getTileAnalytics, getTileStats, getUrlHostname, getUserErrorMessage, glyphService, hasImports, hostMatches, i18n, icons, idbFetchHandler, isMapboxHost, isMapboxProtocol, isStyleDownloaded, loadAllStoredRegions, loadGlyphs, loadStyleById, loadStyles, logger, modelKeyBelongsToStyle, modelService, normalizeSpriteProperty, normalizeStyleUrl, optimizeStorage, parseCacheExpiry, parseTileKey, patchStyleForOffline, performCleanup, processBatch, processStyleSources, registerOfflineServiceWorker, resetOfflineMapDB, resolveImports, resolveMapboxUrl, resourceKeyBelongsToStyle, rewriteMapboxCdnTileUrl, safeExecute, sanitizeIndoorExpressions, setupAutoCleanup, spriteService, stopAutoCleanup, t, tileService, unregisterOfflineServiceWorker, validateBounds, validateRegionOptions, validateResource, validateStyleForProvider, validateZoomLevels, verifyAndRepairFonts, verifyAndRepairGlyphs, verifyAndRepairModels, verifyAndRepairSprites };
+export { AnalyticsService, CONTENT_TYPES, CategorizedError, CleanupService, DB_NAME, DB_VERSION, DOWNLOAD_DEFAULTS, ERROR_MESSAGES, ErrorType, FontService, GLYPH_BLOCK_SIZE, GLYPH_CONFIG, GZIP_MAGIC_BYTES, GlyphService, ImportExportService, LogLevel, MAPBOX_API, MAPBOX_CACHE_TTL, MAPBOX_CLASSIC_STYLES, MAPBOX_STANDARD_SPARSE_TILESETS, MAP_PROVIDERS, MAX_GLYPH_CODEPOINT, MaintenanceService, ModelService, OfflineManagerControl, OfflineMapDBVersionError, OfflineMapManager, RESOURCE_TYPES, RegionService, ResourceService, STORAGE_CONFIG, STORE_NAMES, STYLE_CONFIG, SUCCESS_MESSAGES, ScopedLogger, SpriteService, TILE_CONFIG, TileService, URL_SCHEMES, VALIDATION_PATTERNS, applyProxy, categorizeError, cleanupCompressedTiles, cleanupExpiredTiles, cleanupOldFonts, cleanupOldGlyphs, cleanupOldModels, cleanupOldSprites, cleanupOldStyles, cleanupOldTiles, cleanupService, clearAllCaches, configureLogger, configureProxy, configureSqlJs, convertStyleForServiceWorker, countCompressedTiles, createProgressTracker, createTileKey, dbPromise, OfflineMapManager as default, deleteStyleById, deleteStyles, deriveTileExtension, detectCssPrefix, detectStyleProvider, downloadFonts, downloadGlyphs, downloadModels, downloadSprites, downloadStyleWithProvider, downloadStyles, downloadTiles, escapeHtml$1 as escapeHtml, extractAccessToken, extractAllFontNames, extractFontNamesFromTextField, extractTileExtensionFromUrl, fetchResourceWithRetry, fetchWithRetry, fontService, formatBytes, formatDate, generateGlyphUrlsFromStyle, getExpiredResourceCount, getFontAnalytics, getFontStats, getGlyphAnalytics, getGlyphStats, getIcon, getModel, getModelStats, getRegionAnalytics, getSpriteAnalytics, getSpriteStats, getSqlJs, getStyleStats, getTileAnalytics, getTileStats, getUrlHostname, getUserErrorMessage, glyphService, hasImports, hostMatches, i18n, icons, idbFetchHandler, isMapboxHost, isMapboxProtocol, isStyleDownloaded, loadAllStoredRegions, loadGlyphs, loadStyleById, loadStyles, logger, modelKeyBelongsToStyle, modelService, normalizeSpriteProperty, normalizeStyleUrl, optimizeStorage, parseCacheExpiry, parseTileKey, patchStyleForOffline, performCleanup, processBatch, processStyleSources, registerOfflineServiceWorker, resetOfflineMapDB, resolveImports, resolveMapboxUrl, resourceKeyBelongsToStyle, rewriteMapboxCdnTileUrl, safeExecute, sanitizeIndoorExpressions, setupAutoCleanup, spriteService, stopAutoCleanup, t, tileService, unregisterOfflineServiceWorker, urlReferencesKnownSparseTileset, validateBounds, validateRegionOptions, validateResource, validateStyleForProvider, validateZoomLevels, verifyAndRepairFonts, verifyAndRepairGlyphs, verifyAndRepairModels, verifyAndRepairSprites };
 //# sourceMappingURL=index.esm.js.map