npm - @ecopages/core - Versions diffs - 0.2.0-alpha.27 → 0.2.0-alpha.28 - Mend

@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (546) hide show

package/src/services/html/html-transformer.service.d.ts ADDED Viewed

@@ -0,0 +1,87 @@
+import type { ProcessedAsset } from '../assets/asset-processing-service/assets.types.js';
+import type { PagePackageResult } from '../../types/public-types.js';
+import { type HtmlRewriterMode, type HtmlRewriterProvider } from './html-rewriter-provider.service.js';
+export interface HtmlTransformerServiceOptions {
+    htmlRewriterMode?: HtmlRewriterMode;
+    htmlRewriterProvider?: HtmlRewriterProvider;
+}
+export declare class HtmlTransformerService {
+    private processedDependencies;
+    private pagePackage?;
+    private htmlRewriterProvider;
+    constructor(options?: HtmlTransformerServiceOptions);
+    /**
+     * Overrides the HTML rewriter runtime selection.
+     *
+     * This is intended for internal/runtime tests that need deterministic
+     * selection between native, worker-tools, and string fallback behavior.
+     *
+     * @param mode Requested runtime selection strategy.
+     */
+    setHtmlRewriterMode(mode: HtmlRewriterMode): void;
+    private formatAttributes;
+    private generateScriptTag;
+    private generateStylesheetTag;
+    private appendDependencies;
+    private buildDependencyTags;
+    /**
+     * Injects generated markup immediately before the closing HTML tag when it is
+     * present, or appends/prepends a fallback insertion otherwise.
+     */
+    private injectBeforeClosingTag;
+    /**
+     * Replaces the current processed dependency set used during HTML finalization.
+     */
+    setProcessedDependencies(processedDependencies: ProcessedAsset[]): void;
+    /**
+     * Replaces the current structured page package used during HTML finalization.
+     */
+    setPagePackage(pagePackage: PagePackageResult): void;
+    /**
+     * Returns the processed dependencies queued for the next transform pass.
+     */
+    getProcessedDependencies(): ProcessedAsset[];
+    /**
+     * Returns the structured page package queued for the next transform pass.
+     */
+    getPagePackage(): PagePackageResult | undefined;
+    /**
+     * Applies attributes to the opening `<html>` tag when present.
+     */
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * Applies attributes to the first element nested directly under `<body>`.
+     */
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * Applies attributes to the first element in a fragment or full-document HTML
+     * string.
+     */
+    applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * Removes duplicate processed assets while preserving first-seen order.
+     *
+     * @remarks
+     * Dedupe keys include structural asset fields and HTML attributes so repeated
+     * orchestration passes can merge assets safely without collapsing distinct tag
+     * variants.
+     */
+    dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];
+    /**
+     * Injects the currently processed dependencies into an HTML response.
+     *
+     * @remarks
+     * Native or worker-tools HTML rewriter support is preferred when available. A
+     * string-based fallback remains in place for runtimes that cannot provide one
+     * of those rewriter implementations.
+     */
+    transform(res: Response): Promise<Response>;
+    /**
+     * Splits processed assets into head and body injection groups.
+     */
+    private groupDependenciesByPosition;
+    /**
+     * Builds a serialized HTML attribute string from an attribute object.
+     */
+    private buildAttributeString;
+}

package/src/services/html/html-transformer.service.js ADDED Viewed

