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

package/lib/style-downloader.js

@@ -0,0 +1,369 @@
+import { migrate } from '@maplibre/maplibre-gl-style-spec'
+import { check as checkGeoJson } from '@placemarkio/check-geojson'
+import { includeKeys } from 'filter-obj'
+import ky from 'ky'
+import Queue from 'yocto-queue'
+
+import { downloadTiles } from './tile-downloader.js'
+import { FetchQueue } from './utils/fetch.js'
+import {
+  normalizeGlyphsURL,
+  normalizeSourceURL,
+  normalizeSpriteURL,
+  normalizeStyleURL,
+} from './utils/mapbox.js'
+import { clone, noop } from './utils/misc.js'
+import {
+  assertTileJSON,
+  isInlinedSource,
+  isLocallyRenderedRange,
+  mapFontStacks,
+  validateStyle,
+} from './utils/style.js'
+
+/** @import { SourceSpecification, StyleSpecification } from '@maplibre/maplibre-gl-style-spec' */
+/** @import { TileInfo, GlyphInfo, GlyphRange } from './writer.js' */
+/** @import { TileDownloadStats } from './tile-downloader.js' */
+/** @import { StyleInlinedSources, InlinedSource } from './types.js'*/
+
+/** @typedef { import('ky').ResponsePromise & { body: ReadableStream<Uint8Array> } } ResponsePromise */
+/** @import { DownloadResponse } from './utils/fetch.js' */
+
+/**
+ * @typedef {object} GlyphDownloadStats
+ * @property {number} total
+ * @property {number} downloaded
+ * @property {number} totalBytes
+ */
+
+/**
+ * Download a style and its resources for offline use. Please check the terms of
+ * service of the map provider you are using before downloading any resources.
+ */
+export class StyleDownloader {
+  /** @type {null | string} */
+  #styleURL = null
+  /** @type {null | StyleSpecification} */
+  #inputStyle = null
+  /** @type {FetchQueue} */
+  #fetchQueue
+  #mapboxAccessToken
+
+  /**
+   * @param {string | StyleSpecification} style A url to a style JSON file or a style object
+   * @param {object} [opts]
+   * @param {number} [opts.concurrency=8]
+   * @param {string} [opts.mapboxAccessToken] Downloading a style from Mapbox requires an access token
+   */
+  constructor(style, { concurrency = 8, mapboxAccessToken } = {}) {
+    if (typeof style === 'string') {
+      const { searchParams } = new URL(style)
+      this.#mapboxAccessToken =
+        searchParams.get('access_token') || mapboxAccessToken
+      this.#styleURL = normalizeStyleURL(style, this.#mapboxAccessToken)
+    } else {
+      // Migrate actually mutates the input, so we act on a clone.
+      const styleV8 = migrate(clone(style))
+      if (!validateStyle(styleV8)) {
+        throw new AggregateError(validateStyle.errors, 'Invalid style')
+      }
+      this.#inputStyle = styleV8
+    }
+    this.#fetchQueue = new FetchQueue(concurrency)
+  }
+
+  /**
+   * Number of active downloads.
+   */
+  get active() {
+    return this.#fetchQueue.activeCount
+  }
+
+  /**
+   * Download the style JSON for this style and inline the sources
+   *
+   * @returns {Promise<StyleInlinedSources>}
+   */
+  async getStyle() {
+    if (!this.#inputStyle && this.#styleURL) {
+      const downloadedStyle = await ky(this.#styleURL).json()
+      const styleV8 = migrate(downloadedStyle)
+      if (!validateStyle(styleV8)) {
+        throw new AggregateError(validateStyle.errors, 'Invalid style')
+      }
+      this.#inputStyle = styleV8
+    } else if (!this.#inputStyle) {
+      throw new Error('Unexpected state: no style or style URL provided')
+    }
+    /** @type {{ [_:string]: InlinedSource }} */
+    const inlinedSources = {}
+    for (const [sourceId, source] of Object.entries(this.#inputStyle.sources)) {
+      inlinedSources[sourceId] = await this.#getInlinedSource(source)
+    }
+    return {
+      ...this.#inputStyle,
+      sources: inlinedSources,
+    }
+  }
+
+  /**
+   * @param {SourceSpecification} source
+   * @returns {Promise<InlinedSource>}
+   */
+  async #getInlinedSource(source) {
+    if (isInlinedSource(source)) {
+      return source
+    }
+    if (
+      source.type === 'raster' ||
+      source.type === 'vector' ||
+      source.type === 'raster-dem'
+    ) {
+      if (!source.url) {
+        throw new Error('Source is missing both url and tiles properties')
+      }
+      const sourceUrl = normalizeSourceURL(source.url, this.#mapboxAccessToken)
+      const tilejson = await ky(sourceUrl).json()
+      assertTileJSON(tilejson)
+      return {
+        ...source,
+        ...includeKeys(tilejson, [
+          'bounds',
+          'maxzoom',
+          'minzoom',
+          'tiles',
+          'description',
+          'attribution',
+          'vector_layers',
+        ]),
+      }
+    } else if (source.type === 'geojson') {
+      if (typeof source.data !== 'string') {
+        // Shouldn't get here because of the `isInlineSource()` check above, but
+        // Typescript can't fiture that out.
+        throw new Error('Unexpected data property for GeoJson source')
+      }
+      const geojsonUrl = normalizeSourceURL(
+        source.data,
+        this.#mapboxAccessToken,
+      )
+      const data = checkGeoJson(await ky(geojsonUrl).text())
+      return {
+        ...source,
+        data,
+      }
+    }
+    return source
+  }
+
+  /**
+   * Download the sprite PNGs and JSON files for this style. Returns an async
+   * generator of json and png readable streams, and the sprite id and pixel
+   * ratio. Downloads pixel ratios `1` and `2`.
+   *
+   * @returns {AsyncGenerator<{ json: ReadableStream<Uint8Array>, png: ReadableStream<Uint8Array>, id: string, pixelRatio: number }>}
+   */
+  async *getSprites() {
+    const style = await this.getStyle()
+    if (!style.sprite) return
+    const accessToken = this.#mapboxAccessToken
+    const spriteDefs = Array.isArray(style.sprite)
+      ? style.sprite
+      : [{ id: 'default', url: style.sprite }]
+    for (const { id, url } of spriteDefs) {
+      for (const pixelRatio of [1, 2]) {
+        const format = pixelRatio === 1 ? '' : '@2x'
+        const jsonUrl = normalizeSpriteURL(url, format, '.json', accessToken)
+        const pngUrl = normalizeSpriteURL(url, format, '.png', accessToken)
+        const [{ body: json }, { body: png }] = await Promise.all([
+          this.#fetchQueue.fetch(jsonUrl),
+          this.#fetchQueue.fetch(pngUrl),
+        ])
+        yield { json, png, id, pixelRatio }
+      }
+    }
+  }
+
+  /**
+   * Download all the glyphs for the fonts used in this style. When font stacks
+   * are used in the style.json (e.g. lists of prefered fonts like with CSS),
+   * then the first font in the stack is downloaded. Defaults to downloading all
+   * UTF character ranges, which may be overkill for some styles. TODO: add more
+   * options here.
+   *
+   * Returns an async generator of readable streams of glyph data and glyph info
+   * objects.
+   *
+   * @param {object} opts
+   * @param {(progress: GlyphDownloadStats) => void} [opts.onprogress]
+   * @param {boolean} [opts.skipLocalGlyphs] Skip glyph ranges rendered client-side by MapLibre GL via localIdeographFontFamily (CJK, Hangul, Kana, Yi, etc.)
+   * @returns {AsyncGenerator<[ReadableStream<Uint8Array>, GlyphInfo]>}
+   */
+  async *getGlyphs({ onprogress = noop, skipLocalGlyphs = false } = {}) {
+    const style = await this.getStyle()
+    if (!style.glyphs) return
+
+    let completed = 0
+    /** @type {GlyphDownloadStats} */
+    let stats = {
+      total: 0,
+      downloaded: 0,
+      totalBytes: 0,
+    }
+    /** @type {import('./utils/streams.js').ProgressCallback} */
+    function onDownloadProgress({ chunkBytes }) {
+      stats.totalBytes += chunkBytes
+      onprogress(stats)
+    }
+    function onDownloadComplete() {
+      stats.downloaded = ++completed
+      onprogress(stats)
+    }
+
+    /** @type {Queue<[Promise<void | DownloadResponse>, GlyphInfo]>} */
+    const queue = new Queue()
+    /** @type {Map<string, string>} */
+    const fontStacks = new Map()
+    mapFontStacks(style.layers, (fontStack) => {
+      // Assume that the font we get back from the API is the first font in the
+      // font stack. TODO: When we know the API, we can check this font is
+      // actually available.
+      fontStacks.set(fontStack[0], fontStack.join(','))
+      return []
+    })
+    const glyphUrl = normalizeGlyphsURL(style.glyphs, this.#mapboxAccessToken)
+
+    for (const [font, fontStack] of fontStacks.entries()) {
+      for (let i = 0; i < Math.pow(2, 16); i += 256) {
+        if (skipLocalGlyphs && isLocallyRenderedRange(i)) continue
+        /** @type {GlyphRange} */
+        const range = `${i}-${i + 255}`
+        const url = glyphUrl
+          .replace('{fontstack}', fontStack)
+          .replace('{range}', range)
+        const result = this.#fetchQueue
+          .fetch(url, { onprogress: onDownloadProgress })
+          // TODO: Handle errors downloading glyphs
+          .catch(noop)
+        queue.enqueue([result, { font, range }])
+      }
+    }
+
+    stats.total = queue.size
+    if (onprogress) onprogress(stats)
+
+    for (const [result, glyphInfo] of queue) {
+      // TODO: Handle errors downloading glyphs
+      const downloadResponse = await result.catch(noop)
+      if (!downloadResponse) continue
+      const { body } = downloadResponse
+      // Glyphs are always gzipped. Unfortunately we can't stop fetch from ungzipping, so we need to re-gzip it.
+      // Pipe body directly into the CompressionStream so pipeTo's resolved promise signals when consumer is done.
+      const gzip = /** @type {TransformStream<Uint8Array, Uint8Array>} */ (
+        new CompressionStream('gzip')
+      )
+      body.pipeTo(gzip.writable).then(onDownloadComplete, noop)
+      const gzippedStream = gzip.readable
+      yield [gzippedStream, glyphInfo]
+    }
+  }
+
+  /**
+   * Get all the tiles for this style within the given bounds and zoom range.
+   * Returns an async generator of readable streams of tile data and tile info
+   * objects.
+   *
+   * The returned iterator also has a `skipped` property which is an
+   * array of tiles which could not be downloaded, and a `stats` property which
+   * is an object with the total number of tiles, downloaded tiles, and total
+   * bytes downloaded.
+   *
+   * @param {object} opts
+   * @param {Readonly<import('./utils/geo.js').BBox>} opts.bounds
+   * @param {number} opts.maxzoom
+   * @param {(progress: TileDownloadStats) => void} [opts.onprogress]
+   * @param {boolean} [opts.trackErrors=false] Include errors in the returned array of skipped tiles - this has memory overhead so should only be used for debugging.
+   * @returns {AsyncGenerator<[ReadableStream<Uint8Array>, TileInfo]> & { readonly skipped: Array<TileInfo & { error?: Error }>, readonly stats: TileDownloadStats }}
+   */
+  getTiles({ bounds, maxzoom, onprogress = noop, trackErrors = false }) {
+    const _this = this
+    /** @type {Array<TileInfo & { error?: Error }>} */
+    const skipped = []
+    /** @type {TileDownloadStats} */
+    let stats = {
+      total: 0,
+      downloaded: 0,
+      skipped: 0,
+      totalBytes: 0,
+    }
+
+    /** @type {ReturnType<StyleDownloader['getTiles']>} */
+    const tiles = (async function* () {
+      const inlinedStyle = await _this.getStyle()
+      for await (const [sourceId, source] of Object.entries(
+        inlinedStyle.sources,
+      )) {
+        if (source.type !== 'raster' && source.type !== 'vector') {
+          continue
+        }
+        // Baseline stats for this source, used in the `onprogress` closure
+        // below. Sorry for the hard-to-follow code! `onprogress` can be called
+        // after we are already reading the next source, hence the need for a
+        // closure.
+        const statsBaseline = { ...stats }
+        const sourceTiles = downloadTiles({
+          tileUrls: source.tiles,
+          bounds,
+          maxzoom: Math.min(maxzoom, source.maxzoom || maxzoom),
+          minzoom: source.minzoom,
+          sourceBounds: source.bounds,
+          boundsBuffer: true,
+          scheme: source.scheme,
+          fetchQueue: _this.#fetchQueue,
+          onprogress: (sourceStats) => {
+            stats = addStats(statsBaseline, sourceStats)
+            onprogress(stats)
+          },
+          trackErrors,
+        })
+        for await (const [tileDataStream, tileInfo] of sourceTiles) {
+          yield [tileDataStream, { ...tileInfo, sourceId }]
+        }
+        Array.prototype.push.apply(
+          skipped,
+          sourceTiles.skipped.map((tile) => ({ ...tile, sourceId })),
+        )
+      }
+    })()
+
+    Object.defineProperty(tiles, 'skipped', {
+      get() {
+        return skipped
+      },
+    })
+
+    Object.defineProperty(tiles, 'stats', {
+      get() {
+        return stats
+      },
+    })
+
+    return tiles
+  }
+}
+
+/**
+ * Add two TileDownloadStats objects together.
+ *
+ * @param {TileDownloadStats} statsA
+ * @param {TileDownloadStats} statsB
+ * @returns {TileDownloadStats}
+ */
+function addStats(statsA, statsB) {
+  return {
+    total: statsA.total + statsB.total,
+    downloaded: statsA.downloaded + statsB.downloaded,
+    skipped: statsA.skipped + statsB.skipped,
+    totalBytes: statsA.totalBytes + statsB.totalBytes,
+  }
+}

package/lib/tile-downloader.js

@@ -0,0 +1,189 @@
+import SphericalMercator from '@mapbox/sphericalmercator'
+import Queue from 'yocto-queue'
+
+import { FetchQueue } from './utils/fetch.js'
+import {
+  getFormatFromMimeType,
+  getTileFormatFromStream,
+} from './utils/file-formats.js'
+import { getTileUrl, MAX_BOUNDS } from './utils/geo.js'
+import { noop } from './utils/misc.js'
+
+/** @typedef {Omit<import('./writer.js').TileInfo, 'sourceId'>} TileInfo */
+/**
+ * @typedef {object} TileDownloadStats
+ * @property {number} total
+ * @property {number} downloaded
+ * @property {number} skipped
+ * @property {number} totalBytes
+ */
+
+/**
+ * Download tiles from a list of tile URLs within a bounding box and zoom range.
+ * Returns an async generator of tile data as readable streams and tile info objects.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.tileUrls Array of tile URL templates. Use `{x}`, `{y}`, `{z}` placeholders, and optional `{scheme}` placeholder which can be `xyz` or `tms`.
+ * @param {Readonly<import('./utils/geo.js').BBox>} opts.bounds Bounding box of the area to download
+ * @param {number} opts.maxzoom Maximum zoom level to download
+ * @param {(progress: TileDownloadStats) => void} [opts.onprogress] Callback to report download progress
+ * @param {boolean} [opts.trackErrors=false] Include errors in the returned array of skipped tiles - this has memory overhead so should only be used for debugging.
+ * @param {Readonly<import('./utils/geo.js').BBox>} [opts.sourceBounds=MAX_BOUNDS] Bounding box of source data.
+ * @param {boolean} [opts.boundsBuffer=false] Buffer the bounds by one tile at each zoom level to ensure no tiles are missed at the edges. With this set to false, in most instances the map will appear incomplete when viewed because the downloaded tiles at lower zoom levels will not cover the map view area.
+ * @param {number} [opts.minzoom=0] Minimum zoom level to download (for most cases this should be left as `0` - the size overhead is minimal, because each zoom level has 4x as many tiles)
+ * @param {number} [opts.concurrency=8] Number of concurrent downloads (ignored if `fetchQueue` is provided)
+ * @param {FetchQueue} [opts.fetchQueue=new FetchQueue(concurrency)] Optional fetch queue to use for downloading tiles
+ * @param {'xyz' | 'tms'} [opts.scheme='xyz'] Tile scheme to use for tile URLs
+ * @returns {AsyncGenerator<[ReadableStream<Uint8Array>, TileInfo]> & { readonly skipped: Array<TileInfo & { error?: Error }>, readonly stats: TileDownloadStats }}
+ */
+export function downloadTiles({
+  tileUrls,
+  bounds,
+  maxzoom,
+  onprogress = noop,
+  trackErrors = false,
+  sourceBounds = MAX_BOUNDS,
+  boundsBuffer = false,
+  minzoom = 0,
+  concurrency = 8,
+  fetchQueue = new FetchQueue(concurrency),
+  scheme = 'xyz',
+}) {
+  /** @type {Array<TileInfo & { error?: Error }>} */
+  const skipped = []
+  let completed = 0
+  /** @type {TileDownloadStats} */
+  let stats = {
+    total: 0,
+    downloaded: 0,
+    skipped: 0,
+    totalBytes: 0,
+  }
+  /** @type {import('./utils/streams.js').ProgressCallback} */
+  function onDownloadProgress({ chunkBytes }) {
+    stats.totalBytes += chunkBytes
+    onprogress(stats)
+  }
+  /**
+   *
+   * @param {Error} error
+   * @param {TileInfo} tileInfo
+   */
+  function onDownloadError(error, tileInfo) {
+    if (trackErrors) {
+      skipped.push({ ...tileInfo, error })
+    } else {
+      skipped.push(tileInfo)
+    }
+    onprogress(stats)
+  }
+  function onDownloadComplete() {
+    stats.downloaded = ++completed - skipped.length
+    stats.skipped = skipped.length
+    onprogress(stats)
+  }
+
+  /** @type {ReturnType<downloadTiles>} */
+  const tiles = (async function* () {
+    /** @type {Queue<[Promise<void | import('./utils/fetch.js').DownloadResponse>, TileInfo]>} */
+    const queue = new Queue()
+    const tiles = tileIterator({
+      bounds,
+      minzoom,
+      maxzoom,
+      sourceBounds,
+      boundsBuffer,
+    })
+    for (const { x, y, z } of tiles) {
+      const tileURL = getTileUrl(tileUrls, { x, y, z, scheme })
+      const tileInfo = { z, x, y }
+      const result = fetchQueue
+        .fetch(tileURL, { onprogress: onDownloadProgress })
+        // We handle error here rather than below to avoid uncaught errors
+        .catch((err) => onDownloadError(err, tileInfo))
+      queue.enqueue([result, tileInfo])
+    }
+
+    stats.total = queue.size
+    if (onprogress) onprogress(stats)
+
+    for (const [result, tileInfo] of queue) {
+      // We handle any error above and add to `skipped`
+      const downloadResponse = await result.catch(noop)
+      if (!downloadResponse) continue
+      let { body, mimeType } = downloadResponse
+      /** @type {import('./writer.js').TileFormat} */
+      let format
+      if (mimeType) {
+        format = getFormatFromMimeType(mimeType)
+      } else {
+        ;[format, body] = await getTileFormatFromStream(body)
+      }
+
+      let stream = body
+      // MVT tiles are always gzipped. Unfortunately we can't stop fetch from
+      // ungzipping the data during download, so we need to re-gzip it.
+      // Use the gzip transform (or a passthrough for other formats) as the pipe
+      // target so pipeTo's resolved promise signals when the consumer is done.
+      const transform = /** @type {TransformStream<Uint8Array, Uint8Array>} */ (
+        format === 'mvt' ? new CompressionStream('gzip') : new TransformStream()
+      )
+      body
+        .pipeTo(transform.writable)
+        .then(onDownloadComplete, (err) => onDownloadError(err, tileInfo))
+      stream = transform.readable
+
+      yield [stream, { ...tileInfo, format }]
+    }
+  })()
+
+  Object.defineProperty(tiles, 'skipped', {
+    get() {
+      return skipped
+    },
+  })
+
+  Object.defineProperty(tiles, 'stats', {
+    get() {
+      return stats
+    },
+  })
+
+  return tiles
+}
+
+/**
+ *
+ * @param {object} opts
+ * @param {Readonly<import('./utils/geo.js').BBox>} [opts.bounds]
+ * @param {Readonly<import('./utils/geo.js').BBox>} [opts.sourceBounds]
+ * @param {boolean} [opts.boundsBuffer]
+ * @param {number} [opts.minzoom]
+ * @param {number} opts.maxzoom
+ */
+export function* tileIterator({
+  bounds = [...MAX_BOUNDS],
+  minzoom = 0,
+  maxzoom,
+  sourceBounds,
+  boundsBuffer = false,
+}) {
+  const sm = new SphericalMercator({ size: 256 })
+  for (let z = minzoom; z <= maxzoom; z++) {
+    // Cloning bounds passed to sm.xyz because no guarantee it won't mutate the array
+    let { minX, minY, maxX, maxY } = sm.xyz([...bounds], z)
+    let sourceXYBounds = sourceBounds
+      ? sm.xyz([...sourceBounds], z)
+      : { minX, minY, maxX, maxY }
+    const buffer = boundsBuffer ? 1 : 0
+    minX = Math.max(0, minX - buffer, sourceXYBounds.minX)
+    minY = Math.max(0, minY - buffer, sourceXYBounds.minY)
+    maxX = Math.min(Math.pow(2, z) - 1, maxX + buffer, sourceXYBounds.maxX)
+    maxY = Math.min(Math.pow(2, z) - 1, maxY + buffer, sourceXYBounds.maxY)
+    for (let x = minX; x <= maxX; x++) {
+      for (let y = minY; y <= maxY; y++) {
+        yield { x, y, z }
+      }
+    }
+  }
+}

package/lib/types.ts

@@ -0,0 +1,99 @@
+import type {
+  SourceSpecification,
+  StyleSpecification,
+  ValidationError,
+  GeoJSONSourceSpecification,
+  VectorSourceSpecification,
+  RasterSourceSpecification,
+  RasterDEMSourceSpecification,
+} from '@maplibre/maplibre-gl-style-spec'
+import type { GeoJSON, BBox } from 'geojson'
+import type { Except, SetRequired, Simplify } from 'type-fest'
+
+import { SUPPORTED_SOURCE_TYPES } from './writer.js'
+
+export type InputSource = Extract<
+  SourceSpecification,
+  { type: (typeof SUPPORTED_SOURCE_TYPES)[number] }
+>
+type TransformInlinedSource<T extends SourceSpecification> =
+  T extends GeoJSONSourceSpecification
+    ? OmitUnion<T, 'data'> & { data: GeoJSON }
+    : T extends
+          | VectorSourceSpecification
+          | RasterSourceSpecification
+          | RasterDEMSourceSpecification
+      ? SetRequired<OmitUnion<T, 'url'>, 'tiles'>
+      : T
+/**
+ * This is a slightly stricter version of SourceSpecification that requires
+ * sources to be inlined (e.g. no urls to TileJSON or GeoJSON files).
+ */
+export type InlinedSource = TransformInlinedSource<SourceSpecification>
+type SupportedInlinedSource = Extract<
+  InlinedSource,
+  { type: (typeof SUPPORTED_SOURCE_TYPES)[number] }
+>
+/**
+ * This is a slightly stricter version of StyleSpecification that requires
+ * sources to be inlined (e.g. no urls to TileJSON or GeoJSON files).
+ */
+export type StyleInlinedSources = Omit<StyleSpecification, 'sources'> & {
+  sources: {
+    [_: string]: InlinedSource
+  }
+}
+
+export type SMPSource = TransformSMPInputSource<SupportedInlinedSource>
+/**
+ * This is a slightly stricter version of StyleSpecification that is provided in
+ * a Styled Map Package. Tile sources must have tile URLs inlined (they cannot
+ * refer to a TileJSON url), and they must have bounds, minzoom, and maxzoom.
+ * GeoJSON sources must have inlined GeoJSON (not a URL to a GeoJSON file).
+ */
+export type SMPStyle = TransformSMPStyle<StyleSpecification>
+
+export type TransformSMPInputSource<T extends SupportedInlinedSource> =
+  T extends GeoJSONSourceSpecification
+    ? T & { data: { bbox: BBox } }
+    : T extends RasterSourceSpecification | VectorSourceSpecification
+      ? SetRequired<T, 'bounds' | 'minzoom' | 'maxzoom'>
+      : T
+
+type TransformSMPStyle<T extends StyleSpecification> = Omit<T, 'sources'> & {
+  metadata: {
+    'smp:bounds': [number, number, number, number]
+    'smp:maxzoom': 0
+    'smp:sourceFolders': { [_: string]: string }
+    [key: string]: unknown
+  }
+  sources: {
+    [_: string]: SMPSource
+  }
+}
+
+export interface ValidateStyle {
+  (style: unknown): style is StyleSpecification
+  errors: Array<ValidationError>
+}
+
+export type DownloadStream = ReadableStream<Uint8Array>
+
+export type RequiredUnion<T> = T extends any ? Required<T> : never
+export type OmitUnion<T, K extends keyof any> = T extends unknown
+  ? Omit<T, K>
+  : never
+
+type SetRequiredIfPresent<
+  BaseType,
+  Keys extends keyof any,
+> = BaseType extends unknown
+  ? Keys extends keyof BaseType
+    ? Simplify<
+        // Pick just the keys that are optional from the base type.
+        Except<BaseType, Keys> &
+          // Pick the keys that should be required from the base type and make them required.
+          Required<Pick<BaseType, Keys>>
+      >
+    : never
+  : never

package/lib/utils/errors.js

@@ -0,0 +1,24 @@
+export class ENOENT extends Error {
+  code = 'ENOENT'
+  /** @param {string} path */
+  constructor(path) {
+    const message = `ENOENT: no such file or directory, open '${path}'`
+    super(message)
+    this.path = path
+  }
+}
+
+/**
+ * Returns true if the error if because a file is not found. On Windows, some
+ * operations like fs.watch() throw an EPERM error rather than ENOENT.
+ *
+ * @param {unknown} error
+ * @returns {error is Error & { code: 'ENOENT' | 'EPERM' }}
+ */
+export function isFileNotThereError(error) {
+  return (
+    error instanceof Error &&
+    'code' in error &&
+    (error.code === 'ENOENT' || error.code === 'EPERM')
+  )
+}