@mikestools/usefilesystem 0.0.1 → 0.0.3

package/README.md

@@ -1,187 +1,589 @@
 # @mikestools/usefilesystem
 
-Vue 3 composables for in-memory virtual filesystem and ZIP archive operations.
+Vue 3 composable for an in-memory virtual filesystem with reactive state and familiar Node.js-like API.
 
 ## Features
 
-- **Virtual Filesystem** - In-memory filesystem with familiar Node.js-like API
-- **ZIP Archives** - Create and extract ZIP files using native browser compression
-- **Reactive State** - Vue 3 composables with reactive stats and progress tracking
-- **Zero Dependencies** - Uses native browser APIs (CompressionStream/DecompressionStream)
-- **TypeScript** - Full type safety with exported types
-- **Glob Search** - Find files with patterns like `**/*.ts`
-- **File Watchers** - Subscribe to create, modify, delete events
+- 🎯 **Composable-First** - Pure Vue 3 Composition API, no components
+- 📦 **TypeScript First** - Full type safety with IntelliSense
+- 🗂️ **Auto Directories** - Parent directories created automatically on file write
+- ✨ **Reactive State** - File counts and sizes update automatically
+
+### Complete Feature Set
+
+| Feature                   | Description                                      |
+|---------------------------|--------------------------------------------------|
+| 📁 **File Operations**    | Write, read, copy, move, delete files            |
+| 📂 **Directory Ops**      | Create, list, remove directories                 |
+| 🔍 **Glob Search**        | Find files with patterns like `**/*.ts`          |
+| 👀 **File Watchers**      | Subscribe to events with filtering & debouncing  |
+| ⚡ **Reactive Stats**      | Auto-updating file count and total size          |
+| 💾 **Serialization**      | Export/import filesystem state as JSON           |
+| 🗄️ **Persistence**       | OPFS adapter + custom adapters with auto-persist |
+| 📝 **MIME Types**         | Automatic inference from file extensions         |
+| 🔄 **Path Normalization** | Handles mixed separators and relative paths      |
+| 📤 **Upload/Download**    | Import Files, export Blobs, trigger downloads    |
+| 🌊 **Web Streams**        | ReadableStream/WritableStream for large files    |
+| 🔐 **Checksums**          | SHA-256 file hashing                             |
+| 💿 **Storage Quotas**     | Max size, file count limits with warnings        |
+| ⚛️ **Transactions**       | Atomic multi-file operations with rollback       |
 
 ## Installation
 
 ```bash
-npm install @mikestools/usefilesystem
+npm install @mikestools/usefilesystem vue
 ```
 
 ## Quick Start
 
 ```typescript
-import { useFileSystem, useZip } from '@mikestools/usefilesystem'
+import { ref, onMounted } from 'vue'
+import { useFileSystem } from '@mikestools/usefilesystem'
 
-const fs = useFileSystem()
+onMounted(() => {
+  const fs = useFileSystem()
+
+  // Write files - directories auto-created
+  fs.writeFile('/src/index.ts', 'export const version = "1.0.0"')
+  fs.writeFile('/readme.md', '# My Project')
+
+  // Reactive stats (update automatically)
+  console.log(fs.fileCount.value)  // 2
+  console.log(fs.totalSize.value)  // bytes
 
-// Write files - directories auto-created
-fs.writeFile('/src/index.ts', 'export const version = "1.0.0"')
-fs.writeFile('/readme.md', '# My Project')
+  // Read content
+  const content = fs.readFile('/src/index.ts')
 
-// Reactive stats
-console.log(fs.fileCount.value)  // 2
-console.log(fs.totalSize.value)  // bytes
+  // Search with glob patterns
+  const tsFiles = fs.find('/src/**/*.ts')
 
-// Export as ZIP
-const zip = useZip()
-await zip.download(
-  fs.getAllFiles().map(f => ({ path: f.path, content: f.content })),
-  'project.zip'
-)
+  // Watch for changes
+  const unsubscribe = fs.watch((event, path, type) => {
+    console.log(`${event} ${type}: ${path}`)
+  })
+})
 ```
 
