@danielsimonjr/memory-mcp 12.5.2 → 12.7.0

package/dist/features/IOManager.d.ts

@@ -0,0 +1,221 @@
+/**
+ * IO Manager
+ *
+ * Unified manager for import, export, and backup operations.
+ * Consolidates BackupManager, ExportManager, and ImportManager (Sprint 11.4).
+ *
+ * @module features/IOManager
+ */
+import type { ReadonlyKnowledgeGraph, ImportResult, BackupOptions, BackupResult, RestoreResult, ExportOptions, ExportResult } from '../types/index.js';
+import type { GraphStorage } from '../core/GraphStorage.js';
+/**
+ * Supported export formats.
+ */
+export type ExportFormat = 'json' | 'csv' | 'graphml' | 'gexf' | 'dot' | 'markdown' | 'mermaid';
+/**
+ * Supported import formats.
+ */
+export type ImportFormat = 'json' | 'csv' | 'graphml';
+/**
+ * Merge strategies for handling existing entities during import.
+ */
+export type MergeStrategy = 'replace' | 'skip' | 'merge' | 'fail';
+/**
+ * Metadata stored with each backup.
+ * Extended with compression information for Phase 3 Sprint 2.
+ */
+export interface BackupMetadata {
+    /** Timestamp when backup was created (ISO 8601) */
+    timestamp: string;
+    /** Number of entities in the backup */
+    entityCount: number;
+    /** Number of relations in the backup */
+    relationCount: number;
+    /** File size in bytes (compressed size if compressed) */
+    fileSize: number;
+    /** Optional description/reason for backup */
+    description?: string;
+    /** Whether the backup is compressed (default: true for new backups) */
+    compressed?: boolean;
+    /** Original size before compression in bytes */
+    originalSize?: number;
+    /** Compression ratio achieved (compressedSize / originalSize) */
+    compressionRatio?: number;
+    /** Compression format used */
+    compressionFormat?: 'brotli' | 'none';
+}
+/**
+ * Information about a backup file.
+ * Extended with compression details for Phase 3 Sprint 2.
+ */
+export interface BackupInfo {
+    /** Backup file name */
+    fileName: string;
+    /** Full path to backup file */
+    filePath: string;
+    /** Backup metadata */
+    metadata: BackupMetadata;
+    /** Whether the backup is compressed */
+    compressed: boolean;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * Unified manager for import, export, and backup operations.
+ *
+ * Combines functionality from:
+ * - ExportManager: Graph export to various formats
+ * - ImportManager: Graph import from various formats
+ * - BackupManager: Point-in-time backup and restore
+ */
+export declare class IOManager {
+    private storage;
+    private readonly backupDir;
+    constructor(storage: GraphStorage);
+    /**
+     * Export graph to specified format.
+     *
+     * @param graph - Knowledge graph to export
+     * @param format - Export format
+     * @returns Formatted export string
+     */
+    exportGraph(graph: ReadonlyKnowledgeGraph, format: ExportFormat): string;
+    /**
+     * Export graph with optional brotli compression.
+     *
+     * Compression is applied when:
+     * - `options.compress` is explicitly set to `true`
+     * - The exported content exceeds 100KB (auto-compress threshold)
+     *
+     * Compressed content is returned as base64-encoded string.
+     * Uncompressed content is returned as UTF-8 string.
+     *
+     * @param graph - Knowledge graph to export
+     * @param format - Export format
+     * @param options - Export options including compression settings
+     * @returns Export result with content and compression metadata
+     *
+     * @example
+     * ```typescript
+     * // Export with explicit compression
+     * const result = await manager.exportGraphWithCompression(graph, 'json', {
+     *   compress: true,
+     *   compressionQuality: 11
+     * });
+     *
+     * // Export with auto-compression for large graphs
+     * const result = await manager.exportGraphWithCompression(graph, 'json');
+     * // Compresses automatically if content > 100KB
+     * ```
+     */
+    exportGraphWithCompression(graph: ReadonlyKnowledgeGraph, format: ExportFormat, options?: ExportOptions): Promise<ExportResult>;
+    /**
+     * Stream export to a file for large graphs.
+     *
+     * Uses StreamingExporter to write entities and relations incrementally
+     * to avoid loading the entire export content into memory.
+     *
+     * @param format - Export format
+     * @param graph - Knowledge graph to export
+     * @param options - Export options with required outputPath
+     * @returns Export result with streaming metadata
+     * @private
+     */
+    private streamExport;
+    private exportAsJson;
+    private exportAsCsv;
+    private exportAsGraphML;
+    private exportAsGEXF;
+    private exportAsDOT;
+    private exportAsMarkdown;
+    private exportAsMermaid;
+    /**
+     * Import graph from formatted data.
+     *
+     * @param format - Import format
+     * @param data - Import data string
+     * @param mergeStrategy - How to handle conflicts
+     * @param dryRun - If true, preview changes without applying
+     * @returns Import result with statistics
+     */
+    importGraph(format: ImportFormat, data: string, mergeStrategy?: MergeStrategy, dryRun?: boolean): Promise<ImportResult>;
+    private parseJsonImport;
+    private parseCsvImport;
+    private parseGraphMLImport;
+    private mergeImportedGraph;
+    /**
+     * Ensure backup directory exists.
+     */
+    private ensureBackupDir;
+    /**
+     * Generate backup file name with timestamp.
+     * @param compressed - Whether the backup will be compressed (affects extension)
+     */
+    private generateBackupFileName;
+    /**
+     * Create a backup of the current knowledge graph.
+     *
+     * By default, backups are compressed with brotli for 50-70% space reduction.
+     * Use `options.compress = false` to create uncompressed backups.
+     *
+     * @param options - Backup options (compress, description) or legacy description string
+     * @returns Promise resolving to BackupResult with compression statistics
+     *
+     * @example
+     * ```typescript
+     * // Compressed backup (default)
+     * const result = await manager.createBackup({ description: 'Pre-migration backup' });
+     * console.log(`Compressed from ${result.originalSize} to ${result.compressedSize} bytes`);
+     *
+     * // Uncompressed backup
+     * const result = await manager.createBackup({ compress: false });
+     * ```
+     */
+    createBackup(options?: BackupOptions | string): Promise<BackupResult>;
+    /**
+     * List all available backups, sorted by timestamp (newest first).
+     *
+     * Detects both compressed (.jsonl.br) and uncompressed (.jsonl) backups.
+     *
+     * @returns Promise resolving to array of backup information with compression details
+     */
+    listBackups(): Promise<BackupInfo[]>;
+    /**
+     * Restore the knowledge graph from a backup file.
+     *
+     * Automatically detects and decompresses brotli-compressed backups (.br extension).
+     * Maintains backward compatibility with uncompressed backups.
+     *
+     * @param backupPath - Path to the backup file to restore from
+     * @returns Promise resolving to RestoreResult with restoration details
+     *
+     * @example
+     * ```typescript
+     * // Restore from compressed backup
+     * const result = await manager.restoreFromBackup('/path/to/backup.jsonl.br');
+     * console.log(`Restored ${result.entityCount} entities from compressed backup`);
+     *
+     * // Restore from uncompressed backup (legacy)
+     * const result = await manager.restoreFromBackup('/path/to/backup.jsonl');
+     * ```
+     */
+    restoreFromBackup(backupPath: string): Promise<RestoreResult>;
+    /**
+     * Delete a specific backup file.
+     *
+     * @param backupPath - Path to the backup file to delete
+     */
+    deleteBackup(backupPath: string): Promise<void>;
+    /**
+     * Clean old backups, keeping only the most recent N backups.
+     *
+     * @param keepCount - Number of recent backups to keep (default: 10)
+     * @returns Promise resolving to number of backups deleted
+     */
+    cleanOldBackups(keepCount?: number): Promise<number>;
+    /**
+     * Get the path to the backup directory.
+     */
+    getBackupDir(): string;
+}
+//# sourceMappingURL=IOManager.d.ts.map

package/dist/features/IOManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IOManager.d.ts","sourceRoot":"","sources":["../../src/features/IOManager.ts"],"names":[],"mappings":"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"}