opfs-worker 1.3.2 → 2.0.0

package/src/createOPFSWorker.ts

@@ -0,0 +1,57 @@
+import { wrap } from 'comlink';
+
+import WorkerCtor from './worker.entry?worker&inline';
+
+import type { OPFSOptions, RemoteOPFSWorker } from './types';
+
+const InlineWorker = WorkerCtor as new (options?: WorkerOptions) => Worker;
+
+export interface RawWorker {
+    /** Comlink proxy to `OPFSWorker` (bytes in / bytes out) */
+    fs: RemoteOPFSWorker;
+    /** Underlying browser Worker */
+    worker: Worker;
+    /** Calls worker `dispose()` then `terminate()` */
+    dispose: () => void;
+}
+
+/** A `BroadcastChannel` instance can't cross the wire — send its name instead. */
+function applyWorkerOptions(fs: Pick<RemoteOPFSWorker, 'setOptions'>, options?: OPFSOptions): void {
+    if (!options) {
+        return;
+    }
+
+    if (options.broadcastChannel instanceof BroadcastChannel) {
+        options.broadcastChannel = options.broadcastChannel.name;
+    }
+
+    void fs.setOptions(options);
+}
+
+/**
+ * Mode 2: spawn the inlined worker and get a Comlink proxy to `OPFSWorker`
+ * (bytes in / bytes out), without the facade.
+ *
+ * `OPFSFacade` is built on top of this — copy it if you want your own facade.
+ */
+export function createOPFSWorker(options?: OPFSOptions): RawWorker {
+    const worker = new InlineWorker();
+    const fs = wrap<RemoteOPFSWorker>(worker);
+
+    applyWorkerOptions(fs, options);
+
+    return {
+        fs,
+        worker,
+        dispose() {
+            void (async() => {
+                try {
+                    await fs.dispose();
+                }
+                finally {
+                    worker.terminate();
+                }
+            })();
+        },
+    };
+}

package/src/index.pure.ts

@@ -0,0 +1,7 @@
+export * from './types';
+export * from './utils/errors';
+export * from './utils/helpers';
+export * from './utils/encoder';
+
+// Explicit re-export shadows the type-only `OPFSWorker` coming from './types'
+export { OPFSWorker } from './OPFSWorker';

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './types';
+export * from './utils/errors';
+export * from './utils/helpers';
+export * from './utils/encoder';
+
+export {
+    OPFSFacade,
+    OPFSFileSystem,
+    createOPFS,
+    // 1.x aliases
+    createWorker,
+} from './OPFSFacade';
+
+export { createOPFSWorker } from './createOPFSWorker';
+export type { RawWorker } from './createOPFSWorker';

package/src/types.ts

@@ -0,0 +1,99 @@
+import type { OPFSWorker } from './OPFSWorker';
+import type { Remote } from 'comlink';
+
+/**
+ * Type for paths that can be either a string or URI
+ */
+export type PathLike = string | URL;
+
+export type Kind = 'file' | 'directory';
+
+export type StringEncoding = 'ascii'
+  | 'utf8'
+  | 'utf-8'
+  | 'utf16le'
+  | 'utf-16le'
+  | 'ucs2'
+  | 'ucs-2'
+  | 'base64'
+  | 'latin1'
+  | 'hex';
+
+export type BinaryEncoding = 'binary';
+
+export type Encoding = StringEncoding | BinaryEncoding;
+
+export interface FileStat {
+    kind: Kind;
+    size: number;
+    mtime: string; // ISO string
+    ctime: string; // ISO string
+    isFile: boolean;
+    isDirectory: boolean;
+    /** Hash of file content (only for files, undefined for directories) */
+    hash?: string;
+}
+
+export interface DirentData {
+    name: string;
+    kind: 'file' | 'directory';
+    isFile: boolean;
+    isDirectory: boolean;
+}
+
+export enum WatchEventType {
+    Added = 'added',
+    Changed = 'changed',
+    Removed = 'removed'
+}
+
+export interface WatchEvent {
+    namespace: string;
+    path: string;
+    type: WatchEventType;
+    isDirectory: boolean;
+    timestamp: string;
+    hash?: string;
+}
+
+export type { OPFSWorker };
+export type RemoteOPFSWorker = Remote<OPFSWorker>;
+
+export interface OPFSOptions {
+    /** Root path for the file system (default: '/') */
+    root?: string;
+    /** Namespace for the events (default: 'opfs-worker:${root}') */
+    namespace?: string;
+    /** Hash algorithm for file hashing, or false/null to disable (default: 'etag') */
+    hashAlgorithm?: null | false | 'etag' | 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';
+    /** Maximum file size in bytes for hashing (default: 50MB) */
+    maxFileSize?: number;
+    /** Custom name for the broadcast channel (default: 'opfs-worker') */
+    broadcastChannel?: string | BroadcastChannel | null;
+}
+
+export interface RenameOptions {
+    /** Whether to overwrite existing files (default: false) */
+    overwrite?: boolean;
+}
+
+export interface WatchOptions {
+    /** Whether to watch recursively (default: true) */
+    recursive?: boolean;
+    /** Glob patterns to include in watching (minimatch syntax, default: ['**']) */
+    include?: string | string[];
+    /** Glob patterns to exclude from watching (minimatch syntax, default: []) */
+    exclude?: string | string[];
+}
+
+export interface FileOpenOptions {
+    create?: boolean;
+    exclusive?: boolean;
+    truncate?: boolean;
+}
+
+export interface WatchSnapshot {
+    pattern: string;
+    include: string[];
+    exclude: string[];
+}

