@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/services/module-loading/module-loading-types.d.ts

@@ -0,0 +1,2 @@
+export type SourceModuleLoader = (id: string) => Promise<unknown>;
+export type SourceModuleLoaderFactory = () => SourceModuleLoader | undefined;

package/src/services/module-loading/node-bootstrap-plugin.d.ts

@@ -0,0 +1,22 @@
+import type { EcoBuildOnResolveArgs, EcoBuildOnResolveResult, EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Returns the app-local node_modules directory used by framework-owned Node
+ * bootstrap loads outside the thin-host manifest path.
+ */
+export declare function getAppRuntimeNodeModulesDir(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>): string;
+export interface NodeBootstrapResolutionOptions {
+    projectDir: string;
+    runtimeNodeModulesDir: string;
+    preserveImportMetaPaths?: string[];
+}
+/**
+ * Builds the user-facing error for Bun-native imports that cannot run on the
+ * Node bootstrap transpile path.
+ */
+export declare function getNodeUnsupportedBuiltinError(specifier: string, importer?: string): string;
+export declare function resolveNodeBootstrapDependency(args: Pick<EcoBuildOnResolveArgs, 'path' | 'importer'>, options: NodeBootstrapResolutionOptions): EcoBuildOnResolveResult | undefined;
+export declare function createNodeBootstrapPlugin(options: NodeBootstrapResolutionOptions): EcoBuildPlugin;
+export declare function createAppNodeBootstrapPlugin(appConfig: Pick<EcoPagesAppConfig, 'rootDir' | 'workDir' | 'absolutePaths'>, options?: {
+    preserveImportMetaPaths?: string[];
+}): EcoBuildPlugin;

package/src/services/module-loading/node-bootstrap-plugin.js

@@ -0,0 +1,179 @@
+import path from "node:path";
+import { existsSync, mkdirSync, readFileSync, symlinkSync } from "node:fs";
+import { createRequire } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
+function getAppRuntimeNodeModulesDir(appConfig) {
+  return path.join(resolveInternalExecutionDir(appConfig), "node_modules");
+}
+function getPackageNameFromSpecifier(specifier) {
+  if (specifier.startsWith("@")) {
+    const [scope, name] = specifier.split("/");
+    return `${scope}/${name}`;
+  }
+  return specifier.split("/")[0] ?? specifier;
+}
+function findPackageRoot(resolvedPath) {
+  let currentPath = path.dirname(resolvedPath);
+  while (true) {
+    const packageJsonPath = path.join(currentPath, "package.json");
+    if (existsSync(packageJsonPath)) {
+      return currentPath;
+    }
+    const parentPath = path.dirname(currentPath);
+    if (parentPath === currentPath) {
+      throw new Error(`Could not find package root for resolved dependency path: ${resolvedPath}`);
+    }
+    currentPath = parentPath;
+  }
+}
+function ensureRuntimePackageLink(nodeModulesDir, specifier, resolvedPath) {
+  const packageName = getPackageNameFromSpecifier(specifier);
+  const packageRoot = findPackageRoot(resolvedPath);
+  const linkPath = path.join(nodeModulesDir, packageName);
+  if (existsSync(linkPath)) {
+    return;
+  }
+  mkdirSync(path.dirname(linkPath), { recursive: true });
+  symlinkSync(packageRoot, linkPath, "dir");
+}
+function getNodeUnsupportedBuiltinError(specifier, importer) {
+  return `Node bootstrap transpilation does not support Bun builtin specifier ${JSON.stringify(specifier)}${importer ? ` imported from ${importer}` : ""}.`;
+}
+function shouldResolveFromImporter(importer) {
+  return Boolean(importer && importer.includes(`${path.sep}node_modules${path.sep}`));
+}
+function resolveSpecifier(specifier, parentPath) {
+  try {
+    return createRequire(parentPath).resolve(specifier);
+  } catch {
+    return fileURLToPath(import.meta.resolve(specifier, pathToFileURL(parentPath).href));
+  }
+}
+function resolveFromCore(specifier) {
+  return createRequire(import.meta.url).resolve(specifier);
+}
+function getBootstrapBuildLoaderForPath(filePath) {
+  switch (path.extname(filePath).toLowerCase()) {
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "ts";
+    case ".tsx":
+      return "tsx";
+    case ".jsx":
+      return "jsx";
+    case ".json":
+      return "json";
+    default:
+      return "js";
+  }
+}
+const REEXPORT_FROM_STATEMENT_PATTERN = /^\s*export\s+(?!type\b)(?:\*|\{[\s\S]*?\})\s+from\s+(['"][^'"]+['"])\s*;?\s*$/gm;
+function injectBootstrapReexportImports(source) {
+  const sideEffectImports = [];
+  const importedSpecifiers = /* @__PURE__ */ new Set();
+  let importIndex = 0;
+  const rewrittenSource = source.replace(REEXPORT_FROM_STATEMENT_PATTERN, (statement, specifierLiteral) => {
+    if (!importedSpecifiers.has(specifierLiteral)) {
+      importedSpecifiers.add(specifierLiteral);
+      const importBinding = `__eco_bootstrap_reexport_${importIndex++}`;
+      sideEffectImports.push(`import * as ${importBinding} from ${specifierLiteral};`);
+      sideEffectImports.push(`void ${importBinding};`);
+    }
+    return statement;
+  });
+  if (sideEffectImports.length === 0) {
+    return source;
+  }
+  return `${sideEffectImports.join("\n")}
+${rewrittenSource}`;
+}
+function shouldRewriteBootstrapSource(filePath, projectDir) {
+  const normalizedPath = path.resolve(filePath);
+  const normalizedProjectDir = path.resolve(projectDir);
+  return normalizedPath.startsWith(`${normalizedProjectDir}${path.sep}`) && !normalizedPath.includes(`${path.sep}node_modules${path.sep}`);
+}
+function resolveNodeBootstrapDependency(args, options) {
+  if (args.path.startsWith("./") || args.path.startsWith("../") || args.path.startsWith("@/") || args.path.startsWith("/") || args.path.startsWith("node:")) {
+    return void 0;
+  }
+  const resolveParent = args.importer && path.isAbsolute(args.importer) && shouldResolveFromImporter(args.importer) ? args.importer : path.join(options.projectDir, "package.json");
+  if (args.path.startsWith("@ecopages/")) {
+    let resolvedPath2;
+    try {
+      resolvedPath2 = resolveFromCore(args.path);
+    } catch {
+      resolvedPath2 = resolveSpecifier(args.path, resolveParent);
+    }
+    if (resolvedPath2.includes(`${path.sep}node_modules${path.sep}`)) {
+      ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, resolvedPath2);
+      return {
+        path: args.path,
+        external: true
+      };
+    }
+    return { path: resolvedPath2 };
+  }
+  const resolvedPath = resolveSpecifier(args.path, resolveParent);
+  ensureRuntimePackageLink(options.runtimeNodeModulesDir, args.path, resolvedPath);
+  return {
+    path: args.path,
+    external: true
+  };
+}
+function createNodeBootstrapPlugin(options) {
+  const projectDir = path.resolve(options.projectDir);
+  const importMetaRewritePaths = new Set(
+    (options.preserveImportMetaPaths ?? []).map((filePath) => path.resolve(filePath))
+  );
+  return {
+    name: "node-bootstrap-plugin",
+    setup(build) {
+      build.onResolve({ filter: /^bun:/ }, (args) => {
+        throw new Error(getNodeUnsupportedBuiltinError(args.path, args.importer));
+      });
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (args) => {
+        const absolutePath = path.resolve(args.path);
+        const shouldPreserveImportMeta = importMetaRewritePaths.has(absolutePath);
+        const shouldRewriteReexports = shouldRewriteBootstrapSource(absolutePath, projectDir);
+        if (!shouldPreserveImportMeta && !shouldRewriteReexports) {
+          return void 0;
+        }
+        const originalContents = readFileSync(args.path, "utf8");
+        let contents = originalContents;
+        if (shouldPreserveImportMeta) {
+          contents = contents.replaceAll("import.meta.dirname", JSON.stringify(path.dirname(args.path))).replaceAll("import.meta.filename", JSON.stringify(args.path));
+        }
+        if (shouldRewriteReexports) {
+          contents = injectBootstrapReexportImports(contents);
+        }
+        if (contents === originalContents) {
+          return void 0;
+        }
+        return {
+          contents,
+          loader: getBootstrapBuildLoaderForPath(args.path),
+          resolveDir: path.dirname(args.path)
+        };
+      });
+      build.onResolve({ filter: /^[@A-Za-z0-9][^:]*$/ }, (args) => {
+        return resolveNodeBootstrapDependency(args, options);
+      });
+    }
+  };
+}
+function createAppNodeBootstrapPlugin(appConfig, options) {
+  return createNodeBootstrapPlugin({
+    projectDir: appConfig.rootDir,
+    runtimeNodeModulesDir: getAppRuntimeNodeModulesDir(appConfig),
+    preserveImportMetaPaths: options?.preserveImportMetaPaths
+  });
+}
+export {
+  createAppNodeBootstrapPlugin,
+  createNodeBootstrapPlugin,
+  getAppRuntimeNodeModulesDir,
+  getNodeUnsupportedBuiltinError,
+  resolveNodeBootstrapDependency
+};

