@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.8

package/src/create-app.js

@@ -0,0 +1,66 @@
+import { AbstractApplicationAdapter } from "./adapters/abstract/application-adapter.js";
+import { SharedApplicationAdapter } from "./adapters/shared/application-adapter.js";
+async function createRuntimeApp(options) {
+  const bun = globalThis.Bun;
+  if (bun) {
+    const { createApp: createBunApp } = await import("./adapters/bun/create-app.js");
+    return await createBunApp(options);
+  }
+  const { createNodeApp } = await import("./adapters/node/create-app.js");
+  return await createNodeApp(options);
+}
+async function createApp(options) {
+  return createRuntimeApp(options);
+}
+class EcopagesApp extends SharedApplicationAdapter {
+  appOptions;
+  runtimeApp = null;
+  runtimeAppPromise = null;
+  constructor(options) {
+    super(options);
+    this.appOptions = options;
+  }
+  async getRuntimeApp() {
+    if (this.runtimeApp) {
+      return this.runtimeApp;
+    }
+    if (!this.runtimeAppPromise) {
+      this.runtimeAppPromise = createRuntimeApp({
+        ...this.appOptions,
+        clearOutput: false
+      }).then((app) => {
+        for (const handler of this.apiHandlers) {
+          app.add(handler);
+        }
+        for (const route of this.staticRoutes) {
+          app.static(route.path, route.loader);
+        }
+        if (this.errorHandler) {
+          app.onError(this.errorHandler);
+        }
+        this.runtimeApp = app;
+        return app;
+      });
+    }
+    return this.runtimeAppPromise;
+  }
+  async initializeServerAdapter() {
+    return this.getRuntimeApp();
+  }
+  async start() {
+    const runtimeApp = await this.getRuntimeApp();
+    return runtimeApp.start();
+  }
+  async fetch(request) {
+    const runtimeApp = await this.getRuntimeApp();
+    const candidate = runtimeApp;
+    if (!candidate.fetch) {
+      throw new Error("The selected runtime adapter does not expose fetch()");
+    }
+    return candidate.fetch(request);
+  }
+}
+export {
+  EcopagesApp,
+  createApp
+};

package/src/dev/sc-server.d.ts

@@ -0,0 +1,30 @@
+import type { Server } from 'bun';
+import type { EcoPagesAppConfig } from '../internal-types.js';
+type StaticContentServerOptions = {
+    port?: number;
+};
+/**
+ * Static content server for production builds.
+ * Serves pre-built static files from the dist directory with gzip compression support.
+ */
+export declare class StaticContentServer {
+    server: Server<unknown> | null;
+    private appConfig;
+    private options;
+    constructor({ appConfig, options }: {
+        appConfig: EcoPagesAppConfig;
+        options?: StaticContentServerOptions;
+    });
+    private shouldServeGzip;
+    private isHtml;
+    private sendNotFoundPage;
+    private serveFromDir;
+    fetch(request: Request): Promise<Response>;
+    private startServer;
+    stop(): void;
+    static createServer({ appConfig, options, }: {
+        appConfig: EcoPagesAppConfig;
+        options?: StaticContentServerOptions;
+    }): StaticContentServer;
+}
+export {};

package/src/dev/sc-server.js

