File System Access

https://github.com/wicg/file-system-access
Admin
A web API specification that enables developers to build powerful web apps that interact with files...
Tokens:12,473
Snippets:144
Trust Score:9.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### CSP Client Registration File Example

Source: https://github.com/wicg/file-system-access/blob/main/proposals/CloudIdentifier.md

An example JSON file structure for registering a Cloud Storage Provider client with the browser. This file specifies the provider's name, the path to its executable, and the directories it synchronizes.

```json
{
  "name": "com.foo-company.drive",
  "path": "C:\\Program Files\\FooCompany\\cloud_storage_provider_helper.exe",
  "synced_paths": [
    "C:\\path_to_synced_directory\\",
    "C:\\path_to_other_synced_directory\\",
  ]
}
```

--------------------------------

### Specify starting directory using an open file handle

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

When opening a file, use the `startIn` option with an existing file handle to start the picker in the parent directory of that file. This is useful for opening related files.

```javascript
// Used when prompting the user to open a new file, starting out in the
// directory containing a currently open file.
async function openFileFromDirectoryContainingFile(open_file) {
  return await self.showOpenFilePicker({
    startIn: open_file
  });
}
```

--------------------------------

### Accessing System Directories like Fonts

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

This example shows how to access specific system directories, such as the fonts directory, using `FileSystemDirectoryHandle.getSystemDirectory`. This may require user permission.

```javascript
const font_dir = await FileSystemDirectoryHandle.getSystemDirectory({type: 'fonts'});
for await (const entry of font_dir.values()) {
    // Use font entry.
};
```

--------------------------------

### Specify starting directory using a directory handle for open

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Use the `startIn` option with a directory handle to set the initial directory for opening files. This is useful for accessing files within a specific project directory.

```javascript
async function openFileFromDirectory(project_dir) {
  return await self.showOpenFilePicker({
    startIn: project_dir
  });
}
```

--------------------------------

### Specify starting directory for opening a directory

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Use the `startIn` option with a file handle to open the directory containing that file. This is useful for file formats that reference other files within the same directory.

```javascript
// Used for example in a flow where a website wants to prompt the user to open
// the directory containing the currently opened file (for example for file
// formats that contain relative paths to other files in the same directory).
async function openDirectoryContainingFile(open_file) {
  return await self.showDirectoryPicker({
    startIn: open_file
  });
}
```

--------------------------------

### Getting Directory Children: Before vs. After

Source: https://github.com/wicg/file-system-access/blob/main/changes.md

Compares the methods for retrieving files and subdirectories from a parent directory.

```javascript
let file1 = parent.getFile('name');
let file2 = parent.getFile('name2', {create: true});
let dir1 = parent.getDirectory('dir1');
let dir2 = parent.getDirectory('dir2', {create: true});
```

```javascript
let file1 = parent.getFileHandle('name');
let file2 = parent.getFileHandle('name2', {create: true});
let dir1 = parent.getDirectoryHandle('dir1');
let dir2 = parent.getDirectoryHandle('dir2', {create: true});
```

--------------------------------

### Suggest a file name and type for saving

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Use `suggestedName` and `types` to guide the user when saving a file. This helps ensure the file is saved with the correct name and extension.

```javascript
const file_ref = await self.showSaveFilePicker({
  suggestedName: 'README.md',
  types: [{
    description: 'Markdown',
    accept: {
      'text/markdown': ['.md'],
    },
  }],
});
```

--------------------------------

### Specify a well-known starting directory for opening files

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Use string values like 'pictures' with the `startIn` option to specify well-known directories for opening files. This provides a convenient way to access common user directories.

```javascript
const file_ref = await self.showOpenFilePicker({
  startIn: 'pictures'
});
```

--------------------------------

### Specify starting directory using a file handle for save

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

When saving a file, use the `startIn` option with a file handle to set the initial directory. If `suggestedName` is not provided, the name from the file handle will be used.

```javascript
async function saveFileAs(file_handle) {
  return await self.showSaveFilePicker({
    startIn: file_handle
  });
}
```

--------------------------------

### Accessing and Managing a Sandboxed File System

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

