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

package/src/adapters/shared/define-api-handler.d.ts

@@ -1,25 +0,0 @@
-import type { ApiHandler, ApiHandlerContext, Middleware, RouteSchema, TypedGroupHandlerContext } from '../../types/public-types.js';
-type UniversalContext = ApiHandlerContext<Request, unknown>;
-type SchemaHandlerContext<TSchema extends RouteSchema | undefined, TContext extends UniversalContext> = TSchema extends RouteSchema ? TypedGroupHandlerContext<TSchema, TContext> : TContext;
-export declare function defineApiHandler<TPath extends string, TSchema extends RouteSchema | undefined = undefined, TContext extends UniversalContext = UniversalContext>(handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {
-    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
-    middleware?: Middleware<Request, unknown, TContext>[];
-    schema?: TSchema;
-}): ApiHandler<TPath, Request, unknown>;
-export interface GroupHandler<TPrefix extends string = string> {
-    prefix: TPrefix;
-    middleware?: readonly Middleware<Request, unknown, any>[];
-    routes: readonly ApiHandler<string, Request, unknown>[];
-}
-type GroupDefineHandler<TContext extends UniversalContext> = <const TPath extends string, TSchema extends RouteSchema | undefined = undefined>(handler: Omit<ApiHandler<TPath, Request, unknown>, 'handler' | 'middleware' | 'schema'> & {
-    path: TPath;
-    handler: (context: SchemaHandlerContext<TSchema, TContext>) => Promise<Response> | Response;
-    middleware?: Middleware<Request, unknown, TContext>[];
-    schema?: TSchema;
-}) => ApiHandler<TPath, Request, unknown>;
-export declare function defineGroupHandler<TPrefix extends string, TMiddleware extends readonly Middleware<Request, unknown, any>[] = [], TContext extends UniversalContext = TMiddleware extends readonly Middleware<Request, unknown, infer TGroupContext>[] ? TGroupContext : UniversalContext>(config: {
-    prefix: TPrefix;
-    middleware?: TMiddleware;
-    routes: (define: GroupDefineHandler<TContext>) => readonly ApiHandler<string, Request, unknown>[];
-}): GroupHandler<TPrefix>;
-export {};

package/src/adapters/shared/define-api-handler.js

@@ -1,15 +0,0 @@
-function defineApiHandler(handler) {
-  return handler;
-}
-function defineGroupHandler(config) {
-  const define = ((handler) => handler);
-  return {
-    prefix: config.prefix,
-    middleware: config.middleware,
-    routes: config.routes(define)
-  };
-}
-export {
-  defineApiHandler,
-  defineGroupHandler
-};

package/src/adapters/shared/hmr-entrypoint-registrar.js

