@goauthentik/esbuild-plugin-live-reload 1.6.1 → 2.0.1

package/README.md

@@ -47,7 +47,7 @@ Add the following import near the beginning of your application's entry point.
 
 ```js
 if (process.env.NODE_ENV === "development") {
-    await import("@goauthentik/esbuild-plugin-live-reload/client");
+    await import("@goauthentik/esbuild-plugin-live-reload");
 }
 ```
 
@@ -69,11 +69,11 @@ This code is licensed under the [MIT License](https://www.tldrlegal.com/license/
 
 #### Properties
 
-| Property                                      | Type                                                                   |
-| --------------------------------------------- | ---------------------------------------------------------------------- |
-| <a id="property-dispatcher"></a> `dispatcher` | `EventTarget`                                                          |
-| <a id="property-logger"></a> `logger?`        | `Pick`\<`BaseLogger`, `"warn"` \| `"error"` \| `"debug"` \| `"info"`\> |
-| <a id="property-pathname"></a> `pathname`     | `string`                                                               |
+| Property                                      | Type          |
+| --------------------------------------------- | ------------- |
+| <a id="property-dispatcher"></a> `dispatcher` | `EventTarget` |
+| <a id="property-logger"></a> `logger?`        | `Logger`      |
+| <a id="property-pathname"></a> `pathname`     | `string`      |
 
 ---
 
@@ -84,16 +84,16 @@ This code is licensed under the [MIT License](https://www.tldrlegal.com/license/
 | Property                                             | Type                                                                                                                                   | Description                                                                                                     |
 | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
 | <a id="property-listenoptions"></a> `listenOptions?` | `ListenOptions`                                                                                                                        | Options for the server's listen method.                                                                         |
-| <a id="property-logger-1"></a> `logger?`             | `Pick`\<`BaseLogger`, `"warn"` \| `"error"` \| `"debug"` \| `"info"`\>                                                                 | A console-like logger.                                                                                          |
+| <a id="property-logger-1"></a> `logger?`             | `Logger`                                                                                                                               | A console-like logger.                                                                                          |
 | <a id="property-publicurl"></a> `publicURL?`         | `string` \| `URL`                                                                                                                      | A URL to listen on. If not provided, a random port will be used.                                                |
 | <a id="property-relativeroot"></a> `relativeRoot?`   | `string`                                                                                                                               | A relative path to the root of the project. This is used to resolve build errors, line numbers, and file paths. |
 | <a id="property-server"></a> `server?`               | `Server`\<_typeof_ `IncomingMessage`, _typeof_ `ServerResponse`\> \| `Server`\<_typeof_ `IncomingMessage`, _typeof_ `ServerResponse`\> | A server to listen on. If not provided, a new server will be created.                                           |
 
 ---
 
-### RequestHandler()
+### RequestHandler
 
-> **RequestHandler**\<\> = (`req`, `res`) => `void`
+> **RequestHandler** = (`req`, `res`) => `void`
 
 #### Type Parameters
 

package/client/index.js

@@ -1,13 +1,242 @@
 /**
- * @file Entry point for the ESBuild client-side observer.
+ * @file Client-side observer for ESBuild events.
+ *
+ * @import { BaseLogger } from "@goauthentik/logger-js";
+ * @import { Message as ESBuildMessage } from "esbuild";
  */
+
 /// <reference types="./types.js" />
-import { ESBuildObserver } from "./ESBuildObserver.js";
 
-if (import.meta.env?.ESBUILD_WATCHER_URL) {
-    const buildObserver = new ESBuildObserver(import.meta.env.ESBUILD_WATCHER_URL);
+import { createLogger } from "@goauthentik/esbuild-plugin-live-reload/shared";
+
+if (typeof EventSource === "undefined") {
+    throw new TypeError("Environment doesn't appear to have an EventSource constructor");
+}
+
+/**
+ * @template {unknown} [Data=unknown]
+ * @typedef {(event: MessageEvent) => void} BuildEventListener
+ */
+
+/**
+ * A symbol used to dispose of resources.
+ *
+ * @type {typeof Symbol.dispose}
+ */
+const disposeSymbol = Symbol.dispose || Symbol.for("dispose");
+
+/**
+ * A client-side watcher for ESBuild.
+ *
+ * Note that this should be conditionally imported in your code, so that
+ * ESBuild may tree-shake it out of production builds.
+ *
+ * ```ts
+ * if (process.env.NODE_ENV === "development") {
+ *   await import("@goauthentik/esbuild-plugin-live-reload")
+ *     .catch(() => console.warn("Failed to import watcher"))
+ * }
+ * ```
+ *
+ * @implements {Disposable}
+ * @category Plugin
+ * @runtime browser
+ */
+export class ESBuildObserver extends EventSource {
+    /**
+     * @type {BaseLogger}
+     * @protected
+     */
+    logger;
+
+    /**
+     * Whether the watcher has a recent connection to the server.
+     */
+    alive = true;
+
+    /**
+     * The number of errors that have occurred since the watcher started.
+     */
+    errorCount = 0;
+
+    /**
+     * Whether a reload has been requested while offline.
+     */
+    deferredReload = false;
+
+    /**
+     * The last time a message was received from the server.
+     */
+    lastUpdatedAt = Date.now();
+
+    /**
+     * Whether the browser considers itself online.
+     */
+    online = true;
+
+    /**
+     * The ID of the animation frame for the reload.
+     */
+    #reloadFrameID = -1;
+
+    /**
+     * The interval for the keep-alive check.
+     * @type {ReturnType<typeof setInterval> | undefined}
+     */
+    #keepAliveInterval;
+
+    #trackActivity = () => {
+        this.lastUpdatedAt = Date.now();
+        this.alive = true;
+    };
+
+    /**
+     * @type {BuildEventListener}
+     */
+    #startListener = () => {
+        this.#trackActivity();
+        this.logger.info("⏰ Build started...");
+    };
+
+    #internalErrorListener = () => {
+        this.errorCount += 1;
+
+        if (this.errorCount > 100) {
+            clearTimeout(this.#keepAliveInterval);
+
+            this.close();
+            this.logger.info("⛔️ Closing connection");
+        }
+    };
+
+    /**
+     * @type {BuildEventListener<string>}
+     */
+    #errorListener = (event) => {
+        this.#trackActivity();
+
+        this.logger.warn("⛔️⛔️⛔️  Build error...");
+
+        /**
+         * @type {ESBuildMessage[]}
+         */
+        const esbuildErrorMessages = JSON.parse(event.data);
+
+        for (const error of esbuildErrorMessages) {
+            this.logger.warn(error.text);
 
-    window.addEventListener("beforeunload", () => {
-        buildObserver.dispose();
-    });
+            if (error.location) {
+                this.logger.debug(
+                    `file://${error.location.file}:${error.location.line}:${error.location.column}`,
+                );
+                this.logger.debug(error.location.lineText);
+            }
+        }
+    };
+
+    /**
+     * @type {BuildEventListener}
+     */
+    #endListener = () => {
+        cancelAnimationFrame(this.#reloadFrameID);
+
+        this.#trackActivity();
+
+        if (!this.online) {
+            this.logger.info("🚫 Build finished while offline.");
+            this.deferredReload = true;
+
+            return;
+        }
+
+        this.logger.info("🛎️ Build completed! Reloading...");
+
+        // We use an animation frame to keep the reload from happening before the
+        // event loop has a chance to process the message.
+        this.#reloadFrameID = requestAnimationFrame(() => {
+            location.reload();
+        });
+    };
+
+    /**
+     * @type {BuildEventListener}
+     */
+    #keepAliveListener = () => {
+        this.#trackActivity();
+        this.logger.info("🏓 Keep-alive");
+    };
+
+    /**
+     * Initialize the ESBuild observer. This should only be called once.
+     *
+     * @param {string | URL} [url]
+     * @param {BaseLogger} [logger]
+     * @returns {ESBuildObserver}
+     */
+    static initialize = (url, logger) => {
+        const esbuildObserver = new ESBuildObserver(url, logger);
+
+        return esbuildObserver;
+    };
+
+    /**
+     *
+     * @param {string | URL} [url]
+     * @param {BaseLogger} [logger]
+     */
+    constructor(url, logger = createLogger()) {
+        if (!url) {
+            throw new TypeError("ESBuildObserver: Cannot construct without a URL");
+        }
+
+        super(url);
+
+        this.logger = logger;
+
+        this.addEventListener("esbuild:start", this.#startListener);
+        this.addEventListener("esbuild:end", this.#endListener);
+        this.addEventListener("esbuild:error", this.#errorListener);
+        this.addEventListener("esbuild:keep-alive", this.#keepAliveListener);
+
+        this.addEventListener("error", this.#internalErrorListener);
+
+        addEventListener("offline", () => {
+            this.online = false;
+        });
+
+        addEventListener("online", () => {
+            this.online = true;
+
+            if (!this.deferredReload) return;
+
+            this.logger.info("🛎️ Reloading after offline build...");
+            this.deferredReload = false;
+
+            location.reload();
+        });
+
+        this.logger.debug("🛎️ Listening for build changes...");
+
+        this.#keepAliveInterval = setInterval(() => {
+            const now = Date.now();
+
+            if (now - this.lastUpdatedAt < 10_000) return;
+
+            this.alive = false;
+        }, 15_000);
+
+        addEventListener("beforeunload", this.dispose);
+    }
+
+    [disposeSymbol]() {
+        clearTimeout(this.#keepAliveInterval);
+
+        return this.close();
+    }
+
+    dispose = () => {
+        return this[disposeSymbol]();
+    };
 }
+
+export default ESBuildObserver;

package/index.js

@@ -1,6 +1,11 @@
 /**
- * @remarks Live reload plugin for ESBuild.
+ * @file Entry point for the ESBuild client-side observer.
  */
 
-export * from "./client/index.js";
-export * from "./plugin/index.js";
+/// <reference types="./client/types.js" />
+
+import { ESBuildObserver } from "./client/index.js";
+
+if (import.meta.env?.ESBUILD_WATCHER_URL) {
+    ESBuildObserver.initialize(import.meta.env.ESBUILD_WATCHER_URL);
+}

package/out/client/index.d.ts

@@ -1,2 +1,65 @@
-export {};
+/**
+ * A client-side watcher for ESBuild.
+ *
+ * Note that this should be conditionally imported in your code, so that
+ * ESBuild may tree-shake it out of production builds.
+ *
+ * ```ts
+ * if (process.env.NODE_ENV === "development") {
+ *   await import("@goauthentik/esbuild-plugin-live-reload")
+ *     .catch(() => console.warn("Failed to import watcher"))
+ * }
+ * ```
+ *
+ * @implements {Disposable}
+ * @category Plugin
+ * @runtime browser
+ */
+export class ESBuildObserver extends EventSource implements Disposable {
+    /**
+     * Initialize the ESBuild observer. This should only be called once.
+     *
+     * @param {string | URL} [url]
+     * @param {BaseLogger} [logger]
+     * @returns {ESBuildObserver}
+     */
+    static initialize: (url?: string | URL, logger?: BaseLogger) => ESBuildObserver;
+    /**
+     *
+     * @param {string | URL} [url]
+     * @param {BaseLogger} [logger]
+     */
+    constructor(url?: string | URL, logger?: BaseLogger);
+    /**
+     * @type {BaseLogger}
+     * @protected
+     */
+    protected logger: BaseLogger;
+    /**
+     * Whether the watcher has a recent connection to the server.
+     */
+    alive: boolean;
+    /**
+     * The number of errors that have occurred since the watcher started.
+     */
+    errorCount: number;
+    /**
+     * Whether a reload has been requested while offline.
+     */
+    deferredReload: boolean;
+    /**
+     * The last time a message was received from the server.
+     */
+    lastUpdatedAt: number;
+    /**
+     * Whether the browser considers itself online.
+     */
+    online: boolean;
+    dispose: () => void;
+    [Symbol.dispose](): void;
+    #private;
+}
+export default ESBuildObserver;
+export type BuildEventListener<Data extends unknown = unknown> = (event: MessageEvent) => void;
+import type { BaseLogger } from "@goauthentik/logger-js";
 //# sourceMappingURL=index.d.ts.map

package/out/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../client/index.js"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../client/index.js"],"names":[],"mappings":"AA2BA;;;;;;;;;;;;;;;;GAgBG;AACH,4DAJgB,UAAU;IAgItB;;;;;;OAMG;IACH,oBAAqB,MAJV,MAAM,GAAG,GAII,EAAE,SAHf,UAGqB,KAFnB,eAAe,CAM1B;IAEF;;;;OAIG;IACH,kBAHW,MAAM,GAAG,GAAG,WACZ,UAAU,EA4CpB;IAvLD;;;OAGG;IACH,kBAHU,UAAU,CAGb;IAEP;;OAEG;IACH,eAAa;IAEb;;OAEG;IACH,mBAAe;IAEf;;OAEG;IACH,wBAAuB;IAEvB;;OAEG;IACH,sBAA2B;IAE3B;;OAEG;IACH,gBAAc;IAkKd,oBAEE;IARF,yBAIC;;CAKJ;;+BA/NuB,IAAI,SAAf,OAAS,cACT,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI;gCAdX,wBAAwB"}

package/out/index.d.ts

@@ -1,3 +1,2 @@
-export * from "./client/index.js";
-export * from "./plugin/index.js";
+export {};
 //# sourceMappingURL=index.d.ts.map

package/out/plugin/index.d.ts

@@ -66,7 +66,7 @@ export default liveReloadPlugin;
 export type EventServerInit = {
     pathname: string;
     dispatcher: EventTarget;
-    logger?: Pick<import("pino").BaseLogger, "warn" | "error" | "debug" | "info"> | undefined;
+    logger?: Logger | undefined;
 };
 export type RequestHandler = (req: http.IncomingMessage, res: http.ServerResponse) => void;
 /**
@@ -88,12 +88,13 @@ export type LiveReloadPluginOptions = {
     /**
      * A console-like logger.
      */
-    logger?: Pick<import("pino").BaseLogger, "warn" | "error" | "debug" | "info"> | undefined;
+    logger?: Logger | undefined;
     /**
      * A relative path to the root of the project. This is used to resolve build errors, line numbers, and file paths.
      */
     relativeRoot?: string | undefined;
 };
