@mikestools/usefilesystem 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -1,15 +1,4 @@
 import { ComputedRef } from 'vue';
-import { Ref } from 'vue';
-
-/**
- * Compresses data using DEFLATE (native CompressionStream).
- */
-export declare function compress(data: Uint8Array): Promise<Uint8Array>;
-
-/**
- * Computes CRC-32 checksum for data.
- */
-export declare function computeCrc32(data: Uint8Array): number;
 
 /**
  * Options for copying files.
@@ -72,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;
@@ -84,31 +73,19 @@ export declare function createFileSystem(): {
 };
 
 /**
- * Creates a ZIP archive from files.
+ * 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 zipBlob = await createZip([
- *   { path: 'readme.txt', content: 'Hello World!' },
- *   { path: 'data/config.json', content: JSON.stringify({ enabled: true }) },
- *   { path: 'images/logo.png', content: pngBytes }
- * ])
+ * const adapter = createOPFSAdapter()
+ * const filesystem = useFileSystem({ adapter, autoPersist: true })
  * ```
  */
-export declare function createZip(files: readonly ZipInput[], options?: CreateZipOptions): Promise<Blob>;
-
-/**
- * Options for creating a ZIP archive.
- */
-export declare interface CreateZipOptions extends ZipCompressionOptions {
-    /** Comment to include in the ZIP archive */
-    readonly comment?: string;
-}
-
-/**
- * Decompresses DEFLATE data (native DecompressionStream).
- */
-export declare function decompress(data: Uint8Array): Promise<Uint8Array>;
+export declare function createOPFSAdapter(): StorageAdapter;
 
 /**
  * Directory entry for listing.
@@ -127,42 +104,16 @@ export declare interface DirectoryMetadata {
     readonly name: string;
     readonly path: string;
     readonly createdAt: number;
-}
-
-/**
- * Downloads data as a ZIP file.
- */
-export declare function downloadAsZip(files: readonly ZipInput[], fileName: string, options?: CreateZipOptions): Promise<void>;
-
-/**
- * Downloads a blob as a file.
- */
-export declare function downloadBlob(blob: Blob, fileName: string): void;
-
-/**
- * Extracts a single file from a ZIP archive.
- */
-export declare function extractFile(zipData: Uint8Array | Blob, filePath: string): Promise<Uint8Array | undefined>;
-
-/**
- * Extracts all files from a ZIP archive.
- *
- * @example
- * ```ts
- * const entries = await extractZip(zipBlob)
- * for (const entry of entries) {
- *   console.log(entry.path, entry.content.length)
- * }
- * ```
- */
-export declare function extractZip(zipData: Uint8Array | Blob, options?: ExtractZipOptions): Promise<readonly ZipEntry[]>;
-
-/**
- * Options for extracting from a ZIP archive.
- */
-export declare interface ExtractZipOptions {
-    /** Filter function to select which entries to extract */
-    readonly filter?: (entry: ZipEntryMetadata) => boolean;
+    /** 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;
 }
 
 /**
@@ -175,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;
 }
 
 /**
@@ -203,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.
@@ -215,11 +178,6 @@ export declare interface ListOptions {
     readonly directoriesOnly?: boolean;
 }
 
-/**
- * Reads entries from a ZIP archive without extracting content.
- */
-export declare function listZip(zipData: Uint8Array | Blob): Promise<readonly ZipEntryMetadata[]>;
-
 /**
  * Options for moving files.
  */
@@ -245,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.
  *
@@ -268,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;
 }
 
 /**
@@ -284,142 +295,90 @@ export declare interface UseFileSystemReturn extends FileSystem_2 {
     persist: () => Promise<void>;
     /** Restore from storage adapter */
     restore: () => Promise<void>;
