@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.33

package/src/adapters/shared/runtime/render-context.js

@@ -1,84 +1,99 @@
-import { fileURLToPath } from "node:url";
-import { invariant } from "../../../utils/invariant.js";
-import { createBodyResponse } from "../http/create-body-response.js";
+import { fileURLToPath } from 'node:url';
+import { invariant } from '../../../utils/invariant.js';
+import { createBodyResponse } from '../http/create-body-response.js';
 function resolveServerModulePath(filePath) {
-  return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
+    return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
 }
+/**
+ * Merges request locals into component props as a dedicated 'locals' property.
+ * This prevents naming conflicts and maintains type safety by keeping locals
+ * separate from other props.
+ *
+ * @param props - The original component props
+ * @param locals - Optional request-scoped locals from middleware
+ * @returns Props with locals merged in, or original props if no locals provided
+ */
 function mergePropsWithLocals(props, locals) {
-  if (!locals || typeof props !== "object" || props === null) {
-    return props;
-  }
-  return { ...props, locals };
-}
-function createRenderContext(options) {
-  const { integrations } = options;
-  const getRendererForView = (view) => {
-    const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
-    invariant(
-      !!integrationName,
-      "Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension."
-    );
-    const integration = integrations.find((i) => i.name === integrationName);
-    invariant(!!integration, `No integration found for: ${integrationName}`);
-    return integration.initializeRenderer({
-      rendererModules: options.rendererModules
-    });
-  };
-  const renderContext = {
-    importServerModule: async (filePath) => {
-      invariant(!!options.importServerModule, "Server module importing is not available in this render context.");
-      return await options.importServerModule(resolveServerModulePath(filePath));
-    },
-    async renderServerModule(filePath, props, renderOptions) {
-      const module = await renderContext.importServerModule(filePath);
-      const view = module.default;
-      const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
-      const renderer = getRendererForView(view);
-      const ctx = {
-        partial: false,
-        status: renderOptions?.status,
-        headers: renderOptions?.headers
-      };
-      return await renderer.renderToResponse(view, mergedProps, ctx);
-    },
-    async render(view, props, renderOptions) {
-      const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props ?? {}, locals);
-      const renderer = getRendererForView(view);
-      const ctx = {
-        partial: false,
-        status: renderOptions?.status,
-        headers: renderOptions?.headers
-      };
-      return renderer.renderToResponse(view, mergedProps, ctx);
-    },
-    async renderPartial(view, props, renderOptions) {
-      const locals = this?.locals;
-      const mergedProps = mergePropsWithLocals(props, locals);
-      const renderer = getRendererForView(view);
-      const ctx = {
-        partial: true,
-        status: renderOptions?.status,
-        headers: renderOptions?.headers
-      };
-      return renderer.renderToResponse(view, mergedProps, ctx);
-    },
-    json(data, responseOptions) {
-      return createBodyResponse("json", data, {
-        status: responseOptions?.status,
-        headers: responseOptions?.headers
-      });
-    },
-    html(content, responseOptions) {
-      return createBodyResponse("html", content, {
-        status: responseOptions?.status,
-        headers: responseOptions?.headers
-      });
+    if (!locals || typeof props !== 'object' || props === null) {
+        return props;
     }
-  };
-  return renderContext;
+    return { ...props, locals };
+}
+/**
+ * Creates a render context for route handlers.
+ * Provides render(), renderPartial(), json(), and html() methods that can be used
+ * within route handlers to generate responses.
+ *
+ * @param options - Configuration options including available integrations
+ * @returns A RenderContext object with methods for rendering views and creating responses
+ */
+export function createRenderContext(options) {
+    const { integrations } = options;
+    /**
+     * Resolves the appropriate renderer for a given view component based on its integration.
+     * Throws an error if the integration cannot be determined or is not found.
+     */
+    const getRendererForView = (view) => {
+        const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
+        invariant(!!integrationName, 'Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension.');
+        const integration = integrations.find((i) => i.name === integrationName);
+        invariant(!!integration, `No integration found for: ${integrationName}`);
+        return integration.initializeRenderer({
+            rendererModules: options.rendererModules,
+        });
+    };
+    const renderContext = {
+        importServerModule: async (filePath) => {
+            invariant(!!options.importServerModule, 'Server module importing is not available in this render context.');
+            return (await options.importServerModule(resolveServerModulePath(filePath)));
+        },
+        async renderServerModule(filePath, props, renderOptions) {
+            const module = await renderContext.importServerModule(filePath);
+            const view = module.default;
+            const locals = this?.locals;
+            const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+            const renderer = getRendererForView(view);
+            const ctx = {
+                partial: false,
+                status: renderOptions?.status,
+                headers: renderOptions?.headers,
+            };
+            return await renderer.renderToResponse(view, mergedProps, ctx);
+        },
+        async render(view, props, renderOptions) {
+            const locals = this?.locals;
+            const mergedProps = mergePropsWithLocals(props ?? {}, locals);
+            const renderer = getRendererForView(view);
+            const ctx = {
+                partial: false,
+                status: renderOptions?.status,
+                headers: renderOptions?.headers,
+            };
+            return renderer.renderToResponse(view, mergedProps, ctx);
+        },
+        async renderPartial(view, props, renderOptions) {
+            const locals = this?.locals;
+            const mergedProps = mergePropsWithLocals(props, locals);
+            const renderer = getRendererForView(view);
+            const ctx = {
+                partial: true,
+                status: renderOptions?.status,
+                headers: renderOptions?.headers,
+            };
+            return renderer.renderToResponse(view, mergedProps, ctx);
+        },
+        json(data, responseOptions) {
+            return createBodyResponse('json', data, {
+                status: responseOptions?.status,
+                headers: responseOptions?.headers,
+            });
+        },
+        html(content, responseOptions) {
+            return createBodyResponse('html', content, {
+                status: responseOptions?.status,
+                headers: responseOptions?.headers,
+            });
+        },
+    };
+    return renderContext;
 }
