@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.40

package/src/router/server/route-registry.js

@@ -0,0 +1,262 @@
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { fileSystem } from "@ecopages/file-system";
+import { appLogger } from "../../global/app-logger.js";
+import { invariant } from "../../utils/invariant.js";
+const ROUTE_PRIORITY = {
+  exact: 0,
+  dynamic: 1,
+  "catch-all": 2
+};
+class RouteRegistry {
+  origin;
+  appConfig;
+  pagesDir;
+  templatesExt;
+  buildMode;
+  pageModuleAdapter;
+  templateRouteList = [];
+  reloadListeners = /* @__PURE__ */ new Set();
+  constructor(options) {
+    this.origin = options.origin;
+    this.appConfig = options.appConfig;
+    this.pagesDir = options.pagesDir;
+    this.templatesExt = options.templatesExt;
+    this.buildMode = options.buildMode;
+    this.pageModuleAdapter = options.pageModuleAdapter;
+  }
+  get templateRoutes() {
+    return this.templateRouteList;
+  }
+  async init() {
+    this.templateRouteList = await this.scanTemplateRoutes();
+    appLogger.debug("RouteRegistry initialized", this.templateRouteList);
+  }
+  async reload() {
+    await this.init();
+    for (const listener of this.reloadListeners) {
+      listener();
+    }
+  }
+  onReload(listener) {
+    this.reloadListeners.add(listener);
+    return () => {
+      this.reloadListeners.delete(listener);
+    };
+  }
+  matchRequest(requestUrl) {
+    const url = new URL(requestUrl);
+    const requestedPathname = normalizePathname(url.pathname);
+    const query = this.getSearchParams(url);
+    for (const route of this.templateRouteList) {
+      if (route.kind !== "exact") {
+        continue;
+      }
+      if (requestedPathname === route.pathname || requestedPathname === `${route.pathname}/`) {
+        return {
+          requestedPathname,
+          templateRoute: route,
+          params: {},
+          query
+        };
+      }
+    }
+    for (const route of this.templateRouteList) {
+      if (route.kind !== "dynamic") {
+        continue;
+      }
+      const params = this.tryExtractParams(route, requestedPathname);
+      if (!params) {
+        continue;
+      }
+      return {
+        requestedPathname,
+        templateRoute: route,
+        params,
+        query
+      };
+    }
+    for (const route of this.templateRouteList) {
+      if (route.kind !== "catch-all") {
+        continue;
+      }
+      const params = this.tryExtractParams(route, requestedPathname);
+      if (!params) {
+        continue;
+      }
+      return {
+        requestedPathname,
+        templateRoute: route,
+        params,
+        query
+      };
+    }
+    return null;
+  }
+  async listStaticPathExpansions(input) {
+    const expansions = [];
+    for (const route of this.templateRouteList) {
+      if (route.kind === "exact") {
+        continue;
+      }
+      const pageModule = await this.pageModuleAdapter.loadPageModule(route.filePath);
+      const staticPaths = pageModule.staticPaths;
+      if (this.buildMode) {
+        invariant(staticPaths !== void 0, `[ecopages] Missing getStaticPaths in ${route.filePath}`);
+        invariant(
+          pageModule.staticProps !== void 0,
+          `[ecopages] Missing getStaticProps in ${route.filePath}`
+        );
+      }
+      if (!staticPaths) {
+        continue;
+      }
+      const result = await staticPaths({
+        appConfig: this.appConfig,
+        runtimeOrigin: input.runtimeOrigin
+      });
+      for (const { params } of result.paths) {
+        expansions.push({
+          pathname: this.resolveTemplatePath(route.pathname, params),
+          templateRoute: route,
+          params
+        });
+      }
+    }
+    return expansions;
+  }
+  async listStaticGenerationRoutes(input) {
+    const staticPathExpansions = await this.listStaticPathExpansions(input);
+    return [
+      ...this.templateRouteList.filter((route) => route.kind === "exact").map((route) => ({
+        requestUrl: `${input.runtimeOrigin}${route.pathname}`,
+        pathname: route.pathname,
+        templateRoute: route,
+        params: {}
+      })),
+      ...staticPathExpansions.map((route) => ({
+        requestUrl: `${input.runtimeOrigin}${route.pathname}`,
+        pathname: route.pathname,
+        templateRoute: route.templateRoute,
+        params: route.params
+      }))
+    ];
+  }
+  async scanTemplateRoutes() {
+    if (!existsSync(this.pagesDir)) {
+      return [];
+    }
+    const scannedFiles = await fileSystem.glob(
+      this.templatesExt.map((ext) => `**/*${ext}`),
+      {
+        cwd: this.pagesDir
+      }
+    );
+    const templateRoutes = [];
+    for await (const file of scannedFiles) {
+      if (file.includes(".ecopages-node.")) {
+        continue;
+      }
+      const routePathname = this.getRoutePath(file);
+      const filePath = path.join(this.pagesDir, file);
+      const kind = this.classifyRouteKind(filePath);
+      templateRoutes.push({
+        pathname: routePathname,
+        kind,
+        filePath,
+        paramNames: this.getParamNames(routePathname)
+      });
+    }
+    return templateRoutes.sort((left, right) => {
+      const priorityDifference = ROUTE_PRIORITY[left.kind] - ROUTE_PRIORITY[right.kind];
+      if (priorityDifference !== 0) {
+        return priorityDifference;
+      }
+      if (left.pathname === "/") {
+        return -1;
+      }
+      if (right.pathname === "/") {
+        return 1;
+      }
+      return left.pathname.localeCompare(right.pathname);
+    });
+  }
+  getRoutePath(file) {
+    const cleanedRoute = this.templatesExt.reduce((route, ext) => route.replace(ext, ""), file).replace(/\/?index$/, "");
+    return normalizePathname(`/${cleanedRoute}`);
+  }
+  classifyRouteKind(filePath) {
+    if (filePath.includes("[...")) {
+      return "catch-all";
+    }
+    if (filePath.includes("[") && filePath.includes("]")) {
+      return "dynamic";
+    }
+    return "exact";
+  }
+  getParamNames(routePathname) {
+    const matches = routePathname.match(/\[(?:\.\.\.)?([^\]]+)\]/g);
+    return matches ? matches.map((match) => match.replace(/^\[(?:\.\.\.)?/, "").replace(/\]$/, "")) : [];
+  }
+  tryExtractParams(route, requestedPathname) {
+    const routeParts = route.pathname.split("/");
+    const pathnameParts = requestedPathname.split("/");
+    if (route.kind === "dynamic" && routeParts.length !== pathnameParts.length) {
+      return null;
+    }
+    const params = {};
+    for (let i = 0; i < routeParts.length; i++) {
+      const routePart = routeParts[i];
+      const pathnamePart = pathnameParts[i];
+      if (!routePart) {
+        continue;
+      }
+      if (routePart.startsWith("[...") && routePart.endsWith("]")) {
+        const paramName = routePart.slice(4, -1);
+        params[paramName] = pathnameParts.slice(i).filter(Boolean);
+        return params;
+      }
+      if (routePart.startsWith("[") && routePart.endsWith("]")) {
+        if (pathnamePart === void 0) {
+          return null;
+        }
+        params[routePart.slice(1, -1)] = pathnamePart;
+        continue;
+      }
+      if (routePart !== pathnamePart) {
+        return null;
+      }
+    }
+    if (route.kind === "catch-all") {
+      const cleanPathname = route.pathname.replace(/\[.*?\]/g, "");
+      return requestedPathname.includes(cleanPathname) ? params : null;
+    }
+    return params;
+  }
+  getSearchParams(url) {
+    const query = {};
+    for (const [key, value] of url.searchParams) {
+      query[key] = value;
+    }
+    return query;
+  }
+  resolveTemplatePath(pathname, params) {
+    let resolvedPath = pathname;
+    for (const [key, value] of Object.entries(params)) {
+      const serializedValue = Array.isArray(value) ? value.join("/") : value;
+      resolvedPath = resolvedPath.replace(`[...${key}]`, serializedValue);
+      resolvedPath = resolvedPath.replace(`[${key}]`, serializedValue);
+    }
+    return normalizePathname(resolvedPath);
+  }
+}
+function normalizePathname(pathname) {
+  if (!pathname || pathname === "/") {
+    return "/";
+  }
+  const normalized = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  return normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+}
+export {
+  RouteRegistry
+};

