@ecopages/core 0.2.0-alpha.1

package/src/utils/server-utils.module.ts

@@ -0,0 +1,67 @@
+const ContentTypeMap = new Map<string, string>([
+	['jpg', 'image/jpeg'],
+	['jpeg', 'image/jpeg'],
+	['png', 'image/png'],
+	['gif', 'image/gif'],
+	['bmp', 'image/bmp'],
+	['svg', 'image/svg+xml'],
+	['tiff', 'image/tiff'],
+	['webp', 'image/webp'],
+	['avif', 'image/avif'],
+	['ico', 'image/x-icon'],
+	['mp3', 'audio/mpeg'],
+	['ogg', 'audio/ogg'],
+	['wav', 'audio/wav'],
+	['mp4', 'video/mp4'],
+	['webm', 'video/webm'],
+	['ogv', 'video/ogg'],
+	['mov', 'video/quicktime'],
+	['txt', 'text/plain'],
+	['html', 'text/html'],
+	['css', 'text/css'],
+	['js', 'text/javascript'],
+	['mjs', 'text/javascript'],
+	['json', 'application/json'],
+	['map', 'application/json'],
+	['xml', 'application/xml'],
+	['webmanifest', 'application/manifest+json'],
+	['wasm', 'application/wasm'],
+	['csv', 'text/csv'],
+	['ttf', 'font/ttf'],
+	['woff', 'font/woff'],
+	['woff2', 'font/woff2'],
+	['otf', 'font/otf'],
+	['eot', 'application/vnd.ms-fontobject'],
+	['gz', 'application/x-gzip'],
+	['zip', 'application/zip'],
+	['pdf', 'application/pdf'],
+	['doc', 'application/msword'],
+]);
+
+/**
+ * Get the content type of a file based on its extension.
+ * @param file - The file name.
+ * @returns The content type.
+ */
+export const getContentType = (file: string): string => {
+	const extension = file.split('.').pop() || 'txt';
+	return ContentTypeMap.get(extension) || 'text/plain';
+};
+
+/**
+ * Check if a file path has a known static file extension.
+ * @param file - The file name or path.
+ * @returns true if the extension is recognized.
+ */
+export const hasKnownExtension = (file: string): boolean => {
+	const extension = file.split('.').pop();
+	return extension !== undefined && ContentTypeMap.has(extension);
+};
+
+/**
+ * A module for server utilities.
+ */
+export const ServerUtils = {
+	getContentType,
+	hasKnownExtension,
+};

package/src/watchers/project-watcher.d.ts

