styled-map-package 1.1.0 → 2.0.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 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/dist/reader-watch.d.ts

@@ -0,0 +1,13 @@
+/** @implements {Pick<Reader, keyof Reader>} */
+export default class ReaderWatch implements Pick<Reader, keyof Reader> {
+    /**
+     * @param {string} filepath
+     */
+    constructor(filepath: string);
+    opened(): Promise<void>;
+    getStyle(baseUrl?: string | null | undefined): Promise<import("./types.js").SMPStyle>;
+    getResource(path: string): Promise<Resource>;
+    close(): Promise<void>;
+    #private;
+}
+import Reader from './reader.js';

package/dist/server.d.ts

@@ -1,7 +1,5 @@
 export default function _default(instance: import("fastify").FastifyInstance<import("fastify").RawServerDefault, import("http").IncomingMessage, import("http").ServerResponse<import("http").IncomingMessage>, import("fastify").FastifyBaseLogger, import("fastify").FastifyTypeProviderDefault>, opts: PluginOptions, done: (err?: Error) => void): void;
-export type PluginOptions = {
-    lazy?: boolean | undefined;
-    prefix?: string | undefined;
+export type PluginOptionsFilepath = {
     /**
      * Path to styled map package (`.smp`) file
      */
@@ -10,3 +8,14 @@ export type PluginOptions = {
      */
     filepath: string;
 };
+export type PluginOptionsReader = {
+    /**
+     * SMP Reader interface (also supports ReaderWatch)
+     */
+    /**
+     * SMP Reader interface (also supports ReaderWatch)
+     */
+    reader: Pick<Reader, keyof Reader>;
+};
+export type PluginOptions = PluginOptionsFilepath | PluginOptionsReader;
+import Reader from './reader.js';

package/dist/utils/errors.d.ts

@@ -1,3 +1,13 @@
+/**
+ * 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: unknown): error is Error & {
+    code: "ENOENT" | "EPERM";
+};
 export class ENOENT extends Error {
     /** @param {string} path */
     constructor(path: string);

package/lib/index.js

@@ -2,6 +2,7 @@
 /** @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/server.js

@@ -1,17 +1,23 @@
 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} PluginOptions
- * @property {boolean} [lazy=false]
- * @property {string} [prefix]
+ * @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
@@ -29,60 +35,28 @@ 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, { lazy = false, filepath }, done) {
-  /** @type {Reader | undefined} */
-  let _reader
-  /** @type {Promise<Reader> | undefined} */
-  let _readerOpeningPromise
-
-  async function getReader() {
-    // 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 (_reader) return _reader
-    if (_readerOpeningPromise) return _readerOpeningPromise
-    const maybeReader = new Reader(filepath)
-    _readerOpeningPromise = maybeReader
-      .opened()
-      .then(() => {
-        _reader = maybeReader
-        return _reader
-      })
-      .finally(() => {
-        _readerOpeningPromise = undefined
-      })
-    return _readerOpeningPromise
-  }
+export default function (fastify, opts, done) {
+  const reader = 'reader' in opts ? opts.reader : new Reader(opts.filepath)
 
-  if (!lazy) {
-    getReader().catch(noop)
+  // Only close the reader if it was created by this plugin
+  if (!('reader' in opts)) {
+    fastify.addHook('onClose', () => reader.close().catch(noop))
   }
 
-  fastify.addHook('onClose', async () => {
-    try {
-      const reader = await getReader()
-      await reader.close()
-    } catch {
-      // ignore
-    }
-  })
-
   fastify.get('/style.json', async () => {
     try {
-      const reader = await getReader()
       const baseUrl = new URL(fastify.prefix, fastify.listeningOrigin)
-      return reader.getStyle(baseUrl.href)
+      const style = await reader.getStyle(baseUrl.href)
+      return style
     } catch (error) {
-      if (isENOENT(error)) {
+      if (isFileNotThereError(error)) {
         throw createError(404, error.message)
       }
       throw error
@@ -94,11 +68,10 @@ export default function (fastify, { lazy = false, filepath }, done) {
     const path = request.params['*']
 
     try {
-      const reader = await getReader()
       const resource = await reader.getResource(path)
       return sendResource(reply, resource)
     } catch (error) {
-      if (isENOENT(error)) {
+      if (isFileNotThereError(error)) {
         throw createError(404, error.message)
       }
       throw error
@@ -106,11 +79,3 @@ export default function (fastify, { lazy = false, filepath }, done) {
   })
   done()
 }
-
-/**
- * @param {unknown} error
- * @returns {error is Error & { code: 'ENOENT' }}
- */
-function isENOENT(error) {
-  return error instanceof Error && 'code' in error && error.code === 'ENOENT'
-}

package/lib/utils/errors.js

@@ -7,3 +7,18 @@ export class ENOENT extends Error {
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styled-map-package",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "",
   "exports": {
     ".": {
@@ -11,6 +11,10 @@
       "types": "./dist/reader.d.ts",
       "import": "./lib/reader.js"
     },
+    "./reader-watch": {
+      "types": "./dist/reader-watch.d.ts",
+      "import": "./lib/reader-watch.js"
+    },
     "./writer": {
       "types": "./dist/writer.d.ts",
       "import": "./lib/writer.js"