-## useFileSystem
+## API Reference
+
+### Core Properties
+
+| Property     | Type                            | Description                    |
+|--------------|---------------------------------|--------------------------------|
+| `stats`      | `ComputedRef<FileSystemStats>`  | Reactive stats object          |
+| `fileCount`  | `ComputedRef<number>`           | Number of files                |
+| `totalSize`  | `ComputedRef<number>`           | Total size in bytes            |
 
-In-memory virtual filesystem with reactive stats.
+### File Methods
 
+#### Write Operations
 ```typescript
-const fs = useFileSystem()
+fs.writeFile('/path/file.txt', 'content')
+fs.writeFile('/path/file.txt', 'content', { mimeType: 'text/plain', overwrite: false })
+fs.appendFile('/path/file.txt', 'more content')
+```
+
+#### Read Operations
+```typescript
+const text = fs.readFile('/path/file.txt')                    // Returns string
+const binary = fs.readFile('/image.png', { encoding: 'binary' })  // Returns Uint8Array
+const meta = fs.stat('/path/file.txt')                        // Returns FileMetadata
+```
 
-// File operations
-fs.writeFile('/path/to/file.txt', 'content')
-fs.appendFile('/path/to/file.txt', 'more content')
-const content = fs.readFile('/path/to/file.txt')
-const binary = fs.readFile('/image.png', { encoding: 'binary' })
-fs.remove('/path/to/file.txt')
+#### File Management
+```typescript
 fs.copy('/source.txt', '/dest.txt')
+fs.copy('/source.txt', '/dest.txt', { overwrite: false })
 fs.move('/old.txt', '/new.txt')
+fs.move('/old.txt', '/new.txt', { overwrite: false })
+fs.rename('/path/old.txt', 'new.txt')
+fs.remove('/path/file.txt')
+```
+
+#### Path Checks
+```typescript
+fs.exists('/path')        // true if file or directory exists
+fs.isFile('/path')        // true if path is a file
+fs.isDirectory('/path')   // true if path is a directory
+```
+
+### Directory Methods
+
+#### Directory Operations
+```typescript
+fs.mkdir('/a/b/c')                    // Creates all parent directories
+fs.rmdir('/empty')                    // Removes empty directory only
+fs.rmdirRecursive('/folder')          // Removes directory and all contents
+const meta = fs.statDirectory('/path')  // Returns DirectoryMetadata
+```
+
+#### List Contents
+```typescript
+const entries = fs.list('/')
+const recursive = fs.list('/', { recursive: true })
+const filesOnly = fs.list('/', { filesOnly: true })
+const dirsOnly = fs.list('/', { directoriesOnly: true })
+```
+
+### Search Methods
 
-// Directory operations
-fs.mkdir('/a/b/c')  // Creates all parent directories
-fs.rmdir('/empty')  // Removes empty directory
-fs.rmdirRecursive('/folder')  // Removes with contents
-const entries = fs.list('/src', { recursive: true })
+#### Glob Patterns
+```typescript
+const tsFiles = fs.find('/src/**/*.ts')     // Recursive TypeScript files
+const configs = fs.find('/**/config.*')     // Any config file
+const rootFiles = fs.find('/*.txt')         // Root-level text files
+```
 
-// Search
-const tsFiles = fs.find('/src/**/*.ts')
+#### Extension Search
+```typescript
 const jsonFiles = fs.findByExtension('.json')
+const images = fs.findByExtension('png')    // Works with or without dot
+```
 
-// Metadata
-const meta = fs.stat('/file.txt')  // { name, path, size, mimeType, createdAt, modifiedAt }
-fs.exists('/path')
-fs.isFile('/path')
-fs.isDirectory('/path')
+#### Bulk Access
+```typescript
+const allFiles = fs.getAllFiles()    // Returns VirtualFile[]
+const allPaths = fs.getAllPaths()    // Returns string[]
+const stats = fs.getStats()          // Returns FileSystemStats
+```
 
