@opfs.js/core
    Preparing search index...

    @opfs.js/core

    @opfs.js/core

    NPM Version Package Size
    GitHub Stars

    @opfs.js/core is a modern JavaScript/TypeScript wrapper for the browser's native OPFS (Origin Private File System), providing a clean, user-friendly, and feature-rich API for working with the browser's private file system.

    • 🔄 Fully Asynchronous API - Based on Promises and async/await
    • 📁 Complete File System Operations - Create, read, write, copy, move, and delete files and directories
    • 🔒 Synchronized File Access - Efficient synchronous file operations through Web Workers
    • 📝 Streaming File Processing - Support for streaming large files
    • 🔍 TypeScript Support - Full type definitions and type checking
    • ⚡ High Performance - Concurrent operations using Promise pools
    • 🧩 Modular Design - Easy to extend and integrate

    Install using npm, yarn, or pnpm:

    # Using npm
    npm install @opfs.js/core

    # Using yarn
    yarn add @opfs.js/core

    # Using pnpm
    pnpm add @opfs.js/core

    import { file } from "@opfs.js/core";

    // Create or open a file
    const myFile = file("/documents/report.txt");
    await myFile.create();

    // Write content to the file
    const rw = await myFile.open({ mode: "readwrite" });
    await rw.write("Hello, OPFS!");
    await rw.flush();
    await rw.close();

    // Read file content
    const fileContent = await myFile.text();
    console.log(fileContent); // 'Hello, OPFS!'

    // Read as binary data
    const buffer = await myFile.arrayBuffer();

    // Delete the file
    await myFile.remove();

    import { dir } from "@opfs.js/core";

    // Create or open a directory
    const myDir = dir("/documents/work");
    await myDir.create();

    // List directory contents
    const children = await myDir.children();
    children.forEach((child) => {
      console.log(`${child.kind}: ${child.fullPath}`);
    });

    // Copy directory
    const destDir = dir("/backup");
    await destDir.create();
    await myDir.copyTo(destDir);

    // Delete directory
    await myDir.remove();

    Every file system object (file or directory) has the following properties:

    const myFile = file("/documents/report.txt");
    console.log(myFile.fullPath); // '/documents/report.txt'
    console.log(myFile.name); // 'report.txt'
    console.log(myFile.parents); // ['documents']
    console.log(myFile.kind); // 'file' (or 'directory')

    import { file } from "@opfs.js/core";

    const largeFile = file("/data/large.bin");
    await largeFile.create();

    // Write large data
    const rw = await largeFile.open();
    // Write at specific offset
    await rw.write(new Uint8Array([1, 2, 3, 4, 5]), { at: 100 });
    // Truncate file
    await rw.truncate(1024 * 1024); // 1MB
    await rw.close();

    // Read as stream
    const stream = await largeFile.stream();
    const reader = stream.getReader();
    // Read stream data...

    // Check if file exists
    const exists = await largeFile.exists();

    // Move file
    const newLocation = dir("/archive");
    await newLocation.create();
    await largeFile.moveTo(newLocation);

    Full API documentation is available at https://atox996.github.io/opfs/.

    • file(path: string): OPFile - Creates a file operation object
    • dir(path: string): OPDir - Creates a directory operation object
    • create(): Promise<FileSystemFileHandle> - Creates the file
    • exists(): Promise<boolean> - Checks if the file exists
    • remove(): Promise<void> - Deletes the file
    • copyTo(dest): Promise<void> - Copies the file to the destination
    • moveTo(dest): Promise<void> - Moves the file to the destination
    • open(options?): Promise<FileRO | FileRW> - Opens the file to get an access handle
    • text(): Promise<string> - Reads the file content as text
    • arrayBuffer(): Promise<ArrayBuffer> - Reads the file content as binary data
    • stream(): Promise<ReadableStream<BufferSource>> - Gets a readable stream for the file
    • getFile(): Promise<File | undefined> - Gets the underlying File object
    • create(): Promise<FileSystemDirectoryHandle> - Creates the directory
    • exists(): Promise<boolean> - Checks if the directory exists
    • remove(): Promise<void> - Deletes the directory and its contents
    • children(): Promise<(OPDir | OPFile)[]> - Lists the immediate children of the directory
    • copyTo(dest): Promise<void> - Copies the directory and its contents to the destination
    • moveTo(dest): Promise<void> - Moves the directory and its contents to the destination
    • read(size, options?): Promise<ArrayBuffer> - Reads data from the file
    • getSize(): Promise<number> - Gets the file size
    • close(): Promise<void> - Closes the file handle

    Extends FileRO with these additional methods:

    • write(data, options?): Promise<number> - Writes data to the file
    • truncate(newSize): Promise<void> - Truncates the file to the specified size
    • flush(): Promise<void> - Flushes pending writes to storage

    This library requires browsers that support:

    • Origin Private File System (OPFS)
    • Web Workers
    • ReadableStream
    • Chrome 121+ (createSyncAccessHandle with full mode option support)
    • Edge 121+ (createSyncAccessHandle with full mode option support)
    • Firefox 111+ (createSyncAccessHandle supported, but mode parameter not yet available)
    • Safari 15.2+ (createSyncAccessHandle supported, but mode parameter not yet available)

    If you want to contribute to this project, follow these steps:

    1. Clone the repository
    git clone https://github.com/atox996/opfs.git
    cd opfs
    1. Install dependencies
    pnpm install
    1. Start the development server
    pnpm dev
    1. Build the project
    pnpm build
    1. Run code checks
    pnpm lint

    This project is licensed under the MIT License - see the LICENSE file for details

    Contributions are welcome! Please submit Issues and Pull Requests to help improve this project. Before submitting, ensure your code adheres to the project's coding style and quality requirements.

    This project is built on top of the browser's native Origin Private File System API, aiming to provide a cleaner, more user-friendly interface for working with the browser's private file system.

    Settings

    Member Visibility

    On This Page

    @opfs.js/core