package/src/services/module-loading/page-module-import.service.d.ts

@@ -0,0 +1,75 @@
+import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { SourceModuleLoaderFactory } from './module-loading-types.js';
+export interface PageModuleImportOptions {
+    filePath: string;
+    rootDir: string;
+    outdir: string;
+    bypassCache?: boolean;
+    buildExecutor?: BuildExecutor;
+    invalidationVersion?: number;
+    splitting?: boolean;
+    externalPackages?: boolean;
+    plugins?: EcoBuildPlugin[];
+    transpileErrorMessage?: (details: string) => string;
+    noOutputMessage?: (filePath: string) => string;
+}
+/**
+ * Minimal runtime dependencies required to load page modules.
+ *
+ * @remarks
+ * This service owns cache and runtime import policy. Hashing and build
+ * execution are injected so tests can provide explicit fakes without module
+ * interception.
+ */
+export interface PageModuleImportDependencies {
+    hashFile(filePath: string): string;
+    buildModule(options: Parameters<typeof build>[0], buildExecutor?: BuildExecutor): Promise<BuildResult>;
+    canLoadSourceModuleFromHost(filePath: string): boolean;
+    getHostModuleLoader: SourceModuleLoaderFactory;
+}
+/**
+ * Loads source page modules in a runtime-agnostic way.
+ *
+ * This service centralizes the Bun-vs-Node import strategy used by route
+ * scanning, page data loading, and request-time page inspection. In Bun it can
+ * import source files directly; in Node it transpiles the file into a dedicated
+ * output directory first and then imports the generated module.
+ *
+ * Keeping this logic in one place prevents subtle drift in cache-busting,
+ * transpilation settings, and error semantics across the different callers.
+ */
+export declare class PageModuleImportService {
+    private readonly dependencies;
+    private readonly importCache;
+    private developmentInvalidationVersion;
+    constructor(dependencies?: Partial<PageModuleImportDependencies>);
+    /**
+     * Clears the shared import cache used by framework-owned page-module loads.
+     */
+    clearImportCache(): void;
+    /**
+     * Invalidates all previously imported modules in development by clearing the
+     * import cache and incrementing the invalidation version included in cache keys.
+     *
+     * This forces all modules to be reloaded on the next import, even if their
+     * source content hasn't changed. This is necessary to ensure that changes to
+     * non-content aspects of modules (e.g. dependencies, transpilation output)
+     * are picked up during development.
+     */
+    invalidateDevelopmentGraph(): void;
+    /**
+     * Imports a page-like module from source.
+     *
+     * The caller controls the output directory and error wording so different
+     * subsystems can reuse the same loading mechanism while preserving their
+     * current diagnostics. Module identities stay stable for unchanged files and
+     * roll forward automatically when the source hash changes during watch mode.
+     *
+     * @typeParam T Expected module shape.
+     * @param options Runtime-specific import settings.
+     * @returns The loaded module.
+     */
+    importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
+    private loadModule;
+}

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