-// Reactive stats
-console.log(fs.stats.value)  // { totalFiles, totalDirectories, totalSize }
-console.log(fs.fileCount.value)
-console.log(fs.totalSize.value)
+### Watcher Methods
 
-// Watchers
+```typescript
+// Simple watch for all changes
 const unsubscribe = fs.watch((event, path, type) => {
   console.log(`${event} ${type}: ${path}`)
+  // event: 'create' | 'modify' | 'delete'
+  // type: 'file' | 'directory'
+})
+
+// Watch with options (receives WatchEvent objects)
+const unsubscribe = fs.watch((event) => {
+  console.log(`${event.event}: ${event.path}`)
+  console.log('Metadata:', event.metadata)  // File size, timestamps, etc.
+}, {
+  pattern: '/*.txt',           // Glob pattern filter
+  events: ['create', 'modify'], // Event type filter
+  type: 'file',                // Entry type filter ('file' | 'directory' | 'all')
+  debounce: 100,               // Debounce rapid changes (ms)
+  path: '/src',                // Watch specific directory
+  recursive: true              // Include subdirectories
 })
 
-// Serialization
+// Triggers: "create file: /new.txt"
+fs.writeFile('/new.txt', 'content')
+
+// Triggers: "modify file: /new.txt"
+fs.writeFile('/new.txt', 'updated')
+
+// Triggers: "delete file: /new.txt"
+fs.remove('/new.txt')
+
+// Stop watching
+unsubscribe()
+```
+
+### Serialization Methods
+
+```typescript
+// Export to JSON (base64 encoded content)
 const json = fs.toJSON()
-fs.fromJSON(json)
+localStorage.setItem('filesystem', JSON.stringify(json))
+
+// Import from JSON
+const data = JSON.parse(localStorage.getItem('filesystem'))
+fs.fromJSON(data)
+
+// Clear all files and directories
 fs.clear()
 ```
 
-## useZip
+### Persistence Methods
+
+```typescript
+import { useFileSystem, type StorageAdapter } from '@mikestools/usefilesystem'
+
+// Create custom adapter
+const adapter: StorageAdapter = {
+  async save(key, data) { /* save Uint8Array */ },
+  async load(key) { /* return Uint8Array | undefined */ },
+  async remove(key) { /* delete key */ },
+  async list() { /* return string[] of keys */ },
+  async clear() { /* clear all */ }
+}
+
+// Use with composable
+const fs = useFileSystem({
+  adapter,
+  autoPersist: true  // Auto-save on every change
+})
+
+// Manual persist/restore
+await fs.persist()
+await fs.restore()
+```
+
+### OPFS Storage Adapter
 
-ZIP archive operations with reactive state.
+Built-in high-performance adapter using Origin Private File System:
 
 ```typescript
-const zip = useZip()
+import { useFileSystem, createOPFSAdapter } from '@mikestools/usefilesystem'
 
-// Create ZIP
-const blob = await zip.create([
-  { path: 'readme.txt', content: 'Hello!' },
-  { path: 'data/config.json', content: '{}' }
-])
+const adapter = createOPFSAdapter()
+const fs = useFileSystem({ adapter, autoPersist: true })
+```
+
+### Upload/Download Methods
+
+```typescript
+// Upload native File objects
+const fileInput = document.querySelector('input[type="file"]')
+await fs.upload(fileInput.files[0])                    // Upload to root
+await fs.upload(file, '/custom/path/file.txt')        // Custom path
+await fs.uploads(fileInput.files, '/documents')        // Upload multiple
+
+// Export files
+const blob = fs.toBlob('/image.png')                   // Get as Blob
+const file = fs.toFile('/data.json')                   // Get as File object
+const url = fs.createObjectURL('/photo.jpg')           // Object URL
+fs.revokeObjectURL(url)                                // Clean up URL
+
+// Download to user's device
+fs.download('/report.pdf')                             // Uses original filename
+fs.download('/report.pdf', 'annual-report.pdf')        // Custom filename
+fs.downloads(['/file1.txt', '/file2.txt'])             // Multiple downloads
+```
+
+### Web Streams API
+
+```typescript
+// Create ReadableStream from file
+const stream = fs.createReadStream('/large-file.bin')
+const response = new Response(stream)
+
+// Create WritableStream to file
+const writable = fs.createWriteStream('/output.bin', { mimeType: 'application/octet-stream' })
+await someReadable.pipeTo(writable)
+
+// Write from any ReadableStream
+await fs.writeFromStream('/download.zip', response.body)
+
+// Create Response for Service Workers
+const response = fs.toResponse('/api/data.json', { status: 200 })
+```
 
