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

package/src/hmr/strategies/default-hmr-strategy.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Default HMR Strategy
+ *
+ * Fallback strategy for file types that don't have specialized handling.
+ * Triggers a full page reload to ensure changes are reflected.
+ *
+ * @module
+ */
+import { HmrStrategy, type HmrAction } from '../hmr-strategy.js';
+/**
+ * Default fallback strategy for unhandled file types.
+ *
+ * This strategy matches all files and triggers a full page reload.
+ * It has the lowest priority (FALLBACK) and acts as a catch-all when
+ * no other strategy matches the changed file.
+ *
+ * @remarks
+ * This strategy ensures that all file changes result in some action,
+ * even if we don't have specialized handling for that file type.
+ *
+ * @example
+ * ```typescript
+ * const strategy = new DefaultHmrStrategy();
+ * const action = await strategy.process('/path/to/unknown.file');
+ * ```
+ */
+export declare class DefaultHmrStrategy extends HmrStrategy {
+    readonly type: 0;
+    /**
+     * Matches all file paths.
+     *
+     * @param _filePath - Absolute path to the changed file (unused)
+     * @returns Always returns true as this is a catch-all strategy
+     */
+    matches(_filePath: string): boolean;
+    /**
+     * Processes a file change by triggering a full page reload.
+     *
+     * @param filePath - Absolute path to the changed file
+     * @returns Action to broadcast a reload event
+     */
+    process(filePath: string): Promise<HmrAction>;
+}

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

@@ -0,0 +1,34 @@
+import { HmrStrategy, HmrStrategyType } from "../hmr-strategy.js";
+class DefaultHmrStrategy extends HmrStrategy {
+  type = HmrStrategyType.FALLBACK;
+  /**
+   * Matches all file paths.
+   *
+   * @param _filePath - Absolute path to the changed file (unused)
+   * @returns Always returns true as this is a catch-all strategy
+   */
+  matches(_filePath) {
+    return true;
+  }
+  /**
+   * Processes a file change by triggering a full page reload.
+   *
+   * @param filePath - Absolute path to the changed file
+   * @returns Action to broadcast a reload event
+   */
+  async process(filePath) {
+    return {
+      type: "broadcast",
+      events: [
+        {
+          type: "reload",
+          path: filePath,
+          message: "fallback-strategy"
+        }
+      ]
+    };
+  }
+}
+export {
+  DefaultHmrStrategy
+};

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

