styled-map-package 1.0.1 → 2.0.0

package/dist/utils/streams.d.ts

@@ -0,0 +1,69 @@
+/** @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<T extends (...args: any[]) => Promise<void>>(fn: T, { concurrency }?: {
+    concurrency?: number | undefined;
+}): import("readable-stream").Writable;
+/**
+ * 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: ReadableStream, options?: {
+    highWaterMark?: number;
+    encoding?: string;
+    objectMode?: boolean;
+    signal?: AbortSignal;
+} | undefined): import("stream").Readable;
+/**
+ * @param {unknown} obj
+ * @returns {obj is ReadableStream}
+ */
+export function isWebReadableStream(obj: unknown): obj is ReadableStream;
+/** @typedef {(opts: { totalBytes: number, chunkBytes: number }) => void} ProgressCallback */
+/** @typedef {TransformOptions & { onprogress?: ProgressCallback }} ProgressStreamOptions */
+/**
+ * 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.
+ * @extends {Transform}
+ */
+export class ProgressStream extends Transform {
+    /**
+     * @param {ProgressStreamOptions} [opts]
+     */
+    constructor({ onprogress, ...opts }?: ProgressStreamOptions | undefined);
+    /** Total bytes that have passed through this stream */
+    get byteLength(): number;
+    /**
+     * @override
+     * @param {Buffer | Uint8Array} chunk
+     * @param {Parameters<Transform['_transform']>[1]} encoding
+     * @param {Parameters<Transform['_transform']>[2]} callback
+     */
+    override _transform(chunk: Buffer | Uint8Array, encoding: Parameters<Transform["_transform"]>[1], callback: Parameters<Transform["_transform"]>[2]): void;
+    #private;
+}
+export type ProgressCallback = (opts: {
+    totalBytes: number;
+    chunkBytes: number;
+}) => void;
+export type ProgressStreamOptions = TransformOptions & {
+    onprogress?: ProgressCallback;
+};
+import { Transform } from 'readable-stream';
+import type { TransformOptions } from 'readable-stream';

package/dist/utils/style.d.ts