-// Download ZIP
-await zip.download(files, 'archive.zip')
+### Checksum
 
-// Extract ZIP
-const entries = await zip.extract(zipBlob)
-const filtered = await zip.extract(zipBlob, {
-  filter: entry => entry.path.endsWith('.txt')
+```typescript
+const hash = await fs.computeChecksum('/important-file.bin')
+console.log(hash)  // SHA-256 hex string
+```
+
+### Storage Quotas
+
+```typescript
+const fs = useFileSystem({
+  maxSize: 10 * 1024 * 1024,    // 10MB total limit
+  maxFiles: 1000,               // Max file count
+  maxFileSize: 5 * 1024 * 1024, // 5MB per file
+  warnAtPercentage: 80          // Warn at 80% capacity
 })
 
-// Extract single file
-const content = await zip.extractSingle(zipBlob, 'readme.txt')
+// Reactive storage estimate
+console.log(fs.storageEstimate.value)
+// { quota: 10485760, usage: 1234567, available: 9251193, percentage: 11.8 }
+
+// Check if near capacity
+if (fs.isNearCapacity.value) {
+  console.warn('Storage is almost full!')
+}
 
-// List without extracting
-const metadata = await zip.list(zipBlob)
+// Subscribe to warnings
+const unsubscribe = fs.onStorageWarning((estimate) => {
+  console.warn(`Storage at ${estimate.percentage}%`)
+})
+```
 
-// Reactive state
-console.log(zip.isProcessing.value)  // boolean
-console.log(zip.progress.value)      // 0-100
-console.log(zip.error.value)         // string | undefined
+### Transactions
 
-// Compression utilities
-const compressed = await zip.compress(data)
-const decompressed = await zip.decompress(data)
-const checksum = zip.computeCrc32(data)
+```typescript
+// Atomic multi-file operations
+const transaction = fs.beginTransaction()
+  .writeFile('/config.json', JSON.stringify(config))
+  .writeFile('/backup.json', JSON.stringify(backup))
+  .copy('/template.txt', '/output.txt')
+  .remove('/temp.txt')
+
+// All operations succeed or none do
+const result = transaction.commit()
+if (!result.success) {
+  console.error('Transaction failed:', result.error)
+  // All changes have been rolled back automatically
+}
+
+// Or explicitly discard
+transaction.rollback()
 ```
 
-## Standalone Functions
+### Standalone Function
 
-Core functions are also available without Vue:
+For use without Vue reactivity:
 
 ```typescript
-import {
-  createFileSystem,
-  createZip,
-  extractZip,
-  listZip,
-  compress,
-  decompress,
-  computeCrc32,
-  downloadBlob,
-  downloadAsZip
-} from '@mikestools/usefilesystem'
+import { createFileSystem } from '@mikestools/usefilesystem'
 
 // Pure filesystem (no Vue reactivity)
 const fs = createFileSystem()
+fs.writeFile('/file.txt', 'Hello')
+const content = fs.readFile('/file.txt')
+```
+
+### Types
 
-// Direct ZIP operations
-const blob = await createZip([{ path: 'file.txt', content: 'Hello' }])
-const entries = await extractZip(blob)
+```typescript
+// File types
+interface VirtualFile {
+  readonly name: string
+  readonly path: string
+  readonly content: Uint8Array
+  readonly size: number
+  readonly mimeType: string
+  readonly createdAt: number
+  readonly modifiedAt: number
+}
+
+interface FileMetadata {
+  readonly name: string
+  readonly path: string
+  readonly size: number
+  readonly mimeType: string
+  readonly createdAt: number
+  readonly modifiedAt: number
+  readonly extension: string    // e.g., '.txt'
+  readonly isText: boolean      // MIME type is text-based
+  readonly isBinary: boolean    // MIME type is binary
+  readonly parentPath: string   // Parent directory
+  readonly depth: number        // Directory depth from root
+}
+
+// Directory types
+interface DirectoryMetadata {
+  readonly name: string
+  readonly path: string
+  readonly createdAt: number
+  readonly parentPath: string
+  readonly depth: number
+  readonly fileCount: number      // Direct children files
+  readonly directoryCount: number // Direct children dirs
+  readonly totalSize: number      // Recursive total size
+}
+
+interface DirectoryEntry {
+  readonly name: string
+  readonly path: string
+  readonly type: 'file' | 'directory'
+  readonly size?: number  // Only for files
+}
+
+// Operation result
+interface FileSystemResult {
+  readonly success: boolean
+  readonly error?: string
+}
+
+// Stats
+interface FileSystemStats {
+  readonly totalFiles: number
+  readonly totalDirectories: number
+  readonly totalSize: number
+}
+
+// Watch options for filtering and debouncing
+interface WatchOptions {
+  readonly pattern?: string                             // Glob pattern filter
+  readonly events?: readonly ('create' | 'modify' | 'delete')[]
+  readonly type?: 'file' | 'directory' | 'all'
+  readonly debounce?: number                            // Debounce ms
+  readonly path?: string                                // Watch directory
+  readonly recursive?: boolean                          // Include subdirs
+}
+
+// Watch event (when using options)
+interface WatchEvent {
+  readonly event: 'create' | 'modify' | 'delete'
+  readonly path: string
+  readonly type: 'file' | 'directory'
+  readonly timestamp: number
+  readonly metadata?: FileMetadata | DirectoryMetadata
+}
+
+// Watcher callback (without options: simple params, with options: WatchEvent)
+type FileSystemWatcher = 
+  | ((event: WatchEvent) => void)
+  | ((event: 'create' | 'modify' | 'delete', path: string, type: 'file' | 'directory') => void)
+
+// Storage estimate
+interface StorageEstimate {
+  readonly quota: number      // Max allowed bytes
+  readonly usage: number      // Current usage bytes
+  readonly available: number  // Remaining bytes
+  readonly percentage: number // Usage percentage (0-100)
+}
+
+// Transaction for atomic operations
+interface Transaction {
+  writeFile(path: string, content: string | Uint8Array, options?: WriteFileOptions): Transaction
+  remove(path: string): Transaction
+  mkdir(path: string): Transaction
+  copy(source: string, destination: string): Transaction
+  move(source: string, destination: string): Transaction
+  commit(): FileSystemResult
+  rollback(): void
+}
+
+// Options
+interface WriteFileOptions {
+  readonly mimeType?: string
+  readonly overwrite?: boolean
+}
+
+interface ReadFileOptions {
+  readonly encoding?: 'utf8' | 'binary'
+}
+
+interface ListOptions {
+  readonly recursive?: boolean
+  readonly filesOnly?: boolean
+  readonly directoriesOnly?: boolean
+}
+
+interface CopyOptions {
+  readonly overwrite?: boolean
+}
+
+interface MoveOptions {
+  readonly overwrite?: boolean
+}
+
+// Persistence
+interface StorageAdapter {
+  save(key: string, data: Uint8Array): Promise<void>
+  load(key: string): Promise<Uint8Array | undefined>
+  remove(key: string): Promise<void>
+  list(): Promise<readonly string[]>
+  clear(): Promise<void>
+}
+
+interface UseFileSystemOptions {
+  readonly adapter?: StorageAdapter
+  readonly autoPersist?: boolean
+  readonly maxSize?: number           // Max total bytes
+  readonly maxFiles?: number          // Max file count
+  readonly maxFileSize?: number       // Max bytes per file
+  readonly warnAtPercentage?: number  // Warning threshold (default: 90)
+}
 ```
 
-## Types
+## Examples
 
-All types are exported:
+### Project Scaffolding
 
 ```typescript
-import type {
-  VirtualFile,
-  FileMetadata,
-  DirectoryMetadata,
-  DirectoryEntry,
-  FileSystemStats,
-  FileSystemWatcher,
-  StorageAdapter,
-  ZipEntry,
-  ZipEntryMetadata,
-  ZipInput,
-  CreateZipOptions,
-  ExtractZipOptions
-} from '@mikestools/usefilesystem'
+const fs = useFileSystem()
+
+// Generate project structure
+fs.writeFile('/package.json', JSON.stringify({
+  name: 'my-app',
+  version: '1.0.0'
+}, null, 2))
+
+fs.writeFile('/src/index.ts', 'export const app = () => console.log("Hello!")')
+fs.writeFile('/src/utils/helpers.ts', 'export const add = (a: number, b: number) => a + b')
+fs.writeFile('/readme.md', '# My App\n\nGenerated project.')
+
+console.log(fs.stats.value)
+// { totalFiles: 4, totalDirectories: 2, totalSize: ... }
+```
+
+### File Browser
+
+```typescript
+const fs = useFileSystem()
+const currentPath = ref('/')
+
+// Navigate directories
+function navigate(path: string) {
+  if (fs.isDirectory(path)) {
+    currentPath.value = path
+  }
+}
+
+// Get current directory contents
+const entries = computed(() => {
+  return fs.list(currentPath.value).sort((a, b) => {
+    if (a.type !== b.type) return a.type === 'directory' ? -1 : 1
+    return a.name.localeCompare(b.name)
+  })
+})
+```
+
+### Auto-Save with localStorage
+
+```typescript
+const adapter: StorageAdapter = {
+  async save(key, data) {
+    localStorage.setItem(key, btoa(String.fromCharCode(...data)))
+  },
+  async load(key) {
+    const base64 = localStorage.getItem(key)
+    if (!base64) return undefined
+    return Uint8Array.from(atob(base64), c => c.charCodeAt(0))
+  },
+  async remove(key) {
+    localStorage.removeItem(key)
+  },
+  async list() {
+    return Object.keys(localStorage)
+  },
+  async clear() {
+    localStorage.clear()
+  }
+}
+
+const fs = useFileSystem({ adapter, autoPersist: true })
+
+// Restore on startup
+await fs.restore()
+
+// All changes now auto-save!
+fs.writeFile('/notes.txt', 'This will persist')
+```
+
+### Change Tracking
+
+```typescript
+const fs = useFileSystem()
+const changes = ref<string[]>([])
+
+fs.watch((event, path, type) => {
+  changes.value.push(`${new Date().toISOString()}: ${event} ${type} ${path}`)
+})
+
+// Track all operations
+fs.writeFile('/file.txt', 'content')
+fs.writeFile('/file.txt', 'updated')
+fs.remove('/file.txt')
+
+console.log(changes.value)
+// ["...: create file /file.txt", "...: modify file /file.txt", "...: delete file /file.txt"]
 ```
 
 ## Browser Support
 
-Requires browsers with support for:
-- CompressionStream/DecompressionStream (Chrome 80+, Firefox 113+, Safari 16.4+)
-- TextEncoder/TextDecoder
-- Blob, ArrayBuffer, Uint8Array
+Works in all modern browsers that support ES2020+.
 
 ## License
 
-MIT
+MIT © Mike Garcia