@firesystem/workspace

Revolutionary Multi-Project Workspace Manager - The first file system workspace that enables multiple projects running simultaneously in parallel, breaking the traditional "one project = one filesystem" paradigm. Unlike IDEs that switch between projects, Firesystem Workspace keeps ALL projects active and accessible at once.


🚀 Why This Changes Everything

Traditional development environments work with one active project at a time:

``typescript
// ❌ Traditional approach (VSCode, etc.)
await closeProject("frontend"); // Lost from memory
await openProject("backend"); // Only this is accessible
await closeProject("backend"); // Lost from memory
await openProject("database"); // Only this is accessible
`

Firesystem Workspace revolutionizes this:

`typescript
// ✅ Revolutionary approach - ALL PROJECTS ACTIVE SIMULTANEOUSLY
const frontend = workspace.getProject("frontend"); // Always accessible
const backend = workspace.getProject("backend"); // Always accessible
const database = workspace.getProject("database"); // Always accessible

// Cross-project operations without switching context
const config = await backend.fs.readFile("/config/database.json");
await database.fs.writeFile("/import/backend-config.json", config);
await frontend.fs.writeFile("/src/api-config.json", config);

// One project focused for UI, but ALL remain active
workspace.setActiveProject("frontend"); // Just changes UI focus
`

🌟 Revolutionary Features

$3

- Multiple file systems active simultaneously - not just "open tabs"
- Cross-project operations - copy/sync data between different storage types
- Zero context switching - all projects remain in memory and accessible
- Focus vs Active - UI shows one project, but all remain operational

$3

- Workspace knows NOTHING about specific implementations
- Completely extensible - anyone can create providers for any storage
- Zero dependencies - workspace has no file system implementations
- Capability-aware - each provider declares what it can/cannot do

$3

- Hot enable/disable - pause projects for performance without losing config
- Automatic cleanup - orphaned references removed on startup
- Memory optimization - smart resource management for hundreds of projects
- Persistent state - everything survives restarts

$3

- Complete deletion support - remove projects with optional data cleanup
- Provider-aware deletion - knows which providers store local vs remote data
- Confirmation events - intercept and cancel deletions programmatically
- Storage estimation - see how much space will be freed before deleting

📦 Installation

`bash
npm install @firesystem/workspace @firesystem/core


or

yarn add @firesystem/workspace @firesystem/core

or

pnpm add @firesystem/workspace @firesystem/core
`

🚀 Quick Start

$3

`typescript
import { WorkspaceFileSystem } from "@firesystem/workspace";
import { memoryProvider } from "@firesystem/memory/provider";
import { indexedDBProvider } from "@firesystem/indexeddb/provider";

// Create workspace and register providers
const workspace = new WorkspaceFileSystem();
workspace.registerProvider(memoryProvider);
workspace.registerProvider(indexedDBProvider);

// Initialize (restores previous state automatically)
await workspace.initialize();

// Load multiple projects simultaneously
const devProject = await workspace.loadProject({
id: "dev-env",
name: "Development Environment",
source: {
type: "memory",
config: {
initialData: {
"/src/app.ts": { content: "console.log('dev');" },
"/config/dev.json": { content: JSON.stringify({ env: "development" }) }
}
}
}
});

const prodBackup = await workspace.loadProject({
id: "prod-backup",
name: "Production Backup",
source: {
type: "indexeddb",
config: { dbName: "production-backup" }
}
});

// ALL PROJECTS ARE NOW ACTIVE AND ACCESSIBLE!
console.log("Active projects:", workspace.getProjects().length); // 2

// Cross-project operations (the revolutionary part!)
const prodConfig = await prodBackup.fs.readFile("/config/production.json");
await devProject.fs.writeFile("/config/prod-copy.json", prodConfig.content);

// Work with the focused project transparently
workspace.setActiveProject("dev-env");
await workspace.writeFile("/test.js", "// This goes to dev-env");

// But other projects remain accessible
await prodBackup.fs.writeFile("/logs/import.log", "Config copied to dev");
`

🎯 Core Concepts

$3

Unlike traditional workspaces that handle one project at a time:

`typescript
// Traditional: Only one project accessible
const currentProject = getCurrentProject(); // Only this exists

