/**
 * @fileoverview Pagination helpers for the DeepSource MCP Server
 * This module provides utilities for working with pagination.
 */

import { createLogger } from '../logging/logger.js';
import { PageInfo, PaginationParams, PaginatedResponse, PaginationMetadata } from './types.js';

// Logger for pagination utilities
const logger = createLogger('PaginationUtils');

/**
 * Creates an empty paginated response with no items
 * @template T The type of items in the response
 * @returns {PaginatedResponse<T>} Empty paginated response with consistent structure
 * @public
 */
export function createEmptyPaginatedResponse<T>(): PaginatedResponse<T> {
  return {
    items: [],
    pageInfo: {
      hasNextPage: false,
      hasPreviousPage: false,
    },
    totalCount: 0,
  };
}

/**
 * Logs a warning message about non-standard pagination usage
 * @param message Optional custom warning message to use instead of the default
 * @private
 */
function logPaginationWarning(message?: string): void {
  const warningMessage =
    message ||
    'Non-standard pagination: Using "last" without "before" is not recommended in Relay pagination';
  logger.warn(warningMessage);
}

/**
 * Normalizes pagination parameters for GraphQL queries
 * Ensures consistency in pagination parameters following Relay pagination best practices
 *
 * Normalization rules:
 * 1. If 'before' is provided (backward pagination):
 *    - Use 'last' as the count parameter (default: 10)
 *    - Remove any 'first' parameter to avoid ambiguity
 * 2. If 'last' is provided without 'before' (non-standard but supported):
 *    - Keep 'last' as is
 *    - Remove any 'first' parameter to avoid ambiguity
 *    - Log a warning about non-standard usage
 * 3. Otherwise (forward pagination or defaults):
 *    - Use 'first' as the count parameter (default: 10)
 *    - Remove any 'last' parameter to avoid ambiguity
 *
 * @template T Type that extends PaginationParams
 * @param {T} params - Original pagination parameters
 * @returns {T} Normalized pagination parameters with consistent values
 * @public
 */
export function normalizePaginationParams<T extends PaginationParams>(params: T): T {
  const normalizedParams = { ...params };

  // Validate and normalize numerical parameters
  if (normalizedParams.offset !== undefined) {
    normalizedParams.offset = Math.max(0, Math.floor(Number(normalizedParams.offset)));
  }

  if (normalizedParams.first !== undefined) {
    // Ensure first is a positive integer or undefined
    normalizedParams.first = Math.max(1, Math.floor(Number(normalizedParams.first)));
  }

  if (normalizedParams.last !== undefined) {
    // Ensure last is a positive integer or undefined
    normalizedParams.last = Math.max(1, Math.floor(Number(normalizedParams.last)));
  }

  // Validate cursor parameters (ensure they're valid strings)
  if (normalizedParams.after !== undefined && typeof normalizedParams.after !== 'string') {
    normalizedParams.after = String(normalizedParams.after ?? '');
  }

  if (normalizedParams.before !== undefined && typeof normalizedParams.before !== 'string') {
    normalizedParams.before = String(normalizedParams.before ?? '');
  }

  // Apply Relay pagination rules
  if (normalizedParams.before) {
    // When fetching backwards with 'before', prioritize 'last'
    normalizedParams.last = normalizedParams.last ?? normalizedParams.first ?? 10;
    delete normalizedParams.first;
  } else if (normalizedParams.last) {
    // If 'last' is provided without 'before', log a warning but still use 'last'
    logPaginationWarning(
      `Non-standard pagination: Using "last=${normalizedParams.last}" without "before" cursor is not recommended`
    );
    // Keep normalizedParams.last as is
    delete normalizedParams.first;
  } else {
    // Default or forward pagination with 'after', prioritize 'first'
    normalizedParams.first = normalizedParams.first ?? 10;
    delete normalizedParams.last;
  }

  return normalizedParams;
}

/**
 * Creates a formatted pagination help object for API responses
 * @param pageInfo The page information to create help documentation for
 * @returns Pagination help documentation object
 * @public
 */
export function createPaginationHelp(pageInfo: PageInfo): Record<string, unknown> {
  return {
    description: 'This API uses Relay-style cursor-based pagination',
    forward_pagination: `To get the next page, use 'first: 10, after: "${
      pageInfo.endCursor || 'cursor_value'
    }"'`,
    backward_pagination: `To get the previous page, use 'last: 10, before: "${
      pageInfo.startCursor || 'cursor_value'
    }"'`,
    page_status: {
      has_next_page: pageInfo.hasNextPage,
      has_previous_page: pageInfo.hasPreviousPage,
    },
  };
}

/**
 * Creates a detailed pagination help object for API responses with more examples
 * @param pageInfo The page information to create help documentation for
 * @param itemCount The number of items in the current page
 * @returns Enhanced pagination help documentation object
 * @public
 */
export function createEnhancedPaginationHelp(
  pageInfo: PageInfo,
  itemCount: number
): Record<string, unknown> {
  return {
    description: 'This API uses Relay-style cursor-based pagination for efficient data retrieval',
    current_page: {
      size: itemCount,
      has_next_page: pageInfo.hasNextPage,
      has_previous_page: pageInfo.hasPreviousPage,
    },
    next_page: pageInfo.hasNextPage
      ? {
          example: `{"first": 10, "after": "${pageInfo.endCursor}"}`,
          description: 'Use these parameters to fetch the next page of results',
        }
      : null,
    previous_page: pageInfo.hasPreviousPage
      ? {
          example: `{"last": 10, "before": "${pageInfo.startCursor}"}`,
          description: 'Use these parameters to fetch the previous page of results',
        }
      : null,
    pagination_types: {
      forward: 'For forward pagination, use "first" with optional "after" cursor',
      backward: 'For backward pagination, use "last" with optional "before" cursor',
      legacy: 'Legacy offset-based pagination is also supported via the "offset" parameter',
    },
  };
}

/**
 * Handles page_size parameter as an alias for first
 * @param params Pagination parameters that may include page_size
 * @returns Normalized params with first set appropriately
 * @public
 */
export function handlePageSizeAlias(params: PaginationParams): PaginationParams {
  const { page_size, ...restParams } = params;

  // Use page_size as an alias for first if first is not already set
  if (page_size !== undefined && restParams.first === undefined && !restParams.before) {
    restParams.first = page_size;
  }

  return restParams;
}

/**
 * Determines if multi-page fetching is needed based on parameters
 * @param params Pagination parameters
 * @returns Whether multiple pages should be fetched
 * @public
 */
export function shouldFetchMultiplePages(params: PaginationParams): boolean {
  return params.max_pages !== undefined && params.max_pages > 1;
}

/**
 * Creates pagination metadata from a standard response
 * @param response Paginated response
 * @param pagesFetched Number of pages fetched (for multi-page operations)
 * @returns User-friendly pagination metadata
 * @public
 */
export function createPaginationMetadata<T>(
  response: PaginatedResponse<T>,
  pagesFetched = 1
): PaginationMetadata {
  const metadata: PaginationMetadata = {
    has_more_pages: response.pageInfo.hasNextPage,
    page_size: response.items.length,
  };

  if (response.pageInfo.endCursor) {
    metadata.next_cursor = response.pageInfo.endCursor;
  }
  if (response.pageInfo.startCursor) {
    metadata.previous_cursor = response.pageInfo.startCursor;
  }
  if (response.totalCount !== undefined) {
    metadata.total_count = response.totalCount;
  }
  if (pagesFetched > 1) {
    metadata.pages_fetched = pagesFetched;
  }

  return metadata;
}