import {IDBPromisedMutableFile} from 'idb-file-storage/src/idb-file-storage.js'

public class | source

IDBPromisedMutableFile

Wraps an IDBMutableFile with a nicer Promise-based API.

Instances of this class are created from the IDBFileStorage.createMutableFile method.

Method Summary

Public Methods
public	getFile(): Promise<File> Get a File instance of this mutable file.
public	open(mode: "readonly" \| "readwrite" \| "writeonly"): IDBPromisedFileHandle Open a mutable file for reading/writing data.
public	persist(): Promise Persist the this mutable file into its related IDBFileStorage.
public	async persistAsFileSnapshot(snapshotName: *): Promise<File> Persist the content of the mutable file into the files storage as a File, using the specified snapshot name and return the persisted File instance.
public	async runFileRequestGenerator(generatorFunction: function* (lockedFile) {...}, mode: "readonly" \| "readwrite" \| "writeonly") Run a generator function which can run a sequence of FileRequests without the lockfile to become inactive.

Public Methods

public getFile(): Promise<File> source

Get a File instance of this mutable file.

Return:

Promise<File>

A promise resolved to the File instance.

To read the actual content of the mutable file as a File object, it is often better to use IDBPromisedMutableFile.saveAsFileSnapshot to save a persistent snapshot of the file in the IndexedDB store, or reading it directly using the IDBPromisedFileHandle instance returned by the IDBPromisedMutableFile.open method.

The reason is that to be able to read the content of the returned file a lockfile have be keep the file open, e.d. as in the following example.

Example:

    ...
    let waitSnapshotStored;
    await mutableFile.runFileRequestGenerator(function* (lockedFile) {
      const file = yield lockedFile.mutableFile.getFile();
      // read the file content or turn it into a persistent object of its own
      // (e.g. by saving it back into IndexedDB as its snapshot in form of a File object,
      // or converted into a data url, a string or an array buffer)

      waitSnapshotStored = tmpFiles.put("${filename}/last_snapshot", file);
    }

    await waitSnapshotStored;
    let fileSnapshot = await tmpFiles.get("${filename}/last_snapshot");
    ...
    // now you can use fileSnapshot even if the mutableFile lock is not active anymore.

public open(mode: "readonly" | "readwrite" | "writeonly"): IDBPromisedFileHandle source

Open a mutable file for reading/writing data.

Params:

Name	Type	Attribute	Description
mode	"readonly" \| "readwrite" \| "writeonly"		The mode of the created IDBPromisedFileHandle instance.

Return:

IDBPromisedFileHandle

The created IDBPromisedFileHandle instance.

public persist(): Promise source

Persist the this mutable file into its related IDBFileStorage.

Return:

Promise

A promise resolved on the mutable file has been persisted into IndexedDB.

public async persistAsFileSnapshot(snapshotName: *): Promise<File> source

Persist the content of the mutable file into the files storage as a File, using the specified snapshot name and return the persisted File instance.

Params:

Name	Type	Attribute	Description
snapshotName	*

Return:

Promise<File>

A promise resolved to the File instance.

Example:


     const file = await mutableFile.persistAsFileSnapshot(`${filename}/last_snapshot`);
     const blobURL = URL.createObjectURL(file);
     ...
     // The blob URL is still valid even if the mutableFile is not active anymore.

public async runFileRequestGenerator(generatorFunction: function* (lockedFile) {...}, mode: "readonly" | "readwrite" | "writeonly") source

Run a generator function which can run a sequence of FileRequests without the lockfile to become inactive.

This method should be rarely needed, mostly to optimize a sequence of file operations without the file to be closed and automatically re-opened between two file requests.

Params:

Name	Type	Attribute	Description
generatorFunction	function* (lockedFile) {...}
mode	"readonly" \| "readwrite" \| "writeonly"

Example:

  (async function () {
     const tmpFiles = await IDBFiles.getFileStorage({name: "tmpFiles"});
     const mutableFile = await tmpFiles.createMutableFile("test-mutable-file.txt");

     let allFileData;

     function* fileOperations(lockedFile) {
       yield lockedFile.write("some data");
       yield lockedFile.write("more data");
       const metadata = yield lockedFile.getMetadata();

       lockedFile.location = 0;
       allFileData = yield lockedFile.readAsText(metadata.size);
     }

     await mutableFile.runFileRequestGenerator(fileOperations, "readwrite");

     console.log("File Data", allFileData);
  })();