This snippet shows how to get access to a private, origin-bound file system using `getSandboxedFileSystem`. It demonstrates creating directories and files within this sandboxed environment.

```javascript
const sandboxed_dir = await self.getSandboxedFileSystem();

// The website can freely create files and directories in this directory.
const cache_dir = await sandboxed_dir.getDirectory('cache', {create: true});
for await (const entry of cache_dir.values()) {
    // Do something with entry.
};

const new_file = await sandboxed_dir.getFile('Untitled 1.txt', {create: true});
const writer = await new_file.createWritable();
writer.write("some data");
await writer.close();
```

--------------------------------

### Access and Iterate Directory Contents

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

Shows how to open a directory picker and then iterate through its contents, accessing individual files or subdirectories. It also demonstrates how to get a specific file or subdirectory reference.

```javascript
const dir_ref = await self.showDirectoryPicker();
if (!dir_ref) {
    // User cancelled, or otherwise failed to open a directory.
    return;
}
// Read directory contents.
for await (const [name, entry] of dir_ref) {
    // entry is a FileSystemFileHandle or a FileSystemDirectoryHandle.
    // name is equal to entry.name
}

// Get a specific file.
const file_ref = await dir_ref.getFile('foo.js');
// Do something useful with the file.

// Get a subdirectory.

```

--------------------------------

### FileSystemFileHandle Interface Definition

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Defines the FileSystemFileHandle interface, which extends FileSystemHandle and provides methods for getting file content, creating writable streams, and accessing synchronous or asynchronous handles.

```webidl
interface FileSystemFileHandle : FileSystemHandle {
  Promise<File> getFile();
  Promise<FileSystemWritableFileStream> createWritable(optional FileSystemCreateWritableOptions options = {});

  Promise<FileSystemAccessHandle> createAccessHandle();
  [Exposed=DedicatedWorker]
  Promise<FileSystemSyncAccessHandle> createSyncAccessHandle();
};
```

--------------------------------

### FileSystemSyncAccessHandle Interface Definition

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Defines the FileSystemSyncAccessHandle interface for synchronous file access, providing methods for reading, writing, truncating, getting size, flushing, and closing the file.

```webidl
[Exposed=DedicatedWorker, SecureContext]
interface FileSystemSyncAccessHandle {
  unsigned long long read([AllowShared] BufferSource buffer,
                             FilesystemReadWriteOptions options);
  unsigned long long write([AllowShared] BufferSource buffer,
                              FilesystemReadWriteOptions options);

  Promise<undefined> truncate([EnforceRange] unsigned long long size);
  Promise<unsigned long long> getSize();
  Promise<undefined> flush();
  Promise<undefined> close();
};
```

--------------------------------

### Resolving Relative Path of a File within a Directory

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

This example demonstrates how to check if a file reference exists within a given directory and retrieve its relative path. It uses `showDirectoryPicker`, `showOpenFilePicker`, and `resolve` methods.

```javascript
// Assume we at some point got a valid directory handle.
const dir_ref = await self.showDirectoryPicker();
if (!dir_ref) return;

// Now get a file reference by showing another file picker:
const file_ref = await self.showOpenFilePicker();
if (!file_ref) {
    // User cancelled, or otherwise failed to open a file.
    return;
}

// Check if file_ref exists inside dir_ref:
const relative_path = await dir_ref.resolve(file_ref);
if (relative_path === null) {
    // Not inside dir_ref
} else {
    // relative_path is an array of names, giving the relative path
    // from dir_ref to the file that is represented by file_ref:
    let entry = dir_ref;
    for (const name of relative_path) {
        entry = await entry.getChild(name);
    }

    // Now |entry| will represent the same file on disk as |file_ref|.
    assert await entry.isSameEntry(file_ref) == true;
}
```

--------------------------------

### FileSystemAccessHandle Interface Definition

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Defines the FileSystemAccessHandle interface for asynchronous file access, including properties for readable and writable streams, and methods for truncating, getting size, flushing, and closing the file.