// Firesystem: All projects accessible simultaneously
const projects = workspace.getProjects(); // All active projects
const dev = workspace.getProject("dev");
const staging = workspace.getProject("staging");
const prod = workspace.getProject("prod");

// Work with all at once
const devConfig = await dev.fs.readFile("/config.json");
const stagingData = await staging.fs.glob("*/.log");
await prod.fs.writeFile("/backup/dev-config.json", devConfig.content);
`

$3

- Active Projects: Loaded in memory, consuming resources, ready for operations
- Focused Project: The project shown in UI (File Explorer), receives direct operations
- Disabled Projects: Configuration preserved but not loaded, zero resource usage

`typescript
// Load multiple projects - all become active
await workspace.loadProject({ id: "app", source: { type: "memory" } });
await workspace.loadProject({ id: "docs", source: { type: "indexeddb" } });
await workspace.loadProject({ id: "assets", source: { type: "s3" } });

// Set focus for UI - others remain active
await workspace.setActiveProject("app"); // File Explorer shows "app"

// Direct access to any project
const docs = workspace.getProject("docs");
const assets = workspace.getProject("assets");

// Proxy operations go to focused project
await workspace.writeFile("/test.txt", "content"); // Goes to "app"

// Direct operations go to specific project
await docs.fs.writeFile("/readme.md", "# Documentation");
await assets.fs.writeFile("/logo.png", imageData);
`

$3

`typescript
// Disable projects for performance (keeps config)
await workspace.disableProject("large-dataset"); // Frees memory, keeps config

// Re-enable when needed
await workspace.enableProject("large-dataset"); // Reconstructs from config

// Batch operations
await workspace.disableProjects(["old-1", "old-2", "old-3"]);
await workspace.enableProjects(["needed-1", "needed-2"]);

// Auto-optimization settings
const workspace = new WorkspaceFileSystem({
settings: {
maxActiveProjects: 5, // Auto-disable least recently used
autoDisableAfter: 30 60 1000, // 30 minutes of inactivity
keepFocusedActive: true // Never auto-disable focused project
}
});
`

$3

Delete projects with full control over data cleanup:

`typescript
// Delete project configuration only (preserves data)
await workspace.deleteProject("temp-project");

// Delete project AND its data
await workspace.deleteProject("old-project", {
deleteData: true
});

// With confirmation event
workspace.events.on("project:delete-confirm", (event) => {
if (!confirm(Delete ${event.project.name}?)) {
event.cancelled = true; // Cancel deletion
}
});

// Skip confirmation for automation
await workspace.deleteProject("temp-project", {
skipConfirmation: true,
deleteData: true
});
`

🔌 Provider System

The workspace is completely agnostic about file systems. Providers encapsulate all implementation knowledge:

$3

| Provider | Package | Type | Description |
|----------|---------|------|-------------|
| Memory | @firesystem/memory/provider | "memory" | In-memory, fast iteration |
| IndexedDB | @firesystem/indexeddb/provider | "indexeddb" | Browser persistent storage |
| S3* | @firesystem/s3/provider | "s3" | AWS S3 cloud storage |
| GitHub* | @firesystem/github/provider | "github" | GitHub repository |
| API* | @firesystem/api/provider | "api" | REST API backend |

*Coming soon

$3

`typescript
import { WorkspaceFileSystem } from "@firesystem/workspace";
import { memoryProvider } from "@firesystem/memory/provider";
import { indexedDBProvider } from "@firesystem/indexeddb/provider";

const workspace = new WorkspaceFileSystem();

// Register only what you need
workspace.registerProvider(memoryProvider);
workspace.registerProvider(indexedDBProvider);

// Provider capabilities are automatically detected
const memoryCapabilities = workspace.getProvider("memory")?.getCapabilities();
console.log(memoryCapabilities.supportsWatch); // true
console.log(memoryCapabilities.readonly); // false
`

$3

`typescript
import type { SourceProvider } from "@firesystem/workspace";
import { withEvents } from "@firesystem/core";