package/src/services/README.md

@@ -0,0 +1,28 @@
+# Core Services
+
+This directory contains the app-owned service layer used by runtime startup, rendering, asset processing, browser bundling, and development invalidation.
+
+## Purpose
+
+Services in this directory exist to keep cross-cutting framework logic out of adapters, integrations, and processors.
+
+Typical responsibilities include:
+
+- server-module loading and transpilation
+- browser bundle coordination
+- asset processing and runtime asset declaration helpers
+- server invalidation state and entrypoint dependency graphs
+- HTML finalization and dependency injection
+
+## Main Areas
+
+- `module-loading/`: framework-owned config/app bootstrap loading and server-side source loading
+- `assets/`: shared browser build coordination and processed asset pipelines
+- `invalidation/`: file-change classification and invalidation policy
+- `runtime-state/`: app-owned invalidation state and dependency graphs
+- `runtime-manifest/`: node runtime manifest derivation and persistence
+- `html/`: final HTML dependency injection and rewriter selection
+
+## Design Rule
+
+If a concern affects more than one integration or more than one runtime adapter, it usually belongs here instead of in a package-specific implementation.

package/src/services/assets/asset-processing-service/asset-dependency-keys.d.ts

@@ -0,0 +1,3 @@
+import type { AssetDefinition } from './assets.types.js';
+export declare function getAssetDependencyKey(dep: AssetDefinition): string;
+export declare function deduplicateAssetDependencies(deps: AssetDefinition[]): AssetDefinition[];