@@ -1,87 +0,0 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { appLogger } from "../../global/app-logger.js";
-import { RESOLVED_ASSETS_DIR } from "../../config/constants.js";
-class HmrEntrypointRegistrar {
-  options;
-  constructor(options) {
-    this.options = options;
-  }
-  /**
-   * Registers a single source entrypoint and returns the browser URL for its emitted HMR module.
-   *
-   * Concurrent requests for the same normalized entrypoint share the same in-flight promise so the
-   * integration only builds once per registration cycle.
-   */
-  async registerEntrypoint(entrypointPath, registrationOptions) {
-    const normalizedEntrypoint = path.resolve(entrypointPath);
-    const existingRegistration = this.options.entrypointRegistrations.get(normalizedEntrypoint);
-    if (existingRegistration) {
-      return await this.awaitEntrypointRegistration(existingRegistration, normalizedEntrypoint);
-    }
-    const registration = this.registerEntrypointInternal(normalizedEntrypoint, registrationOptions);
-    this.options.entrypointRegistrations.set(normalizedEntrypoint, registration);
-    try {
-      return await this.awaitEntrypointRegistration(registration, normalizedEntrypoint);
-    } catch (error) {
-      this.options.clearFailedRegistration?.(normalizedEntrypoint);
-      throw error;
-    } finally {
-      this.options.entrypointRegistrations.delete(normalizedEntrypoint);
-    }
-  }
-  async registerEntrypointInternal(entrypointPath, registrationOptions) {
-    if (this.options.watchedFiles.has(entrypointPath)) {
-      return this.options.watchedFiles.get(entrypointPath);
-    }
-    const { outputPath, outputUrl } = this.getEntrypointOutput(entrypointPath);
-    this.options.watchedFiles.set(entrypointPath, outputUrl);
-    this.removeStaleEntrypointOutput(outputPath);
-    await registrationOptions.emit(entrypointPath, outputPath);
-    if (!fileSystem.exists(outputPath)) {
-      throw registrationOptions.getMissingOutputError(entrypointPath, outputPath);
-    }
-    return outputUrl;
-  }
-  async awaitEntrypointRegistration(registration, entrypointPath) {
-    if (process.env.NODE_ENV !== "development") {
-      return await registration;
-    }
-    return await Promise.race([
-      registration,
-      new Promise((_, reject) => {
-        setTimeout(() => {
-          reject(new Error(`[HMR] Timed out registering entrypoint: ${entrypointPath}`));
-        }, this.options.registrationTimeoutMs);
-      })
-    ]);
-  }
-  getEntrypointOutput(entrypointPath) {
-    const relativePath = path.relative(this.options.srcDir, entrypointPath);
-    const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, ".js");
-    const encodedPathJs = this.encodeDynamicSegments(relativePathJs);
-    const urlPath = encodedPathJs.split(path.sep).join("/");
-    return {
-      outputUrl: `/${path.join(RESOLVED_ASSETS_DIR, "_hmr", urlPath)}`,
-      outputPath: path.join(this.options.distDir, urlPath)
-    };
-  }
-  removeStaleEntrypointOutput(outputPath) {
-    if (!fileSystem.exists(outputPath)) {
-      return;
-    }
-    try {
-      fileSystem.remove(outputPath);
-    } catch (error) {
-      appLogger.warn(
-        `[HMR] Failed to remove stale entrypoint output ${outputPath}: ${error instanceof Error ? error.message : String(error)}`
-      );
-    }
-  }
-  encodeDynamicSegments(filepath) {
-    return filepath.replace(/\[([^\]]+)\]/g, "_$1_");
-  }
-}
-export {
-  HmrEntrypointRegistrar
-};

package/src/adapters/shared/server-adapter.js

