FileIO

This provides methods for saving and loading files in the browser.

import * as fileio from '@cipscis/fileio'; import { load, save, ReadMethod } from '@cipscis/fileio'; import { load, ReadMethod } from '@cipscis/fileio/load'; import { save } from '@cipscis/fileio/save';

Load

load(readMethod: ReadMethod)

Prompts the user to select a file on their computer, then loads it into memory. Returns a Promise.

Important note: for browsers that don't support the File System Access API, because there is no reliable way to detect when a user cancels out of a file selection window, it is possible this Promise may never resolve. Make sure your code is written to accommodate this.

To load files, FileIO creates an <input type="file" /> element and triggers a click event on it, causing the browser to open a file dialogue.

Because this involves opening a native modal dialogue, the load method can only be called as a direct response to user action.

If the user selects a file, then that file's contents are passed to the Promise's resolve callback.

This method can be loaded on its own:

import { load } from '@cipscis/fileio'; import { load } from '@cipscis/fileio/load';

readMethod: ReadMethod

'arrayBuffer' | 'binaryString' | 'dataUrl' | text' | 'file'

You can import the ReadMethod enum directly:

import { ReadMethod } from '@cipscis/fileio'; import { ReadMethod } from '@cipscis/fileio/load';

Determines which read method to use with the FileReader API. Defaults to 'text'.

The 'file' option bypasses the FileReader API and returns the File object directly.

Examples

The format in which the file is made available depends on the method used.

Images can be loaded using the 'dataUrl' read method, allowing the result to be set as the src attribute of an img tag to display the selected image:

Load Image

Save

save(data: any, options?: SaveOptions)

The save method can save a File, a Blob, or arbitrary data to disk.

To save files, FileIO creates an <a> tag pointing to a data URL with a download attribute and triggers a click on it. This causes the browser to perform its default download action, which may include showing the user a native modal dialogue window prompting them to select a location or change the filename.

For Microsoft browsers that don't support this method, navigator.msSaveBlob is used instead.

This method can be loaded on its own:

import { save } from '@cipscis/fileio'; import { save } from '@cipscis/fileio/save';

data: any

The data to be saved as a file.

options?: SaveOptions

filename?: string

The default name to prompt the user to use for the file. Defaults to 'file', though if a File object with a name property is being saved that name will be used as the default.

type?: string

The MIME type to use when saving arbitrary data. The strings 'csv' and 'json' can be used as shorthand for 'text/csv' and 'application/json', respectively.

If the MIME type indicates that data should be saved as JSON, FileIO will attempt to stringify the data if it isn't already a string, and the filename will be given a '.json' extension.

If the MIME type indicates that data should be saved as a CSV, FileIO will expect a 2D array for it to process into a CSV string.

saveAs?: boolean

If saveAs is set to true, the File System Access API's showSaveFilePicker method will be used if available, forcing browsers to show a "Save As" dialogue regardless of their standard download location settings.

Important note: When saving a file via a file handle retrieved through the showSaveFilePicker method, the browser will not display the usual "file saved" notification to the user. If you intend to use this method of saving, you should consider how to notify the user that their file has been saved.

All the examples on this page have the saveAs option set to false.

Toggle saveAs option

If you are saving data as a CSV, you can also pass through any options accepted by @cipscis/csv.

Examples

Save some data

Save JSON

Save a CSV

Save a file