styled-map-package 1.0.0

package/lib/utils/streams.js

@@ -0,0 +1,162 @@
+import { Readable, Writable, Transform } from 'readable-stream'
+
+/** @import { TransformOptions } from 'readable-stream' */
+
+/**
+ * Create a writable stream from an async function. Default concurrecy 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 {import('readable-stream').Writable}
+ */
+export function writeStreamFromAsync(fn, { concurrency = 16 } = {}) {
+  return new Writable({
+    highWaterMark: concurrency,
+    objectMode: true,
+    write(chunk, encoding, callback) {
+      fn.apply(null, chunk).then(() => callback(), callback)
+    },
+  })
+}
+
+/**
+ * From https://github.com/nodejs/node/blob/430c0269/lib/internal/webstreams/adapters.js#L509
+ *
+ * @param {ReadableStream} readableStream
+ * @param {{
+ *   highWaterMark? : number,
+ *   encoding? : string,
+ *   objectMode? : boolean,
+ *   signal? : AbortSignal,
+ * }} [options]
+ * @returns {import('stream').Readable}
+ */
+
+export function fromWebReadableStream(readableStream, options = {}) {
+  if (!isWebReadableStream(readableStream)) {
+    throw new Error('First argument must be a ReadableStream')
+  }
+
+  const { highWaterMark, encoding, objectMode = false, signal } = options
+
+  if (encoding !== undefined && !Buffer.isEncoding(encoding))
+    throw new Error('Invalid encoding')
+
+  const reader = readableStream.getReader()
+  let closed = false
+
+  const readable = new Readable({
+    objectMode,
+    highWaterMark,
+    encoding,
+    // @ts-ignore
+    signal,
+
+    read() {
+      reader.read().then(
+        (chunk) => {
+          if (chunk.done) {
+            // Value should always be undefined here.
+            readable.push(null)
+          } else {
+            readable.push(chunk.value)
+          }
+        },
+        (error) => readable.destroy(error),
+      )
+    },
+
+    destroy(error, callback) {
+      function done() {
+        try {
+          callback(error)
+        } catch (error) {
+          // In a next tick because this is happening within
+          // a promise context, and if there are any errors
+          // thrown we don't want those to cause an unhandled
+          // rejection. Let's just escape the promise and
+          // handle it separately.
+          process.nextTick(() => {
+            throw error
+          })
+        }
+      }
+
+      if (!closed) {
+        reader.cancel(error).then(done, done)
+        return
+      }
+      done()
+    },
+  })
+
+  reader.closed.then(
+    () => {
+      closed = true
+    },
+    (error) => {
+      closed = true
+      readable.destroy(error)
+    },
+  )
+
+  return readable
+}
+
+/**
+ * @param {unknown} obj
+ * @returns {obj is ReadableStream}
+ */
+export function isWebReadableStream(obj) {
+  return !!(
+    typeof obj === 'object' &&
+    obj !== null &&
+    'pipeThrough' in obj &&
+    typeof obj.pipeThrough === 'function' &&
+    'getReader' in obj &&
+    typeof obj.getReader === 'function' &&
+    'cancel' in obj &&
+    typeof obj.cancel === 'function'
+  )
+}
+
+/** @typedef {(opts: { totalBytes: number, chunkBytes: number }) => void} ProgressCallback */
+
+/**
+ * Passthrough stream 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 extends Transform {
+  #onprogress
+  #byteLength = 0
+
+  /**
+   * @param {TransformOptions & { onprogress?: ProgressCallback }} [opts]
+   */
+  constructor({ onprogress, ...opts } = {}) {
+    super(opts)
+    this.#onprogress = onprogress
+  }
+
+  /** Total bytes that have passed through this stream */
+  get byteLength() {
+    return this.#byteLength
+  }
+
+  /**
+   * @param {Buffer | Uint8Array} chunk
+   * @param {Parameters<Transform['_transform']>[1]} encoding
+   * @param {Parameters<Transform['_transform']>[2]} callback
+   */
+  _transform(chunk, encoding, callback) {
+    this.#byteLength += chunk.length
+    this.#onprogress?.({
+      totalBytes: this.#byteLength,
+      chunkBytes: chunk.length,
+    })
+    callback(null, chunk)
+  }
+}