@@ -0,0 +1,59 @@
+/** @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: StyleSpecification, fonts: string[]): StyleSpecification;
+/**
+ * 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: StyleSpecification["layers"], callbackFn: (fontStack: string[]) => string[]): StyleSpecification["layers"];
+/**
+ * @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: unknown): asserts tilejson is TileJSONPartial;
+/**
+ * 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: import("@maplibre/maplibre-gl-style-spec").SourceSpecification): source is import("../types.js").InlinedSource;
+export const validateStyle: {
+    (style: unknown): style is StyleSpecification;
+    errors: ValidationError[];
+};
+export type TileJSONPartial = {
+    tiles: string[];
+    description?: string | undefined;
+    attribution?: string | undefined;
+    vector_layers?: object[] | undefined;
+    bounds?: import("./geo.js").BBox | undefined;
+    maxzoom?: number | undefined;
+    minzoom?: number | undefined;
+};
+import type { StyleSpecification } from '@maplibre/maplibre-gl-style-spec';
+import type { ValidationError } from '@maplibre/maplibre-gl-style-spec';

package/dist/utils/templates.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @param {string} path
+ * @returns
+ */
+export function getResourceType(path: string): "sprite" | "tile" | "glyph" | "style";
+/**
+ * Determine the content type of a file based on its extension.
+ *
+ * @param {string} path
+ */
+export function getContentType(path: string): "application/json; charset=utf-8" | "application/x-protobuf" | "image/png" | "image/jpeg" | "image/webp" | "application/vnd.mapbox-vector-tile";
+/**
+ * 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 }: import("type-fest").SetRequired<import("../writer.js").TileInfo, "format">): string;
+/**
+ * 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 }: {
+    id: string;
+    pixelRatio: number;
+    ext: ".json" | ".png";
+}): string;
+/**
+ * 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 }: {
+    fontstack: string;
+    range: import("../writer.js").GlyphRange;
+}): string;
+/**
+ * Get the URI template for the sprites in the style
+ */
+export function getSpriteUri(id?: string): string;
+/**
+ * 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 }: {
+    sourceId: string;
+    format: import("../writer.js").TileFormat;
+}): string;
+/**
+ * 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: string, variables: Record<string, string | number>): string;
+export const URI_SCHEME: "smp";
+export const URI_BASE: string;
+export const STYLE_FILE: "style.json";
+export const GLYPH_URI: string;

package/dist/writer.d.ts

@@ -0,0 +1,130 @@
+/** @typedef {string | Buffer | Uint8Array | import('stream').Readable } Source */
+/** @typedef {string | Buffer | import('stream').Readable} SourceInternal */
+/** @typedef {`${number}-${number}`} GlyphRange */
+/** @typedef {'png' | 'mvt' | 'jpg' | 'webp'} TileFormat */
+/**
+ * @typedef {object} SourceInfo
+ * @property {import('./types.js').SMPSource} source
+ * @property {string} encodedSourceId
+ * @property {TileFormat} [format]
+ */
+/**
+ * @typedef {object} TileInfo
+ * @property {number} z
+ * @property {number} x
+ * @property {number} y
+ * @property {string} sourceId
+ * @property {TileFormat} [format]
+ */
+/**
+ * @typedef {object} GlyphInfo
+ * @property {string} font
+ * @property {GlyphRange} range
+ */
+/** @import { StyleSpecification } from '@maplibre/maplibre-gl-style-spec' */
+/** @import { InputSource, SMPSource } from './types.js' */
+export const SUPPORTED_SOURCE_TYPES: readonly ["raster", "vector", "geojson"];
+/**
+ * Write a styled map package to a stream. Stream `writer.outputStream` to a
+ * destination, e.g. `fs.createWriteStream('my-map.styledmap')`. You must call
+ * `witer.finish()` and then wait for your writable stream to `finish` before
+ * using the output.
+ */
+export default class Writer extends EventEmitter<[never]> {
+    static SUPPORTED_SOURCE_TYPES: readonly ["raster", "vector", "geojson"];
+    /**
+     * @param {any} style A v7 or v8 MapLibre style. v7 styles will be migrated to
+     * v8. (There are currently no typescript declarations for v7 styles, hence
+     * this is typed as `any` and validated internally)
+     * @param {object} opts
+     * @param {number} [opts.highWaterMark=1048576] The maximum number of bytes to buffer during write
+     */
+    constructor(style: any, { highWaterMark }?: {
+        highWaterMark?: number | undefined;
+    });
+    /**
+     * @returns {import('stream').Readable} Readable stream of the styled map package
+     */
+    get outputStream(): Readable;
+    /**
+     * Add a tile to the styled map package
+     *
+     * @param {Source} tileData
+     * @param {TileInfo} opts
+     */
+    addTile(tileData: Source, { z, x, y, sourceId, format }: TileInfo): Promise<void>;
+    /**
+     * Create a write stream for adding tiles to the styled map package
+     *
+     * @param {object} opts
+     * @param {number} [opts.concurrency=16] The number of concurrent writes
+     *
+     * @returns
+     */
+    createTileWriteStream({ concurrency }?: {
+        concurrency?: number | undefined;
+    }): import("readable-stream").Writable;
+    /**
+     * Add a sprite to the styled map package
+     *
+     * @param {object} options
+     * @param {Source} options.json
+     * @param {Source} options.png
+     * @param {number} [options.pixelRatio]
+     * @param {string} [options.id='default']
+     * @returns {Promise<void>}
+     */
+    addSprite({ json, png, pixelRatio, id }: {
+        json: Source;
+        png: Source;
+        pixelRatio?: number | undefined;
+        id?: string | undefined;
+    }): Promise<void>;
+    /**
+     * Add glyphs to the styled map package
+     *
+     * @param {Source} glyphData
+     * @param {GlyphInfo} glyphInfo
+     * @returns {Promise<void>}
+     */
+    addGlyphs(glyphData: Source, { font: fontName, range }: GlyphInfo): Promise<void>;
+    /**
+     * Create a write stream for adding glyphs to the styled map package
+     *
+     * @param {object} opts
+     * @param {number} [opts.concurrency=16] The number of concurrent writes
+     * @returns
+     */
+    createGlyphWriteStream({ concurrency }?: {
+        concurrency?: number | undefined;
+    }): import("readable-stream").Writable;
+    /**
+     * Finalize the styled map package and write the style to the archive.
+     * This method must be called to complete the archive.
+     * You must wait for your destination write stream to 'finish' before using the output.
+     */
+    finish(): void;
+    #private;
+}
+export type Source = string | Buffer | Uint8Array | import("stream").Readable;
+export type SourceInternal = string | Buffer | import("stream").Readable;
+export type GlyphRange = `${number}-${number}`;
+export type TileFormat = "png" | "mvt" | "jpg" | "webp";
+export type SourceInfo = {
+    source: import("./types.js").SMPSource;
+    encodedSourceId: string;
+    format?: TileFormat | undefined;
+};
+export type TileInfo = {
+    z: number;
+    x: number;
+    y: number;
+    sourceId: string;
+    format?: TileFormat | undefined;
+};
+export type GlyphInfo = {
+    font: string;
+    range: GlyphRange;
+};
+import { EventEmitter } from 'events';
+import { Readable } from 'stream';