@@ -0,0 +1,161 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { fileSystem } from "@ecopages/file-system";
+import { build } from "../../build/build-adapter.js";
+class PageModuleImportService {
+  dependencies;
+  importCache = /* @__PURE__ */ new Map();
+  developmentInvalidationVersion = 0;
+  constructor(dependencies) {
+    this.dependencies = {
+      hashFile: dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath)),
+      buildModule: dependencies?.buildModule ?? ((options, buildExecutor) => build(options, buildExecutor)),
+      canLoadSourceModuleFromHost: dependencies?.canLoadSourceModuleFromHost ?? supportsHostSourceModuleLoading,
+      getHostModuleLoader: dependencies?.getHostModuleLoader ?? (() => void 0)
+    };
+  }
+  /**
+   * Clears the shared import cache used by framework-owned page-module loads.
+   */
+  clearImportCache() {
+    this.importCache.clear();
+  }
+  /**
+   * Invalidates all previously imported modules in development by clearing the
+   * import cache and incrementing the invalidation version included in cache keys.
+   *
+   * This forces all modules to be reloaded on the next import, even if their
+   * source content hasn't changed. This is necessary to ensure that changes to
+   * non-content aspects of modules (e.g. dependencies, transpilation output)
+   * are picked up during development.
+   */
+  invalidateDevelopmentGraph() {
+    this.clearImportCache();
+    this.developmentInvalidationVersion += 1;
+  }
+  /**
+   * Imports a page-like module from source.
+   *
+   * The caller controls the output directory and error wording so different
+   * subsystems can reuse the same loading mechanism while preserving their
+   * current diagnostics. Module identities stay stable for unchanged files and
+   * roll forward automatically when the source hash changes during watch mode.
+   *
+   * @typeParam T Expected module shape.
+   * @param options Runtime-specific import settings.
+   * @returns The loaded module.
+   */
+  async importModule(options) {
+    const { filePath, rootDir, externalPackages, splitting } = options;
+    const invalidationVersion = options.invalidationVersion ?? this.developmentInvalidationVersion;
+    const fileHash = this.dependencies.hashFile(filePath);
+    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);
+      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,
+      splitting ?? "default",
+      externalPackages ?? "default",
+      fileHash,
+      invalidationVersion
+    ].join("::");
+    const cachedModule = this.importCache.get(cacheKey);
+    if (cachedModule) {
+      return await cachedModule;
+    }
+    const importPromise = this.loadModule({
+      ...options,
+      fileHash
+    });
+    this.importCache.set(cacheKey, importPromise);
+    try {
+      return await importPromise;
+    } catch (error) {
+      this.importCache.delete(cacheKey);
+      throw error;
+    }
+  }
+  async loadModule(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
+    } = options;
+    const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion);
+    if (typeof Bun !== "undefined") {
+      return await import(
+        /* @vite-ignore */
+        sourceModuleUrl.href
+      );
+    }
+    const fileBaseName = path.basename(filePath, path.extname(filePath));
+    const outputFileName = `${fileBaseName}-${fileHash}.js`;
+    const buildResult = await this.dependencies.buildModule(
+      {
+        entrypoints: [filePath],
+        root: rootDir,
+        outdir,
+        target: "node",
+        format: "esm",
+        sourcemap: "none",
+        splitting: splitting ?? true,
+        minify: false,
+        naming: outputFileName,
+        externalPackages: true,
+        plugins: options.plugins,
+        ...externalPackages !== void 0 ? { externalPackages } : {}
+      },
+      options.buildExecutor
+    );
+    if (!buildResult.success) {
+      const details = buildResult.logs.map((log) => log.message).join(" | ");
+      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;
+    if (!compiledOutput) {
+      throw new Error(noOutputMessage(filePath));
+    }
+    const compiledOutputUrl = pathToFileURL(compiledOutput);
+    if (process.env.NODE_ENV === "development") {
+      compiledOutputUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
+    }
+    return await import(
+      /* @vite-ignore */
+      compiledOutputUrl.href
+    );
+  }
+}
+function createRuntimeModuleUrl(filePath, fileHash, invalidationVersion) {
+  const moduleUrl = pathToFileURL(filePath);
+  if (process.env.NODE_ENV === "development") {
+    moduleUrl.searchParams.set("update", `${fileHash}-${invalidationVersion}`);
+  }
+  return moduleUrl;
+}
+function supportsHostSourceModuleLoading(filePath) {
+  const extension = path.extname(filePath);
+  return extension === ".js" || extension === ".jsx" || extension === ".ts" || extension === ".tsx" || extension === ".mjs" || extension === ".mts" || extension === ".cjs" || extension === ".cts";
+}
+export {
+  PageModuleImportService
+};

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

