From 5885c6c72de0970c0eb264d02808658465bf1cee Mon Sep 17 00:00:00 2001 From: Chris Mills Date: Wed, 2 Aug 2023 15:09:01 +0100 Subject: [PATCH] Add OPFS standalone article / Update API landing to "File System API" (#27440) * Add OPFS standalone article * Multiple small improvements to OPFS-related reference docs * Update files/en-us/web/api/file_system_access_api/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/file_system_access_api/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/file_system_access_api/origin_private_file_system/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/filesystemsyncaccesshandle/write/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/file_system_access_api/origin_private_file_system/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/filesystemwritablefilestream/seek/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/filesystemwritablefilestream/truncate/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/file_system_access_api/origin_private_file_system/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/file_system_access_api/origin_private_file_system/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/file_system_access_api/origin_private_file_system/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/file_system_access_api/origin_private_file_system/index.md Co-authored-by: Thomas Steiner * Update files/en-us/web/api/filesystemsyncaccesshandle/index.md Co-authored-by: Thomas Steiner * Change File System Access API to File System API * Fix a couple more broken links * More broken link fixes * small assorted updates * Fixes made for Rumyra comments --------- Co-authored-by: Thomas Steiner --- files/en-us/_redirects.txt | 5 +- files/en-us/_wikihistory.json | 2 +- .../mozilla/firefox/releases/111/index.md | 2 +- .../getasfilesystemhandle/index.md | 2 +- .../index.md | 33 +-- .../origin_private_file_system/index.md | 194 ++++++++++++++++++ .../entries/index.md | 4 +- .../getdirectoryhandle/index.md | 4 +- .../getfilehandle/index.md | 4 +- .../api/filesystemdirectoryhandle/index.md | 31 ++- .../filesystemdirectoryhandle/keys/index.md | 12 +- .../removeentry/index.md | 4 +- .../resolve/index.md | 4 +- .../filesystemdirectoryhandle/values/index.md | 12 +- .../createsyncaccesshandle/index.md | 8 +- .../createwritable/index.md | 4 +- .../api/filesystemfilehandle/getfile/index.md | 4 +- .../web/api/filesystemfilehandle/index.md | 6 +- files/en-us/web/api/filesystemhandle/index.md | 6 +- .../api/filesystemhandle/issameentry/index.md | 4 +- .../web/api/filesystemhandle/kind/index.md | 4 +- .../web/api/filesystemhandle/name/index.md | 4 +- .../filesystemhandle/querypermission/index.md | 4 +- .../web/api/filesystemhandle/remove/index.md | 6 +- .../requestpermission/index.md | 4 +- .../filesystemsyncaccesshandle/close/index.md | 4 +- .../filesystemsyncaccesshandle/flush/index.md | 4 +- .../getsize/index.md | 4 +- .../api/filesystemsyncaccesshandle/index.md | 10 +- .../filesystemsyncaccesshandle/read/index.md | 8 +- .../truncate/index.md | 4 +- .../filesystemsyncaccesshandle/write/index.md | 14 +- .../api/filesystemwritablefilestream/index.md | 20 +- .../seek/index.md | 46 ++++- .../truncate/index.md | 50 ++++- .../write/index.md | 66 +++--- .../index.md | 16 +- .../api/storagemanager/getdirectory/index.md | 2 +- files/en-us/web/api/storagemanager/index.md | 2 +- .../api/window/showdirectorypicker/index.md | 4 +- .../api/window/showopenfilepicker/index.md | 4 +- .../api/window/showsavefilepicker/index.md | 4 +- .../associate_files_with_your_pwa/index.md | 2 +- files/jsondata/GroupData.json | 6 +- 44 files changed, 453 insertions(+), 184 deletions(-) rename files/en-us/web/api/{file_system_access_api => file_system_api}/index.md (75%) create mode 100644 files/en-us/web/api/file_system_api/origin_private_file_system/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index d0c6215cd0f6cd8..95e6f9feb890af3 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -3458,7 +3458,7 @@ /en-US/docs/Event.initEvent /en-US/docs/Web/API/Event/initEvent /en-US/docs/Extension_Library/Extensions /en-US/docs/Mozilla/Add-ons /en-US/docs/Extension_Library/Extensions/Firefox /en-US/docs/Mozilla/Add-ons -/en-US/docs/File_System_Access_API /en-US/docs/Web/API/File_System_Access_API +/en-US/docs/File_System_Access_API /en-US/docs/Web/API/File_System_API /en-US/docs/Firefox 11 for developers /en-US/docs/Mozilla/Firefox/Releases/11 /en-US/docs/Firefox_1.5 /en-US/docs/Mozilla/Firefox/Releases/1.5 /en-US/docs/Firefox_1.5_Beta_for_Developers /en-US/docs/Mozilla/Firefox/Releases/1.5 @@ -8198,8 +8198,9 @@ /en-US/docs/Web/API/FileSystemFlags/create /en-US/docs/Web/API/FileSystemDirectoryEntry/getFile /en-US/docs/Web/API/FileSystemFlags/exclusive /en-US/docs/Web/API/FileSystemDirectoryEntry/getFile /en-US/docs/Web/API/File_Handle_API /en-US/docs/Web/API/File_and_Directory_Entries_API -/en-US/docs/Web/API/File_System_API /en-US/docs/Web/API/File_and_Directory_Entries_API /en-US/docs/Web/API/File_System_API/Introduction /en-US/docs/Web/API/File_and_Directory_Entries_API/Introduction +/en-US/docs/Web/API/File_System_Access_API /en-US/docs/Web/API/File_System_API +/en-US/docs/Web/API/File_System_Access_API/Origin_private_file_system /en-US/docs/Web/API/File_System_API/Origin_private_file_system /en-US/docs/Web/API/Float32Array /en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array /en-US/docs/Web/API/Float64Array /en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array /en-US/docs/Web/API/FocusEvent.FocusEvent /en-US/docs/Web/API/FocusEvent/FocusEvent diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json index 060aca0bdd91d3c..ffdc5b2df64d6e8 100644 --- a/files/en-us/_wikihistory.json +++ b/files/en-us/_wikihistory.json @@ -36002,7 +36002,7 @@ "sicking" ] }, - "Web/API/File_System_Access_API": { + "Web/API/File_System_API": { "modified": "2020-12-12T15:46:27.214Z", "contributors": ["Rumyra"] }, diff --git a/files/en-us/mozilla/firefox/releases/111/index.md b/files/en-us/mozilla/firefox/releases/111/index.md index 45b62a4563491c1..6f04656f02ac3bd 100644 --- a/files/en-us/mozilla/firefox/releases/111/index.md +++ b/files/en-us/mozilla/firefox/releases/111/index.md @@ -37,7 +37,7 @@ No notable changes. ### APIs -- [Origin private file system (OPFS)](/en-US/docs/Web/API/File_System_Access_API#origin_private_file_system) is now supported when using the [File System Access API](/en-US/docs/Web/API/File_System_Access_API). +- [Origin private file system (OPFS)](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) is now supported when using the [File System API](/en-US/docs/Web/API/File_System_API). The data in this file system is origin-specific: permission prompts are not required to access files, and clearing data for the site/origin deletes the storage. The OPFS is accessed with the {{domxref("StorageManager.getDirectory()")}} method, by calling `navigator.storage.getDirectory()` in a worker or the main thread. See [Firefox bug 1785123](https://bugzil.la/1785123) for more details. diff --git a/files/en-us/web/api/datatransferitem/getasfilesystemhandle/index.md b/files/en-us/web/api/datatransferitem/getasfilesystemhandle/index.md index 6981f71c3757c58..6626d659ec80cd2 100644 --- a/files/en-us/web/api/datatransferitem/getasfilesystemhandle/index.md +++ b/files/en-us/web/api/datatransferitem/getasfilesystemhandle/index.md @@ -72,5 +72,5 @@ elem.addEventListener("drop", async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/file_system_access_api/index.md b/files/en-us/web/api/file_system_api/index.md similarity index 75% rename from files/en-us/web/api/file_system_access_api/index.md rename to files/en-us/web/api/file_system_api/index.md index 2f8b3b2f3b5033a..eb106d94c72880a 100644 --- a/files/en-us/web/api/file_system_access_api/index.md +++ b/files/en-us/web/api/file_system_api/index.md @@ -1,15 +1,15 @@ --- -title: File System Access API -slug: Web/API/File_System_Access_API +title: File System API +slug: Web/API/File_System_API page-type: web-api-overview browser-compat: - api.FileSystemHandle - api.FileSystemFileHandle --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}} +{{securecontext_header}}{{DefaultAPISidebar("File System API")}} -The File System Access API allows read, write and file management capabilities. +The File System API — with extensions provided via the [File System Access API](https://wicg.github.io/file-system-access/) to access files on the device file system — allows read, write and file management capabilities. ## Concepts and Usage @@ -24,7 +24,7 @@ You can also gain access to file handles via: - The {{domxref('DataTransferItem.getAsFileSystemHandle()')}} method of the {{domxref('HTML Drag and Drop API', 'HTML Drag and Drop API', '', 'nocode')}}. - The [File Handling API](https://developer.chrome.com/en/articles/file-handling/). -Each handle provides its own functionality and there are a few differences depending on which one you are using (see the [interfaces](#interfaces) section for specific details). You then can access file data, or information (including children) of the directory selected. This API opens up potential functionality the web has been lacking. Still, security has been of utmost concern when designing the API, and access to file/directory data is disallowed unless the user specifically permits it. +Each handle provides its own functionality and there are a few differences depending on which one you are using (see the [interfaces](#interfaces) section for specific details). You then can access file data, or information (including children) of the directory selected. This API opens up potential functionality the web has been lacking. Still, security has been of utmost concern when designing the API, and access to file/directory data is disallowed unless the user specifically permits it (note that this is not the case with the [Origin private file system](#origin_private_file_system), because it is not visible to the user). > **Note:** The different exceptions that can be thrown when using the features of this API are listed on relevant pages as defined in the spec. However, the situation is made more complex by the interaction of the API and the underlying operating system. A proposal has been made to [list the error mappings in the spec](https://github.com/whatwg/fs/issues/57), which includes useful related information. @@ -32,28 +32,12 @@ Each handle provides its own functionality and there are a few differences depen ### Origin private file system -The [origin private file system (OPFS)](https://fs.spec.whatwg.org/#origin-private-file-system) is a storage endpoint private to the origin of the page, providing optional access to a special kind of file that is highly optimized for performance, for example, by offering in-place and exclusive write access to a file's content. +The origin private file system (OPFS) is a storage endpoint provided as part of the File System API, which is private to the origin of the page and not visible to the user like the regular file system. It provides access to a special kind of file that is highly optimized for performance and offers in-place write access to its content. -Storing data in the OPFS is similar to storing data in any other browser-provided storage mechanism that's private to the origin of the page (for example the {{domxref("IndexedDB API", "IndexedDB API", "", "nocode")}}). This means that files in the OPFS differ from files selected using a picker in the following ways: - -- Permission prompts are not required to access files in the OPFS. -- Clearing data for the site deletes the OPFS. -- The OPFS is subject to browser quota restrictions. - -Files can be manipulated inside the OPFS via a three-step process: - -1. The {{domxref("StorageManager.getDirectory()")}} method, which is obtained using [`navigator.storage.getDirectory()`](/en-US/docs/Web/API/Navigator/storage) in a worker or the main thread, returns a reference to a {{domxref("FileSystemDirectoryHandle")}} object allowing access to a directory and its contents — this represents the root of the OPFS. -2. The {{domxref("FileSystemDirectoryHandle.getFileHandle()")}} method is invoked to return a {{domxref('FileSystemFileHandle')}} object representing a handle to a specific file in the directory. -3. The {{domxref('FileSystemFileHandle.createSyncAccessHandle', 'createSyncAccessHandle()')}} method is invoked on that file handle, and returns a {{domxref('FileSystemSyncAccessHandle')}} object that can be used to read and write to the file. This is a high-performance handle for _synchronous_ read/write operations (the other handle types are asynchronous). The synchronous nature of this class brings performance advantages intended for use in contexts where asynchronous operations come with high overhead (for example, [WebAssembly](/en-US/docs/WebAssembly)). Note that it is only usable inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API). - -While browsers typically implement this by persisting the contents of the OPFS to disk somewhere, it is not intended that the contents be easily user-accessible. While the browser might make it seem that there are files, they might be stored in a database or any other data structure. You cannot expect to find the created files matched one-to-one somewhere on the hard disk. - -> **Note:** Writes performed using {{domxref('FileSystemSyncAccessHandle.write()')}} are in-place, meaning that changes are written to the actual underlying file at the same time as they are written to the writer. This is not the case with other writing mechanisms available in this API (e.g. {{domxref('FileSystemFileHandle.createWritable()')}}), where changes are not committed to disk until the writing stream is closed. +Read our [Origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) for instructions on how to use it. ### Saving files -There is also "save" functionality: - - In the case of the asynchronous handles, use the {{domxref('FileSystemWritableFileStream')}} interface. Once the data you'd like to save is in a format of {{domxref('Blob')}}, {{jsxref("String")}} object, string literal or {{jsxref('ArrayBuffer', 'buffer')}}, you can open a stream and save the data to a file. This can be the existing file or a new file. - In the case of the synchronous {{domxref('FileSystemSyncAccessHandle')}}, you write changes to a file using the {{domxref('FileSystemSyncAccessHandle.write', 'write()')}} method. You can optionally also call {{domxref('FileSystemSyncAccessHandle.flush', 'flush()')}} if you need the changes committed to disk at a specific time (otherwise you can leave the underlying operating system to handle this when it sees fit, which should be OK in most cases). @@ -240,4 +224,5 @@ onmessage = async (e) => { ## See also -- [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) +- [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) on web.dev +- [The origin private file system](https://web.dev/origin-private-file-system/) on web.dev diff --git a/files/en-us/web/api/file_system_api/origin_private_file_system/index.md b/files/en-us/web/api/file_system_api/origin_private_file_system/index.md new file mode 100644 index 000000000000000..46005023cec1ecc --- /dev/null +++ b/files/en-us/web/api/file_system_api/origin_private_file_system/index.md @@ -0,0 +1,194 @@ +--- +title: Origin private file system +slug: Web/API/File_System_API/Origin_private_file_system +page-type: guide +browser-compat: api.StorageManager.getDirectory +--- + +{{securecontext_header}}{{DefaultAPISidebar("File System API")}} + +The origin private file system (OPFS) is a storage endpoint provided as part of the [File System API](/en-US/docs/Web/API/File_System_API), which is private to the origin of the page and not visible to the user like the regular file system. It provides access to a special kind of file that is highly optimized for performance and offers in-place write access to its content. + +## Working with files using the File System Access API + +The [File System Access API](https://wicg.github.io/file-system-access/), which extends the [File System API](/en-US/docs/Web/API/File_System_API), provides access to files using picker methods. For example: + +1. {{domxref("Window.showOpenFilePicker()")}} allows the user to choose a file to access, which results in a {{domxref("FileSystemFileHandle")}} object being returned. +2. {{domxref("FileSystemFileHandle.getFile()")}} is called to get access to the file's contents, the content is modified using {{domxref("FileSystemFileHandle.createWritable()")}} / {{domxref("FileSystemWritableFileStream.write()")}}. +3. {{domxref("FileSystemHandle.requestPermission()", "FileSystemHandle.requestPermission({mode: 'readwrite'})")}} is used to request the user's permission to save the changes. +4. If the user accepts the permission request, the changes are saved back to the original file. + +This works, but it has some restrictions. These changes are being made to the user-visible file system, so there are a lot of security checks in place (for example, [safe browsing](https://developers.google.com/safe-browsing) in Chrome) to guard against malicious content being written to that file system. These writes are not in-place, and instead use a temporary file. The original is not modified unless it passes all the security checks. + +As a result, these operations are fairly slow. It is not so noticeable when you are making small text updates, but the performance suffers when making more significant, large-scale file updates such as [SQLite](https://www.sqlite.org/wasm) database modifications. + +## How does the OPFS solve such problems? + +The OPFS offers low-level, byte-by-byte file access, which is private to the origin of the page and not visible to the user. As a result, it doesn't require the same series of security checks and permission grants and is therefore faster than File System Access API calls. It also has a set of synchronous calls available (other File System API calls are asynchronous) that can be run inside web workers only so as not to block the main thread. + +To summarize how the OPFS differs from the user-visible file system: + +- The OPFS is subject to [browser storage quota restrictions](/en-US/docs/Web/API/Storage_API/Storage_quotas_and_eviction_criteria), just like any other origin-partitioned storage mechanism (for example {{domxref("IndexedDB API", "IndexedDB API", "", "nocode")}}). You can access the amount of storage space the OPFS is using via {{domxref("StorageManager.estimate()", "navigator.storage.estimate()")}}. +- Clearing storage data for the site deletes the OPFS. +- Permission prompts and security checks are not required to access files in the OPFS. +- Browsers persist the contents of the OPFS to disk somewhere, but you cannot expect to find the created files matched one-to-one. The OPFS is not intended to be visible to the user. + +## How do you access the OPFS? + +To access the OPFS in the first place, you call the {{domxref("StorageManager.getDirectory()", "navigator.storage.getDirectory()")}} method. This returns a reference to a {{domxref("FileSystemDirectoryHandle")}} object that represents the root of the OPFS. + +## Manipulating the OPFS from the main thread + +When accessing the OPFS from the main thread, you will use asynchronous, {{jsxref("Promise")}}-based APIs. You can access file ({{domxref("FileSystemFileHandle")}}) and directory ({{domxref("FileSystemDirectoryHandle")}}) handles by calling {{domxref("FileSystemDirectoryHandle.getFileHandle()")}} and {{domxref("FileSystemDirectoryHandle.getDirectoryHandle()")}} respectively on the {{domxref("FileSystemDirectoryHandle")}} object representing the OPFS root (and child directories, as they are created). + +> **Note:** Passing `{ create: true }` into the above methods causes the file or folder to be created if it doesn't exist. + +```js +// Create a hierarchy of files and folders +const fileHandle = await opfsRoot + .getFileHandle('my first file', {create: true}); +const directoryHandle = await opfsRoot + .getDirectoryHandle('my first folder', {create: true}); +const nestedFileHandle = await directoryHandle + .getFileHandle('my first nested file', {create: true}); +const nestedDirectoryHandle = await directoryHandle + .getDirectoryHandle('my first nested folder', {create: true}); + +// Access existing files and folders via their names +const existingFileHandle = await opfsRoot.getFileHandle('my first file'); +const existingDirectoryHandle = await opfsRoot + .getDirectoryHandle('my first folder); +``` + +### Reading a file + +1. Make a {{domxref("FileSystemDirectoryHandle.getFileHandle()")}} call to return a {{domxref("FileSystemFileHandle")}} object. +2. Call the {{domxref("FileSystemFileHandle.getFile()")}} object to return a {{domxref("File")}} object. This is a specialized type of {{domxref("Blob")}}, and as such can be manipulated just like any other `Blob`. For example, you could access the text content directly via {{domxref("Blob.text()")}}. + +### Writing a file + +1. Make a {{domxref("FileSystemDirectoryHandle.getFileHandle()")}} call to return a {{domxref("FileSystemFileHandle")}} object. +2. Call {{domxref("FileSystemFileHandle.createWritable()")}} to return a {{domxref("FileSystemWritableFileStream")}} object, which is a specialized type of {{domxref("WritableStream")}}. +3. Write contents to it using a {{domxref("FileSystemWritableFilestream.write()")}} call. +4. Close the stream using {{domxref("WritableStream.close()")}}. + +### Deleting a file or folder + +You can call {{domxref("FileSystemDirectoryHandle.removeEntry()")}} on the parent directory, passing it the name of the item you want to remove: + +```js +directoryHandle.removeEntry("my first nested file"); +``` + +You can also call {{domxref("FileSystemHandle.remove()")}} on the {{domxref("FileSystemFileHandle")}} or {{domxref("FileSystemDirectoryHandle")}} representing the item you want to remove. To delete a folder including all subfolders, pass the `{ recursive: true }` option. + +```js +await fileHandle.remove(); +await directoryHandle.remove({ recursive: true }); +``` + +The following provides a quick way to clear the entire OPFS: + +```js +await (await navigator.storage.getDirectory()).remove({ recursive: true }); +``` + +### Listing the contents of a folder + +{{domxref("FileSystemDirectoryHandle")}} is an [asynchronous iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols). As such, you can iterate over it with a [`for await…of`](/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of) loop and standard methods such as [`entries()`](/en-US/docs/Web/API/FileSystemDirectoryHandle/entries), [`values()`](/en-US/docs/Web/API/FileSystemDirectoryHandle/entries), and [`keys()`](/en-US/docs/Web/API/FileSystemDirectoryHandle/entries). + +For example: + +```js +for await (let [name, handle] of directoryHandle) { +} +for await (let [name, handle] of directoryHandle.entries()) { +} +for await (let handle of directoryHandle.values()) { +} +for await (let name of directoryHandle.keys()) { +} +``` + +## Manipulating the OPFS from a web worker + +Web Workers don't block the main thread, which means you can use the synchronous file access APIs in this context. Synchronous APIs are faster as they avoid having to deal with promises. + +You can synchronously access a file by calling {{domxref("FileSystemFileHandle.createSyncAccessHandle()")}} on a regular {{domxref("FileSystemFileHandle")}}: + +> **Note:** Despite having "Sync" in its name, the `createSyncAccessHandle()` method itself is asynchronous. + +```js +const opfsRoot = await navigator.storage.getDirectory(); +const fileHandle = await opfsRoot.getFileHandle("my highspeed file.txt", { + create: true, +}); +const syncAccessHandle = await fileHandle.createSyncAccessHandle(); +``` + +There are a number of _synchronous_ methods available on the returned {{domxref("FileSystemSyncAccessHandle")}}: + +- {{domxref("FileSystemSyncAccessHandle.getSize", "getSize()")}}: Returns the size of the file in bytes. +- {{domxref("FileSystemSyncAccessHandle.write", "write()")}}: Writes the content of a buffer into the file, optionally at a given offset, and returns the number of written bytes. Checking the returned number of written bytes allows callers to detect and handle errors and partial writes. +- {{domxref("FileSystemSyncAccessHandle.read", "read()")}}: Reads the contents of the file into a buffer, optionally at a given offset. +- {{domxref("FileSystemSyncAccessHandle.truncate", "truncate()")}}: Resizes the file to the given size. +- {{domxref("FileSystemSyncAccessHandle.flush", "flush()")}}: Ensures that the file contents contain all the modifications done through `write()`. +- {{domxref("FileSystemSyncAccessHandle.close", "close()")}}: Closes the access handle. + +Here is an example that uses all the methods mentioned above: + +```js +const opfsRoot = await navigator.storage.getDirectory(); +const fileHandle = await opfsRoot.getFileHandle("fast", { create: true }); +const accessHandle = await fileHandle.createSyncAccessHandle(); + +const textEncoder = new TextEncoder(); +const textDecoder = new TextDecoder(); + +// Initialize this variable for the size of the file. +let size; +// The current size of the file, initially `0`. +size = accessHandle.getSize(); +// Encode content to write to the file. +const content = textEncoder.encode("Some text"); +// Write the content at the beginning of the file. +accessHandle.write(content, { at: size }); +// Flush the changes. +accessHandle.flush(); +// The current size of the file, now `9` (the length of "Some text"). +size = accessHandle.getSize(); + +// Encode more content to write to the file. +const moreContent = textEncoder.encode("More content"); +// Write the content at the end of the file. +accessHandle.write(moreContent, { at: size }); +// Flush the changes. +accessHandle.flush(); +// The current size of the file, now `21` (the length of +// "Some textMore content"). +size = accessHandle.getSize(); + +// Prepare a data view of the length of the file. +const dataView = new DataView(new ArrayBuffer(size)); + +// Read the entire file into the data view. +accessHandle.read(dataView); +// Logs `"Some textMore content"`. +console.log(textDecoder.decode(dataView)); + +// Read starting at offset 9 into the data view. +accessHandle.read(dataView, { at: 9 }); +// Logs `"More content"`. +console.log(textDecoder.decode(dataView)); + +// Truncate the file after 4 bytes. +accessHandle.truncate(4); +``` + +## Browser compatibility + +{{Compat}} + +## See also + +- [The origin private file system](https://web.dev/origin-private-file-system/) on web.dev diff --git a/files/en-us/web/api/filesystemdirectoryhandle/entries/index.md b/files/en-us/web/api/filesystemdirectoryhandle/entries/index.md index 861704e122c473f..e818db4e7dd0629 100644 --- a/files/en-us/web/api/filesystemdirectoryhandle/entries/index.md +++ b/files/en-us/web/api/filesystemdirectoryhandle/entries/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemDirectoryHandle.entries --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`entries()`** method of the {{domxref("FileSystemDirectoryHandle")}} interface returns an array of a given object's @@ -49,5 +49,5 @@ for await (const [key, value] of dirHandle.entries()) { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemdirectoryhandle/getdirectoryhandle/index.md b/files/en-us/web/api/filesystemdirectoryhandle/getdirectoryhandle/index.md index 88dbfb163bbb61a..2559a7ef884f1ca 100644 --- a/files/en-us/web/api/filesystemdirectoryhandle/getdirectoryhandle/index.md +++ b/files/en-us/web/api/filesystemdirectoryhandle/getdirectoryhandle/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemDirectoryHandle.getDirectoryHandle --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`getDirectoryHandle()`** method of the {{domxref("FileSystemDirectoryHandle")}} interface returns a @@ -71,5 +71,5 @@ const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true }); ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemdirectoryhandle/getfilehandle/index.md b/files/en-us/web/api/filesystemdirectoryhandle/getfilehandle/index.md index 9a9cd03273a9afc..1c07cd4aa0135e1 100644 --- a/files/en-us/web/api/filesystemdirectoryhandle/getfilehandle/index.md +++ b/files/en-us/web/api/filesystemdirectoryhandle/getfilehandle/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemDirectoryHandle.getFileHandle --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`getFileHandle()`** method of the {{domxref("FileSystemDirectoryHandle")}} interface returns a @@ -73,5 +73,5 @@ const fileHandle = currentDirHandle.getFileHandle(fileName, { create: true }); ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemdirectoryhandle/index.md b/files/en-us/web/api/filesystemdirectoryhandle/index.md index 0b262e8e9383582..bba7a76fd48485c 100644 --- a/files/en-us/web/api/filesystemdirectoryhandle/index.md +++ b/files/en-us/web/api/filesystemdirectoryhandle/index.md @@ -5,9 +5,9 @@ page-type: web-api-interface browser-compat: api.FileSystemDirectoryHandle --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} -The **`FileSystemDirectoryHandle`** interface of the {{domxref('File System Access API')}} provides a handle to a file system directory. +The **`FileSystemDirectoryHandle`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} provides a handle to a file system directory. The interface can be accessed via the {{domxref('window.showDirectoryPicker()')}}, {{domxref('StorageManager.getDirectory()')}}, {{domxref('DataTransferItem.getAsFileSystemHandle()')}}, and {{domxref('FileSystemDirectoryHandle.getDirectoryHandle()')}} methods. @@ -21,18 +21,23 @@ _Inherits properties from its parent, {{DOMxRef("FileSystemHandle")}}._ _Inherits methods from its parent, {{DOMxRef("FileSystemHandle")}}._ -- {{domxref('FileSystemDirectoryHandle.entries()')}} - - : Returns a new _async iterator_ of a given object's own enumerable property `[key, value]` pairs -- {{domxref('FileSystemDirectoryHandle.getFileHandle()')}} - - : Returns a {{jsxref('Promise')}} fulfilled with a {{domxref('FileSystemFileHandle')}} for a file with the specified name, within the directory the method is called. +Regular methods: + - {{domxref('FileSystemDirectoryHandle.getDirectoryHandle()')}} - : Returns a {{jsxref('Promise')}} fulfilled with a {{domxref('FileSystemDirectoryHandle')}} for a subdirectory with the specified name within the directory handle on which the method is called. -- {{domxref('FileSystemDirectoryHandle.keys()')}} - - : Returns a new _async iterator_ containing the keys for each item in `FileSystemDirectoryHandle`. +- {{domxref('FileSystemDirectoryHandle.getFileHandle()')}} + - : Returns a {{jsxref('Promise')}} fulfilled with a {{domxref('FileSystemFileHandle')}} for a file with the specified name, within the directory the method is called. - {{domxref('FileSystemDirectoryHandle.removeEntry()')}} - : Attempts to asynchronously remove an entry if the directory handle contains a file or directory called the name specified. - {{domxref('FileSystemDirectoryHandle.resolve()')}} - : Returns a {{jsxref('Promise')}} fulfilled with an {{jsxref('Array')}} of directory names from the parent handle to the specified child entry, with the name of the child entry as the last array item. + +[Asynchronous iterator](/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) methods: + +- {{domxref('FileSystemDirectoryHandle.entries()')}} + - : Returns a new _async iterator_ of a given object's own enumerable property `[key, value]` pairs. +- {{domxref('FileSystemDirectoryHandle.keys()')}} + - : Returns a new _async iterator_ containing the keys for each item in `FileSystemDirectoryHandle`. - {{domxref('FileSystemDirectoryHandle.values()')}} - : Returns a new _async iterator_ containing the values for each index in the `FileSystemDirectoryHandle` object. - [`FileSystemDirectoryHandle[@@asyncIterator]()`](/en-US/docs/Web/API/FileSystemDirectoryHandle/entries) @@ -40,7 +45,9 @@ _Inherits methods from its parent, {{DOMxRef("FileSystemHandle")}}._ ## Examples -The following example returns a directory handle with the specified name, if the directory does not exist it is created. +### Return directory handle + +The following example returns a directory handle with the specified name; if the directory does not already exist it is created. ```js const dirName = "directoryToGetName"; @@ -49,6 +56,8 @@ const dirName = "directoryToGetName"; const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true }); ``` +### Return file path + The following asynchronous function uses `resolve()` to find the path to a chosen file, relative to a specified directory handle. ```js @@ -76,6 +85,8 @@ async function returnPathDirectories(directoryHandle) { } ``` +### Return handles for all files in a directory + The following example scans recursively through a directory to return {{domxref('FileSystemFileHandle')}} objects for each file in that directory: ```js @@ -107,5 +118,5 @@ for await (const fileHandle of getFilesRecursively(directoryHandle)) { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemdirectoryhandle/keys/index.md b/files/en-us/web/api/filesystemdirectoryhandle/keys/index.md index 0b469af7dfe066f..8cfc30ddadeb282 100644 --- a/files/en-us/web/api/filesystemdirectoryhandle/keys/index.md +++ b/files/en-us/web/api/filesystemdirectoryhandle/keys/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemDirectoryHandle.keys --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`keys()`** method of the {{domxref("FileSystemDirectoryHandle")}} interface returns a new _array iterator_ @@ -28,7 +28,13 @@ A new {{jsxref('Array')}} ## Examples -Todo +```js +const dirHandle = await window.showDirectoryPicker(); + +for await (const key of dirHandle.keys()) { + console.log(key); +} +``` ## Specifications @@ -40,5 +46,5 @@ Todo ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemdirectoryhandle/removeentry/index.md b/files/en-us/web/api/filesystemdirectoryhandle/removeentry/index.md index ee2c3bbe0ab9456..cece9dc7c06d82d 100644 --- a/files/en-us/web/api/filesystemdirectoryhandle/removeentry/index.md +++ b/files/en-us/web/api/filesystemdirectoryhandle/removeentry/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemDirectoryHandle.removeEntry --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`removeEntry()`** method of the {{domxref("FileSystemDirectoryHandle")}} interface attempts to remove an entry if the @@ -70,5 +70,5 @@ currentDirHandle.removeEntry(entryName).then(() => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemdirectoryhandle/resolve/index.md b/files/en-us/web/api/filesystemdirectoryhandle/resolve/index.md index 9fd4655d26432d7..b8b2b7061bb2488 100644 --- a/files/en-us/web/api/filesystemdirectoryhandle/resolve/index.md +++ b/files/en-us/web/api/filesystemdirectoryhandle/resolve/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemDirectoryHandle.resolve --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`resolve()`** method of the {{domxref("FileSystemDirectoryHandle")}} interface returns an {{jsxref('Array')}} of @@ -72,5 +72,5 @@ async function returnPathDirectories(directoryHandle) { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemdirectoryhandle/values/index.md b/files/en-us/web/api/filesystemdirectoryhandle/values/index.md index 77228da91149d54..b0fda1d577052b0 100644 --- a/files/en-us/web/api/filesystemdirectoryhandle/values/index.md +++ b/files/en-us/web/api/filesystemdirectoryhandle/values/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemDirectoryHandle.values --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`values()`** method of the {{domxref("FileSystemDirectoryHandle")}} interface returns a new _array iterator_ @@ -29,7 +29,13 @@ A new {{jsxref('Array')}} ## Examples -Todo +```js +const dirHandle = await window.showDirectoryPicker(); + +for await (const value of dirHandle.values()) { + console.log(value); +} +``` ## Specifications @@ -41,5 +47,5 @@ Todo ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md index a992afcc3500f85..510dfc8647fb571 100644 --- a/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createsyncaccesshandle/index.md @@ -6,12 +6,12 @@ page-type: web-api-instance-method browser-compat: api.FileSystemFileHandle.createSyncAccessHandle --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`createSyncAccessHandle()`** method of the {{domxref("FileSystemFileHandle")}} interface returns a {{jsxref('Promise')}} which resolves to a {{domxref('FileSystemSyncAccessHandle')}} object that can be used to synchronously read from and write to a file. The synchronous nature of this method brings performance advantages, -but it is only usable inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) for files within the [origin private file system](/en-US/docs/Web/API/File_System_Access_API#origin_private_file_system). +but it is only usable inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) for files within the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system). Creating a {{domxref('FileSystemSyncAccessHandle')}} takes an exclusive lock on the file associated with the file handle. This prevents the creation of further {{domxref('FileSystemSyncAccessHandle')}}s or {{domxref('FileSystemWritableFileStream')}}s for the file until the existing access handle is closed. @@ -32,7 +32,7 @@ A {{jsxref('Promise')}} which resolves to a {{domxref('FileSystemSyncAccessHandl ### Exceptions - `InvalidStateError` {{domxref("DOMException")}} - - : Thrown if the {{domxref('FileSystemSyncAccessHandle')}} object does not represent a file in the [origin private file system](/en-US/docs/Web/API/File_System_Access_API#origin_private_file_system). + - : Thrown if the {{domxref('FileSystemSyncAccessHandle')}} object does not represent a file in the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system). - `NoModificationAllowedError` {{domxref("DOMException")}} - : Thrown if the browser is not able to acquire a lock on the file associated with the file handle. - `NotAllowedError` {{domxref("DOMException")}} @@ -70,5 +70,5 @@ onmessage = async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemfilehandle/createwritable/index.md b/files/en-us/web/api/filesystemfilehandle/createwritable/index.md index dd9aaeabea95381..e0998f0c4f4b8f3 100644 --- a/files/en-us/web/api/filesystemfilehandle/createwritable/index.md +++ b/files/en-us/web/api/filesystemfilehandle/createwritable/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemFileHandle.createWritable --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`createWritable()`** method of the {{domxref("FileSystemFileHandle")}} interface creates @@ -74,5 +74,5 @@ async function writeFile(fileHandle, contents) { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemfilehandle/getfile/index.md b/files/en-us/web/api/filesystemfilehandle/getfile/index.md index 7fd194becd80965..cccc37540c47760 100644 --- a/files/en-us/web/api/filesystemfilehandle/getfile/index.md +++ b/files/en-us/web/api/filesystemfilehandle/getfile/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemFileHandle.getFile --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`getFile()`** method of the {{domxref("FileSystemFileHandle")}} interface returns a {{jsxref('Promise')}} which resolves to a @@ -60,5 +60,5 @@ async function getTheFile() { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemfilehandle/index.md b/files/en-us/web/api/filesystemfilehandle/index.md index a4c8887c643d8ca..4b86c3253ea6a58 100644 --- a/files/en-us/web/api/filesystemfilehandle/index.md +++ b/files/en-us/web/api/filesystemfilehandle/index.md @@ -5,9 +5,9 @@ page-type: web-api-interface browser-compat: api.FileSystemFileHandle --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} -The **`FileSystemFileHandle`** interface of the {{domxref("File System Access API", "File System Access API", "", "nocode")}} represents a handle to a file system entry. The interface is accessed through the {{domxref('window.showOpenFilePicker()')}} method. +The **`FileSystemFileHandle`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} represents a handle to a file system entry. The interface is accessed through the {{domxref('window.showOpenFilePicker()')}} method. Note that read and write operations depend on file-access permissions that do not persist after a page refresh if no other tabs for that origin remain open. The {{domxref("FileSystemHandle.queryPermission()", "queryPermission")}} method of the {{domxref("FileSystemHandle")}} interface can be used to verify permission state before accessing a file. @@ -130,5 +130,5 @@ onmessage = async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemhandle/index.md b/files/en-us/web/api/filesystemhandle/index.md index a2583a09e8d56a7..d36e9adb8a3fa41 100644 --- a/files/en-us/web/api/filesystemhandle/index.md +++ b/files/en-us/web/api/filesystemhandle/index.md @@ -5,9 +5,9 @@ page-type: web-api-interface browser-compat: api.FileSystemHandle --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} -The **`FileSystemHandle`** interface of the {{domxref('File System Access API')}} is an object which represents a file or directory entry. Multiple handles can represent the same entry. For the most part you do not work with `FileSystemHandle` directly but rather its child interfaces {{domxref('FileSystemFileHandle')}} and {{domxref('FileSystemDirectoryHandle')}}. +The **`FileSystemHandle`** interface of the {{domxref('File System API')}} is an object which represents a file or directory entry. Multiple handles can represent the same entry. For the most part you do not work with `FileSystemHandle` directly but rather its child interfaces {{domxref('FileSystemFileHandle')}} and {{domxref('FileSystemDirectoryHandle')}}. ## Interfaces based on FileSystemHandle @@ -109,5 +109,5 @@ function removeMatches(fileEntry, entriesArr) { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemhandle/issameentry/index.md b/files/en-us/web/api/filesystemhandle/issameentry/index.md index f524c0a8bda0aa9..16f082fd46ec41e 100644 --- a/files/en-us/web/api/filesystemhandle/issameentry/index.md +++ b/files/en-us/web/api/filesystemhandle/issameentry/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemHandle.isSameEntry --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`isSameEntry()`** method of the {{domxref("FileSystemHandle")}} interface compares two {{domxref("FileSystemHandle", @@ -55,5 +55,5 @@ function removeMatches(fileEntry, entriesArr) { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemhandle/kind/index.md b/files/en-us/web/api/filesystemhandle/kind/index.md index 43b778b9b884a5d..d67882714d9c592 100644 --- a/files/en-us/web/api/filesystemhandle/kind/index.md +++ b/files/en-us/web/api/filesystemhandle/kind/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-property browser-compat: api.FileSystemHandle.kind --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`kind`** read-only property of the {{domxref("FileSystemHandle")}} interface returns the type of entry. This is @@ -52,5 +52,5 @@ async function getFile() { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemhandle/name/index.md b/files/en-us/web/api/filesystemhandle/name/index.md index ebfd70ebbe771c0..5ffd75cd77ff6c7 100644 --- a/files/en-us/web/api/filesystemhandle/name/index.md +++ b/files/en-us/web/api/filesystemhandle/name/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-property browser-compat: api.FileSystemHandle.name --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`name`** read-only property of the {{domxref("FileSystemHandle")}} interface returns the name of the entry represented by @@ -43,5 +43,5 @@ async function getFile() { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemhandle/querypermission/index.md b/files/en-us/web/api/filesystemhandle/querypermission/index.md index 4e3276c80192aec..d50514711caa51f 100644 --- a/files/en-us/web/api/filesystemhandle/querypermission/index.md +++ b/files/en-us/web/api/filesystemhandle/querypermission/index.md @@ -8,7 +8,7 @@ status: browser-compat: api.FileSystemHandle.queryPermission --- -{{securecontext_header}}{{APIRef("File System Access API")}}{{SeeCompatTable}} +{{securecontext_header}}{{APIRef("File System API")}}{{SeeCompatTable}} The **`queryPermission()`** method of the {{domxref("FileSystemHandle")}} interface queries the current permission state of the @@ -87,5 +87,5 @@ async function verifyPermission(fileHandle, withWrite) { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemhandle/remove/index.md b/files/en-us/web/api/filesystemhandle/remove/index.md index 4935d572e238ac9..999981d6599bd00 100644 --- a/files/en-us/web/api/filesystemhandle/remove/index.md +++ b/files/en-us/web/api/filesystemhandle/remove/index.md @@ -9,13 +9,13 @@ status: browser-compat: api.FileSystemHandle.remove --- -{{securecontext_header}}{{APIRef("File System Access API")}}{{SeeCompatTable}}{{Non-standard_header}} +{{securecontext_header}}{{APIRef("File System API")}}{{SeeCompatTable}}{{Non-standard_header}} The **`remove()`** method of the {{domxref("FileSystemHandle")}} interface requests removal of the entry represented by the handle from the underlying file system. The `remove()` method allows you to remove a file or directory directly from its handle. Without this method, you would have to obtain the handle of the parent directory, then call {{domxref("FileSystemDirectoryHandle.removeEntry()")}} on that to remove it. -You can also call `remove()` on the root directory of the [Origin Private File System](/en-US/docs/Web/API/File_System_Access_API#origin_private_file_system) to clear its contents, after which a new empty OPFS is created. +You can also call `remove()` on the root directory of the [Origin Private File System](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) to clear its contents, after which a new empty OPFS is created. ## Syntax @@ -91,5 +91,5 @@ Walking through this: ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [FileSystemHandle.remove() demo](https://filesystemhandle-remove.glitch.me/) diff --git a/files/en-us/web/api/filesystemhandle/requestpermission/index.md b/files/en-us/web/api/filesystemhandle/requestpermission/index.md index 4099c1caf755f56..8da9b4df09b500b 100644 --- a/files/en-us/web/api/filesystemhandle/requestpermission/index.md +++ b/files/en-us/web/api/filesystemhandle/requestpermission/index.md @@ -8,7 +8,7 @@ status: browser-compat: api.FileSystemHandle.requestPermission --- -{{securecontext_header}}{{APIRef("File System Access API")}}{{SeeCompatTable}} +{{securecontext_header}}{{APIRef("File System API")}}{{SeeCompatTable}} The **`requestPermission()`** method of the {{domxref("FileSystemHandle")}} interface requests read or readwrite permissions for the @@ -79,5 +79,5 @@ async function verifyPermission(fileHandle, withWrite) { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md index f8fdb25f637ba2b..ae38c662768b1ed 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/close/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemSyncAccessHandle.close --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`close()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface closes an open synchronous file handle, disabling any further operations on it and releasing the exclusive lock previously put on the file associated with the file handle. @@ -81,5 +81,5 @@ onmessage = async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md index 709d508cc46e883..e0858782a54ad66 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/flush/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemSyncAccessHandle.flush --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`flush()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface persists any changes made to the file associated with the handle via the {{domxref('FileSystemSyncAccessHandle.write', 'write()')}} method to disk. @@ -83,5 +83,5 @@ onmessage = async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md index f04c2c3508a8798..90c76eb8f6a39a2 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/getsize/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemSyncAccessHandle.getSize --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`getSize()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface returns the size of the file associated with the handle in bytes. @@ -82,5 +82,5 @@ onmessage = async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/index.md index 46a6096f771b9c5..0303b85b4faf609 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/index.md @@ -5,11 +5,13 @@ page-type: web-api-interface browser-compat: api.FileSystemSyncAccessHandle --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} -The **`FileSystemSyncAccessHandle`** interface of the {{domxref("File System Access API", "File System Access API", "", "nocode")}} represents a synchronous handle to a file system entry. The synchronous nature of the file reads and writes allows for higher performance for critical methods in contexts where asynchronous operations come with high overhead, e.g., [WebAssembly](/en-US/docs/WebAssembly). +The **`FileSystemSyncAccessHandle`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} represents a synchronous handle to a file system entry. -This class is only accessible inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) for files within the [origin private file system](/en-US/docs/Web/API/File_System_Access_API#origin_private_file_system). +This class is only accessible inside dedicated [Web Workers](/en-US/docs/Web/API/Web_Workers_API) (so that its methods do not block execution on the main thread) for files within the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system), which is not visible to end-users. + +As a result, its methods are not subject to the same security checks as methods running on files within the user-visible file system, and so are much more performant. This makes them suitable for significant, large-scale file updates such as [SQLite](https://www.sqlite.org/wasm) database modifications. The interface is accessed through the {{domxref('FileSystemFileHandle.createSyncAccessHandle()')}} method. @@ -86,5 +88,5 @@ onmessage = async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md index 7a6a5f03b20aeb0..e9e58470c02a0cd 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/read/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemSyncAccessHandle.read --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`read()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface reads the content of the file associated with the handle into a specified buffer, optionally at a given offset. @@ -14,14 +14,14 @@ The **`read()`** method of the ## Syntax ```js-nolint -read(buffer, FileSystemReadWriteOptions) +read(buffer, options) ``` ### Parameters - `buffer` - : An {{jsxref("ArrayBuffer")}} or `ArrayBufferView` (such as a {{jsxref("DataView")}}) representing the buffer that the file content should be read into. Note that you cannot directly manipulate the contents of an `ArrayBuffer`. Instead, you create one of the typed array objects like an {{jsxref("Int8Array")}} or a {{jsxref("DataView")}} object which represents the buffer in a specific format, and use that to read and write the contents of the buffer. -- `FileSystemReadWriteOptions` {{optional_inline}} +- `options` {{optional_inline}} - : An options object containing the following properties: @@ -89,5 +89,5 @@ onmessage = async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md index cc00bf86ddd314e..90175304098db7f 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/truncate/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemSyncAccessHandle.truncate --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`truncate()`** method of the {{domxref("FileSystemSyncAccessHandle")}} interface resizes the file associated with the handle to a specified number of bytes. @@ -66,5 +66,5 @@ async function truncateFile() { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md index 35e723dfbe37304..29745575b9f366f 100644 --- a/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md +++ b/files/en-us/web/api/filesystemsyncaccesshandle/write/index.md @@ -6,28 +6,30 @@ page-type: web-api-instance-method browser-compat: api.FileSystemSyncAccessHandle.write --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`write()`** method of the -{{domxref("FileSystemSyncAccessHandle")}} interface writes the content of a specified buffer to the file associated with the handle, optionally at a given offset. Note that you cannot directly manipulate the contents of an `ArrayBuffer`. Instead, you create one of the typed array objects like an {{jsxref("Int8Array")}} or a {{jsxref("DataView")}} object which represents the buffer in a specific format, and use that to read and write the contents of the buffer. +{{domxref("FileSystemSyncAccessHandle")}} interface writes the content of a specified buffer to the file associated with the handle, optionally at a given offset. -Writes performed using {{domxref('FileSystemSyncAccessHandle.write()')}} are in-place, meaning that changes are written to the actual underlying file at the same time as they are written to the writer. This is not the case with other writing mechanisms available in the {{domxref("File System Access API", "File System Access API", "", "nocode")}} (e.g. {{domxref('FileSystemFileHandle.createWritable()')}}), where changes are not committed to disk until the writing stream is closed. +Files within the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) are not visible to end-users, therefore are not subject to the same security checks as methods running on files within the user-visible file system. As a result, writes performed using {{domxref('FileSystemSyncAccessHandle.write()')}} are much more performant. This makes them suitable for significant, large-scale file updates such as [SQLite](https://www.sqlite.org/wasm) database modifications. ## Syntax ```js-nolint -write(buffer, FileSystemReadWriteOptions) +write(buffer, options) ``` ### Parameters - `buffer` - : An {{jsxref("ArrayBuffer")}} or `ArrayBufferView` (such as a {{jsxref("DataView")}}) representing the buffer to be written to the file. -- `FileSystemReadWriteOptions` {{optional_inline}} +- `options` {{optional_inline}} - : An options object containing the following properties: - `at` - : A number representing the offset in bytes from the start of the file that the buffer should be written at. +> **Note:** You cannot directly manipulate the contents of an `ArrayBuffer`. Instead, you create a typed array object like an {{jsxref("Int8Array")}} or a {{jsxref("DataView")}} object, which represents the buffer in a specific format, and use that to read and write the contents of the buffer. + ### Return value A number representing the number of bytes written to the file. @@ -89,5 +91,5 @@ onmessage = async (e) => { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemwritablefilestream/index.md b/files/en-us/web/api/filesystemwritablefilestream/index.md index 61fe6ccd478b268..480d57d7d6de214 100644 --- a/files/en-us/web/api/filesystemwritablefilestream/index.md +++ b/files/en-us/web/api/filesystemwritablefilestream/index.md @@ -5,9 +5,9 @@ page-type: web-api-interface browser-compat: api.FileSystemWritableFileStream --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} -The **`FileSystemWritableFileStream`** interface of the {{domxref('File System Access API')}} is a {{domxref('WritableStream')}} object with additional convenience methods, which operates on a single file on disk. The interface is accessed through the {{domxref('FileSystemFileHandle.createWritable()')}} method. +The **`FileSystemWritableFileStream`** interface of the {{domxref("File System API", "File System API", "", "nocode")}} is a {{domxref('WritableStream')}} object with additional convenience methods, which operates on a single file on disk. The interface is accessed through the {{domxref('FileSystemFileHandle.createWritable()')}} method. {{InheritanceDiagram}} @@ -19,18 +19,18 @@ _Inherits properties from its parent, {{DOMxRef("WritableStream")}}._ _Inherits methods from its parent, {{DOMxRef("WritableStream")}}._ -- {{domxref('FileSystemWritableFileStream.write')}} +- {{domxref('FileSystemWritableFileStream.write()')}} - : Writes content into the file the method is called on, at the current file cursor offset. -- {{domxref('FileSystemWritableFileStream.seek')}} +- {{domxref('FileSystemWritableFileStream.seek()')}} - : Updates the current file cursor offset to the position (in bytes) specified. -- {{domxref('FileSystemWritableFileStream.truncate')}} +- {{domxref('FileSystemWritableFileStream.truncate()')}} - : Resizes the file associated with the stream to be the specified size in bytes. ## Examples -This asynchronous function opens the 'Save File' picker, which returns a {{domxref('FileSystemFileHandle')}} once a file is selected. From which a writable stream is then created using the {{domxref('FileSystemFileHandle.createWritable()')}} method. +The following asynchronous function opens the 'Save File' picker, which returns a {{domxref('FileSystemFileHandle')}} once a file is selected. From this, a writable stream is created using the {{domxref('FileSystemFileHandle.createWritable()')}} method. -A user defined {{domxref('Blob')}} is then written to the stream which is subsequently closed. +A text string is then written to the stream, which is subsequently closed. ```js async function saveFile() { @@ -41,14 +41,14 @@ async function saveFile() { const writableStream = await newHandle.createWritable(); // write our file - await writableStream.write(imgBlob); + await writableStream.write("This is my file content"); // close the file and write the contents to disk. await writableStream.close(); } ``` -The following show different examples of options that can be passed into the `write()` method. +The following examples show different options that can be passed into the `write()` method. ```js // just pass in the data (no options) @@ -74,5 +74,5 @@ writableStream.write({ type: "truncate", size }); ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemwritablefilestream/seek/index.md b/files/en-us/web/api/filesystemwritablefilestream/seek/index.md index 3a3633320c40911..8342aa12fbdc71d 100644 --- a/files/en-us/web/api/filesystemwritablefilestream/seek/index.md +++ b/files/en-us/web/api/filesystemwritablefilestream/seek/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemWritableFileStream.seek --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`seek()`** method of the {{domxref("FileSystemWritableFileStream")}} interface updates the current file cursor offset to the position (in bytes) specified when calling the method. @@ -19,22 +19,54 @@ seek(position) ### Parameters - `position` - - : An unsigned long describing the byte position from the top (beginning) of the file. + - : A number specifying the byte position from the beginning of the file. ### Return value -{{jsxref('Promise')}} which returns undefined. +A {{jsxref('Promise')}} that returns `undefined`. ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : If the {{domxref('PermissionStatus.state')}} is not 'granted'. + - : Returned if {{domxref('PermissionStatus.state')}} is not `granted`. - {{jsxref("TypeError")}} - - : If `position` is not defined or of type unsigned long. + - : Returned if `position` is not a number or not defined. ## Examples -Todo +The following asynchronous function opens the 'Save File' picker, which returns a {{domxref('FileSystemFileHandle')}} once a file is selected. From this, a writable stream is created using the {{domxref('FileSystemFileHandle.createWritable()')}} method. + +Next, we write to the stream: + +1. A text string is written to the stream. +2. The `seek()` method is used to put the cursor at the start of the stream. +3. A second text string is written to the start of the stream, overwriting the first write. + +The stream is then closed. + +```js +async function saveFile() { + try { + // create a new handle + const newHandle = await window.showSaveFilePicker(); + + // create a FileSystemWritableFileStream to write to + const writableStream = await newHandle.createWritable(); + + // write our file + await writableStream.write("My first file content"); + await writableStream.seek(0); + await writableStream.write("My second file content"); + + // close the file and write the contents to disk. + await writableStream.close(); + } catch (err) { + console.error(err.name, err.message); + } +} +``` + +If you run the above function and then open the resulting file created on disk, you should see the text "My second file content". ## Specifications @@ -46,5 +78,5 @@ Todo ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemwritablefilestream/truncate/index.md b/files/en-us/web/api/filesystemwritablefilestream/truncate/index.md index d801394051de678..cd59ea42a7b567c 100644 --- a/files/en-us/web/api/filesystemwritablefilestream/truncate/index.md +++ b/files/en-us/web/api/filesystemwritablefilestream/truncate/index.md @@ -6,11 +6,11 @@ page-type: web-api-instance-method browser-compat: api.FileSystemWritableFileStream.truncate --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} -The **`truncate()`** method of the {{domxref("FileSystemWritableFileStream")}} interface resizes the file associated with the stream to be the specified size in bytes. +The **`truncate()`** method of the {{domxref("FileSystemWritableFileStream")}} interface resizes the file associated with the stream to the specified size in bytes. -If the size specified is larger than the current file size this pads the file with `null` bytes, otherwise it truncates the file. +If the size specified is larger than the current file size the file is padded with `null` bytes. The file cursor is also updated when `truncate()` is called. If the offset is smaller than the size, it remains unchanged. @@ -23,31 +23,61 @@ Changes are typically written to a temporary file instead. ## Syntax ```js-nolint -truncate() +truncate(size) ``` ### Parameters - size - - : An `unsigned long` of the amount of bytes to resize the stream to. + - : A number specifying the number of bytes to resize the stream to. ### Return value -A {{jsxref('Promise')}} which returns undefined. +A {{jsxref('Promise')}} that returns `undefined`. ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : If the {{domxref('PermissionState')}} is not 'granted'. + - : Returned if {{domxref('PermissionStatus.state')}} is not `granted`. - {{jsxref("TypeError")}} - - : If the size is undefined or not an unsigned long. + - : Returned if `size` is not a number or not defined. ## Examples +The following asynchronous function opens the 'Save File' picker, which returns a {{domxref('FileSystemFileHandle')}} once a file is selected. From this, a writable stream is created using the {{domxref('FileSystemFileHandle.createWritable()')}} method. + +Next, we write to the stream: + +1. A text string is written to the stream. +2. The `truncate()` method is used to resize the file to 8 bytes. +3. A second text string is written to the start of the stream, overwriting the first write. + +The stream is then closed. + ```js -// todo +async function saveFile() { + try { + // create a new handle + const newHandle = await window.showSaveFilePicker(); + + // create a FileSystemWritableFileStream to write to + const writableStream = await newHandle.createWritable(); + + // write our file + await writableStream.write("This is my first file content"); + await writableStream.truncate(8); + await writableStream.write("my second file content"); + + // close the file and write the contents to disk. + await writableStream.close(); + } catch (err) { + console.error(err.name, err.message); + } +} ``` +If you run the above function and then open the resulting file created on disk, you should see the text "This is my second file content". + ## Specifications {{Specifications}} @@ -58,5 +88,5 @@ A {{jsxref('Promise')}} which returns undefined. ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/filesystemwritablefilestream/write/index.md b/files/en-us/web/api/filesystemwritablefilestream/write/index.md index 1bbaa23588663d2..fba3633e5f329ba 100644 --- a/files/en-us/web/api/filesystemwritablefilestream/write/index.md +++ b/files/en-us/web/api/filesystemwritablefilestream/write/index.md @@ -6,7 +6,7 @@ page-type: web-api-instance-method browser-compat: api.FileSystemWritableFileStream.write --- -{{securecontext_header}}{{APIRef("File System Access API")}} +{{securecontext_header}}{{APIRef("File System API")}} The **`write()`** method of the {{domxref("FileSystemWritableFileStream")}} interface writes content into the file the method is called on, at the current file cursor offset. @@ -23,60 +23,60 @@ write(data) - `data` - - : Can be either the file data to write, in the form of an {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, - a {{jsxref("DataView")}}, a {{domxref('Blob')}}, a {{jsxref("String")}} object, or a string literal. - Or an object containing the following properties: - - - `type` - - : A string that is one of the following: `"write"`, `"seek"`, or `"truncate"`. - - `data` - - : The file data to write. Can be an {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, a {{jsxref("DataView")}}, - a {{domxref('Blob')}}, a {{jsxref("String")}} object, or a string literal. - This property is required if `type` is set to `write`. - - `position` - - : The byte position the current file cursor should move to if type `seek` is used. - Can also be set with if `type` is `write`, in which case the write will start at the position. - - `size` - - : An unsigned long value representing the amount of bytes the stream should contain. - This property is required if `type` is set to `truncate`. + - : Can be one of the following: + + - The file data to write, in the form of an {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, {{jsxref("DataView")}}, {{domxref('Blob')}}, or string. + - An object containing the following properties: + + - `type` + - : A string that is one of `"write"`, `"seek"`, or `"truncate"`. + - `data` + - : The file data to write. Can be an {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, {{jsxref("DataView")}}, {{domxref('Blob')}}, or string. This property is required if `type` is set to `"write"`. + - `position` + - : The byte position the current file cursor should move to if type `"seek"` is used. Can also be set if `type` is `"write"`, in which case the write will start at the specified position. + - `size` + - : A number representing the number of bytes the stream should contain. This property is required if `type` is set to `"truncate"`. ### Return value -{{jsxref('Promise')}} which returns undefined. +A {{jsxref('Promise')}} that returns `undefined`. ### Exceptions - `NotAllowedError` {{domxref("DOMException")}} - - : Returned if {{domxref('PermissionStatus')}} is not granted. + - : Returned if {{domxref('PermissionStatus.state')}} is not `granted`. - {{jsxref("TypeError")}} - : Returned if data is undefined, or if `position` or `size` aren't valid. - `InvalidStateError` {{domxref("DOMException")}} - - : Returned if the `position` is set and larger than the bytes available. + - : Returned if the specified `position` is larger than the length of the file data in bytes. ## Examples -This asynchronous function opens the 'Save File' picker, which returns a {{domxref('FileSystemFileHandle')}} once a file is selected. -From which a writable stream is then created using the {{domxref('FileSystemFileHandle.createWritable()')}} method. +The following asynchronous function opens the 'Save File' picker, which returns a {{domxref('FileSystemFileHandle')}} once a file is selected. From this, a writable stream is created using the {{domxref('FileSystemFileHandle.createWritable()')}} method. -A user defined {{domxref('Blob')}} is then written to the stream which is subsequently closed. +A text string is then written to the stream, which is subsequently closed. ```js async function saveFile() { - // create a new handle - const newHandle = await window.showSaveFilePicker(); + try { + // create a new handle + const newHandle = await window.showSaveFilePicker(); - // create a FileSystemWritableFileStream to write to - const writableStream = await newHandle.createWritable(); + // create a FileSystemWritableFileStream to write to + const writableStream = await newHandle.createWritable(); - // write our file - await writableStream.write(imgBlob); + // write our file + await writableStream.write("This is my file content"); - // close the file and write the contents to disk. - await writableStream.close(); + // close the file and write the contents to disk. + await writableStream.close(); + } catch (err) { + console.error(err.name, err.message); + } } ``` -The following show different examples of options that can be passed into the `write()` method. +The following examples show different options that can be passed into the `write()` method. ```js // just pass in the data (no options) @@ -102,5 +102,5 @@ writableStream.write({ type: "truncate", size }); ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/storage_api/storage_quotas_and_eviction_criteria/index.md b/files/en-us/web/api/storage_api/storage_quotas_and_eviction_criteria/index.md index bdd2ee64a3c2437..52f9a2cb121f6af 100644 --- a/files/en-us/web/api/storage_api/storage_quotas_and_eviction_criteria/index.md +++ b/files/en-us/web/api/storage_api/storage_quotas_and_eviction_criteria/index.md @@ -26,13 +26,13 @@ In some cases, however, browsers can decide to further separate the data stored Web developers can use the following web technologies to store data in the browser: -| Technology | Description | -| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Cookies](/en-US/docs/Web/HTTP/Cookies) | An HTTP cookie is a small piece of data that the web server and browser send each other to remember stateful information across page navigation. | -| [Web Storage](/en-US/docs/Web/API/Web_Storage_API) | The Web Storage API provides mechanisms for webpages to store string-only key/value pairs, including [`localStorage`](/en-US/docs/Web/API/Window/localStorage) and [`sessionStorage`](/en-US/docs/Web/API/Window/sessionStorage). | -| [IndexedDB](/en-US/docs/Web/API/IndexedDB_API) | IndexedDB is a Web API for storing large data structures in the browser and indexing them for high-performance searching. | -| [Cache API](/en-US/docs/Web/API/Cache) | The Cache API provides a persistent storage mechanism for HTTP request and response object pairs that's used to make webpages load faster. | -| [Origin Private File System Access API (OPFS)](/en-US/docs/Web/API/File_System_Access_API#origin_private_file_system) | OPFS provides a file system that's private to the origin of the page and can be used to read and write directories and files. | +| Technology | Description | +| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Cookies](/en-US/docs/Web/HTTP/Cookies) | An HTTP cookie is a small piece of data that the web server and browser send each other to remember stateful information across page navigation. | +| [Web Storage](/en-US/docs/Web/API/Web_Storage_API) | The Web Storage API provides mechanisms for webpages to store string-only key/value pairs, including [`localStorage`](/en-US/docs/Web/API/Window/localStorage) and [`sessionStorage`](/en-US/docs/Web/API/Window/sessionStorage). | +| [IndexedDB](/en-US/docs/Web/API/IndexedDB_API) | IndexedDB is a Web API for storing large data structures in the browser and indexing them for high-performance searching. | +| [Cache API](/en-US/docs/Web/API/Cache) | The Cache API provides a persistent storage mechanism for HTTP request and response object pairs that's used to make webpages load faster. | +| [Origin Private File System (OPFS)](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) | OPFS provides a file system that's private to the origin of the page and can be used to read and write directories and files. | Note that, in addition to the above, browsers will store other types of data in the browser for an origin, such as [WebAssembly](/en-US/docs/WebAssembly) code caching. @@ -75,7 +75,7 @@ Once this limit is reached, browsers throw a `QuotaExceededError` exception whic ### Other web technologies -The data that's stored by using other web technologies, such as IndexedDB, Cache API, or Origin-Private File System Access API, is managed by a storage management system that's specific to each browser. +The data that's stored by using other web technologies, such as IndexedDB, Cache API, or File System API (which defines the Origin Private File System), is managed by a storage management system that's specific to each browser. This system regulates all of the data that an origin stores using these APIs. diff --git a/files/en-us/web/api/storagemanager/getdirectory/index.md b/files/en-us/web/api/storagemanager/getdirectory/index.md index ab4964865d98a8e..70ab945aec6dbeb 100644 --- a/files/en-us/web/api/storagemanager/getdirectory/index.md +++ b/files/en-us/web/api/storagemanager/getdirectory/index.md @@ -8,7 +8,7 @@ browser-compat: api.StorageManager.getDirectory {{securecontext_header}}{{APIRef("Storage")}} -The **`getDirectory()`** method of the {{domxref("StorageManager")}} interface is used to obtain a reference to a {{domxref("FileSystemDirectoryHandle")}} object allowing access to a directory and its contents, stored in the [origin private file system](/en-US/docs/Web/API/File_System_Access_API#origin_private_file_system) (OPFS). +The **`getDirectory()`** method of the {{domxref("StorageManager")}} interface is used to obtain a reference to a {{domxref("FileSystemDirectoryHandle")}} object allowing access to a directory and its contents, stored in the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system) (OPFS). ## Syntax diff --git a/files/en-us/web/api/storagemanager/index.md b/files/en-us/web/api/storagemanager/index.md index eb55defae3a8304..b4a4d6559ecb864 100644 --- a/files/en-us/web/api/storagemanager/index.md +++ b/files/en-us/web/api/storagemanager/index.md @@ -14,7 +14,7 @@ The **`StorageManager`** interface of the [Storage API](/en-US/docs/Web/API/Stor - {{domxref("StorageManager.estimate()")}} {{securecontext_inline}} - : Returns a {{jsxref('Promise')}} that resolves to an object containing usage and quota numbers for your origin. - {{domxref("StorageManager.getDirectory()")}} {{securecontext_inline}} - - : Used to obtain a reference to a {{domxref("FileSystemDirectoryHandle")}} object allowing access to a directory and its contents, stored in the [origin private file system](/en-US/docs/Web/API/File_System_Access_API#origin_private_file_system). Returns a {{jsxref('Promise')}} that fulfills with a {{domxref("FileSystemDirectoryHandle")}} object. + - : Used to obtain a reference to a {{domxref("FileSystemDirectoryHandle")}} object allowing access to a directory and its contents, stored in the [origin private file system](/en-US/docs/Web/API/File_System_API/Origin_private_file_system). Returns a {{jsxref('Promise')}} that fulfills with a {{domxref("FileSystemDirectoryHandle")}} object. - {{domxref("StorageManager.persist()")}} {{securecontext_inline}} - : Returns a {{jsxref('Promise')}} that resolves to `true` if the user agent is able to persist your site's storage. - {{domxref("StorageManager.persisted()")}} {{securecontext_inline}} diff --git a/files/en-us/web/api/window/showdirectorypicker/index.md b/files/en-us/web/api/window/showdirectorypicker/index.md index 544093ef449cc33..25e9bc4c9429c5d 100644 --- a/files/en-us/web/api/window/showdirectorypicker/index.md +++ b/files/en-us/web/api/window/showdirectorypicker/index.md @@ -8,7 +8,7 @@ status: browser-compat: api.Window.showDirectoryPicker --- -{{securecontext_header}}{{DefaultAPISidebar("File System Access API")}}{{SeeCompatTable}} +{{securecontext_header}}{{DefaultAPISidebar("File System API")}}{{SeeCompatTable}} The **`showDirectoryPicker()`** method of the {{domxref("Window")}} interface displays a directory picker which allows the user to @@ -74,5 +74,5 @@ async function getDir() { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/window/showopenfilepicker/index.md b/files/en-us/web/api/window/showopenfilepicker/index.md index 8b8f03b375b6622..fd37597db282cff 100644 --- a/files/en-us/web/api/window/showopenfilepicker/index.md +++ b/files/en-us/web/api/window/showopenfilepicker/index.md @@ -8,7 +8,7 @@ status: browser-compat: api.Window.showOpenFilePicker --- -{{APIRef("File System Access API")}}{{SecureContext_Header}}{{SeeCompatTable}} +{{APIRef("File System API")}}{{SecureContext_Header}}{{SeeCompatTable}} The **`showOpenFilePicker()`** method of the {{domxref("Window")}} interface shows a file picker that allows a user to select a file @@ -105,5 +105,5 @@ async function getFile() { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/api/window/showsavefilepicker/index.md b/files/en-us/web/api/window/showsavefilepicker/index.md index 2aa5e864a263d59..3f06fb9c863b17d 100644 --- a/files/en-us/web/api/window/showsavefilepicker/index.md +++ b/files/en-us/web/api/window/showsavefilepicker/index.md @@ -8,7 +8,7 @@ status: browser-compat: api.Window.showSaveFilePicker --- -{{APIRef("File System Access API")}}{{SecureContext_Header}}{{SeeCompatTable}} +{{APIRef("File System API")}}{{SecureContext_Header}}{{SeeCompatTable}} The **`showSaveFilePicker()`** method of the {{domxref("Window")}} interface shows a file picker that allows a user to save a file. @@ -87,5 +87,5 @@ async function getNewFileHandle() { ## See also -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [The File System Access API: simplifying access to local files](https://web.dev/file-system-access/) diff --git a/files/en-us/web/progressive_web_apps/how_to/associate_files_with_your_pwa/index.md b/files/en-us/web/progressive_web_apps/how_to/associate_files_with_your_pwa/index.md index 501e86f55373910..7c04d400b7a6bb2 100644 --- a/files/en-us/web/progressive_web_apps/how_to/associate_files_with_your_pwa/index.md +++ b/files/en-us/web/progressive_web_apps/how_to/associate_files_with_your_pwa/index.md @@ -96,7 +96,7 @@ Note that the code checks that `launchQueue` exists before using it, to ensure t - [`file_handlers`](/en-US/docs/Web/Manifest/file_handlers) manifest member - {{domxref("LaunchQueue")}} interface -- [File System Access API](/en-US/docs/Web/API/File_System_Access_API) +- [File System API](/en-US/docs/Web/API/File_System_API) - [File API](/en-US/docs/Web/API/File_API) - [Let installed web applications be file handlers](https://developer.chrome.com/articles/file-handling/) on web.dev (2022) - [Handle files in Progressive Web Apps](https://learn.microsoft.com/en-us/microsoft-edge/progressive-web-apps-chromium/how-to/handle-files) on learn.microsoft.com (2023) diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index 373c6b76d1ca214..dc0bbc781e37cad 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -485,9 +485,9 @@ "properties": [], "events": [] }, - "File System Access API": { - "overview": ["File System Access API"], - "guides": [], + "File System API": { + "overview": ["File System API"], + "guides": ["/docs/Web/API/File_System_API/Origin_private_file_system"], "interfaces": [ "FileSystemHandle", "FileSystemFileHandle",