Code Monkey home page Code Monkey logo

browser-fs-access's Introduction

Browser-FS-Access

This module allows you to easily use the File System Access API on supporting browsers, with a transparent fallback to the <input type="file"> and <a download> legacy methods. This library is a ponyfill.

Read more on the background of this module in my post Progressive Enhancement In the Age of Fugu APIs.

Live Demo

Try the library in your browser: https://googlechromelabs.github.io/browser-fs-access/demo/.

Installation

You can install the module with npm.

npm install --save browser-fs-access

Usage Examples

The module feature-detects support for the File System Access API and only loads the actually relevant code.

Importing what you need

Import only the features that you need. In the code sample below, all features are loaded. The imported methods will use the File System Access API or a fallback implementation.

import {
  fileOpen,
  directoryOpen,
  fileSave,
  supported,
} from 'https://unpkg.com/browser-fs-access';

Feature detection

You can check supported to see if the File System Access API is supported.

if (supported) {
  console.log('Using the File System Access API.');
} else {
  console.log('Using the fallback implementation.');
}

Opening a file

const blob = await fileOpen({
  mimeTypes: ['image/*'],
});

Opening multiple files

const blobs = await fileOpen({
  mimeTypes: ['image/*'],
  multiple: true,
});

Opening files of different MIME types

const blobs = await fileOpen([
  {
    description: 'Image files',
    mimeTypes: ['image/jpg', 'image/png', 'image/gif', 'image/webp'],
    extensions: ['.jpg', '.jpeg', '.png', '.gif', '.webp'],
    multiple: true,
  },
  {
    description: 'Text files',
    mimeTypes: ['text/*'],
    extensions: ['.txt'],
  },
]);

Opening all files in a directory

Optionally, you can recursively include subdirectories.

const blobsInDirectory = await directoryOpen({
  recursive: true,
});

Saving a file

await fileSave(blob, {
  fileName: 'Untitled.png',
  extensions: ['.png'],
});

Saving a Response that will be streamed

const response = await fetch('foo.png');
await fileSave(response, {
  fileName: 'foo.png',
  extensions: ['.png'],
});

Saving a Promise<Blob> that will be streamed.

No need to await the Blob to be created.

const blob = createBlobAsyncWhichMightTakeLonger(someData);
await fileSave(blob, {
  fileName: 'Untitled.png',
  extensions: ['.png'],
});

API Documentation

Opening files:

// Options are optional. You can pass an array of options, too.
const options = {
  // List of allowed MIME types, defaults to `*/*`.
  mimeTypes: ['image/*'],
  // List of allowed file extensions (with leading '.'), defaults to `''`.
  extensions: ['.png', '.jpg', '.jpeg', '.webp'],
  // Set to `true` for allowing multiple files, defaults to `false`.
  multiple: true,
  // Textual description for file dialog , defaults to `''`.
  description: 'Image files',
  // Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle.
  startIn: 'downloads',
  // By specifying an ID, the user agent can remember different directories for different IDs.
  id: 'projects',
  // Include an option to not apply any filter in the file picker, defaults to `false`.
  excludeAcceptAllOption: true,
};

const blobs = await fileOpen(options);

Opening directories:

// Options are optional.
const options = {
  // Set to `true` to recursively open files in all subdirectories, defaults to `false`.
  recursive: true,
  // Open the directory with `"read"` or `"readwrite"` permission, defaults to `"read"`.
  mode:
  // Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle.
  startIn: 'downloads',
  // By specifying an ID, the user agent can remember different directories for different IDs.
  id: 'projects',
  // Callback to determine whether a directory should be entered, return `true` to skip.
  skipDirectory: (entry) => entry.name[0] === '.',
};

const blobs = await directoryOpen(options);

The module also polyfills a webkitRelativePath property on returned files in a consistent way, regardless of the underlying implementation.

Saving files:

// Options are optional. You can pass an array of options, too.
const options = {
  // Suggested file name to use, defaults to `''`.
  fileName: 'Untitled.txt',
  // Suggested file extensions (with leading '.'), defaults to `''`.
  extensions: ['.txt'],
  // Suggested directory in which the file picker opens. A well-known directory, or a file or directory handle.
  startIn: 'downloads',
  // By specifying an ID, the user agent can remember different directories for different IDs.
  id: 'projects',
  // Include an option to not apply any filter in the file picker, defaults to `false`.
  excludeAcceptAllOption: true,
};

// Optional file handle to save back to an existing file.
// This will only work with the File System Access API.
// Get a `FileHandle` from the `handle` property of the `Blob`
// you receive from `fileOpen()` (this is non-standard).
const existingHandle = previouslyOpenedBlob.handle;

// Optional flag to determine whether to throw (rather than open a new file
// save dialog) when `existingHandle` is no longer good, for example, because
// the underlying file was deleted. Defaults to `false`.
const throwIfExistingHandleNotGood = true;

// `blobOrPromiseBlobOrResponse` is a `Blob`, a `Promise<Blob>`, or a `Response`.
await fileSave(
  blobOrResponseOrPromiseBlob,
  options,
  existingHandle,
  throwIfExistingHandleNotGood
);

File operations and exceptions

The File System Access API supports exceptions, so apps can throw when problems occur (permissions not granted, out of disk space,โ€ฆ), or when the user cancels the dialog. The legacy methods, unfortunately, do not support exceptions (albeit there is an HTML issue open for this request). If your app depends on exceptions, see the file index.d.ts for the documentation of the legacySetup parameter.

Browser-FS-Access in Action

You can see the module in action in the Excalidraw drawing app.

excalidraw

It also powers the SVGcode app that converts raster images to SVGs.

svgcode

Alternatives

A similar, but more extensive library called native-file-system-adapter is provided by @jimmywarting.

Ecosystem

If you are looking for a similar solution for dragging and dropping of files, check out @placemarkio/flat-drop-files.

Acknowledgements

Thanks to @developit for improving the dynamic module loading and @dwelle for the helpful feedback, issue reports, and the Windows build fix. Directory operations were made consistent regarding webkitRelativePath and parallelized and sped up significantly by @RReverser. The TypeScript type annotations were initially provided by @nanaian. Dealing correctly with cross-origin iframes was contributed by @nikhilbghodke and @kbariotis. The exception handling of the legacy methods was contributed by @jmrog. The streams and blob saving was improved by @tmcw.

License and Note

Apache 2.0.

This is not an official Google product.

browser-fs-access's People

Contributors

tomayac avatar dwelle avatar seanaye avatar developit avatar dependabot[bot] avatar bates64 avatar steveruizok avatar amatewasu avatar rreverser avatar tclangv avatar tmcw avatar niedzielski avatar jmrog avatar barba828 avatar christianliebel avatar dmihalcik-virtru avatar fvilers avatar kbariotis avatar raid avatar simon-lammes avatar nikhilbghodke avatar rwv avatar skratchdot avatar soulofmischief avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.