@@ -0,0 +1,111 @@
+import { extname, join } from "node:path";
+import { STATUS_MESSAGE } from "../constants.js";
+import { fileSystem } from "@ecopages/file-system";
+import { ServerUtils } from "../utils/server-utils.module.js";
+import { getRequiredBunRuntime } from "../utils/runtime.js";
+class StaticContentServer {
+  server = null;
+  appConfig;
+  options = { port: 3e3 };
+  constructor({ appConfig, options }) {
+    this.appConfig = appConfig;
+    if (options) this.options = options;
+    this.startServer();
+  }
+  shouldServeGzip(contentType) {
+    return ["text/javascript", "text/css"].includes(contentType);
+  }
+  isHtml(contentType) {
+    return contentType === "text/html";
+  }
+  async sendNotFoundPage() {
+    const error404TemplatePath = `${this.appConfig.absolutePaths.distDir}/404.html`;
+    try {
+      fileSystem.exists(error404TemplatePath);
+    } catch {
+      return new Response(STATUS_MESSAGE[404], {
+        status: 404
+      });
+    }
+    const response = new Response(fileSystem.readFileAsBuffer(error404TemplatePath), {
+      headers: { "Content-Type": "text/html" }
+    });
+    return response;
+  }
+  async serveFromDir({ path, request }) {
+    const { absolutePaths } = this.appConfig;
+    const basePath = join(absolutePaths.distDir, path);
+    const contentType = ServerUtils.getContentType(extname(basePath));
+    const acceptsGzip = request.headers.get("Accept-Encoding")?.includes("gzip");
+    try {
+      if (acceptsGzip && this.shouldServeGzip(contentType)) {
+        const gzipPath = `${basePath}.gz`;
+        if (fileSystem.exists(gzipPath)) {
+          const file = fileSystem.readFileAsBuffer(gzipPath);
+          return new Response(file, {
+            headers: {
+              "Content-Type": contentType,
+              "Content-Encoding": "gzip",
+              Vary: "Accept-Encoding"
+            }
+          });
+        }
+      }
+      if (path.includes(".") && fileSystem.exists(basePath)) {
+        const file = fileSystem.readFileAsBuffer(basePath);
+        return new Response(file, {
+          headers: { "Content-Type": contentType }
+        });
+      }
+      const htmlCandidates = [`${basePath}.html`, `${basePath}/index.html`];
+      for (const candidate of htmlCandidates) {
+        if (fileSystem.exists(candidate)) {
+          const file = fileSystem.readFileAsBuffer(candidate);
+          return new Response(file, {
+            headers: {
+              "Content-Type": ServerUtils.getContentType(extname(candidate))
+            }
+          });
+        }
+      }
+      return this.sendNotFoundPage();
+    } catch {
+      return this.sendNotFoundPage();
+    }
+  }
+  async fetch(request) {
+    let reqPath = new URL(request.url).pathname;
+    if (reqPath === "/") reqPath = "/index.html";
+    const response = this.serveFromDir({
+      path: reqPath,
+      request
+    });
+    if (response) return response;
+    return new Response(STATUS_MESSAGE[404], {
+      status: 404
+    });
+  }
+  startServer() {
+    this.server = getRequiredBunRuntime().serve({
+      fetch: this.fetch.bind(this),
+      port: this.options.port
+    });
+  }
+  stop() {
+    if (this.server) {
+      this.server.stop(true);
+    }
+  }
+  static createServer({
+    appConfig,
+    options
+  }) {
+    return new StaticContentServer({
+      appConfig,
+      options
+    });
+  }
+}
+export {
+  StaticContentServer
+};

package/src/eco/component-render-context.d.ts

