@ecopages/core 0.2.0-alpha.2 → 0.2.0-alpha.20

package/src/route-renderer/orchestration/component-render-context.d.ts

@@ -0,0 +1,83 @@
+import type { EcoComponent } from '../../types/public-types.js';
+/**
+ * Result returned by a renderer-owned boundary runtime.
+ *
+ * `inline` keeps rendering inside the current integration. `resolved` returns a
+ * renderer-owned value immediately, which can be final HTML or a renderer-local
+ * transport token for later queue resolution.
+ */
+export type ComponentBoundaryInterceptionResult = {
+    kind: 'inline';
+} | {
+    kind: 'resolved';
+    value: unknown;
+};
+/**
+ * Boundary metadata passed into the active renderer-owned runtime.
+ */
+export type ComponentBoundaryInterceptionInput = {
+    currentIntegration: string;
+    targetIntegration?: string;
+    component: EcoComponent;
+    props: Record<string, unknown>;
+};
+/**
+ * Narrow renderer-owned boundary runtime injected into one active render
+ * context.
+ *
+ * Integrations implement this contract when foreign boundaries must be handed
+ * off inside the renderer instead of being left for route-level reconciliation.
+ */
+export interface ComponentBoundaryRuntime {
+    interceptBoundary?(input: ComponentBoundaryInterceptionInput): ComponentBoundaryInterceptionResult | Promise<ComponentBoundaryInterceptionResult>;
+    interceptBoundarySync?(input: ComponentBoundaryInterceptionInput): ComponentBoundaryInterceptionResult;
+}
+type ComponentBoundaryRenderInput = {
+    component: EcoComponent;
+    props: Record<string, unknown>;
+    targetIntegration?: string;
+};
+/**
+ * Per-render mutable state used while applying boundary interception and lazy
+ * output wrapping.
+ */
+export type ComponentRenderContext = {
+    currentIntegration: string;
+    boundaryRuntime?: ComponentBoundaryRuntime;
+    interceptBoundary(input: ComponentBoundaryRenderInput): Promise<unknown | undefined> | unknown | undefined;
+    finalizeComponentRender<T>(component: EcoComponent, content: T): T;
+};
+/**
+ * Returns the current component render context, if one is active.
+ *
+ * @returns Active render context or `undefined` outside render execution.
+ */
+export declare function getComponentRenderContext(): ComponentRenderContext | undefined;
+/**
+ * Runs boundary interception for one component boundary.
+ *
+ * The active runtime may resolve the boundary immediately or keep it inline.
+ */
+export declare function interceptComponentBoundary(input: ComponentBoundaryRenderInput): Promise<unknown | undefined> | unknown | undefined;
+/**
+ * Applies lazy trigger or injector wrapping to completed component output.
+ *
+ * This helper works both inside render-context execution and in fallback flows
+ * where no active context exists.
+ */
+export declare function finalizeComponentRender<T>(component: EcoComponent, content: T): T;
+/**
+ * Runs render work under a fresh component render context and returns the
+ * resulting value.
+ *
+ * @param input Execution metadata for current integration and boundary policy.
+ * @param render Async render function to execute inside the context.
+ * @returns Render result value.
+ */
+export declare function runWithComponentRenderContext<T>(input: {
+    currentIntegration: string;
+    boundaryRuntime?: ComponentBoundaryRuntime;
+}, render: () => Promise<T>): Promise<{
+    value: T;
+}>;
+export {};

package/src/route-renderer/orchestration/component-render-context.js

