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

package/lib/utils/fetch.js

@@ -0,0 +1,104 @@
+import ky from 'ky'
+import pLimit from 'p-limit'
+
+import { ProgressStream } from './streams.js'
+
+/**
+ * @typedef {object} DownloadResponse
+ * @property {ReadableStream<Uint8Array>} body Web ReadableStream of the response body
+ * @property {string | null} mimeType Content mime-type (from http content-type header)
+ * @property {number | null} contentLength Content length in bytes (from http content-length header)
+ */
+
+/**
+ * A wrapper for fetch that limits the number of concurrent downloads.
+ */
+export class FetchQueue {
+  /** @type {import('p-limit').LimitFunction} */
+  #limit
+  /** @param {number} concurrency */
+  constructor(concurrency) {
+    this.#limit = pLimit(concurrency)
+  }
+
+  get activeCount() {
+    return this.#limit.activeCount
+  }
+
+  /**
+   * Fetch a URL, limiting the number of concurrent downloads. Resolves with a
+   * `DownloadResponse`, which is a parsed from the Fetch `Response` objects,
+   * with `body` as a web ReadableStream, and the MIME type and content length
+   * of the response.
+   *
+   * NB: The response body stream must be consumed to the end, otherwise the
+   * queue will never be emptied.
+   *
+   * @param {string} url
+   * @param {{ onprogress?: import('./streams.js').ProgressCallback }} opts
+   * @returns {Promise<DownloadResponse>}
+   */
+  fetch(url, { onprogress } = {}) {
+    // This is wrapped like this so that pLimit limits concurrent `fetchStream`
+    // calls, which only resolve when the body is completely downloaded, but
+    // this method will return a response as soon as it is available. NB: If the
+    // body of a response is never "consumed" (e.g. by reading it to the end),
+    // the fetchStream function will never resolve, and the limit will never be
+    // released.
+    return new Promise((resolveResponse, rejectResponse) => {
+      this.#limit(fetchStream, {
+        url,
+        onresponse: resolveResponse,
+        onerror: rejectResponse,
+        onprogress,
+      })
+    })
+  }
+}
+
+/**
+ * This will resolve when the download is complete, regardless of success or
+ * failure, but a readable stream is available before download via the
+ * onReadStream param. This strange function signature is used for limiting the
+ * number of simultaneous downloads, but still being able to expose the Response
+ * as soon as it is available. This is implmented this way to avoid creating
+ * unnecessary closures, which is important here because we can have thousands
+ * of tile requests.
+ *
+ * @param {object} opts
+ * @param {string} opts.url
+ * @param {(response: DownloadResponse) => void} opts.onresponse
+ * @param {(err: Error) => void} opts.onerror
+ * @param {import('./streams.js').ProgressCallback} [opts.onprogress]
+ * @returns {Promise<void>}
+ */
+async function fetchStream({ url, onresponse, onerror, onprogress }) {
+  try {
+    const response = await ky(url, { retry: 3 })
+    if (!response.body) {
+      throw new Error('No body in response')
+    }
+    const contentType = response.headers.get('content-type')
+    const mimeType =
+      typeof contentType === 'string' ? contentType.split(';')[0] : null
+    const contentLengthHeader = response.headers.get('content-length')
+    const contentLength =
+      contentLengthHeader === null ? null : parseInt(contentLengthHeader, 10)
+
+    const passthrough = new TransformStream()
+    // pipeTo resolves when the body is fully consumed (respects backpressure),
+    // which releases the pLimit slot for the next download
+    const pipePromise = response.body.pipeTo(passthrough.writable)
+
+    let body = passthrough.readable
+    if (onprogress) {
+      const progress = new ProgressStream({ onprogress })
+      body = body.pipeThrough(progress)
+    }
+
+    onresponse({ body, mimeType, contentLength })
+    await pipePromise
+  } catch (err) {
+    onerror(err instanceof Error ? err : new Error('Unknown error'))
+  }
+}

package/lib/utils/file-formats.js

