styled-map-package-api 5.0.0-pre.0

package/dist/reader.cjs

@@ -0,0 +1,287 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var reader_exports = {};
+__export(reader_exports, {
+  Reader: () => Reader
+});
+module.exports = __toCommonJS(reader_exports);
+var import_zip_reader = require("@gmaclennan/zip-reader");
+var import_errors = require('./utils/errors.cjs');
+var import_misc = require('./utils/misc.cjs');
+var import_style = require('./utils/style.cjs');
+var import_templates = require('./utils/templates.cjs');
+function defer() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+class Entries {
+  /** @type {Map<string, import('@gmaclennan/zip-reader').ZipEntry>} */
+  #entries = /* @__PURE__ */ new Map();
+  /** @type {Map<string, ReturnType<typeof defer<import('@gmaclennan/zip-reader').ZipEntry | undefined>>>} */
+  #deferredEntries = /* @__PURE__ */ new Map();
+  #readyPromise;
+  #ready = false;
+  #closing = false;
+  /** @type {unknown} */
+  #error;
+  /** @param {Promise<import('@gmaclennan/zip-reader').ZipReader>} zipPromise */
+  constructor(zipPromise) {
+    this.#readyPromise = (async () => {
+      try {
+        if (this.#closing) return;
+        const zip = await zipPromise;
+        if (this.#closing) return;
+        for await (const entry of zip) {
+          if (this.#closing) return;
+          this.#entries.set(entry.name, entry);
+          this.#deferredEntries.get(entry.name)?.resolve(entry);
+          this.#deferredEntries.delete(entry.name);
+        }
+      } catch (error) {
+        this.#error = error;
+        for (const deferred of this.#deferredEntries.values()) {
+          deferred.reject(error);
+        }
+        this.#deferredEntries.clear();
+        throw error;
+      } finally {
+        this.#ready = true;
+        for (const deferred of this.#deferredEntries.values()) {
+          deferred.resolve(void 0);
+        }
+        this.#deferredEntries.clear();
+      }
+    })();
+    this.#readyPromise.catch(import_misc.noop);
+  }
+  async ready() {
+    await this.#readyPromise;
+  }
+  /** @param {string} path */
+  async get(path) {
+    if (this.#entries.has(path)) {
+      return this.#entries.get(path);
+    }
+    if (this.#ready || this.#closing) {
+      if (this.#error) throw this.#error;
+      return void 0;
+    }
+    const existingDeferred = this.#deferredEntries.get(path);
+    if (existingDeferred) {
+      return existingDeferred.promise;
+    }
+    const deferred = defer();
+    this.#deferredEntries.set(path, deferred);
+    return deferred.promise;
+  }
+  async close() {
+    this.#closing = true;
+    await this.#readyPromise;
+  }
+}
+async function streamToText(readable) {
+  const chunks = (
+    /** @type {Uint8Array[]} */
+    []
+  );
+  const reader = readable.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value instanceof Uint8Array ? value : new Uint8Array(value));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const totalLen = chunks.reduce((s, c) => s + c.byteLength, 0);
+  const buf = new Uint8Array(totalLen);
+  let off = 0;
+  for (const chunk of chunks) {
+    buf.set(chunk, off);
+    off += chunk.byteLength;
+  }
+  return new TextDecoder().decode(buf);
+}
+async function streamToJson(readable) {
+  return JSON.parse(await streamToText(readable));
+}
+class Reader {
+  #entries;
+  /** @type {undefined | Promise<void>} */
+  #closePromise;
+  /** @type {import('@gmaclennan/zip-reader/file-source').FileSource | null} */
+  #fileSource = null;
+  /**
+   * @param {string | import('@gmaclennan/zip-reader').ZipReader} filepathOrZip Path to styled map package (`.styledmap`) file, or a ZipReader instance
+   */
+  constructor(filepathOrZip) {
+    let zipPromise;
+    if (typeof filepathOrZip === "string") {
+      const sourcePromise = import("@gmaclennan/zip-reader/file-source").then(
+        ({ FileSource }) => FileSource.open(filepathOrZip)
+      );
+      sourcePromise.catch(import_misc.noop);
+      zipPromise = sourcePromise.then((source) => {
+        this.#fileSource = source;
+        return import_zip_reader.ZipReader.from(source);
+      });
+    } else {
+      zipPromise = Promise.resolve(filepathOrZip);
+    }
+    zipPromise.catch(import_misc.noop);
+    this.#entries = new Entries(zipPromise);
+    this.#entries.ready().catch(() => this.close());
+  }
+  /**
+   * 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.#entries.ready();
+  }
+  /**
+   * Get the format version from the VERSION file in the styled map package.
+   * Returns "1.0" if no VERSION file exists (older SMP files did not have a
+   * VERSION file, so we assume version 1.0).
+   *
+   * @returns {Promise<string>}
+   */
+  async getVersion() {
+    const versionEntry = await this.#entries.get(import_templates.VERSION_FILE);
+    if (!versionEntry) return "1.0";
+    return (await streamToText(versionEntry.readable())).trim();
+  }
+  /**
+   * Get the style JSON from the styled map package. The URLs in the style JSON
+   * will be transformed to use the provided base URL.
+   *
+   * @param {string | null} [baseUrl] Base URL where you plan to serve the resources in this styled map package, e.g. `http://localhost:3000/maps/styleA`
+   * @returns {Promise<import('./types.js').SMPStyle>}
+   */
+  async getStyle(baseUrl = null) {
+    const styleEntry = await this.#entries.get(import_templates.STYLE_FILE);
+    if (!styleEntry) throw new import_errors.ENOENT(import_templates.STYLE_FILE);
+    const style = await streamToJson(styleEntry.readable());
+    if (!(0, import_style.validateStyle)(style)) {
+      throw new AggregateError(import_style.validateStyle.errors, "Invalid style");
+    }
+    if (typeof style.glyphs === "string") {
+      style.glyphs = getUrl(style.glyphs, baseUrl);
+    }
+    if (typeof style.sprite === "string") {
+      style.sprite = getUrl(style.sprite, baseUrl);
+    } else if (Array.isArray(style.sprite)) {
+      style.sprite = style.sprite.map(({ id, url }) => {
+        return { id, url: getUrl(url, baseUrl) };
+      });
+    }
+    for (const source of Object.values(style.sources)) {
+      if ("tiles" in source && source.tiles) {
+        source.tiles = source.tiles.map((tile) => getUrl(tile, baseUrl));
+      }
+    }
+    return (
+      /** @type {import('./types.js').SMPStyle} */
+      style
+    );
+  }
+  /**
+   * Get a resource from the styled map package. The path should be relative to
+   * the root of the package.
+   *
+   * @param {string} path
+   * @returns {Promise<Resource>}
+   */
+  async getResource(path) {
+    if (path[0] === "/") path = path.slice(1);
+    if (path === import_templates.STYLE_FILE) {
+      const styleJSON = JSON.stringify(await this.getStyle());
+      const bytes = new TextEncoder().encode(styleJSON);
+      return {
+        contentType: "application/json; charset=utf-8",
+        contentLength: bytes.byteLength,
+        resourceType: "style",
+        stream: new ReadableStream({
+          start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+          }
+        })
+      };
+    }
+    const entry = await this.#entries.get(path);
+    if (!entry) throw new import_errors.ENOENT(path);
+    const resourceType = (0, import_templates.getResourceType)(path);
+    const contentType = (0, import_templates.getContentType)(path);
+    const stream = entry.readable();
+    const resource = {
+      resourceType,
+      contentType,
+      contentLength: entry.uncompressedSize,
+      stream
+    };
+    if (path.endsWith(".gz")) {
+      resource.contentEncoding = "gzip";
+    }
+    return resource;
+  }
+  /**
+   * Close the styled map package file (should be called after reading the file to avoid memory leaks)
+   */
+  async close() {
+    if (this.#closePromise) return this.#closePromise;
+    this.#closePromise = (async () => {
+      await this.#entries.close().catch(import_misc.noop);
+      if (this.#fileSource) {
+        await this.#fileSource.close().catch(import_misc.noop);
+      }
+    })();
+    return this.#closePromise;
+  }
+}
+function getUrl(smpUri, baseUrl) {
+  if (!smpUri.startsWith(import_templates.URI_BASE)) {
+    throw new Error(`Invalid SMP URI: ${smpUri}`);
+  }
+  if (typeof baseUrl !== "string") return smpUri;
+  if (!baseUrl.endsWith("/")) {
+    baseUrl += "/";
+  }
+  return smpUri.replace(import_templates.URI_BASE, baseUrl);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Reader
+});

