@fractal-synapse/storage-mock

In-memory mock storage plugin for Fractal Synapse that provides the same API as the existing storage-fs plugin but operates entirely in memory. This plugin is specifically designed for testing scenarios where actual file system operations are not desired.

Features

• Full API Compatibility: Implements PluginStorageInterface identically to storage-fs
• In-Memory Storage: Uses Map<string, string | Buffer> for fast, isolated storage
• Cross-Platform Path Support: Handles Windows (\) and Unix (/) path separators consistently
• Directory Simulation: Parses stored file paths to simulate directory structure
• Configuration Object Pattern: Flexible constructor accepting configuration object
• Logging Interface: Integrated logging support with customizable logger
• Testing Utilities: Additional methods for test inspection and management

Installation

npm install @fractal-synapse/storage-mock

Usage

Basic Usage

import { StorageMockPlugin } from '@fractal-synapse/storage-mock';

// Create plugin instance with default configuration
const plugin = new StorageMockPlugin();

// Create plugin instance with custom app name
const plugin = new StorageMockPlugin({ appName: 'test-app' });

// Create plugin instance with custom logger
import { getLogger } from '@fractal-synapse/agent-core';
const plugin = new StorageMockPlugin({
  appName: 'test-app',
  logger: getLogger()
});

// Save files
await plugin.saveFile('config/settings.json', '{"debug": true}');
await plugin.saveFile('data/binary.bin', Buffer.from([1, 2, 3, 4]));

// Load files
const data = await plugin.loadFile('config/settings.json');
const buffer = await plugin.loadFile('data/binary.bin');

// Check file existence
const exists = await plugin.exists('config/settings.json'); // true

// List files in directory
const files = await plugin.listFiles('config'); // ['settings.json']
const allFiles = await plugin.listFiles(); // ['config/settings.json', 'data/binary.bin']

// Delete files
const deleted = await plugin.deleteFile('config/settings.json'); // true

Plugin Registry Integration

import { PluginRegistry } from '@fractal-synapse/agent-core';
import { StorageMockPlugin } from '@fractal-synapse/storage-mock';

const pluginRegistry = new PluginRegistry();
pluginRegistry.register(new StorageMockPlugin({ appName: 'my-app' }));

Testing Utilities

// Get current file count
console.log(`Stored files: ${plugin.getStoredFileCount()}`);

// Get all stored paths
console.log(`All paths: ${plugin.getAllStoredPaths()}`);

// Get mock storage directory identifier
console.log(`Storage dir: ${plugin.getStorageDir()}`); // "mock://app-name"

// Clean up for test isolation
await plugin.cleanup();

API Reference

Constructor

constructor(config: StorageMockPluginConfig = {})

Accepts a configuration object with the following optional properties:

• appName?: string - Application name for storage identification (default: 'mock-app')
• storage?: PluginStorageInterface - Custom storage implementation (for future extensibility)
• logger?: LoggingInterface - Custom logger implementation (default: uses getLogger() from agent-core)

export interface StorageMockPluginConfig {
  appName?: string;
  storage?: PluginStorageInterface;
  logger?: LoggingInterface;
}

Core Methods

All methods implement the PluginStorageInterface:

saveFile(filePath: string, data: string | Buffer): Promise<void>

Store string or Buffer data in memory.

loadFile(filePath: string): Promise<string | Buffer | null>

Retrieve data from memory. Returns null if file doesn't exist.

deleteFile(filePath: string): Promise<boolean>

Remove file from memory. Returns true if file was deleted, false if it didn't exist.

exists(filePath: string): Promise<boolean>

Check if file exists in memory storage.

listFiles(dirPath?: string): Promise<string[]>

List files and subdirectories. Without dirPath, lists all files. Results are sorted alphabetically.

getStorageDir(): string

Returns the mock storage directory identifier (mock://app-name).

cleanup(): Promise<void>

Clear all stored files from memory.

Testing Utilities

getStoredFileCount(): number

Returns the current number of stored files.

getAllStoredPaths(): string[]

Returns a sorted array of all stored file paths.

Testing

The plugin includes comprehensive tests covering:

• Plugin Lifecycle: Initialization, cleanup, storage directory identification
• Configuration: Constructor config object patterns, default values
• Logging: Custom logger integration, default logger fallback
• File Operations: Text/binary save/load, JSON handling, nested paths
• File Management: Existence checking, deletion, path normalization
• Directory Operations: Listing, empty directories, nested structures
• File Type Support: Markdown, CSV, XML, binary data
• Error Handling: Edge cases and path normalization

Run tests:

npm test        # Watch mode
npm run test:run # Single run

Performance Characteristics

• Memory Usage: Linear with stored data size
• Operation Speed: O(1) for save/load/exists, O(n) for listFiles
• Cleanup: O(1) - simple Map clear operation
• Path Normalization: O(1) per operation

Use Cases

Perfect for:

• Unit tests requiring storage functionality
• Integration tests with controlled data
• CI/CD environments without file system access
• Rapid test execution without I/O overhead
• Development environments requiring isolated storage
• Testing scenarios requiring custom logging
• Plugin development with configurable dependencies

License

Part of the Fractal Synapse project.