class DropboxProvider implements SourceProvider {
readonly scheme = "dropbox";
readonly displayName = "Dropbox Storage";

async createFileSystem(config: DropboxConfig) {
const baseFs = new DropboxFileSystem(config);
return withEvents(baseFs); // Add reactive events
}

getCapabilities() {
return {
readonly: false,
caseSensitive: false,
atomicRename: true,
supportsWatch: false, // Dropbox limitation
supportsMetadata: true,
maxFileSize: 150 1024 1024 // 150MB
};
}

async validateConfiguration(config: any) {
const errors = [];
if (!config.accessToken) errors.push("Access token required");
return { valid: errors.length === 0, errors };
}

// Optional: Data management methods
deleteProjectData?(config: DropboxConfig): Promise {
// Remove Dropbox app folder if needed
}

hasLocalData(): boolean {
return false; // Dropbox is cloud storage
}

async estimateDataSize(config: DropboxConfig): Promise {
// Could query Dropbox API for folder size
return null;
}
}

// Register and use
workspace.registerProvider(new DropboxProvider());
await workspace.loadProject({
id: "my-dropbox",
name: "Dropbox Files",
source: {
type: "dropbox",
config: { accessToken: "...", path: "/projects" }
}
});
`

🔄 Cross-Project Operations

The revolutionary feature that enables true multi-project workflows:

$3

`typescript
// Load different storage types
const memory = await workspace.loadProject({
id: "temp",
source: { type: "memory", config: {} }
});

const persistent = await workspace.loadProject({
id: "storage",
source: { type: "indexeddb", config: { dbName: "app-data" } }
});

// Copy files between different storage types
await workspace.copyFiles(
"temp", // Source project
"/work/*.json", // Source pattern
"storage", // Target project
"/backup/" // Target directory
);
`

$3

`typescript
// Sync entire project from S3 to local IndexedDB
await workspace.syncProjects("s3-backup", "local-cache", {
direction: "source-to-target",
deleteOrphaned: false,
skipExisting: true
});
`

$3

`typescript
const diff = await workspace.compareProjects("dev", "staging");
console.log(diff.added); // Files in staging not in dev
console.log(diff.removed); // Files in dev not in staging
console.log(diff.modified); // Files that differ
`

$3

`typescript
// Set up multi-stage data pipeline
const rawData = await workspace.loadProject({
id: "s3-raw",
source: { type: "s3", config: { bucket: "raw-data" } }
});

const processing = await workspace.loadProject({
id: "memory-work",
source: { type: "memory", config: {} }
});

const results = await workspace.loadProject({
id: "indexeddb-cache",
source: { type: "indexeddb", config: { dbName: "results" } }
});

// Process: S3 → Memory → IndexedDB
const files = await rawData.fs.glob("batch-*.json");
for (const file of files) {
// 1. Read from S3
const data = await rawData.fs.readFile(file);

// 2. Process in memory (fast)
const processed = await processData(JSON.parse(data.content));
await processing.fs.writeFile(/work${file}, JSON.stringify(processed));

// 3. Save results to IndexedDB (persistent)
await results.fs.writeFile(/final${file}, JSON.stringify(processed));
}
`

📡 Event System

Unified events across all projects with rich context:

`typescript
// Project lifecycle events
workspace.events.on("project:loaded", ({ project }) => {
console.log(✅ ${project.name} loaded (${project.source.type}));
});

workspace.events.on("project:activated", ({ projectId, previousId }) => {
console.log(🔄 Switched from ${previousId} to ${projectId});
});

// File operations with project context
workspace.events.on("project:file:written", ({ projectId, path, size }) => {
console.log(📝 ${path} written in ${projectId} (${size} bytes));
});

// Cross-project operations
workspace.events.on("workspace:sync:completed", ({ sourceId, targetId, stats }) => {
console.log(🔄 Synced ${stats.files} files from ${sourceId} to ${targetId});
});

// Performance events with enhanced data
workspace.events.on("project:disabled", ({ projectId, hasLocalData, reason }) => {
console.log(💤 ${projectId} disabled);
console.log( Has local data: ${hasLocalData});
console.log( Reason: ${reason});
});

workspace.events.on("project:enabled", ({ projectId }) => {
console.log(⚡ ${projectId} re-enabled);
});