```webidl
[SecureContext]
interface FileSystemAccessHandle {
  // Assumes seekable streams are available. The
  // Seekable extended attribute is ad-hoc notation for this proposal.
  [Seekable] readonly attribute WritableStream writable;
  [Seekable] readonly attribute ReadableStream readable;

  // Resizes the file to be size bytes long. If size is larger than the current
  // size the file is padded with null bytes, otherwise it is truncated.
  Promise<undefined> truncate([EnforceRange] unsigned long long size);
  // Returns the current size of the file.
  Promise<unsigned long long> getSize();
  // Persists the changes that have been written to disk
  Promise<undefined> flush();
  // Flushes and closes the streams, then releases the lock on the file
  Promise<undefined> close();
};
```

--------------------------------

### Get Cloud Identifiers for a FileHandle

Source: https://github.com/wicg/file-system-access/blob/main/proposals/CloudIdentifier.md

Obtain cloud identifiers for a given FileSystemHandle. Use this to check if a file is synced by a Cloud Storage Provider (CSP) and to retrieve provider-specific IDs for direct API interaction.

```javascript
const [fileHandle] = await window.showOpenFilePicker(pickerOpts);
const cloudIdentifiers = await fileHandle.getCloudIdentifiers();

if(cloudIdentifiers.length === 0) {
  // File is not synced by any CSP
}
for(const cloudIdentifier of cloudIdentifiers) {
  if(cloudIdentifier.providerName === 'drive.google.com') {
    // retrieve/modify the file from Google Drive API using cloudIdentifier.id
  } else if(cloudIdentifier.providerName === 'onedrive.live.com') {
    // retrieve/modify the file from Microsoft OneDrive API using cloudIdentifier.id
  }
}
```

--------------------------------

### showDirectoryPicker with startIn (File Handle for Directory)

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Shows how to use a file handle with `startIn` in `showDirectoryPicker` to prompt the user to open the directory containing the specified file.

```APIDOC
## showDirectoryPicker with startIn (File Handle for Directory)

### Description
Allows prompting the user to select a directory, starting the picker in the directory that contains a given file handle.

### Method
`showDirectoryPicker(options)`

### Parameters
#### Options
- **startIn** (FileSystemHandle) - Optional - A file handle. The picker will start in the parent directory of this file.

### Request Example
```javascript
// Used for example in a flow where a website wants to prompt the user to open
// the directory containing the currently opened file (for example for file
// formats that contain relative paths to other files in the same directory).
async function openDirectoryContainingFile(open_file) {
  return await self.showDirectoryPicker({
    startIn: open_file
  });
}
```
```

--------------------------------

### showOpenFilePicker with startIn (Directory Handle)

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Shows how to use the `startIn` option with a directory handle in `showOpenFilePicker` to set the initial directory for opening files.

```APIDOC
## showOpenFilePicker with startIn (Directory Handle)

### Description
Allows specifying a starting directory for the open file picker using an existing directory handle.

### Method
`showOpenFilePicker(options)`

### Parameters
#### Options
- **startIn** (FileSystemHandle) - Optional - A directory handle. The picker will start in this directory.

### Request Example
```javascript
async function openFileFromDirectory(project_dir) {
  return await self.showOpenFilePicker({
    startIn: project_dir
  });
}
```
```

--------------------------------

### showOpenFilePicker with startIn (File Handle for Directory)

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Demonstrates using a file handle with `startIn` in `showOpenFilePicker` to open files from the directory containing the specified file.

```APIDOC
## showOpenFilePicker with startIn (File Handle for Directory)

### Description
Enables opening files from the directory containing a given file handle by passing the file handle to the `startIn` option.

### Method
`showOpenFilePicker(options)`

### Parameters
#### Options
- **startIn** (FileSystemHandle) - Optional - A file handle. The picker will start in the parent directory of this file.

### Request Example
```javascript
// Used when prompting the user to open a new file, starting out in the
// directory containing a currently open file.
async function openFileFromDirectoryContainingFile(open_file) {
  return await self.showOpenFilePicker({
    startIn: open_file
  });
}
```
```

--------------------------------

### showOpenFilePicker with startIn (Well-known Directory String)

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Demonstrates using a string value for `startIn` in `showOpenFilePicker` to specify a well-known directory like 'pictures'.

