@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/hmr/strategies/js-hmr-strategy.js

@@ -0,0 +1,178 @@
+import path from "node:path";
+import { fileSystem } from "@ecopages/file-system";
+import { HmrStrategy, HmrStrategyType } from "../hmr-strategy";
+import { appLogger } from "../../global/app-logger";
+class JsHmrStrategy extends HmrStrategy {
+  type = HmrStrategyType.SCRIPT;
+  context;
+  constructor(context) {
+    super();
+    this.context = context;
+  }
+  /**
+   * Determines if the file is a JS/TS file that could affect registered entrypoints.
+   *
+   * Matches if:
+   * 1. There are registered entrypoints to rebuild
+   * 2. The changed file is a JS/TS file in the src directory
+   *
+   * @param filePath - Absolute path to the changed file
+   * @returns True if this file should trigger entrypoint rebuilds
+   */
+  matches(filePath) {
+    const watchedFiles = this.context.getWatchedFiles();
+    const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
+    const isInSrc = filePath.startsWith(this.context.getSrcDir());
+    const isRouteTemplate = filePath.startsWith(this.context.getPagesDir()) || filePath.startsWith(this.context.getLayoutsDir());
+    const isIntegrationTemplate = isRouteTemplate && this.context.getTemplateExtensions().some((extension) => filePath.endsWith(extension));
+    if (watchedFiles.size === 0) {
+      return false;
+    }
+    if (!isJsTs || !isInSrc) {
+      return false;
+    }
+    if (isIntegrationTemplate) {
+      return false;
+    }
+    if (watchedFiles.has(filePath)) {
+      return true;
+    }
+    const entrypointDependencyGraph = this.context.getEntrypointDependencyGraph();
+    if (entrypointDependencyGraph.supportsSelectiveInvalidation()) {
+      return entrypointDependencyGraph.getDependencyEntrypoints(filePath).size > 0;
+    }
+    return true;
+  }
+  /**
+   * Processes a file change by rebuilding affected entrypoints.
+   *
+   * @param filePath - Absolute path to the changed file
+   *
+   * @remarks
+   * If runtime-specific dependency graph hooks are unavailable, this strategy
+   * falls back to rebuilding all watched entrypoints.
+   * When multiple entrypoints are impacted they are bundled in a single esbuild
+   * invocation to share AST parsing and chunk deduplication.
+   * @returns Action to broadcast update events
+   */
+  async process(filePath) {
+    appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
+    const watchedFiles = this.context.getWatchedFiles();
+    if (watchedFiles.size === 0) {
+      appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
+      return { type: "none" };
+    }
+    const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
+    const hasDependencyHit = dependencyHits.size > 0;
+    const impactedEntrypoints = hasDependencyHit ? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint)) : Array.from(watchedFiles.keys());
+    const buildableEntrypoints = impactedEntrypoints.filter(
+      (entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true
+    );
+    if (!hasDependencyHit) {
+      appLogger.debug("[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints");
+    }
+    if (buildableEntrypoints.length === 0) {
+      return { type: "none" };
+    }
+    const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
+    if (!buildResult.success) {
+      return { type: "none" };
+    }
+    const updates = [];
+    let reloadRequired = false;
+    for (const entrypoint of buildableEntrypoints) {
+      const outputUrl = watchedFiles.get(entrypoint);
+      if (!outputUrl) continue;
+      if (buildResult.dependencies) {
+        const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
+        this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
+      }
+      const srcDir = this.context.getSrcDir();
+      const relativePath = path.relative(srcDir, entrypoint);
+      const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
+      const outputPath = path.join(this.context.getDistDir(), relativePathJs);
+      const result = await this.processOutput(outputPath, outputUrl);
+      if (result.success) {
+        updates.push(outputUrl);
+        if (result.requiresReload) {
+          reloadRequired = true;
+        }
+      }
+    }
+    if (updates.length > 0) {
+      if (reloadRequired) {
+        appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
+        return {
+          type: "broadcast",
+          events: [{ type: "reload" }]
+        };
+      }
+      return {
+        type: "broadcast",
+        events: updates.map((p) => ({
+          type: "update",
+          path: p,
+          timestamp: Date.now()
+        }))
+      };
+    }
+    return { type: "none" };
+  }
+  /**
+   * Bundles one or more entrypoints in a single esbuild invocation.
+   * Uses the source directory as the output base so that the directory structure
+   * is preserved under the HMR dist folder.
+   */
+  async bundleEntrypoints(entrypoints) {
+    try {
+      const result = await this.context.getBrowserBundleService().bundle({
+        profile: "hmr-entrypoint",
+        entrypoints,
+        outdir: this.context.getDistDir(),
+        outbase: this.context.getSrcDir(),
+        naming: "[dir]/[name]",
+        plugins: this.context.getPlugins(),
+        minify: false
+      });
+      if (!result.success) {
+        appLogger.error("[JsHmrStrategy] Batched build failed:", result.logs);
+        return { success: false };
+      }
+      const dependencies = /* @__PURE__ */ new Map();
+      if (result.dependencyGraph?.entrypoints) {
+        for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+          dependencies.set(path.resolve(entrypoint), deps);
+        }
+      }
+      return { success: true, dependencies };
+    } catch (error) {
+      appLogger.error("[JsHmrStrategy] Error in batched build:", error);
+      return { success: false };
+    }
+  }
+  /**
+   * Processes bundled output and determines whether the browser can hot-accept
+   * the update or must fall back to a full reload.
+   *
+   * @param filepath - Path to the bundled output file
+   * @param url - URL path for the bundled file
+   * @returns True if processing was successful and update should be broadcast
+   */
+  async processOutput(filepath, url) {
+    try {
+      const code = await fileSystem.readFile(filepath);
+      if (code.includes("/* [ecopages] hmr */")) {
+        return { success: true, requiresReload: !code.includes("import.meta.hot.accept") };
+      }
+      appLogger.debug(`[JsHmrStrategy] Processed ${url}`);
+      const hasHmrAccept = code.includes("import.meta.hot.accept");
+      return { success: true, requiresReload: !hasHmrAccept };
+    } catch (error) {
+      appLogger.error(`[JsHmrStrategy] Error processing output for ${url}:`, error);
+      return { success: false, requiresReload: false };
+    }
+  }
+}
+export {
+  JsHmrStrategy
+};