package/src/utils/encoder.ts

@@ -0,0 +1,205 @@
+import { ValidationError } from './errors';
+
+import type { Encoding } from '../types';
+
+
+/**
+ * Common binary file extensions
+ */
+export const BINARY_FILE_EXTENSIONS = [
+    // Images
+    '.jpg',
+    '.jpeg',
+    '.png',
+    '.gif',
+    '.bmp',
+    '.webp',
+    '.ico',
+    '.tiff',
+    '.tga',
+    // Audio
+    '.mp3',
+    '.wav',
+    '.ogg',
+    '.flac',
+    '.aac',
+    '.wma',
+    '.m4a',
+    // Video
+    '.mp4',
+    '.avi',
+    '.mov',
+    '.wmv',
+    '.flv',
+    '.webm',
+    '.mkv',
+    '.m4v',
+    // Documents
+    '.pdf',
+    '.doc',
+    '.docx',
+    '.xls',
+    '.xlsx',
+    '.ppt',
+    '.pptx',
+    // Archives
+    '.zip',
+    '.rar',
+    '.7z',
+    '.tar',
+    '.gz',
+    '.bz2',
+    // Executables
+    '.exe',
+    '.dll',
+    '.so',
+    '.dylib',
+    // Other binary formats
+    '.dat',
+    '.db',
+    '.sqlite',
+    '.bin',
+    '.obj',
+    '.fbx',
+    '.3ds',
+] as const;
+
+/**
+ * Check if a file extension indicates a binary file
+ * 
+ * @param path - The file path or filename
+ * @returns True if the file extension suggests binary content
+ * 
+ * @example
+ * ```typescript
+ * isBinaryFileExtension('/path/to/image.jpg'); // true
+ * isBinaryFileExtension('/path/to/document.txt'); // false
+ * isBinaryFileExtension('data.bin'); // true
+ * isBinaryFileExtension('data'); // true
+ * ```
+ */
+export function isBinaryFileExtension(path: string): boolean {
+    const i = path.lastIndexOf('.');
+
+    if (i <= 0) {
+        return true;
+    }
+
+    const ext = path.slice(i).toLowerCase();
+
+    return BINARY_FILE_EXTENSIONS.includes(ext as any);
+}
+
+export function encodeString(data: string, encoding: Encoding = 'utf-8'): Uint8Array {
+    switch (encoding) {
+        case 'utf8':
+        case 'utf-8':
+            return new TextEncoder().encode(data);
+
+        case 'utf16le':
+        case 'utf-16le':
+        case 'ucs2':
+        case 'ucs-2':
+            return encodeUtf16LE(data);
+
+        case 'ascii':
+            return encodeAscii(data);
+
+        case 'latin1':
+            return encodeLatin1(data);
+
+        case 'binary':
+            return Uint8Array.from(data, char => char.charCodeAt(0));
+
+        case 'base64':
+            return Uint8Array.from(atob(data), c => c.charCodeAt(0));
+
+        case 'hex':
+            if (!/^[\da-f]+$/i.test(data) || data.length % 2 !== 0) {
+                throw new ValidationError('format', 'Invalid hex string');
+            }
+
+            return Uint8Array.from(data.match(/.{1,2}/g)!.map(b => parseInt(b, 16)));
+
+        default:
+            console.warn('Encoding not supported, falling back to UTF-8');
+
+            return new TextEncoder().encode(data);
+    }
+}
+
+export function decodeBuffer(buffer: Uint8Array, encoding: Encoding = 'utf-8'): string {
+    // eslint-disable-next-line ts/switch-exhaustiveness-check
+    switch (encoding) {
+        case 'utf8':
+        case 'utf-8':
+            return new TextDecoder().decode(buffer);
+
+        case 'utf16le':
+        case 'utf-16le':
+        case 'ucs2':
+        case 'ucs-2':
+            return decodeUtf16LE(buffer);
+
+        case 'latin1':
+            return String.fromCharCode(...buffer);
+
+        case 'ascii':
+            return String.fromCharCode(...buffer.map(b => b & 0x7F));
+
+        case 'base64':
+            return btoa(String.fromCharCode(...buffer));
+
+        case 'hex':
+            return Array.from(buffer).map(b => b.toString(16).padStart(2, '0')).join('');
+
+        default:
+            console.warn('Unsupported encoding, falling back to UTF-8');
+
+            return new TextDecoder().decode(buffer);
+    }
+}
+
+function encodeUtf16LE(str: string): Uint8Array {
+    const buf = new Uint8Array(str.length * 2);
+
+    for (let i = 0; i < str.length; i++) {
+        const code = str.charCodeAt(i);
+
+        buf[(i * 2)] = code & 0xFF;
+        buf[(i * 2) + 1] = code >> 8;
+    }
+
+    return buf;
+}
+
+function decodeUtf16LE(buf: Uint8Array): string {
+    if (buf.length % 2 !== 0) {
+        console.warn('Invalid UTF-16LE buffer length, truncating last byte');
+        buf = buf.slice(0, buf.length - 1);
+    }
+
+    const codeUnits = new Uint16Array(buf.buffer, buf.byteOffset, buf.byteLength / 2);
+
+    return String.fromCharCode(...codeUnits);
+}
+
+function encodeLatin1(str: string): Uint8Array {
+    const buf = new Uint8Array(str.length);
+
+    for (let i = 0; i < str.length; i++) {
+        buf[i] = str.charCodeAt(i) & 0xFF;
+    }
+
+    return buf;
+}
+
+function encodeAscii(str: string): Uint8Array {
+    const buf = new Uint8Array(str.length);
+
+    for (let i = 0; i < str.length; i++) {
+        buf[i] = str.charCodeAt(i) & 0x7F;
+    }
+
+    return buf;
+}