// Deletion events
workspace.events.on("project:deleted", ({ projectId, deletedData }) => {
console.log(🗑️ ${projectId} deleted${deletedData ? ' with data' : ''});
});
`

💾 Persistent State & Auto-Recovery

$3

`typescript
const workspace = new WorkspaceFileSystem();
await workspace.initialize(); // Automatically restores:
// - All previously loaded projects
// - Active project selection
// - Project configurations
// - Settings and preferences

// State is automatically saved when:
// - Projects are loaded/unloaded
// - Active project changes
// - Settings are modified
// - Projects are enabled/disabled
`

$3

The workspace automatically handles corrupted state:

`typescript
// Before v1.0.3: Could crash with "NotFoundError"
// v1.0.3+: Automatically cleans up orphaned references

await workspace.initialize(); // Always succeeds

// Console output:
// ⚠️ Removing orphaned activeProjectId: deleted-project-123
// ⚠️ Removing orphaned recentProjectId: missing-project-456
// ℹ️ Workspace state cleaned: removed orphaned project references
`

$3

`typescript
// Discover existing IndexedDB projects
const discovered = await workspace.discoverIndexedDBProjects();
console.log("Found projects:", discovered.map(p => p.name));

// Load discovered projects
for (const project of discovered) {
await workspace.loadProject(project);
}

// Get all disabled projects (async now)
const disabledProjects = await workspace.getDisabledProjects();
console.log(${disabledProjects.length} projects are disabled);
`

🔐 Security & Credentials

$3

`bash


S3 credentials

FIRESYSTEM_S3_ACCESS_KEY_ID=your_access_key
FIRESYSTEM_S3_SECRET_ACCESS_KEY=your_secret_key
FIRESYSTEM_S3_REGION=us-east-1

GitHub token

FIRESYSTEM_GITHUB_TOKEN=ghp_xxxxxxxxxxxx

API credentials

FIRESYSTEM_API_API_KEY=your_api_key
`

$3

`typescript
// Credentials requested when needed
const s3Project = await workspace.loadProject({
id: "cloud-files",
source: {
type: "s3",
config: { bucket: "my-bucket" }
// No credentials in config - resolved from environment
}
});

// Custom credential providers
workspace.registerCredentialProvider("s3", new InteractiveCredentialProvider({
prompt: async (message, secure) => {
return await showCredentialDialog(message, secure);
}
}));
`

$3

`typescript
// Exports are automatically sanitized
const exportData = await workspace.exportWorkspace({
includeFiles: true,
includeCredentials: false // Never exports credentials
});

// Safe for sharing/version control
await workspace.exportToGitHubGist({
token: "ghp_...",
description: "Team Workspace Configuration",
public: false
});
`

⚛️ Framework Integration

$3

`typescript
import { create } from "zustand";
import { WorkspaceFileSystem } from "@firesystem/workspace";

interface WorkspaceStore {
workspace: WorkspaceFileSystem | null;
projects: Project[];
activeProject: Project | null;

initWorkspace: () => Promise;
createProject: (name: string, type: string) => Promise;
switchProject: (projectId: string) => Promise;
deleteProject: (projectId: string, deleteData?: boolean) => Promise;
}

const useWorkspaceStore = create((set, get) => ({
workspace: null,
projects: [],
activeProject: null,

async initWorkspace() {
const workspace = new WorkspaceFileSystem();
await workspace.initialize(); // Auto-restores state

// Setup reactive events
workspace.events.on("project:loaded", ({ project }) => {
set(state => ({
projects: [...state.projects, project]
}));
});

workspace.events.on("project:activated", ({ projectId }) => {
const project = workspace.getProject(projectId);
set({ activeProject: project });
});

workspace.events.on("project:deleted", ({ projectId }) => {
set(state => ({
projects: state.projects.filter(p => p.id !== projectId),
activeProject: state.activeProject?.id === projectId ? null : state.activeProject
}));
});

set({
workspace,
projects: workspace.getProjects(),
activeProject: workspace.getActiveProject()
});
},

async createProject(name: string, type: string) {
const { workspace } = get();
if (!workspace) return;

const project = await workspace.loadProject({
id: project-${Date.now()},
name,
source: { type, config: {} }
});

await workspace.setActiveProject(project.id);
},

async switchProject(projectId: string) {
const { workspace } = get();
if (!workspace) return;

await workspace.setActiveProject(projectId);
},

async deleteProject(projectId: string, deleteData = false) {
const { workspace } = get();
if (!workspace) return;

await workspace.deleteProject(projectId, { deleteData });
}
}));

