feat(initial): add comprehensive PDF to JPEG preview library with dual-environment support

- Add Node.js implementation using @push.rocks/smartpdf - Add browser implementation with PDF.js and Web Workers - Support configurable quality, dimensions, and page selection - Include comprehensive TypeScript definitions and error handling - Provide extensive test coverage for both environments - Add download functionality and browser compatibility checking
2025-08-03 21:44:01 +00:00
commit bc1c7edd35
23 changed files with 12822 additions and 0 deletions
--- a/ts_web/interfaces.ts
+++ b/ts_web/interfaces.ts
@@ -0,0 +1,202 @@
+/**
+ * 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;
+}