@@ -0,0 +1,92 @@
+import { hasOwn } from './misc.js'
+
+const MAGIC_BYTES = /** @type {const} */ ({
+  png: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+  jpg: [0xff, 0xd8, 0xff],
+  // eslint-disable-next-line no-sparse-arrays
+  webp: [0x52, 0x49, 0x46, 0x46, , , , , 0x57, 0x45, 0x42, 0x50],
+  // Include the compression-type byte, which is always 0x08 (DEFLATE) for gzip
+  gz: [0x1f, 0x8b, 0x08],
+})
+
+const MIME_TYPES = /** @type {const} */ ({
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+})
+
+/** @type {Map<number, keyof typeof MAGIC_BYTES>} */
+const magicByteMap = new Map()
+for (const [ext, bytes] of Object.entries(MAGIC_BYTES)) {
+  magicByteMap.set(
+    bytes[0],
+    // @ts-ignore
+    ext,
+  )
+}
+/**
+ * For a given buffer, determine the tile format based on the magic bytes.
+ * Will throw for unknown file types.
+ * Smaller and faster version of magic-bytes.js due to the limited use case.
+ *
+ * @param {Buffer | Uint8Array} buf
+ * @returns {import("../writer.js").TileFormat}
+ */
+export function getTileFormatFromBuffer(buf) {
+  const ext = magicByteMap.get(buf[0])
+  if (!ext) {
+    throw new Error('Unknown file type')
+  }
+  const sig = MAGIC_BYTES[ext]
+  for (let i = 1; i < sig.length; i++) {
+    if (typeof sig[i] !== 'undefined' && sig[i] !== buf[i]) {
+      throw new Error('Unknown file type')
+    }
+  }
+  if (ext === 'gz') {
+    // Gzipped tiles are always MVT
+    return 'mvt'
+  }
+  return ext
+}
+
+/**
+ * Determine the tile format from a readable stream from the magic bytes at the
+ * start of the file. Used if data is served without a content-type header.
+ * Returns the format and a new readable stream that includes all original data.
+ *
+ * @param {ReadableStream<Uint8Array>} tileData Web ReadableStream
+ * @returns {Promise<[import("../writer.js").TileFormat, ReadableStream<Uint8Array>]>}
+ */
+export async function getTileFormatFromStream(tileData) {
+  const [stream1, stream2] = tileData.tee()
+
+  // Read enough bytes to detect the format from the first branch
+  // 12 bytes is enough for all magic byte signatures (WEBP needs 12)
+  const reader = stream1.getReader()
+  let buffer = new Uint8Array(0)
+  while (buffer.length < 12) {
+    const { done, value } = await reader.read()
+    if (done) break
+    const newBuffer = new Uint8Array(buffer.length + value.length)
+    newBuffer.set(buffer)
+    newBuffer.set(value, buffer.length)
+    buffer = newBuffer
+  }
+  reader.cancel()
+
+  const format = getTileFormatFromBuffer(buffer)
+  return [format, stream2]
+}
+
+/**
+ * Get the tile format from a MIME type. Throws for unsupported types.
+ *
+ * @param {string} mimeType
+ * @returns {import("../writer.js").TileFormat}
+ */
+export function getFormatFromMimeType(mimeType) {
+  if (mimeType.startsWith('application/')) return 'mvt'
+  if (hasOwn(MIME_TYPES, mimeType)) return MIME_TYPES[mimeType]
+  throw new Error('Unsupported MIME type ' + mimeType)
+}

package/lib/utils/geo.js