package/dist/reader.d.cts

@@ -0,0 +1,68 @@
+import { a as SMPStyle } from './types-CJq90eOB.cjs';
+import * as _gmaclennan_zip_reader from '@gmaclennan/zip-reader';
+import '@maplibre/maplibre-gl-style-spec';
+import 'geojson';
+import 'type-fest';
+import 'events';
+
+/**
+ * @typedef {object} Resource
+ * @property {string} resourceType
+ * @property {string} contentType
+ * @property {number} contentLength
+ * @property {ReadableStream<Uint8Array>} stream
+ * @property {'gzip'} [contentEncoding]
+ */
+/**
+ * A low-level reader for styled map packages. Returns resources in the package
+ * as readable streams, for serving over HTTP for example.
+ */
+declare class Reader {
+    /**
+     * @param {string | import('@gmaclennan/zip-reader').ZipReader} filepathOrZip Path to styled map package (`.styledmap`) file, or a ZipReader instance
+     */
+    constructor(filepathOrZip: string | _gmaclennan_zip_reader.ZipReader);
+    /**
+     * Resolves when the styled map package has been opened and the entries have
+     * been read. Throws any error that occurred during opening.
+     */
+    opened(): Promise<void>;
+    /**
+     * Get the format version from the VERSION file in the styled map package.
+     * Returns "1.0" if no VERSION file exists (older SMP files did not have a
+     * VERSION file, so we assume version 1.0).
+     *
+     * @returns {Promise<string>}
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Get the style JSON from the styled map package. The URLs in the style JSON
+     * will be transformed to use the provided base URL.
+     *
+     * @param {string | null} [baseUrl] Base URL where you plan to serve the resources in this styled map package, e.g. `http://localhost:3000/maps/styleA`
+     * @returns {Promise<import('./types.js').SMPStyle>}
+     */
+    getStyle(baseUrl?: string | null): Promise<SMPStyle>;
+    /**
+     * Get a resource from the styled map package. The path should be relative to
+     * the root of the package.
+     *
+     * @param {string} path
+     * @returns {Promise<Resource>}
+     */
+    getResource(path: string): Promise<Resource>;
+    /**
+     * Close the styled map package file (should be called after reading the file to avoid memory leaks)
+     */
+    close(): Promise<void>;
+    #private;
+}
+type Resource = {
+    resourceType: string;
+    contentType: string;
+    contentLength: number;
+    stream: ReadableStream<Uint8Array>;
+    contentEncoding?: "gzip" | undefined;
+};
+
+export { Reader, type Resource };

