novaapp-sdk 1.4.0 → 1.4.2

package/dist/devtools/index.d.mts

@@ -0,0 +1,94 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * @module devtools/HotLoader
+ *
+ * File-watcher utility for development mode (`nova dev`).
+ *
+ * Uses Node's built-in `fs.watch` — **no external dependencies**.
+ *
+ * @example
+ * ```ts
+ * import { HotLoader } from 'novaapp-sdk/devtools'
+ *
+ * const loader = new HotLoader('./src', { debounce: 300 })
+ *
+ * loader.on('reload', path => console.log(`Reloading because ${path} changed`))
+ * loader.start()
+ *
+ * // When a module changes, re-run your setup:
+ * loader.restart(async () => {
+ *   await client.disconnect()
+ *   // ...rebuild / re-require...
+ *   await client.connect()
+ * })
+ * ```
+ */
+
+interface HotLoaderOptions {
+    /** Debounce window in milliseconds before a `reload` event fires. Default: 250ms. */
+    debounce?: number;
+    /** Extensions to watch. Default: `['.ts', '.js', '.mjs', '.cjs', '.json']`. */
+    extensions?: string[];
+    /** Whether to watch subdirectories recursively. Default: `true`. */
+    recursive?: boolean;
+}
+interface HotLoaderEvents {
+    /** Fires whenever a watched file is modified (before debounce). */
+    change: [filePath: string];
+    /** Fires after the debounce window with the last changed file path. */
+    reload: [filePath: string];
+    /** Fires when an error occurs in the watcher. */
+    error: [err: Error];
+}
+/**
+ * Watches a directory for source file changes and emits typed events.  The
+ * `restart` helper runs a callback after every debounced `reload`.
+ */
+declare class HotLoader extends EventEmitter {
+    private readonly watchPath;
+    private readonly debounceMs;
+    private readonly extensions;
+    private readonly recursive;
+    private watcher;
+    private debounceTimer;
+    private lastChanged;
+    private restartFn;
+    private restarting;
+    constructor(watchPath: string, options?: HotLoaderOptions);
+    /**
+     * Start watching for file changes.
+     *
+     * Calling `start()` again after `stop()` is safe — it creates a new watcher.
+     */
+    start(): void;
+    /**
+     * Stop watching.  Safe to call even if not started.
+     */
+    stop(): void;
+    /**
+     * Register a callback that runs after every debounced `reload` event.
+     *
+     * If the callback is already running when another reload fires it will be
+     * queued once and run again after the current run finishes.
+     *
+     * @example
+     * ```ts
+     * loader.restart(async () => {
+     *   await client.disconnect()
+     *   await build()
+     *   await client.connect()
+     * })
+     * ```
+     */
+    restart(fn: () => void | Promise<void>): void;
+    private triggerRestart;
+    on<K extends keyof HotLoaderEvents>(event: K, listener: (...args: HotLoaderEvents[K]) => void): this;
+    once<K extends keyof HotLoaderEvents>(event: K, listener: (...args: HotLoaderEvents[K]) => void): this;
+    off<K extends keyof HotLoaderEvents>(event: K, listener: (...args: HotLoaderEvents[K]) => void): this;
+    emit<K extends keyof HotLoaderEvents>(event: K, ...args: HotLoaderEvents[K]): boolean;
+    /** Whether the loader is currently active. */
+    get watching(): boolean;
+}
+
+export { HotLoader, type HotLoaderEvents, type HotLoaderOptions };

package/dist/devtools/index.d.ts

@@ -0,0 +1,94 @@
+import { EventEmitter } from 'node:events';
+
+/**
+ * @module devtools/HotLoader
+ *
+ * File-watcher utility for development mode (`nova dev`).
+ *
+ * Uses Node's built-in `fs.watch` — **no external dependencies**.
+ *
+ * @example
+ * ```ts
+ * import { HotLoader } from 'novaapp-sdk/devtools'
+ *
+ * const loader = new HotLoader('./src', { debounce: 300 })
+ *
+ * loader.on('reload', path => console.log(`Reloading because ${path} changed`))
+ * loader.start()
+ *
+ * // When a module changes, re-run your setup:
+ * loader.restart(async () => {
+ *   await client.disconnect()
+ *   // ...rebuild / re-require...
+ *   await client.connect()
+ * })
+ * ```
+ */
+
+interface HotLoaderOptions {
+    /** Debounce window in milliseconds before a `reload` event fires. Default: 250ms. */
+    debounce?: number;
+    /** Extensions to watch. Default: `['.ts', '.js', '.mjs', '.cjs', '.json']`. */
+    extensions?: string[];
+    /** Whether to watch subdirectories recursively. Default: `true`. */
+    recursive?: boolean;
+}
+interface HotLoaderEvents {
+    /** Fires whenever a watched file is modified (before debounce). */
+    change: [filePath: string];
+    /** Fires after the debounce window with the last changed file path. */
+    reload: [filePath: string];
+    /** Fires when an error occurs in the watcher. */
+    error: [err: Error];
+}
+/**
+ * Watches a directory for source file changes and emits typed events.  The
+ * `restart` helper runs a callback after every debounced `reload`.
+ */
+declare class HotLoader extends EventEmitter {
+    private readonly watchPath;
+    private readonly debounceMs;
+    private readonly extensions;
+    private readonly recursive;
+    private watcher;
+    private debounceTimer;
+    private lastChanged;
+    private restartFn;
+    private restarting;
+    constructor(watchPath: string, options?: HotLoaderOptions);
+    /**
+     * Start watching for file changes.
+     *
+     * Calling `start()` again after `stop()` is safe — it creates a new watcher.
+     */
+    start(): void;
+    /**
+     * Stop watching.  Safe to call even if not started.
+     */
+    stop(): void;
+    /**
+     * Register a callback that runs after every debounced `reload` event.
+     *
+     * If the callback is already running when another reload fires it will be
+     * queued once and run again after the current run finishes.
+     *
+     * @example
+     * ```ts
+     * loader.restart(async () => {
+     *   await client.disconnect()
+     *   await build()
+     *   await client.connect()
+     * })
+     * ```
+     */
+    restart(fn: () => void | Promise<void>): void;
+    private triggerRestart;
+    on<K extends keyof HotLoaderEvents>(event: K, listener: (...args: HotLoaderEvents[K]) => void): this;
+    once<K extends keyof HotLoaderEvents>(event: K, listener: (...args: HotLoaderEvents[K]) => void): this;
+    off<K extends keyof HotLoaderEvents>(event: K, listener: (...args: HotLoaderEvents[K]) => void): this;
+    emit<K extends keyof HotLoaderEvents>(event: K, ...args: HotLoaderEvents[K]): boolean;
+    /** Whether the loader is currently active. */
+    get watching(): boolean;
+}
+
+export { HotLoader, type HotLoaderEvents, type HotLoaderOptions };

