@ecopages/core 0.2.0-alpha.22 → 0.2.0-alpha.24

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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-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

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

package/src/utils/hash.js

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

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

@@ -1,7 +0,0 @@
-/**
- * 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

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

package/src/utils/html.js

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

package/src/utils/invariant.d.ts

@@ -1,5 +0,0 @@
-/**
- * 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

@@ -1,11 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,62 +0,0 @@
-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

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

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

@@ -1,14 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,31 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,56 +0,0 @@
-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

@@ -1,136 +0,0 @@
-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>;
-}