+import type { Logger } from "@goauthentik/logger-js";
 import * as http from "node:http";
 import type { Server as HTTPSServer } from "node:https";
 import type { ListenOptions } from "node:net";

package/out/plugin/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../plugin/index.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;GAUG;AACH,oDARW,KAAK,GACH,MAAM,CAclB;AAyBD;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,uEANW,eAAe,GACb,cAAc,CA6D1B;AAED;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,2CAHW,uBAAuB,GACrB,OAAO,SAAS,EAAE,MAAM,CA+FpC;;;;;;cApMa,MAAM;gBACN,WAAW;;;6BAQZ,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;sBAhEpD,WAAW;2CAJS,YAAY;mCAFpB,UAAU"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../plugin/index.js"],"names":[],"mappings":"AAgBA;;;;;;;;;;GAUG;AACH,oDARW,KAAK,GACH,MAAM,CAclB;AAyBD;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,uEANW,eAAe,GACb,cAAc,CA6D1B;AAED;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,2CAHW,uBAAuB,GACrB,OAAO,SAAS,EAAE,MAAM,CA+FpC;;;;;;cApMa,MAAM;gBACN,WAAW;;;6BAQZ,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,KAAK,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;4BAnE/C,wBAAwB;sBAG7B,WAAW;2CAJS,YAAY;mCAFpB,UAAU"}

package/out/shared/index.d.ts

@@ -1,18 +1,14 @@
 /**
  * @file Shared utilities for the live reload plugin.
  *
- * @import { BaseLogger } from "pino";
- */
-/**
- * @typedef {Pick<BaseLogger, "info" | "warn" | "error" | "debug">} Logger
+ * @import { BaseLogger } from "@goauthentik/logger-js";
  */
 /**
  * Creates a logger with the given prefix.
  *
  * @param {string} [prefix]
- * @returns {Logger}
+ * @returns {BaseLogger}
  */
-export function createLogger(prefix?: string): Logger;
-export type Logger = Pick<BaseLogger, "info" | "warn" | "error" | "debug">;
-import type { BaseLogger } from "pino";
+export function createLogger(prefix?: string): BaseLogger;
+import type { BaseLogger } from "@goauthentik/logger-js";
 //# sourceMappingURL=index.d.ts.map

package/out/shared/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../shared/index.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AAEH;;;;;GAKG;AACH,sCAHW,MAAM,GACJ,MAAM,CASlB;qBAhBY,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;gCAJnC,MAAM"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../shared/index.js"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,sCAHW,MAAM,GACJ,UAAU,CAUtB;gCAjB8B,wBAAwB"}