package/dist/reader.d.ts

@@ -0,0 +1,68 @@
+import { a as SMPStyle } from './types-CJq90eOB.js';
+import * as _gmaclennan_zip_reader from '@gmaclennan/zip-reader';
+import '@maplibre/maplibre-gl-style-spec';
+import 'geojson';
+import 'type-fest';
+import 'events';
+
+/**
+ * @typedef {object} Resource
+ * @property {string} resourceType
+ * @property {string} contentType
+ * @property {number} contentLength
+ * @property {ReadableStream<Uint8Array>} stream
+ * @property {'gzip'} [contentEncoding]
+ */
+/**
+ * A low-level reader for styled map packages. Returns resources in the package
+ * as readable streams, for serving over HTTP for example.
+ */
+declare class Reader {
+    /**
+     * @param {string | import('@gmaclennan/zip-reader').ZipReader} filepathOrZip Path to styled map package (`.styledmap`) file, or a ZipReader instance
+     */
+    constructor(filepathOrZip: string | _gmaclennan_zip_reader.ZipReader);
+    /**
+     * Resolves when the styled map package has been opened and the entries have
+     * been read. Throws any error that occurred during opening.
+     */
+    opened(): Promise<void>;
+    /**
+     * Get the format version from the VERSION file in the styled map package.
+     * Returns "1.0" if no VERSION file exists (older SMP files did not have a
+     * VERSION file, so we assume version 1.0).
+     *
+     * @returns {Promise<string>}
+     */
+    getVersion(): Promise<string>;
+    /**
+     * Get the style JSON from the styled map package. The URLs in the style JSON
+     * will be transformed to use the provided base URL.
+     *
+     * @param {string | null} [baseUrl] Base URL where you plan to serve the resources in this styled map package, e.g. `http://localhost:3000/maps/styleA`
+     * @returns {Promise<import('./types.js').SMPStyle>}
+     */
+    getStyle(baseUrl?: string | null): Promise<SMPStyle>;
+    /**
+     * Get a resource from the styled map package. The path should be relative to
+     * the root of the package.
+     *
+     * @param {string} path
+     * @returns {Promise<Resource>}
+     */
+    getResource(path: string): Promise<Resource>;
+    /**
+     * Close the styled map package file (should be called after reading the file to avoid memory leaks)
+     */
+    close(): Promise<void>;
+    #private;
+}
+type Resource = {
+    resourceType: string;
+    contentType: string;
+    contentLength: number;
+    stream: ReadableStream<Uint8Array>;
+    contentEncoding?: "gzip" | undefined;
+};
+
+export { Reader, type Resource };

