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

package/src/services/runtime-state/server-invalidation-state.service.d.ts

@@ -0,0 +1,26 @@
+import type { EcoPagesAppConfig } from '../../internal-types.js';
+/**
+ * App-owned coarse invalidation state for server-executed modules.
+ */
+export interface ServerInvalidationState {
+    getServerInvalidationVersion(): number;
+    invalidateServerModules(changedFiles?: string[]): void;
+    reset(): void;
+}
+/**
+ * Minimal app-local invalidation state backed by a single generation counter.
+ */
+export declare class CounterServerInvalidationState implements ServerInvalidationState {
+    private serverInvalidationVersion;
+    getServerInvalidationVersion(): number;
+    invalidateServerModules(_changedFiles?: string[]): void;
+    reset(): void;
+}
+/**
+ * Returns the app-owned server invalidation state.
+ */
+export declare function getAppServerInvalidationState(appConfig: EcoPagesAppConfig): ServerInvalidationState;
+/**
+ * Installs the invalidation state used by one app instance.
+ */
+export declare function setAppServerInvalidationState(appConfig: EcoPagesAppConfig, serverInvalidationState: ServerInvalidationState): void;

package/src/services/runtime-state/server-invalidation-state.service.js

@@ -0,0 +1,35 @@
+class CounterServerInvalidationState {
+  serverInvalidationVersion = 0;
+  getServerInvalidationVersion() {
+    return this.serverInvalidationVersion;
+  }
+  invalidateServerModules(_changedFiles) {
+    this.serverInvalidationVersion += 1;
+  }
+  reset() {
+    this.serverInvalidationVersion += 1;
+  }
+}
+function isLegacyServerInvalidationState(value) {
+  return Boolean(value) && typeof value === "object" && typeof value.getServerInvalidationVersion === "function" && typeof value.invalidateServerModules === "function" && typeof value.reset === "function";
+}
+function getAppServerInvalidationState(appConfig) {
+  if (appConfig.runtime?.serverInvalidationState) {
+    return appConfig.runtime.serverInvalidationState;
+  }
+  if (isLegacyServerInvalidationState(appConfig.runtime?.devGraphService)) {
+    return appConfig.runtime.devGraphService;
+  }
+  return new CounterServerInvalidationState();
+}
+function setAppServerInvalidationState(appConfig, serverInvalidationState) {
+  appConfig.runtime = {
+    ...appConfig.runtime ?? {},
+    serverInvalidationState
+  };
+}
+export {
+  CounterServerInvalidationState,
+  getAppServerInvalidationState,
+  setAppServerInvalidationState
+};

package/src/services/validation/schema-validation-service.d.ts

@@ -0,0 +1,122 @@
+import type { StandardSchema } from './standard-schema.types.js';
+export interface ValidationResult<T = unknown> {
+    success: boolean;
+    data?: T;
+    errors?: Array<{
+        message: string;
+        path?: Array<string | number>;
+    }>;
+}
+export interface ValidationSource {
+    body?: unknown;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+}
+export interface ValidationSchemas {
+    body?: StandardSchema;
+    query?: StandardSchema;
+    headers?: StandardSchema;
+    params?: StandardSchema;
+}
+export interface ValidatedData {
+    body?: unknown;
+    query?: unknown;
+    headers?: unknown;
+    params?: unknown;
+}
+/**
+ * Service for validating request data using Standard Schema compliant validators.
+ *
+ * This service provides a unified interface for validating HTTP request data (body, query parameters, headers)
+ * using any validation library that implements the Standard Schema specification.
+ *
+ * @example Using with Zod
+ * ```typescript
+ * import { z } from 'zod';
+ * import { SchemaValidationService } from './schema-validation-service.js';
+ *
+ * const service = new SchemaValidationService();
+ * const result = await service.validateRequest(
+ *   { body: { title: 'Hello', count: 42 } },
+ *   { body: z.object({ title: z.string(), count: z.number() }) }
+ * );
+ *
+ * if (result.success) {
+ *   console.log(result.data.body);
+ * }
+ * ```
+ *
+ * @example Using with Valibot
+ * ```typescript
+ * import * as v from 'valibot';
+ *
+ * const result = await service.validateRequest(
+ *   { query: { page: '1' } },
+ *   { query: v.object({ page: v.string() }) }
+ * );
+ * ```
+ *
+ * @example Using with ArkType
+ * ```typescript
+ * import { type } from 'arktype';
+ *
+ * const result = await service.validateRequest(
+ *   { headers: { 'authorization': 'Bearer token' } },
+ *   { headers: type({ authorization: 'string' }) }
+ * );
+ * ```
+ *
+ * @example Multiple sources
+ * ```typescript
+ * const result = await service.validateRequest(
+ *   {
+ *     body: { title: 'Post' },
+ *     query: { format: 'json' },
+ *     headers: { 'content-type': 'application/json' }
+ *   },
+ *   {
+ *     body: z.object({ title: z.string() }),
+ *     query: v.object({ format: v.string() }),
+ *     headers: type({ 'content-type': 'string' })
+ *   }
+ * );
+ * ```
+ *
+ * Supported libraries: Zod, Valibot, ArkType, Effect Schema (with standardSchemaV1 wrapper)
+ */
+export declare class SchemaValidationService {
+    /**
+     * Validates request data against provided schemas.
+     *
+     * Validates body, query parameters, and headers against their respective schemas.
+     * All validations are performed, and errors are aggregated from all sources.
+     *
+     * @param source - The data to validate (body, query, headers)
+     * @param schemas - The Standard Schema validators for each source
+     * @returns Validation result with validated data or aggregated errors
+     *
+     * @example
+     * ```typescript
+     * const result = await service.validateRequest(
+     *   { body: { name: 'John', age: 30 } },
+     *   { body: z.object({ name: z.string(), age: z.number() }) }
+     * );
+     *
+     * if (result.success) {
+     *   const validated = result.data.body;
+     * } else {
+     *   console.error(result.errors);
+     * }
+     * ```
+     */
+    validateRequest(source: ValidationSource, schemas: ValidationSchemas): Promise<ValidationResult<ValidatedData>>;
+    /**
+     * Validates a single value against a Standard Schema.
+     *
+     * @param schema - The Standard Schema validator
+     * @param data - The data to validate
+     * @returns Validation result with validated data or errors
+     */
+    private validateWithSchema;
+}