package/src/index.browser.d.ts

@@ -0,0 +1,3 @@
+export type * from './public-types.js';
+export type * from './eco/eco.types.js';
+export { eco } from './eco/eco.js';

package/src/index.browser.js

@@ -0,0 +1,4 @@
+import { eco } from "./eco/eco.js";
+export {
+  eco
+};

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './public-types.js';
+export type * from './eco/eco.types.js';
+export { eco } from './eco/eco.js';
+export { EcopagesApp, createApp, type EcopagesAppOptions } from './create-app.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './adapters/shared/define-api-handler.js';

package/src/index.js

@@ -0,0 +1,10 @@
+import { eco } from "./eco/eco.js";
+import { EcopagesApp, createApp } from "./create-app.js";
+import { defineApiHandler, defineGroupHandler } from "./adapters/shared/define-api-handler.js";
+export {
+  EcopagesApp,
+  createApp,
+  defineApiHandler,
+  defineGroupHandler,
+  eco
+};

package/src/integrations/ghtml/ghtml-renderer.d.ts

@@ -0,0 +1,15 @@
+/**
+ * This module contains the ghtml renderer
+ * @module
+ */
+import type { EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../public-types.js';
+import { IntegrationRenderer, type RenderToResponseContext } from '../../route-renderer/orchestration/integration-renderer.js';
+/**
+ * A renderer for the ghtml integration.
+ * It renders a page using the HtmlTemplate and Page components.
+ */
+export declare class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
+    name: string;
+    render({ params, query, props, locals, pageLocals, metadata, Page, Layout, HtmlTemplate, }: IntegrationRendererRenderOptions): Promise<RouteRendererBody>;
+    renderToResponse<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, ctx: RenderToResponseContext): Promise<Response>;
+}

package/src/integrations/ghtml/ghtml-renderer.js