@@ -0,0 +1,147 @@
+import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./render-output.utils.js";
+class ComponentRenderOutputRuntime {
+  finalizeComponentRender(component, content) {
+    const lazyTriggers = component.config?._resolvedLazyTriggers;
+    if (lazyTriggers && lazyTriggers.length > 0) {
+      return this.addTriggerToContent(content, lazyTriggers[0].triggerId);
+    }
+    const lazyGroups = component.config?._resolvedLazyScripts;
+    if (lazyGroups && lazyGroups.length > 0) {
+      return this.wrapContentWithScriptsInjector(content, lazyGroups);
+    }
+    return content;
+  }
+  addTriggerToContent(content, triggerId) {
+    if (isThenable(content)) {
+      return content.then((resolvedContent) => addTriggerAttribute(resolvedContent, triggerId));
+    }
+    return addTriggerAttribute(content, triggerId);
+  }
+  wrapContentWithScriptsInjector(content, lazyGroups) {
+    if (isThenable(content)) {
+      return content.then((resolvedContent) => wrapWithScriptsInjector(resolvedContent, lazyGroups));
+    }
+    return wrapWithScriptsInjector(content, lazyGroups);
+  }
+}
+class ContextualComponentRenderRuntime extends ComponentRenderOutputRuntime {
+  context;
+  constructor(context) {
+    super();
+    this.context = context;
+  }
+  applyBoundaryInterceptionResult(result) {
+    if (result.kind === "resolved") {
+      return result.value;
+    }
+    return void 0;
+  }
+  /**
+   * Resolves one boundary interception through the active runtime.
+   *
+   * The runtime may choose inline rendering or immediate resolved output.
+   */
+  interceptBoundary(input) {
+    const boundaryRuntimeInput = {
+      currentIntegration: this.context.currentIntegration,
+      targetIntegration: input.targetIntegration,
+      component: input.component,
+      props: input.props
+    };
+    const asyncInterception = this.context.boundaryRuntime?.interceptBoundary?.(boundaryRuntimeInput);
+    if (asyncInterception !== void 0) {
+      if (isThenable(asyncInterception)) {
+        return asyncInterception.then((result) => this.applyBoundaryInterceptionResult(result));
+      }
+      return this.applyBoundaryInterceptionResult(asyncInterception);
+    }
+    const syncInterception = this.context.boundaryRuntime?.interceptBoundarySync?.(boundaryRuntimeInput);
+    if (syncInterception === void 0) {
+      return void 0;
+    }
+    return this.applyBoundaryInterceptionResult(syncInterception);
+  }
+}
+const GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY = "__ECOPAGES_COMPONENT_RENDER_CONTEXT_STATE__";
+function getSharedContextScope() {
+  const globalProcess = globalThis.process;
+  if (globalProcess && typeof globalProcess === "object") {
+    return globalProcess;
+  }
+  return globalThis;
+}
+function getComponentRenderContextState() {
+  const sharedScope = getSharedContextScope();
+  sharedScope[GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY] ??= {
+    contextStack: [],
+    nodeContextStorage: null,
+    nodeContextStorageLoader: null
+  };
+  return sharedScope[GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY];
+}
+async function getContextStorage() {
+  const state = getComponentRenderContextState();
+  if (state.nodeContextStorage) {
+    return state.nodeContextStorage;
+  }
+  if (state.nodeContextStorageLoader) {
+    return state.nodeContextStorageLoader;
+  }
+  state.nodeContextStorageLoader = import("node:async_hooks").then((module) => {
+    const storage = new module.AsyncLocalStorage();
+    state.nodeContextStorage = {
+      getStore: () => storage.getStore(),
+      run: (store, callback) => storage.run(store, callback)
+    };
+    return state.nodeContextStorage;
+  }).catch(() => {
+    state.nodeContextStorage = null;
+    return null;
+  }).finally(() => {
+    state.nodeContextStorageLoader = null;
+  });
+  return state.nodeContextStorageLoader;
+}
+function getComponentRenderContext() {
+  const state = getComponentRenderContextState();
+  return state.nodeContextStorage?.getStore() ?? state.contextStack[state.contextStack.length - 1];
+}
+const componentRenderOutputRuntime = new ComponentRenderOutputRuntime();
+function interceptComponentBoundary(input) {
+  return getComponentRenderContext()?.interceptBoundary(input);
+}
+function finalizeComponentRender(component, content) {
+  const renderContext = getComponentRenderContext();
+  return renderContext?.finalizeComponentRender(component, content) ?? componentRenderOutputRuntime.finalizeComponentRender(component, content);
+}
+async function runWithComponentRenderContext(input, render) {
+  const context = {
+    currentIntegration: input.currentIntegration,
+    boundaryRuntime: input.boundaryRuntime
+  };
+  const runtime = new ContextualComponentRenderRuntime(context);
+  context.interceptBoundary = (deferredInput) => runtime.interceptBoundary(deferredInput);
+  context.finalizeComponentRender = (component, content) => runtime.finalizeComponentRender(component, content);
+  const storage = await getContextStorage();
+  let value;
+  if (storage) {
+    value = await storage.run(context, render);
+  } else {
+    const state = getComponentRenderContextState();
+    state.contextStack.push(context);
+    try {
+      value = await render();
+    } finally {
+      state.contextStack.pop();
+    }
+  }
+  return {
+    value
+  };
+}
+export {
+  finalizeComponentRender,
+  getComponentRenderContext,
+  interceptComponentBoundary,
+  runWithComponentRenderContext
+};