filesystem

IDE filesystem(s)

Virtual filesystem for browser environments with pluggable storage backends.

Coverage

Usage

Import

import { FileSystem } from './filesystem.js';
import { MemoryFS } from './connectors/memory/memory.js';
import { LocalStorageFS } from './connectors/localstorage/localstorage.js';
import { IDBFS } from './connectors/indexeddb/indexeddb.js';
import { CacheFS } from './connectors/cache/cache.js';
import { RemoteFS } from './connectors/remote/remote.js';

Create Filesystem Instance

// Choose a connector based on your needs
const connector = new MemoryFS();           // Fast, non-persistent
const connector = new LocalStorageFS();     // Browser localStorage
const connector = new IDBFS(indexedDB);     // IndexedDB (larger storage)
const connector = new RemoteFS({ PORT: 8080 }); // Remote server

// Wrap with cache for performance
const cachedConnector = new CacheFS(connector);

// Create filesystem interface
const fs = new FileSystem(cachedConnector);

File Operations

// Write file
await fs.writeFile('project/main.asm', 'ORG 0\nLD A,42\n');

// Read file
const content = await fs.readFile('project/main.asm');

// Check existence
const exists = await fs.exists('project/main.asm');

// Get file size
const size = await fs.size('project/main.asm');

// Get modification time
const mtime = await fs.mtime('project/main.asm');

// List directory - returns immediate subdirectories only (directories with trailing /)
const files = await fs.readdir('project/');
// ['lib/', 'output/']

// List with full names - returns all files and directories in the directory
const files = await fs.readdir('project/', true);
// ['lib/', 'main.asm', 'output/']

// List with full paths - returns all items with full path from root
const files = await fs.readdir('project/', false, true);
// ['project/lib/', 'project/main.asm', 'project/output/']

// Rename
await fs.rename('old.asm', 'new.asm');

// Copy
await fs.copyFile('source.asm', 'dest.asm');

// Delete
await fs.unlink('project/main.asm');

Directory Structure

Virtual filesystem uses flat structure with path-like names:

project/
├── main.asm
├── lib/
│   └── macros.asm
└── output/
    └── program.bin

Use names like 'project/main.asm', 'project/lib/macros.asm'.

Connectors

| Connector | Description | Persistence | Capacity | |-----------|-------------|-------------|----------| | MemoryFS | In-memory object | No | Unlimited (RAM) | | LocalStorageFS | Browser localStorage | Yes | ~5MB | | IDBFS | IndexedDB | Yes | ~50MB+ | | CacheFS | Wrapper with caching | Depends on backend | Depends on backend | | RemoteFS | HTTP API backend | Yes (remote) | Unlimited |

CacheFS

Provides transparent caching layer:

• Lazy read-through: Files loaded on first read, cached in memory
• Write-through: Writes go to cache AND backend immediately

const backend = new IDBFS(indexedDB);
const cached = new CacheFS(backend);
const fs = new FileSystem(cached);

API Reference

FileSystem Class

| Method | Description | |--------|-------------| | readFile(name) | Read file content, returns Promise<string> | | writeFile(name, data) | Write content to file, returns Promise<void> | | exists(name) | Check if file exists, returns Promise<boolean> | | size(name) | Get file size in bytes, returns Promise<number> | | mtime(name) | Get modification timestamp, returns Promise<number> | | readdir(name, fullnames, fullpath) | List directory contents. fullnames=true includes files, not just subdirectories. fullpath=true returns full paths from root. | | rename(name, newName) | Rename file | | copyFile(name, newName) | Copy file | | unlink(name) | Delete file |

Connector Interface

All connectors implement:

{
  readFile: async (name) => string,
  writeFile: async (name, data) => void,
  exists: async (name) => boolean,
  size: async (name) => number,
  mtime: async (name) => number,
  readdir: async () => string[],
  rename: async (name, newName) => void,
  copyFile: async (name, newName) => void,
  unlink: async (name) => void
}