@@ -0,0 +1,62 @@
+import {
+  IntegrationRenderer
+} from "../../route-renderer/orchestration/integration-renderer.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.plugin.js";
+class GhtmlRenderer extends IntegrationRenderer {
+  name = GHTML_PLUGIN_NAME;
+  async render({
+    params,
+    query,
+    props,
+    locals,
+    pageLocals,
+    metadata,
+    Page,
+    Layout,
+    HtmlTemplate
+  }) {
+    try {
+      const pageContent = await Page({ params, query, ...props, locals: pageLocals });
+      const children = Layout && typeof Layout === "function" ? await Layout({ children: pageContent, locals }) : pageContent;
+      const body = await HtmlTemplate({
+        metadata,
+        children,
+        pageProps: props || {}
+      });
+      return this.DOC_TYPE + body;
+    } catch (error) {
+      throw this.createRenderError("Error rendering page", error);
+    }
+  }
+  async renderToResponse(view, props, ctx) {
+    try {
+      const Layout = view.config?.layout;
+      const viewFn = view;
+      const pageContent = await viewFn(props);
+      let body;
+      if (ctx.partial) {
+        body = pageContent;
+      } else {
+        const children = Layout ? await Layout({ children: pageContent }) : pageContent;
+        const HtmlTemplate = await this.getHtmlTemplate();
+        const metadata = view.metadata ? await view.metadata({
+          params: {},
+          query: {},
+          props,
+          appConfig: this.appConfig
+        }) : this.appConfig.defaultMetadata;
+        body = this.DOC_TYPE + await HtmlTemplate({
+          metadata,
+          children,
+          pageProps: props
+        });
+      }
+      return this.createHtmlResponse(body, ctx);
+    } catch (error) {
+      throw this.createRenderError("Error rendering view", error);
+    }
+  }
+}
+export {
+  GhtmlRenderer
+};

package/src/integrations/ghtml/ghtml.plugin.d.ts

@@ -0,0 +1,20 @@
+import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin';
+import { GhtmlRenderer } from './ghtml-renderer';
+/**
+ * The name of the ghtml plugin
+ */
+export declare const GHTML_PLUGIN_NAME = "ghtml";
+/**
+ * The Ghtml plugin class
+ * This plugin provides support for ghtml components in Ecopages
+ */
+export declare class GhtmlPlugin extends IntegrationPlugin {
+    renderer: typeof GhtmlRenderer;
+    constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
+}
+/**
+ * Factory function to create a Ghtml plugin instance
+ * @param options Configuration options for the Ghtml plugin
+ * @returns A new GhtmlPlugin instance
+ */
+export declare function ghtmlPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): GhtmlPlugin;

package/src/integrations/ghtml/ghtml.plugin.js

@@ -0,0 +1,21 @@
+import { IntegrationPlugin } from "../../plugins/integration-plugin";
+import { GhtmlRenderer } from "./ghtml-renderer";
+const GHTML_PLUGIN_NAME = "ghtml";
+class GhtmlPlugin extends IntegrationPlugin {
+  renderer = GhtmlRenderer;
+  constructor(options) {
+    super({
+      name: GHTML_PLUGIN_NAME,
+      extensions: [".ghtml.ts", ".ghtml.tsx", ".ghtml"],
+      ...options
+    });
+  }
+}
+function ghtmlPlugin(options) {
+  return new GhtmlPlugin(options);
+}
+export {
+  GHTML_PLUGIN_NAME,
+  GhtmlPlugin,
+  ghtmlPlugin
+};

package/src/internal-types.d.ts