@@ -0,0 +1,105 @@
+import type { EcoComponent } from '../public-types.js';
+import type { MarkerNodeId } from '../route-renderer/component-graph/component-marker.js';
+/**
+ * Outcome returned by boundary policy during one component render pass.
+ *
+ * - `inline`: render the target component immediately in the current pass
+ * - `defer`: emit an `eco-marker` and resolve it during the marker graph phase
+ */
+export type BoundaryRenderMode = 'inline' | 'defer';
+/**
+ * Input provided to boundary policy when a component boundary is reached.
+ *
+ * This keeps `eco.component()` decoupled from concrete integration/plugin
+ * objects while still giving policy enough information to decide whether the
+ * boundary should render immediately or be deferred.
+ */
+export type BoundaryRenderDecisionInput = {
+    currentIntegration: string;
+    targetIntegration?: string;
+    component: EcoComponent;
+};
+/**
+ * Narrow render-pass facade used by `eco.component()` for boundary decisions.
+ *
+ * The boundary context is intentionally small so component rendering can remain
+ * unaware of integration registries, plugin instances, or renderer lifecycles.
+ */
+export type ComponentRenderBoundaryContext = {
+    /**
+     * Decides whether the next component boundary should render inline or defer to
+     * the marker graph stage.
+     *
+     * @param input Boundary metadata for the current render pass.
+     * @returns Boundary rendering mode for the target component.
+     */
+    decideBoundaryRender(input: BoundaryRenderDecisionInput): BoundaryRenderMode;
+};
+/**
+ * Per-render mutable state used while collecting marker graph references.
+ *
+ * Counters generate deterministic ids within one render execution.
+ */
+type ComponentRenderContext = {
+    currentIntegration: string;
+    boundaryContext: ComponentRenderBoundaryContext;
+    nextNodeId: number;
+    nextPropsRefId: number;
+    nextSlotRefId: number;
+    propsByRef: Record<string, Record<string, unknown>>;
+    slotChildrenByRef: Record<string, MarkerNodeId[]>;
+};
+/**
+ * Serializable graph context captured from one render execution.
+ *
+ * This payload is merged with explicit page-module graph context before marker
+ * resolution in the route renderer.
+ */
+export type ComponentGraphContext = {
+    propsByRef: Record<string, Record<string, unknown>>;
+    slotChildrenByRef: Record<string, MarkerNodeId[]>;
+};
+/**
+ * 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;
+/**
+ * Allocates the next marker node id in the active render context.
+ *
+ * @param context Active render context.
+ * @returns Stable marker node id for this render pass.
+ */
+export declare function createNodeId(context: ComponentRenderContext): MarkerNodeId;
+/**
+ * Allocates the next props reference id in the active render context.
+ *
+ * @param context Active render context.
+ * @returns Props reference key.
+ */
+export declare function createPropsRef(context: ComponentRenderContext): string;
+/**
+ * Allocates the next slot reference id in the active render context.
+ *
+ * @param context Active render context.
+ * @returns Slot reference key.
+ */
+export declare function createSlotRef(context: ComponentRenderContext): string;
+/**
+ * Runs render work under a fresh component render context and returns both:
+ * - the render result value
+ * - captured graph reference maps for downstream marker resolution
+ *
+ * @param input Execution metadata for current integration and boundary policy.
+ * @param render Async render function to execute inside the context.
+ * @returns Render result and captured graph context maps.
+ */
+export declare function runWithComponentRenderContext<T>(input: {
+    currentIntegration: string;
+    boundaryContext: ComponentRenderBoundaryContext;
+}, render: () => Promise<T>): Promise<{
+    value: T;
+    graphContext: ComponentGraphContext;
+}>;
+export {};

package/src/eco/component-render-context.js

@@ -0,0 +1,87 @@
+const GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY = "__ECOPAGES_COMPONENT_RENDER_CONTEXT_STATE__";
+function getComponentRenderContextState() {
+  const globalScope = globalThis;
+  globalScope[GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY] ??= {
+    contextStack: [],
+    nodeContextStorage: null,
+    nodeContextStorageLoader: null
+  };
+  return globalScope[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];
+}
+function createNodeId(context) {
+  context.nextNodeId += 1;
+  return `n_${context.nextNodeId}`;
+}
+function createPropsRef(context) {
+  context.nextPropsRefId += 1;
+  return `p_${context.nextPropsRefId}`;
+}
+function createSlotRef(context) {
+  context.nextSlotRefId += 1;
+  return `s_${context.nextSlotRefId}`;
+}
+async function runWithComponentRenderContext(input, render) {
+  const context = {
+    currentIntegration: input.currentIntegration,
+    boundaryContext: input.boundaryContext,
+    nextNodeId: 0,
+    nextPropsRefId: 0,
+    nextSlotRefId: 0,
+    propsByRef: {},
+    slotChildrenByRef: {}
+  };
+  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,
+    graphContext: {
+      propsByRef: context.propsByRef,
+      slotChildrenByRef: context.slotChildrenByRef
+    }
+  };
+}
+export {
+  createNodeId,
+  createPropsRef,
+  createSlotRef,
+  getComponentRenderContext,
+  runWithComponentRenderContext
+};