```APIDOC
## showOpenFilePicker with startIn (Well-known Directory String)

### Description
Enables specifying a well-known directory as the starting point for the open file picker by passing a predefined string to the `startIn` option.

### Method
`showOpenFilePicker(options)`

### Parameters
#### Options
- **startIn** (string) - Optional - A string representing a well-known directory. Possible values include: 'desktop', 'documents', 'downloads', 'music', 'pictures', 'videos'.

### Request Example
```javascript
const file_ref = await self.showOpenFilePicker({
  startIn: 'pictures'
});
```
```

--------------------------------

### showSaveFilePicker with startIn (File Handle)

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Illustrates using the `startIn` option with a file handle in `showSaveFilePicker`. If `suggestedName` is not provided, the name from the file handle is used.

```APIDOC
## showSaveFilePicker with startIn (File Handle)

### Description
Enables specifying a starting directory for the save file picker using an existing file handle. If no `suggestedName` is provided, the name of the file handle is used as the suggested name.

### Method
`showSaveFilePicker(options)`

### Parameters
#### Options
- **startIn** (FileSystemHandle) - Optional - A file handle. The picker will start in the parent directory of this file.

### Request Example
```javascript
async function saveFileAs(file_handle) {
  return await self.showSaveFilePicker({
    startIn: file_handle
  });
}
```
```

--------------------------------

### Directory Iteration Methods: Before vs. After

Source: https://github.com/wicg/file-system-access/blob/main/changes.md

Demonstrates the different ways to iterate over the contents of a directory.

```javascript
for await (let handle of parent.getEntries()) {
  // Use handle and/or handle.name
}
```

```javascript
for await (let handle of parent.values()) { /* ... */ }
for await (let [name, handle] of parent) { /* ... */ }
for await (let [name, handle] of parent.entries()) { /* ... */ }
for await (let name of parent.keys()) { /* ... */ }
```

--------------------------------

### Specifying Accepted File Types: Before vs. After

Source: https://github.com/wicg/file-system-access/blob/main/changes.md

Illustrates how accepted file types for the file picker were specified in the Origin Trial compared to Chrome M86.

```javascript
await window.chooseFileSystemEntries({
  accepts: [
    {
      description: 'Text Files',
      mimeTypes: ['text/plain', 'text/html'],
      extensions: ['txt', 'text', 'html', 'htm']
    },
    {
      description: 'Images',
      mimeTypes: ['image/*'],
      extensions: ['png', 'gif', 'jpeg', 'jpg']
    }
  ]
});
```

```javascript
await window.showOpenFilePicker({
  types: [
    {
      description: 'Text Files',
      accept: {
        'text/plain': ['.txt', '.text'],
        'text/html': ['.html', '.htm']
      }
    },
    {
      description: 'Images',
      accept: {
        'image/*': ['.png', '.gif', '.jpeg', '.jpg']
      }
    }
  ]
});
```

--------------------------------

### File Picker API Entry Points: Before vs. After

Source: https://github.com/wicg/file-system-access/blob/main/changes.md

Compares the methods used to open files, save files, and select directories before and after Chrome M86.

```javascript
let file1 = await window.chooseFileSystemEntries(
    {type: 'open-file'});
let files = await window.chooseFileSystemEntries(
    {type: 'open-file', multiple: true});
let file2 = await window.chooseFileSystemEntries(
    {type: 'save-file'});
let dir = window.chooseFileSystemEntries(
    {type: 'open-directory'});
```

```javascript
let [file1] = await window.showOpenFilePicker();
let files = await window.showOpenFilePicker({multiple: true});
let file2 = await window.showSaveFilePicker();
let dir = await window.showDirectoryPicker();
```

--------------------------------

### Open and Read/Write a File

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

Opens a file picker for the user to select an image file, then reads and writes to it. It demonstrates creating a writable stream and piping data into it.