@@ -0,0 +1,97 @@
+// Adapted from https://github.com/mapbox/tilebelt
+
+const r2d = 180 / Math.PI
+
+/** Spherical Mercator max bounds, rounded to 6 decimal places */
+export const MAX_BOUNDS = /** @type {BBox} */ ([
+  -180, -85.051129, 180, 85.051129,
+])
+
+/**
+ * @typedef {[number, number, number, number]} BBox
+ */
+
+/**
+ * Return the bounding box for the given tile.
+ *
+ * @param {{ x: number, y: number, z: number }} tile
+ * @returns {BBox} Bounding Box [w, s, e, n]
+ */
+export function tileToBBox({ x, y, z }) {
+  const e = tile2lon({ x: x + 1, z })
+  const w = tile2lon({ x, z })
+  const s = tile2lat({ y: y + 1, z })
+  const n = tile2lat({ y, z })
+  return [w, s, e, n]
+}
+
+/**
+ * @param {{ x: number, y: number, z: number }} tile
+ */
+export function getQuadkey({ x, y, z }) {
+  let quadkey = ''
+  let mask
+  for (let i = z; i > 0; i--) {
+    mask = 1 << (i - 1)
+    quadkey += (x & mask ? 1 : 0) + (y & mask ? 2 : 0)
+  }
+  return quadkey
+}
+
+/**
+ * From an array of tile URL templates, get the URL for the given tile.
+ *
+ * @param {string[]} urls
+ * @param {{ x: number, y: number, z: number, scheme?: 'xyz' | 'tms' }} opts
+ */
+export function getTileUrl(urls, { x, y, z, scheme = 'xyz' }) {
+  const bboxEspg3857 = tileToBBox({ x, y: Math.pow(2, z) - y - 1, z })
+  const quadkey = getQuadkey({ x, y, z })
+
+  return urls[(x + y) % urls.length]
+    .replace('{prefix}', (x % 16).toString(16) + (y % 16).toString(16))
+    .replace(/{z}/g, String(z))
+    .replace(/{x}/g, String(x))
+    .replace(/{y}/g, String(scheme === 'tms' ? Math.pow(2, z) - y - 1 : y))
+    .replace('{quadkey}', quadkey)
+    .replace('{bbox-epsg-3857}', bboxEspg3857.join(','))
+}
+
+/**
+ * Returns a bbox that is the smallest bounding box that contains all the input bboxes.
+ *
+ * @param {[Readonly<BBox>, ...Readonly<BBox>[]]} bboxes
+ * @returns {BBox} Bounding Box [w, s, e, n]
+ */
+export function unionBBox(bboxes) {
+  let [w, s, e, n] = bboxes[0]
+  for (let i = 1; i < bboxes.length; i++) {
+    const [w1, s1, e1, n1] = bboxes[i]
+    w = Math.min(w, w1)
+    s = Math.min(s, s1)
+    e = Math.max(e, e1)
+    n = Math.max(n, n1)
+  }
+  return [w, s, e, n]
+}
+
+/**
+ * Convert a TMS Y coordinate to an XYZ Y coordinate.
+ *
+ * @param {{ y: number, z: number }} tile
+ * @returns {number} The XYZ Y coordinate
+ */
+export function tmsToXyzY({ y, z }) {
+  return Math.pow(2, z) - y - 1
+}
+
+/** @param {{ x: number, z: number }} opts */
+function tile2lon({ x, z }) {
+  return (x / Math.pow(2, z)) * 360 - 180
+}
+
+/** @param {{ y: number, z: number }} opts */
+function tile2lat({ y, z }) {
+  const n = Math.PI - (2 * Math.PI * y) / Math.pow(2, z)
+  return r2d * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n)))
+}

package/lib/utils/mapbox.js

