import { Result } from "../Result";

/**
 * PageQuery contract interface
 *
 * Defines the canonical contract for all server-side page queries.
 *
 * Architecture:
 * - Server-side composition classes
 * - Construct Services manually (no DI container)
 * - Services create their own dependencies (API Client, Logger, ErrorReporter)
 * - Services return Result<ApiDto, DomainError>
 * - PageQuery maps DomainError → PresentationError
 * - PageQuery returns Result<ViewData, PresentationError>
 * - Do not implement business rules
 *
 * @template TViewData - The ViewData type this query produces for templates
 * @template TParams - The parameters required to execute this query
 * @template TError - The error type (default: string for backward compatibility)
 */
export interface PageQuery<TViewData, TParams = void, TError = string> {
  /**
   * Execute the page query
   *
   * Manual construction pattern:
   * ```typescript
   * const service = new MyService();
   * const result = await service.getData();
   * if (result.isErr()) {
   *   return Result.err(mapToPresentationError(result.error));
   * }
   * const viewData = MyViewDataBuilder.build(result.value);
   * return Result.ok(viewData);
   * ```
   *
   * @param params - Parameters required for query execution
   * @returns Promise<Result<ViewData, TError>>
   */
  execute(params: TParams): Promise<Result<TViewData, TError>>;
}