@@ -0,0 +1,216 @@
+import {
+  DefaultHtmlRewriterProvider
+} from "./html-rewriter-provider.service.js";
+import { dedupeProcessedAssets } from "../../route-renderer/orchestration/processed-asset-dedupe.js";
+class HtmlTransformerService {
+  processedDependencies = [];
+  pagePackage;
+  htmlRewriterProvider;
+  constructor(options = {}) {
+    this.htmlRewriterProvider = options.htmlRewriterProvider ?? new DefaultHtmlRewriterProvider();
+    if (options.htmlRewriterMode) {
+      this.htmlRewriterProvider.setMode(options.htmlRewriterMode);
+    }
+  }
+  /**
+   * Overrides the HTML rewriter runtime selection.
+   *
+   * This is intended for internal/runtime tests that need deterministic
+   * selection between native, worker-tools, and string fallback behavior.
+   *
+   * @param mode Requested runtime selection strategy.
+   */
+  setHtmlRewriterMode(mode) {
+    this.htmlRewriterProvider.setMode(mode);
+  }
+  formatAttributes(attrs) {
+    if (!attrs) return "";
+    return ` ${Object.entries(attrs).map(([key, value]) => `${key}="${value}"`).join(" ")}`;
+  }
+  generateScriptTag(dep) {
+    return dep.inline ? `<script${this.formatAttributes(dep.attributes)}>${dep.content}<\/script>` : `<script src="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}><\/script>`;
+  }
+  generateStylesheetTag(dep) {
+    return dep.inline ? `<style${this.formatAttributes(dep.attributes)}>${dep.content}</style>` : `<link rel="stylesheet" href="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}>`;
+  }
+  appendDependencies(element, dependencies) {
+    for (const dep of dependencies) {
+      const tag = dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep);
+      element.append(tag, { html: true });
+    }
+  }
+  buildDependencyTags(dependencies) {
+    return dependencies.map(
+      (dep) => dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep)
+    ).join("");
+  }
+  /**
+   * Injects generated markup immediately before the closing HTML tag when it is
+   * present, or appends/prepends a fallback insertion otherwise.
+   */
+  injectBeforeClosingTag(html, tag, content) {
+    if (!content) {
+      return html;
+    }
+    const closingTag = `</${tag}>`;
+    const lowerHtml = html.toLowerCase();
+    const closingTagIndex = lowerHtml.lastIndexOf(closingTag);
+    if (closingTagIndex !== -1) {
+      return `${html.slice(0, closingTagIndex)}${content}${html.slice(closingTagIndex)}`;
+    }
+    if (tag === "head") {
+      return `${content}${html}`;
+    }
+    return `${html}${content}`;
+  }
+  /**
+   * Replaces the current processed dependency set used during HTML finalization.
+   */
+  setProcessedDependencies(processedDependencies) {
+    this.pagePackage = void 0;
+    this.processedDependencies = processedDependencies;
+  }
+  /**
+   * Replaces the current structured page package used during HTML finalization.
+   */
+  setPagePackage(pagePackage) {
+    this.pagePackage = pagePackage;
+    this.processedDependencies = pagePackage.htmlAssets;
+  }
+  /**
+   * Returns the processed dependencies queued for the next transform pass.
+   */
+  getProcessedDependencies() {
+    return this.processedDependencies;
+  }
+  /**
+   * Returns the structured page package queued for the next transform pass.
+   */
+  getPagePackage() {
+    return this.pagePackage;
+  }
+  /**
+   * Applies attributes to the opening `<html>` tag when present.
+   */
+  applyAttributesToHtmlElement(html, attributes) {
+    const htmlTagMatch = html.match(/<html\b[^>]*>/i);
+    if (!htmlTagMatch || htmlTagMatch.index === void 0) {
+      return html;
+    }
+    const attrs = this.buildAttributeString(attributes);
+    if (attrs.length === 0) {
+      return html;
+    }
+    const injectionOffset = htmlTagMatch.index + htmlTagMatch[0].length - 1;
+    return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+  }
+  /**
+   * Applies attributes to the first element nested directly under `<body>`.
+   */
+  applyAttributesToFirstBodyElement(html, attributes) {
+    const bodyMatch = html.match(/<body\b[^>]*>/i);
+    if (!bodyMatch || bodyMatch.index === void 0) {
+      return html;
+    }
+    const bodyOpenEnd = bodyMatch.index + bodyMatch[0].length;
+    const afterBody = html.slice(bodyOpenEnd);
+    const firstTagMatch = afterBody.match(/^(\s*<)([a-zA-Z][a-zA-Z0-9:-]*)(\b[^>]*>)/);
+    if (!firstTagMatch || firstTagMatch.index === void 0) {
+      return html;
+    }
+    const attrs = this.buildAttributeString(attributes);
+    if (attrs.length === 0) {
+      return html;
+    }
+    const injectionOffset = bodyOpenEnd + firstTagMatch[1].length + firstTagMatch[2].length;
+    return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+  }
+  /**
+   * Applies attributes to the first element in a fragment or full-document HTML
+   * string.
+   */
+  applyAttributesToFirstElement(html, attributes) {
+    const firstTagMatch = html.match(/^(\s*<)([a-zA-Z][a-zA-Z0-9:-]*)(\b[^>]*>)/);
+    if (!firstTagMatch || firstTagMatch.index === void 0) {
+      return html;
+    }
+    const attrs = this.buildAttributeString(attributes);
+    if (attrs.length === 0) {
+      return html;
+    }
+    const injectionOffset = firstTagMatch[1].length + firstTagMatch[2].length;
+    return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+  }
+  /**
+   * Removes duplicate processed assets while preserving first-seen order.
+   *
+   * @remarks
+   * Dedupe keys include structural asset fields and HTML attributes so repeated
+   * orchestration passes can merge assets safely without collapsing distinct tag
+   * variants.
+   */
+  dedupeProcessedAssets(assets) {
+    return dedupeProcessedAssets(assets);
+  }
+  /**
+   * Injects the currently processed dependencies into an HTML response.
+   *
+   * @remarks
+   * Native or worker-tools HTML rewriter support is preferred when available. A
+   * string-based fallback remains in place for runtimes that cannot provide one
+   * of those rewriter implementations.
+   */
+  async transform(res) {
+    const { head, body } = this.groupDependenciesByPosition();
+    const htmlRewriter = await this.htmlRewriterProvider.createHtmlRewriter();
+    if (htmlRewriter) {
+      htmlRewriter.on("head", {
+        element: (element) => this.appendDependencies(element, head)
+      }).on("body", {
+        element: (element) => this.appendDependencies(element, body)
+      });
+      return htmlRewriter.transform(res);
+    }
+    const html = await res.text();
+    const headers = new Headers(res.headers);
+    const withHeadDependencies = this.injectBeforeClosingTag(html, "head", this.buildDependencyTags(head));
+    const transformedHtml = this.injectBeforeClosingTag(
+      withHeadDependencies,
+      "body",
+      this.buildDependencyTags(body)
+    );
+    return new Response(transformedHtml, {
+      headers,
+      status: res.status,
+      statusText: res.statusText
+    });
+  }
+  /**
+   * Splits processed assets into head and body injection groups.
+   */
+  groupDependenciesByPosition() {
+    const dependencies = this.pagePackage?.htmlAssets ?? this.processedDependencies;
+    return dependencies.reduce(
+      (acc, dep) => {
+        if (dep.kind === "script") {
+          if (dep.excludeFromHtml) return acc;
+          const position = dep.position || "body";
+          acc[position].push(dep);
+        } else if (dep.kind === "stylesheet") {
+          acc.head.push(dep);
+        }
+        return acc;
+      },
+      { head: [], body: [] }
+    );
+  }
+  /**
+   * Builds a serialized HTML attribute string from an attribute object.
+   */
+  buildAttributeString(attributes) {
+    return Object.entries(attributes).filter(([key, value]) => key.length > 0 && value.length > 0).map(([key, value]) => ` ${key}="${value}"`).join("");
+  }
+}
+export {
+  HtmlTransformerService
+};