@@ -0,0 +1,120 @@
+import { type FSWatcher } from 'chokidar';
+import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../internal-types.js';
+/**
+ * Configuration options for the ProjectWatcher
+ * @interface ProjectWatcherConfig
+ * @property {EcoPagesAppConfig} config - The application configuration
+ * @property {() => void} refreshRouterRoutesCallback - Callback to refresh router routes
+ * @property {IHmrManager} hmrManager - The HMR manager instance
+ * @property {ClientBridge} bridge - The client bridge instance
+ */
+export interface ProjectWatcherConfig {
+    config: EcoPagesAppConfig;
+    refreshRouterRoutesCallback: () => void;
+    hmrManager: IHmrManager;
+    bridge: IClientBridge;
+}
+/**
+ * ProjectWatcher handles file system changes for hot module replacement (HMR).
+ * It uses chokidar to watch for file changes and triggers appropriate actions:
+ * - Uncaches modules when files change
+ * - Refreshes router routes for page files
+ * - Triggers HMR server reload
+ * - Handles processor-specific file changes
+ *
+ * The watcher uses chokidar's built-in debouncing through `awaitWriteFinish`
+ * to handle rapid file changes efficiently:
+ * - stabilityThreshold: 50ms - Time to wait for writes to stabilize
+ * - pollInterval: 50ms - Interval to poll for file changes
+ *
+ * @class ProjectWatcher
+ */
+export declare class ProjectWatcher {
+    /**
+     * Duplicate identical watcher events within this window are ignored.
+     *
+     * Some editors or save pipelines emit two near-identical filesystem change
+     * notifications for the same file. Ecopages should treat those as one logical
+     * update so HMR and route refresh work are not repeated unnecessarily.
+     */
+    private static readonly duplicateChangeWindowMs;
+    private appConfig;
+    private refreshRouterRoutesCallback;
+    private hmrManager;
+    private bridge;
+    private watcher;
+    private lastHandledChange;
+    constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: ProjectWatcherConfig);
+    /**
+     * Uncaches modules in the source directory to ensure fresh imports.
+     * This is necessary for hot module replacement to work correctly.
+     * @private
+     */
+    private uncacheModules;
+    /**
+     * Handles public directory file changes by copying only the changed file.
+     * @param filePath - Absolute path of the changed file
+     */
+    private handlePublicDirFileChange;
+    /**
+     * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
+     * Follows 4-rule priority:
+     * 0. Public directory match? → copy file and reload
+     * 1. additionalWatchPaths match? → reload
+     * 2. Processor extension match? → processor handles (skip HMR)
+     * 3. Otherwise → HMR strategies
+     *
+     * Duplicate identical watcher events for the same file are coalesced within a
+     * short window before any of the priority rules run.
+     * @param rawPath - Path of the changed file
+     */
+    private handleFileChange;
+    /**
+     * Checks if a file is in the public directory.
+     */
+    private isPublicDirFile;
+    /**
+     * Checks if file path matches any additionalWatchPaths patterns.
+     */
+    private matchesAdditionalWatchPaths;
+    /**
+     * Checks if a file is handled by a processor.
+     * Processors that declare extensions own those file types.
+     */
+    private isHandledByProcessor;
+    /**
+     * Triggers router refresh for page directory changes.
+     * This ensures the router is updated when pages are added or removed.
+     *
+     * @param {string} path - Path of the changed directory
+     */
+    triggerRouterRefresh(path: string): void;
+    /**
+     * Handles and logs errors that occur during file watching.
+     *
+     * @param {unknown} error - The error to handle
+     */
+    handleError(error: unknown): void;
+    /**
+     * Processes file changes for specific file extensions.
+     * Used by processors to handle their specific file types.
+     *
+     * @private
+     * @param {string} path - Path of the changed file
+     * @param {string[]} extensions - File extensions to process
+     * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
+     */
+    private shouldProcess;
+    /**
+     * Creates and configures the file system watcher.
+     * This sets up:
+     * 1. Processor-specific file watching
+     * 2. Page file watching
+     * 3. Directory watching
+     * 4. Error handling
+     *
+     * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
+     * rapid file changes efficiently.
+     */
+    createWatcherSubscription(): Promise<FSWatcher>;
+}

package/src/watchers/project-watcher.js