```javascript
// Show a file picker to open a file.
const [file_ref] = await self.showOpenFilePicker({
    multiple: false,
    types: [{description: 'Images', accept: {'image/*': ['.jpg', '.gif', '.png']}}],
    suggestedStartLocation: 'pictures-library'
});
if (!file_ref) {
    // User cancelled, or otherwise failed to open a file.
    return;
}

// Read the contents of the file.
const file_reader = new FileReader();
file_reader.onload = async (event) => {
    // File contents will appear in event.target.result.  See
    // https://developer.mozilla.org/en-US/docs/Web/API/FileReader/onload for
    // more info.

    // ...

    // Write changed contents back to the file. Rejects if file reference is not
    // writable. Note that it is not generally possible to know if a file
    // reference is going to be writable without actually trying to write to it.
    // For example, both the underlying filesystem level permissions for the
    // file might have changed, or the user/user agent might have revoked write
    // access for this website to this file after it acquired the file
    // reference.
    const writable = await file_ref.createWritable();
    await writable.write(new Blob(['foobar']));
    await writable.seek(1024);
    await writable.write(new Blob(['bla']));

    // |writable| is also a WritableStream, so you can for example pipe into it.
    let response = await fetch('foo');
    await response.body.pipeTo(writable);

    // pipeTo by default closes the destination pipe, otherwise an explicit
    // writable.close() call would have been needed to persist the written data.
};

// file_ref.file() method will reject if site (no longer) has access to the
// file.
let file = await file_ref.file();

// readAsArrayBuffer() is async and returns immediately.  |file_reader|'s onload
// handler will be called with the result of the file read.
file_reader.readAsArrayBuffer(file);
```

--------------------------------

### Permission Query/Request: Read-Write Mode

Source: https://github.com/wicg/file-system-access/blob/main/changes.md

Illustrates how to query and request read-write permissions for a file system handle.

```javascript
await handle.queryPermission({writable: true});
await handle.requestPermission({writable: true});
```

```javascript
await handle.queryPermission({mode: 'readwrite'});
await handle.requestPermission({mode: 'readwrite'});
```

--------------------------------

### Asynchronous and Synchronous AccessHandle Creation and Operations

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Demonstrates how to create and use both asynchronous and synchronous AccessHandles. The asynchronous version is available in all contexts, while the synchronous version is restricted to worker contexts. Assumes seekable streams and SharedArrayBuffer support.

```javascript
const accessHandle = await fileHandle.createAccessHandle();
await accessHandle.writable.getWriter().write(buffer);
const reader = accessHandle.readable.getReader({ mode: "byob" });
// Assumes seekable streams, and SharedArrayBuffer support are available
await reader.read(buffer, { at: 1 });

// Only in a worker context
const accessHandle = await fileHandle.createSyncAccessHandle();
const writtenBytes = accessHandle.write(buffer);
const readBytes = accessHandle.read(buffer, { at: 1 });
```

--------------------------------

### Pass FileSystemFileHandle via postMessage

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

Illustrates how to pass a FileSystemFileHandle between different contexts, such as from a service worker to a web page, using the `postMessage` API.

```javascript
// In a service worker:
self.addEventListener('some-hypothetical-launch-event', async (e) => {
  // e.file is a FileSystemFileHandle representing the file this SW was launched with.
  let win = await clients.openWindow('bla.html');
  if (win)
    win.postMessage({openFile: e.file});
});

// In bla.html
avigator.serviceWorker.addEventListener('message', e => {
  let file_ref = e.openFile;
  // Do something useful with the file reference.
});
```

--------------------------------

### Permission Query/Request: Read-Only Mode

Source: https://github.com/wicg/file-system-access/blob/main/changes.md

Shows how to query and request read-only permissions for a file system handle.

```javascript
await handle.queryPermission();
await handle.queryPermission({writable: false});
await handle.requestPermission();
await handle.requestPermission({writable: false});
```

```javascript
await handle.queryPermission({mode: 'read'});
await handle.requestPermission({mode: 'read'});
```

--------------------------------

### Determining Handle Type: Before vs. After

Source: https://github.com/wicg/file-system-access/blob/main/changes.md

Shows the change in how to determine if a file system handle refers to a file or a directory.

```javascript
if (handle.isFile) {
  // handle is a file
} else if (handle.isDirectory) {
  // handle is a directory
} else {
  // can't happen
}
```