// React component
function MultiProjectIDE() {
const {
workspace,
projects,
activeProject,
initWorkspace,
createProject,
switchProject,
deleteProject
} = useWorkspaceStore();

useEffect(() => {
initWorkspace();
}, []);

return (



);
}
`

$3

`typescript
import { ref, reactive, onMounted } from 'vue';
import { WorkspaceFileSystem } from '@firesystem/workspace';

export function useWorkspace() {
const workspace = ref(null);
const projects = ref([]);
const activeProject = ref(null);

const initWorkspace = async () => {
workspace.value = new WorkspaceFileSystem();
await workspace.value.initialize();

workspace.value.events.on('project:loaded', ({ project }) => {
projects.value.push(project);
});

workspace.value.events.on('project:activated', ({ projectId }) => {
activeProject.value = workspace.value!.getProject(projectId);
});

workspace.value.events.on('project:deleted', ({ projectId }) => {
projects.value = projects.value.filter(p => p.id !== projectId);
if (activeProject.value?.id === projectId) {
activeProject.value = null;
}
});

projects.value = workspace.value.getProjects();
activeProject.value = workspace.value.getActiveProject();
};

const createProject = async (name: string, type: string) => {
if (!workspace.value) return;

const project = await workspace.value.loadProject({
id: project-${Date.now()},
name,
source: { type, config: {} }
});

await workspace.value.setActiveProject(project.id);
};

const deleteProject = async (projectId: string, deleteData = false) => {
if (!workspace.value) return;

await workspace.value.deleteProject(projectId, { deleteData });
};

return {
workspace,
projects,
activeProject,
initWorkspace,
createProject,
deleteProject
};
}
`

🌍 Real-World Use Cases

$3

`typescript
class DevelopmentWorkspace {
async setup() {
// Load all environments simultaneously
const local = await workspace.loadProject({
id: "local-dev",
source: { type: "memory", config: {} }
});

const staging = await workspace.loadProject({
id: "staging-mirror",
source: { type: "indexeddb", config: { dbName: "staging-cache" } }
});

const production = await workspace.loadProject({
id: "prod-readonly",
source: { type: "s3", config: { bucket: "prod-backup" } }
});

// Copy production config to development
const prodConfig = await production.fs.readFile("/config/app.json");
await local.fs.writeFile("/config/prod-like.json", prodConfig.content);

// Sync staging data for testing
await workspace.syncProjects("staging-mirror", "local-dev", {
include: ["data/*/.json"],
exclude: ["data/sensitive/**"]
});
}
}
`

$3

`typescript
class ContentPipeline {
async processContent() {
// Multiple content sources active simultaneously
const cms = await workspace.loadProject({
id: "cms-api",
source: { type: "api", config: { baseUrl: "https://cms.example.com" } }
});

const assets = await workspace.loadProject({
id: "cdn-assets",
source: { type: "s3", config: { bucket: "cdn-assets" } }
});

const cache = await workspace.loadProject({
id: "local-cache",
source: { type: "indexeddb", config: { dbName: "content-cache" } }
});

// Process content across all sources
const articles = await cms.fs.glob("/articles/*.json");
for (const article of articles) {
const content = await cms.fs.readFile(article);
const processed = await this.processArticle(content);

// Cache processed content
await cache.fs.writeFile(article, processed);

// Upload assets
if (processed.images) {
for (const image of processed.images) {
await assets.fs.writeFile(/images/${image.name}, image.data);
}
}
}
}
}
`

$3

`typescript
class DataAnalysisWorkspace {
async analyzeData() {
// Load datasets from different sources
const rawData = await workspace.loadProject({
id: "data-lake",
source: { type: "s3", config: { bucket: "analytics-data" } }
});

const processing = await workspace.loadProject({
id: "analysis-memory",
source: { type: "memory", config: {} }
});

const results = await workspace.loadProject({
id: "results-db",
source: { type: "indexeddb", config: { dbName: "analysis-results" } }
});

// Cross-dataset analysis
const datasets = await rawData.fs.glob("datasets/*/.csv");
const analysis = {
totalRows: 0,
correlations: {},
summaries: {}
};

// Process each dataset in memory for speed
for (const dataset of datasets) {
const data = await rawData.fs.readFile(dataset);
const processed = await this.analyzeDataset(data.content);

// Store intermediate results in memory
await processing.fs.writeFile(/processed/${dataset}, processed);

// Aggregate analysis
analysis.totalRows += processed.rows;
analysis.summaries[dataset] = processed.summary;
}

// Save final results
await results.fs.writeFile("/analysis/summary.json", JSON.stringify(analysis));
}
}
`

📊 Performance & Best Practices

$3

`typescript
// Configure auto-optimization
const workspace = new WorkspaceFileSystem({
settings: {
maxActiveProjects: 5, // Auto-disable oldest
autoDisableAfter: 30 60 1000, // 30 minutes inactive
keepFocusedActive: true, // Never disable focused
memoryThreshold: 500 1024 1024 // 500MB threshold
}
});