package/lib/utils/style.js

@@ -0,0 +1,174 @@
+import { expressions, validateStyleMin } from '@maplibre/maplibre-gl-style-spec'
+
+/** @import {StyleSpecification, ExpressionSpecification, ValidationError} from '@maplibre/maplibre-gl-style-spec' */
+
+/**
+ * For a given style, replace all font stacks (`text-field` properties) with the
+ * provided fonts. If no matching font is found, the first font in the stack is
+ * used.
+ *
+ * *Modifies the input style object*
+ *
+ * @param {StyleSpecification} style
+ * @param {string[]} fonts
+ */
+export function replaceFontStacks(style, fonts) {
+  const mappedLayers = mapFontStacks(style.layers, (fontStack) => {
+    let match
+    for (const font of fontStack) {
+      if (fonts.includes(font)) {
+        match = font
+        break
+      }
+    }
+    return [match || fonts[0]]
+  })
+  style.layers = mappedLayers
+  return style
+}
+
+/**
+ * From given style layers, create a new style by calling the provided callback
+ * function on every font stack defined in the style.
+ *
+ * @param {StyleSpecification['layers']} layers
+ * @param {(fontStack: string[]) => string[]} callbackFn
+ * @returns {StyleSpecification['layers']}
+ */
+export function mapFontStacks(layers, callbackFn) {
+  return layers.map((layer) => {
+    if (layer.type !== 'symbol' || !layer.layout || !layer.layout['text-font'])
+      return layer
+    const textFont = layer.layout['text-font']
+    let mappedValue
+    if (isExpression(textFont)) {
+      mappedValue = mapArrayExpressionValue(textFont, callbackFn)
+    } else if (Array.isArray(textFont)) {
+      mappedValue = callbackFn(textFont)
+    } else {
+      // Deprecated property function, unsupported, but within this module
+      // functions will have been migrated to expressions anyway.
+      console.warn(
+        'Deprecated function definitions are not supported, font stack has not been transformed.',
+      )
+      console.dir(textFont, { depth: null })
+      return layer
+    }
+    return {
+      ...layer,
+      layout: {
+        ...layer.layout,
+        'text-font': mappedValue,
+      },
+    }
+  })
+}
+
+/**
+ * See https://github.com/maplibre/maplibre-style-spec/blob/c2f01dbaa6c5fb8409126258b9464b450018e939/src/expression/index.ts#L128
+ *
+ * @param {unknown} value
+ * @returns {value is ExpressionSpecification}
+ */
+function isExpression(value) {
+  return (
+    Array.isArray(value) &&
+    value.length > 0 &&
+    typeof value[0] === 'string' &&
+    value[0] in expressions
+  )
+}
+
+/**
+ * For an expression whose value is an array, map the array to a new array using
+ * the given callbackFn.
+ *
+ * @param {ExpressionSpecification} expression
+ * @param {(value: string[]) => string[]} callbackFn
+ * @returns {ExpressionSpecification}
+ */
+function mapArrayExpressionValue(expression, callbackFn) {
+  // This only works for properties whose value is an array, because it relies
+  // on the style specification that array values must be declared with the
+  // `literal` expression.
+  if (expression[0] === 'literal' && Array.isArray(expression[1])) {
+    return ['literal', callbackFn(expression[1])]
+  } else {
+    // @ts-ignore
+    return [
+      expression[0],
+      ...expression.slice(1).map(
+        // @ts-ignore
+        (x) => {
+          if (isExpression(x)) {
+            return mapArrayExpressionValue(x, callbackFn)
+          } else {
+            return x
+          }
+        },
+      ),
+    ]
+  }
+}
+
+/**
+ * @typedef {object} TileJSONPartial
+ * @property {string[]} tiles
+ * @property {string} [description]
+ * @property {string} [attribution]
+ * @property {object[]} [vector_layers]
+ * @property {import('./geo.js').BBox} [bounds]
+ * @property {number} [maxzoom]
+ * @property {number} [minzoom]
+ */
+
+/**
+ *
+ * @param {unknown} tilejson
+ * @returns {asserts tilejson is TileJSONPartial}
+ */
+export function assertTileJSON(tilejson) {
+  if (typeof tilejson !== 'object' || tilejson === null) {
+    throw new Error('Invalid TileJSON')
+  }
+  if (
+    !('tiles' in tilejson) ||
+    !Array.isArray(tilejson.tiles) ||
+    tilejson.tiles.length === 0 ||
+    tilejson.tiles.some((tile) => typeof tile !== 'string')
+  ) {
+    throw new Error('Invalid TileJSON: missing or invalid tiles property')
+  }
+}
+
+export const validateStyle =
+  /** @type {{ (style: unknown): style is StyleSpecification, errors: ValidationError[] }} */ (
+    (style) => {
+      validateStyle.errors = validateStyleMin(
+        /** @type {StyleSpecification} */ (style),
+      )
+      if (validateStyle.errors.length) return false
+      return true
+    }
+  )
+
+/**
+ * Check whether a source is already inlined (e.g. does not reference a TileJSON or GeoJSON url)
+ *
+ * @param {import('@maplibre/maplibre-gl-style-spec').SourceSpecification} source
+ * @returns {source is import('../types.js').InlinedSource}
+ */
+export function isInlinedSource(source) {
+  if (source.type === 'geojson') {
+    return typeof source.data === 'object'
+  } else if (
+    source.type === 'vector' ||
+    source.type === 'raster' ||
+    source.type === 'raster-dem'
+  ) {
+    return 'tiles' in source
+  } else {
+    // Video and image sources are not strictly "inlined", but we treat them as such.
+    return true
+  }
+}