@@ -0,0 +1,72 @@
+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';
+import type { SourceModuleLoaderFactory } from './module-loading-types.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;
+}
+/**
+ * Immutable execution context for one server-transpiler instance.
+ *
+ * @remarks
+ * Callers own when and why a new transpiler is created. This service only owns
+ * applying the supplied root/build-executor pair consistently to every module
+ * load that passes through it.
+ */
+export type ServerModuleTranspilerBootstrapArgs = {
+    rootDir: string;
+    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. */
+    getDefaultPlugins?: () => EcoBuildPlugin[];
+};
+/**
+ * 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 declare class ServerModuleTranspiler {
+    private readonly pageModuleImportService;
+    private readonly getRootDir;
+    private readonly getBuildExecutor;
+    private readonly getInvalidationVersion;
+    private readonly invalidateModules;
+    private readonly getDefaultPlugins;
+    /**
+     * Creates one explicit server-transpiler boundary for a given execution
+     * context.
+     */
+    constructor(args: ServerModuleTranspilerBootstrapArgs);
+    /**
+     * Loads a server-side source module through the caller-owned transpile
+     * context.
+     */
+    importModule<T = unknown>(options: ServerModuleTranspilerOptions): Promise<T>;
+    /**
+     * Invalidates cached module state for development reloads.
+     */
+    invalidate(changedFiles?: string[]): void;
+    /**
+     * 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.
+     */
+    dispose(): Promise<void>;
+}

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

@@ -0,0 +1,64 @@
+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({
+      canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
+      getHostModuleLoader: args.getHostModuleLoader
+    });
+    this.getRootDir = () => args.rootDir;
+    this.getBuildExecutor = args.getBuildExecutor;
+    this.getInvalidationVersion = () => args.getInvalidationVersion?.();
+    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(),
+      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
+};