```javascript
switch (handle.kind) {
  case 'file':
    // handle is a file
    break;
  case 'directory':
    // handle is a directory
    break;
  default:
    // can't happen
}
```

--------------------------------

### Simulate File Download with Window Location

Source: https://github.com/wicg/file-system-access/blob/main/README.md

This workaround uses the window.location to trigger a file download. It's a simpler alternative for 'save as' functionality when dealing with data streams.

```javascript
window.location = 'data:application/octet-stream' + data_stream;
```

--------------------------------

### Simulate File Download with Anchor Element

Source: https://github.com/wicg/file-system-access/blob/main/README.md

This workaround demonstrates how to simulate a file download using a fake anchor element. It's useful for creating a 'save as' experience in browsers that don't fully support the File System Access API.

```javascript
var a = document.createElement('a');
a.download = 'file.txt';
a.href = URL.createObjectURL(blob);
a.click();
URL.revokeObjectURL(a.href);
```

--------------------------------

### showSaveFilePicker with suggestedName

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Demonstrates how to use the `showSaveFilePicker` method with the `suggestedName` option to propose a default file name and `types` for the file picker.

```APIDOC
## showSaveFilePicker with suggestedName

### Description
Allows websites to suggest a default file name and specify file types when invoking the save file picker.

### Method
`showSaveFilePicker(options)`

### Parameters
#### Options
- **suggestedName** (string) - Optional - The suggested file name to be displayed in the save file picker.
- **types** (Array<object>) - Optional - An array of objects, where each object defines a file type with a description and accepted MIME types and extensions.
  - **description** (string) - Description of the file type.
  - **accept** (object) - An object mapping MIME types to an array of file extensions.

### Request Example
```javascript
const file_ref = await self.showSaveFilePicker({
  suggestedName: 'README.md',
  types: [{
    description: 'Markdown',
    accept: {
      'text/markdown': ['.md'],
    },
  }],
});
```
```

--------------------------------

### Copying a File using Read and Write APIs

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

This snippet shows how to copy a file by reading its content and writing it to a new file. It uses `getFile` and `createWritable` methods.

```javascript
const subdir = await dir_ref.getDirectory('bla', {create: true});

// No special API to create copies, but still possible to do so by using
// available read and write APIs.
const new_file = await dir_ref.getFile('new_name', {create: true});
const new_file_writer = await new_file.createWritable();
await new_file_writer.write(await file_ref.getFile());
await new_file_writer.close();
```

--------------------------------

### Store and Retrieve File References with IndexedDB

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

Demonstrates saving file references to IndexedDB for persistence across sessions and retrieving them later. It includes requesting permissions before accessing stored handles.

```javascript
// Open a db instance to save file references for later sessions
let db;
let request = indexedDB.open("WritableFilesDemo");
request.onerror = function(e) { console.log(e); }
request.onsuccess = function(e) { db = e.target.result; }

// Show file picker UI.
const [file_ref] = await self.showOpenFilePicker();

if (file_ref) {
    // Save the reference to open the file later.
    let transaction = db.transaction(["filerefs"], "readwrite");
    let request = transaction.objectStore("filerefs").add( file_ref );
    request.onsuccess = function(e) { console.log(e); }

    // Do other useful things with the opened file.
};

// ...

// Retrieve a file you've opened before. Show's no filepicker UI, but can show
// some other permission prompt if the browser so desires.
// The browser can choose when to allow or not allow this open.
let file_id = "123"; // Some logic to determine which file you'd like to open
let transaction = db.transaction(["filerefs"], "readonly");
let request = transaction.objectStore("filerefs").get(file_id);
request.onsuccess = async function(e) {
    let ref = e.result;

    // Permissions for the handle may have expired while the handle was stored
    // in IndexedDB. Before it is safe to use the handle we should request at
    // least read access to the handle again.
    if (await ref.requestPermission() != 'granted') {
      // No longer allowed to access the handle.
      return;
    }

    // Rejects if file is no longer readable, either because it doesn't exist
    // anymore or because the website no longer has permission to read it.
    let file = await ref.file();
    // ... read from file

    // Rejects if file is no longer writable, because the website no longer has
    // permission to write to it.
    let file_writer = await ref.createWritable();
    // ... write to file_writer
}
```