@@ -0,0 +1,221 @@
+import type { EcoBuildPlugin } from './build/build-types.js';
+import type { AppBuildManifest } from './build/build-manifest.js';
+import type { BuildAdapter, BuildExecutor } from './build/build-adapter.js';
+import type { IntegrationPlugin } from './plugins/integration-plugin.js';
+import type { Processor } from './plugins/processor.js';
+import type { PageMetadataProps } from './public-types.js';
+import type { FSRouter } from './router/server/fs-router.js';
+import type { CacheConfig } from './services/cache/cache.types.js';
+import type { DevGraphService } from './services/runtime-state/dev-graph.service.js';
+import type { EntrypointDependencyGraph } from './services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { NodeRuntimeManifest } from './services/runtime-manifest/node-runtime-manifest.service.js';
+import type { RuntimeSpecifierRegistry } from './services/runtime-state/runtime-specifier-registry.service.js';
+import type { ServerInvalidationState } from './services/runtime-state/server-invalidation-state.service.js';
+import type { ServerModuleTranspiler } from './services/module-loading/server-module-transpiler.service.js';
+export interface RobotsPreference {
+    /**
+     * The user agent
+     * If an empty array is provided, it will enable all paths for the user agent
+     * If a path is provided, it will disallow the path for the user agent
+     */
+    [key: string]: string[];
+}
+/**
+ * Represents the complete configuration object for EcoPages.
+ */
+export type EcoPagesAppConfig = {
+    /**
+     * The base URL of the website, localhost or the domain
+     */
+    baseUrl: string;
+    /**
+     * The root directory of the project
+     * @default "."
+     */
+    rootDir: string;
+    /**
+     * The root directory of the project
+     * @default "src"
+     */
+    srcDir: string;
+    /**
+     * The directory where the public files are located
+     * @default "public"
+     */
+    publicDir: string;
+    /**
+     * The directory where the pages are located
+     * @default "pages"
+     */
+    pagesDir: string;
+    /**
+     * The directory where the includes templates are located
+     * @default "includes"
+     */
+    includesDir: string;
+    /**
+     * The directory where the layouts are located
+     * @default "layouts"
+     */
+    layoutsDir: string;
+    /**
+     * The directory where the output will be located
+     * @default "dist"
+     */
+    distDir: string;
+    /**
+     * The directory where internal runtime and build artifacts are stored.
+     *
+     * @remarks
+     * This directory is not intended for deployment. It owns transpiled server
+     * modules, runtime manifests, and processor caches so `distDir` can remain a
+     * clean export tree.
+     *
+     * @default ".eco"
+     */
+    workDir: string;
+    /**
+     * The templates extensions based on the integrations
+     */
+    templatesExt: string[];
+    /**
+     * The directory where the components are located
+     * @default "components"
+     */
+    componentsDir: string;
+    /**
+     * The robots.txt configuration
+     */
+    robotsTxt: {
+        /**
+         * The robots preferences. The key is the user agent and the value is the disallowed paths.
+         * @default { "*": [] }
+         */
+        preferences: RobotsPreference;
+    };
+    /** Additional paths to watch. Use this to monitor extra files. It is relative to the rootDir */
+    additionalWatchPaths: string[];
+    /**
+     * @default { title: 'Ecopages', description: 'Ecopages' }
+     */
+    defaultMetadata: PageMetadataProps;
+    /** Integrations plugins */
+    integrations: IntegrationPlugin[];
+    /** Integrations dependencies */
+    integrationsDependencies: IntegrationDependencyConfig[];
+    /** Derived Paths */
+    absolutePaths: {
+        config: string;
+        componentsDir: string;
+        distDir: string;
+        workDir: string;
+        includesDir: string;
+        layoutsDir: string;
+        pagesDir: string;
+        projectDir: string;
+        publicDir: string;
+        srcDir: string;
+        htmlTemplatePath: string;
+        error404TemplatePath: string;
+    };
+    /**
+     * The processors to be used in the app
+     */
+    processors: Map<string, Processor>;
+    /**
+     * Loaders to be used in the app, these are used to process the files when importing them
+     */
+    loaders: Map<string, EcoBuildPlugin>;
+    /**
+     * Cache configuration for ISR and page caching.
+     * @default { store: 'memory', defaultStrategy: 'static', enabled: true }
+     */
+    cache?: CacheConfig;
+    /**
+     * Runtime-owned services attached after config construction.
+     *
+     * These values are internal implementation details used to thread per-app
+     * executors and similar runtime state through the system without relying on
+     * process-global registries.
+     */
+    runtime?: {
+        buildAdapter?: BuildAdapter;
+        buildManifest?: AppBuildManifest;
+        buildExecutor?: BuildExecutor;
+        devGraphService?: DevGraphService;
+        entrypointDependencyGraph?: EntrypointDependencyGraph;
+        nodeRuntimeManifest?: NodeRuntimeManifest;
+        runtimeSpecifierRegistry?: RuntimeSpecifierRegistry;
+        serverInvalidationState?: ServerInvalidationState;
+        serverModuleTranspiler?: ServerModuleTranspiler;
+    };
+    /**
+     * Experimental features.
+     */
+    experimental?: {
+        /** Escape hatch for short-lived private toggles. No validation or IntelliSense. */
+        unsafe?: Record<string, unknown>;
+    };
+};
+export type IntegrationDependencyConfig = {
+    integration: string;
+    kind: 'script' | 'stylesheet';
+    position?: 'head' | 'body';
+    srcUrl: string;
+    filePath: string;
+    /** @todo inline dependencies not implemented yet */
+    inline?: boolean;
+};
+/**
+ * The possible kinds of a route.
+ */
+export type RouteKind = 'exact' | 'catch-all' | 'dynamic';
+/**
+ * Represents the result of a route match.
+ */
+export type MatchResult = {
+    filePath: string;
+    kind: RouteKind;
+    pathname: string;
+    query?: Record<string, string>;
+    params?: Record<string, string | string[]>;
+};
+/**
+ * Represents a route in EcoPages.
+ */
+export type Route = {
+    kind: RouteKind;
+    filePath: string;
+    pathname: string;
+};
+/**
+ * Represents the routes in EcoPages.
+ */
+export type Routes = Record<string, Route>;
+/**
+ * Represents the options for the file system server.
+ */
+export type FileSystemServerOptions = {
+    watchMode: boolean;
+    port?: number | string;
+};
+/**
+ * Represents the file system server adapter.
+ */
+export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown> {
+    startServer(serverOptions: ServerInstanceOptions): {
+        router: FSRouter;
+        server: unknown;
+    } | Promise<{
+        router: FSRouter;
+        server: unknown;
+    }>;
+}
+export interface ProcessorPlugin {
+    name: string;
+    description?: string;
+    setup(): Promise<void>;
+    process<T = unknown>(input: T): Promise<T>;
+    teardown?(): Promise<void>;
+}
+export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.js';

