@ecopages/core 0.2.0-alpha.9 → 0.2.0-beta.1

package/src/services/module-loading/page-module-import.service.js

@@ -2,6 +2,8 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { fileSystem } from "@ecopages/file-system";
 import { build } from "../../build/build-adapter.js";
+import { normalizeNodeRuntimeBuildOutputFile } from "../../build/runtime-build-output-normalizer.js";
+import { supportsSourceModuleLoading } from "./source-module-support.js";
 class PageModuleImportService {
   dependencies;
   importCache = /* @__PURE__ */ new Map();
@@ -9,7 +11,9 @@ class PageModuleImportService {
   constructor(dependencies) {
     this.dependencies = {
       hashFile: dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath)),
-      buildModule: dependencies?.buildModule ?? ((options, buildExecutor) => build(options, buildExecutor))
+      buildModule: dependencies?.buildModule ?? ((options, buildExecutor) => build(options, buildExecutor)),
+      canLoadSourceModuleFromHost: dependencies?.canLoadSourceModuleFromHost ?? supportsSourceModuleLoading,
+      getHostModuleLoader: dependencies?.getHostModuleLoader ?? (() => void 0)
     };
   }
   /**
@@ -44,16 +48,33 @@ class PageModuleImportService {
    * @returns The loaded module.
    */
   async importModule(options) {
-    const { filePath, rootDir, externalPackages, splitting } = options;
+    const { filePath } = options;
     const invalidationVersion = options.invalidationVersion ?? this.developmentInvalidationVersion;
+    const { externalPackages, splitting } = options;
     const fileHash = this.dependencies.hashFile(filePath);
-    const runtime = typeof Bun !== "undefined" ? "bun" : "node";
+    const hostModuleLoader = typeof Bun === "undefined" && process.env.NODE_ENV === "development" && this.dependencies.canLoadSourceModuleFromHost(filePath) ? this.dependencies.getHostModuleLoader() : void 0;
+    if (hostModuleLoader) {
+      const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, options.cacheScope);
+      return await hostModuleLoader(sourceModuleUrl.href);
+    }
+    if (options.bypassCache) {
+      this.developmentInvalidationVersion += 1;
+      return await this.loadModule({
+        ...options,
+        invalidationVersion: this.developmentInvalidationVersion,
+        fileHash
+      });
+    }
+    const runtime = typeof Bun !== "undefined" ? "bun" : "node-build";
     const cacheKey = [
       runtime,
       filePath,
-      rootDir,
+      options.rootDir,
       splitting ?? "default",
       externalPackages ?? "default",
+      options.cacheScope ?? "default",
+      createJsxCacheKey(options.jsx),
+      createPluginCacheKey(options.plugins),
       fileHash,
       invalidationVersion
     ].join("::");