--------------------------------

### showOpenFilePicker with id

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Demonstrates using the `id` option in `showOpenFilePicker` to associate a specific purpose with the file picker, influencing which last-used directory is remembered.

```APIDOC
## showOpenFilePicker with id

### Description
Assigns an identifier to an open file picker invocation, allowing the system to track and recall the last-used directory specific to that `id`.

### Method
`showOpenFilePicker(options)`

### Parameters
#### Options
- **id** (string) - Optional - An identifier for the file picker invocation. Used to maintain separate last-used directories for different purposes.

### Request Example
```javascript
// Picker should start out in the directory `file_ref1` was picked from.
const file_ref3 = await self.showOpenFilePicker({
  id: 'fruit'
});
```
```

--------------------------------

### Origin Private/Sandboxed File System Access

Source: https://github.com/wicg/file-system-access/blob/main/changes.md

Compares the method for accessing the origin private/sandboxed file system.

```javascript
let root = await FileSystemDirectoryHandle.getSystemDirectory(type: 'sandbox');
```

```javascript
let root = await navigator.storage.getDirectory();
```

--------------------------------

### FileSystemFileHandle Interface

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Methods available on the FileSystemFileHandle interface for file operations.

```APIDOC
## FileSystemFileHandle

### Description
Provides methods to interact with a file, such as retrieving its content, creating a writable stream, or obtaining access handles for synchronous or asynchronous operations.

### Methods

- **getFile()**: Returns a Promise that resolves with a File object representing the file's current content.
- **createWritable(optional FileSystemCreateWritableOptions options = {})**: Returns a Promise that resolves with a FileSystemWritableFileStream, allowing for writing to the file. Options can specify initial settings for the stream.
- **createAccessHandle()**: Returns a Promise that resolves with a FileSystemAccessHandle, providing access to the file's readable and writable streams and methods for truncation, size retrieval, flushing, and closing.
- **createSyncAccessHandle()**: Returns a Promise that resolves with a FileSystemSyncAccessHandle, enabling synchronous read, write, truncate, getSize, flush, and close operations on the file. This method is exposed on DedicatedWorker.
```

--------------------------------

### FilesystemReadWriteOptions Dictionary

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Options for read and write operations on FileSystemSyncAccessHandle.

```APIDOC
## FilesystemReadWriteOptions

### Description
Dictionary specifying options for read and write operations.

### Fields

- **at** (unsigned long long): Required. The byte offset within the file at which to start the read or write operation.
```

--------------------------------

### Exclusive Write Lock Demonstration

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Illustrates how creating an AccessHandle acquires an exclusive write lock, preventing other access handles or WritableFileStreams from being created. The lock is released upon closing the handle.

```javascript
const accessHandle1 = await fileHandle.createAccessHandle();
try {
  const accessHandle2 = await fileHandle.createAccessHandle();
} catch (e) {
  // This catch will always be executed, since there is an open access handle
}
await accessHandle1.close();
// Now a new access handle may be created
```

--------------------------------

### FileSystemSyncAccessHandle Interface

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Interface for synchronous read and write operations on a file.

```APIDOC
## FileSystemSyncAccessHandle

### Description
Enables synchronous read and write operations on a file, suitable for use in dedicated workers.

### Methods

- **read(buffer: BufferSource, options: FilesystemReadWriteOptions)**: Reads data from the file into the provided `buffer`. Returns the number of bytes read.
- **write(buffer: BufferSource, options: FilesystemReadWriteOptions)**: Writes data from the `buffer` to the file. Returns the number of bytes written.
- **truncate(size: unsigned long long)**: Resizes the file to the specified size in bytes. Pads with null bytes if `size` is larger than the current size, or truncates if smaller.
- **getSize()**: Returns the current size of the file in bytes.
- **flush()**: Persists any changes that have been written to disk.
- **close()**: Flushes and closes the file, releasing the lock.
```

