@ecopages/core 0.2.0-alpha.25 → 0.2.0-alpha.26

package/src/utils/deep-merge.d.ts

@@ -0,0 +1,14 @@
+/**
+ * This module contains a simple utility function to merge two objects deeply
+ * @module
+ */
+/**
+ * Deeply merges two objects or arrays
+ * @function deepMerge
+ * @template T - Type of target object
+ * @template U - Type of source object
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns A new object with merged properties
+ */
+export declare function deepMerge<T, U>(target: T, source: U): T & U;

package/src/utils/deep-merge.js

@@ -0,0 +1,32 @@
+function isObject(item) {
+  return item && typeof item === "object" && !Array.isArray(item);
+}
+function isArray(item) {
+  return Array.isArray(item);
+}
+function deepMerge(target, source) {
+  if (isArray(target) && isArray(source)) {
+    return [...target, ...source];
+  }
+  if (!isObject(target) || !isObject(source)) {
+    return source;
+  }
+  const output = Object.assign({}, target);
+  for (const key in source) {
+    if (isObject(source[key])) {
+      if (!target[key]) {
+        Object.assign(output, { [key]: source[key] });
+      } else {
+        output[key] = deepMerge(target[key], source[key]);
+      }
+    } else if (isArray(source[key])) {
+      output[key] = [...target[key] || [], ...source[key]];
+    } else if (source[key] !== void 0) {
+      Object.assign(output, { [key]: source[key] });
+    }
+  }
+  return output;
+}
+export {
+  deepMerge
+};

package/src/utils/hash.d.ts

@@ -0,0 +1 @@
+export declare const rapidhash: (content: string | Buffer<ArrayBufferLike>) => number | bigint;

package/src/utils/hash.js

@@ -0,0 +1,7 @@
+import { runtimeHash } from "./runtime.js";
+const rapidhash = (content) => {
+  return runtimeHash(content);
+};
+export {
+  rapidhash
+};

package/src/utils/html-escaping.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Escapes a string for safe use inside a double-quoted HTML attribute value.
+ *
+ * @param value Raw attribute value.
+ * @returns Escaped attribute-safe string.
+ */
+export declare function escapeHtmlAttribute(value: string): string;

package/src/utils/html-escaping.js

