use-file-system-access

Open, edit, and save local files with the File System Access API.


Package	`@vizejs/composable/use-file-system-access`
Own the source	`vize lib pull composable:use-file-system-access`
Runtime exports	`useFileSystemAccess`
Gzip budget	1536 B

Usage

import { useFileSystemAccess } from "@vizejs/composable/use-file-system-access";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useFileSystemAccess`	storage	experimental	deterministic-fallback	caller-managed	none	web, desktop	`window`	—

API

`useFileSystemAccess`

Open, edit, and save local files with the File System Access API. data is typed by dataType (string, ArrayBuffer, or Blob) and is writable: edit it and call save to write back through the retained file handle. Every action resolves to a discriminated FileSystemAccessResult; a dismissed picker is "cancelled". No listeners or timers are held, so nothing needs cleanup. Server rendering: supported is false, data is undefined, and every action resolves to "unsupported".

function useFileSystemAccess( options?: UseFileSystemAccessOptions<"text">, ): FileSystemAccessControls<"text">

const editor = useFileSystemAccess({ types: [{ accept: { "text/markdown": [".md"] } }] });
await editor.open();
editor.data.value += "\n";
await editor.save();

`useFileSystemAccess`

function useFileSystemAccess<Kind extends FileSystemAccessDataType>( options: UseFileSystemAccessOptions<Kind> & { readonly dataType: Kind }, ): FileSystemAccessControls<Kind>

`useFileSystemAccess`

function useFileSystemAccess( options: UseFileSystemAccessOptions<FileSystemAccessDataType> = {}, ): FileSystemAccessControls<FileSystemAccessDataType>

Types

`FileSystemAccessDataMap`

Value types produced for each FileSystemAccessDataType.

Member	Type	Description
`text`	`string`	UTF-8 decoded text.
`arrayBuffer`	`ArrayBuffer`	Raw bytes.
`blob`	`Blob`	The file itself (a `Blob`).

`FilePickerAcceptTypeLike`

One accepted file type group for the pickers.

Member	Type	Description
`description`?	`string`	Human-readable description.
`accept`	`Readonly<Record<string, string \| readonly string[]>>`	MIME type to extensions map, for example `{ "text/plain": [".txt"] }`.

`FileSystemWritableLike`

Writable stream returned by createWritable.

Member	Type	Description
`write`	`(data: string \| ArrayBuffer \| Blob) => Promise<void>`	Write data.
`close`	`() => Promise<void>`	Commit and close the stream.

`FileSystemFileHandleLike`

Minimal FileSystemFileHandle.

Member	Type	Description
`name`	`string`	File name.
`getFile`	`() => Promise<File>`	Snapshot of the current file contents.
`createWritable`	`() => Promise<FileSystemWritableLike>`	Open a writable stream.

`OpenFilePickerOptionsLike`

Options passed to showOpenFilePicker.

Member	Type	Description
`types`?	`readonly FilePickerAcceptTypeLike[]`	Accepted types.
`excludeAcceptAllOption`?	`boolean`	Hide the "all files" option.
`multiple`?	`boolean`	Allow selecting multiple files.

`SaveFilePickerOptionsLike`

Options passed to showSaveFilePicker.

Member	Type	Description
`types`?	`readonly FilePickerAcceptTypeLike[]`	Accepted types.
`excludeAcceptAllOption`?	`boolean`	Hide the "all files" option.
`suggestedName`?	`string`	Suggested file name.

`FileSystemAccessHost`

File System Access pickers (window.showOpenFilePicker and friends).

Member	Type	Description
`showOpenFilePicker`	`(options?: OpenFilePickerOptionsLike) => Promise<readonly FileSystemFileHandleLike[]>`	Show the open-file picker.
`showSaveFilePicker`	`(options?: SaveFilePickerOptionsLike) => Promise<FileSystemFileHandleLike>`	Show the save-file picker.

`UseFileSystemAccessOptions`

Options for useFileSystemAccess.

Member	Type	Description
`dataType`?	`Kind`	How file contents are exposed through `data`. Required for any representation other than text so the data type is always inferred from a runtime value.
`types`?	`MaybeRefOrGetter<readonly FilePickerAcceptTypeLike[] \| undefined>`	Accepted file types for both pickers.
`excludeAcceptAllOption`?	`MaybeRefOrGetter<boolean>`	Hide the "all files" option.
`suggestedName`?	`MaybeRefOrGetter<string \| undefined>`	Suggested name for the save picker.
`host`?	`MaybeRefOrGetter<FileSystemAccessHost \| null \| undefined>`	File System Access capability for alternate runtimes and tests.

`FileSystemAccessControls`

Reactive state and actions returned by useFileSystemAccess.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the File System Access pickers are available.
`data`	`Ref<FileSystemAccessDataMap[Kind] \| undefined>`	File contents, typed by `dataType`. Assign to edit, then `save`.
`file`	`Readonly<ShallowRef<File \| undefined>>`	Snapshot of the current file.
`handle`	`Readonly<ShallowRef<FileSystemFileHandleLike \| undefined>>`	Current file handle.
`fileName`	`ComputedRef<string>`	Name of the current file.
`fileMIME`	`ComputedRef<string>`	MIME type of the current file.
`fileSize`	`ComputedRef<number>`	Size in bytes of the current file.
`fileLastModified`	`ComputedRef<number>`	Last modification time (Unix milliseconds) of the current file.
`open`	`() => Promise<FileSystemAccessResult>`	Pick a file and read it.
`create`	`() => Promise<FileSystemAccessResult>`	Pick a new file location and clear `data`.
`save`	`() => Promise<FileSystemAccessResult>`	Write `data` to the current file, or ask for a location first.
`saveAs`	`() => Promise<FileSystemAccessResult>`	Ask for a location and write `data` there.
`updateData`	`() => Promise<FileSystemAccessResult>`	Re-read the current file into `data`.