package/src/services/assets/asset-processing-service/asset-dependency-keys.js

@@ -0,0 +1,56 @@
+import { rapidhash } from "../../../utils/hash.js";
+function generateHash(content) {
+  return rapidhash(content).toString();
+}
+function getScriptDependencyBuildSignature(dep) {
+  if (dep.kind !== "script") {
+    return void 0;
+  }
+  const pluginNames = dep.bundleOptions?.plugins?.map((plugin) => plugin.name) ?? [];
+  const signature = {
+    bundle: dep.bundle,
+    inline: dep.inline,
+    excludeFromHtml: dep.excludeFromHtml,
+    groupedBundle: dep.groupedBundle,
+    naming: dep.bundleOptions?.naming,
+    external: dep.bundleOptions?.external,
+    minify: dep.bundleOptions?.minify,
+    plugins: pluginNames
+  };
+  return generateHash(JSON.stringify(signature));
+}
+function getAssetDependencyKey(dep) {
+  const parts = [dep.kind, dep.source];
+  if ("filepath" in dep) {
+    parts.push(dep.filepath);
+  } else if ("content" in dep) {
+    parts.push(`content:${generateHash(dep.content)}`);
+  } else if ("importPath" in dep) {
+    parts.push(dep.importPath);
+  }
+  if ("position" in dep && dep.position) {
+    parts.push(dep.position);
+  }
+  if ("packageRole" in dep && dep.packageRole) {
+    parts.push(`package:${dep.packageRole}`);
+  }
+  const scriptBuildSignature = getScriptDependencyBuildSignature(dep);
+  if (scriptBuildSignature) {
+    parts.push(`build:${scriptBuildSignature}`);
+  }
+  return parts.join(":");
+}
+function deduplicateAssetDependencies(deps) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const dep of deps) {
+    const key = getAssetDependencyKey(dep);
+    if (!seen.has(key)) {
+      seen.set(key, dep);
+    }
+  }
+  return Array.from(seen.values());
+}
+export {
+  deduplicateAssetDependencies,
+  getAssetDependencyKey
+};