// Manual optimization
const stats = await workspace.getProjectStats();
console.log(stats);
// {
// total: 15,
// active: 5,
// disabled: 10,
// memoryUsage: "245MB",
// connections: { s3: 2, api: 1 }
// }

// Optimize when needed
if (stats.memoryUsage > threshold) {
await workspace.optimizeMemoryUsage();
}
`

$3

`typescript
// Batch operations across projects
const operations = [
{ project: "dev", operation: () => dev.fs.writeFile("/a.txt", "content") },
{ project: "staging", operation: () => staging.fs.writeFile("/b.txt", "content") },
{ project: "prod", operation: () => prod.fs.readFile("/config.json") }
];

await Promise.all(operations.map(op => op.operation()));

// Use project capabilities efficiently
const provider = workspace.getProvider("s3");
if (provider?.getCapabilities().supportsGlob) {
const files = await s3Project.fs.glob("*/.log");
} else {
// Fallback for providers without glob
const files = await this.manualGlob(s3Project, "*/.log");
}
`

$3

`typescript
// Robust multi-project error handling
async function robustOperation() {
const results = { success: [], failed: [] };

for (const project of workspace.getProjects()) {
try {
await project.fs.writeFile("/health-check.txt", new Date().toISOString());
results.success.push(project.id);
} catch (error) {
console.warn(Health check failed for ${project.id}:, error.message);
results.failed.push({ project: project.id, error: error.message });

// Auto-disable problematic projects
if (error.message.includes("network") || error.message.includes("credentials")) {
await workspace.disableProject(project.id);
}
}
}

return results;
}
`

🧪 Testing

The workspace includes comprehensive test coverage with a focus on core functionality:

`bash


Run all tests

pnpm test

Core functionality tests

pnpm test tests/core/

Specific test suites

pnpm test tests/core/ProjectManagement.test.ts # Load/unload/delete
pnpm test tests/core/ProjectStateManagement.test.ts # Enable/disable
pnpm test tests/core/CrossProjectOperations.test.ts # Multi-project ops
pnpm test tests/core/FileSystemProxy.test.ts # Transparent proxy
pnpm test tests/core/ProviderValidation.test.ts # Provider system
`

$3

- Unit Tests: Core workspace logic with mocked providers (fast, deterministic)
- Integration Tests: Real provider implementations (in individual packages)
- Mocked Providers: Complete FileSystem mocks with configurable capabilities
- Edge Cases: Orphaned references, capability limitations, error scenarios

🏗️ Architecture

The workspace system follows a modular architecture with clear separation of concerns:

$3

`
src/
├── WorkspaceFileSystem.ts # Main orchestrator class (~900 lines)
├── managers/ # Business logic managers
│ ├── ProjectManager.ts # Project lifecycle and loading
│ ├── PerformanceManager.ts # Memory optimization and metrics
│ ├── PersistenceManager.ts # State persistence and restoration
│ └── EventManager.ts # Event forwarding and enrichment
├── operations/ # Cross-cutting operations
│ ├── ProjectOperations.ts # Copy, sync, compare between projects
│ └── FileSystemProxy.ts # IReactiveFileSystem delegation
├── credentials/ # Credential management (provider-agnostic)
├── import-export/ # Workspace import/export functionality
└── interfaces/ # Core interfaces and types

