@ecopages/core 0.2.0-alpha.52 → 0.2.0-alpha.54

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

@@ -1,95 +0,0 @@
-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';
-interface PageModuleImportBaseOptions {
-    filePath: string;
-    bypassCache?: boolean;
-    cacheScope?: string;
-    invalidationVersion?: number;
-}
-/**
- * Options for imports that must pass through the Ecopages build pipeline.
- *
- * @remarks
- * Callers should use build mode for framework-owned page modules and any other
- * source that relies on Ecopages build resolution before runtime execution.
- */
-export interface PageModuleBuildImportOptions extends PageModuleImportBaseOptions {
-    rootDir: string;
-    outdir: string;
-    buildExecutor?: BuildExecutor;
-    splitting?: boolean;
-    externalPackages?: boolean;
-    jsx?: {
-        development?: boolean;
-        factory?: string;
-        fragment?: string;
-        importSource?: string;
-        runtime?: 'classic' | 'automatic';
-        sideEffects?: 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 page-like modules through the Ecopages build pipeline.
- *
- * This service centralizes the shared build-first import strategy used by route
- * scanning, page data loading, and request-time page inspection. In Node
- * development it can still delegate compatible source imports to the active
- * host loader, but the public contract remains one transpile-targeted module
- * loading path.
- *
- * 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: PageModuleBuildImportOptions): Promise<T>;
-    private loadModule;
-}
-export {};

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

@@ -1,191 +0,0 @@
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { fileSystem } from "@ecopages/file-system";
-import { build } from "../../build/build-adapter.js";
-import { supportsSourceModuleLoading } from "./source-module-support.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 ?? supportsSourceModuleLoading,
-      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 } = options;
-    const invalidationVersion = options.invalidationVersion ?? this.developmentInvalidationVersion;
-    const { externalPackages, splitting } = options;
-    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, 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,
-      options.rootDir,
-      splitting ?? "default",
-      externalPackages ?? "default",
-      options.cacheScope ?? "default",
-      createJsxCacheKey(options.jsx),
-      createPluginCacheKey(options.plugins),
-      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, invalidationVersion = this.developmentInvalidationVersion, cacheScope, fileHash } = options;
-    const {
-      rootDir,
-      outdir,
-      splitting,
-      externalPackages,
-      transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
-      noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`
-    } = options;
-    const fileBaseName = path.basename(filePath, path.extname(filePath));
-    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: "es2022",
-        format: "esm",
-        sourcemap: "none",
-        splitting: splitting ?? true,
-        minify: false,
-        naming: outputNamingTemplate,
-        externalPackages: true,
-        jsx: options.jsx,
-        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) => /\.(?:[cm]?js)$/u.test(output.path))?.path;
-    if (!compiledOutput) {
-      throw new Error(noOutputMessage(filePath));
-    }
-    const compiledOutputUrl = pathToFileURL(compiledOutput);
-    if (shouldAddRuntimeUpdateQuery(invalidationVersion, cacheScope)) {
-      compiledOutputUrl.searchParams.set(
-        "update",
-        [fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : void 0].filter((value) => value !== void 0).join("-")
-      );
-    }
-    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,63 +0,0 @@
-import type { BuildExecutor } from '../../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../../build/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';
-export type ServerModuleTranspilerOptions = Omit<PageModuleBuildImportOptions, 'rootDir' | 'buildExecutor'>;
-export type ServerModuleImportDependency = Pick<AppModuleLoader, 'importModule' | 'invalidateDevelopmentGraph'>;
-/**
- * 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

@@ -1,64 +0,0 @@
-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 ?? (() => void 0);
-    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
-};

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

@@ -1,5 +0,0 @@
-/**
- * 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

@@ -1,8 +0,0 @@
-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,118 +0,0 @@
-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';
-/**
- * Tracks development-time dependency relationships and invalidation state for
- * one Ecopages app instance.
- *
- * @remarks
- * The current contract stays intentionally small. It supports today's needs for
- * server-module cache invalidation and entrypoint-to-dependency lookups without
- * forcing the rest of the runtime to know about one specific graph
- * implementation.
- */
-export interface DevGraphService extends ServerInvalidationState, EntrypointDependencyGraph {
-}
-/**
- * Minimal dev-graph implementation used when an app has no selective graph
- * metadata available.
- *
- * @remarks
- * This preserves correct behavior by using coarse invalidation version bumps.
- * Callers still pass changed-file information through the interface now so a
- * richer graph can become more selective later without changing call sites.
- */
-export declare class NoopDevGraphService implements DevGraphService {
-    private readonly invalidationState;
-    private readonly dependencyGraph;
-    /**
-     * Returns the current coarse invalidation version.
-     */
-    getServerInvalidationVersion(): number;
-    /**
-     * Invalidates all server-side module state by incrementing the shared version.
-     */
-    invalidateServerModules(changedFiles?: string[]): void;
-    /**
-     * Indicates that this graph cannot target invalidation to one entrypoint set.
-     */
-    supportsSelectiveInvalidation(): boolean;
-    /**
-     * Returns an empty entrypoint set because this implementation stores no
-     * dependency graph metadata.
-     */
-    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;
-    /**
-     * 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;
-    /**
-     * Resets graph-owned state for a fresh runtime cycle.
-     */
-    reset(): void;
-}
-/**
- * In-memory development graph with entrypoint-to-dependency reverse lookups.
- *
- * @remarks
- * This is the current selective graph implementation used by development flows
- * that need to answer which entrypoints depend on a changed file while still
- * keeping invalidation state app-local.
- */
-export declare class InMemoryDevGraphService implements DevGraphService {
-    private readonly invalidationState;
-    private readonly dependencyGraph;
-    /**
-     * Returns the current app-local server invalidation version.
-     */
-    getServerInvalidationVersion(): number;
-    /**
-     * Invalidates the current server-module cache generation.
-     *
-     * @remarks
-     * The current implementation still uses a coarse generation bump for server
-     * modules. Selective dependency lookups are used by callers that need to limit
-     * browser rebuild work.
-     */
-    invalidateServerModules(changedFiles?: string[]): void;
-    /**
-     * Indicates that this graph can answer dependency-to-entrypoint lookups.
-     */
-    supportsSelectiveInvalidation(): boolean;
-    /**
-     * Returns all known entrypoints that currently depend on the given file.
-     */
-    getDependencyEntrypoints(filePath: string): Set<string>;
-    /**
-     * Replaces the stored dependency set for one entrypoint.
-     *
-     * @remarks
-     * The entrypoint itself is always included in its own dependency set so reverse
-     * lookups can map a changed entry file back to that same entrypoint.
-     */
-    setEntrypointDependencies(entrypointPath: string, dependencies: string[]): void;
-    /**
-     * Removes one entrypoint and all of its reverse dependency edges.
-     */
-    clearEntrypointDependencies(entrypointPath: string): void;
-    /**
-     * Clears all graph state and starts a fresh invalidation generation.
-     */
-    reset(): void;
-}
-/**
- * Returns the dev-graph service owned by one app instance.
- */
-export declare function getAppDevGraphService(appConfig: EcoPagesAppConfig): DevGraphService;
-/**
- * Installs the dev-graph service that should back one app/runtime instance.
- */
-export declare function setAppDevGraphService(appConfig: EcoPagesAppConfig, devGraphService: DevGraphService): void;