package/src/services/validation/schema-validation-service.js

@@ -0,0 +1,101 @@
+class SchemaValidationService {
+  /**
+   * Validates request data against provided schemas.
+   *
+   * Validates body, query parameters, and headers against their respective schemas.
+   * All validations are performed, and errors are aggregated from all sources.
+   *
+   * @param source - The data to validate (body, query, headers)
+   * @param schemas - The Standard Schema validators for each source
+   * @returns Validation result with validated data or aggregated errors
+   *
+   * @example
+   * ```typescript
+   * const result = await service.validateRequest(
+   *   { body: { name: 'John', age: 30 } },
+   *   { body: z.object({ name: z.string(), age: z.number() }) }
+   * );
+   *
+   * if (result.success) {
+   *   const validated = result.data.body;
+   * } else {
+   *   console.error(result.errors);
+   * }
+   * ```
+   */
+  async validateRequest(source, schemas) {
+    const validated = {};
+    const allErrors = [];
+    if (schemas.body && source.body !== void 0) {
+      const result = await this.validateWithSchema(schemas.body, source.body);
+      if (!result.success) {
+        allErrors.push(...result.errors || []);
+      } else {
+        validated.body = result.data;
+      }
+    }
+    if (schemas.query && source.query) {
+      const result = await this.validateWithSchema(schemas.query, source.query);
+      if (!result.success) {
+        allErrors.push(...result.errors || []);
+      } else {
+        validated.query = result.data;
+      }
+    }
+    if (schemas.headers && source.headers) {
+      const result = await this.validateWithSchema(schemas.headers, source.headers);
+      if (!result.success) {
+        allErrors.push(...result.errors || []);
+      } else {
+        validated.headers = result.data;
+      }
+    }
+    if (schemas.params && source.params) {
+      const result = await this.validateWithSchema(schemas.params, source.params);
+      if (!result.success) {
+        allErrors.push(...result.errors || []);
+      } else {
+        validated.params = result.data;
+      }
+    }
+    if (allErrors.length > 0) {
+      return { success: false, errors: allErrors };
+    }
+    return { success: true, data: validated };
+  }
+  /**
+   * Validates a single value against a Standard Schema.
+   *
+   * @param schema - The Standard Schema validator
+   * @param data - The data to validate
+   * @returns Validation result with validated data or errors
+   */
+  async validateWithSchema(schema, data) {
+    try {
+      const resultOrPromise = schema["~standard"].validate(data);
+      const result = resultOrPromise instanceof Promise ? await resultOrPromise : resultOrPromise;
+      if (result.issues) {
+        return {
+          success: false,
+          errors: result.issues.map((issue) => ({
+            message: issue.message,
+            path: issue.path?.map((p) => typeof p === "object" && "key" in p ? p.key : p)
+          }))
+        };
+      }
+      return { success: true, data: result.value };
+    } catch (error) {
+      return {
+        success: false,
+        errors: [
+          {
+            message: error instanceof Error ? error.message : "Validation failed"
+          }
+        ]
+      };
+    }
+  }
+}
+export {
+  SchemaValidationService
+};