package/lib/index.js

@@ -1,4 +1,8 @@
+/** @typedef {import('./types.js').SMPSource} SMPSource */
+/** @typedef {import('./types.js').SMPStyle} SMPStyle */
+
 export { default as Reader } from './reader.js'
+export { default as ReaderWatch } from './reader-watch.js'
 export { default as Writer } from './writer.js'
 export { default as Server } from './server.js'
 export { default as StyleDownloader } from './style-downloader.js'

package/lib/reader-watch.js

@@ -0,0 +1,133 @@
+import { once } from 'events'
+
+import fs from 'node:fs'
+import fsPromises from 'node:fs/promises'
+
+import Reader from './reader.js'
+import { ENOENT, isFileNotThereError } from './utils/errors.js'
+import { noop } from './utils/misc.js'
+
+/** @implements {Pick<Reader, keyof Reader>} */
+export default class ReaderWatch {
+  /** @type {Reader | undefined} */
+  #reader
+  /** @type {Reader | undefined} */
+  #maybeReader
+  /** @type {Promise<Reader> | undefined} */
+  #readerOpeningPromise
+  #filepath
+  /** @type {fs.FSWatcher | undefined} */
+  #watch
+
+  /**
+   * @param {string} filepath
+   */
+  constructor(filepath) {
+    this.#filepath = filepath
+    // Call this now to catch any synchronous errors
+    this.#tryToWatchFile()
+    // eagerly open Reader
+    this.#get().catch(noop)
+  }
+
+  #tryToWatchFile() {
+    if (this.#watch) return
+    try {
+      this.#watch = fs
+        .watch(this.#filepath, { persistent: false }, () => {
+          this.#reader?.close().catch(noop)
+          this.#reader = undefined
+          this.#maybeReader = undefined
+          this.#readerOpeningPromise = undefined
+          // Close the watcher (which on some platforms will continue watching
+          // the previous file) so on the next request we will start watching
+          // the new file
+          this.#watch?.close()
+          this.#watch = undefined
+        })
+        .on('error', noop)
+    } catch (error) {
+      if (isFileNotThereError(error)) {
+        // Ignore: File does not exist yet, but we'll try to open it later
+      } else {
+        throw error
+      }
+    }
+  }
+
+  async #get() {
+    if (isWin() && (this.#reader || this.#readerOpeningPromise)) {
+      // On Windows, the file watcher does not recognize file deletions, so we
+      // need to check if the file still exists each time
+      try {
+        await fsPromises.stat(this.#filepath)
+      } catch {
+        this.#watch?.close()
+        this.#watch = undefined
+        this.#reader?.close().catch(noop)
+        this.#reader = undefined
+        this.#maybeReader = undefined
+        this.#readerOpeningPromise = undefined
+      }
+    }
+    // Need to retry this each time in case it failed initially because the file
+    // was not present, or if the file was moved or deleted.
+    this.#tryToWatchFile()
+    // A lovely promise tangle to confuse future readers... sorry.
+    //
+    // 1. If the reader is already open, return it.
+    // 2. If the reader is in the process of opening, return a promise that will
+    //    return the reader instance if it opened without error, or throw.
+    // 3. If the reader threw an error during opening, try to open it again next
+    //    time this is called.
+    if (this.#reader) return this.#reader
+    if (this.#readerOpeningPromise) return this.#readerOpeningPromise
+    this.#maybeReader = new Reader(this.#filepath)
+    this.#readerOpeningPromise = this.#maybeReader
+      .opened()
+      .then(() => {
+        if (!this.#maybeReader) {
+          throw new ENOENT(this.#filepath)
+        }
+        this.#reader = this.#maybeReader
+        return this.#reader
+      })
+      .finally(() => {
+        this.#maybeReader = undefined
+        this.#readerOpeningPromise = undefined
+      })
+    return this.#readerOpeningPromise
+  }
+
+  /** @type {Reader['opened']} */
+  async opened() {
+    const reader = await this.#get()
+    return reader.opened()
+  }
+
+  /** @type {Reader['getStyle']} */
+  async getStyle(baseUrl = null) {
+    const reader = await this.#get()
+    return reader.getStyle(baseUrl)
+  }
+
+  /** @type {Reader['getResource']} */
+  async getResource(path) {
+    const reader = await this.#get()
+    return reader.getResource(path)
+  }
+
+  async close() {
+    const reader = await this.#get()
+    if (this.#watch) {
+      this.#watch.close()
+      await once(this.#watch, 'close')
+    }
+    await reader.close()
+  }
+}
+
+/** @returns {boolean} */
+function isWin() {
+  return process.platform === 'win32'
+}

package/lib/reader.js

@@ -3,6 +3,8 @@ import { open } from 'yauzl-promise'
 
 import { json } from 'node:stream/consumers'
 
+import { ENOENT } from './utils/errors.js'
+import { noop } from './utils/misc.js'
 import { validateStyle } from './utils/style.js'
 import {
   getContentType,
@@ -39,6 +41,7 @@ export default class Reader {
       typeof filepathOrZip === 'string'
         ? open(filepathOrZip)
         : Promise.resolve(filepathOrZip))
+    zipPromise.catch(noop)
     this.#entriesPromise = (async () => {
       /** @type {Map<string, import('yauzl-promise').Entry>} */
       const entries = new Map()
@@ -51,6 +54,15 @@ export default class Reader {
       }
       return entries
     })()
+    this.#entriesPromise.catch(noop)
+  }
+
+  /**
+   * Resolves when the styled map package has been opened and the entries have
+   * been read. Throws any error that occurred during opening.
+   */
+  async opened() {
+    await this.#entriesPromise
   }
 
   /**
@@ -62,7 +74,7 @@ export default class Reader {
    */
   async getStyle(baseUrl = null) {
     const styleEntry = (await this.#entriesPromise).get(STYLE_FILE)
-    if (!styleEntry) throw new Error(`File not found: ${STYLE_FILE}`)
+    if (!styleEntry) throw new ENOENT(STYLE_FILE)
     const stream = await styleEntry.openReadStream()
     const style = await json(stream)
     if (!validateStyle(style)) {
@@ -107,7 +119,7 @@ export default class Reader {
       }
     }
     const entry = (await this.#entriesPromise).get(path)
-    if (!entry) throw new Error(`File not found: ${path}`)
+    if (!entry) throw new ENOENT(path)
     const resourceType = getResourceType(path)
     const contentType = getContentType(path)
     const stream = await entry.openReadStream()
@@ -146,5 +158,8 @@ function getUrl(smpUri, baseUrl) {
     throw new Error(`Invalid SMP URI: ${smpUri}`)
   }
   if (typeof baseUrl !== 'string') return smpUri
-  return smpUri.replace(URI_BASE, baseUrl + '/')
+  if (!baseUrl.endsWith('/')) {
+    baseUrl += '/'
+  }
+  return smpUri.replace(URI_BASE, baseUrl)
 }

package/lib/server.js

@@ -1,13 +1,24 @@
-/**
- * @typedef {object} PluginOptions
- * @property {string} filepath
- * @property {boolean} [lazy=false]
- */
+import createError from 'http-errors'
+
 import Reader from './reader.js'
+import { isFileNotThereError } from './utils/errors.js'
+import { noop } from './utils/misc.js'
 
 /** @import { FastifyPluginCallback, FastifyReply } from 'fastify' */
 /** @import { Resource } from './reader.js' */
 
+/**
+ * @typedef {object} PluginOptionsFilepath
+ * @property {string} filepath Path to styled map package (`.smp`) file
+ */
+/**
+ * @typedef {object} PluginOptionsReader
+ * @property {Pick<Reader, keyof Reader>} reader SMP Reader interface (also supports ReaderWatch)
+ */
+/**
+ * @typedef {PluginOptionsFilepath | PluginOptionsReader} PluginOptions
+ */
+
 /**
  * @param {FastifyReply} reply
  * @param {Resource} resource
@@ -24,41 +35,47 @@ function sendResource(reply, resource) {
 }
 
 /**
- * Fastify plugin for serving a styled map package. User `lazy: true` to defer
- * opening the file until the first request.
+ * Fastify plugin for serving a styled map package.
+ *
+ * If you provide a `Reader` (or `ReaderWatch`) instance via the `reader` opt,
+ * you must manually close the instance yourself.
  *
  * @type {FastifyPluginCallback<PluginOptions>}
  */
-export default function (fastify, { filepath, lazy = false }, done) {
-  /** @type {Reader | undefined} */
-  let reader
-  if (!lazy) {
-    reader = new Reader(filepath)
+export default function (fastify, opts, done) {
+  const reader = 'reader' in opts ? opts.reader : new Reader(opts.filepath)
+
+  // Only close the reader if it was created by this plugin
+  if (!('reader' in opts)) {
+    fastify.addHook('onClose', () => reader.close().catch(noop))
   }
 
   fastify.get('/style.json', async () => {
-    if (!reader) {
-      reader = new Reader(filepath)
+    try {
+      const baseUrl = new URL(fastify.prefix, fastify.listeningOrigin)
+      const style = await reader.getStyle(baseUrl.href)
+      return style
+    } catch (error) {
+      if (isFileNotThereError(error)) {
+        throw createError(404, error.message)
+      }
+      throw error
     }
-    return reader.getStyle(fastify.listeningOrigin)
   })
 
   fastify.get('*', async (request, reply) => {
-    if (!reader) {
-      reader = new Reader(filepath)
-    }
+    // @ts-expect-error - not worth the hassle of type casting this
+    const path = request.params['*']
 
-    /** @type {Resource} */
-    let resource
     try {
-      resource = await reader.getResource(decodeURI(request.url))
-    } catch (e) {
-      // @ts-ignore
-      e.statusCode = 404
-      throw e
+      const resource = await reader.getResource(path)
+      return sendResource(reply, resource)
+    } catch (error) {
+      if (isFileNotThereError(error)) {
+        throw createError(404, error.message)
+      }
+      throw error
     }
-
-    return sendResource(reply, resource)
   })
   done()
 }

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')
+  )
+}

package/lib/utils/streams.js

@@ -123,18 +123,20 @@ export function isWebReadableStream(obj) {
 }
 
 /** @typedef {(opts: { totalBytes: number, chunkBytes: number }) => void} ProgressCallback */
+/** @typedef {TransformOptions & { onprogress?: ProgressCallback }} ProgressStreamOptions */
 
 /**
  * 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.
+ * @extends {Transform}
  */
 export class ProgressStream extends Transform {
   #onprogress
   #byteLength = 0
 
   /**
-   * @param {TransformOptions & { onprogress?: ProgressCallback }} [opts]
+   * @param {ProgressStreamOptions} [opts]
    */
   constructor({ onprogress, ...opts } = {}) {
     super(opts)
@@ -147,6 +149,7 @@ export class ProgressStream extends Transform {
   }
 
   /**
+   * @override
    * @param {Buffer | Uint8Array} chunk
    * @param {Parameters<Transform['_transform']>[1]} encoding
    * @param {Parameters<Transform['_transform']>[2]} callback