package/src/eco/eco.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The eco namespace - unified component and page factory API
+ * @module
+ */
+import type { Eco } from './eco.types.js';
+/**
+ * The eco namespace - provides factories for components and pages
+ */
+export declare const eco: Eco;

package/src/eco/eco.js

@@ -0,0 +1,114 @@
+import { createNodeId, createPropsRef, createSlotRef, getComponentRenderContext } from "./component-render-context.js";
+import { createComponentMarker, parseComponentMarkers } from "../route-renderer/component-graph/component-marker.js";
+import { getComponentReference } from "../route-renderer/component-graph/component-reference.js";
+import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from "./eco.utils.js";
+function createComponentFactory(options) {
+  const integrationName = options.integration ?? options.__eco?.integration;
+  const comp = ((props) => {
+    const renderContext = getComponentRenderContext();
+    const shouldEmitMarker = renderContext !== void 0 && renderContext.boundaryContext.decideBoundaryRender({
+      currentIntegration: renderContext.currentIntegration,
+      targetIntegration: integrationName,
+      component: comp
+    }) === "defer";
+    if (shouldEmitMarker && renderContext) {
+      const nodeId = createNodeId(renderContext);
+      const propsRef = createPropsRef(renderContext);
+      const componentRef = getComponentReference(comp);
+      const componentProps = props ?? {};
+      renderContext.propsByRef[propsRef] = componentProps;
+      let slotRef;
+      const children = componentProps.children;
+      if (typeof children === "string" && children.includes("<eco-marker")) {
+        const childMarkers = parseComponentMarkers(children);
+        if (childMarkers.length > 0) {
+          slotRef = createSlotRef(renderContext);
+          renderContext.slotChildrenByRef[slotRef] = childMarkers.map((marker) => marker.nodeId);
+        }
+      }
+      return createComponentMarker({
+        nodeId,
+        integration: integrationName,
+        componentRef,
+        propsRef,
+        slotRef
+      });
+    }
+    const content = options.render(props);
+    const lazyTriggers = comp.config?._resolvedLazyTriggers;
+    if (lazyTriggers && lazyTriggers.length > 0) {
+      const triggerId = lazyTriggers[0].triggerId;
+      if (isThenable(content)) {
+        return content.then((resolvedContent) => addTriggerAttribute(resolvedContent, triggerId));
+      }
+      return addTriggerAttribute(content, triggerId);
+    }
+    const lazyGroups = comp.config?._resolvedLazyScripts;
+    if (lazyGroups && lazyGroups.length > 0) {
+      if (isThenable(content)) {
+        return content.then((resolvedContent) => wrapWithScriptsInjector(resolvedContent, lazyGroups));
+      }
+      return wrapWithScriptsInjector(content, lazyGroups);
+    }
+    return content;
+  });
+  comp.config = {
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: options.dependencies
+  };
+  return comp;
+}
+function component(options) {
+  return createComponentFactory(options);
+}
+function html(options) {
+  return createComponentFactory(options);
+}
+function layout(options) {
+  return createComponentFactory(options);
+}
+function page(options) {
+  const { layout: layout2, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
+  const componentOptions = {
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: layout2 ? {
+      ...dependencies,
+      components: [...dependencies?.components || [], layout2]
+    } : dependencies,
+    render
+  };
+  const pageComponent = createComponentFactory(componentOptions);
+  if (layout2 && pageComponent.config) {
+    pageComponent.config.layout = layout2;
+  }
+  if (staticPaths2) pageComponent.staticPaths = staticPaths2;
+  if (staticProps2) pageComponent.staticProps = staticProps2;
+  if (metadata2) pageComponent.metadata = metadata2;
+  if (cache) pageComponent.cache = cache;
+  if (requires) pageComponent.requires = requires;
+  if (middleware) pageComponent.middleware = middleware;
+  return pageComponent;
+}
+function metadata(fn) {
+  return fn;
+}
+function staticPaths(fn) {
+  return fn;
+}
+function staticProps(fn) {
+  return fn;
+}
+const eco = {
+  component,
+  html,
+  layout,
+  page,
+  metadata,
+  staticPaths,
+  staticProps
+};
+export {
+  eco
+};