@mikestools/usefilesystem 0.0.1 → 0.0.2

package/README.md

@@ -1,187 +1,418 @@
 # @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 create, modify, delete events  |
+| ⚡ **Reactive Stats**      | Auto-updating file count and total size     |
+| 💾 **Serialization**      | Export/import filesystem state as JSON      |
+| 🗄️ **Persistence**       | Storage adapter support with auto-persist   |
+| 📝 **MIME Types**         | Automatic inference from file extensions    |
+| 🔄 **Path Normalization** | Handles mixed separators and relative paths |
 
 ## 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
 
-In-memory virtual filesystem with reactive stats.
+| Property     | Type                            | Description                    |
+|--------------|---------------------------------|--------------------------------|
+| `stats`      | `ComputedRef<FileSystemStats>`  | Reactive stats object          |
+| `fileCount`  | `ComputedRef<number>`           | Number of files                |
+| `totalSize`  | `ComputedRef<number>`           | Total size in bytes            |
 
+### 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')
+```
 
-// 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')
+#### 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 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
-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 })
+#### 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
+
+#### 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
+// Watch for changes
 const unsubscribe = fs.watch((event, path, type) => {
   console.log(`${event} ${type}: ${path}`)
+  // event: 'create' | 'modify' | 'delete'
+  // type: 'file' | 'directory'
 })
 
-// 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
-
-ZIP archive operations with reactive state.
+### Persistence Methods
 
 ```typescript
-const zip = useZip()
+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
+})
 
-// Create ZIP
-const blob = await zip.create([
-  { path: 'readme.txt', content: 'Hello!' },
-  { path: 'data/config.json', content: '{}' }
-])
+// Manual persist/restore
+await fs.persist()
+await fs.restore()
+```
 
-// Download ZIP
-await zip.download(files, 'archive.zip')
+### Standalone Function
 
-// Extract ZIP
-const entries = await zip.extract(zipBlob)
-const filtered = await zip.extract(zipBlob, {
-  filter: entry => entry.path.endsWith('.txt')
-})
+For use without Vue reactivity:
 
-// Extract single file
-const content = await zip.extractSingle(zipBlob, 'readme.txt')
+```typescript
+import { createFileSystem } from '@mikestools/usefilesystem'
 
-// List without extracting
-const metadata = await zip.list(zipBlob)
+// Pure filesystem (no Vue reactivity)
+const fs = createFileSystem()
+fs.writeFile('/file.txt', 'Hello')
+const content = fs.readFile('/file.txt')
+```
 
-// Reactive state
-console.log(zip.isProcessing.value)  // boolean
-console.log(zip.progress.value)      // 0-100
-console.log(zip.error.value)         // string | undefined
+### Types
 
-// Compression utilities
-const compressed = await zip.compress(data)
-const decompressed = await zip.decompress(data)
-const checksum = zip.computeCrc32(data)
+```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
+}
+
+// Directory types
+interface DirectoryMetadata {
+  readonly name: string
+  readonly path: string
+  readonly createdAt: number
+}
+
+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
+}
+
+// Watcher callback
+type FileSystemWatcher = (
+  event: 'create' | 'modify' | 'delete',
+  path: string,
+  type: 'file' | 'directory'
+) => 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
+}
 ```
 
-## Standalone Functions
+## Examples
 
-Core functions are also available without Vue:
+### Project Scaffolding
 
 ```typescript
-import {
-  createFileSystem,
-  createZip,
-  extractZip,
-  listZip,
-  compress,
-  decompress,
-  computeCrc32,
-  downloadBlob,
-  downloadAsZip
-} from '@mikestools/usefilesystem'
+const fs = useFileSystem()
 
-// Pure filesystem (no Vue reactivity)
-const fs = createFileSystem()
+// 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: ... }
+```
 
-// Direct ZIP operations
-const blob = await createZip([{ path: 'file.txt', content: 'Hello' }])
-const entries = await extractZip(blob)
+### 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)
+  })
+})
 ```
 
-## Types
+### Auto-Save with localStorage
 
-All types are exported:
+```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
-import type {
-  VirtualFile,
-  FileMetadata,
-  DirectoryMetadata,
-  DirectoryEntry,
-  FileSystemStats,
-  FileSystemWatcher,
-  StorageAdapter,
-  ZipEntry,
-  ZipEntryMetadata,
-  ZipInput,
-  CreateZipOptions,
-  ExtractZipOptions
-} from '@mikestools/usefilesystem'
+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