@tauri-apps/plugin-fs
Access the file system.
Security
This module prevents path traversal, not allowing absolute paths or parent dir components (i.e. “/usr/path/to/file” or “../path/to/file” paths are not allowed). Paths accessed with this API must be relative to one of the base directories so if you need access to arbitrary filesystem paths, you must write such logic on the core layer instead.
The API has a scope configuration that forces you to restrict the paths that can be accessed using glob patterns.
The scope configuration is an array of glob patterns describing folder paths that are allowed.
For instance, this scope configuration only allows accessing files on the
databases folder of the $APPDATA
directory:
Notice the use of the $APPDATA
variable. The value is injected at runtime, resolving to the app data directory.
The available variables are:
$APPCONFIG
,
$APPDATA
,
$APPLOCALDATA
,
$APPCACHE
,
$APPLOG
,
$AUDIO
,
$CACHE
,
$CONFIG
,
$DATA
,
$LOCALDATA
,
$DESKTOP
,
$DOCUMENT
,
$DOWNLOAD
,
$EXE
,
$FONT
,
$HOME
,
$PICTURE
,
$PUBLIC
,
$RUNTIME
,
$TEMPLATE
,
$VIDEO
,
$RESOURCE
,
$TEMP
.
Trying to execute any API with a URL not configured on the scope results in a promise rejection due to denied access.
Note that this scope applies to all APIs on this module.
Enumerations
BaseDirectory
Since
2.0.0
Enumeration Members
AppCache
Source: undefined
AppConfig
Source: undefined
AppData
Source: undefined
AppLocalData
Source: undefined
AppLog
Source: undefined
Audio
Source: undefined
Cache
Source: undefined
Config
Source: undefined
Data
Source: undefined
Desktop
Source: undefined
Document
Source: undefined
Download
Source: undefined
Executable
Source: undefined
Font
Source: undefined
Home
Source: undefined
LocalData
Source: undefined
Picture
Source: undefined
Public
Source: undefined
Resource
Source: undefined
Runtime
Source: undefined
Temp
Source: undefined
Template
Source: undefined
Video
Source: undefined
SeekMode
Enumeration Members
Current
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L69
End
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L70
Start
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L68
Classes
FileHandle
The Tauri abstraction for reading and writing files.
Since
2.0.0
Extends
Resource
Constructors
new FileHandle()
Parameters
Parameter | Type |
---|---|
rid | number |
Returns
Inherited from
Resource.constructor
Source: undefined
Properties
Property | Modifier | Type | Inherited from |
---|---|---|---|
#private | private | any | Resource.#private |
Accessors
rid
Returns
number
Source: undefined
Methods
close()
Destroys and cleans up this resource from memory. You should not call any method on this object anymore and should drop any reference to it.
Returns
Promise
<void
>
Inherited from
Resource.close
Source: undefined
read()
Reads up to p.byteLength
bytes into p
. It resolves to the number of
bytes read (0
< n
<= p.byteLength
) and rejects if any error
encountered. Even if read()
resolves to n
< p.byteLength
, it may
use all of p
as scratch space during the call. If some data is
available but not p.byteLength
bytes, read()
conventionally resolves
to what is available instead of waiting for more.
When read()
encounters end-of-file condition, it resolves to EOF
(null
).
When read()
encounters an error, it rejects with an error.
Callers should always process the n
> 0
bytes returned before
considering the EOF (null
). Doing so correctly handles I/O errors that
happen after reading some bytes and also both of the allowed EOF
behaviors.
Parameters
Parameter | Type |
---|---|
buffer | Uint8Array |
Returns
Promise
<null
| number
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L283
seek()
Seek sets the offset for the next read()
or write()
to offset,
interpreted according to whence
: Start
means relative to the
start of the file, Current
means relative to the current offset,
and End
means relative to the end. Seek resolves to the new offset
relative to the start of the file.
Seeking to an offset before the start of the file is an error. Seeking to any positive offset is legal, but the behavior of subsequent I/O operations on the underlying object is implementation-dependent. It returns the number of cursor position.
Parameters
Parameter | Type |
---|---|
offset | number |
whence | SeekMode |
Returns
Promise
<number
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L328
stat()
Returns a FileInfo
for this file.
Returns
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L349
truncate()
Truncates or extends this file, to reach the specified len
.
If len
is not specified then the entire file contents are truncated.
Parameters
Parameter | Type |
---|---|
len ? | number |
Returns
Promise
<void
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L380
write()
Writes p.byteLength
bytes from p
to the underlying data stream. It
resolves to the number of bytes written from p
(0
<= n
<=
p.byteLength
) or reject with the error encountered that caused the
write to stop early. write()
must reject with a non-null error if
would resolve to n
< p.byteLength
. write()
must not modify the
slice data, even temporarily.
Parameters
Parameter | Type |
---|---|
data | Uint8Array |
Returns
Promise
<number
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L407
Interfaces
CopyFileOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
fromPathBaseDir? | BaseDirectory | Base directory for fromPath . |
toPathBaseDir? | BaseDirectory | Base directory for toPath . |
CreateOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path |
DebouncedWatchOptions
Since
2.0.0
Extends
Properties
Property | Type | Description | Inherited from |
---|---|---|---|
baseDir? | BaseDirectory | Base directory for path | WatchOptions .baseDir |
delayMs? | number | Debounce delay | - |
recursive? | boolean | Watch a directory recursively | WatchOptions .recursive |
DirEntry
A disk entry which is either a file, a directory or a symlink.
This is the result of the readDir
.
Since
2.0.0
Properties
ExistsOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path . |
FileInfo
A FileInfo describes a file and is returned by stat
, lstat
or fstat
.
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
atime | null | Date | The last access time of the file. This corresponds to the atime field from stat on Unix and ftLastAccessTime on Windows. This may not be available on all platforms. |
birthtime | null | Date | The creation time of the file. This corresponds to the birthtime field from stat on Mac/BSD and ftCreationTime on Windows. This may not be available on all platforms. |
blksize | null | number | Blocksize for filesystem I/O. Platform-specific
|
blocks | null | number | Number of blocks allocated to the file, in 512-byte units. Platform-specific
|
dev | null | number | ID of the device containing the file. Platform-specific
|
fileAttributes | null | number | This field contains the file system attribute information for a file or directory. For possible values and their descriptions, see File Attribute Constants in the Windows Dev Center Platform-specific
|
gid | null | number | Group ID of the owner of this file. Platform-specific
|
ino | null | number | Inode number. Platform-specific
|
isDirectory | boolean | True if this is info for a regular directory. Mutually exclusive to FileInfo.isFile and FileInfo.isSymlink . |
isFile | boolean | True if this is info for a regular file. Mutually exclusive to FileInfo.isDirectory and FileInfo.isSymlink . |
isSymlink | boolean | True if this is info for a symlink. Mutually exclusive to FileInfo.isFile and FileInfo.isDirectory . |
mode | null | number | The underlying raw Platform-specific
|
mtime | null | Date | The last modification time of the file. This corresponds to the mtime field from stat on Linux/Mac OS and ftLastWriteTime on Windows. This may not be available on all platforms. |
nlink | null | number | Number of hard links pointing to this file. Platform-specific
|
rdev | null | number | Device ID of this file. Platform-specific
|
readonly | boolean | Whether this is a readonly (unwritable) file. |
size | number | The size of the file, in bytes. |
uid | null | number | User ID of the owner of this file. Platform-specific
|
MkdirOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path |
mode? | number | Permissions to use when creating the directory (defaults to 0o777 , before the process’s umask). Ignored on Windows. |
recursive? | boolean | Defaults to false . If set to true , means that any intermediate directories will also be created (as with the shell command mkdir -p ). |
OpenOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
append? | boolean | Sets the option for the append mode. This option, when true , means that writes will append to a file instead of overwriting previous contents. Note that setting { write: true, append: true } has the same effect as setting only { append: true } . |
baseDir? | BaseDirectory | Base directory for path |
create? | boolean | Sets the option to allow creating a new file, if one doesn’t already exist at the specified path. Requires write or append access to be used. |
createNew? | boolean | Defaults to false . If set to true , no file, directory, or symlink is allowed to exist at the target location. Requires write or append access to be used. When createNew is set to true , create and truncate are ignored. |
mode? | number | Permissions to use if creating the file (defaults to 0o666 , before the process’s umask). Ignored on Windows. |
read? | boolean | Sets the option for read access. This option, when true , means that the file should be read-able if opened. |
truncate? | boolean | Sets the option for truncating a previous file. If a file is successfully opened with this option set it will truncate the file to 0 size if it already exists. The file must be opened with write access for truncate to work. |
write? | boolean | Sets the option for write access. This option, when true , means that the file should be write-able if opened. If the file already exists, any write calls on it will overwrite its contents, by default without truncating it. |
ReadDirOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path |
ReadFileOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path |
RemoveOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path |
recursive? | boolean | Defaults to false . If set to true , path will be removed even if it’s a non-empty directory. |
RenameOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
newPathBaseDir? | BaseDirectory | Base directory for newPath . |
oldPathBaseDir? | BaseDirectory | Base directory for oldPath . |
StatOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path . |
TruncateOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path . |
WatchEvent
Since
2.0.0
Properties
Property | Type |
---|---|
attrs | unknown |
paths | string [] |
type | WatchEventKind |
WatchOptions
Since
2.0.0
Extended by
Properties
Property | Type | Description |
---|---|---|
baseDir? | BaseDirectory | Base directory for path |
recursive? | boolean | Watch a directory recursively |
WriteFileOptions
Since
2.0.0
Properties
Property | Type | Description |
---|---|---|
append? | boolean | Defaults to false . If set to true , will append to a file instead of overwriting previous contents. |
baseDir? | BaseDirectory | Base directory for path |
create? | boolean | Sets the option to allow creating a new file, if one doesn’t already exist at the specified path (defaults to true ). |
createNew? | boolean | Sets the option to create a new file, failing if it already exists. |
mode? | number | File permissions. Ignored on Windows. |
Type Aliases
UnwatchFn()
Since
2.0.0
Returns
void
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1167
WatchEventKind
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1109
WatchEventKindAccess
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1120
WatchEventKindCreate
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1129
WatchEventKindModify
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1138
WatchEventKindRemove
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1158
Functions
copyFile()
Copies the contents and permissions of one file to another specified path, by default creating a new file if needed, else overwriting.
Parameters
Parameter | Type |
---|---|
fromPath | string | URL |
toPath | string | URL |
options ? | CopyFileOptions |
Returns
Promise
<void
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L556
create()
Creates a file if none exists or truncates an existing file and resolves to
an instance of FileHandle
.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | CreateOptions |
Returns
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L435
exists()
Check if a path exists.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | ExistsOptions |
Returns
Promise
<boolean
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1065
lstat()
Resolves to a FileInfo
for the specified path
. If path
is a
symlink, information for the symlink will be returned instead of what it
points to.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | StatOptions |
Returns
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L917
mkdir()
Creates a new directory with the specified path.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | MkdirOptions |
Returns
Promise
<void
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L599
open()
Open a file and resolve to an instance of FileHandle
. The
file does not need to previously exist if using the create
or createNew
open options. It is the callers responsibility to close the file when finished
with it.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | OpenOptions |
Returns
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L520
readDir()
Reads the directory given by path and returns an array of DirEntry
.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | ReadDirOptions |
Returns
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L660
readFile()
Reads and resolves to the entire contents of a file as an array of bytes. TextDecoder can be used to transform the bytes to string if required.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | ReadFileOptions |
Returns
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L693
readTextFile()
Reads and returns the entire contents of a file as UTF-8 string.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | ReadFileOptions |
Returns
Promise
<string
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L721
readTextFileLines()
Returns an async AsyncIterableIterator over the lines of a file as UTF-8 string.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | ReadFileOptions |
Returns
Promise
<AsyncIterableIterator
<string
>>
Example
You could also call AsyncIterableIterator.next to advance the iterator so you can lazily read the next line whenever you want.
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L750
remove()
Removes the named file or directory.
If the directory is not empty and the recursive
option isn’t set to true, the promise will be rejected.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | RemoveOptions |
Returns
Promise
<void
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L812
rename()
Renames (moves) oldpath to newpath. Paths may be files or directories. If newpath already exists and is not a directory, rename() replaces it. OS-specific restrictions may apply when oldpath and newpath are in different directories.
On Unix, this operation does not follow symlinks at either path.
Parameters
Parameter | Type |
---|---|
oldPath | string | URL |
newPath | string | URL |
options ? | RenameOptions |
Returns
Promise
<void
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L851
stat()
Resolves to a FileInfo
for the specified path
. Will always
follow symlinks but will reject if the symlink points to a path outside of the scope.
Parameters
Parameter | Type |
---|---|
path | string | URL |
options ? | StatOptions |
Returns
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L891
truncate()
Truncates or extends the specified file, to reach the specified len
.
If len
is 0
or not specified, then the entire file contents are truncated.
Parameters
Parameter | Type |
---|---|
path | string | URL |
len ? | number |
options ? | TruncateOptions |
Returns
Promise
<void
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L957
watch()
Watch changes (after a delay) on files or directories.
Parameters
Parameter | Type |
---|---|
paths | string | URL | string [] | URL [] |
cb | (event ) => void |
options ? | DebouncedWatchOptions |
Returns
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1178
watchImmediate()
Watch changes on files or directories.
Parameters
Parameter | Type |
---|---|
paths | string | URL | string [] | URL [] |
cb | (event ) => void |
options ? | WatchOptions |
Returns
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1216
writeFile()
Write data
to the given path
, by default creating a new file if needed, else overwriting.
Parameters
Parameter | Type |
---|---|
path | string | URL |
data | Uint8Array |
options ? | WriteFileOptions |
Returns
Promise
<void
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1002
writeTextFile()
Writes UTF-8 string data
to the given path
, by default creating a new file if needed, else overwriting.
Parameters
Parameter | Type |
---|---|
path | string | URL |
data | string |
options ? | WriteFileOptions |
Returns
Promise
<void
>
Example
Since
2.0.0
Source: https://github.com/tauri-apps/plugins-workspace/blob/v2/plugins/fs/guest-js/index.ts#L1030
© 2024 Tauri Contributors. CC-BY / MIT