package/src/services/invalidation/development-invalidation.service.d.ts ADDED Viewed

@@ -0,0 +1,74 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type DevelopmentInvalidationCategory = 'public-asset' | 'additional-watch' | 'include-source' | 'route-source' | 'processor-owned-asset' | 'server-source' | 'other';
+/**
+ * Framework-owned invalidation plan for one changed file.
+ *
+ * @remarks
+ * This is the explicit invalidation matrix Workstream 4 needs. Watchers and
+ * runtime adapters consume this plan instead of encoding file-category rules in
+ * host-specific control flow.
+ */
+export interface DevelopmentInvalidationPlan {
+    category: DevelopmentInvalidationCategory;
+    invalidateServerModules: boolean;
+    refreshRoutes: boolean;
+    reloadBrowser: boolean;
+    delegateToHmr: boolean;
+    processorHandledAsset: boolean;
+}
+/**
+ * Framework-owned development invalidation service.
+ *
+ * @remarks
+ * This service centralizes two responsibilities:
+ * - file-change classification for watcher behavior
+ * - app-owned server-module invalidation versioning backed by the dev graph
+ *
+ * Hosts and watchers should ask this service what a file change means instead
+ * of deciding invalidation semantics inline.
+ */
+export declare class DevelopmentInvalidationService {
+    private readonly appConfig;
+    constructor(appConfig: EcoPagesAppConfig);
+    /**
+     * Returns the current app-owned server-module invalidation version.
+     */
+    getServerModuleInvalidationVersion(): number;
+    /**
+     * Invalidates the app-owned server-module graph.
+     */
+    invalidateServerModules(changedFiles?: string[]): void;
+    /**
+     * Resets runtime-owned graph state and invalidates server modules.
+     */
+    resetRuntimeState(changedFiles?: string[]): void;
+    /**
+     * Classifies one changed file into an explicit framework invalidation plan.
+     */
+    planFileChange(filePath: string): DevelopmentInvalidationPlan;
+    /**
+     * Returns whether the file lives under the public directory.
+     */
+    isPublicDirFile(filePath: string): boolean;
+    /**
+     * Returns whether the file matches `additionalWatchPaths`.
+     */
+    matchesAdditionalWatchPaths(filePath: string): boolean;
+    /**
+     * Returns whether the file is a route source file.
+     */
+    isRouteSourceFile(filePath: string): boolean;
+    /**
+     * Returns whether the file is an include/template source file.
+     */
+    isIncludeSourceFile(filePath: string): boolean;
+    /**
+     * Returns whether the file is a server-executed source module outside the
+     * special route/include buckets.
+     */
+    isServerModuleSourceFile(filePath: string): boolean;
+    /**
+     * Returns whether a processor owns the changed file as an asset input.
+     */
+    isProcessorOwnedAsset(filePath: string): boolean;
+}