package/src/utils/errors.ts

@@ -0,0 +1,297 @@
+/**
+ * Error code to numeric errno mapping (Node.js compatible)
+ */
+const ERROR_CODE_TO_ERRNO: Record<string, number> = {
+    ENOENT: -2, // No such file or directory
+    EISDIR: -21, // Is a directory
+    ENOTDIR: -20, // Not a directory
+    EACCES: -13, // Permission denied
+    EEXIST: -17, // File exists
+    ENOTEMPTY: -39, // Directory not empty
+    EINVAL: -22, // Invalid argument
+    EIO: -5, // I/O error
+    ENOSPC: -28, // No space left on device
+    EBUSY: -16, // Device or resource busy
+    EINTR: -4, // Interrupted system call
+    ENOTSUP: -95, // Operation not supported
+    ERANGE: -34, // Result too large
+    EBADF: -9, // Bad file descriptor
+    EROOT: -1, // Custom: Cannot remove root directory
+};
+
+/**
+ * Base error class for all OPFS-related errors (Node.js SystemError compatible)
+ */
+export class OPFSError extends Error {
+    public readonly errno: number;
+    public readonly syscall?: string;
+    public readonly path?: string;
+
+    constructor(
+        message: string,
+        code: string,
+        path?: string,
+        syscall?: string,
+        cause?: any
+    ) {
+        super(message, { cause });
+        this.name = code;
+        this.errno = ERROR_CODE_TO_ERRNO[code] || -1;
+        this.path = path;
+        this.syscall = syscall;
+    }
+}
+
+/**
+ * Error thrown when OPFS is not supported in the current browser
+ */
+export class OPFSNotSupportedError extends OPFSError {
+    constructor(cause?: unknown) {
+        super('OPFS is not supported in this browser', 'ENOTSUP', undefined, undefined, cause);
+    }
+}
+
+/**
+ * Error thrown for invalid paths or path traversal attempts
+ */
+export class PathError extends OPFSError {
+    constructor(message: string, path: string, cause?: unknown) {
+        super(message, 'INVALID_PATH', path, 'access', cause);
+    }
+}
+
+/**
+ * Error thrown when files or directories don't exist
+ */
+export class ExistenceError extends OPFSError {
+    constructor(type: 'file' | 'directory' | 'source', path: string, cause?: unknown) {
+        const messages = {
+            file: `File not found: ${ path }`,
+            directory: `Directory not found: ${ path }`,
+            source: `Source does not exist: ${ path }`,
+        };
+
+        super(messages[type], 'ENOENT', path, 'access', cause);
+    }
+}
+
+/**
+ * Error thrown when permission is denied for an operation
+ */
+export class PermissionError extends OPFSError {
+    constructor(path: string, operation: string, cause?: unknown) {
+        super(`Permission denied for ${ operation } on: ${ path }`, 'EACCES', path, operation, cause);
+    }
+}
+
+/**
+ * Error thrown when an operation fails due to insufficient storage
+ */
+export class StorageError extends OPFSError {
+    constructor(message: string, path?: string, cause?: unknown) {
+        super(message, 'ENOSPC', path, 'write', cause);
+    }
+}
+
+/**
+ * Error thrown when a file is busy (locked by another operation)
+ */
+export class FileBusyError extends OPFSError {
+    constructor(path: string, cause?: unknown) {
+        super(`File is busy: ${ path }`, 'EBUSY', path, 'open', cause);
+    }
+}
+
+/**
+ * Error thrown when file/directory type expectations don't match
+ */
+export class FileTypeError extends OPFSError {
+    constructor(actualType: 'file' | 'directory', path: string, cause?: unknown) {
+        const message = actualType === 'directory'
+            ? `Is a directory: ${ path }`
+            : `Not a directory: ${ path }`;
+        const code = actualType === 'directory' ? 'EISDIR' : 'ENOTDIR';
+
+        super(message, code, path, 'access', cause);
+    }
+}
+
+/**
+ * Error thrown for validation failures (invalid arguments, formats, etc.)
+ */
+export class ValidationError extends OPFSError {
+    constructor(type: 'argument' | 'format' | 'descriptor' | 'overflow', message: string, path?: string, cause?: unknown) {
+        const codes = {
+            argument: 'EINVAL',
+            format: 'INVALID_FORMAT',
+            descriptor: 'EBADF',
+            overflow: 'ERANGE',
+        };
+
+        super(message, codes[type], path, 'validate', cause);
+    }
+}
+
+/**
+ * Error thrown when an operation is aborted
+ */
+export class OperationAbortedError extends OPFSError {
+    constructor(path: string, cause?: unknown) {
+        super(`Operation aborted: ${ path }`, 'EINTR', path, 'interrupt', cause);
+    }
+}
+
+/**
+ * Error thrown for I/O operation failures
+ */
+export class IOError extends OPFSError {
+    constructor(message: string, path?: string, cause?: unknown) {
+        super(message, 'EIO', path, 'io', cause);
+    }
+}
+
+/**
+ * Error thrown when an operation is not supported
+ */
+export class OperationNotSupportedError extends OPFSError {
+    constructor(path: string, cause?: unknown) {
+        super(`Operation not supported: ${ path }`, 'ENOTSUP', path, 'operation', cause);
+    }
+}
+
+/**
+ * Error thrown when directory operations fail
+ */
+export class DirectoryOperationError extends OPFSError {
+    constructor(code: string, path: string, cause?: unknown) {
+        const messages = {
+            RM_FAILED: `Failed to remove entry: ${ path }`,
+            ENOTEMPTY: `Directory not empty: ${ path }. Use recursive option to force removal.`,
+            EROOT: 'Cannot remove root directory',
+        };
+
+        super(messages[code as keyof typeof messages] || `Directory operation failed: ${ path }`, code, path, 'unlink', cause);
+    }
+}
+
+
+/**
+ * Error thrown when OPFS initialization fails
+ */
+export class InitializationFailedError extends OPFSError {
+    constructor(path: string, cause?: unknown) {
+        super('Failed to initialize OPFS', 'INIT_FAILED', path, 'init', cause);
+    }
+}
+
+/**
+ * Error thrown when file system operations fail
+ */
+export class FileSystemOperationError extends OPFSError {
+    constructor(operation: string, path: string, cause?: unknown) {
+        super(`Failed to ${ operation }: ${ path }`, `${ operation.toUpperCase() }_FAILED`, path, operation, cause);
+    }
+}
+
+/**
+ * Error thrown when a file or directory already exists
+ */
+export class AlreadyExistsError extends OPFSError {
+    constructor(path: string, cause?: unknown) {
+        super(`Destination already exists: ${ path }`, 'EEXIST', path, 'open', cause);
+    }
+}
+
+/**
+ * Create an OPFSError with file descriptor context
+ * 
+ * @param operation - The operation that failed (e.g., 'read', 'write', 'close')
+ * @param fd - The file descriptor number
+ * @param path - The file path
+ * @param error - The underlying error (optional)
+ * @returns OPFSError with appropriate context
+ */
+export function createFDError(operation: string, fd: number, path: string, error?: any): OPFSError {
+    const errorCode = `${ operation.toUpperCase() }_FAILED` as 'READ_FAILED' | 'WRITE_FAILED' | 'CLOSE_FAILED';
+
+    return new OPFSError(`Failed to ${ operation } file descriptor: ${ fd }`, errorCode, path, operation, error);
+}
+
+/**
+ * Context for mapping DOM errors to OPFS errors
+ */
+export interface MapDomErrorContext {
+    /** File path for context-specific errors */
+    path?: string;
+    /** Whether the operation involves a directory (for TypeMismatchError) */
+    isDirectory?: boolean;
+    /** Type of existence for NotFoundError (default: 'file') */
+    existenceType?: 'file' | 'directory';
+    /** When 'remove', maps InvalidModificationError to ENOTEMPTY and default to RM_FAILED */
+    operation?: 'remove';
+}
+
+/**
+ * Map DOM exceptions to OPFS error codes
+ *
+ * @param error - The DOM exception to map
+ * @param context - Context information for better error mapping
+ * @returns OPFSError with appropriate error code
+ */
+export function mapDomError(error: any, context?: MapDomErrorContext): OPFSError {
+    const path = context?.path;
+    const isDirectory = context?.isDirectory;
+    const existenceType = context?.existenceType ?? 'file';
+    const operation = context?.operation;
+
+    switch (error.name) {
+        case 'InvalidStateError':
+            return new FileBusyError(path || 'unknown', error);
+
+        case 'QuotaExceededError':
+            return new StorageError(`No space left on device: ${ path || 'unknown' }`, path, error);
+
+        case 'NotFoundError':
+            return new ExistenceError(existenceType, path!, error);
+
+        case 'TypeMismatchError':
+            if (isDirectory !== undefined) {
+                if (isDirectory) {
+                    return new FileTypeError('directory', path || 'unknown', error);
+                }
+                else {
+                    return new FileTypeError('file', path || 'unknown', error);
+                }
+            }
+
+            // Fall through to default for ambiguous cases
+            return new ValidationError('argument', `Type mismatch: ${ path || 'unknown' }`, path, error);
+
+        case 'NotAllowedError':
+        case 'SecurityError':
+            return new PermissionError(path!, 'unknown', error);
+
+        case 'InvalidModificationError':
+            if (operation === 'remove') {
+                return new DirectoryOperationError('ENOTEMPTY', path!, error);
+            }
+
+            return new ValidationError('argument', `Invalid modification: ${ path || 'unknown' }`, path, error);
+
+        case 'AbortError':
+            return new OperationAbortedError(path || 'unknown', error);
+
+        case 'OperationError':
+            return new IOError(`Operation failed: ${ path || 'unknown' }`, path, error);
+
+        case 'TypeError':
+            return new OperationNotSupportedError(path || 'unknown', error);
+
+        default:
+            if (operation === 'remove') {
+                return new DirectoryOperationError('RM_FAILED', path!, error);
+            }
+
+            return new IOError(`I/O error: ${ path || 'unknown' }`, path, error);
+    }
+}