@ecopages/core 0.2.0-beta.26 → 0.2.0-beta.27

package/src/route-renderer/orchestration/page-browser-graph-session.d.ts

@@ -0,0 +1,106 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../types/public-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/assets.types.js';
+export type GraphPolicy = 'development' | 'production';
+export type GraphKey = {
+    integrationName: string;
+    routeFile: string;
+    entryFingerprint: string;
+    policy: GraphPolicy;
+};
+export type GraphRecord = {
+    key: GraphKey;
+    result: PageBrowserGraphResult;
+    dependencyPaths: ReadonlySet<string>;
+    committedAt: number;
+    generation: number;
+};
+export type GraphBuildResult = {
+    result: PageBrowserGraphResult;
+    dependencyPaths: ReadonlySet<string>;
+};
+type GroupedGraphRecord = {
+    assetsByRoute: Map<string, ProcessedAsset[]>;
+    dependencyPaths: ReadonlySet<string>;
+    generation: number;
+};
+export type GroupedGraphBuildOutcome = GroupedGraphRecord | {
+    skipCache: true;
+    assetsByRoute: Map<string, ProcessedAsset[]>;
+    dependencyPaths: ReadonlySet<string>;
+};
+export type AffectedGraphIdentity = {
+    integrationName: string;
+    routeFile: string;
+    policy: GraphPolicy;
+    entryFingerprint: string;
+};
+/**
+ * Reverse index from dependency paths to graph cache keys.
+ */
+export declare class GraphDependencyIndex {
+    private readonly dependencyToGraphKeys;
+    bindRecord(record: GraphRecord): void;
+    unbindRecord(record: GraphRecord): void;
+    bindGroupedRecord(integrationName: string, record: GroupedGraphRecord): void;
+    unbindGroupedRecord(integrationName: string, record: GroupedGraphRecord): void;
+    getAffectedKeys(filePath: string): Set<string>;
+    resetForTests(): void;
+    private addDependencyBinding;
+    private removeDependencyBinding;
+}
+/**
+ * Session-local Page Browser Graph cache with precise dependency invalidation.
+ */
+export declare class SessionPageBrowserGraphCache {
+    private readonly records;
+    private readonly inFlight;
+    private readonly groupedRecords;
+    private readonly groupedInFlight;
+    private readonly dependencyIndex;
+    private readonly graphGenerations;
+    private readonly groupedGenerations;
+    private buildCount;
+    getGraphByRoute(integrationName: string, routeFile: string, policy: GraphPolicy): PageBrowserGraphResult | undefined;
+    getBuildCount(): number;
+    getAffectedGraphIdentities(filePath: string): AffectedGraphIdentity[];
+    resolveGraph(key: GraphKey, build: () => Promise<GraphBuildResult | undefined>): Promise<PageBrowserGraphResult | undefined>;
+    resolveGroupedGraph(integrationName: string, build: () => Promise<GroupedGraphBuildOutcome | undefined>): Promise<Map<string, ProcessedAsset[]>>;
+    peekGroupedGraph(integrationName: string): Map<string, ProcessedAsset[]> | undefined;
+    invalidateByFilePath(filePath: string): number;
+    invalidateRoute(integrationName: string, routeFile: string): void;
+    invalidateByRouteFile(routeFile: string): void;
+    resetForTests(): void;
+    exportRecords(policy: GraphPolicy): GraphRecord[];
+    clearPolicyRecords(policy: GraphPolicy): void;
+    private pruneStaleRouteRecords;
+    private bumpGraphGeneration;
+    private bumpGroupedGeneration;
+    private invalidateSerializedGraphKey;
+    private invalidateGroupedRecord;
+    private runGraphBuild;
+    private runGroupedBuild;
+    private canCommitGraphBuild;
+    private canCommitGroupedBuild;
+}
+/**
+ * Returns the session graph cache for one app instance.
+ */
+export declare function getAppPageBrowserGraphSession(appConfig: EcoPagesAppConfig): SessionPageBrowserGraphCache;
+/**
+ * Invalidates graph records that depend on the changed file path.
+ */
+export declare function invalidatePageBrowserGraphSession(appConfig: EcoPagesAppConfig, filePath: string): number;
+/**
+ * Returns graph identities affected by a source file change.
+ */
+export declare function getAffectedPageBrowserGraphIdentities(appConfig: EcoPagesAppConfig, filePath: string): AffectedGraphIdentity[];
+/**
+ * Builds a stable fingerprint from declared browser-entry dependencies and assets.
+ */
+export declare function createPageBrowserGraphEntryFingerprint(contribution: PageBrowserGraphContribution): string;
+/**
+ * Collects dependency paths used for graph invalidation.
+ */
+export declare function collectPageBrowserGraphDependencyPaths(routeFile: string, contribution: PageBrowserGraphContribution, processedAssets: ProcessedAsset[]): ReadonlySet<string>;
+export {};