package/dist/reader.js

@@ -0,0 +1,259 @@
+import { ZipReader } from "@gmaclennan/zip-reader";
+import { ENOENT } from "./utils/errors.js";
+import { noop } from "./utils/misc.js";
+import { validateStyle } from "./utils/style.js";
+import {
+  getContentType,
+  getResourceType,
+  STYLE_FILE,
+  URI_BASE,
+  VERSION_FILE
+} from "./utils/templates.js";
+function defer() {
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+class Entries {
+  /** @type {Map<string, import('@gmaclennan/zip-reader').ZipEntry>} */
+  #entries = /* @__PURE__ */ new Map();
+  /** @type {Map<string, ReturnType<typeof defer<import('@gmaclennan/zip-reader').ZipEntry | undefined>>>} */
+  #deferredEntries = /* @__PURE__ */ new Map();
+  #readyPromise;
+  #ready = false;
+  #closing = false;
+  /** @type {unknown} */
+  #error;
+  /** @param {Promise<import('@gmaclennan/zip-reader').ZipReader>} zipPromise */
+  constructor(zipPromise) {
+    this.#readyPromise = (async () => {
+      try {
+        if (this.#closing) return;
+        const zip = await zipPromise;
+        if (this.#closing) return;
+        for await (const entry of zip) {
+          if (this.#closing) return;
+          this.#entries.set(entry.name, entry);
+          this.#deferredEntries.get(entry.name)?.resolve(entry);
+          this.#deferredEntries.delete(entry.name);
+        }
+      } catch (error) {
+        this.#error = error;
+        for (const deferred of this.#deferredEntries.values()) {
+          deferred.reject(error);
+        }
+        this.#deferredEntries.clear();
+        throw error;
+      } finally {
+        this.#ready = true;
+        for (const deferred of this.#deferredEntries.values()) {
+          deferred.resolve(void 0);
+        }
+        this.#deferredEntries.clear();
+      }
+    })();
+    this.#readyPromise.catch(noop);
+  }
+  async ready() {
+    await this.#readyPromise;
+  }
+  /** @param {string} path */
+  async get(path) {
+    if (this.#entries.has(path)) {
+      return this.#entries.get(path);
+    }
+    if (this.#ready || this.#closing) {
+      if (this.#error) throw this.#error;
+      return void 0;
+    }
+    const existingDeferred = this.#deferredEntries.get(path);
+    if (existingDeferred) {
+      return existingDeferred.promise;
+    }
+    const deferred = defer();
+    this.#deferredEntries.set(path, deferred);
+    return deferred.promise;
+  }
+  async close() {
+    this.#closing = true;
+    await this.#readyPromise;
+  }
+}
+async function streamToText(readable) {
+  const chunks = (
+    /** @type {Uint8Array[]} */
+    []
+  );
+  const reader = readable.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value instanceof Uint8Array ? value : new Uint8Array(value));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const totalLen = chunks.reduce((s, c) => s + c.byteLength, 0);
+  const buf = new Uint8Array(totalLen);
+  let off = 0;
+  for (const chunk of chunks) {
+    buf.set(chunk, off);
+    off += chunk.byteLength;
+  }
+  return new TextDecoder().decode(buf);
+}
+async function streamToJson(readable) {
+  return JSON.parse(await streamToText(readable));
+}
+class Reader {
+  #entries;
+  /** @type {undefined | Promise<void>} */
+  #closePromise;
+  /** @type {import('@gmaclennan/zip-reader/file-source').FileSource | null} */
+  #fileSource = null;
+  /**
+   * @param {string | import('@gmaclennan/zip-reader').ZipReader} filepathOrZip Path to styled map package (`.styledmap`) file, or a ZipReader instance
+   */
+  constructor(filepathOrZip) {
+    let zipPromise;
+    if (typeof filepathOrZip === "string") {
+      const sourcePromise = import("@gmaclennan/zip-reader/file-source").then(
+        ({ FileSource }) => FileSource.open(filepathOrZip)
+      );
+      sourcePromise.catch(noop);
+      zipPromise = sourcePromise.then((source) => {
+        this.#fileSource = source;
+        return ZipReader.from(source);
+      });
+    } else {
+      zipPromise = Promise.resolve(filepathOrZip);
+    }
+    zipPromise.catch(noop);
+    this.#entries = new Entries(zipPromise);
+    this.#entries.ready().catch(() => this.close());
+  }
+  /**
+   * 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.#entries.ready();
+  }
+  /**
+   * Get the format version from the VERSION file in the styled map package.
+   * Returns "1.0" if no VERSION file exists (older SMP files did not have a
+   * VERSION file, so we assume version 1.0).
+   *
+   * @returns {Promise<string>}
+   */
+  async getVersion() {
+    const versionEntry = await this.#entries.get(VERSION_FILE);
+    if (!versionEntry) return "1.0";
+    return (await streamToText(versionEntry.readable())).trim();
+  }
+  /**
+   * Get the style JSON from the styled map package. The URLs in the style JSON
+   * will be transformed to use the provided base URL.
+   *
+   * @param {string | null} [baseUrl] Base URL where you plan to serve the resources in this styled map package, e.g. `http://localhost:3000/maps/styleA`
+   * @returns {Promise<import('./types.js').SMPStyle>}
+   */
+  async getStyle(baseUrl = null) {
+    const styleEntry = await this.#entries.get(STYLE_FILE);
+    if (!styleEntry) throw new ENOENT(STYLE_FILE);
+    const style = await streamToJson(styleEntry.readable());
+    if (!validateStyle(style)) {
+      throw new AggregateError(validateStyle.errors, "Invalid style");
+    }
+    if (typeof style.glyphs === "string") {
+      style.glyphs = getUrl(style.glyphs, baseUrl);
+    }
+    if (typeof style.sprite === "string") {
+      style.sprite = getUrl(style.sprite, baseUrl);
+    } else if (Array.isArray(style.sprite)) {
+      style.sprite = style.sprite.map(({ id, url }) => {
+        return { id, url: getUrl(url, baseUrl) };
+      });
+    }
+    for (const source of Object.values(style.sources)) {
+      if ("tiles" in source && source.tiles) {
+        source.tiles = source.tiles.map((tile) => getUrl(tile, baseUrl));
+      }
+    }
+    return (
+      /** @type {import('./types.js').SMPStyle} */
+      style
+    );
+  }
+  /**
+   * Get a resource from the styled map package. The path should be relative to
+   * the root of the package.
+   *
+   * @param {string} path
+   * @returns {Promise<Resource>}
+   */
+  async getResource(path) {
+    if (path[0] === "/") path = path.slice(1);
+    if (path === STYLE_FILE) {
+      const styleJSON = JSON.stringify(await this.getStyle());
+      const bytes = new TextEncoder().encode(styleJSON);
+      return {
+        contentType: "application/json; charset=utf-8",
+        contentLength: bytes.byteLength,
+        resourceType: "style",
+        stream: new ReadableStream({
+          start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+          }
+        })
+      };
+    }
+    const entry = await this.#entries.get(path);
+    if (!entry) throw new ENOENT(path);
+    const resourceType = getResourceType(path);
+    const contentType = getContentType(path);
+    const stream = entry.readable();
+    const resource = {
+      resourceType,
+      contentType,
+      contentLength: entry.uncompressedSize,
+      stream
+    };
+    if (path.endsWith(".gz")) {
+      resource.contentEncoding = "gzip";
+    }
+    return resource;
+  }
+  /**
+   * Close the styled map package file (should be called after reading the file to avoid memory leaks)
+   */
+  async close() {
+    if (this.#closePromise) return this.#closePromise;
+    this.#closePromise = (async () => {
+      await this.#entries.close().catch(noop);
+      if (this.#fileSource) {
+        await this.#fileSource.close().catch(noop);
+      }
+    })();
+    return this.#closePromise;
+  }
+}
+function getUrl(smpUri, baseUrl) {
+  if (!smpUri.startsWith(URI_BASE)) {
+    throw new Error(`Invalid SMP URI: ${smpUri}`);
+  }
+  if (typeof baseUrl !== "string") return smpUri;
+  if (!baseUrl.endsWith("/")) {
+    baseUrl += "/";
+  }
+  return smpUri.replace(URI_BASE, baseUrl);
+}
+export {
+  Reader
+};