@@ -1,436 +0,0 @@
-import path from "node:path";
-import { AbstractServerAdapter } from "../abstract/server-adapter.js";
-import { RouteRendererFactory } from "../../route-renderer/route-renderer.js";
-import { RouteRegistry } from "../../router/server/route-registry.js";
-import { MemoryCacheStore } from "../../services/cache/memory-cache-store.js";
-import { PageCacheService } from "../../services/cache/page-cache-service.js";
-import { SchemaValidationService } from "../../services/validation/schema-validation-service.js";
-import { StaticSiteGenerator } from "../../static-site-generator/static-site-generator.js";
-import { ServerStaticBuilder } from "./server-static-builder.js";
-import { ExplicitStaticRouteMatcher } from "./explicit-static-route-matcher.js";
-import { FileSystemServerResponseFactory } from "./fs-server-response-factory.js";
-import { FileSystemResponseMatcher } from "./fs-server-response-matcher.js";
-import { ServerRouteHandler } from "./server-route-handler.js";
-import { createRenderContext } from "./render-context.js";
-import { createRequire } from "../../utils/locals-utils.js";
-import { HttpError } from "../../errors/http-error.js";
-import { ApiResponseBuilder } from "./api-response.js";
-import { appLogger } from "../../global/app-logger.js";
-import { fileSystem } from "@ecopages/file-system";
-import { getAppServerModuleTranspiler } from "../../services/module-loading/app-server-module-transpiler.service.js";
-import { resolveInternalExecutionDir } from "../../utils/resolve-work-dir.js";
-class SharedServerAdapter extends AbstractServerAdapter {
-  router;
-  fileSystemResponseMatcher;
-  routeRendererFactory;
-  routeHandler;
-  staticSiteGenerator;
-  staticBuilder;
-  schemaValidator = new SchemaValidationService();
-  async initializeSharedRouteHandling(options) {
-    await this.initSharedRouter();
-    this.configureSharedResponseHandlers(options.staticRoutes, options.hmrManager);
-  }
-  createSharedWatchRefreshCallback(options) {
-    return async () => {
-      try {
-        await this.initializeSharedRouteHandling({
-          staticRoutes: options.staticRoutes,
-          hmrManager: options.hmrManager
-        });
-        if (options.onRoutesReady) {
-          await options.onRoutesReady();
-        }
-      } catch (error) {
-        if (options.onError) {
-          await options.onError(error instanceof Error ? error : new Error(String(error)));
-          return;
-        }
-        throw error;
-      }
-    };
-  }
-  /**
-   * Scans the filesystem and dynamically constructs the Route Registry.
-   *
-   * This process runs identically across both Bun and Node wrappers. It analyzes the configured pages
-   * directory, building a map of all available UI routes and API endpoints.
-   * The resulting `RouteRegistry` instance becomes the central nervous system for mapping WinterCG incoming
-   * Web Requests (`Request`) to their corresponding internal execution paths.
-   */
-  async initSharedRouter() {
-    this.router = new RouteRegistry({
-      pagesDir: path.join(this.appConfig.rootDir, this.appConfig.srcDir, this.appConfig.pagesDir),
-      appConfig: this.appConfig,
-      origin: this.runtimeOrigin,
-      templatesExt: this.appConfig.templatesExt,
-      buildMode: !this.options?.watch,
-      pageModuleAdapter: this.createRouteRegistryPageModuleAdapter()
-    });
-    await this.router.init();
-  }
-  createRouteRegistryPageModuleAdapter() {
-    const serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
-    return {
-      loadPageModule: async (filePath) => {
-        const module = await serverModuleTranspiler.importModule({
-          filePath,
-          outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-route-modules"),
-          externalPackages: true,
-          transpileErrorMessage: (details) => `Error transpiling route module: ${details}`,
-          noOutputMessage: (targetFilePath) => `No transpiled output generated for route module: ${targetFilePath}`
-        });
-        const page = module.default;
-        return {
-          staticPaths: page?.staticPaths ?? module.getStaticPaths,
-          staticProps: page?.staticProps ?? module.getStaticProps
-        };
-      }
-    };
-  }
-  /**
-   * Sets up the unified rendering pipeline and response matching chain.
-   *
-   * It bridges several sub-systems together so that when an incoming request is received, the adapter knows:
-   * 1. How to render React/Lit pages via `RouteRendererFactory`
-   * 2. How to match logical routes to physical filesystem artifacts via `FileSystemResponseMatcher`
-   * 3. Whether to serve the response from the embedded `PageCacheService` or generate it fresh on the fly.
-   *
-   * Because `HmrManager` implementations rely heavily on runtime-specific WebSocket APIs (e.g. Bun.serve Websockets vs Node WS),
-   * we leave it untyped (`any`) here at the common denominator core.
-   *
-   * @param staticRoutes - A map of explicitly served static assets.
-   * @param hmrManager - The runtime-specific Hot Module Replacement orchestrator (if watching).
-   */
-  configureSharedResponseHandlers(staticRoutes, hmrManager) {
-    this.routeRendererFactory = new RouteRendererFactory({
-      appConfig: this.appConfig,
-      rendererModules: this.appConfig.runtime?.rendererModuleContext,
-      runtimeOrigin: this.runtimeOrigin
-    });
-    const { fileSystemResponseMatcher, explicitStaticRouteMatcher } = this.createSharedResponseHandlerDependencies(staticRoutes);
-    this.fileSystemResponseMatcher = fileSystemResponseMatcher;
-    this.routeHandler = new ServerRouteHandler({
-      router: this.router,
-      fileSystemResponseMatcher: this.fileSystemResponseMatcher,
-      explicitStaticRouteMatcher,
-      watch: !!this.options?.watch,
-      hmrManager
-    });
-  }
-  createSharedResponseHandlerDependencies(staticRoutes) {
-    const fileSystemResponseFactory = new FileSystemServerResponseFactory({
-      options: {
-        watchMode: !!this.options?.watch
-      }
-    });
-    const cacheService = this.createSharedPageCacheService();
-    const fileSystemResponseMatcher = new FileSystemResponseMatcher({
-      appConfig: this.appConfig,
-      assetPrefix: path.join(this.appConfig.rootDir, this.appConfig.distDir),
-      router: this.router,
-      routeRendererFactory: this.routeRendererFactory,
-      fileSystemResponseFactory,
-      cacheService,
-      defaultCacheStrategy: this.appConfig.cache?.defaultStrategy ?? "static"
-    });
-    return {
-      cacheService,
-      fileSystemResponseMatcher,
-      explicitStaticRouteMatcher: staticRoutes.length > 0 ? new ExplicitStaticRouteMatcher({
-        appConfig: this.appConfig,
-        routeRendererFactory: this.routeRendererFactory,
-        staticRoutes
-      }) : void 0
-    };
-  }
-  createSharedPageCacheService() {
-    const cacheConfig = this.appConfig.cache;
-    const isCacheEnabled = cacheConfig?.enabled ?? !this.options?.watch;
-    if (!isCacheEnabled) {
-      return null;
-    }
-    const store = cacheConfig?.store === "memory" || !cacheConfig?.store ? new MemoryCacheStore({ maxEntries: cacheConfig?.maxEntries }) : cacheConfig.store;
-    return new PageCacheService({ store, enabled: true });
-  }
-  getCacheService() {
-    return this.fileSystemResponseMatcher?.getCacheService() ?? null;
-  }
-  getRenderContext() {
-    const serverModuleTranspiler = getAppServerModuleTranspiler(this.appConfig);
-    return createRenderContext({
-      integrations: this.appConfig.integrations,
-      rendererModules: this.appConfig.runtime?.rendererModuleContext,
-      importServerModule: async (filePath) => await serverModuleTranspiler.importModule({
-        filePath,
-        outdir: path.join(resolveInternalExecutionDir(this.appConfig), ".server-modules"),
-        externalPackages: true,
-        bypassCache: this.options?.watch === true
-      })
-    });
-  }
-  /**
-   * Executes an Application Programming Interface (API) handler in an environment-agnostic manner.
-   *
-   * API routes in Ecopages are universally written using standard WinterCG `Request` and `Response` objects.
-   * This execution pipeline takes the raw `Request`, extracts its dynamic segments, runs our high-speed JSON schema
-   * validator against the body/query/headers, and triggers the developer's middleware chain sequentially.
-   *
-   * If the execution throws an error, it is gracefully caught, logged, and mutated into a standardized Http error payload,
-   * ensuring the consuming client receives a parsable response even upon internal catastrophic failure.
-   *
-   * @param request - The incoming Web standard `Request`.
-   * @param params - The extracted dynamic URL parameters (e.g., `{ id: '123' }`).
-   * @param routeConfig - The user-defined API handler object containing their business logic (`handler`) and `middleware`.
-   * @param serverInstance - Untyped reference to the underlying native server instance (BunServer/NodeServer) for potential escape hatches.
-   * @param errorHandler - Optional global error trap defined in project configuration.
-   * @returns The resulting Web standard `Response` constructed by the user's handler.
-   */
-  async executeApiHandler(request, params, routeConfig, serverInstance, errorHandler) {
-    let context;
-    try {
-      context = this.createApiHandlerContext(request, params, serverInstance);
-      const schemaResponse = await this.applyApiRequestSchema(context, routeConfig.schema);
-      if (schemaResponse) {
-        return schemaResponse;
-      }
-      return await this.runApiMiddlewareChain(context, routeConfig);
-    } catch (error) {
-      if (error instanceof Response) return error;
-      if (errorHandler) {
-        try {
-          if (!context) {
-            context = this.createApiHandlerContext(request, params, serverInstance);
-          }
-          return await errorHandler(error, context);
-        } catch (handlerError) {
-          appLogger.error(`[ecopages] Error in custom error handler: ${handlerError}`);
-        }
-      }
-      if (error instanceof HttpError) return error.toResponse();
-      appLogger.error(`[ecopages] Error handling API request: ${error}`);
-      return new Response("Internal Server Error", { status: 500 });
-    }
-  }
-  createApiHandlerContext(request, params, serverInstance) {
-    const locals = {};
-    const normalizedParams = this.normalizeApiParams(params);
-    return {
-      request,
-      params: normalizedParams,
-      response: new ApiResponseBuilder(),
-      server: serverInstance,
-      locals,
-      require: createRequire(() => locals),
-      services: {
-        cache: this.getCacheService()
-      },
-      ...this.getRenderContext()
-    };
-  }
-  normalizeApiParams(params) {
-    return Object.fromEntries(
-      Object.entries(params).map(([key, value]) => [key, Array.isArray(value) ? value.join("/") : value])
-    );
-  }
-  async applyApiRequestSchema(context, schema) {
-    if (!schema) {
-      return void 0;
-    }
-    const url = new URL(context.request.url);
-    const queryParams = Object.fromEntries(url.searchParams);
-    const headers = Object.fromEntries(context.request.headers);
-    let body;
-    if (schema.body) {
-      try {
-        const contentType = context.request.headers.get("Content-Type") || "";
-        if (contentType.includes("application/json")) body = await context.request.clone().json();
-        else if (contentType.includes("text/plain")) body = await context.request.clone().text();
-      } catch {
-        return context.response.status(400).json({ error: "Invalid request body" });
-      }
-    }
-    const validationResult = await this.schemaValidator.validateRequest(
-      { body, query: queryParams, headers, params: context.params },
-      schema
-    );
-    if (!validationResult.success) {
-      return context.response.status(400).json({
-        error: "Validation failed",
-        issues: validationResult.errors
-      });
-    }
-    const validated = validationResult.data;
-    if (validated.body !== void 0) context.body = validated.body;
-    if (validated.query !== void 0) context.query = validated.query;
-    if (validated.headers !== void 0) context.headers = validated.headers;
-    if (validated.params !== void 0) context.params = validated.params;
-    return void 0;
-  }
-  async runApiMiddlewareChain(context, routeConfig) {
-    const middleware = routeConfig.middleware || [];
-    if (middleware.length === 0) {
-      return await routeConfig.handler(context);
-    }
-    let index = 0;
-    const executeNext = async () => {
-      if (index < middleware.length) {
-        const currentMiddleware = middleware[index++];
-        return await currentMiddleware(context, executeNext);
-      }
-      return await routeConfig.handler(context);
-    };
-    return await executeNext();
-  }
-  normalizePath(pathname) {
-    if (pathname.length > 1 && pathname.endsWith("/")) {
-      return pathname.slice(0, -1);
-    }
-    return pathname;
-  }
-  matchApiPath(pattern, pathname) {
-    const normalizedPattern = this.normalizePath(pattern);
-    const normalizedPathname = this.normalizePath(pathname);
-    const patternSegments = normalizedPattern.split("/").filter(Boolean);
-    const pathSegments = normalizedPathname.split("/").filter(Boolean);
-    const params = {};
-    let patternIndex = 0;
-    let pathIndex = 0;
-    while (patternIndex < patternSegments.length && pathIndex < pathSegments.length) {
-      const patternSegment = patternSegments[patternIndex];
-      const pathSegment = pathSegments[pathIndex];
-      if (patternSegment === "*") {
-        return params;
-      }
-      if (patternSegment.startsWith("[...") && patternSegment.endsWith("]")) {
-        const paramName = patternSegment.slice(4, -1);
-        params[paramName] = pathSegments.slice(pathIndex);
-        return params;
-      }
-      if (patternSegment.startsWith(":")) {
-        params[patternSegment.slice(1)] = pathSegment;
-        patternIndex++;
-        pathIndex++;
-        continue;
-      }
-      if (patternSegment.startsWith("[") && patternSegment.endsWith("]")) {
-        params[patternSegment.slice(1, -1)] = pathSegment;
-        patternIndex++;
-        pathIndex++;
-        continue;
-      }
-      if (patternSegment !== pathSegment) {
-        return null;
-      }
-      patternIndex++;
-      pathIndex++;
-    }
-    if (patternIndex < patternSegments.length) {
-      const remaining = patternSegments.slice(patternIndex);
-      const catchAll = remaining[0];
-      if (remaining.length === 1 && (catchAll === "*" || catchAll.startsWith("[...") && catchAll.endsWith("]"))) {
-        if (catchAll.startsWith("[...")) {
-          const paramName = catchAll.slice(4, -1);
-          params[paramName] = [];
-        }
-        return params;
-      }
-      return null;
-    }
-    if (pathIndex < pathSegments.length) {
-      return null;
-    }
-    return params;
-  }
-  getApiPathScore(pattern) {
-    const segments = this.normalizePath(pattern).split("/").filter(Boolean);
-    let score = 0;
-    for (const segment of segments) {
-      if (segment === "*" || segment.startsWith("[...") && segment.endsWith("]")) {
-        score += 10;
-      } else if (segment.startsWith(":") || segment.startsWith("[") && segment.endsWith("]")) {
-        score += 50;
-      } else {
-        score += 100;
-      }
-    }
-    return score;
-  }
-  matchApiHandler(request, apiHandlers) {
-    const pathname = new URL(request.url).pathname;
-    const method = request.method.toUpperCase();
-    const sortedHandlers = [...apiHandlers].sort((a, b) => {
-      return this.getApiPathScore(b.path) - this.getApiPathScore(a.path);
-    });
-    for (const routeConfig of sortedHandlers) {
-      const routeMethod = (routeConfig.method || "GET").toUpperCase();
-      if (routeMethod !== method) {
-        continue;
-      }
-      const params = this.matchApiPath(routeConfig.path, pathname);
-      if (params) {
-        return { routeConfig, params };
-      }
-    }
-    return null;
-  }
-  tryHandleSharedHmrRequest(request, context) {
-    const url = new URL(request.url);
-    if (url.pathname === "/_hmr_runtime.js" && context.hmrManager) {
-      const runtimePath = context.hmrManager.getRuntimePath();
-      if (fileSystem.exists(runtimePath)) {
-        return new Response(fileSystem.readFileAsBuffer(runtimePath), {
-          headers: { "Content-Type": "application/javascript" }
-        });
-      }
-    }
-    if (url.pathname.startsWith("/assets/_hmr/") && context.hmrManager) {
-      const relativePath = url.pathname.slice("/assets/_hmr/".length);
-      const assetPath = path.join(context.hmrManager.getDistDir(), relativePath);
-      if (fileSystem.exists(assetPath)) {
-        return new Response(fileSystem.readFileAsBuffer(assetPath), {
-          headers: { "Content-Type": "application/javascript" }
-        });
-      }
-    }
-    return null;
-  }
-  async tryHandleSharedApiRequest(request, context) {
-    const apiMatch = this.matchApiHandler(request, context.apiHandlers);
-    if (!apiMatch) {
-      return null;
-    }
-    return await this.executeApiHandler(
-      request,
-      apiMatch.params,
-      apiMatch.routeConfig,
-      context.serverInstance,
-      context.errorHandler
-    );
-  }
-  /**
-   * Universally processes an incoming WinterCG Web standard Request.
-   *
-   * 1. Resolves static Hot Module Replacement runtime blobs if development.
-   * 2. Checks if the incoming request matches any parsed API route schemas.
-   *   - Routes through `executeApiHandler` which performs strict validation.
-   * 3. Falls through to standard `ServerRouteHandler` for React/Lit filesystem pages.
-   *
-   * Both Bun and Node bindings fall back to this exact function once they have mapped their
-   * native HTTP objects into Web Standard Requests.
-   */
-  async handleSharedRequest(request, context) {
-    const hmrResponse = this.tryHandleSharedHmrRequest(request, context);
-    if (hmrResponse) {
-      return hmrResponse;
-    }
-    const apiResponse = await this.tryHandleSharedApiRequest(request, context);
-    if (apiResponse) {
-      return apiResponse;
-    }
-    return this.routeHandler.handleResponse(request);
-  }
-}
-export {
-  SharedServerAdapter
-};