smartpreview/ts_web/interfaces.ts

/**
 * Configuration options for preview generation in browser environment
 */
export interface IPreviewOptions {
  /**
   * JPEG quality (1-100)
   * @default 80
   */
  quality?: number;

  /**
   * Maximum width in pixels
   */
  width?: number;

  /**
   * Maximum height in pixels
   */
  height?: number;

  /**
   * PDF page number to convert (1-based)
   * @default 1
   */
  page?: number;

  /**
   * Scale factor for rendering
   * @default 1.0
   */
  scale?: number;
}

/**
 * Preview generation result for browser environment
 */
export interface IPreviewResult {
  /**
   * Generated JPEG image blob
   */
  blob: Blob;

  /**
   * Image dimensions
   */
  dimensions: {
    width: number;
    height: number;
  };

  /**
   * File size in bytes
   */
  size: number;

  /**
   * MIME type
   */
  mimeType: 'image/jpeg';

  /**
   * Data URL for immediate use
   */
  dataUrl: string;
}

/**
 * Supported input types for browser environment
 */
export type TWebInputType = File | Blob | ArrayBuffer | Uint8Array | string;

/**
 * Supported input formats (extensible)
 */
export type TSupportedInputFormat = 'pdf';

/**
 * Supported output formats (extensible)
 */
export type TSupportedOutputFormat = 'jpeg';

/**
 * Worker message types for communication
 */
export type TWorkerMessageType = 
  | 'INIT'
  | 'PROCESS_PDF'
  | 'PROCESS_COMPLETE'
  | 'PROCESS_ERROR'
  | 'WORKER_READY';

/**
 * Worker message interface
 */
export interface IWorkerMessage {
  type: TWorkerMessageType;
  id: string;
  data?: any;
  error?: string;
}

/**
 * PDF processing request for worker
 */
export interface IPdfProcessRequest {
  pdfData: ArrayBuffer;
  options: Required<IPreviewOptions>;
}

/**
 * PDF processing response from worker
 */
export interface IPdfProcessResponse {
  imageData: ArrayBuffer;
  width: number;
  height: number;
}

/**
 * Base interface for format processors (extensible architecture)
 */
export interface IWebFormatProcessor {
  /**
   * Supported input format
   */
  inputFormat: TSupportedInputFormat;

  /**
   * Supported output format
   */
  outputFormat: TSupportedOutputFormat;

  /**
   * Process the input and generate preview
   */
  processPreview(input: TWebInputType, options: IPreviewOptions): Promise<IPreviewResult>;
}

/**
 * PDF-specific processor interface for web
 */
export interface IWebPdfProcessor extends IWebFormatProcessor {
  inputFormat: 'pdf';
  outputFormat: 'jpeg';
}

/**
 * Error types for preview generation
 */
export type TPreviewError = 
  | 'INVALID_INPUT'
  | 'UNSUPPORTED_FORMAT'
  | 'PROCESSING_FAILED'
  | 'INVALID_OPTIONS'
  | 'PDF_CORRUPTED'
  | 'PAGE_NOT_FOUND'
  | 'WORKER_ERROR'
  | 'WORKER_TIMEOUT';

/**
 * Custom error class for preview operations in browser
 */
export class PreviewError extends Error {
  public readonly errorType: TPreviewError;
  public readonly originalError?: Error;

  constructor(errorType: TPreviewError, message: string, originalError?: Error) {
    super(message);
    this.name = 'PreviewError';
    this.errorType = errorType;
    this.originalError = originalError;
  }
}

/**
 * Progress callback interface
 */
export interface IProgressCallback {
  (progress: number, stage: string): void;
}

/**
 * Advanced options for web processing
 */
export interface IWebPreviewOptions extends IPreviewOptions {
  /**
   * Progress callback function
   */
  onProgress?: IProgressCallback;

  /**
   * Worker timeout in milliseconds
   * @default 30000
   */
  timeout?: number;

  /**
   * Whether to generate data URL
   * @default true
   */
  generateDataUrl?: boolean;
}