package/src/services/invalidation/development-invalidation.service.js ADDED Viewed

@@ -0,0 +1,190 @@
+import path from "node:path";
+import { getAppServerInvalidationState } from "../runtime-state/server-invalidation-state.service.js";
+class DevelopmentInvalidationService {
+  appConfig;
+  constructor(appConfig) {
+    this.appConfig = appConfig;
+  }
+  /**
+   * Returns the current app-owned server-module invalidation version.
+   */
+  getServerModuleInvalidationVersion() {
+    return getAppServerInvalidationState(this.appConfig).getServerInvalidationVersion();
+  }
+  /**
+   * Invalidates the app-owned server-module graph.
+   */
+  invalidateServerModules(changedFiles) {
+    getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
+    this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
+  }
+  /**
+   * Resets runtime-owned graph state and invalidates server modules.
+   */
+  resetRuntimeState(changedFiles) {
+    const serverInvalidationState = getAppServerInvalidationState(this.appConfig);
+    serverInvalidationState.invalidateServerModules(changedFiles);
+    serverInvalidationState.reset();
+  }
+  /**
+   * Classifies one changed file into an explicit framework invalidation plan.
+   */
+  planFileChange(filePath) {
+    if (this.isPublicDirFile(filePath)) {
+      return {
+        category: "public-asset",
+        invalidateServerModules: false,
+        refreshRoutes: false,
+        reloadBrowser: true,
+        delegateToHmr: false,
+        processorHandledAsset: false
+      };
+    }
+    if (this.matchesAdditionalWatchPaths(filePath)) {
+      return {
+        category: "additional-watch",
+        invalidateServerModules: false,
+        refreshRoutes: false,
+        reloadBrowser: true,
+        delegateToHmr: false,
+        processorHandledAsset: false
+      };
+    }
+    if (this.isIncludeSourceFile(filePath)) {
+      return {
+        category: "include-source",
+        invalidateServerModules: true,
+        refreshRoutes: false,
+        reloadBrowser: true,
+        delegateToHmr: false,
+        processorHandledAsset: false
+      };
+    }
+    if (this.isRouteSourceFile(filePath)) {
+      return {
+        category: "route-source",
+        invalidateServerModules: true,
+        refreshRoutes: true,
+        reloadBrowser: false,
+        delegateToHmr: true,
+        processorHandledAsset: false
+      };
+    }
+    if (this.isProcessorOwnedAsset(filePath)) {
+      return {
+        category: "processor-owned-asset",
+        invalidateServerModules: false,
+        refreshRoutes: false,
+        reloadBrowser: false,
+        delegateToHmr: false,
+        processorHandledAsset: true
+      };
+    }
+    if (this.isServerModuleSourceFile(filePath)) {
+      return {
+        category: "server-source",
+        invalidateServerModules: true,
+        refreshRoutes: false,
+        reloadBrowser: false,
+        delegateToHmr: true,
+        processorHandledAsset: false
+      };
+    }
+    return {
+      category: "other",
+      invalidateServerModules: false,
+      refreshRoutes: false,
+      reloadBrowser: false,
+      delegateToHmr: true,
+      processorHandledAsset: false
+    };
+  }
+  /**
+   * Returns whether the file lives under the public directory.
+   */
+  isPublicDirFile(filePath) {
+    return path.resolve(filePath).startsWith(this.appConfig.absolutePaths.publicDir);
+  }
+  /**
+   * Returns whether the file matches `additionalWatchPaths`.
+   */
+  matchesAdditionalWatchPaths(filePath) {
+    const normalizedPath = path.resolve(filePath);
+    const patterns = this.appConfig.additionalWatchPaths;
+    if (!patterns.length) return false;
+    for (const pattern of patterns) {
+      if (pattern.includes("*")) {
+        const ext = pattern.replace(/\*\*?\/\*/, "");
+        if (normalizedPath.endsWith(ext)) return true;
+      } else if (normalizedPath.endsWith(pattern) || normalizedPath === path.resolve(pattern)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Returns whether the file is a route source file.
+   */
+  isRouteSourceFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir)) {
+      return false;
+    }
+    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+      return true;
+    }
+    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+  }
+  /**
+   * Returns whether the file is an include/template source file.
+   */
+  isIncludeSourceFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.includesDir)) {
+      return false;
+    }
+    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+      return true;
+    }
+    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+  }
+  /**
+   * Returns whether the file is a server-executed source module outside the
+   * special route/include buckets.
+   */
+  isServerModuleSourceFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.srcDir)) {
+      return false;
+    }
+    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+      return true;
+    }
+    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+  }
+  /**
+   * Returns whether a processor owns the changed file as an asset input.
+   */
+  isProcessorOwnedAsset(filePath) {
+    for (const processor of this.appConfig.processors.values()) {
+      const capabilities = processor.getAssetCapabilities?.() ?? [];
+      if (capabilities.length > 0) {
+        const matchesConfiguredAsset = typeof processor.matchesFileFilter !== "function" || processor.matchesFileFilter(filePath);
+        if (matchesConfiguredAsset && capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))) {
+          return true;
+        }
+        continue;
+      }
+      const watchConfig = processor.getWatchConfig();
+      if (!watchConfig) continue;
+      const { extensions = [] } = watchConfig;
+      if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
+        return true;
+      }
+    }
+    return false;
+  }
+}
+export {
+  DevelopmentInvalidationService
+};

