@mikestools/usefilesystem 0.0.2 → 0.0.3

package/README.md

@@ -11,17 +11,22 @@ Vue 3 composable for an in-memory virtual filesystem with reactive state and fam
 
 ### 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 |
+| 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
 
@@ -145,13 +150,26 @@ const stats = fs.getStats()          // Returns FileSystemStats
 ### Watcher Methods
 
 ```typescript
-// Watch for changes
+// 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
+})
+
 // Triggers: "create file: /new.txt"
 fs.writeFile('/new.txt', 'content')
 
@@ -205,6 +223,109 @@ await fs.persist()
 await fs.restore()
 ```
 
+### OPFS Storage Adapter
+
+Built-in high-performance adapter using Origin Private File System:
+
+```typescript
+import { useFileSystem, createOPFSAdapter } from '@mikestools/usefilesystem'
+
+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 })
+```
+
+### Checksum
+
+```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
+})
+
+// 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!')
+}
+
+// Subscribe to warnings
+const unsubscribe = fs.onStorageWarning((estimate) => {
+  console.warn(`Storage at ${estimate.percentage}%`)
+})
+```
+
+### Transactions
+
+```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 Function
 
 For use without Vue reactivity:
@@ -239,6 +360,11 @@ interface FileMetadata {
   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
@@ -246,6 +372,11 @@ 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 {
@@ -268,12 +399,48 @@ interface FileSystemStats {
   readonly totalSize: number
 }
 
-// Watcher callback
-type FileSystemWatcher = (
-  event: 'create' | 'modify' | 'delete',
-  path: string,
-  type: 'file' | 'directory'
-) => void
+// 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 {
@@ -311,6 +478,10 @@ interface StorageAdapter {
 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)
 }
 ```
 

package/dist/index.d.ts

@@ -61,7 +61,7 @@ export declare function createFileSystem(): {
     clear: () => void;
     find: (pattern: string) => readonly string[];
     findByExtension: (extension: string) => readonly string[];
-    watch: (callback: FileSystemWatcher) => () => void;
+    watch: (callback: FileSystemWatcher, options?: WatchOptions) => () => void;
     toJSON: () => Record<string, {
         content: string;
         mimeType: string;
@@ -72,6 +72,21 @@ export declare function createFileSystem(): {
     }>) => void;
 };
 
+/**
+ * Built-in OPFS (Origin Private File System) storage adapter.
+ * Provides high-performance persistence using the browser's native file system.
+ *
+ * OPFS is available in modern browsers and provides fast, synchronous-like
+ * access to a private file system sandboxed to the origin.
+ *
+ * @example
+ * ```ts
+ * const adapter = createOPFSAdapter()
+ * const filesystem = useFileSystem({ adapter, autoPersist: true })
+ * ```
+ */
+export declare function createOPFSAdapter(): StorageAdapter;
+
 /**
  * Directory entry for listing.
  */
@@ -89,6 +104,16 @@ export declare interface DirectoryMetadata {
     readonly name: string;
     readonly path: string;
     readonly createdAt: number;
+    /** Parent directory path */
+    readonly parentPath: string;
+    /** Directory depth from root (root = 0) */
+    readonly depth: number;
+    /** Count of direct children files */
+    readonly fileCount: number;
+    /** Count of direct children directories */
+    readonly directoryCount: number;
+    /** Recursive total size of all contents in bytes */
+    readonly totalSize: number;
 }
 
 /**
@@ -101,6 +126,16 @@ export declare interface FileMetadata {
     readonly mimeType: string;
     readonly createdAt: number;
     readonly modifiedAt: number;
+    /** File extension including leading dot, or empty string if none */
+    readonly extension: string;
+    /** True if MIME type indicates text content */
+    readonly isText: boolean;
+    /** True if MIME type indicates binary content */
+    readonly isBinary: boolean;
+    /** Parent directory path */
+    readonly parentPath: string;
+    /** Directory depth from root (root = 0) */
+    readonly depth: number;
 }
 
 /**
@@ -129,8 +164,10 @@ export declare interface FileSystemStats {
 
 /**
  * Watcher callback for filesystem changes.
+ * When using watch options, receives a WatchEvent object.
+ * When using simple watch (no options), receives individual parameters.
  */
