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
}