@ecopages/core 0.2.0-alpha.1

package/src/services/page-request-cache-coordinator.service.ts

@@ -0,0 +1,128 @@
+import { getCacheControlHeader, type PageCacheService } from './cache/page-cache-service.ts';
+import type { CacheStrategy, RenderResult } from './cache/cache.types.ts';
+
+type CacheStatus = 'hit' | 'miss' | 'stale' | 'expired' | 'disabled';
+
+/**
+ * Coordinates request-time page caching concerns around one render invocation.
+ *
+ * This service keeps `FileSystemResponseMatcher` from owning low-level cache
+ * policy mechanics such as cache key construction, `dynamic` bypass behavior,
+ * body normalization for cache storage, and final cache header generation.
+ */
+export class PageRequestCacheCoordinator {
+	constructor(
+		private cacheService: PageCacheService | null,
+		private defaultCacheStrategy: CacheStrategy,
+	) {}
+
+	/**
+	 * Builds the cache key used for page lookups.
+	 *
+	 * Query parameters are part of the key so two requests that hit the same
+	 * pathname but differ by search params do not share the same rendered entry.
+	 *
+	 * @param input Pathname plus optional query record.
+	 * @returns Stable cache key for the request.
+	 */
+	buildCacheKey(input: { pathname: string; query?: Record<string, string> }): string {
+		let key = input.pathname;
+		if (input.query && Object.keys(input.query).length > 0) {
+			const queryString = new URLSearchParams(input.query).toString();
+			key += `?${queryString}`;
+		}
+		return key;
+	}
+
+	/**
+	 * Resolves a render request through the configured cache policy.
+	 *
+	 * Pages using `dynamic` rendering, or applications without a cache service,
+	 * bypass cache lookup entirely and still receive the same response header
+	 * contract as cached pages.
+	 *
+	 * @param options Cache coordination inputs for one page request.
+	 * @returns HTTP response with cache headers applied.
+	 */
+	async render(options: {
+		cacheKey: string;
+		pageCacheStrategy: CacheStrategy;
+		renderFn: () => Promise<RenderResult>;
+	}): Promise<Response> {
+		if (!this.cacheService || options.pageCacheStrategy === 'dynamic') {
+			const { html, strategy } = await options.renderFn();
+			return this.createCachedResponse(html, strategy, 'disabled');
+		}
+
+		const result = await this.cacheService.getOrCreate(
+			options.cacheKey,
+			options.pageCacheStrategy,
+			options.renderFn,
+		);
+
+		return this.createCachedResponse(result.html, result.strategy, result.status);
+	}
+
+	/**
+	 * Exposes the underlying cache service for invalidation and adapter plumbing.
+	 *
+	 * @returns Configured cache service or `null` when caching is disabled.
+	 */
+	getCacheService(): PageCacheService | null {
+		return this.cacheService;
+	}
+
+	/**
+	 * Returns the default render strategy used when a page does not declare one.
+	 *
+	 * @returns Application-level fallback cache strategy.
+	 */
+	getDefaultCacheStrategy(): CacheStrategy {
+		return this.defaultCacheStrategy;
+	}
+
+	/**
+	 * Normalizes various route render body shapes into a cacheable string.
+	 *
+	 * Page rendering may produce strings, buffers, byte arrays, or streams. The
+	 * matcher needs a single representation before passing HTML through the cache
+	 * layer, so this method centralizes the conversion rules.
+	 *
+	 * @param body Render output body in any supported form.
+	 * @returns HTML string representation.
+	 */
+	async bodyToString(body: unknown): Promise<string> {
+		if (typeof body === 'string') {
+			return body;
+		}
+		if (Buffer.isBuffer(body)) {
+			return body.toString('utf-8');
+		}
+		if (body instanceof ReadableStream) {
+			return new Response(body).text();
+		}
+		if (body instanceof Uint8Array) {
+			return new TextDecoder().decode(body);
+		}
+		return String(body);
+	}
+
+	/**
+	 * Creates the final HTML response with the current cache semantics encoded in
+	 * response headers.
+	 *
+	 * @param html Rendered page HTML.
+	 * @param strategy Effective cache strategy for the response.
+	 * @param cacheStatus Status used for `X-Cache` and `Cache-Control` generation.
+	 * @returns HTTP response ready to send to the client.
+	 */
+	private createCachedResponse(html: string, strategy: CacheStrategy, cacheStatus: CacheStatus): Response {
+		const headers: HeadersInit = {
+			'Content-Type': 'text/html',
+			'Cache-Control': getCacheControlHeader(cacheStatus === 'disabled' ? 'disabled' : strategy),
+			'X-Cache': cacheStatus.toUpperCase(),
+		};
+
+		return new Response(html, { headers });
+	}
+}

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

@@ -0,0 +1,122 @@
+import type { StandardSchema } from './validation/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/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/schema-validation-service.ts

@@ -0,0 +1,204 @@
+import type { StandardSchema, StandardSchemaIssue } from './validation/standard-schema.types.ts';
+
+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.ts';
+ *
+ * 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 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: ValidationSource,
+		schemas: ValidationSchemas,
+	): Promise<ValidationResult<ValidatedData>> {
+		const validated: ValidatedData = {};
+		const allErrors: Array<{ message: string; path?: Array<string | number> }> = [];
+
+		if (schemas.body && source.body !== undefined) {
+			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
+	 */
+	private async validateWithSchema<T>(schema: StandardSchema, data: unknown): Promise<ValidationResult<T>> {
+		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: StandardSchemaIssue) => ({
+						message: issue.message,
+						path: issue.path?.map((p) => (typeof p === 'object' && 'key' in p ? p.key : p)) as
+							| Array<string | number>
+							| undefined,
+					})),
+				};
+			}
+
+			return { success: true, data: result.value as T };
+		} catch (error) {
+			return {
+				success: false,
+				errors: [
+					{
+						message: error instanceof Error ? error.message : 'Validation failed',
+					},
+				],
+			};
+		}
+	}
+}

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/services/validation/standard-schema.types.ts

@@ -0,0 +1,68 @@
+/**
+ * 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;