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

package/src/services/module-loading/route-module-dependency-hasher.js

@@ -1,121 +1,148 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-class RouteModuleDependencyHasher {
-  memo = /* @__PURE__ */ new Map();
-  hashFile;
-  exists;
-  constructor(dependencies) {
-    this.hashFile = dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath));
-    this.exists = dependencies?.exists ?? ((filePath) => fileSystem.exists(filePath));
-  }
-  /**
-   * Returns a memoized content hash for one trackable dependency path.
-   *
-   * @param filePath - Absolute or project-relative source path.
-   * @returns The content hash, or `undefined` when the path is not trackable or missing.
-   */
-  hashDependency(filePath) {
-    const normalizedPath = path.normalize(filePath);
-    if (!isTrackableRouteModuleDependency(normalizedPath)) {
-      return void 0;
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+/**
+ * Lazily hashes route-module dependency files while memoizing results for one build run.
+ *
+ * @remarks
+ * Multiple route modules often share layouts or utilities. Memoizing per path avoids
+ * re-reading the same dependency file while validating or recording many cache entries
+ * during one production build.
+ */
+export class RouteModuleDependencyHasher {
+    memo = new Map();
+    hashFile;
+    exists;
+    constructor(dependencies) {
+        this.hashFile = dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath));
+        this.exists = dependencies?.exists ?? ((filePath) => fileSystem.exists(filePath));
     }
-    if (!this.exists(normalizedPath)) {
-      return void 0;
+    /**
+     * Returns a memoized content hash for one trackable dependency path.
+     *
+     * @param filePath - Absolute or project-relative source path.
+     * @returns The content hash, or `undefined` when the path is not trackable or missing.
+     */
+    hashDependency(filePath) {
+        const normalizedPath = path.normalize(filePath);
+        if (!isTrackableRouteModuleDependency(normalizedPath)) {
+            return undefined;
+        }
+        if (!this.exists(normalizedPath)) {
+            return undefined;
+        }
+        const cachedHash = this.memo.get(normalizedPath);
+        if (cachedHash) {
+            return cachedHash;
+        }
+        const nextHash = this.hashFile(normalizedPath);
+        this.memo.set(normalizedPath, nextHash);
+        return nextHash;
     }
-    const cachedHash = this.memo.get(normalizedPath);
-    if (cachedHash) {
-      return cachedHash;
+    /**
+     * Builds the dependency-hash map for one route entrypoint graph.
+     *
+     * @param modulePaths - Raw module ids from the bundler dependency graph.
+     * @returns Hashes for every trackable, existing source file in the graph.
+     */
+    createDependencyHashes(modulePaths) {
+        const dependencyHashes = {};
+        for (const modulePath of filterTrackableRouteModuleDependencies(modulePaths)) {
+            const dependencyHash = this.hashDependency(modulePath);
+            if (dependencyHash) {
+                dependencyHashes[modulePath] = dependencyHash;
+            }
+        }
+        return dependencyHashes;
     }
-    const nextHash = this.hashFile(normalizedPath);
-    this.memo.set(normalizedPath, nextHash);
-    return nextHash;
-  }
-  /**
-   * Builds the dependency-hash map for one route entrypoint graph.
-   *
-   * @param modulePaths - Raw module ids from the bundler dependency graph.
-   * @returns Hashes for every trackable, existing source file in the graph.
-   */
-  createDependencyHashes(modulePaths) {
-    const dependencyHashes = {};
-    for (const modulePath of filterTrackableRouteModuleDependencies(modulePaths)) {
-      const dependencyHash = this.hashDependency(modulePath);
-      if (dependencyHash) {
-        dependencyHashes[modulePath] = dependencyHash;
-      }
+    /**
+     * Returns whether every stored dependency hash still matches the current file contents.
+     *
+     * @param storedHashes - Dependency hashes previously persisted for one route module.
+     * @param entrypointPath - Route entry file whose hash is validated separately.
+     * @param entrypointSourceHash - Already-validated content hash for {@link entrypointPath}.
+     * @returns `true` when all stored hashes are present and still valid.
+     */
+    matchesStoredHashes(storedHashes, entrypointPath, entrypointSourceHash) {
+        this.clearMemo();
+        if (!storedHashes || Object.keys(storedHashes).length === 0) {
+            return false;
+        }
+        const normalizedEntrypoint = entrypointPath ? path.normalize(entrypointPath) : undefined;
+        for (const [dependencyPath, storedHash] of Object.entries(storedHashes)) {
+            if (normalizedEntrypoint && path.normalize(dependencyPath) === normalizedEntrypoint) {
+                if (entrypointSourceHash && storedHash !== entrypointSourceHash) {
+                    return false;
+                }
+                continue;
+            }
+            const currentHash = this.hashDependency(dependencyPath);
+            if (!currentHash || currentHash !== storedHash) {
+                return false;
+            }
+        }
+        return true;
     }
-    return dependencyHashes;
-  }
-  /**
-   * Returns whether every stored dependency hash still matches the current file contents.
-   *
-   * @param storedHashes - Dependency hashes previously persisted for one route module.
-   * @param entrypointPath - Route entry file whose hash is validated separately.
-   * @param entrypointSourceHash - Already-validated content hash for {@link entrypointPath}.
-   * @returns `true` when all stored hashes are present and still valid.
-   */
-  matchesStoredHashes(storedHashes, entrypointPath, entrypointSourceHash) {
-    if (!storedHashes || Object.keys(storedHashes).length === 0) {
-      return false;
+    /** Clears the per-build memo so subsequent reads reflect current file contents. */
+    clearMemo() {
+        this.memo.clear();
     }
-    const normalizedEntrypoint = entrypointPath ? path.normalize(entrypointPath) : void 0;
-    for (const [dependencyPath, storedHash] of Object.entries(storedHashes)) {
-      if (normalizedEntrypoint && path.normalize(dependencyPath) === normalizedEntrypoint) {
-        if (entrypointSourceHash && storedHash !== entrypointSourceHash) {
-          return false;
-        }
-        continue;
-      }
-      const currentHash = this.hashDependency(dependencyPath);
-      if (!currentHash || currentHash !== storedHash) {
+}
+/**
+ * Returns whether a bundler module id should participate in route-module cache invalidation.
+ *
+ * @remarks
+ * Builtins and installed packages are excluded. Their changes are expected to be
+ * reflected through framework-level invalidation instead of per-route file hashing.
+ */
+export function isTrackableRouteModuleDependency(modulePath) {
+    const normalizedPath = path.normalize(modulePath);
+    if (normalizedPath.startsWith('node:')) {
         return false;
-      }
     }
-    return true;
-  }
-  /** Clears the per-build memo. Intended for unit tests only. */
-  clearMemoForTests() {
-    this.memo.clear();
-  }
-}
-function isTrackableRouteModuleDependency(modulePath) {
-  const normalizedPath = path.normalize(modulePath);
-  if (normalizedPath.startsWith("node:")) {
-    return false;
-  }
-  if (normalizedPath.includes(`${path.sep}node_modules${path.sep}`)) {
-    return false;
-  }
-  return /\.(?:[cm]?[jt]sx?|mdx)$/iu.test(normalizedPath) || normalizedPath.endsWith(".json");
+    if (normalizedPath.includes(`${path.sep}node_modules${path.sep}`)) {
+        return false;
+    }
+    return /\.(?:[cm]?[jt]sx?|mdx)$/iu.test(normalizedPath) || normalizedPath.endsWith('.json');
 }
-function filterTrackableRouteModuleDependencies(modulePaths) {
-  const uniquePaths = /* @__PURE__ */ new Set();
-  for (const modulePath of modulePaths) {
-    const normalizedPath = path.normalize(modulePath);
-    if (isTrackableRouteModuleDependency(normalizedPath)) {
-      uniquePaths.add(normalizedPath);
+/**
+ * Filters a bundler module list down to trackable app-owned source files.
+ */
+export function filterTrackableRouteModuleDependencies(modulePaths) {
+    const uniquePaths = new Set();
+    for (const modulePath of modulePaths) {
+        const normalizedPath = path.normalize(modulePath);
+        if (isTrackableRouteModuleDependency(normalizedPath)) {
+            uniquePaths.add(normalizedPath);
+        }
     }
-  }
-  return Array.from(uniquePaths).sort();
+    return Array.from(uniquePaths).sort();
 }
-function resolveRouteModuleDependencyPaths(buildResult, entrypointPath, rootDir) {
-  const normalizedEntrypoint = path.isAbsolute(entrypointPath) ? path.normalize(entrypointPath) : path.normalize(path.resolve(rootDir, entrypointPath));
-  const graphEntrypoints = buildResult.dependencyGraph?.entrypoints ?? {};
-  const dependencyPaths = graphEntrypoints[normalizedEntrypoint] ?? graphEntrypoints[entrypointPath] ?? Object.entries(graphEntrypoints).find(([candidate]) => path.normalize(candidate) === normalizedEntrypoint)?.[1];
-  if (!dependencyPaths || dependencyPaths.length === 0) {
-    return [normalizedEntrypoint];
-  }
-  return dependencyPaths.map(
-    (dependencyPath) => path.isAbsolute(dependencyPath) ? path.normalize(dependencyPath) : path.normalize(path.resolve(rootDir, dependencyPath))
-  );
+/**
+ * Resolves the dependency module list for one route entrypoint from a build result.
+ *
+ * @param buildResult - Completed route-module build output.
+ * @param entrypointPath - Absolute or root-relative route source path used as the build entry.
+ * @param rootDir - Project root used to normalize relative module ids.
+ * @returns Normalized module paths, falling back to the entrypoint when no graph is available.
+ */
+export function resolveRouteModuleDependencyPaths(buildResult, entrypointPath, rootDir) {
+    const normalizedEntrypoint = path.isAbsolute(entrypointPath)
+        ? path.normalize(entrypointPath)
+        : path.normalize(path.resolve(rootDir, entrypointPath));
+    const graphEntrypoints = buildResult.dependencyGraph?.entrypoints ?? {};
+    const dependencyPaths = graphEntrypoints[normalizedEntrypoint] ??
+        graphEntrypoints[entrypointPath] ??
+        Object.entries(graphEntrypoints).find(([candidate]) => path.normalize(candidate) === normalizedEntrypoint)?.[1];
+    if (!dependencyPaths || dependencyPaths.length === 0) {
+        return [normalizedEntrypoint];
+    }
+    return dependencyPaths.map((dependencyPath) => path.isAbsolute(dependencyPath)
+        ? path.normalize(dependencyPath)
+        : path.normalize(path.resolve(rootDir, dependencyPath)));
 }
-function createRouteModuleDependencyHashes(hasher, buildResult, entrypointPath, rootDir) {
-  return hasher.createDependencyHashes(resolveRouteModuleDependencyPaths(buildResult, entrypointPath, rootDir));
+/**
+ * Convenience helper that combines graph extraction and dependency hashing.
+ */
+export function createRouteModuleDependencyHashes(hasher, buildResult, entrypointPath, rootDir) {
+    return hasher.createDependencyHashes(resolveRouteModuleDependencyPaths(buildResult, entrypointPath, rootDir));
 }
-export {
-  RouteModuleDependencyHasher,
-  createRouteModuleDependencyHashes,
-  filterTrackableRouteModuleDependencies,
-  isTrackableRouteModuleDependency,
-  resolveRouteModuleDependencyPaths
-};

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

@@ -1,5 +1,5 @@
 import type { BuildExecutor } from '../../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
 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';
@@ -18,7 +18,6 @@ export type ServerModuleTranspilerBootstrapArgs = {
     getBuildExecutor?: () => BuildExecutor | undefined;
     canLoadSourceModuleFromHost?: (filePath: string) => boolean;
     getHostModuleLoader?: SourceModuleLoaderFactory;
-    getInvalidationVersion?: () => number;
     invalidateModules?: (changedFiles?: string[]) => void;
     pageModuleImportService?: ServerModuleImportDependency;
     /** Factory evaluated on each importModule call to produce plugins applied to every load. */
@@ -35,7 +34,6 @@ export declare class ServerModuleTranspiler {
     private readonly pageModuleImportService;
     private readonly getRootDir;
     private readonly getBuildExecutor;
-    private readonly getInvalidationVersion;
     private readonly invalidateModules;
     private readonly getDefaultPlugins;
     /**

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

@@ -1,64 +1,67 @@
-import { PageModuleImportService } from "./page-module-import.service.js";
-class ServerModuleTranspiler {
-  pageModuleImportService;
-  getRootDir;
-  getBuildExecutor;
-  getInvalidationVersion;
-  invalidateModules;
-  getDefaultPlugins;
-  /**
-   * Creates one explicit server-transpiler boundary for a given execution
-   * context.
-   */
-  constructor(args) {
-    this.pageModuleImportService = args.pageModuleImportService ?? new PageModuleImportService(void 0, {
-      canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
-      getHostModuleLoader: args.getHostModuleLoader
-    });
-    this.getRootDir = () => args.rootDir;
-    this.getBuildExecutor = args.getBuildExecutor ?? (() => void 0);
-    this.getInvalidationVersion = () => args.getInvalidationVersion?.();
-    this.getDefaultPlugins = args.getDefaultPlugins ?? (() => []);
-    this.invalidateModules = (changedFiles) => {
-      if (args.invalidateModules) {
-        args.invalidateModules(changedFiles);
+import { PageModuleImportService } from './page-module-import.service.js';
+/**
+ * App-owned boundary for server-side source module loading.
+ *
+ * @remarks
+ * This service centralizes server-side module transpilation and import behind
+ * an explicit caller-owned root and build executor.
+ */
+export class ServerModuleTranspiler {
+    pageModuleImportService;
+    getRootDir;
+    getBuildExecutor;
+    invalidateModules;
+    getDefaultPlugins;
+    /**
+     * Creates one explicit server-transpiler boundary for a given execution
+     * context.
+     */
+    constructor(args) {
+        this.pageModuleImportService =
+            args.pageModuleImportService ??
+                new PageModuleImportService(undefined, {
+                    canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
+                    getHostModuleLoader: args.getHostModuleLoader,
+                });
+        this.getRootDir = () => args.rootDir;
+        this.getBuildExecutor = args.getBuildExecutor ?? (() => undefined);
+        this.getDefaultPlugins = args.getDefaultPlugins ?? (() => []);
+        this.invalidateModules = (changedFiles) => {
+            if (args.invalidateModules) {
+                args.invalidateModules(changedFiles);
+                return;
+            }
+            this.pageModuleImportService.invalidateDevelopmentGraph();
+        };
+    }
+    /**
+     * Loads a server-side source module through the caller-owned transpile
+     * context.
+     */
+    async importModule(options) {
+        const mergedPlugins = [...this.getDefaultPlugins(), ...(options.plugins ?? [])];
+        const { plugins: _plugins, ...baseOptions } = options;
+        return await this.pageModuleImportService.importModule({
+            ...baseOptions,
+            ...(mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {}),
+            rootDir: this.getRootDir(),
+            buildExecutor: this.getBuildExecutor(),
+        });
+    }
+    /**
+     * Invalidates cached module state for development reloads.
+     */
+    invalidate(changedFiles) {
+        this.invalidateModules(changedFiles);
+    }
+    /**
+     * Releases transpiler-owned resources.
+     *
+     * @remarks
+     * The current implementation delegates cache ownership to lower-level module
+     * loading services, so disposal is intentionally a no-op for now.
+     */
+    async dispose() {
         return;
-      }
-      this.pageModuleImportService.invalidateDevelopmentGraph();
-    };
-  }
-  /**
-   * Loads a server-side source module through the caller-owned transpile
-   * context.
-   */
-  async importModule(options) {
-    const mergedPlugins = [...this.getDefaultPlugins(), ...options.plugins ?? []];
-    const { plugins: _plugins, ...baseOptions } = options;
-    return await this.pageModuleImportService.importModule({
-      ...baseOptions,
-      ...mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {},
-      rootDir: this.getRootDir(),
-      buildExecutor: this.getBuildExecutor(),
-      invalidationVersion: this.getInvalidationVersion()
-    });
-  }
-  /**
-   * Invalidates cached module state for development reloads.
-   */
-  invalidate(changedFiles) {
-    this.invalidateModules(changedFiles);
-  }
-  /**
-   * Releases transpiler-owned resources.
-   *
-   * @remarks
-   * The current implementation delegates cache ownership to lower-level module
-   * loading services, so disposal is intentionally a no-op for now.
-   */
-  async dispose() {
-    return;
-  }
+    }
 }
-export {
-  ServerModuleTranspiler
-};

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

@@ -1,8 +1,16 @@
-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";
+import path from 'node:path';
+/**
+ * Returns whether a source module can be loaded directly by the host runtime without
+ * first going through the transpile/import pipeline.
+ */
+export 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
-};