opfs-worker 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+export type Kind = 'file' | 'directory';
+export interface FileStat {
+    kind: Kind;
+    size: number;
+    mtime: string;
+    ctime: 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 type * from './opfs.worker';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,WAAW,CAAC;AAExC,MAAM,WAAW,QAAQ;IACrB,IAAI,EAAE,IAAI,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;CACxB;AAED,mBAAmB,eAAe,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/encoder.d.ts

@@ -0,0 +1,4 @@
+import type { BufferEncoding } from 'typescript';
+export declare function encodeString(data: string, encoding?: BufferEncoding): Uint8Array;
+export declare function decodeBuffer(buffer: Uint8Array, encoding?: BufferEncoding): string;
+//# sourceMappingURL=encoder.d.ts.map

package/dist/utils/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../../src/utils/encoder.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,cAAwB,GAAG,UAAU,CAqCzF;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,GAAE,cAAwB,GAAG,MAAM,CAgC3F"}

package/dist/utils/encoder.js

@@ -0,0 +1,86 @@
+import { OPFSError } from './errors';
+export function encodeString(data, encoding = 'utf-8') {
+    switch (encoding) {
+        case 'utf8':
+        case 'utf-8':
+            return new TextEncoder().encode(data);
+        case 'utf16le':
+        case 'ucs2':
+        case 'ucs-2':
+            return encodeUtf16LE(data);
+        case 'ascii':
+            return encodeAscii(data);
+        case 'latin1':
+            return encodeLatin1(data);
+        case 'binary':
+            // For binary encoding, treat the string as raw bytes
+            // This assumes the string contains raw byte values
+            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 OPFSError('Invalid hex string', 'INVALID_HEX_FORMAT');
+            }
+            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, encoding = 'utf-8') {
+    switch (encoding) {
+        case 'utf8':
+        case 'utf-8':
+            return new TextDecoder().decode(buffer);
+        case 'utf16le':
+        case 'ucs2':
+        case 'ucs-2':
+            return decodeUtf16LE(buffer);
+        case 'latin1':
+            return String.fromCharCode(...buffer);
+        case 'binary':
+            // For binary encoding, return raw byte values as string
+            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) {
+    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) {
+    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) {
+    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) {
+    const buf = new Uint8Array(str.length);
+    for (let i = 0; i < str.length; i++) {
+        buf[i] = str.charCodeAt(i) & 0x7F;
+    }
+    return buf;
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Base error class for all OPFS-related errors
+ */
+export declare class OPFSError extends Error {
+    readonly code: string;
+    readonly path?: string | undefined;
+    constructor(message: string, code: string, path?: string | undefined);
+}
+/**
+ * Error thrown when OPFS is not supported in the current browser
+ */
+export declare class OPFSNotSupportedError extends OPFSError {
+    constructor();
+}
+/**
+ * Error thrown when OPFS is not mounted
+ */
+export declare class OPFSNotMountedError extends OPFSError {
+    constructor();
+}
+/**
+ * Error thrown for invalid paths or path traversal attempts
+ */
+export declare class PathError extends OPFSError {
+    constructor(message: string, path: string);
+}
+/**
+ * Error thrown when a requested file doesn't exist
+ */
+export declare class FileNotFoundError extends OPFSError {
+    constructor(path: string);
+}
+/**
+ * Error thrown when a requested directory doesn't exist
+ */
+export declare class DirectoryNotFoundError extends OPFSError {
+    constructor(path: string);
+}
+/**
+ * Error thrown when permission is denied for an operation
+ */
+export declare class PermissionError extends OPFSError {
+    constructor(path: string, operation: string);
+}
+/**
+ * Error thrown when an operation fails due to insufficient storage
+ */
+export declare class StorageError extends OPFSError {
+    constructor(message: string, path?: string);
+}
+/**
+ * Error thrown when an operation times out
+ */
+export declare class TimeoutError extends OPFSError {
+    constructor(operation: string, path?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;aACa,IAAI,EAAE,MAAM;aAAkB,IAAI,CAAC,EAAE,MAAM;gBAA5E,OAAO,EAAE,MAAM,EAAkB,IAAI,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAI3F;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,SAAS;;CAInD;AAGD;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,SAAS;;CAIjD;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,SAAS;gBACxB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAG5C;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,SAAS;gBAChC,IAAI,EAAE,MAAM;CAG3B;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,SAAS;gBACrC,IAAI,EAAE,MAAM;CAG3B;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,SAAS;gBAC9B,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAG9C;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC3B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAG7C;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,SAAS;gBAC3B,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAG/C"}

package/dist/utils/errors.js

@@ -0,0 +1,77 @@
+/**
+ * Base error class for all OPFS-related errors
+ */
+export class OPFSError extends Error {
+    code;
+    path;
+    constructor(message, code, path) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.name = 'OPFSError';
+    }
+}
+/**
+ * Error thrown when OPFS is not supported in the current browser
+ */
+export class OPFSNotSupportedError extends OPFSError {
+    constructor() {
+        super('OPFS is not supported in this browser', 'OPFS_NOT_SUPPORTED');
+    }
+}
+/**
+ * Error thrown when OPFS is not mounted
+ */
+export class OPFSNotMountedError extends OPFSError {
+    constructor() {
+        super('OPFS is not mounted', 'OPFS_NOT_MOUNTED');
+    }
+}
+/**
+ * Error thrown for invalid paths or path traversal attempts
+ */
+export class PathError extends OPFSError {
+    constructor(message, path) {
+        super(message, 'INVALID_PATH', path);
+    }
+}
+/**
+ * Error thrown when a requested file doesn't exist
+ */
+export class FileNotFoundError extends OPFSError {
+    constructor(path) {
+        super(`File not found: ${path}`, 'FILE_NOT_FOUND', path);
+    }
+}
+/**
+ * Error thrown when a requested directory doesn't exist
+ */
+export class DirectoryNotFoundError extends OPFSError {
+    constructor(path) {
+        super(`Directory not found: ${path}`, 'DIRECTORY_NOT_FOUND', path);
+    }
+}
+/**
+ * Error thrown when permission is denied for an operation
+ */
+export class PermissionError extends OPFSError {
+    constructor(path, operation) {
+        super(`Permission denied for ${operation} on: ${path}`, 'PERMISSION_DENIED', path);
+    }
+}
+/**
+ * Error thrown when an operation fails due to insufficient storage
+ */
+export class StorageError extends OPFSError {
+    constructor(message, path) {
+        super(message, 'STORAGE_ERROR', path);
+    }
+}
+/**
+ * Error thrown when an operation times out
+ */
+export class TimeoutError extends OPFSError {
+    constructor(operation, path) {
+        super(`Operation timed out: ${operation}`, 'TIMEOUT_ERROR', path);
+    }
+}

package/dist/utils/helpers.d.ts

@@ -0,0 +1,33 @@
+import type { BufferEncoding } from 'typescript';
+export declare function checkOPFSSupport(): void;
+export declare function splitPath(path: string | string[]): string[];
+export declare function joinPath(segments: string[] | string): string;
+export declare function createBuffer(data: string | Uint8Array | ArrayBuffer, encoding?: BufferEncoding): Uint8Array;
+/**
+ * Read raw binary data from a file using a file handle
+ *
+ * @param fileHandle - The file handle to read from
+ * @returns The raw binary data as Uint8Array
+ */
+export declare function readFileData(fileHandle: FileSystemFileHandle): Promise<Uint8Array>;
+/**
+ * Write data to a file using a file handle
+ *
+ * @param fileHandle - The file handle to write to
+ * @param data - The data to write to the file
+ * @param encoding - The encoding to use
+ * @param options - Write options (truncate or append)
+ */
+export declare function writeFileData(fileHandle: FileSystemFileHandle, data: string | Uint8Array | ArrayBuffer, encoding?: BufferEncoding, options?: {
+    truncate?: boolean;
+    append?: boolean;
+}): Promise<void>;
+/**
+ * Calculate file hash using Web Crypto API
+ *
+ * @param buffer - The file content as Uint8Array
+ * @param algorithm - Hash algorithm to use (default: 'SHA-1')
+ * @returns Promise that resolves to the hash string
+ */
+export declare function calculateFileHash(buffer: Uint8Array, algorithm?: string): Promise<string>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/utils/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/utils/helpers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,wBAAgB,gBAAgB,IAAI,IAAI,CAIvC;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAM3D;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,MAAM,CAI5D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,EAAE,QAAQ,GAAE,cAAwB,GAAG,UAAU,CAMpH;AAGD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,oBAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAcxF;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAC/B,UAAU,EAAE,oBAAoB,EAChC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,WAAW,EACvC,QAAQ,CAAC,EAAE,cAAc,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACvD,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,UAAU,EAAE,SAAS,GAAE,MAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAcxG"}

package/dist/utils/helpers.js

@@ -0,0 +1,96 @@
+import { encodeString } from './encoder';
+import { OPFSError, OPFSNotSupportedError } from './errors';
+export function checkOPFSSupport() {
+    if (!('storage' in navigator) || !('getDirectory' in navigator.storage)) {
+        throw new OPFSNotSupportedError();
+    }
+}
+export function splitPath(path) {
+    if (Array.isArray(path)) {
+        return path;
+    }
+    return path.split('/').filter(Boolean);
+}
+export function joinPath(segments) {
+    return typeof segments === 'string'
+        ? (segments ?? '/')
+        : `/${segments.join('/')}`;
+}
+export function createBuffer(data, encoding = 'utf-8') {
+    if (typeof data === 'string') {
+        return encodeString(data, encoding);
+    }
+    return data instanceof Uint8Array ? data : new Uint8Array(data);
+}
+/**
+ * Read raw binary data from a file using a file handle
+ *
+ * @param fileHandle - The file handle to read from
+ * @returns The raw binary data as Uint8Array
+ */
+export async function readFileData(fileHandle) {
+    const handle = await fileHandle.createSyncAccessHandle();
+    try {
+        const size = handle.getSize();
+        const buffer = new Uint8Array(size);
+        handle.read(buffer, { at: 0 });
+        return buffer;
+    }
+    finally {
+        handle.close();
+    }
+}
+/**
+ * Write data to a file using a file handle
+ *
+ * @param fileHandle - The file handle to write to
+ * @param data - The data to write to the file
+ * @param encoding - The encoding to use
+ * @param options - Write options (truncate or append)
+ */
+export async function writeFileData(fileHandle, data, encoding, options = {}) {
+    let handle = null;
+    try {
+        handle = await fileHandle.createSyncAccessHandle();
+        const buffer = createBuffer(data, encoding);
+        const writeOffset = options.append ? handle.getSize() : 0;
+        handle.write(buffer, { at: writeOffset });
+        if (options.truncate && !options.append) {
+            handle.truncate(buffer.byteLength);
+        }
+        handle.flush();
+    }
+    catch (error) {
+        console.error(error);
+        const operation = options.append ? 'append' : 'write';
+        throw new OPFSError(`Failed to ${operation} file`, `${operation.toUpperCase()}_FAILED`);
+    }
+    finally {
+        if (handle) {
+            try {
+                handle.close();
+            }
+            catch { /* ~ */ }
+        }
+    }
+}
+/**
+ * Calculate file hash using Web Crypto API
+ *
+ * @param buffer - The file content as Uint8Array
+ * @param algorithm - Hash algorithm to use (default: 'SHA-1')
+ * @returns Promise that resolves to the hash string
+ */
+export async function calculateFileHash(buffer, algorithm = 'SHA-1') {
+    try {
+        // Ensure buffer is properly typed for crypto.subtle.digest
+        const bufferSource = new Uint8Array(buffer);
+        const hashBuffer = await crypto.subtle.digest(algorithm, bufferSource);
+        const hashArray = Array.from(new Uint8Array(hashBuffer));
+        return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
+    }
+    catch (error) {
+        console.warn(`Failed to calculate ${algorithm} hash:`, error);
+        throw error;
+    }
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+    "name": "opfs-worker",
+    "version": "0.1.1",
+    "description": "A robust TypeScript library for working with Origin Private File System (OPFS) through Web Workers",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/types.d.ts",
+            "import": "./dist/opfs-worker.js",
+            "require": "./dist/opfs-worker.cjs"
+        },
+        "./inline": {
+            "types": "./dist/worker/inline-worker.d.ts",
+            "import": "./dist/opfs-worker-inline.js",
+            "require": "./dist/opfs-worker-inline.cjs"
+        }
+    },
+    "files": [
+        "dist/**/*",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "vite build && tsc -p tsconfig.build.json",
+        "dev": "vite serve demo",
+        "preview": "vite preview demo",
+        "type-check": "tsc --noEmit",
+        "lint": "eslint src --ext .ts,.tsx",
+        "lint:fix": "eslint src --ext .ts,.tsx --fix",
+        "test": "vitest",
+        "test:coverage": "vitest --coverage",
+        "prepublishOnly": "npm run build",
+        "version": "changeset && changeset version",
+        "release": "changeset publish"
+    },
+    "keywords": [
+        "opfs",
+        "origin-private-file-system",
+        "web-worker",
+        "filesystem",
+        "browser-storage",
+        "file-api",
+        "typescript"
+    ],
+    "author": "Your Name <your.email@example.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/your-username/opfs-worker.git"
+    },
+    "bugs": {
+        "url": "https://github.com/your-username/opfs-worker/issues"
+    },
+    "homepage": "https://github.com/your-username/opfs-worker#readme",
+    "devDependencies": {
+        "@changesets/cli": "^2.29.5",
+        "@flexbe/eslint-config": "^1.0.11",
+        "@types/node": "^20.19.9",
+        "@typescript-eslint/eslint-plugin": "^7.18.0",
+        "@typescript-eslint/parser": "^7.18.0",
+        "@vitest/coverage-v8": "^1.6.1",
+        "eslint": "^8.57.1",
+        "happy-dom": "^13.10.1",
+        "typescript": "^5.9.2",
+        "vite": "^7.0.6",
+        "vitest": "^1.6.1"
+    },
+    "engines": {
+        "node": ">=20.0.0"
+    },
+    "peerDependencies": {
+        "typescript": ">=5.0.0"
+    },
+    "packageManager": "bun@1.1.29",
+    "dependencies": {
+        "comlink": "^4.4.2"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}