@@ -74,38 +95,33 @@ class PageModuleImportService {
     }
   }
   async loadModule(options) {
+    const { filePath, invalidationVersion = this.developmentInvalidationVersion, cacheScope, fileHash } = options;
     const {
-      filePath,
       rootDir,
       outdir,
-      invalidationVersion = this.developmentInvalidationVersion,
       splitting,
       externalPackages,
       transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
-      noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
-      fileHash
+      noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`
     } = options;
-    if (typeof Bun !== "undefined") {
-      const moduleUrl = pathToFileURL(filePath);
-      if (process.env.NODE_ENV === "development") {
-        moduleUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
-      }
-      return await import(moduleUrl.href);
-    }
     const fileBaseName = path.basename(filePath, path.extname(filePath));
-    const outputFileName = `${fileBaseName}-${fileHash}.js`;
+    const cacheScopeSuffix = cacheScope ? `-${sanitizeCacheScope(cacheScope)}` : "";
+    const invalidationSuffix = shouldVersionBuildOutputPath(invalidationVersion) ? `-v${invalidationVersion}` : "";
+    const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${invalidationSuffix}.mjs`;
+    const outputNamingTemplate = `${fileBaseName}-${fileHash}${cacheScopeSuffix}${invalidationSuffix}.[ext]`;
     const buildResult = await this.dependencies.buildModule(
       {
         entrypoints: [filePath],
         root: rootDir,
         outdir,
-        target: "node",
+        target: "es2022",
         format: "esm",
         sourcemap: "none",
         splitting: splitting ?? true,
         minify: false,
-        naming: outputFileName,
+        naming: outputNamingTemplate,
         externalPackages: true,
+        jsx: options.jsx,
         plugins: options.plugins,
         ...externalPackages !== void 0 ? { externalPackages } : {}
       },
@@ -116,16 +132,61 @@ class PageModuleImportService {
       throw new Error(transpileErrorMessage(details));
     }
     const preferredOutputPath = path.join(outdir, outputFileName);
-    const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => output.path.endsWith(".js"))?.path;
+    const compiledOutput = buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ?? buildResult.outputs.find((output) => /\.(?:[cm]?js)$/u.test(output.path))?.path;
     if (!compiledOutput) {
       throw new Error(noOutputMessage(filePath));
     }
+    normalizeNodeRuntimeBuildOutputFile(compiledOutput, rootDir);
     const compiledOutputUrl = pathToFileURL(compiledOutput);
-    if (process.env.NODE_ENV === "development") {
-      compiledOutputUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
+    if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
+      compiledOutputUrl.searchParams.set(
+        "update",
+        [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : void 0].filter((value) => value !== void 0).join("-")
+      );
     }
-    return await import(compiledOutputUrl.href);
+    return await import(
+      /* @vite-ignore */
+      compiledOutputUrl.href
+    );
+  }
+}
+function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheScope) {
+  const moduleUrl = pathToFileURL(filePath);
+  if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
+    moduleUrl.searchParams.set(
+      "update",
+      [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : void 0].filter((value) => value !== void 0).join("-")
+    );
+  }
+  return moduleUrl;
+}
+function shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope) {
+  return process.env.NODE_ENV === "development" || invalidationVersion > 0 || !!cacheScope;
+}
+function shouldVersionBuildOutputPath(invalidationVersion) {
+  return typeof Bun !== "undefined" && invalidationVersion > 0;
+}
+function sanitizeCacheScope(cacheScope) {
+  return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+function createJsxCacheKey(jsx) {
+  if (!jsx) {
+    return "jsx:default";
+  }
+  return JSON.stringify({
+    development: jsx.development ?? false,
+    factory: jsx.factory ?? null,
+    fragment: jsx.fragment ?? null,
+    importSource: jsx.importSource ?? null,
+    runtime: jsx.runtime ?? null,
+    sideEffects: jsx.sideEffects ?? null
+  });
+}
+function createPluginCacheKey(plugins) {
+  if (!plugins || plugins.length === 0) {
+    return "plugins:default";
   }
+  return `plugins:${plugins.map((plugin) => plugin.name).join(",")}`;
 }
 export {
   PageModuleImportService

package/src/services/module-loading/server-module-transpiler.service.d.ts

@@ -1,18 +1,10 @@
 import type { BuildExecutor } from '../../build/build-adapter.js';
 import type { EcoBuildPlugin } from '../../build/build-types.js';
-import { type PageModuleImportOptions } from './page-module-import.service.js';
-export type ServerModuleTranspilerOptions = Omit<PageModuleImportOptions, 'rootDir' | 'buildExecutor'>;
-/**
- * Minimal import-service dependency required by the server module transpiler.
- *
- * @remarks
- * This keeps the transpiler boundary testable without module-level mocking and
- * lets callers provide an app-owned import implementation when needed.
- */
-export interface ServerModuleImportDependency {
-    importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
-    invalidateDevelopmentGraph(): void;
-}
+import type { AppModuleLoader } from './app-module-loader.service.js';
+import { type PageModuleBuildImportOptions } from './page-module-import.service.js';
+import type { SourceModuleLoaderFactory } from './module-loading-types.js';
+export type ServerModuleTranspilerOptions = Omit<PageModuleBuildImportOptions, 'rootDir' | 'buildExecutor'>;
+export type ServerModuleImportDependency = Pick<AppModuleLoader, 'importModule' | 'invalidateDevelopmentGraph'>;
 /**
  * Immutable execution context for one server-transpiler instance.
  *
@@ -23,7 +15,9 @@ export interface ServerModuleImportDependency {
  */
 export type ServerModuleTranspilerBootstrapArgs = {
     rootDir: string;
-    getBuildExecutor: () => BuildExecutor | undefined;
+    getBuildExecutor?: () => BuildExecutor | undefined;
+    canLoadSourceModuleFromHost?: (filePath: string) => boolean;
+    getHostModuleLoader?: SourceModuleLoaderFactory;
     getInvalidationVersion?: () => number;
     invalidateModules?: (changedFiles?: string[]) => void;
     pageModuleImportService?: ServerModuleImportDependency;

package/src/services/module-loading/server-module-transpiler.service.js

@@ -11,9 +11,12 @@ class ServerModuleTranspiler {
    * context.
    */
   constructor(args) {
-    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService();
+    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService({
+      canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
+      getHostModuleLoader: args.getHostModuleLoader
+    });
     this.getRootDir = () => args.rootDir;
-    this.getBuildExecutor = args.getBuildExecutor;
+    this.getBuildExecutor = args.getBuildExecutor ?? (() => void 0);
     this.getInvalidationVersion = () => args.getInvalidationVersion?.();
     this.getDefaultPlugins = args.getDefaultPlugins ?? (() => []);
     this.invalidateModules = (changedFiles) => {

package/src/services/module-loading/source-module-support.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns whether a source module can be loaded directly by the host runtime without
+ * first going through the transpile/import pipeline.
+ */
+export declare function supportsSourceModuleLoading(filePath: string): boolean;

package/src/services/module-loading/source-module-support.js

@@ -0,0 +1,8 @@
+import path from "node:path";
+function supportsSourceModuleLoading(filePath) {
+  const extension = path.extname(filePath);
+  return extension === ".js" || extension === ".jsx" || extension === ".ts" || extension === ".tsx" || extension === ".mjs" || extension === ".mts" || extension === ".cjs" || extension === ".cts";
+}
+export {
+  supportsSourceModuleLoading
+};

package/src/services/runtime-state/dev-graph.service.d.ts

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import { type ServerInvalidationState } from './server-invalidation-state.service.js';
 import { type EntrypointDependencyGraph } from './entrypoint-dependency-graph.service.js';
 /**
@@ -32,7 +32,7 @@ export declare class NoopDevGraphService implements DevGraphService {
     /**
      * Invalidates all server-side module state by incrementing the shared version.
      */
-    invalidateServerModules(_changedFiles?: string[]): void;
+    invalidateServerModules(changedFiles?: string[]): void;
     /**
      * Indicates that this graph cannot target invalidation to one entrypoint set.
      */
@@ -41,19 +41,19 @@ export declare class NoopDevGraphService implements DevGraphService {
      * Returns an empty entrypoint set because this implementation stores no
      * dependency graph metadata.
      */
-    getDependencyEntrypoints(_filePath: string): Set<string>;
+    getDependencyEntrypoints(filePath: string): Set<string>;
     /**
      * Accepts dependency updates to preserve interface compatibility, but stores no
      * graph state in the noop implementation.
      */
-    setEntrypointDependencies(_entrypointPath: string, _dependencies: string[]): void;
+    setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void;
     /**
      * Clears one entrypoint from the graph.
      *
      * @remarks
      * There is no stored graph state in this implementation, so this is a no-op.
      */
-    clearEntrypointDependencies(_entrypointPath: string): void;
+    clearEntrypointDependencies(entrypointPath: string): void;
     /**
      * Resets graph-owned state for a fresh runtime cycle.
      */
@@ -82,7 +82,7 @@ export declare class InMemoryDevGraphService implements DevGraphService {
      * modules. Selective dependency lookups are used by callers that need to limit
      * browser rebuild work.
      */
-    invalidateServerModules(_changedFiles?: string[]): void;
+    invalidateServerModules(changedFiles?: string[]): void;
     /**
      * Indicates that this graph can answer dependency-to-entrypoint lookups.
      */

package/src/services/runtime-state/dev-graph.service.js

@@ -21,8 +21,8 @@ class NoopDevGraphService {
   /**
    * Invalidates all server-side module state by incrementing the shared version.
    */
-  invalidateServerModules(_changedFiles) {
-    this.invalidationState.invalidateServerModules(_changedFiles);
+  invalidateServerModules(changedFiles) {
+    this.invalidationState.invalidateServerModules(changedFiles);
   }
   /**
    * Indicates that this graph cannot target invalidation to one entrypoint set.
@@ -34,15 +34,15 @@ class NoopDevGraphService {
    * Returns an empty entrypoint set because this implementation stores no
    * dependency graph metadata.
    */
-  getDependencyEntrypoints(_filePath) {
-    return this.dependencyGraph.getDependencyEntrypoints(_filePath);
+  getDependencyEntrypoints(filePath) {
+    return this.dependencyGraph.getDependencyEntrypoints(filePath);
   }
   /**
    * Accepts dependency updates to preserve interface compatibility, but stores no
    * graph state in the noop implementation.
    */
-  setEntrypointDependencies(_entrypointPath, _dependencies) {
-    this.dependencyGraph.setEntrypointDependencies(_entrypointPath, _dependencies);
+  setEntrypointDependencies(entrypointPath, dependencies) {
+    this.dependencyGraph.setEntrypointDependencies(entrypointPath, dependencies);
   }
   /**
    * Clears one entrypoint from the graph.
@@ -50,8 +50,8 @@ class NoopDevGraphService {
    * @remarks
    * There is no stored graph state in this implementation, so this is a no-op.
    */
-  clearEntrypointDependencies(_entrypointPath) {
-    this.dependencyGraph.clearEntrypointDependencies(_entrypointPath);
+  clearEntrypointDependencies(entrypointPath) {
+    this.dependencyGraph.clearEntrypointDependencies(entrypointPath);
   }
   /**
    * Resets graph-owned state for a fresh runtime cycle.
@@ -78,8 +78,8 @@ class InMemoryDevGraphService {
    * modules. Selective dependency lookups are used by callers that need to limit
    * browser rebuild work.
    */
-  invalidateServerModules(_changedFiles) {
-    this.invalidationState.invalidateServerModules(_changedFiles);
+  invalidateServerModules(changedFiles) {
+    this.invalidationState.invalidateServerModules(changedFiles);
   }
   /**
    * Indicates that this graph can answer dependency-to-entrypoint lookups.

package/src/services/runtime-state/entrypoint-dependency-graph.service.d.ts

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 /**
  * App-owned dependency graph used to target browser entrypoint rebuilds.
  */

package/src/services/runtime-state/server-invalidation-state.service.d.ts

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 /**
  * App-owned coarse invalidation state for server-executed modules.
  */

package/src/static-site-generator/static-site-generator.d.ts

@@ -1,7 +1,14 @@
-import type { EcoPagesAppConfig } from '../internal-types.js';
-import type { StaticRoute } from '../public-types.js';
-import type { RouteRendererFactory } from '../route-renderer/route-renderer.js';
-import type { FSRouter } from '../router/server/fs-router.js';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+import type { StaticRoute } from '../types/public-types.js';
+import type { PageRendererResolver, StaticGenerationRendererResolver } from '../route-renderer/route-renderer.js';
+import type { StaticGenerationRoute } from '../router/server/route-registry.js';
+type StaticGenerationRouteSource = {
+    listStaticGenerationRoutes(input: {
+        runtimeOrigin: string;
+    }): Promise<readonly StaticGenerationRoute[]>;
+};
+type StaticPageRouteRendererFactory = PageRendererResolver;
+type StaticGenerationRendererFactory = StaticGenerationRendererResolver;
 export declare const STATIC_SITE_GENERATOR_ERRORS: {
     readonly ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy";
     readonly unsupportedBodyType: (bodyType: string) => string;
@@ -20,17 +27,12 @@ export declare const STATIC_SITE_GENERATOR_ERRORS: {
  */
 export declare class StaticSiteGenerator {
     appConfig: EcoPagesAppConfig;
-    private serverModuleTranspiler;
     /**
      * Creates the static-site generator for one app config.
      */
     constructor({ appConfig }: {
         appConfig: EcoPagesAppConfig;
     });
-    /**
-     * Returns the transpiler output directory used for static page-module probes.
-     */
-    private getStaticPageModuleOutdir;
     private getExportDir;
     /**
      * Logs the standardized warning emitted when a dynamic-cache page is skipped.
@@ -58,14 +60,9 @@ export declare class StaticSiteGenerator {
      * Collects parent directories that must exist for the generated route set.
      */
     getDirectories(routes: string[]): string[];
-    /**
-     * Extracts dynamic parameters from the actual path based on the template path.
-     *
-     * @param templatePath - The template path (e.g., "/blog/[slug]")
-     * @param actualPath - The actual path (e.g., "/blog/my-post")
-     * @returns A record of extracted parameters (e.g., { slug: "my-post" })
-     */
-    private extractParams;
+    private writeStaticOutput;
+    private getStaticBuildStrategy;
+    private createFilesystemStaticContents;
     /**
      * Generates static output for all filesystem-discovered routes.
      *
@@ -74,14 +71,15 @@ export declare class StaticSiteGenerator {
      * issuing a request against the running server origin. Render-strategy routes
      * go through the normal route renderer directly.
      */
-    generateStaticPages(router: FSRouter, baseUrl: string, routeRendererFactory?: RouteRendererFactory): Promise<void>;
+    generateStaticPages(router: StaticGenerationRouteSource, baseUrl: string, routeRendererFactory?: StaticPageRouteRendererFactory): Promise<void>;
+    private resolveStaticFetchUrl;
     /**
      * Executes the full static-generation workflow for one app run.
      */
     run({ router, baseUrl, routeRendererFactory, staticRoutes, }: {
-        router: FSRouter;
+        router: StaticGenerationRouteSource;
         baseUrl: string;
-        routeRendererFactory?: RouteRendererFactory;
+        routeRendererFactory?: StaticGenerationRendererFactory;
         staticRoutes?: StaticRoute[];
     }): Promise<void>;
     /**
@@ -89,14 +87,10 @@ export declare class StaticSiteGenerator {
      * These routes use eco.page views via loader functions for HMR support.
      */
     private generateExplicitStaticPages;
-    /**
-     * Generate a single static page for a non-dynamic route.
-     */
-    private generateSingleStaticRoute;
-    /**
-     * Generate static pages for a dynamic route using staticPaths.
-     */
-    private generateDynamicStaticRoute;
+    private generateExplicitStaticRoute;
+    private planExplicitStaticRoute;
+    private createExplicitStaticContents;
+    private listExplicitStaticRouteEntries;
     /**
      * Resolve a route path template with actual params.
      * Supports both :param and [param] syntax.
@@ -107,3 +101,4 @@ export declare class StaticSiteGenerator {
      */
     private getOutputPath;
 }
+export {};