package/src/route-renderer/orchestration/page-browser-graph-session.js

@@ -0,0 +1,436 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { appLogger } from "../../global/app-logger.js";
+function isSkipCacheGroupedOutcome(outcome) {
+  return "skipCache" in outcome;
+}
+function serializeGraphKey(key) {
+  return `${key.policy}::${key.integrationName}::${key.routeFile}::${key.entryFingerprint}`;
+}
+function normalizeDependencyPath(filePath) {
+  return path.resolve(filePath);
+}
+function parseSerializedGraphKey(serializedKey) {
+  if (serializedKey.startsWith("grouped::")) {
+    return void 0;
+  }
+  const [policy, integrationName, routeFile, entryFingerprint] = serializedKey.split("::");
+  if (!policy || !integrationName || !routeFile || entryFingerprint === void 0) {
+    return void 0;
+  }
+  if (policy !== "development" && policy !== "production") {
+    return void 0;
+  }
+  return {
+    policy,
+    integrationName,
+    routeFile,
+    entryFingerprint
+  };
+}
+class GraphDependencyIndex {
+  dependencyToGraphKeys = /* @__PURE__ */ new Map();
+  bindRecord(record) {
+    const serializedKey = serializeGraphKey(record.key);
+    for (const dependencyPath of record.dependencyPaths) {
+      this.addDependencyBinding(normalizeDependencyPath(dependencyPath), serializedKey);
+    }
+  }
+  unbindRecord(record) {
+    const serializedKey = serializeGraphKey(record.key);
+    for (const dependencyPath of record.dependencyPaths) {
+      this.removeDependencyBinding(normalizeDependencyPath(dependencyPath), serializedKey);
+    }
+  }
+  bindGroupedRecord(integrationName, record) {
+    const serializedKey = `grouped::${integrationName}`;
+    for (const dependencyPath of record.dependencyPaths) {
+      this.addDependencyBinding(normalizeDependencyPath(dependencyPath), serializedKey);
+    }
+  }
+  unbindGroupedRecord(integrationName, record) {
+    const serializedKey = `grouped::${integrationName}`;
+    for (const dependencyPath of record.dependencyPaths) {
+      this.removeDependencyBinding(normalizeDependencyPath(dependencyPath), serializedKey);
+    }
+  }
+  getAffectedKeys(filePath) {
+    return new Set(this.dependencyToGraphKeys.get(normalizeDependencyPath(filePath)) ?? []);
+  }
+  resetForTests() {
+    this.dependencyToGraphKeys.clear();
+  }
+  addDependencyBinding(dependencyPath, serializedKey) {
+    const graphKeys = this.dependencyToGraphKeys.get(dependencyPath) ?? /* @__PURE__ */ new Set();
+    graphKeys.add(serializedKey);
+    this.dependencyToGraphKeys.set(dependencyPath, graphKeys);
+  }
+  removeDependencyBinding(dependencyPath, serializedKey) {
+    const graphKeys = this.dependencyToGraphKeys.get(dependencyPath);
+    if (!graphKeys) {
+      return;
+    }
+    graphKeys.delete(serializedKey);
+    if (graphKeys.size === 0) {
+      this.dependencyToGraphKeys.delete(dependencyPath);
+    }
+  }
+}
+class SessionPageBrowserGraphCache {
+  records = /* @__PURE__ */ new Map();
+  inFlight = /* @__PURE__ */ new Map();
+  groupedRecords = /* @__PURE__ */ new Map();
+  groupedInFlight = /* @__PURE__ */ new Map();
+  dependencyIndex = new GraphDependencyIndex();
+  graphGenerations = /* @__PURE__ */ new Map();
+  groupedGenerations = /* @__PURE__ */ new Map();
+  buildCount = 0;
+  getGraphByRoute(integrationName, routeFile, policy) {
+    const normalizedRoute = normalizeDependencyPath(routeFile);
+    for (const record of this.records.values()) {
+      if (record.key.integrationName !== integrationName) {
+        continue;
+      }
+      if (record.key.policy !== policy) {
+        continue;
+      }
+      if (normalizeDependencyPath(record.key.routeFile) !== normalizedRoute) {
+        continue;
+      }
+      return record.result;
+    }
+    return void 0;
+  }
+  getBuildCount() {
+    return this.buildCount;
+  }
+  getAffectedGraphIdentities(filePath) {
+    const identities = [];
+    for (const serializedKey of this.dependencyIndex.getAffectedKeys(filePath)) {
+      const identity = parseSerializedGraphKey(serializedKey);
+      if (identity) {
+        identities.push(identity);
+      }
+    }
+    return identities;
+  }
+  resolveGraph(key, build) {
+    const serializedKey = serializeGraphKey(key);
+    const cached = this.records.get(serializedKey);
+    if (cached) {
+      return Promise.resolve(cached.result);
+    }
+    const pending = this.inFlight.get(serializedKey);
+    if (pending) {
+      return pending;
+    }
+    const buildGeneration = this.bumpGraphGeneration(serializedKey);
+    const buildPromise = this.runGraphBuild(serializedKey, key, buildGeneration, build);
+    this.inFlight.set(serializedKey, buildPromise);
+    return buildPromise;
+  }
+  resolveGroupedGraph(integrationName, build) {
+    const cached = this.groupedRecords.get(integrationName);
+    if (cached) {
+      return Promise.resolve(cached.assetsByRoute);
+    }
+    const pending = this.groupedInFlight.get(integrationName);
+    if (pending) {
+      return pending;
+    }
+    const buildGeneration = this.bumpGroupedGeneration(integrationName);
+    const buildPromise = this.runGroupedBuild(integrationName, buildGeneration, build);
+    this.groupedInFlight.set(integrationName, buildPromise);
+    return buildPromise;
+  }
+  peekGroupedGraph(integrationName) {
+    return this.groupedRecords.get(integrationName)?.assetsByRoute;
+  }
+  invalidateByFilePath(filePath) {
+    const normalizedFilePath = normalizeDependencyPath(filePath);
+    const affectedKeys = this.dependencyIndex.getAffectedKeys(normalizedFilePath);
+    let invalidated = 0;
+    for (const serializedKey of affectedKeys) {
+      if (serializedKey.startsWith("grouped::")) {
+        const integrationName = serializedKey.slice("grouped::".length);
+        invalidated += this.invalidateGroupedRecord(integrationName);
+        continue;
+      }
+      invalidated += this.invalidateSerializedGraphKey(serializedKey);
+    }
+    for (const serializedKey of this.inFlight.keys()) {
+      const identity = parseSerializedGraphKey(serializedKey);
+      if (!identity) {
+        continue;
+      }
+      if (normalizeDependencyPath(identity.routeFile) !== normalizedFilePath) {
+        continue;
+      }
+      if (affectedKeys.has(serializedKey)) {
+        continue;
+      }
+      this.bumpGraphGeneration(serializedKey);
+      this.inFlight.delete(serializedKey);
+      invalidated += 1;
+    }
+    if (invalidated > 0) {
+      appLogger.debug(
+        `[PageBrowserGraphSession] invalidated ${invalidated} graph record(s) for ${normalizedFilePath}`
+      );
+    }
+    return invalidated;
+  }
+  invalidateRoute(integrationName, routeFile) {
+    const normalizedRoute = normalizeDependencyPath(routeFile);
+    for (const [serializedKey, record] of this.records) {
+      if (record.key.integrationName !== integrationName) {
+        continue;
+      }
+      if (normalizeDependencyPath(record.key.routeFile) !== normalizedRoute) {
+        continue;
+      }
+      this.invalidateSerializedGraphKey(serializedKey);
+    }
+  }
+  invalidateByRouteFile(routeFile) {
+    const normalizedRoute = normalizeDependencyPath(routeFile);
+    for (const [serializedKey, record] of this.records) {
+      if (normalizeDependencyPath(record.key.routeFile) !== normalizedRoute) {
+        continue;
+      }
+      this.invalidateSerializedGraphKey(serializedKey);
+    }
+  }
+  resetForTests() {
+    this.records.clear();
+    this.inFlight.clear();
+    this.groupedRecords.clear();
+    this.groupedInFlight.clear();
+    this.graphGenerations.clear();
+    this.groupedGenerations.clear();
+    this.dependencyIndex.resetForTests();
+    this.buildCount = 0;
+  }
+  exportRecords(policy) {
+    return [...this.records.values()].filter((record) => record.key.policy === policy);
+  }
+  clearPolicyRecords(policy) {
+    for (const [serializedKey, record] of this.records) {
+      if (record.key.policy !== policy) {
+        continue;
+      }
+      this.dependencyIndex.unbindRecord(record);
+      this.records.delete(serializedKey);
+      this.inFlight.delete(serializedKey);
+      this.graphGenerations.delete(serializedKey);
+    }
+    if (policy === "production") {
+      for (const integrationName of [...this.groupedRecords.keys()]) {
+        const groupedRecord = this.groupedRecords.get(integrationName);
+        if (groupedRecord) {
+          this.dependencyIndex.unbindGroupedRecord(integrationName, groupedRecord);
+        }
+        this.groupedRecords.delete(integrationName);
+        this.groupedInFlight.delete(integrationName);
+        this.groupedGenerations.delete(integrationName);
+      }
+    }
+  }
+  pruneStaleRouteRecords(key) {
+    const normalizedRoute = normalizeDependencyPath(key.routeFile);
+    for (const [serializedKey, record] of this.records) {
+      if (record.key.integrationName !== key.integrationName) {
+        continue;
+      }
+      if (normalizeDependencyPath(record.key.routeFile) !== normalizedRoute) {
+        continue;
+      }
+      if (record.key.entryFingerprint === key.entryFingerprint && record.key.policy === key.policy) {
+        continue;
+      }
+      this.invalidateSerializedGraphKey(serializedKey);
+    }
+  }
+  bumpGraphGeneration(serializedKey) {
+    const next = (this.graphGenerations.get(serializedKey) ?? 0) + 1;
+    this.graphGenerations.set(serializedKey, next);
+    return next;
+  }
+  bumpGroupedGeneration(integrationName) {
+    const next = (this.groupedGenerations.get(integrationName) ?? 0) + 1;
+    this.groupedGenerations.set(integrationName, next);
+    return next;
+  }
+  invalidateSerializedGraphKey(serializedKey) {
+    const record = this.records.get(serializedKey);
+    if (record) {
+      this.dependencyIndex.unbindRecord(record);
+      this.records.delete(serializedKey);
+    }
+    this.bumpGraphGeneration(serializedKey);
+    this.inFlight.delete(serializedKey);
+    return record ? 1 : 0;
+  }
+  invalidateGroupedRecord(integrationName) {
+    const groupedRecord = this.groupedRecords.get(integrationName);
+    if (groupedRecord) {
+      this.dependencyIndex.unbindGroupedRecord(integrationName, groupedRecord);
+      this.groupedRecords.delete(integrationName);
+    }
+    this.bumpGroupedGeneration(integrationName);
+    this.groupedInFlight.delete(integrationName);
+    return groupedRecord ? 1 : 0;
+  }
+  async runGraphBuild(serializedKey, key, buildGeneration, build) {
+    try {
+      this.buildCount += 1;
+      const buildResult = await build();
+      if (!buildResult) {
+        return void 0;
+      }
+      if (!this.canCommitGraphBuild(serializedKey, buildGeneration)) {
+        const existing = this.records.get(serializedKey);
+        return existing?.result;
+      }
+      this.pruneStaleRouteRecords(key);
+      const previous = this.records.get(serializedKey);
+      if (previous) {
+        this.dependencyIndex.unbindRecord(previous);
+      }
+      const record = {
+        key,
+        result: buildResult.result,
+        dependencyPaths: buildResult.dependencyPaths,
+        committedAt: Date.now(),
+        generation: buildGeneration
+      };
+      this.records.set(serializedKey, record);
+      this.dependencyIndex.bindRecord(record);
+      return record.result;
+    } catch (error) {
+      return Promise.reject(error);
+    } finally {
+      this.inFlight.delete(serializedKey);
+    }
+  }
+  async runGroupedBuild(integrationName, buildGeneration, build) {
+    try {
+      this.buildCount += 1;
+      const buildResult = await build();
+      if (!buildResult) {
+        return /* @__PURE__ */ new Map();
+      }
+      if (isSkipCacheGroupedOutcome(buildResult)) {
+        return buildResult.assetsByRoute;
+      }
+      if (!this.canCommitGroupedBuild(integrationName, buildGeneration)) {
+        const existing = this.groupedRecords.get(integrationName);
+        return existing?.assetsByRoute ?? /* @__PURE__ */ new Map();
+      }
+      const previous = this.groupedRecords.get(integrationName);
+      if (previous) {
+        this.dependencyIndex.unbindGroupedRecord(integrationName, previous);
+      }
+      const record = {
+        assetsByRoute: buildResult.assetsByRoute,
+        dependencyPaths: buildResult.dependencyPaths,
+        generation: buildGeneration
+      };
+      this.groupedRecords.set(integrationName, record);
+      this.dependencyIndex.bindGroupedRecord(integrationName, record);
+      return record.assetsByRoute;
+    } catch (error) {
+      return Promise.reject(error);
+    } finally {
+      this.groupedInFlight.delete(integrationName);
+    }
+  }
+  canCommitGraphBuild(serializedKey, buildGeneration) {
+    return this.graphGenerations.get(serializedKey) === buildGeneration;
+  }
+  canCommitGroupedBuild(integrationName, buildGeneration) {
+    return this.groupedGenerations.get(integrationName) === buildGeneration;
+  }
+}
+const sessionByAppConfig = /* @__PURE__ */ new WeakMap();
+function getAppPageBrowserGraphSession(appConfig) {
+  const existing = appConfig.runtime?.pageBrowserGraphSession;
+  if (existing) {
+    return existing;
+  }
+  const cached = sessionByAppConfig.get(appConfig);
+  if (cached) {
+    return cached;
+  }
+  const session = new SessionPageBrowserGraphCache();
+  sessionByAppConfig.set(appConfig, session);
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    pageBrowserGraphSession: session
+  };
+  return session;
+}
+function invalidatePageBrowserGraphSession(appConfig, filePath) {
+  return getAppPageBrowserGraphSession(appConfig).invalidateByFilePath(filePath);
+}
+function getAffectedPageBrowserGraphIdentities(appConfig, filePath) {
+  return getAppPageBrowserGraphSession(appConfig).getAffectedGraphIdentities(filePath);
+}
+function createPageBrowserGraphEntryFingerprint(contribution) {
+  const descriptors = [
+    ...(contribution.dependencies ?? []).map((dependency) => describeAssetDependency(dependency)),
+    ...(contribution.assets ?? []).map((asset) => describeProcessedAsset(asset))
+  ].sort((left, right) => left.localeCompare(right));
+  return descriptors.join("|") || "empty";
+}
+function collectPageBrowserGraphDependencyPaths(routeFile, contribution, processedAssets) {
+  const dependencyPaths = /* @__PURE__ */ new Set([normalizeDependencyPath(routeFile)]);
+  for (const dependency of contribution.dependencies ?? []) {
+    if (dependency.source === "file") {
+      dependencyPaths.add(normalizeDependencyPath(dependency.filepath));
+    }
+  }
+  for (const asset of processedAssets) {
+    if (asset.sourceFilepath) {
+      dependencyPaths.add(normalizeDependencyPath(asset.sourceFilepath));
+    }
+    for (const bundledSourceFilepath of asset.bundledSourceFilepaths ?? []) {
+      dependencyPaths.add(normalizeDependencyPath(bundledSourceFilepath));
+    }
+  }
+  return dependencyPaths;
+}
+function describeProcessedAsset(asset) {
+  const filepath = asset.filepath ?? "";
+  const sourceFilepath = asset.sourceFilepath ?? "";
+  const content = typeof asset.content === "string" ? asset.content : "";
+  const contentDigest = content ? createHash("sha1").update(content).digest("hex").slice(0, 12) : "";
+  return `asset:${asset.kind}:${filepath}:${sourceFilepath}:${contentDigest}`;
+}
+function describeAssetDependency(dependency) {
+  switch (dependency.source) {
+    case "file":
+      return `file:${dependency.filepath}`;
+    case "node-module":
+      return `module:${dependency.importPath}`;
+    case "content": {
+      const content = typeof dependency.content === "string" ? dependency.content : "";
+      const contentDigest = createHash("sha1").update(content).digest("hex").slice(0, 12);
+      const name = "name" in dependency && typeof dependency.name === "string" ? dependency.name : "";
+      return `content:${dependency.kind}:${name}:${contentDigest}`;
+    }
+    default: {
+      const exhaustive = dependency;
+      return String(exhaustive);
+    }
+  }
+}
+export {
+  GraphDependencyIndex,
+  SessionPageBrowserGraphCache,
+  collectPageBrowserGraphDependencyPaths,
+  createPageBrowserGraphEntryFingerprint,
+  getAffectedPageBrowserGraphIdentities,
+  getAppPageBrowserGraphSession,
+  invalidatePageBrowserGraphSession
+};