package/dist/devtools/index.js

@@ -0,0 +1,160 @@
+"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);
+
+// src/devtools/index.ts
+var devtools_exports = {};
+__export(devtools_exports, {
+  HotLoader: () => HotLoader
+});
+module.exports = __toCommonJS(devtools_exports);
+
+// src/devtools/HotLoader.ts
+var import_node_events = require("events");
+var fs = __toESM(require("fs"));
+var path = __toESM(require("path"));
+var HotLoader = class extends import_node_events.EventEmitter {
+  constructor(watchPath, options = {}) {
+    super();
+    this.watcher = null;
+    this.debounceTimer = null;
+    this.lastChanged = null;
+    this.restartFn = null;
+    this.restarting = false;
+    this.watchPath = path.resolve(watchPath);
+    this.debounceMs = options.debounce ?? 250;
+    this.recursive = options.recursive ?? true;
+    this.extensions = new Set(
+      options.extensions ?? [".ts", ".js", ".mjs", ".cjs", ".json"]
+    );
+  }
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+  /**
+   * Start watching for file changes.
+   *
+   * Calling `start()` again after `stop()` is safe — it creates a new watcher.
+   */
+  start() {
+    if (this.watcher) return;
+    this.watcher = fs.watch(
+      this.watchPath,
+      { recursive: this.recursive, encoding: "utf8" },
+      (event, filename) => {
+        if (!filename) return;
+        const ext = path.extname(filename);
+        if (!this.extensions.has(ext)) return;
+        const full = path.join(this.watchPath, filename);
+        this.emit("change", full);
+        this.lastChanged = full;
+        if (this.debounceTimer) clearTimeout(this.debounceTimer);
+        this.debounceTimer = setTimeout(() => {
+          this.debounceTimer = null;
+          if (this.lastChanged) {
+            const f = this.lastChanged;
+            this.lastChanged = null;
+            this.emit("reload", f);
+            this.triggerRestart();
+          }
+        }, this.debounceMs);
+      }
+    );
+    this.watcher.on("error", (err) => {
+      this.emit("error", err);
+    });
+  }
+  /**
+   * Stop watching.  Safe to call even if not started.
+   */
+  stop() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+    }
+  }
+  // ── Restart helper ─────────────────────────────────────────────────────────
+  /**
+   * Register a callback that runs after every debounced `reload` event.
+   *
+   * If the callback is already running when another reload fires it will be
+   * queued once and run again after the current run finishes.
+   *
+   * @example
+   * ```ts
+   * loader.restart(async () => {
+   *   await client.disconnect()
+   *   await build()
+   *   await client.connect()
+   * })
+   * ```
+   */
+  restart(fn) {
+    this.restartFn = fn;
+  }
+  triggerRestart() {
+    if (!this.restartFn || this.restarting) return;
+    const fn = this.restartFn;
+    this.restarting = true;
+    const result = fn();
+    const finish = () => {
+      this.restarting = false;
+    };
+    if (result instanceof Promise) {
+      result.then(finish, (err) => {
+        finish();
+        this.emit("error", err instanceof Error ? err : new Error(String(err)));
+      });
+    } else {
+      finish();
+    }
+  }
+  // ── Typed event overloads ──────────────────────────────────────────────────
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+  once(event, listener) {
+    return super.once(event, listener);
+  }
+  off(event, listener) {
+    return super.off(event, listener);
+  }
+  emit(event, ...args) {
+    return super.emit(event, ...args);
+  }
+  /** Whether the loader is currently active. */
+  get watching() {
+    return this.watcher !== null;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HotLoader
+});

package/dist/devtools/index.mjs

@@ -0,0 +1,7 @@
+import {
+  HotLoader
+} from "../chunk-LMORGVJR.mjs";
+import "../chunk-53M2BTB5.mjs";
+export {
+  HotLoader
+};