`

$3

1. Single Responsibility: Each module handles one specific aspect
2. Provider Agnostic: Core knows nothing about specific implementations
3. Dependency Injection: Modules receive dependencies via constructor
4. Event-Driven: Reactive architecture with typed events
5. Testable: Small, focused modules that are easy to test

$3

- ProjectManager: Handles project loading, unloading, and conversion
- PerformanceManager: Monitors memory usage and optimizes resources
- PersistenceManager: Manages database operations and state restoration
- EventManager: Forwards filesystem events with project context
- ProjectOperations: Implements cross-project operations
- FileSystemProxy: Delegates all filesystem calls to active project

📚 Documentation

Explore our comprehensive guides to master Firesystem Workspace:

- Project Lifecycle Management - Complete guide to loading, enabling/disabling, and deleting projects
- Event System Guide - Master the reactive event system for real-time updates
- Provider System Guide - Learn how to work with providers and create custom storage implementations
- Cross-Project Operations - Unlock the power of multi-project workflows
- React Integration Guide - Build modern React apps with Firesystem Workspace

For code examples, check out the examples directory.

📚 API Reference

$3

`typescript
class WorkspaceFileSystem implements IReactiveFileSystem {
// Project Management
async loadProject(config: ProjectConfig): Promise
async unloadProject(projectId: string): Promise
getProject(projectId: string): Project | null
getProjects(): Project[]
async setActiveProject(projectId: string): Promise
getActiveProject(): Project | null

// Project Lifecycle
async deleteProject(projectId: string, options?: DeleteProjectOptions): Promise
async disableProject(projectId: string): Promise
async enableProject(projectId: string): Promise
async disableProjects(projectIds: string[]): Promise
async enableProjects(projectIds: string[]): Promise
isProjectEnabled(projectId: string): boolean
async getDisabledProjects(): Promise

// Cross-Project Operations
async copyFiles(sourceId: string, pattern: string, targetId: string, targetPath: string): Promise
async syncProjects(sourceId: string, targetId: string, options?: SyncOptions): Promise
async compareProjects(projectId1: string, projectId2: string): Promise

// Provider Management
registerProvider(provider: SourceProvider): void
unregisterProvider(scheme: string): void
getProvider(scheme: string): SourceProvider | undefined
getRegisteredProviders(): SourceProvider[]

// Performance & Statistics
async getProjectStats(): Promise
async getProjectMetrics(projectId: string): Promise
async optimizeMemoryUsage(): Promise

// Discovery & Persistence
async discoverIndexedDBProjects(): Promise
async exportWorkspace(options?: ExportOptions): Promise
async importFromUrl(url: string): Promise

// All IReactiveFileSystem methods (proxied to active project)
async readFile(path: string): Promise
async writeFile(path: string, content: any): Promise
// ... (all file system operations)

// Event System
readonly events: TypedEventEmitter

// Lifecycle
async initialize(config?: WorkspaceConfig): Promise
async clear(): Promise
async close(): Promise
}
`

$3

`typescript
interface Project {
id: string
name: string
source: ProjectSource
fs: IReactiveFileSystem
metadata: ProjectMetadata
state: "loading" | "loaded" | "error" | "disabled"
lastAccessed: Date
accessCount: number
memoryUsage: number
}

interface ProjectSource {
type: "memory" | "indexeddb" | "s3" | "github" | "api" | "json-url"
config: any
auth?: SourceAuth
}

interface DeleteProjectOptions {
deleteData?: boolean // Also delete project data (provider-specific)
skipConfirmation?: boolean // Skip confirmation event
}

interface SourceProvider {
readonly scheme: string
readonly displayName: string
createFileSystem(config: any): Promise
getCapabilities(): IFileSystemCapabilities
validateConfiguration?(config: any): Promise<{ valid: boolean; errors?: string[] }>
dispose?(fs: IReactiveFileSystem): Promise

// Optional data management methods
deleteProjectData?(config: any): Promise
hasLocalData?(): boolean
estimateDataSize?(config: any): Promise
}

interface WorkspaceSettings {
maxActiveProjects?: number // Auto-disable when exceeded
autoDisableAfter?: number // Ms of inactivity before auto-disable
keepFocusedActive?: boolean // Never auto-disable focused project
autoSave?: boolean
autoSaveInterval?: number
memoryThreshold?: number // Bytes before optimization
}
`

🔧 Configuration

$3

`bash