--------------------------------

### FileSystemAccessHandle Interface

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Interface for asynchronous access to file streams and control operations.

```APIDOC
## FileSystemAccessHandle

### Description
Provides asynchronous access to a file's readable and writable streams, along with methods to manage the file's size and state.

### Properties

- **writable** (WritableStream): A seekable stream for writing data to the file.
- **readable** (ReadableStream): A seekable stream for reading data from the file.

### Methods

- **truncate(size: unsigned long long)**: Resizes the file to the specified size in bytes. Pads with null bytes if `size` is larger than the current size, or truncates if smaller.
- **getSize()**: Returns a Promise that resolves with the current size of the file in bytes.
- **flush()**: Persists any changes that have been written to disk.
- **close()**: Flushes and closes the associated streams, then releases the lock on the file.
```

--------------------------------

### Copying a File using Streams

Source: https://github.com/wicg/file-system-access/blob/main/EXPLAINER.md

An alternative method for copying files using streams, which can be more efficient for large files. It pipes the file stream directly to a writable stream.

```javascript
// Or using streams:
const copy2 = await dir_ref.getFile('new_name', {create: true});
(await file_ref.getFile()).stream().pipeTo(await copy2.createWritable());
```

--------------------------------

### Web IDL for FileSystemCloudIdentifier and FileSystemHandle

Source: https://github.com/wicg/file-system-access/blob/main/proposals/CloudIdentifier.md

Defines the data structure for cloud identifiers and the method to retrieve them from a FileSystemHandle.

```idl
dictionary FileSystemCloudIdentifier {
  DOMString providerName;
  DOMString id;
};

partial interface FileSystemHandle {
  Promise<FileSystemCloudIdentifier[]> getCloudIdentifiers();
}
```

--------------------------------

### FilesystemReadWriteOptions Dictionary Definition

Source: https://github.com/wicg/file-system-access/blob/main/proposals/AccessHandle.md

Defines the FilesystemReadWriteOptions dictionary, used for specifying the 'at' (offset) parameter in read and write operations for synchronous file access handles.

```webidl
dictionary FilesystemReadWriteOptions {
  [EnforceRange] unsigned long long at;
};
```

--------------------------------

### showSaveFilePicker with id

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Shows how to use the `id` option in `showSaveFilePicker` to distinguish the purpose of different file picker invocations, allowing the system to remember separate last-used directories.

```APIDOC
## showSaveFilePicker with id

### Description
Allows websites to assign an identifier to a file picker invocation. This enables the file picker implementation to remember a separate last-used directory for each unique `id`, distinguishing the purpose of different picker calls.

### Method
`showSaveFilePicker(options)`

### Parameters
#### Options
- **id** (string) - Optional - An identifier for the file picker invocation. Used to maintain separate last-used directories for different purposes.

### Request Example
```javascript
const file_ref1 = await self.showSaveFilePicker({
  id: 'fruit'
});
```
```

--------------------------------

### Add Contributor

Source: https://github.com/wicg/file-system-access/blob/main/CONTRIBUTING.md

Use this format to add a GitHub username as a contributor in a pull request comment. Ensure one username is listed per line.

```text
+@github_username
```

--------------------------------

### Distinguish file picker purposes using an ID

Source: https://github.com/wicg/file-system-access/blob/main/proposals/SuggestedNameAndDir.md

Use the `id` option to differentiate the purpose of file picker invocations. This allows the browser to remember separate last-used directories for different picker types.

```javascript
const file_ref1 = await self.showSaveFilePicker({
  id: 'fruit'
});

const file_ref2 = await self.showSaveFilePicker({
  id: 'flower'
});

// Picker should start out in the directory `file_ref1` was picked from.
const file_ref3 = await self.showOpenFilePicker({
  id: 'fruit'
});
```

--------------------------------

### Remove Contributor

Source: https://github.com/wicg/file-system-access/blob/main/CONTRIBUTING.md

Use this format to remove a GitHub username from the contributor list in a pull request comment. This is also used to remove yourself if you made a mistake or are submitting on behalf of someone else without design input.

```text
-@github_username
```
Tokens:
Raw