-export {
-  createRenderContext
-};

package/src/adapters/shared/runtime/runtime-app-bootstrap.js

@@ -1,43 +1,38 @@
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../../config/constants.js";
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../../config/constants.js';
 function normalizeOriginHostname(hostname) {
-  if (hostname.includes(":") && !hostname.startsWith("[") && !hostname.endsWith("]")) {
-    return `[${hostname}]`;
-  }
-  return hostname;
+    if (hostname.includes(':') && !hostname.startsWith('[') && !hostname.endsWith(']')) {
+        return `[${hostname}]`;
+    }
+    return hostname;
 }
-function resolveServeRuntimeOrigin(serveOptions) {
-  const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
-  const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
-  return `http://${hostname}:${port}`;
+export function resolveServeRuntimeOrigin(serveOptions) {
+    const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
+    const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+    return `http://${hostname}:${port}`;
 }
-function resolveRuntimeBinding(options) {
-  const env = options.env ?? process.env;
-  const portExplicitlyConfigured = options.cliArgs.port !== void 0 || Boolean(env.ECOPAGES_PORT) || options.serverOptions?.port !== void 0;
-  const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : void 0) ?? DEFAULT_ECOPAGES_PORT;
-  const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
-  return {
-    preferredPort,
-    preferredHostname,
-    allowPortFallback: !portExplicitlyConfigured,
-    runtimeOrigin: resolveServeRuntimeOrigin({
-      hostname: preferredHostname,
-      port: preferredPort
-    }),
-    serveOptions: {
-      port: preferredPort,
-      hostname: preferredHostname,
-      ...options.serverOptions ?? {}
-    },
-    watch: options.cliArgs.dev
-  };
+export function resolveRuntimeBinding(options) {
+    const env = options.env ?? process.env;
+    const portExplicitlyConfigured = options.cliArgs.port !== undefined || Boolean(env.ECOPAGES_PORT) || options.serverOptions?.port !== undefined;
+    const preferredPort = options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : undefined) ?? DEFAULT_ECOPAGES_PORT;
+    const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
+    return {
+        preferredPort,
+        preferredHostname,
+        allowPortFallback: !portExplicitlyConfigured,
+        runtimeOrigin: resolveServeRuntimeOrigin({
+            hostname: preferredHostname,
+            port: preferredPort,
+        }),
+        serveOptions: {
+            port: preferredPort,
+            hostname: preferredHostname,
+            ...(options.serverOptions ?? {}),
+        },
+        watch: options.cliArgs.dev,
+    };
 }