package/src/route-renderer/orchestration/page-browser-graph.service.d.ts

@@ -1,10 +1,12 @@
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
 import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../types/public-types.js';
 import { type AssetProcessingService } from '../../services/assets/asset-processing-service/index.js';
+import { type GraphPolicy } from './page-browser-graph-session.js';
 export type PageBrowserGraphResolveInput = {
     routeFile: string;
     integrationName: string;
     collectContribution: (routeFile: string) => Promise<PageBrowserGraphContribution | undefined>;
+    policy?: GraphPolicy;
 };
 /**
  * Resolves declarative page browser graph assets for one route and integration.
@@ -12,12 +14,16 @@ export type PageBrowserGraphResolveInput = {
 export declare class PageBrowserGraphService {
     private readonly appConfig;
     private readonly assetProcessingService;
-    private readonly pageBrowserGraphCache;
-    private readonly groupedPageBrowserGraphCache;
     constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
     resolvePageBrowserGraph(input: PageBrowserGraphResolveInput): Promise<PageBrowserGraphResult | undefined>;
+    /**
+     * Resolves or builds one Page Browser Graph under the given policy.
+     */
+    getOrBuild(input: PageBrowserGraphResolveInput): Promise<PageBrowserGraphResult | undefined>;
+    private resolveGraphPolicy;
     private isHmrEnabled;
-    private buildPageBrowserGraph;
+    private buildPageBrowserGraphRecord;
+    private materializePageBrowserGraph;
     private resolveGroupedPageBrowserAssets;
     private buildGroupedPageBrowserAssets;
     private listIntegrationRouteFiles;