styled-map-package-api 5.0.0-pre.2 → 5.0.0-pre.4

package/lib/download.js

@@ -0,0 +1,125 @@
+import { StyleDownloader } from './style-downloader.js'
+import { readableFromAsync } from './utils/streams.js'
+import { Writer } from './writer.js'
+
+/**
+ * @typedef {object} DownloadProgress
+ * @property {import('./tile-downloader.js').TileDownloadStats & { done: boolean }} tiles
+ * @property {{ done: boolean }} style
+ * @property {{ downloaded: number, done: boolean }} sprites
+ * @property {import('./style-downloader.js').GlyphDownloadStats & { done: boolean }} glyphs
+ * @property {{ totalBytes: number, done: boolean }} output
+ * @property {number} elapsedMs
+ */
+
+/**
+ * Download a map style and its resources for a given bounding box and max zoom
+ * level. Returns a readable stream of a "styled map package", a zip file
+ * containing all the resources needed to serve the style offline.
+ *
+ * @param {object} opts
+ * @param {Readonly<import("./utils/geo.js").BBox>} opts.bbox Bounding box to download tiles for
+ * @param {number} opts.maxzoom Max zoom level to download tiles for
+ * @param {string} opts.styleUrl URL of the style to download
+ * @param { (progress: DownloadProgress) => void } [opts.onprogress] Optional callback for reporting progress
+ * @param {string} [opts.accessToken]
+ * @param {boolean} [opts.skipLocalGlyphs] Skip glyph ranges rendered client-side by MapLibre GL via localIdeographFontFamily (CJK, Hangul, Kana, Yi, etc.)
+ * @param {boolean} [opts.dedupe] When true, duplicate tiles are stored only once (see {@link Writer})
+ * @returns {import('./types.js').DownloadStream} Readable stream of the output styled map file
+ */
+export function download({
+  bbox,
+  maxzoom,
+  styleUrl,
+  onprogress,
+  accessToken,
+  skipLocalGlyphs,
+  dedupe,
+}) {
+  const downloader = new StyleDownloader(styleUrl, {
+    concurrency: 24,
+    mapboxAccessToken: accessToken,
+  })
+
+  let start = Date.now()
+  /** @type {DownloadProgress} */
+  let progress = {
+    tiles: { downloaded: 0, totalBytes: 0, total: 0, skipped: 0, done: false },
+    style: { done: false },
+    sprites: { downloaded: 0, done: false },
+    glyphs: { downloaded: 0, total: 0, totalBytes: 0, done: false },
+    output: { totalBytes: 0, done: false },
+    elapsedMs: 0,
+  }
+
+  /** @param {Partial<DownloadProgress>} update */
+  function handleProgress(update) {
+    progress = { ...progress, ...update, elapsedMs: Date.now() - start }
+    onprogress?.(progress)
+  }
+
+  const sizeCounter = new TransformStream({
+    transform(chunk, controller) {
+      handleProgress({
+        output: {
+          totalBytes: progress.output.totalBytes + chunk.byteLength,
+          done: false,
+        },
+      })
+      controller.enqueue(chunk)
+    },
+    flush() {
+      handleProgress({ output: { ...progress.output, done: true } })
+    },
+  })
+
+  ;(async () => {
+    /** @type {Writer | undefined} */
+    let writer
+    try {
+      const style = await downloader.getStyle()
+      writer = new Writer(style, { dedupe: !!dedupe })
+      handleProgress({ style: { done: true } })
+      // Pipe the output stream through the size counter (fire-and-forget;
+      // errors propagate via writer.abort())
+      writer.outputStream.pipeTo(sizeCounter.writable).catch(() => {})
+
+      for await (const spriteInfo of downloader.getSprites()) {
+        await writer.addSprite(spriteInfo)
+        handleProgress({
+          sprites: { downloaded: progress.sprites.downloaded + 1, done: false },
+        })
+      }
+      handleProgress({ sprites: { ...progress.sprites, done: true } })
+
+      const tiles = downloader.getTiles({
+        bounds: bbox,
+        maxzoom,
+        onprogress: (tileStats) =>
+          handleProgress({ tiles: { ...tileStats, done: false } }),
+      })
+      await readableFromAsync(tiles).pipeTo(
+        writer.createTileWriteStream({ concurrency: 24 }),
+      )
+      handleProgress({ tiles: { ...progress.tiles, done: true } })
+
+      const glyphs = downloader.getGlyphs({
+        skipLocalGlyphs,
+        onprogress: (glyphStats) =>
+          handleProgress({ glyphs: { ...glyphStats, done: false } }),
+      })
+      await readableFromAsync(glyphs).pipeTo(writer.createGlyphWriteStream())
+      handleProgress({ glyphs: { ...progress.glyphs, done: true } })
+
+      writer.finish()
+    } catch (err) {
+      if (writer) {
+        writer.abort(/** @type {Error} */ (err))
+      } else {
+        sizeCounter.writable.abort(/** @type {Error} */ (err))
+      }
+    }
+  })()
+
+  return sizeCounter.readable
+}