package/src/services/module-loading/app-module-loader.service.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+import type { PageModuleImportOptions } from './page-module-import.service.js';
+export type AppModuleLoaderOwner = 'bun' | 'host';
+export interface AppModuleLoader {
+    readonly owner: AppModuleLoaderOwner;
+    importModule<T = unknown>(options: PageModuleImportOptions): Promise<T>;
+    invalidateDevelopmentGraph(): void;
+}

package/src/services/module-loading/app-module-loader.service.js ADDED Viewed

File without changes

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

@@ -0,0 +1,24 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { type AppModuleLoader } from './app-module-loader.service.js';
+import type { SourceModuleLoader } from './module-loading-types.js';
+import { ServerModuleTranspiler } from './server-module-transpiler.service.js';
+export declare function shouldAppUseHostModuleLoader(appConfig: EcoPagesAppConfig, filePath: string): boolean;
+export declare function getAppHostModuleLoader(appConfig: EcoPagesAppConfig): SourceModuleLoader | undefined;
+export declare function setAppHostModuleLoader(appConfig: EcoPagesAppConfig, hostModuleLoader?: SourceModuleLoader): void;
+export declare function createAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader;
+export declare function getAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader;
+export declare function setAppModuleLoader(appConfig: EcoPagesAppConfig, appModuleLoader: AppModuleLoader): void;
+/**
+ * Creates the shared app-scoped server-module transpiler for one runtime
+ * instance.
+ */
+export declare function createAppServerModuleTranspiler(appConfig: EcoPagesAppConfig): ServerModuleTranspiler;
+/**
+ * Returns the app-owned server-module transpiler, creating it lazily when the
+ * runtime first needs one.
+ */
+export declare function getAppServerModuleTranspiler(appConfig: EcoPagesAppConfig): ServerModuleTranspiler;
+/**
+ * Installs the server-module transpiler that should serve one app instance.
+ */
+export declare function setAppServerModuleTranspiler(appConfig: EcoPagesAppConfig, serverModuleTranspiler: ServerModuleTranspiler): void;