package/src/plugins/alias-resolver-plugin.d.ts

@@ -0,0 +1,2 @@
+import type { EcoBuildPlugin } from '../build/build-types.js';
+export declare function createAliasResolverPlugin(srcDir: string): EcoBuildPlugin;

package/src/plugins/alias-resolver-plugin.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+const RESOLVABLE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mdx", ".css", ".scss", ".sass", ".less"];
+function findResolvablePath(candidate) {
+  if (path.extname(candidate)) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const fileCandidate = `${candidate}${extension}`;
+    if (existsSync(fileCandidate)) {
+      return fileCandidate;
+    }
+  }
+  for (const extension of RESOLVABLE_EXTENSIONS) {
+    const indexCandidate = path.join(candidate, `index${extension}`);
+    if (existsSync(indexCandidate)) {
+      return indexCandidate;
+    }
+  }
+  return void 0;
+}
+function resolveAliasedBarrelTarget(resolvedPath) {
+  if (!path.basename(resolvedPath).startsWith("index.")) {
+    return resolvedPath;
+  }
+  const source = readFileSync(resolvedPath, "utf8").trim();
+  const match = source.match(/^export\s+\*\s+from\s+['"]([^'"]+)['"]\s*;?$/);
+  if (!match?.[1]?.startsWith(".")) {
+    return resolvedPath;
+  }
+  const target = findResolvablePath(path.resolve(path.dirname(resolvedPath), match[1]));
+  return target ?? resolvedPath;
+}
+function createAliasResolverPlugin(srcDir) {
+  return {
+    name: "ecopages-alias-resolver",
+    setup(build) {
+      build.onResolve({ filter: /^@\// }, (args) => {
+        const candidate = path.join(srcDir, args.path.slice(2));
+        const resolved = findResolvablePath(candidate);
+        if (resolved) {
+          return { path: resolveAliasedBarrelTarget(resolved) };
+        }
+        return {};
+      });
+    }
+  };
+}
+export {
+  createAliasResolverPlugin
+};