package/src/services/validation/standard-schema.types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Standard Schema interface for universal validation.
+ * Compatible with Zod, Valibot, ArkType, Effect Schema, and other validation libraries.
+ *
+ * @see https://standardschema.dev
+ *
+ * @example Using with Zod
+ * ```typescript
+ * import { z } from 'zod';
+ *
+ * const bodySchema = z.object({
+ *   title: z.string().min(1),
+ *   content: z.string()
+ * });
+ *
+ * app.post('/posts', async (ctx) => {
+ *   const { title, content } = ctx.body;
+ *   return ctx.json({ id: 1, title, content });
+ * }, {
+ *   schema: { body: bodySchema }
+ * });
+ * ```
+ */
+export interface StandardSchema<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+}
+/**
+ * Result of Standard Schema validation.
+ */
+export type StandardSchemaResult<Output> = StandardSchemaSuccessResult<Output> | StandardSchemaFailureResult;
+/**
+ * Successful validation result.
+ */
+export interface StandardSchemaSuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+}
+/**
+ * Failed validation result.
+ */
+export interface StandardSchemaFailureResult {
+    readonly value?: undefined;
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+}
+/**
+ * Validation issue details.
+ */
+export interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        key: PropertyKey;
+    }>;
+}
+/**
+ * Infers the output type from a Standard Schema.
+ */
+export type InferOutput<T extends StandardSchema> = T extends StandardSchema<any, infer O> ? O : never;

package/src/static-site-generator/static-site-generator.d.ts

@@ -0,0 +1,109 @@
+import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { StaticRoute } from '../public-types.js';
+import type { RouteRendererFactory } from '../route-renderer/route-renderer.js';
+import type { FSRouter } from '../router/server/fs-router.js';
+export declare const STATIC_SITE_GENERATOR_ERRORS: {
+    readonly ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy";
+    readonly unsupportedBodyType: (bodyType: string) => string;
+    readonly missingIntegration: (routePath: string) => string;
+    readonly noRendererForIntegration: (integrationName: string) => string;
+    readonly dynamicRouteRequiresStaticPaths: (routePath: string) => string;
+};
+/**
+ * Generates static output files from the finalized app config and route graph.
+ *
+ * @remarks
+ * This class intentionally reuses the same routing, renderer, and server-module
+ * loading seams used by runtime rendering. Static generation should be a build
+ * loop over the normal app model, not a parallel rendering stack with different
+ * semantics.
+ */
+export declare class StaticSiteGenerator {
+    appConfig: EcoPagesAppConfig;
+    private serverModuleTranspiler;
+    /**
+     * Creates the static-site generator for one app config.
+     */
+    constructor({ appConfig }: {
+        appConfig: EcoPagesAppConfig;
+    });
+    /**
+     * Returns the transpiler output directory used for static page-module probes.
+     */
+    private getStaticPageModuleOutdir;
+    private getExportDir;
+    /**
+     * Logs the standardized warning emitted when a dynamic-cache page is skipped.
+     */
+    private warnDynamicPageSkipped;
+    /**
+     * Determines whether one filesystem-discovered page should be excluded from
+     * static generation.
+     */
+    private shouldSkipStaticPageFile;
+    /**
+     * Determines whether one explicit static route view should be excluded from
+     * static generation.
+     */
+    private shouldSkipStaticView;
+    /**
+     * Writes the robots.txt file declared by the app config.
+     */
+    generateRobotsTxt(): void;
+    /**
+     * Returns whether the input path points at the root directory.
+     */
+    isRootDir(path: string): boolean | null;
+    /**
+     * Collects parent directories that must exist for the generated route set.
+     */
+    getDirectories(routes: string[]): string[];
+    /**
+     * Extracts dynamic parameters from the actual path based on the template path.
+     *
+     * @param templatePath - The template path (e.g., "/blog/[slug]")
+     * @param actualPath - The actual path (e.g., "/blog/my-post")
+     * @returns A record of extracted parameters (e.g., { slug: "my-post" })
+     */
+    private extractParams;
+    /**
+     * Generates static output for all filesystem-discovered routes.
+     *
+     * @remarks
+     * Routes whose integrations opt into fetch-based static builds are rendered by
+     * issuing a request against the running server origin. Render-strategy routes
+     * go through the normal route renderer directly.
+     */
+    generateStaticPages(router: FSRouter, baseUrl: string, routeRendererFactory?: RouteRendererFactory): Promise<void>;
+    /**
+     * Executes the full static-generation workflow for one app run.
+     */
+    run({ router, baseUrl, routeRendererFactory, staticRoutes, }: {
+        router: FSRouter;
+        baseUrl: string;
+        routeRendererFactory?: RouteRendererFactory;
+        staticRoutes?: StaticRoute[];
+    }): Promise<void>;
+    /**
+     * Generates static pages from explicit static routes registered via app.static().
+     * These routes use eco.page views via loader functions for HMR support.
+     */
+    private generateExplicitStaticPages;
+    /**
+     * Generate a single static page for a non-dynamic route.
+     */
+    private generateSingleStaticRoute;
+    /**
+     * Generate static pages for a dynamic route using staticPaths.
+     */
+    private generateDynamicStaticRoute;
+    /**
+     * Resolve a route path template with actual params.
+     * Supports both :param and [param] syntax.
+     */
+    private resolveRoutePath;
+    /**
+     * Get the output file path for a given route.
+     */
+    private getOutputPath;
+}