-export declare type FileSystemWatcher = (event: 'create' | 'modify' | 'delete', path: string, type: 'file' | 'directory') => void;
+export declare type FileSystemWatcher = ((event: WatchEvent) => void) | ((event: 'create' | 'modify' | 'delete', path: string, type: 'file' | 'directory') => void);
 
 /**
  * Options for listing directory contents.
@@ -166,6 +203,51 @@ export declare interface StorageAdapter {
     clear(): Promise<void>;
 }
 
+/**
+ * Storage usage estimate.
+ */
+declare interface StorageEstimate_2 {
+    /** Estimated available space (virtual limit) */
+    readonly quota: number;
+    /** Current usage in bytes */
+    readonly usage: number;
+    /** Available space (quota - usage) */
+    readonly available: number;
+    /** Usage percentage (0-100) */
+    readonly percentage: number;
+}
+export { StorageEstimate_2 as StorageEstimate }
+
+/**
+ * Options for Web Streams API operations.
+ */
+export declare interface StreamOptions {
+    /** Chunk size in bytes for streaming (default: 64KB) */
+    readonly chunkSize?: number;
+    /** High water mark for backpressure (default: 3 chunks) */
+    readonly highWaterMark?: number;
+}
+
+/**
+ * Transaction for atomic multi-file operations.
+ */
+export declare interface Transaction {
+    /** Queue a file write operation */
+    writeFile(path: string, content: string | Uint8Array, options?: WriteFileOptions): Transaction;
+    /** Queue a file removal */
+    remove(path: string): Transaction;
+    /** Queue a directory creation */
+    mkdir(path: string): Transaction;
+    /** Queue a file copy operation */
+    copy(source: string, destination: string): Transaction;
+    /** Queue a file move operation */
+    move(source: string, destination: string): Transaction;
+    /** Execute all operations atomically (all or nothing) */
+    commit(): FileSystemResult;
+    /** Discard all pending operations */
+    rollback(): void;
+}
+
 /**
  * Vue composable wrapper for the virtual filesystem with reactivity.
  *
@@ -189,6 +271,14 @@ export declare function useFileSystem(options?: UseFileSystemOptions): UseFileSy
 export declare interface UseFileSystemOptions {
     readonly adapter?: StorageAdapter;
     readonly autoPersist?: boolean;
+    /** Maximum total size in bytes (default: unlimited) */
+    readonly maxSize?: number;
+    /** Maximum number of files (default: unlimited) */
+    readonly maxFiles?: number;
+    /** Maximum single file size in bytes (default: unlimited) */
+    readonly maxFileSize?: number;
+    /** Trigger warning at this usage percentage (default: 90) */
+    readonly warnAtPercentage?: number;
 }
 
 /**
@@ -205,13 +295,82 @@ export declare interface UseFileSystemReturn extends FileSystem_2 {
     persist: () => Promise<void>;
     /** Restore from storage adapter */
     restore: () => Promise<void>;
+    /** Import a native File object into the virtual filesystem */
+    upload: (file: File, targetPath?: string) => Promise<FileSystemResult>;
+    /** Import multiple files from a FileList (e.g., from <input type="file">) */
+    uploads: (files: FileList, targetDirectory?: string) => Promise<FileSystemResult>;
+    /** Export a virtual file as a native Blob */
+    toBlob: (path: string) => Blob | undefined;
+    /** Export a virtual file as a native File object */
+    toFile: (path: string) => File | undefined;
+    /** Create a downloadable object URL for a file */
+    createObjectURL: (path: string) => string | undefined;
+    /** Revoke a previously created object URL */
+    revokeObjectURL: (url: string) => void;
+    /** Download a virtual file to the user's device */
+    download: (path: string, filename?: string) => boolean;
+    /** Download multiple files as individual downloads */
+    downloads: (paths: readonly string[]) => void;
+    /** Create a Web Streams API ReadableStream for a file */
+    createReadStream: (path: string, options?: StreamOptions) => ReadableStream<Uint8Array> | undefined;
+    /** Create a Web Streams API WritableStream for a file */
+    createWriteStream: (path: string, options?: WriteFileOptions & StreamOptions) => WritableStream<Uint8Array>;
+    /** Write from any ReadableStream (fetch response, Blob.stream(), etc.) */
+    writeFromStream: (path: string, stream: ReadableStream<Uint8Array>, options?: WriteFileOptions) => Promise<FileSystemResult>;
+    /** Create a Response object from a file (for Service Worker integration) */
+    toResponse: (path: string, init?: ResponseInit) => Response | undefined;
+    /** Compute SHA-256 checksum of file content */
+    computeChecksum: (path: string) => Promise<string | undefined>;
+    /** Get storage usage estimate */
+    readonly storageEstimate: ComputedRef<StorageEstimate_2>;
+    /** Check if storage is near capacity (above warning threshold) */
+    readonly isNearCapacity: ComputedRef<boolean>;
+    /** Register callback when storage exceeds warning threshold */
+    onStorageWarning: (callback: (estimate: StorageEstimate_2) => void) => () => void;
+    /** Begin a transaction for atomic operations */
+    beginTransaction: () => Transaction;
 }
 
 /**
  * Represents a complete file with content.
  */
-export declare interface VirtualFile extends FileMetadata {
+export declare interface VirtualFile {
+    readonly name: string;
+    readonly path: string;
     readonly content: Uint8Array;
+    readonly size: number;
+    readonly mimeType: string;
+    readonly createdAt: number;
+    readonly modifiedAt: number;
+}
+
+/**
+ * Enhanced watch event with metadata.
+ */
+export declare interface WatchEvent {
+    readonly event: 'create' | 'modify' | 'delete';
+    readonly path: string;
+    readonly type: 'file' | 'directory';
+    readonly timestamp: number;
+    readonly metadata?: FileMetadata | DirectoryMetadata;
+}
+
+/**
+ * Options for enhanced file watching.
+ */
+export declare interface WatchOptions {
+    /** Filter by path pattern (glob) */
+    readonly pattern?: string;
+    /** Filter by event types */
+    readonly events?: readonly ('create' | 'modify' | 'delete')[];
+    /** Filter by entry type */
+    readonly type?: 'file' | 'directory' | 'all';
+    /** Debounce rapid changes (ms) */
+    readonly debounce?: number;
+    /** Only watch specific directory (non-recursive by default) */
+    readonly path?: string;
+    /** Watch recursively when path is specified */
+    readonly recursive?: boolean;
 }
 
 /**