@@ -0,0 +1,155 @@
+'use strict'
+// from https://github.com/mapbox/mapbox-gl-js/blob/495a695/src/util/mapbox.js
+
+export const API_URL = 'https://api.mapbox.com'
+const HELP = 'See https://www.mapbox.com/api-documentation/#access-tokens'
+
+/**
+ * @typedef {object} URLObject
+ * @property {string} protocol
+ * @property {string} authority
+ * @property {string} path
+ * @property {string[]} params
+ */
+
+/**
+ * @param {URLObject} urlObject
+ * @param {string} [accessToken]
+ */
+function makeAPIURL(urlObject, accessToken) {
+  const apiUrlObject = parseUrl(API_URL)
+  urlObject.protocol = apiUrlObject.protocol
+  urlObject.authority = apiUrlObject.authority
+
+  if (!accessToken) {
+    throw new Error(
+      `An API access token is required to use a Mapbox style. ${HELP}`,
+    )
+  }
+  if (accessToken[0] === 's') {
+    throw new Error(
+      `Use a public access token (pk.*) not a secret access token (sk.*). ${HELP}`,
+    )
+  }
+
+  urlObject.params.push(`access_token=${accessToken}`)
+  return formatUrl(urlObject)
+}
+
+/** @param {string} url */
+export function isMapboxURL(url) {
+  return url.indexOf('mapbox:') === 0
+}
+
+/**
+ * @param {string} url
+ * @param {string} [accessToken]
+ */
+export function normalizeStyleURL(url, accessToken) {
+  if (!isMapboxURL(url)) return url
+  if (!accessToken) throw new Error('Mapbox styles require an access token')
+  const urlObject = parseUrl(url)
+  urlObject.path = `/styles/v1${urlObject.path}`
+  return makeAPIURL(urlObject, accessToken)
+}
+
+/**
+ * @param {string} url
+ * @param {string} [accessToken]
+ */
+export function normalizeGlyphsURL(url, accessToken) {
+  if (!isMapboxURL(url)) return url
+  if (!accessToken) throw new Error('Mapbox styles require an access token')
+  const urlObject = parseUrl(url)
+  urlObject.path = `/fonts/v1${urlObject.path}`
+  return makeAPIURL(urlObject, accessToken)
+}
+
+/**
+ * @param {string} url
+ * @param {string} [accessToken]
+ */
+export function normalizeSourceURL(url, accessToken) {
+  if (!isMapboxURL(url)) return url
+  if (!accessToken) throw new Error('Mapbox styles require an access token')
+  const urlObject = parseUrl(url)
+  urlObject.path = `/v4/${urlObject.authority}.json`
+  // TileJSON requests need a secure flag appended to their URLs so
+  // that the server knows to send SSL-ified resource references.
+  urlObject.params.push('secure')
+  return makeAPIURL(urlObject, accessToken)
+}
+
+/**
+ * @param {string} url
+ * @param {'' | '@2x'} format
+ * @param {'.png' | '.json'} extension
+ * @param {string} [accessToken]
+ */
+export function normalizeSpriteURL(url, format, extension, accessToken) {
+  const urlObject = parseUrl(url)
+  if (!isMapboxURL(url)) {
+    urlObject.path += `${format}${extension}`
+    return formatUrl(urlObject)
+  }
+  urlObject.path = `/styles/v1${urlObject.path}/sprite${format}${extension}`
+  return makeAPIURL(urlObject, accessToken)
+}
+
+const imageExtensionRe = /(\.(png|jpg)\d*)(?=$)/
+
+/**
+ * @param {any} tileURL
+ * @param {string} sourceURL
+ * @param {256 | 512} [tileSize]
+ * @param {{ devicePixelRatio?: number; supportsWebp?: boolean; }} [opts]
+ */
+export function normalizeTileURL(
+  tileURL,
+  sourceURL,
+  tileSize,
+  { devicePixelRatio = 1, supportsWebp = false } = {},
+) {
+  if (!sourceURL || !isMapboxURL(sourceURL)) return tileURL
+
+  const urlObject = parseUrl(tileURL)
+
+  // The v4 mapbox tile API supports 512x512 image tiles only when @2x
+  // is appended to the tile URL. If `tileSize: 512` is specified for
+  // a Mapbox raster source force the @2x suffix even if a non hidpi device.
+  const suffix = devicePixelRatio >= 2 || tileSize === 512 ? '@2x' : ''
+  const extension = supportsWebp ? '.webp' : '$1'
+  urlObject.path = urlObject.path.replace(
+    imageExtensionRe,
+    `${suffix}${extension}`,
+  )
+
+  return formatUrl(urlObject)
+}
+
+const urlRe = /^(\w+):\/\/([^/?]*)(\/[^?]+)?\??(.+)?/
+
+/**
+ * @param {string} url
+ * @returns {URLObject}
+ */
+function parseUrl(url) {
+  const parts = url.match(urlRe)
+  if (!parts) {
+    throw new Error('Unable to parse URL object')
+  }
+  return {
+    protocol: parts[1],
+    authority: parts[2],
+    path: parts[3] || '/',
+    params: parts[4] ? parts[4].split('&') : [],
+  }
+}
+
+/**
+ * @param {URLObject} obj
+ */
+function formatUrl(obj) {
+  const params = obj.params.length ? `?${obj.params.join('&')}` : ''
+  return `${obj.protocol}://${obj.authority}${obj.path}${params}`
+}