package/lib/utils/templates.js

@@ -0,0 +1,136 @@
+export const URI_SCHEME = 'smp' // "Styled Map Package"
+export const URI_BASE = URI_SCHEME + '://maps.v1/'
+
+// These constants determine the file format structure
+export const STYLE_FILE = 'style.json'
+const SOURCES_FOLDER = 's'
+const SPRITES_FOLDER = 'sprites'
+const FONTS_FOLDER = 'fonts'
+
+// This must include placeholders `{z}`, `{x}`, `{y}`, since these are used to
+// define the tile URL, and this is a TileJSON standard.
+// The folder here is just `s` to minimize bytes used for filenames, which are
+// included in the header of every tile in the zip file.
+const TILE_FILE = SOURCES_FOLDER + '/{sourceId}/{z}/{x}/{y}{ext}'
+// The pixel ratio and ext placeholders must be at the end of the string with no
+// data between them, because this is the format defined in the MapLibre style spec.
+const SPRITE_FILE = SPRITES_FOLDER + '/{id}/sprite{pixelRatio}{ext}'
+// This must include placeholders `{fontstack}` and `{range}`, since these are
+// part of the MapLibre style spec.
+const GLYPH_FILE = FONTS_FOLDER + '/{fontstack}/{range}.pbf.gz'
+export const GLYPH_URI = URI_BASE + GLYPH_FILE
+
+const pathToResouceType = /** @type {const} */ ({
+  [TILE_FILE.split('/')[0] + '/']: 'tile',
+  [SPRITE_FILE.split('/')[0] + '/']: 'sprite',
+  [GLYPH_FILE.split('/')[0] + '/']: 'glyph',
+})
+
+/**
+ * @param {string} path
+ * @returns
+ */
+export function getResourceType(path) {
+  if (path === 'style.json') return 'style'
+  for (const [prefix, type] of Object.entries(pathToResouceType)) {
+    if (path.startsWith(prefix)) return type
+  }
+  throw new Error(`Unknown resource type for path: ${path}`)
+}
+
+/**
+ * Determine the content type of a file based on its extension.
+ *
+ * @param {string} path
+ */
+export function getContentType(path) {
+  if (path.endsWith('.json')) return 'application/json; charset=utf-8'
+  if (path.endsWith('.pbf.gz') || path.endsWith('.pbf'))
+    return 'application/x-protobuf'
+  if (path.endsWith('.png')) return 'image/png'
+  if (path.endsWith('.jpg')) return 'image/jpeg'
+  if (path.endsWith('.webp')) return 'image/webp'
+  if (path.endsWith('.mvt.gz') || path.endsWith('.mvt'))
+    return 'application/vnd.mapbox-vector-tile'
+  throw new Error(`Unknown content type for path: ${path}`)
+}
+
+/**
+ * Get the filename for a tile, given the TileInfo
+ *
+ * @param {import("type-fest").SetRequired<import("../writer.js").TileInfo, 'format'>} tileInfo
+ * @returns
+ */
+export function getTileFilename({ sourceId, z, x, y, format }) {
+  const ext = '.' + format + (format === 'mvt' ? '.gz' : '')
+  return replaceVariables(TILE_FILE, { sourceId, z, x, y, ext })
+}
+
+/**
+ * Get a filename for a sprite file, given the sprite id, pixel ratio and extension
+ *
+ * @param {{ id: string, pixelRatio: number, ext: '.json' | '.png'}} spriteInfo
+ */
+export function getSpriteFilename({ id, pixelRatio, ext }) {
+  return replaceVariables(SPRITE_FILE, {
+    id,
+    pixelRatio: getPixelRatioString(pixelRatio),
+    ext,
+  })
+}
+
+/**
+ * Get the filename for a glyph file, given the fontstack and range
+ *
+ * @param {object} options
+ * @param {string} options.fontstack
+ * @param {import("../writer.js").GlyphRange} options.range
+ */
+export function getGlyphFilename({ fontstack, range }) {
+  return replaceVariables(GLYPH_FILE, { fontstack, range })
+}
+
+/**
+ * Get the URI template for the sprites in the style
+ */
+export function getSpriteUri(id = 'default') {
+  return (
+    URI_BASE + replaceVariables(SPRITE_FILE, { id, pixelRatio: '', ext: '' })
+  )
+}
+
+/**
+ * Get the URI template for tiles in the style
+ *
+ * @param {object} opts
+ * @param {string} opts.sourceId
+ * @param {import("../writer.js").TileFormat} opts.format
+ * @returns
+ */
+export function getTileUri({ sourceId, format }) {
+  const ext = '.' + format + (format === 'mvt' ? '.gz' : '')
+  return (
+    URI_BASE + TILE_FILE.replace('{sourceId}', sourceId).replace('{ext}', ext)
+  )
+}
+
+/**
+ * @param {number} pixelRatio
+ */
+function getPixelRatioString(pixelRatio) {
+  return pixelRatio === 1 ? '' : `@${pixelRatio}x`
+}
+
+/**
+ * Replaces variables in a string with values provided in an object. Variables
+ * in the string are denoted by curly braces, e.g., {variableName}.
+ *
+ * @param {string} template - The string containing variables wrapped in curly braces.
+ * @param {Record<string, string | number>} variables - An object where the keys correspond to variable names and values correspond to the replacement values.
+ * @returns {string} The string with the variables replaced by their corresponding values.
+ */
+export function replaceVariables(template, variables) {
+  return template.replace(/{(.*?)}/g, (match, varName) => {
+    return varName in variables ? String(variables[varName]) : match
+  })
+}