pdf-oxide-fips 0.3.47

package/lib/managers/cache-manager.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Cache Manager - TypeScript/Node.js Implementation
+ *
+ * Provides caching functionality for PDF operations:
+ * - Document-level caching
+ * - Page-level caching
+ * - Result caching with TTL
+ * - LRU eviction
+ * - Cache statistics
+ *
+ * This completes the cache coverage for 100% FFI parity.
+ */
+import { EventEmitter } from 'events';
+/**
+ * Cache entry with metadata
+ */
+export interface CacheEntry<T = unknown> {
+    readonly key: string;
+    readonly value: T;
+    readonly timestamp: number;
+    readonly ttl?: number;
+    readonly size?: number;
+    readonly hits: number;
+}
+/**
+ * Cache options
+ */
+export interface CacheOptions {
+    readonly maxSize?: number;
+    readonly maxEntries?: number;
+    readonly defaultTtl?: number;
+    readonly enableStatistics?: boolean;
+    readonly evictionPolicy?: 'lru' | 'lfu' | 'fifo';
+}
+/**
+ * Cache statistics
+ */
+export interface CacheStatistics {
+    readonly totalEntries: number;
+    readonly totalSize: number;
+    readonly hitCount: number;
+    readonly missCount: number;
+    readonly hitRate: number;
+    readonly evictionCount: number;
+    readonly oldestEntry?: number;
+    readonly newestEntry?: number;
+}
+/**
+ * Cache scope enumeration
+ */
+export declare enum CacheScope {
+    /** Cache per document */
+    DOCUMENT = "document",
+    /** Cache per page */
+    PAGE = "page",
+    /** Global cache */
+    GLOBAL = "global",
+    /** Session-level cache */
+    SESSION = "session"
+}
+/**
+ * Cache event data
+ */
+export interface CacheEventData {
+    readonly key: string;
+    readonly scope?: CacheScope;
+    readonly operation: 'set' | 'get' | 'delete' | 'evict' | 'clear';
+    readonly hit?: boolean;
+}
+/**
+ * Cache Manager - Complete caching capabilities
+ *
+ * Provides 10 functions for cache management:
+ * 1. set - Store a value
+ * 2. get - Retrieve a value
+ * 3. has - Check if key exists
+ * 4. delete - Remove a key
+ * 5. clear - Clear all entries
+ * 6. clearScope - Clear entries by scope
+ * 7. getStatistics - Get cache statistics
+ * 8. setTtl - Set TTL for an entry
+ * 9. getKeys - Get all keys
+ * 10. prune - Remove expired entries
+ *
+ * @example
+ * ```typescript
+ * const cache = new CacheManager({
+ *   maxEntries: 1000,
+ *   defaultTtl: 60000, // 1 minute
+ *   evictionPolicy: 'lru',
+ * });
+ *
+ * // Store a value
+ * cache.set('page:0:text', extractedText, CacheScope.PAGE);
+ *
+ * // Retrieve a value
+ * const text = cache.get<string>('page:0:text');
+ *
+ * // Check statistics
+ * const stats = cache.getStatistics();
+ * console.log(`Hit rate: ${stats.hitRate * 100}%`);
+ * ```
+ */
+export declare class CacheManager extends EventEmitter {
+    private readonly cache;
+    private readonly scopeIndex;
+    private readonly options;
+    private hitCount;
+    private missCount;
+    private evictionCount;
+    constructor(options?: CacheOptions);
+    /**
+     * Store a value in the cache
+     */
+    set<T>(key: string, value: T, scope?: CacheScope, ttl?: number): void;
+    /**
+     * Retrieve a value from the cache
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key: string): boolean;
+    /**
+     * Remove a key from the cache
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Clear entries by scope
+     */
+    clearScope(scope: CacheScope): number;
+    /**
+     * Get cache statistics
+     */
+    getStatistics(): CacheStatistics;
+    /**
+     * Set TTL for an existing entry
+     */
+    setTtl(key: string, ttl: number): boolean;
+    /**
+     * Get all cache keys
+     */
+    getKeys(scope?: CacheScope): string[];
+    /**
+     * Remove expired entries
+     */
+    prune(): number;
+    /**
+     * Ensure cache has capacity, evicting if needed
+     */
+    private ensureCapacity;
+    /**
+     * Evict one entry based on eviction policy
+     */
+    private evictOne;
+    /**
+     * Find key with oldest timestamp (LRU)
+     */
+    private findOldestKey;
+    /**
+     * Find key with least hits (LFU)
+     */
+    private findLeastUsedKey;
+    /**
+     * Remove key from scope index
+     */
+    private removeFromScopeIndex;
+    /**
+     * Estimate size of a value in bytes
+     */
+    private estimateSize;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+export default CacheManager;

package/lib/managers/cache-manager.js

@@ -0,0 +1,384 @@
+/**
+ * Cache Manager - TypeScript/Node.js Implementation
+ *
+ * Provides caching functionality for PDF operations:
+ * - Document-level caching
+ * - Page-level caching
+ * - Result caching with TTL
+ * - LRU eviction
+ * - Cache statistics
+ *
+ * This completes the cache coverage for 100% FFI parity.
+ */
+import { EventEmitter } from 'events';
+/**
+ * Cache scope enumeration
+ */
+export var CacheScope;
+(function (CacheScope) {
+    /** Cache per document */
+    CacheScope["DOCUMENT"] = "document";
+    /** Cache per page */
+    CacheScope["PAGE"] = "page";
+    /** Global cache */
+    CacheScope["GLOBAL"] = "global";
+    /** Session-level cache */
+    CacheScope["SESSION"] = "session";
+})(CacheScope || (CacheScope = {}));
+// ============================================================================
+// Cache Manager Implementation
+// ============================================================================
+/**
+ * Cache Manager - Complete caching capabilities
+ *
+ * Provides 10 functions for cache management:
+ * 1. set - Store a value
+ * 2. get - Retrieve a value
+ * 3. has - Check if key exists
+ * 4. delete - Remove a key
+ * 5. clear - Clear all entries
+ * 6. clearScope - Clear entries by scope
+ * 7. getStatistics - Get cache statistics
+ * 8. setTtl - Set TTL for an entry
+ * 9. getKeys - Get all keys
+ * 10. prune - Remove expired entries
+ *
+ * @example
+ * ```typescript
+ * const cache = new CacheManager({
+ *   maxEntries: 1000,
+ *   defaultTtl: 60000, // 1 minute
+ *   evictionPolicy: 'lru',
+ * });
+ *
+ * // Store a value
+ * cache.set('page:0:text', extractedText, CacheScope.PAGE);
+ *
+ * // Retrieve a value
+ * const text = cache.get<string>('page:0:text');
+ *
+ * // Check statistics
+ * const stats = cache.getStatistics();
+ * console.log(`Hit rate: ${stats.hitRate * 100}%`);
+ * ```
+ */
+export class CacheManager extends EventEmitter {
+    constructor(options = {}) {
+        super();
+        this.cache = new Map();
+        this.scopeIndex = new Map();
+        // Statistics
+        this.hitCount = 0;
+        this.missCount = 0;
+        this.evictionCount = 0;
+        this.options = {
+            maxSize: options.maxSize ?? 100 * 1024 * 1024, // 100MB default
+            maxEntries: options.maxEntries ?? 10000,
+            defaultTtl: options.defaultTtl ?? 0, // 0 = no expiry
+            enableStatistics: options.enableStatistics ?? true,
+            evictionPolicy: options.evictionPolicy ?? 'lru',
+        };
+        // Initialize scope index
+        for (const scope of Object.values(CacheScope)) {
+            this.scopeIndex.set(scope, new Set());
+        }
+    }
+    // ==========================================================================
+    // Core Cache Operations (6 functions)
+    // ==========================================================================
+    /**
+     * Store a value in the cache
+     */
+    set(key, value, scope = CacheScope.GLOBAL, ttl) {
+        // Check if we need to evict
+        this.ensureCapacity();
+        const entry = {
+            key,
+            value,
+            timestamp: Date.now(),
+            ttl: ttl ?? this.options.defaultTtl,
+            size: this.estimateSize(value),
+            hits: 0,
+        };
+        // Remove from old scope if exists
+        if (this.cache.has(key)) {
+            this.removeFromScopeIndex(key);
+        }
+        this.cache.set(key, entry);
+        this.scopeIndex.get(scope)?.add(key);
+        this.emit('cache-set', {
+            key,
+            scope,
+            operation: 'set',
+        });
+    }
+    /**
+     * Retrieve a value from the cache
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            if (this.options.enableStatistics) {
+                this.missCount++;
+            }
+            this.emit('cache-miss', { key, operation: 'get', hit: false });
+            return undefined;
+        }
+        // Check TTL
+        if (entry.ttl && entry.ttl > 0 && Date.now() - entry.timestamp > entry.ttl) {
+            this.delete(key);
+            if (this.options.enableStatistics) {
+                this.missCount++;
+            }
+            this.emit('cache-expired', { key, operation: 'get', hit: false });
+            return undefined;
+        }
+        // Update hit count for LFU
+        const updatedEntry = {
+            ...entry,
+            hits: entry.hits + 1,
+            timestamp: this.options.evictionPolicy === 'lru' ? Date.now() : entry.timestamp,
+        };
+        this.cache.set(key, updatedEntry);
+        if (this.options.enableStatistics) {
+            this.hitCount++;
+        }
+        this.emit('cache-hit', { key, operation: 'get', hit: true });
+        return entry.value;
+    }
+    /**
+     * Check if a key exists in the cache
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        // Check TTL
+        if (entry.ttl && entry.ttl > 0 && Date.now() - entry.timestamp > entry.ttl) {
+            this.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Remove a key from the cache
+     */
+    delete(key) {
+        const exists = this.cache.has(key);
+        if (exists) {
+            this.removeFromScopeIndex(key);
+            this.cache.delete(key);
+            this.emit('cache-delete', { key, operation: 'delete' });
+        }
+        return exists;
+    }
+    /**
+     * Clear all entries from the cache
+     */
+    clear() {
+        const count = this.cache.size;
+        this.cache.clear();
+        for (const scope of this.scopeIndex.values()) {
+            scope.clear();
+        }
+        this.hitCount = 0;
+        this.missCount = 0;
+        this.evictionCount = 0;
+        this.emit('cache-clear', { key: '*', operation: 'clear' });
+    }
+    /**
+     * Clear entries by scope
+     */
+    clearScope(scope) {
+        const keys = this.scopeIndex.get(scope);
+        if (!keys)
+            return 0;
+        const count = keys.size;
+        for (const key of keys) {
+            this.cache.delete(key);
+        }
+        keys.clear();
+        this.emit('cache-scope-clear', { key: scope, scope, operation: 'clear' });
+        return count;
+    }
+    // ==========================================================================
+    // Statistics and Maintenance (4 functions)
+    // ==========================================================================
+    /**
+     * Get cache statistics
+     */
+    getStatistics() {
+        const entries = Array.from(this.cache.values());
+        const totalSize = entries.reduce((sum, e) => sum + (e.size ?? 0), 0);
+        const timestamps = entries.map((e) => e.timestamp);
+        return {
+            totalEntries: this.cache.size,
+            totalSize,
+            hitCount: this.hitCount,
+            missCount: this.missCount,
+            hitRate: this.hitCount + this.missCount > 0 ? this.hitCount / (this.hitCount + this.missCount) : 0,
+            evictionCount: this.evictionCount,
+            oldestEntry: timestamps.length > 0 ? Math.min(...timestamps) : undefined,
+            newestEntry: timestamps.length > 0 ? Math.max(...timestamps) : undefined,
+        };
+    }
+    /**
+     * Set TTL for an existing entry
+     */
+    setTtl(key, ttl) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        const updatedEntry = {
+            ...entry,
+            ttl,
+        };
+        this.cache.set(key, updatedEntry);
+        return true;
+    }
+    /**
+     * Get all cache keys
+     */
+    getKeys(scope) {
+        if (scope) {
+            return Array.from(this.scopeIndex.get(scope) ?? []);
+        }
+        return Array.from(this.cache.keys());
+    }
+    /**
+     * Remove expired entries
+     */
+    prune() {
+        const now = Date.now();
+        let pruned = 0;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.ttl && entry.ttl > 0 && now - entry.timestamp > entry.ttl) {
+                this.delete(key);
+                pruned++;
+            }
+        }
+        if (pruned > 0) {
+            this.emit('cache-prune', { key: '*', operation: 'delete' });
+        }
+        return pruned;
+    }
+    // ==========================================================================
+    // Helper Methods
+    // ==========================================================================
+    /**
+     * Ensure cache has capacity, evicting if needed
+     */
+    ensureCapacity() {
+        // Check entry count
+        while (this.cache.size >= this.options.maxEntries) {
+            this.evictOne();
+        }
+        // Check total size
+        let totalSize = 0;
+        for (const entry of this.cache.values()) {
+            totalSize += entry.size ?? 0;
+        }
+        while (totalSize > this.options.maxSize && this.cache.size > 0) {
+            const evicted = this.evictOne();
+            totalSize -= evicted?.size ?? 0;
+        }
+    }
+    /**
+     * Evict one entry based on eviction policy
+     */
+    evictOne() {
+        if (this.cache.size === 0)
+            return undefined;
+        let keyToEvict;
+        switch (this.options.evictionPolicy) {
+            case 'lru':
+                // Find oldest timestamp
+                keyToEvict = this.findOldestKey();
+                break;
+            case 'lfu':
+                // Find least frequently used
+                keyToEvict = this.findLeastUsedKey();
+                break;
+            case 'fifo':
+            default:
+                // First key
+                keyToEvict = this.cache.keys().next().value;
+                break;
+        }
+        if (keyToEvict) {
+            const entry = this.cache.get(keyToEvict);
+            this.removeFromScopeIndex(keyToEvict);
+            this.cache.delete(keyToEvict);
+            this.evictionCount++;
+            this.emit('cache-evict', { key: keyToEvict, operation: 'evict' });
+            return entry;
+        }
+        return undefined;
+    }
+    /**
+     * Find key with oldest timestamp (LRU)
+     */
+    findOldestKey() {
+        let oldestKey;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.timestamp < oldestTime) {
+                oldestTime = entry.timestamp;
+                oldestKey = key;
+            }
+        }
+        return oldestKey;
+    }
+    /**
+     * Find key with least hits (LFU)
+     */
+    findLeastUsedKey() {
+        let leastUsedKey;
+        let leastHits = Infinity;
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.hits < leastHits) {
+                leastHits = entry.hits;
+                leastUsedKey = key;
+            }
+        }
+        return leastUsedKey;
+    }
+    /**
+     * Remove key from scope index
+     */
+    removeFromScopeIndex(key) {
+        for (const keys of this.scopeIndex.values()) {
+            keys.delete(key);
+        }
+    }
+    /**
+     * Estimate size of a value in bytes
+     */
+    estimateSize(value) {
+        if (value === null || value === undefined)
+            return 0;
+        if (typeof value === 'string')
+            return value.length * 2;
+        if (typeof value === 'number')
+            return 8;
+        if (typeof value === 'boolean')
+            return 4;
+        if (Buffer.isBuffer(value))
+            return value.length;
+        if (Array.isArray(value)) {
+            return value.reduce((sum, v) => sum + this.estimateSize(v), 0);
+        }
+        if (typeof value === 'object') {
+            return JSON.stringify(value).length * 2;
+        }
+        return 0;
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        this.clear();
+        this.removeAllListeners();
+    }
+}
+export default CacheManager;