@@ -0,0 +1,6 @@
+function escapeHtmlAttribute(value) {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export {
+  escapeHtmlAttribute
+};

package/src/utils/html.js

@@ -0,0 +1,4 @@
+import { html } from "ghtml";
+export {
+  html
+};

package/src/utils/invariant.d.ts

@@ -0,0 +1,5 @@
+/**
+ * This module contains a simple utility invariant function that throws an error if the condition is not met
+ * @module
+ */
+export declare function invariant(condition: boolean, message?: string): asserts condition;

package/src/utils/invariant.js

@@ -0,0 +1,11 @@
+const prefix = "[ecopages]";
+function invariant(condition, message) {
+  if (condition) {
+    return;
+  }
+  const value = message ? `${prefix} ${message}` : `${prefix} An error occurred`;
+  throw new Error(value);
+}
+export {
+  invariant
+};

package/src/utils/locals-utils.d.ts

@@ -0,0 +1,15 @@
+import type { ApiHandlerContext } from '../types/public-types.js';
+/**
+ * Creates a require function for validating and retrieving request locals.
+ * Supports both single key access and multiple keys with type safety.
+ *
+ * @param getLocals - Function that returns the current locals object
+ * @returns A require function that throws the onMissing response if keys are not found
+ *
+ * @example
+ * ```ts
+ * const require = createRequire(() => context.locals);
+ * const userId = require('userId', () => new Response('Unauthorized', { status: 401 }));
+ * ```
+ */
+export declare function createRequire(getLocals: () => Record<string, unknown>): ApiHandlerContext['require'];

package/src/utils/locals-utils.js

@@ -0,0 +1,24 @@
+function createRequire(getLocals) {
+  return (keyOrKeys, onMissing) => {
+    const locals = getLocals();
+    if (Array.isArray(keyOrKeys)) {
+      const result = {};
+      for (const key of keyOrKeys) {
+        const value2 = locals[key];
+        if (value2 === void 0 || value2 === null) {
+          throw onMissing();
+        }
+        result[key] = value2;
+      }
+      return result;
+    }
+    const value = locals[keyOrKeys];
+    if (value === void 0 || value === null) {
+      throw onMissing();
+    }
+    return value;
+  };
+}
+export {
+  createRequire
+};

package/src/utils/parse-cli-args.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Parsed command line arguments for the Ecopages server.
+ * @property preview - Whether to run in preview mode
+ * @property build - Whether to run a static build
+ * @property start - Whether to start the server
+ * @property dev - Whether to run in development mode
+ * @property port - Optional port number
+ * @property hostname - Optional hostname
+ * @property reactFastRefresh - Whether React Fast Refresh is enabled
+ */
+export type ReturnParseCliArgs = {
+    preview: boolean;
+    build: boolean;
+    start: boolean;
+    dev: boolean;
+    port?: number;
+    hostname?: string;
+    reactFastRefresh?: boolean;
+};
+export type ParseCliArgsOptions = {
+    embeddedRuntime?: boolean;
+};
+/**
+ * Parses command line arguments for the server.
+ * It returns {@link ReturnParseCliArgs}
+ */
+export declare function parseCliArgs(options?: ParseCliArgsOptions): ReturnParseCliArgs;

package/src/utils/parse-cli-args.js

@@ -0,0 +1,62 @@
+import { parseArgs } from "node:util";
+import { getRuntimeArgv } from "./runtime.js";
+function getEmbeddedRuntimeCommandOptions() {
+  const isDevelopment = process.env.NODE_ENV === "development";
+  return {
+    preview: false,
+    build: false,
+    start: !isDevelopment,
+    dev: isDevelopment,
+    port: void 0,
+    hostname: void 0,
+    reactFastRefresh: void 0
+  };
+}
+const ECOPAGES_BIN_FILES = ["ecopages.ts", "ecopages.js", "cli.js"];
+const ECOPAGES_AVAILABLE_COMMANDS = ["dev", "build", "start", "preview"];
+function parseCliArgs(options = {}) {
+  if (options.embeddedRuntime || process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME === "true") {
+    return getEmbeddedRuntimeCommandOptions();
+  }
+  const runtimeArgv = getRuntimeArgv();
+  const { values } = parseArgs({
+    args: runtimeArgv,
+    options: {
+      dev: { type: "boolean" },
+      preview: { type: "boolean" },
+      build: { type: "boolean" },
+      port: { type: "string" },
+      hostname: { type: "string" },
+      "react-fast-refresh": { type: "boolean" }
+    },
+    allowPositionals: true
+  });
+  let command = "";
+  const ecopagesIndex = runtimeArgv.findIndex((arg) => ECOPAGES_BIN_FILES.some((filename) => arg.endsWith(filename)));
+  const isAvailableCommand = ecopagesIndex !== -1;
+  if (isAvailableCommand) {
+    command = ecopagesIndex < runtimeArgv.length - 1 && ECOPAGES_AVAILABLE_COMMANDS.some((cmd) => {
+      return runtimeArgv[ecopagesIndex + 1] === cmd;
+    }) ? runtimeArgv[ecopagesIndex + 1] : "start";
+  }
+  const isStartCommand = command === "start" || !values.dev && !values.build && !values.preview;
+  const isDevCommand = command === "dev" || !!values.dev;
+  const isBuildCommand = command === "build" || !!values.build;
+  const isPreviewCommand = command === "preview" || !!values.preview;
+  const parsedCommandOptions = {
+    preview: isPreviewCommand,
+    build: isBuildCommand,
+    start: isStartCommand,
+    dev: isDevCommand,
+    port: values.port ? Number(values.port) : void 0,
+    hostname: values.hostname,
+    reactFastRefresh: values["react-fast-refresh"]
+  };
+  if (!process.env.NODE_ENV) {
+    process.env.NODE_ENV = isDevCommand ? "development" : "production";
+  }
+  return parsedCommandOptions;
+}
+export {
+  parseCliArgs
+};

package/src/utils/path-utils.module.d.ts

@@ -0,0 +1,5 @@
+declare function getEcoTemplateExtension(filePath: string): string;
+export declare const PathUtils: {
+    getEcoTemplateExtension: typeof getEcoTemplateExtension;
+};
+export {};

package/src/utils/path-utils.module.js

@@ -0,0 +1,14 @@
+import path from "node:path";
+function getEcoTemplateExtension(filePath) {
+  const { name, ext } = path.parse(filePath);
+  const nameParts = name.split(".");
+  const descriptor = nameParts.length > 1 ? nameParts.pop() : void 0;
+  const templateExtension = descriptor ? `.${descriptor}${ext}` : ext;
+  return templateExtension;
+}
+const PathUtils = {
+  getEcoTemplateExtension
+};
+export {
+  PathUtils
+};

package/src/utils/resolve-work-dir.d.ts

@@ -0,0 +1,11 @@
+type InternalPathConfig = {
+    rootDir?: string;
+    workDir?: string;
+    absolutePaths?: {
+        workDir?: string;
+        distDir?: string;
+    };
+};
+export declare function resolveInternalWorkDir(appConfig: InternalPathConfig): string;
+export declare function resolveInternalExecutionDir(appConfig: InternalPathConfig): string;
+export {};

package/src/utils/resolve-work-dir.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
+function isInsideNodeModules(directory) {
+  return path.normalize(directory).split(path.sep).includes("node_modules");
+}
+function resolveInternalWorkDir(appConfig) {
+  if (appConfig.absolutePaths?.workDir) {
+    return appConfig.absolutePaths.workDir;
+  }
+  if (appConfig.rootDir) {
+    return path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+  }
+  if (appConfig.workDir) {
+    return appConfig.workDir;
+  }
+  return DEFAULT_ECOPAGES_WORK_DIR;
+}
+function resolveInternalExecutionDir(appConfig) {
+  const workDir = resolveInternalWorkDir(appConfig);
+  if (!isInsideNodeModules(workDir)) {
+    return workDir;
+  }
+  if (appConfig.rootDir) {
+    return path.join(appConfig.rootDir, DEFAULT_ECOPAGES_WORK_DIR);
+  }
+  return DEFAULT_ECOPAGES_WORK_DIR;
+}
+export {
+  resolveInternalExecutionDir,
+  resolveInternalWorkDir
+};

package/src/utils/runtime.d.ts

@@ -0,0 +1,11 @@
+export declare const RUNTIME_ERRORS: {
+    readonly BUN_RUNTIME_REQUIRED: "Bun runtime is required";
+};
+type RuntimeBun = typeof Bun;
+export declare function getBunRuntime(): RuntimeBun | undefined;
+export declare function getRequiredBunRuntime(): RuntimeBun;
+export declare function getRuntimeArgv(): string[];
+export declare function isDevelopmentRuntime(): boolean;
+export declare function isProductionRuntime(): boolean;
+export declare function runtimeHash(content: string | Buffer<ArrayBufferLike>): number | bigint;
+export {};

package/src/utils/runtime.js

@@ -0,0 +1,40 @@
+import { createHash } from "node:crypto";
+const RUNTIME_ERRORS = {
+  BUN_RUNTIME_REQUIRED: "Bun runtime is required"
+};
+function getBunRuntime() {
+  return globalThis.Bun;
+}
+function getRequiredBunRuntime() {
+  const bun = getBunRuntime();
+  if (!bun) {
+    throw new Error(RUNTIME_ERRORS.BUN_RUNTIME_REQUIRED);
+  }
+  return bun;
+}
+function getRuntimeArgv() {
+  return process.argv;
+}
+function isDevelopmentRuntime() {
+  return process.env.NODE_ENV === "development";
+}
+function isProductionRuntime() {
+  return process.env.NODE_ENV === "production";
+}
+function runtimeHash(content) {
+  const bun = getBunRuntime();
+  if (bun) {
+    return bun.hash(content);
+  }
+  const hex = createHash("sha256").update(content).digest("hex").slice(0, 16);
+  return BigInt(`0x${hex}`);
+}
+export {
+  RUNTIME_ERRORS,
+  getBunRuntime,
+  getRequiredBunRuntime,
+  getRuntimeArgv,
+  isDevelopmentRuntime,
+  isProductionRuntime,
+  runtimeHash
+};

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

@@ -0,0 +1,19 @@
+/**
+ * Get the content type of a file based on its extension.
+ * @param file - The file name.
+ * @returns The content type.
+ */
+export declare const getContentType: (file: string) => string;
+/**
+ * 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 declare const hasKnownExtension: (file: string) => boolean;
+/**
+ * A module for server utilities.
+ */
+export declare const ServerUtils: {
+    getContentType: (file: string) => string;
+    hasKnownExtension: (file: string) => boolean;
+};

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

@@ -0,0 +1,56 @@
+const ContentTypeMap = /* @__PURE__ */ new Map([
+  ["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"]
+]);
+const getContentType = (file) => {
+  const extension = file.split(".").pop() || "txt";
+  return ContentTypeMap.get(extension) || "text/plain";
+};
+const hasKnownExtension = (file) => {
+  const extension = file.split(".").pop();
+  return extension !== void 0 && ContentTypeMap.has(extension);
+};
+const ServerUtils = {
+  getContentType,
+  hasKnownExtension
+};
+export {
+  ServerUtils,
+  getContentType,
+  hasKnownExtension
+};

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

@@ -0,0 +1,136 @@
+import { type FSWatcher } from 'chokidar';
+import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../types/internal-types.js';
+/**
+ * Configuration options for the ProjectWatcher
+ * @interface ProjectWatcherConfig
+ * @property {EcoPagesAppConfig} config - The application configuration
+ * @property {() => Promise<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: () => Promise<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 readonly invalidationService;
+    private watcher;
+    private lastHandledChange;
+    private changeQueue;
+    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;
+    private isRouteSourceFile;
+    private isIncludeSourceFile;
+    /**
+     * Handles public directory file changes by copying only the changed file.
+     * @param filePath - Absolute path of the changed file
+     */
+    private handlePublicDirFileChange;
+    /**
+     * Serializes file change handling so that concurrent chokidar events are
+     * processed one at a time, preventing overlapping builds and race conditions.
+     */
+    private enqueueChange;
+    /**
+     * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
+     * Follows 5-rule priority:
+     * 0. Public directory match? -> copy file and reload
+     * 1. additionalWatchPaths match? -> reload
+     * 2. Include template source? -> reload after processor notifications
+     * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
+     * 4. Otherwise -> HMR strategies
+     *
+     * Processors that watch a file extension as a dependency (e.g. PostCSS watching
+     * .tsx for Tailwind class scanning) are always notified first, but do not
+     * prevent the file from flowing through the normal HMR strategy pipeline.
+     *
+     * 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
+     * @param event - The type of file system event
+     */
+    private handleFileChange;
+    /**
+     * Notifies all processors whose watch config matches the given file extension.
+     * This is called before checking processor ownership so that dependency-only
+     * processors (e.g. PostCSS watching .tsx for class scanning) receive their
+     * notifications regardless of whether they own the file.
+     */
+    private notifyProcessors;
+    private getProcessorHandler;
+    /**
+     * 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 asset capabilities own those file types.
+     * Processors without capabilities fall back to checking watch extensions.
+     */
+    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(changedPath: string): Promise<void>;
+    /**
+     * Handles and logs errors that occur during file watching.
+     *
+     * @param {unknown} error - The error to handle
+     */
+    handleError(error: unknown): void;
+    /**
+     * Creates and configures the file system watcher.
+     * This sets up:
+     * 1. Page file watching
+     * 2. Directory watching
+     * 3. Error handling
+     *
+     * Processor notifications are dispatched inside handleFileChange, ensuring
+     * a single unified event pipeline with no parallel chokidar bindings.
+     *
+     * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
+     * rapid file changes efficiently.
+     */
+    createWatcherSubscription(): Promise<FSWatcher>;
+}