-}
-
-/**
- * Vue composable for ZIP operations with reactive state.
- *
- * @example
- * ```ts
- * const zip = useZip()
- *
- * // Create and download a ZIP
- * await zip.download([
- *   { path: 'readme.txt', content: 'Hello!' },
- *   { path: 'data.json', content: JSON.stringify({ foo: 'bar' }) }
- * ], 'archive.zip')
- *
- * // Extract a ZIP file
- * const entries = await zip.extract(zipBlob)
- * for (const entry of entries) {
- *   console.log(entry.path, new TextDecoder().decode(entry.content))
- * }
- *
- * // Check processing state
- * if (zip.isProcessing.value) {
- *   console.log(`Progress: ${zip.progress.value}%`)
- * }
- * ```
- */
-export declare function useZip(): UseZipReturn;
-
-/**
- * Return type for useZip composable.
- */
-export declare interface UseZipReturn {
-    /** Current operation state */
-    readonly state: ComputedRef<ZipOperationState>;
-    /** Whether an operation is in progress */
-    readonly isProcessing: Ref<boolean>;
-    /** Progress percentage (0-100) */
-    readonly progress: Ref<number>;
-    /** Last error message */
-    readonly error: Ref<string | undefined>;
-    /** Create a ZIP archive from files */
-    create: (files: readonly ZipInput[], options?: CreateZipOptions) => Promise<Blob>;
-    /** Extract all files from a ZIP archive */
-    extract: (zipData: Uint8Array | Blob, options?: ExtractZipOptions) => Promise<readonly ZipEntry[]>;
-    /** Extract a single file from a ZIP archive */
-    extractSingle: (zipData: Uint8Array | Blob, filePath: string) => Promise<Uint8Array | undefined>;
-    /** List entries in a ZIP archive without extracting */
-    list: (zipData: Uint8Array | Blob) => Promise<readonly ZipEntryMetadata[]>;
-    /** Download a ZIP archive */
-    download: (files: readonly ZipInput[], fileName: string, options?: CreateZipOptions) => Promise<void>;
-    /** Download a blob as a file */
-    downloadBlob: (blob: Blob, fileName: string) => void;
-    /** Compress data using DEFLATE */
-    compress: (data: Uint8Array) => Promise<Uint8Array>;
-    /** Decompress DEFLATE data */
-    decompress: (data: Uint8Array) => Promise<Uint8Array>;
-    /** Compute CRC-32 checksum */
-    computeCrc32: (data: Uint8Array) => number;
-    /** Reset error state */
-    clearError: () => 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 {
-    readonly content: Uint8Array;
-}
-
-/**
- * Options for writing a file.
- */
-export declare interface WriteFileOptions {
-    readonly mimeType?: string;
-    readonly overwrite?: boolean;
-}
-
-/**
- * Options for ZIP compression.
- */
-export declare interface ZipCompressionOptions {
-    /** Compression level: 'none' stores files, 'fast'/'default' uses deflate */
-    readonly level?: 'none' | 'fast' | 'default';
-}
-
-/**
- * Represents an entry in a ZIP archive.
- */
-export declare interface ZipEntry {
+export declare interface VirtualFile {
+    readonly name: string;
     readonly path: string;
     readonly content: Uint8Array;
-    readonly compressedSize: number;
-    readonly uncompressedSize: number;
-    readonly compressionMethod: 'store' | 'deflate';
-    readonly crc32: number;
-    readonly modifiedAt: Date;
-    readonly isDirectory: boolean;
-}
-
-/**
- * Metadata for a ZIP entry (without content).
- */
-export declare interface ZipEntryMetadata {
-    readonly path: string;
-    readonly compressedSize: number;
-    readonly uncompressedSize: number;
-    readonly compressionMethod: 'store' | 'deflate';
-    readonly isDirectory: boolean;
-    readonly modifiedAt: Date;
+    readonly size: number;
+    readonly mimeType: string;
+    readonly createdAt: number;
+    readonly modifiedAt: number;
 }
 
 /**
- * Input for adding files to a ZIP archive.
+ * Enhanced watch event with metadata.
  */
-export declare interface ZipInput {
+export declare interface WatchEvent {
+    readonly event: 'create' | 'modify' | 'delete';
     readonly path: string;
-    readonly content: Uint8Array | string;
+    readonly type: 'file' | 'directory';
+    readonly timestamp: number;
+    readonly metadata?: FileMetadata | DirectoryMetadata;
 }
 
 /**
- * State for ZIP operations.
- */
-export declare interface ZipOperationState {
-    readonly isProcessing: boolean;
-    readonly progress: number;
-    readonly error: string | undefined;
+ * 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;
 }
 
 /**
- * Result of a ZIP operation.
+ * Options for writing a file.
  */
-export declare interface ZipResult<T = void> {
-    readonly success: boolean;
-    readonly data?: T;
-    readonly error?: string;
+export declare interface WriteFileOptions {
+    readonly mimeType?: string;
+    readonly overwrite?: boolean;
 }
 
 export { }