package/{dist/utils/misc.d.cts → lib/utils/misc.js}

@@ -7,8 +7,12 @@
  * @param {T} obj
  * @returns {T}
  */
-declare function clone<T>(obj: T): T;
-declare function noop(): void;
+export function clone(obj) {
+  return JSON.parse(JSON.stringify(obj))
+}
+
+export function noop() {}
+
 /**
  * Like `Object.hasOwn`, but refines the type of `key`.
  *
@@ -17,6 +21,6 @@ declare function noop(): void;
  * @param {string} key
  * @returns {key is (keyof T)}
  */
-declare function hasOwn<T extends Record<string, unknown>>(obj: T, key: string): key is (keyof T);
-
-export { clone, hasOwn, noop };
+export function hasOwn(obj, key) {
+  return Object.hasOwn(obj, key)
+}

package/lib/utils/streams.js

@@ -0,0 +1,101 @@
+/**
+ * Create a ReadableStream from an async iterable. Uses the native
+ * `ReadableStream.from()` when available (Node 20+), otherwise falls back to a
+ * manual approach for Node 18 compatibility.
+ *
+ * @template T
+ * @param {AsyncIterable<T>} iterable
+ * @returns {ReadableStream<T>}
+ */
+export function readableFromAsync(iterable) {
+  // @ts-ignore - ReadableStream.from() exists in Node 20+ but not in DOM types
+  if (typeof ReadableStream.from === 'function') {
+    // @ts-ignore
+    return ReadableStream.from(iterable)
+  }
+  const iterator = iterable[Symbol.asyncIterator]()
+  return new ReadableStream({
+    async pull(controller) {
+      const { value, done } = await iterator.next()
+      if (done) {
+        controller.close()
+      } else {
+        controller.enqueue(value)
+      }
+    },
+    async cancel(reason) {
+      await iterator.return?.(reason)
+    },
+  })
+}
+
+/**
+ * Create a writable stream from an async function. Default concurrency is 16 -
+ * this is the number of parallel functions that will be pending before
+ * backpressure is applied on the stream.
+ *
+ * @template {(...args: any[]) => Promise<void>} T
+ * @param {T} fn
+ * @returns {WritableStream}
+ */
+export function writeStreamFromAsync(fn, { concurrency = 16 } = {}) {
+  const pending = new Set()
+  return new WritableStream(
+    {
+      write(chunk) {
+        const p = fn(...chunk)
+        pending.add(p)
+        p.finally(() => pending.delete(p))
+        if (pending.size >= concurrency) {
+          return Promise.race(pending)
+        }
+      },
+      async close() {
+        await Promise.all(pending)
+      },
+    },
+    new CountQueuingStrategy({ highWaterMark: concurrency }),
+  )
+}
+
+/** @typedef {(opts: { totalBytes: number, chunkBytes: number }) => void} ProgressCallback */
+
+/**
+ * A web TransformStream that counts the bytes passing through it. Pass an
+ * optional `onprogress` callback that will be called with the accumulated
+ * total byte count and the chunk byte count after each chunk.
+ */
+export class ProgressStream {
+  #byteLength = 0
+  #ts
+
+  /**
+   * @param {{ onprogress?: ProgressCallback }} [opts]
+   */
+  constructor({ onprogress } = {}) {
+    const self = this
+    this.#ts = new TransformStream({
+      transform(chunk, controller) {
+        self.#byteLength += chunk.byteLength
+        onprogress?.({
+          totalBytes: self.#byteLength,
+          chunkBytes: chunk.byteLength,
+        })
+        controller.enqueue(chunk)
+      },
+    })
+  }
+
+  get readable() {
+    return this.#ts.readable
+  }
+
+  get writable() {
+    return this.#ts.writable
+  }
+
+  /** Total bytes that have passed through this stream */
+  get byteLength() {
+    return this.#byteLength
+  }
+}