@phroun/paged-buffer/lib/virtual-page-manager.d.ts

High-performance buffer system for editing massive files with intelligent memory management and undo/redo capabilities

/**
 * @fileoverview Enhanced Virtual Page Manager with Line Tracking, Marks Integration, and Page Merging
 * @description Handles mapping between virtual buffer addresses and physical page locations
 * while maintaining sparse, efficient access to massive files, with comprehensive line and marks support
 * @author Jeffrey R. Day
 * @version 2.1.0 - Added page merging and marks coordination
 */
/// <reference types="node" />
/// <reference types="node" />
import { type IPageDescriptor, type IPageInfo, type IVirtualPageManager, type ILineAndMarksManager, type IBuffer, type SourceInfo, type SourceType, type TranslateAddressResult, type VirtualPageManagerMemoryStats } from './types/common';
/**
 * Represents a page's metadata for address translation
 */
declare class PageDescriptor implements IPageDescriptor {
    pageKey: string;
    virtualStart: number;
    virtualSize: number;
    sourceType: SourceType;
    sourceInfo: SourceInfo;
    isDirty: boolean;
    isLoaded: boolean;
    lastAccess: number;
    generation: number;
    parentKey: string | null;
    newlineCount: number;
    lineInfoCached: boolean;
    constructor(pageKey: string, virtualStart: number, virtualSize: number, sourceType: SourceType, sourceInfo: SourceInfo);
    /**
     * Get the virtual end position of this page
     */
    get virtualEnd(): number;
    /**
     * Check if a virtual position falls within this page
     */
    contains(virtualPos: number): boolean;
    /**
     * Convert virtual position to relative position within this page
     */
    toRelativePosition(virtualPos: number): number;
    /**
     * Cache line information from a loaded page
     */
    cacheLineInfo(pageInfo: IPageInfo): void;
}
/**
 * Efficient B-tree-like structure for fast address lookups
 * Uses binary search for O(log n) lookups even with thousands of pages
 * Hash map for O(1) pageKey lookups
 */
declare class PageAddressIndex {
    pages: PageDescriptor[];
    pageKeyIndex: Map<string, PageDescriptor>;
    totalVirtualSize: number;
    /**
     * Find the page containing a virtual address
     */
    findPageAt(virtualPos: number): PageDescriptor | null;
    /**
     * Find page by pageKey
     */
    findPageByKey(pageKey: string): PageDescriptor | null;
    /**
     * Insert a new page, maintaining sorted order
     */
    insertPage(pageDesc: PageDescriptor): void;
    /**
     * Remove a page from the index
     */
    removePage(pageKey: string): void;
    /**
     * Update virtual addresses after a size change
     */
    updatePageSize(pageKey: string, sizeDelta: number): void;
    /**
     * Split a page into two pages
     */
    splitPage(pageKey: string, splitPoint: number, newPageKey: string): PageDescriptor;
    /**
     * Get all pages in virtual address order
     */
    getAllPages(): PageDescriptor[];
    /**
     * Find first page that intersects with the range [startPos, endPos)
     */
    private _findFirstIntersecting;
    /**
     * Find last page that intersects with the range [startPos, endPos)
     */
    private _findLastIntersecting;
    /**
     * Get all pages that intersect with the given range
     */
    getPagesInRange(startPos: number, endPos: number): PageDescriptor[];
    /**
     * Recalculate total virtual size
     */
    private _updateVirtualSizes;
    /**
     * Validate the index consistency (for debugging)
     */
    validate(): void;
    /**
     * Validate that hash map is synchronized with pages array
     */
    validateHashMapSync(): void;
}
/**
 * Enhanced Virtual Page Manager with Line Tracking, Marks Integration, and Page Merging
 */
declare class VirtualPageManager implements IVirtualPageManager {
    private buffer;
    private pageSize;
    private nextPageKey;
    addressIndex: PageAddressIndex;
    pageCache: Map<string, IPageInfo>;
    private loadedPages;
    sourceFile: string | null;
    private sourceSize;
    private maxLoadedPages;
    private lruOrder;
    private minPageSize;
    private maxPageSize;
    private lineAndMarksManager;
    constructor(buffer: IBuffer, pageSize?: number, maxMemoryPages?: number);
    /**
     * Set the line and marks manager (called by PagedBuffer)
     */
    setLineAndMarksManager(manager: ILineAndMarksManager): void;
    /**
     * Initialize from a file
     */
    initializeFromFile(filename: string, fileSize: number, _checksum: string): void;
    /**
     * Initialize from string content
     */
    initializeFromContent(content: Buffer): void;
    /**
     * Apply memory limit by evicting excess pages
     */
    private _applyMemoryLimit;
    /**
     * Translate virtual address to page and relative position
     */
    translateAddress(virtualPos: number): Promise<TranslateAddressResult>;
    /**
     * Insert data at a virtual position with line and marks tracking
     */
    insertAt(virtualPos: number, data: Buffer): Promise<number>;
    /**
     * Delete data from a virtual range with line and marks tracking
     */
    deleteRange(startPos: number, endPos: number): Promise<Buffer>;
    /**
     * Read data from a virtual range
     */
    readRange(startPos: number, endPos: number): Promise<Buffer>;
    /**
     * Get total virtual size
     */
    getTotalSize(): number;
    /**
     * Split a page that has grown too large
     */
    private _splitPage;
    /**
     * Check for page merging opportunities
     */
    private _checkForMergeOpportunities;
    /**
     * Merge two adjacent pages
     */
    private _mergePages;
    /**
     * Clean up empty pages and merge small ones
     */
    private _cleanupAndMergePages;
    /**
     * Clean up pages that have become empty
     */
    private _cleanupEmptyPages;
    /**
     * Find the next page after the given page
     */
    private _findNextPage;
    /**
     * Get memory statistics
     */
    getMemoryStats(): VirtualPageManagerMemoryStats;
    /**
     * Create initial page descriptors for a file
     */
    private _createInitialPages;
    /**
     * Enhanced page loading with detachment detection
     */
    _ensurePageLoaded(descriptor: PageDescriptor): Promise<IPageInfo>;
    /**
     * Enhanced corruption handling that properly triggers detachment
     */
    private _handleCorruption;
    /**
     * Determine the specific reason for corruption based on error
     */
    private _determineCorruptionReason;
    /**
     * Enhanced file loading with better corruption detection
     */
    private _loadFromOriginalFile;
    /**
     * Enhanced storage loading with better error handling
     */
    private _loadFromStorage;
    /**
     * Create PageInfo with enhanced line and marks support
     */
    private _createPageInfo;
    /**
     * Update LRU order
     */
    private _updateLRU;
    /**
     * Evict pages if over memory limit
     */
    private _evictIfNeeded;
    /**
     * Evict a specific page with marks preservation and line info caching
     */
    private _evictPage;
    /**
     * Generate unique page Key
     */
    private _generatePageKey;
}
export { VirtualPageManager, PageDescriptor, PageAddressIndex };
//# sourceMappingURL=virtual-page-manager.d.ts.map