@zacharygriffee/random-access-idb NPM

RandomAccessIdb

RandomAccessIdb is a library that provides a random-access interface for IndexedDB storage in web applications. It allows for efficient reading, writing, and management of data blocks using a chunk-based approach, similar to how traditional file systems manage files.

Features

Supports chunk-based random access storage on top of IndexedDB.
Provides functions to read, write, delete, and truncate data.
Automatically manages metadata and file size.
Supports queuing of read/write operations to ensure consistency.
Allows purging and reinitializing storage when needed.

Installation

You can include this library in your project by cloning the repository or importing it into your project as needed.

    npm install @zacharygriffee/random-access-idb

Usage

1. Creating a New File

To create a new RandomAccessIdb file, use the createFile function:

import { createFile } from '@zacharygriffee/random-access-idb';

const ras = createFile('myFile.txt', { chunkSize: 1024 });

2. Writing Data

Use the write method to write data to the file. The method accepts an offset, the data buffer, and a callback function:

const buffer = b4a.alloc(1024, 'Hello, World!'); // 1KB buffer

ras.write(0, buffer, (err) => {
    if (err) {
        console.error('Write failed:', err);
    } else {
        console.log('Write successful');
    }
});

3. Reading Data

To read data from the file, use the read method with the offset, size, and callback:

ras.read(0, 1024, (err, data) => {
    if (err) {
        console.error('Read failed:', err);
    } else {
        console.log('Read data:', b4a.toString(data));
    }
});

4. Truncating the File

You can truncate the file by specifying an offset:

ras.truncate(512, (err) => {
    if (err) {
        console.error('Truncate failed:', err);
    } else {
        console.log('Truncate successful');
    }
});

5. Deleting Data

To delete specific blocks of data, use the del method:

ras.del(0, 512, (err) => {
    if (err) {
        console.error('Delete failed:', err);
    } else {
        console.log('Delete successful');
    }
});

6. Purging the File

To delete the file from IndexedDB and reset its metadata, use the purge method:

ras.purge((err) => {
    if (err) {
        console.error('Purge failed:', err);
    } else {
        console.log('File purged successfully');
    }
});

7. Retrieving File Stats

To get metadata about the file (e.g., file size, chunk size), use the stat method:

ras.stat((err, stats) => {
    if (err) {
        console.error('Stat failed:', err);
    } else {
        console.log('File stats:', stats);
    }
});

Error Handling

This library mimics typical file system error codes, such as ENOENT, when trying to access a file or block that doesn’t exist. Make sure to handle errors properly in callbacks.

Example:

ras.read(0, 1024, (err, data) => {
    if (err) {
        if (err.code === 'ENOENT') {
            console.error('File not found or empty:', err);
        } else {
            console.error('Read error:', err);
        }
    } else {
        console.log('Read successful:', data);
    }
});