@@ -0,0 +1,139 @@
+/**
+ * JavaScript HMR Strategy
+ *
+ * Handles hot module replacement for JavaScript and TypeScript entrypoints.
+ * Bundles files, inspects the emitted output, and decides whether the browser
+ * can hot-accept the change or must reload.
+ *
+ * @module
+ */
+import { HmrStrategy, type HmrAction } from '../hmr-strategy.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { BrowserBundleExecutor } from '../../services/assets/browser-bundle.service.js';
+import type { EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.js';
+/**
+ * Context interface providing access to HmrManager state.
+ * Required for JsHmrStrategy to access registered entrypoints and configuration.
+ */
+export interface JsHmrContext {
+    /**
+     * Map of registered entrypoints to their output URLs.
+     */
+    getWatchedFiles(): Map<string, string>;
+    /**
+     * Map of bare specifiers to vendor URLs for import resolution.
+     */
+    getSpecifierMap(): Map<string, string>;
+    getEntrypointDependencyGraph(): EntrypointDependencyGraph;
+    /**
+     * Directory where HMR bundles are written.
+     */
+    getDistDir(): string;
+    /**
+     * Build plugins to use during bundling.
+     */
+    getPlugins(): EcoBuildPlugin[];
+    /**
+     * Absolute path to the source directory.
+     */
+    getSrcDir(): string;
+    /**
+     * Absolute path to the pages directory.
+     */
+    getPagesDir(): string;
+    /**
+     * Absolute path to the layouts directory.
+     */
+    getLayoutsDir(): string;
+    /**
+     * All configured route-template extensions across integrations.
+     */
+    getTemplateExtensions(): string[];
+    /**
+     * Browser bundler used to rebuild changed entrypoints.
+     */
+    getBrowserBundleService(): BrowserBundleExecutor;
+    /**
+     * Returns whether a watched entrypoint should be rebuilt by the generic JS strategy.
+     *
+     * @remarks
+     * Integrations with higher-priority HMR strategies can use this to keep the
+     * generic JS strategy from overwriting their emitted entrypoints when a shared
+     * dependency changes.
+     */
+    shouldProcessEntrypoint?(entrypointPath: string): boolean;
+}
+/**
+ * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
+ *
+ * The processing steps are:
+ * 1. Check if any entrypoints are registered
+ * 2. Rebuild impacted entrypoints, or all watched entrypoints when no runtime
+ *    dependency graph is available
+ * 3. Emit rebuilt entrypoint bundles for browser delivery
+ * 4. Inject generic HMR boilerplate
+ * 5. Broadcast update events for each rebuilt entrypoint
+ *
+ * @remarks
+ * Node can provide dependency-graph metadata, so this strategy can rebuild only
+ * the entrypoints impacted by a changed dependency. Runtimes that do not expose
+ * that metadata intentionally keep the rebuild-all fallback.
+ *
+ * @see https://bun.sh/docs/runtime/transpiler
+ *
+ * @example
+ * ```typescript
+ * const context = {
+ *   getWatchedFiles: () => watchedFilesMap,
+ *   getSpecifierMap: () => specifierMap,
+ *   getDistDir: () => '/path/to/dist/_hmr',
+ *   getPlugins: () => [],
+ *   getSrcDir: () => '/path/to/src'
+ * };
+ * const strategy = new JsHmrStrategy(context);
+ * ```
+ */
+export declare class JsHmrStrategy extends HmrStrategy {
+    readonly type: 25;
+    private context;
+    constructor(context: JsHmrContext);
+    /**
+     * 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: string): boolean;
+    /**
+     * 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
+     */
+    process(filePath: string): Promise<HmrAction>;
+    /**
+     * 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.
+     */
+    private bundleEntrypoints;
+    /**
+     * 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
+     */
+    private processOutput;
+}

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.js";
+import { appLogger } from "../../global/app-logger.js";
+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 './types/public-types.js';
+export type * from './eco/eco.types.js';
+export { eco } from './eco/eco.browser.js';

package/src/index.browser.js

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

package/src/index.d.ts

@@ -0,0 +1,6 @@
+export type * from './types/public-types.js';
+export type * from './eco/eco.types.js';
+export { eco } from './eco/eco.js';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './adapters/shared/define-api-handler.js';
+export { createEcoBuildPluginFromSourceTransform, createVitePluginsFromAppSourceTransforms, getAppSourceTransforms, createVitePluginFromSourceTransform, normalizeTransformId, type EcoSourceTransform, type EcoSourceTransformResult, type EcoViteCompatiblePlugin, } from './plugins/source-transform.js';
+export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.js';

package/src/index.js

@@ -0,0 +1,21 @@
+import { eco } from "./eco/eco.js";
+import { defineApiHandler, defineGroupHandler } from "./adapters/shared/define-api-handler.js";
+import {
+  createEcoBuildPluginFromSourceTransform,
+  createVitePluginsFromAppSourceTransforms,
+  getAppSourceTransforms,
+  createVitePluginFromSourceTransform,
+  normalizeTransformId
+} from "./plugins/source-transform.js";
+import { createEcoComponentMetaTransform } from "./plugins/eco-component-meta-plugin.js";
+export {
+  createEcoBuildPluginFromSourceTransform,
+  createEcoComponentMetaTransform,
+  createVitePluginFromSourceTransform,
+  createVitePluginsFromAppSourceTransforms,
+  defineApiHandler,
+  defineGroupHandler,
+  eco,
+  getAppSourceTransforms,
+  normalizeTransformId
+};

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

@@ -0,0 +1,20 @@
+/**
+ * This module contains the ghtml renderer
+ * @module
+ */
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '../../types/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;
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    protected createComponentBoundaryRuntime(options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): import("../../index.browser.js").ComponentBoundaryRuntime;
+    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,63 @@
+import {
+  IntegrationRenderer
+} from "../../route-renderer/orchestration/integration-renderer.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
+class GhtmlRenderer extends IntegrationRenderer {
+  name = GHTML_PLUGIN_NAME;
+  async renderComponent(input) {
+    return this.renderStringComponentBoundaryWithQueuedForeignBoundaries(
+      input,
+      input.component
+    );
+  }
+  createComponentBoundaryRuntime(options) {
+    return this.createQueuedBoundaryRuntime({
+      boundaryInput: options.boundaryInput,
+      rendererCache: options.rendererCache
+    });
+  }
+  async render({
+    params,
+    query,
+    props,
+    locals,
+    pageLocals,
+    metadata,
+    Page,
+    Layout,
+    HtmlTemplate
+  }) {
+    try {
+      return await this.renderPageWithDocumentShell({
+        page: {
+          component: Page,
+          props: { params, query, ...props, locals: pageLocals }
+        },
+        layout: Layout ? {
+          component: Layout,
+          props: locals ? { locals } : {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
+        metadata,
+        pageProps: props ?? {}
+      });
+    } catch (error) {
+      throw this.createRenderError("Error rendering page", error);
+    }
+  }
+  async renderToResponse(view, props, ctx) {
+    try {
+      return await this.renderViewWithDocumentShell({
+        view,
+        props,
+        ctx,
+        layout: view.config?.layout
+      });
+    } catch (error) {
+      throw this.createRenderError("Error rendering view", error);
+    }
+  }
+}
+export {
+  GhtmlRenderer
+};

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

@@ -0,0 +1 @@
+export declare const GHTML_PLUGIN_NAME = "ghtml";

package/src/integrations/ghtml/ghtml.constants.js

@@ -0,0 +1,4 @@
+const GHTML_PLUGIN_NAME = "ghtml";
+export {
+  GHTML_PLUGIN_NAME
+};

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

@@ -0,0 +1,16 @@
+import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin.js';
+import { GhtmlRenderer } from './ghtml-renderer.js';
+/**
+ * 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,20 @@
+import { IntegrationPlugin } from "../../plugins/integration-plugin.js";
+import { GhtmlRenderer } from "./ghtml-renderer.js";
+import { GHTML_PLUGIN_NAME } from "./ghtml.constants.js";
+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 {
+  GhtmlPlugin,
+  ghtmlPlugin
+};

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
+};