-function resolveStaticRuntimeMode(options) {
-  return {
-    canBuildWithoutRuntimeServer: options.cliArgs.build || options.cliArgs.preview
-  };
+export function resolveStaticRuntimeMode(options) {
+    return {
+        canBuildWithoutRuntimeServer: options.cliArgs.build || options.cliArgs.preview,
+    };
 }
-export {
-  resolveRuntimeBinding,
-  resolveServeRuntimeOrigin,
-  resolveStaticRuntimeMode
-};

package/src/adapters/shared/runtime/runtime-host.js

@@ -0,0 +1 @@
+export {};

package/src/adapters/shared/runtime/runtime-server-lifecycle.d.ts

@@ -1,5 +1,4 @@
-import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
-import type { IHmrManager } from '../../../types/public-types.js';
+import type { EcoPagesAppConfig, IHmrManager } from '../../../types/internal-types.js';
 import type { ProjectWatcher } from '../../../watchers/project-watcher.js';
 /**
  * Copies source `public/` into dist and ensures the resolved assets directory exists.
@@ -21,7 +20,7 @@ export declare function attachHmrToIntegrations(appConfig: EcoPagesAppConfig, hm
  * coalesced {@link ensureIntegrationRuntimeReady} promise instead of paying a cold vendor build.
  * Failures are logged and do not crash the server.
  */
-export declare function startConfiguredIntegrationRuntimePrewarm(options: {
+export declare function startDevWarmup(options: {
     appConfig: EcoPagesAppConfig;
     runtimeOrigin: string;
 }): void;

package/src/adapters/shared/runtime/runtime-server-lifecycle.js

@@ -1,57 +1,71 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { RESOLVED_ASSETS_DIR } from "../../../config/constants.js";
-import { disposeAppBuildRuntime } from "../../../build/runtime/build-runtime.js";
-import { ensureIntegrationRuntimeReady } from "../../../build/app-build-manifest-runtime.js";
-import { appLogger } from "../../../global/app-logger.js";
-import { copyRuntimePublicDirIfChanged } from "./copy-runtime-public-dir.js";
-import { clearAppDevClientBridge } from "../../../dev/client-bridge-registry.js";
-import { clearAppHmrManager } from "../../../dev/hmr-manager-registry.js";
-function prepareRuntimePublicDir(appConfig) {
-  const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
-  if (fileSystem.exists(srcPublicDir)) {
-    copyRuntimePublicDirIfChanged(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
-  }
-  fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { RESOLVED_ASSETS_DIR } from '../../../config/constants.js';
+import { disposeAppBuildRuntime } from '../../../build/runtime/build-runtime.js';
+import { ensureIntegrationRuntimeReady } from '../../../build/app-build-manifest-runtime.js';
+import { appLogger } from '../../../global/app-logger.js';
+import { copyRuntimePublicDirIfChanged } from './copy-runtime-public-dir.js';
+import { clearAppDevClientBridge } from '../../../dev/client-bridge-registry.js';
+import { clearAppHmrManager } from '../../../dev/hmr-manager-registry.js';
+/**
+ * Copies source `public/` into dist and ensures the resolved assets directory exists.
+ */
+export function prepareRuntimePublicDir(appConfig) {
+    const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+    if (fileSystem.exists(srcPublicDir)) {
+        copyRuntimePublicDirIfChanged(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+    }
+    fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
 }
-const attachedHmrApps = /* @__PURE__ */ new WeakSet();
-function attachHmrToIntegrations(appConfig, hmrManager) {
-  if (attachedHmrApps.has(appConfig)) {
-    return;
-  }
-  attachedHmrApps.add(appConfig);
-  for (const integration of appConfig.integrations) {
-    integration.setHmrManager(hmrManager);
-  }
+const attachedHmrApps = new WeakSet();
+/**
+ * Attaches the shared HMR manager to every integration exactly once per app config.
+ *
+ * @remarks
+ * Runtime plugin setup must not call `integration.setHmrManager()` directly. Adapters invoke
+ * this after the manager is enabled so late plugin init cannot double-bind integrations.
+ */
+export function attachHmrToIntegrations(appConfig, hmrManager) {
+    if (attachedHmrApps.has(appConfig)) {
+        return;
+    }
+    attachedHmrApps.add(appConfig);
+    for (const integration of appConfig.integrations) {
+        integration.setHmrManager(hmrManager);
+    }
 }
-function startConfiguredIntegrationRuntimePrewarm(options) {
-  const { appConfig, runtimeOrigin } = options;
-  void Promise.all(
-    appConfig.integrations.map(
-      (integration) => ensureIntegrationRuntimeReady({
+/**
+ * Starts background activation of every configured integration after watch-mode HMR is ready.
+ *
+ * @remarks
+ * Fire-and-forget: overlaps with watcher setup so first-page render can join the same
+ * coalesced {@link ensureIntegrationRuntimeReady} promise instead of paying a cold vendor build.
+ * Failures are logged and do not crash the server.
+ */
+export function startDevWarmup(options) {
+    const { appConfig, runtimeOrigin } = options;
+    void Promise.all(appConfig.integrations.map((integration) => ensureIntegrationRuntimeReady({
         appConfig,
         integrationName: integration.name,
-        runtimeOrigin
-      })
-    )
-  ).catch((error) => {
-    appLogger.error(
-      `Failed to prewarm integration runtimes: ${error instanceof Error ? error.message : String(error)}`
-    );
-  });
+        runtimeOrigin,
+    }))).catch((error) => {
+        appLogger.error(`Failed to prewarm integration runtimes: ${error instanceof Error ? error.message : String(error)}`);
+    });
 }
-async function disposeDevResources(options) {
-  await options.projectWatcher?.close();
-  await disposeAppBuildRuntime(options.appConfig);
-  options.hmrManager?.stop();
-  options.bridge?.destroy();
-  clearAppDevClientBridge(options.appConfig);
-  clearAppHmrManager(options.appConfig);
-  await options.previewHost.stop();
+/**
+ * Releases shared dev resources in a consistent order across server adapters.
+ *
+ * @remarks
+ * Bun calls `buildRuntime()` during `initialize()` when watch is enabled; Node defers
+ * runtime creation to `completeInitialization()`. Transport-specific setup stays in
+ * each adapter — only shared teardown lives here.
+ */
+export async function disposeDevResources(options) {
+    await options.projectWatcher?.close();
+    await disposeAppBuildRuntime(options.appConfig);
+    options.hmrManager?.stop();
+    options.bridge?.destroy();
+    clearAppDevClientBridge(options.appConfig);
+    clearAppHmrManager(options.appConfig);
+    await options.previewHost.stop();
 }
-export {
-  attachHmrToIntegrations,
-  disposeDevResources,
-  prepareRuntimePublicDir,
-  startConfiguredIntegrationRuntimePrewarm
-};

package/src/adapters/shared/runtime/server-adapter.d.ts

@@ -63,6 +63,7 @@ export declare abstract class SharedServerAdapter<TOptions extends ServerAdapter
     private createSharedPageCacheService;
     protected getCacheService(): CacheInvalidator | null;
     protected getRenderContext(): RenderContext;
+    private tryHandleSharedDevClientRequest;
     private tryHandleSharedHmrRequest;
     private injectSharedHmrHtmlResponse;
     private tryHandleSharedApiRequest;