package/lib/fallbacks.js

@@ -0,0 +1,157 @@
+/** @import { SMPSource } from './types.js' */
+
+/**
+ * Minimal valid 1×1 transparent PNG (67 bytes).
+ * @type {Uint8Array}
+ */
+const EMPTY_PNG = /* @__PURE__ */ fromHex(
+  '89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c489' +
+    '0000000a49444154789c626000000002000198e195280000000049454e44ae426082',
+)
+
+/**
+ * Minimal valid 1×1 transparent WebP (VP8L lossless, 34 bytes).
+ * @type {Uint8Array}
+ */
+const EMPTY_WEBP = /* @__PURE__ */ fromHex(
+  '524946461a000000574542505650384c0d0000002f00000010071011118888fe0700',
+)
+
+/**
+ * Empty gzip stream (gzipped empty buffer, 20 bytes). Used for empty MVT
+ * tiles and empty glyph PBF ranges.
+ * @type {Uint8Array}
+ */
+const EMPTY_GZ = /* @__PURE__ */ fromHex(
+  '1f8b080000000000001303000000000000000000',
+)
+
+/**
+ * Empty GeoJSON FeatureCollection as UTF-8 bytes.
+ * @type {Uint8Array}
+ */
+const EMPTY_JSON = /* @__PURE__ */ new TextEncoder().encode(
+  '{"type":"FeatureCollection","features":[]}',
+)
+
+/** @type {Record<string, { body: Uint8Array, contentType: string, contentEncoding?: string }>} */
+const TILE_FORMATS = {
+  mvt: {
+    body: EMPTY_GZ,
+    contentType: 'application/vnd.mapbox-vector-tile',
+    contentEncoding: 'gzip',
+  },
+  png: {
+    body: EMPTY_PNG,
+    contentType: 'image/png',
+  },
+  jpg: {
+    // No such thing as "empty" JPEG — serve a transparent PNG instead.
+    // MapLibre handles the content-type mismatch gracefully.
+    body: EMPTY_PNG,
+    contentType: 'image/png',
+  },
+  webp: {
+    body: EMPTY_WEBP,
+    contentType: 'image/webp',
+  },
+  json: {
+    body: EMPTY_JSON,
+    contentType: 'application/json; charset=utf-8',
+  },
+}
+
+/**
+ * Detect the tile format from a source's tile URL template.
+ *
+ * @param {SMPSource} source
+ * @returns {string | null}
+ */
+function detectTileFormat(source) {
+  const tiles = 'tiles' in source ? source.tiles : undefined
+  if (!tiles || tiles.length === 0) return null
+  const url = tiles[0]
+  if (
+    url.endsWith('.mvt.gz') ||
+    url.endsWith('.mvt') ||
+    url.endsWith('.pbf.gz') ||
+    url.endsWith('.pbf')
+  )
+    return 'mvt'
+  if (url.endsWith('.png')) return 'png'
+  if (url.endsWith('.jpg') || url.endsWith('.jpeg')) return 'jpg'
+  if (url.endsWith('.webp')) return 'webp'
+  if (url.endsWith('.json') || url.endsWith('.geojson')) return 'json'
+  // Default based on source type
+  if (source.type === 'vector') return 'mvt'
+  if (source.type === 'raster') return 'png'
+  return null
+}
+
+/**
+ * Fallback tile handler for use with `createServer({ fallbackTile })`.
+ * Returns an appropriate empty tile based on the source's tile format:
+ * - vector sources → empty gzipped MVT
+ * - raster PNG sources → 1×1 transparent PNG
+ * - raster WebP sources → 1×1 transparent WebP
+ * - raster JPEG sources → 1×1 transparent PNG (no such thing as transparent JPEG)
+ *
+ * @param {{ x: number, y: number, z: number }} _tileId
+ * @param {{ sourceId: string, source: SMPSource }} sourceInfo
+ * @returns {Response}
+ */
+export function emptyTileFallback(_tileId, { source }) {
+  const format = detectTileFormat(source)
+  const tile = format && TILE_FORMATS[format]
+  if (!tile) {
+    return new Response('Not Found', { status: 404 })
+  }
+  /** @type {HeadersInit} */
+  const headers = {
+    'Content-Type': tile.contentType,
+    'Content-Length': String(tile.body.byteLength),
+    'Cache-Control': 'public, max-age=604800',
+  }
+  if (tile.contentEncoding) {
+    headers['Content-Encoding'] = tile.contentEncoding
+  }
+  return new Response(/** @type {BodyInit} */ (tile.body), {
+    status: 200,
+    headers,
+  })
+}
+
+/**
+ * Fallback glyph handler for use with `createServer({ fallbackGlyph })`.
+ * Returns an empty gzipped PBF (valid protobuf with no glyph entries), which
+ * causes MapLibre to render missing characters as blank space instead of
+ * erroring on a 404.
+ *
+ * @param {string} _fontstack
+ * @param {string} _range
+ * @returns {Response}
+ */
+// eslint-disable-next-line no-unused-vars
+export function emptyGlyphFallback(_fontstack, _range) {
+  return new Response(/** @type {BodyInit} */ (EMPTY_GZ), {
+    status: 200,
+    headers: {
+      'Content-Type': 'application/x-protobuf',
+      'Content-Encoding': 'gzip',
+      'Content-Length': String(EMPTY_GZ.byteLength),
+      'Cache-Control': 'public, max-age=604800',
+    },
+  })
+}
+
+/**
+ * @param {string} hex
+ * @returns {Uint8Array}
+ */
+function fromHex(hex) {
+  const bytes = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16)
+  }
+  return bytes
+}

