@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

package/src/route-renderer/orchestration/page-browser-graph/grouped-graph-build-plan.js

@@ -0,0 +1,9 @@
+/**
+ * Builds a stable grouped-cache identity for one integration static export plan.
+ */
+export function createGroupedGraphBuildPlanKey(integrationName, instances) {
+    const canonicalInstances = [...instances]
+        .map((instance) => [instance.routeFile, instance.dependencyInstanceKey])
+        .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+    return JSON.stringify(['grouped-plan', integrationName, canonicalInstances]);
+}

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

@@ -0,0 +1,5 @@
+import type { PageBrowserGraphContribution } from '../../../types/public-types.js';
+/**
+ * Merges multiple Page Browser Graph contributions into one declarative payload.
+ */
+export declare function mergePageBrowserGraphContributions(...contributions: Array<PageBrowserGraphContribution | undefined>): PageBrowserGraphContribution | undefined;

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

@@ -0,0 +1,30 @@
+/**
+ * Merges multiple Page Browser Graph contributions into one declarative payload.
+ */
+export function mergePageBrowserGraphContributions(...contributions) {
+    const dependencies = [];
+    const assets = [];
+    const watchPaths = new Set();
+    for (const contribution of contributions) {
+        if (!contribution) {
+            continue;
+        }
+        if (contribution.dependencies?.length) {
+            dependencies.push(...contribution.dependencies);
+        }
+        if (contribution.assets?.length) {
+            assets.push(...contribution.assets);
+        }
+        for (const watchPath of contribution.watchPaths ?? []) {
+            watchPaths.add(watchPath);
+        }
+    }
+    if (dependencies.length === 0 && assets.length === 0 && watchPaths.size === 0) {
+        return undefined;
+    }
+    return {
+        ...(dependencies.length > 0 ? { dependencies } : {}),
+        ...(assets.length > 0 ? { assets } : {}),
+        ...(watchPaths.size > 0 ? { watchPaths: Array.from(watchPaths) } : {}),
+    };
+}

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

@@ -0,0 +1,12 @@
+import { type ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import type { PageBrowserGraphResult, PagePackageResult } from '../../../types/public-types.js';
+/**
+ * Merges a page browser graph into an existing page package (or processed dependencies).
+ *
+ * Deduplicates entry/chunk assets against the existing package and rebuilds the
+ * package so downstream HTML finalization sees one canonical graph.
+ */
+export declare function mergePageBrowserGraph(currentPagePackage: PagePackageResult | undefined, processedDependencies: ProcessedAsset[], pageBrowserGraph: PageBrowserGraphResult): {
+    pagePackage: PagePackageResult;
+    mergedGraph: PageBrowserGraphResult;
+};

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

@@ -0,0 +1,32 @@
+import { createPagePackage } from '../../../services/assets/asset-processing-service/index.js';
+import { buildProcessedAssetDedupeKey, dedupeProcessedAssets } from './processed-asset-dedupe.js';
+/**
+ * Merges a page browser graph into an existing page package (or processed dependencies).
+ *
+ * Deduplicates entry/chunk assets against the existing package and rebuilds the
+ * package so downstream HTML finalization sees one canonical graph.
+ */
+export function mergePageBrowserGraph(currentPagePackage, processedDependencies, pageBrowserGraph) {
+    const mergedGraph = currentPagePackage?.pageBrowserGraph
+        ? {
+            entryAssets: dedupeProcessedAssets([
+                ...currentPagePackage.pageBrowserGraph.entryAssets,
+                ...pageBrowserGraph.entryAssets,
+            ]),
+            chunkAssets: dedupeProcessedAssets([
+                ...currentPagePackage.pageBrowserGraph.chunkAssets,
+                ...pageBrowserGraph.chunkAssets,
+            ]),
+        }
+        : pageBrowserGraph;
+    const pageBrowserGraphAssetKeys = new Set([...mergedGraph.entryAssets, ...mergedGraph.chunkAssets].map((asset) => buildProcessedAssetDedupeKey(asset)));
+    const baseAssets = currentPagePackage
+        ? currentPagePackage.assets.filter((asset) => !pageBrowserGraphAssetKeys.has(buildProcessedAssetDedupeKey(asset)))
+        : processedDependencies;
+    return {
+        pagePackage: createPagePackage(dedupeProcessedAssets(baseAssets), {
+            pageBrowserGraph: mergedGraph,
+        }),
+        mergedGraph,
+    };
+}

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

@@ -0,0 +1,126 @@
+import type { GroupedGraphScope } from './route-instance-key.js';
+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;
+    dependencyInstanceKey: 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>;
+    /**
+     * @remarks
+     * When false, the build result is returned to callers but not committed to the session cache.
+     */
+    cacheable?: boolean;
+};
+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;
+    dependencyInstanceKey: 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(cacheKey: string, record: GroupedGraphRecord): void;
+    unbindGroupedRecord(cacheKey: string, record: GroupedGraphRecord): void;
+    bindPaths(serializedKey: string, dependencyPaths: ReadonlySet<string>): void;
+    unbindPaths(serializedKey: string, dependencyPaths: ReadonlySet<string>): 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 inFlightDependencyPaths;
+    private readonly inFlightGenerations;
+    private readonly groupedRecords;
+    private readonly groupedInFlight;
+    private readonly dependencyIndex;
+    private readonly graphGenerations;
+    private readonly groupedGenerations;
+    private buildCount;
+    /**
+     * Page Browser Graph compilations in this dev-server session.
+     */
+    getBuildCount(): number;
+    getGraphByRoute(integrationName: string, routeFile: string, policy: GraphPolicy, dependencyInstanceKey?: string): PageBrowserGraphResult | undefined;
+    getDependencyPathsByRoute(integrationName: string, routeFile: string, policy: GraphPolicy, dependencyInstanceKey?: string): ReadonlySet<string> | undefined;
+    getAffectedGraphIdentities(filePath: string): AffectedGraphIdentity[];
+    resolveGraph(key: GraphKey, provisionalDependencyPaths: ReadonlySet<string>, build: () => Promise<GraphBuildResult | undefined>): Promise<PageBrowserGraphResult | undefined>;
+    resolveGroupedGraph(scope: GroupedGraphScope, build: () => Promise<GroupedGraphBuildOutcome | undefined>): Promise<Map<string, ProcessedAsset[]>>;
+    peekGroupedGraph(scope: GroupedGraphScope): 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;
+    private bindDependencyPaths;
+    private unbindDependencyPaths;
+    private clearInFlightBuild;
+    private releaseInFlightDependencyPaths;
+}
+/**
+ * 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 {};