package/lib/managers/compliance-manager.d.ts

@@ -0,0 +1,103 @@
+/**
+ * ComplianceManager - Canonical Compliance Manager (merged from 2 implementations)
+ *
+ * Consolidates:
+ * - src/compliance-manager.ts ComplianceManager (validation + issue analysis + native FFI)
+ * - src/managers/ocr-compliance-cache.ts ComplianceManager (validation + conversion + fixing)
+ *
+ * Provides complete PDF/A, PDF/X, PDF/UA compliance operations.
+ */
+import { EventEmitter } from 'events';
+export declare enum PdfALevel {
+    A1a = "PDF/A-1a",
+    A1b = "PDF/A-1b",
+    A2a = "PDF/A-2a",
+    A2b = "PDF/A-2b",
+    A3a = "PDF/A-3a",
+    A3b = "PDF/A-3b"
+}
+export declare enum PdfXLevel {
+    X1a = "PDF/X-1a",
+    X1a2001 = "PDF/X-1a:2001",
+    X1a2003 = "PDF/X-1a:2003",
+    X3 = "PDF/X-3",
+    X3_2002 = "PDF/X-3:2002",
+    X3_2003 = "PDF/X-3:2003",
+    X4 = "PDF/X-4"
+}
+export declare enum PdfUALevel {
+    UA1 = "PDF/UA-1",
+    UA2 = "PDF/UA-2"
+}
+export declare enum ComplianceIssueType {
+    FontNotEmbedded = "font_not_embedded",
+    InvalidColorSpace = "invalid_color_space",
+    MissingAltText = "missing_alt_text",
+    MissingLanguage = "missing_language",
+    MissingTitle = "missing_title",
+    InvalidAnnotation = "invalid_annotation",
+    MissingStructure = "missing_structure",
+    InvalidLink = "invalid_link",
+    Other = "other"
+}
+export declare enum IssueSeverity {
+    Error = "error",
+    Warning = "warning",
+    Info = "info"
+}
+export interface ComplianceIssue {
+    type: ComplianceIssueType;
+    severity: IssueSeverity;
+    message: string;
+    pageIndex?: number;
+}
+export interface ComplianceValidationResult {
+    isCompliant: boolean;
+    level: string;
+    issues: ComplianceIssue[];
+    validationTime: number;
+}
+export interface ComplianceResult {
+    type: string;
+    valid: boolean;
+    issues: string[];
+    severity: string;
+}
+export declare class ComplianceManager extends EventEmitter {
+    private document;
+    private resultCache;
+    private maxCacheSize;
+    private native;
+    constructor(document: any);
+    validatePdfA(level?: PdfALevel | string): Promise<ComplianceValidationResult>;
+    validatePdfX(level?: PdfXLevel | string): Promise<ComplianceValidationResult>;
+    validatePdfUA(level?: PdfUALevel | string): Promise<ComplianceValidationResult>;
+    getAllIssues(): Promise<ComplianceIssue[]>;
+    getIssuesOfType(type: ComplianceIssueType): Promise<ComplianceIssue[]>;
+    getIssueCount(): Promise<number>;
+    getErrorCount(): Promise<number>;
+    getWarningCount(): Promise<number>;
+    convertToPdfA(level?: string): Promise<boolean>;
+    convertToPdfUA(): Promise<boolean>;
+    getComplianceReport(complianceType?: string): Promise<string>;
+    checkFontEmbedding(): Promise<boolean>;
+    /** @deprecated Use checkFontEmbedding() instead */
+    hasFontsEmbedded(): Promise<boolean>;
+    checkColorSpace(): Promise<boolean>;
+    /** @deprecated Use checkColorSpace() instead */
+    hasValidColorSpace(): Promise<boolean>;
+    checkTaggedContent(): Promise<boolean>;
+    addMissingTags(): Promise<boolean>;
+    fixFontIssues(): Promise<number>;
+    fixColorIssues(): Promise<number>;
+    removeUnsupportedFeatures(): Promise<number>;
+    getComplianceIssues(): Promise<string[]>;
+    getIssueSeverity(issue: string): string;
+    createComplianceReportFile(filePath: string): Promise<boolean>;
+    getComplianceSummary(): Promise<object>;
+    clearCache(): void;
+    getCacheStats(): Record<string, any>;
+    destroy(): void;
+    private setCached;
+}
+export default ComplianceManager;