package/src/services/assets/asset-processing-service/asset-processing.service.d.ts

@@ -0,0 +1,103 @@
+import type { EcoPagesAppConfig, IHmrManager } from '../../../types/internal-types.js';
+import type { AssetDefinition, AssetKind, AssetSource, ProcessedAsset } from './assets.types.js';
+import { ProcessorRegistry } from './processor.registry.js';
+/**
+ * Processes declared component and page asset dependencies for one app instance.
+ *
+ * @remarks
+ * This service is the shared bridge between dependency declarations and emitted
+ * runtime-ready assets. It owns deduplication, processor dispatch, cache reuse,
+ * output URL normalization, and production gzip preparation so route rendering
+ * and HMR flows do not need to understand processor-specific behavior.
+ */
+export declare class AssetProcessingService {
+    static readonly RESOLVED_ASSETS_DIR = "assets";
+    private registry;
+    private hmrManager?;
+    private cache;
+    private readonly config;
+    /**
+     * Creates the asset-processing service bound to one finalized app config.
+     */
+    constructor(config: EcoPagesAppConfig);
+    /**
+     * Set the HMR manager for the asset processing service.
+     * @param hmrManager The HMR manager to set.
+     */
+    setHmrManager(hmrManager: IHmrManager): void;
+    getHmrManager(): IHmrManager | undefined;
+    /**
+     * Register a processor for a specific asset kind and source.
+     * @param kind The asset kind.
+     * @param variant The asset source.
+     * @param processor The processor to register.
+     */
+    registerProcessor(kind: AssetKind, variant: AssetSource, processor: any): void;
+    /**
+     * Processes one dependency list into normalized emitted assets.
+     *
+     * @remarks
+     * Dependencies are deduplicated before processor execution so repeated
+     * declarations across the render tree reuse the same emitted outputs and cache
+     * entries.
+     */
+    processDependencies(deps: AssetDefinition[], key: string): Promise<ProcessedAsset[]>;
+    /**
+     * Processes deduplicated dependencies grouped by processor type.
+     *
+     * @remarks
+     * Grouping keeps cache and processor behavior isolated by asset kind/source
+     * pair, while still allowing the overall dependency set to resolve in
+     * parallel.
+     */
+    private processDependenciesParallel;
+    /**
+     * Groups dependencies by processor bucket.
+     */
+    private groupDependenciesByType;
+    /**
+     * Converts a dist-local file path into its public URL.
+     */
+    private getSrcUrl;
+    /**
+     * Normalizes the public source URL for one processed asset.
+     */
+    private resolveProcessedAssetSrcUrl;
+    /**
+     * Returns whether a value should be interpreted as a filesystem path instead
+     * of an already-public URL.
+     */
+    private isFilesystemPath;
+    /**
+     * Applies post-processing for emitted production assets.
+     *
+     * @remarks
+     * Current optimization is intentionally conservative: only generated CSS and
+     * JavaScript files inside the app dist directory are gzipped.
+     */
+    private optimizeDependencies;
+    /**
+     * Returns the cached processed asset for a dependency key when available.
+     */
+    private getCachedAsset;
+    /**
+     * Stores one processed asset in the dependency cache.
+     */
+    private setCachedAsset;
+    /**
+     * Clears all cached processed assets.
+     */
+    clearCache(): void;
+    /**
+     * Removes cached assets that were produced from the given file path.
+     */
+    invalidateCacheForFile(filepath: string): void;
+    /**
+     * Creates a service prewired with the default core processors.
+     */
+    static createWithDefaultProcessors(appConfig: EcoPagesAppConfig): AssetProcessingService;
+    /**
+     * Returns the processor registry owned by this service.
+     */
+    getRegistry(): ProcessorRegistry;
+}