package/lib/from-mbtiles.js

@@ -0,0 +1,131 @@
+import { MBTiles } from 'mbtiles-reader'
+
+import { noop } from './utils/misc.js'
+import { readableFromAsync } from './utils/streams.js'
+import { Writer } from './writer.js'
+
+const SOURCE_ID = 'mbtiles-source'
+
+/**
+ * Convert a MBTiles file to a styled map package, returned as a web
+ * ReadableStream. The async MBTiles.open() happens lazily inside the
+ * stream's start(), so this function is synchronous.
+ *
+ * Requires Node >= 20 (uses better-sqlite3 which dropped Node 18 support).
+ *
+ * @param {string | ArrayBuffer | Uint8Array} source MBTiles source — file path
+ *   (Node), OPFS path (browser Worker), or in-memory buffer.
+ * @returns {ReadableStream<Uint8Array>}
+ */
+export function fromMBTiles(source) {
+  /** @type {ReadableStreamDefaultReader<Uint8Array> | undefined} */
+  let outputReader
+  /** @type {Promise<void> | undefined} */
+  let conversionDone
+  const pipeAbort = new AbortController()
+
+  return new ReadableStream({
+    async start() {
+      const reader = await MBTiles.open(source)
+      if (reader.metadata.format === 'pbf') {
+        throw new Error('Vector MBTiles are not yet supported')
+      }
+      const {
+        name,
+        minzoom,
+        maxzoom,
+        scheme,
+        attribution,
+        description,
+        version: tilesetVersion,
+      } = reader.metadata
+      /** @type {import('@maplibre/maplibre-gl-style-spec').StyleSpecification} */
+      const style = {
+        version: 8,
+        name,
+        sources: {
+          [SOURCE_ID]: {
+            type: 'raster',
+            tileSize: 256,
+            minzoom,
+            maxzoom,
+            scheme,
+            attribution,
+          },
+        },
+        layers: [
+          {
+            id: 'background',
+            type: 'background',
+            paint: {
+              'background-color': 'white',
+            },
+          },
+          {
+            id: 'raster',
+            type: 'raster',
+            source: SOURCE_ID,
+            paint: {
+              'raster-opacity': 1,
+            },
+          },
+        ],
+      }
+
+      if (description || tilesetVersion) {
+        style.metadata = {
+          'mbtiles:description': description,
+          'mbtiles:version': tilesetVersion,
+        }
+      }
+
+      const writer = new Writer(style)
+      outputReader = writer.outputStream.getReader()
+
+      conversionDone = (async () => {
+        try {
+          await readableFromAsync(mbtilesToTileArgs(reader)).pipeTo(
+            writer.createTileWriteStream(),
+            { signal: pipeAbort.signal },
+          )
+          writer.finish()
+        } catch (err) {
+          try {
+            writer.abort(err instanceof Error ? err : new Error(String(err)))
+          } catch {
+            // Output stream may already be cancelled/errored
+          }
+        }
+      })()
+    },
+    async pull(controller) {
+      const { done, value } =
+        await /** @type {ReadableStreamDefaultReader<Uint8Array>} */ (
+          outputReader
+        ).read()
+      if (done) {
+        controller.close()
+      } else {
+        controller.enqueue(value)
+      }
+    },
+    async cancel(reason) {
+      pipeAbort.abort(reason)
+      await conversionDone
+      await /** @type {ReadableStreamDefaultReader<Uint8Array>} */ (
+        outputReader
+      )
+        .cancel(reason)
+        .catch(noop)
+    },
+  })
+}
+
+/**
+ * @param {MBTiles} mbtiles
+ */
+async function* mbtilesToTileArgs(mbtiles) {
+  for (const { z, x, y, data, format } of mbtiles) {
+    yield [data, { z, x, y, format, sourceId: SOURCE_ID }]
+  }
+}

package/lib/index.js

@@ -0,0 +1,12 @@
+/** @typedef {import('./types.js').SMPSource} SMPSource */
+/** @typedef {import('./types.js').SMPStyle} SMPStyle */
+
+export { Reader } from './reader.js'
+export { Writer } from './writer.js'
+export { createServer } from './server.js'
+export { StyleDownloader } from './style-downloader.js'
+export { downloadTiles } from './tile-downloader.js'
+export { download } from './download.js'
+export { fromMBTiles } from './from-mbtiles.js'
+export { emptyTileFallback, emptyGlyphFallback } from './fallbacks.js'
+export { validate } from './validator.js'