S3 Configuration

FIRESYSTEM_S3_ACCESS_KEY_ID=your_access_key
FIRESYSTEM_S3_SECRET_ACCESS_KEY=your_secret_key
FIRESYSTEM_S3_REGION=us-east-1

GitHub Configuration

FIRESYSTEM_GITHUB_TOKEN=ghp_xxxxxxxxxxxx
GITHUB_TOKEN=ghp_xxxxxxxxxxxx # Fallback

API Configuration

FIRESYSTEM_API_API_KEY=your_api_key
FIRESYSTEM_API_BASE_URL=https://api.example.com
`

$3

`typescript
const workspace = new WorkspaceFileSystem({
settings: {
maxActiveProjects: 10, // Keep 10 projects active max
autoDisableAfter: 1800000, // 30 minutes
keepFocusedActive: true, // Protect focused project
autoSave: true, // Auto-save state changes
autoSaveInterval: 60000, // Save every minute
memoryThreshold: 512 1024 1024 // 512MB threshold
}
});
`

🚨 Migration Guide

$3

`typescript
// Before: Single project at a time
class OldWorkflow {
async switchToProject(projectId: string) {
await this.closeCurrentProject(); // Lost from memory
await this.openProject(projectId); // Load from scratch
}

async copyToOtherProject(file: string, targetProject: string) {
const content = await this.readFile(file);
await this.closeCurrentProject(); // Lose current context
await this.openProject(targetProject);
await this.writeFile(file, content);
await this.closeCurrentProject(); // Lose target context
await this.openOriginalProject(); // Reload original
}
}

// After: Multi-project simultaneous access
class NewWorkflow {
async switchToProject(projectId: string) {
await workspace.setActiveProject(projectId); // Just change focus
// All other projects remain active and accessible!
}

async copyToOtherProject(file: string, targetProjectId: string) {
const source = workspace.getActiveProject();
const target = workspace.getProject(targetProjectId);

const content = await source.fs.readFile(file);
await target.fs.writeFile(file, content);
// Both projects remain active, no context loss!
}
}
`

$3

| Version | Release Date | Key Features |
|---------|-------------|--------------|
| v1.0.8 | 2025-07-03 | 🏗️ Modular architecture refactoring, improved separation of concerns |
| v1.0.7 | 2025-07-02 | 🗑️ Complete deleteProject, provider data management |
| v1.0.4 | 2025-06-30 | 🧪 Comprehensive test suite, robust validation |
| v1.0.3 | 2025-06-30 | 🧹 Auto-cleanup, empty-by-design, robust validation |
| v1.0.2 | 2025-06-30 | 🚀 Complete workspace system with persistence |
| v1.0.1 | 2025-06-30 | 📦 Initial release with multi-project support |

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

$3

`bash


Clone the repository

git clone https://github.com/firesystem/firesystem.git
cd firesystem/packages/workspace

Install dependencies

pnpm install

Run tests

pnpm test

Type checking

pnpm typecheck

Build

pnpm build
``

📋 Roadmap

$3

- [ ] Native S3FileSystem implementation
- [ ] Google Drive source provider
- [ ] Azure Blob Storage support
- [ ] Enhanced GitHub integration with commit/push

$3

- [ ] Project templates and scaffolding
- [ ] Advanced sync strategies
- [ ] Workspace-level search across all projects
- [ ] Project dependency management

$3

- [ ] Virtual file system for large projects
- [ ] Streaming file operations
- [ ] Background sync and preloading
- [ ] Advanced caching strategies

$3

- [ ] Real-time collaboration protocol
- [ ] Multi-user workspace sharing
- [ ] Role-based access control
- [ ] Audit logging and analytics

📄 License

MIT © Anderson D. Rosa

🙏 Acknowledgments

- Built on top of the robust @firesystem/core foundation
- Inspired by VSCode's multi-root workspace concept, but taken to the next level
- Thanks to the TypeScript team for excellent type system
- IndexedDB API for reliable browser persistence
- The open source community for continuous inspiration

---

🔥 Transform your development workflow with true multi-project parallelism!