@@ -0,0 +1,238 @@
+import path from "node:path";
+import chokidar, {} from "chokidar";
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../global/app-logger.js";
+class ProjectWatcher {
+  /**
+   * Duplicate identical watcher events within this window are ignored.
+   *
+   * Some editors or save pipelines emit two near-identical filesystem change
+   * notifications for the same file. Ecopages should treat those as one logical
+   * update so HMR and route refresh work are not repeated unnecessarily.
+   */
+  static duplicateChangeWindowMs = 150;
+  appConfig;
+  refreshRouterRoutesCallback;
+  hmrManager;
+  bridge;
+  watcher = null;
+  lastHandledChange = /* @__PURE__ */ new Map();
+  constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }) {
+    this.appConfig = config;
+    this.refreshRouterRoutesCallback = refreshRouterRoutesCallback;
+    this.hmrManager = hmrManager;
+    this.bridge = bridge;
+    this.triggerRouterRefresh = this.triggerRouterRefresh.bind(this);
+    this.handleError = this.handleError.bind(this);
+    this.handleFileChange = this.handleFileChange.bind(this);
+  }
+  /**
+   * Uncaches modules in the source directory to ensure fresh imports.
+   * This is necessary for hot module replacement to work correctly.
+   * @private
+   */
+  uncacheModules() {
+    if (typeof require === "undefined") return;
+    const { srcDir, rootDir } = this.appConfig;
+    const regex = new RegExp(`${rootDir}/${srcDir}/.*`);
+    for (const key in require.cache) {
+      if (regex.test(key)) {
+        delete require.cache[key];
+      }
+    }
+  }
+  /**
+   * Handles public directory file changes by copying only the changed file.
+   * @param filePath - Absolute path of the changed file
+   */
+  async handlePublicDirFileChange(filePath) {
+    try {
+      const relativePath = path.relative(this.appConfig.absolutePaths.publicDir, filePath);
+      const destPath = path.join(this.appConfig.absolutePaths.distDir, relativePath);
+      if (fileSystem.exists(filePath)) {
+        const destDir = path.dirname(destPath);
+        fileSystem.ensureDir(destDir);
+        await fileSystem.copyFileAsync(filePath, destPath);
+      }
+      this.bridge.reload();
+    } catch (error) {
+      appLogger.error(`Failed to copy public file: ${error instanceof Error ? error.message : String(error)}`);
+      this.bridge.reload();
+    }
+  }
+  /**
+   * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
+   * Follows 4-rule priority:
+   * 0. Public directory match? → copy file and reload
+   * 1. additionalWatchPaths match? → reload
+   * 2. Processor extension match? → processor handles (skip HMR)
+   * 3. Otherwise → HMR strategies
+   *
+   * Duplicate identical watcher events for the same file are coalesced within a
+   * short window before any of the priority rules run.
+   * @param rawPath - Path of the changed file
+   */
+  async handleFileChange(rawPath) {
+    const filePath = path.resolve(rawPath);
+    const now = Date.now();
+    const lastHandledAt = this.lastHandledChange.get(filePath);
+    if (lastHandledAt !== void 0 && now - lastHandledAt < ProjectWatcher.duplicateChangeWindowMs) {
+      return;
+    }
+    this.lastHandledChange.set(filePath, now);
+    try {
+      if (this.isPublicDirFile(filePath)) {
+        await this.handlePublicDirFileChange(filePath);
+        return;
+      }
+      this.uncacheModules();
+      const isPageFile = filePath.startsWith(this.appConfig.absolutePaths.pagesDir);
+      if (isPageFile) {
+        this.refreshRouterRoutesCallback();
+      }
+      if (this.matchesAdditionalWatchPaths(filePath)) {
+        this.bridge.reload();
+        return;
+      }
+      if (this.isHandledByProcessor(filePath)) {
+        return;
+      }
+      await this.hmrManager.handleFileChange(filePath);
+    } catch (error) {
+      if (error instanceof Error) {
+        this.bridge.error(error.message);
+        this.handleError(error);
+      }
+    }
+  }
+  /**
+   * Checks if a file is in the public directory.
+   */
+  isPublicDirFile(filePath) {
+    return filePath.startsWith(this.appConfig.absolutePaths.publicDir);
+  }
+  /**
+   * Checks if file path matches any additionalWatchPaths patterns.
+   */
+  matchesAdditionalWatchPaths(filePath) {
+    const patterns = this.appConfig.additionalWatchPaths;
+    if (!patterns.length) return false;
+    for (const pattern of patterns) {
+      if (pattern.includes("*")) {
+        const ext = pattern.replace(/\*\*?\/\*/, "");
+        if (filePath.endsWith(ext)) return true;
+      } else {
+        if (filePath.endsWith(pattern) || filePath === path.resolve(pattern)) return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Checks if a file is handled by a processor.
+   * Processors that declare extensions own those file types.
+   */
+  isHandledByProcessor(filePath) {
+    for (const processor of this.appConfig.processors.values()) {
+      const watchConfig = processor.getWatchConfig();
+      if (!watchConfig) continue;
+      const { extensions = [] } = watchConfig;
+      if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Triggers router refresh for page directory changes.
+   * This ensures the router is updated when pages are added or removed.
+   *
+   * @param {string} path - Path of the changed directory
+   */
+  triggerRouterRefresh(path2) {
+    const isPageDir = path2.startsWith(this.appConfig.absolutePaths.pagesDir);
+    if (isPageDir) {
+      this.refreshRouterRoutesCallback();
+    }
+  }
+  /**
+   * Handles and logs errors that occur during file watching.
+   *
+   * @param {unknown} error - The error to handle
+   */
+  handleError(error) {
+    if (error instanceof Error) {
+      this.hmrManager.broadcast({ type: "error", message: error.message });
+    }
+    appLogger.error(`Watcher error: ${error}`);
+  }
+  /**
+   * Processes file changes for specific file extensions.
+   * Used by processors to handle their specific file types.
+   *
+   * @private
+   * @param {string} path - Path of the changed file
+   * @param {string[]} extensions - File extensions to process
+   * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
+   */
+  shouldProcess(path2, extensions, handler) {
+    if (!extensions.length || extensions.some((ext) => path2.endsWith(ext))) {
+      handler({ path: path2, bridge: this.bridge });
+    }
+  }
+  /**
+   * Creates and configures the file system watcher.
+   * This sets up:
+   * 1. Processor-specific file watching
+   * 2. Page file watching
+   * 3. Directory watching
+   * 4. Error handling
+   *
+   * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
+   * rapid file changes efficiently.
+   */
+  async createWatcherSubscription() {
+    if (!this.watcher) {
+      const processorPaths = [];
+      for (const processor of this.appConfig.processors.values()) {
+        const watchConfig = processor.getWatchConfig();
+        if (!watchConfig) continue;
+        processorPaths.push(...watchConfig.paths);
+      }
+      if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
+        processorPaths.push(this.appConfig.absolutePaths.pagesDir);
+      }
+      if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
+        processorPaths.push(this.appConfig.absolutePaths.publicDir);
+      }
+      if (this.appConfig.additionalWatchPaths.length) {
+        processorPaths.push(...this.appConfig.additionalWatchPaths);
+      }
+      this.watcher = chokidar.watch(processorPaths, {
+        ignoreInitial: true,
+        ignorePermissionErrors: true,
+        awaitWriteFinish: {
+          stabilityThreshold: 50,
+          pollInterval: 50
+        }
+      });
+    }
+    for (const processor of this.appConfig.processors.values()) {
+      const watchConfig = processor.getWatchConfig();
+      if (!watchConfig) continue;
+      const { extensions = [], onCreate, onChange, onDelete, onError } = watchConfig;
+      if (onCreate) this.watcher.on("add", (path2) => this.shouldProcess(path2, extensions, onCreate));
+      if (onChange) this.watcher.on("change", (path2) => this.shouldProcess(path2, extensions, onChange));
+      if (onDelete) this.watcher.on("unlink", (path2) => this.shouldProcess(path2, extensions, onDelete));
+      if (onError) this.watcher.on("error", onError);
+    }
+    this.watcher.add(this.appConfig.absolutePaths.srcDir);
+    this.watcher.on("change", (path2) => this.handleFileChange(path2)).on("add", (path2) => {
+      this.handleFileChange(path2);
+      this.triggerRouterRefresh(path2);
+    }).on("addDir", (path2) => this.triggerRouterRefresh(path2)).on("unlink", (path2) => this.triggerRouterRefresh(path2)).on("unlinkDir", (path2) => this.triggerRouterRefresh(path2)).on("error", (error) => this.handleError(error));
+    return this.watcher;
+  }
+}
+export {
+  ProjectWatcher
+};

package/src/watchers/project-watcher.test-helpers.d.ts

@@ -0,0 +1,4 @@
+import type { IHmrManager } from '../internal-types';
+import type { ClientBridge } from '../adapters/bun/client-bridge';
+export declare const createMockHmrManager: () => IHmrManager;
+export declare const createMockBridge: () => ClientBridge;

package/src/watchers/project-watcher.test-helpers.js

@@ -0,0 +1,51 @@
+import { vi } from "vitest";
+const createMockHmrManager = () => ({
+  handleFileChange: vi.fn(async () => {
+  }),
+  broadcast: vi.fn(() => {
+  }),
+  setEnabled: vi.fn(() => {
+  }),
+  setPlugins: vi.fn(() => {
+  }),
+  registerEntrypoint: vi.fn(async () => ""),
+  registerSpecifierMap: vi.fn(() => {
+  }),
+  registerStrategy: vi.fn(() => {
+  }),
+  isEnabled: vi.fn(() => true),
+  getOutputUrl: vi.fn(() => void 0),
+  getWatchedFiles: vi.fn(() => /* @__PURE__ */ new Map()),
+  getSpecifierMap: vi.fn(() => /* @__PURE__ */ new Map()),
+  getDistDir: vi.fn(() => ""),
+  getPlugins: vi.fn(() => []),
+  getDefaultContext: vi.fn(() => ({
+    getWatchedFiles: () => /* @__PURE__ */ new Map(),
+    getSpecifierMap: () => /* @__PURE__ */ new Map(),
+    getDistDir: () => "",
+    getPlugins: () => [],
+    getSrcDir: () => "",
+    getLayoutsDir: () => ""
+  }))
+});
+const createMockBridge = () => ({
+  reload: vi.fn(() => {
+  }),
+  error: vi.fn(() => {
+  }),
+  cssUpdate: vi.fn(() => {
+  }),
+  update: vi.fn(() => {
+  }),
+  subscribe: vi.fn(() => {
+  }),
+  unsubscribe: vi.fn(() => {
+  }),
+  broadcast: vi.fn(() => {
+  }),
+  subscriberCount: 0
+});
+export {
+  createMockBridge,
+  createMockHmrManager
+};

package/src/watchers/project-watcher.test-helpers.ts

@@ -0,0 +1,40 @@
+import { vi } from 'vitest';
+import type { IHmrManager } from '../internal-types';
+import type { ClientBridge } from '../adapters/bun/client-bridge';
+
+export const createMockHmrManager = (): IHmrManager =>
+	({
+		handleFileChange: vi.fn(async () => {}),
+		broadcast: vi.fn(() => {}),
+		setEnabled: vi.fn(() => {}),
+		setPlugins: vi.fn(() => {}),
+		registerEntrypoint: vi.fn(async () => ''),
+		registerSpecifierMap: vi.fn(() => {}),
+		registerStrategy: vi.fn(() => {}),
+		isEnabled: vi.fn(() => true),
+		getOutputUrl: vi.fn(() => undefined),
+		getWatchedFiles: vi.fn(() => new Map()),
+		getSpecifierMap: vi.fn(() => new Map()),
+		getDistDir: vi.fn(() => ''),
+		getPlugins: vi.fn(() => []),
+		getDefaultContext: vi.fn(() => ({
+			getWatchedFiles: () => new Map(),
+			getSpecifierMap: () => new Map(),
+			getDistDir: () => '',
+			getPlugins: () => [],
+			getSrcDir: () => '',
+			getLayoutsDir: () => '',
+		})),
+	}) as unknown as IHmrManager;
+
+export const createMockBridge = (): ClientBridge =>
+	({
+		reload: vi.fn(() => {}),
+		error: vi.fn(() => {}),
+		cssUpdate: vi.fn(() => {}),
+		update: vi.fn(() => {}),
+		subscribe: vi.fn(() => {}),
+		unsubscribe: vi.fn(() => {}),
+		broadcast: vi.fn(() => {}),
+		subscriberCount: 0,
+	}) as unknown as ClientBridge;