CalvinBackup/tauri-plugins-workspace
1
0
Fork 0
mirror of https://github.com/tauri-apps/plugins-workspace.git synced 2026-09-22 21:30:44 +02:00
Code Issues Packages Projects Releases Wiki Activity

chore: update documentation

Browse Source
This commit is contained in:
Lucas Nogueira
2026-09-22 11:30:47 -03:00
parent d869c162a7
commit a87a3c7d44
104 changed files with 4875 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/fs/guest-js/index.ts
+172 -16
View File
@@ -88,9 +88,15 @@
import { BaseDirectory } from '@tauri-apps/api/path'
import { Channel, invoke, Resource } from '@tauri-apps/api/core'
/**
* Defines how the offset given to {@linkcode FileHandle.seek} is interpreted.
*/
enum SeekMode {
/** The offset is relative to the start of the file. */
Start = 0,
/** The offset is relative to the current cursor position. */
Current = 1,
/** The offset is relative to the end of the file. */
End = 2
}
@@ -322,6 +328,8 @@ class FileHandle extends Resource {
* await file.close();
* ```
*
* @param buffer The buffer the file contents are read into.
* @returns A promise resolving to the number of bytes read, or `null` when the end of the file was reached.
* @since 2.0.0
*/
async read(buffer: Uint8Array): Promise<number | null> {
@@ -377,6 +385,9 @@ class FileHandle extends Resource {
* await file.close();
* ```
*
* @param offset The number of bytes the cursor is moved by.
* @param whence Defines the position the `offset` is relative to.
* @returns A promise resolving to the new cursor position, relative to the start of the file.
* @since 2.0.0
*/
async seek(offset: number, whence: SeekMode): Promise<number> {
@@ -399,6 +410,7 @@ class FileHandle extends Resource {
* await file.close();
* ```
*
* @returns A promise resolving to the metadata of this file.
* @since 2.0.0
*/
async stat(): Promise<FileInfo> {
@@ -431,6 +443,7 @@ class FileHandle extends Resource {
* await file.close();
* ```
*
* @param len The length the file is truncated or extended to, in bytes. When not provided the entire file contents are truncated.
* @since 2.0.0
*/
async truncate(len?: number): Promise<void> {
@@ -458,6 +471,8 @@ class FileHandle extends Resource {
* await file.close();
* ```
*
* @param data The bytes written to the file.
* @returns A promise resolving to the number of bytes written.
* @since 2.0.0
*/
async write(data: Uint8Array): Promise<number> {
@@ -469,6 +484,8 @@ class FileHandle extends Resource {
}
/**
* Options for the `create` function, which creates or truncates a file.
*
* @since 2.0.0
*/
interface CreateOptions {
@@ -488,6 +505,9 @@ interface CreateOptions {
* await file.close();
* ```
*
* @param path The path of the file, relative to `options.baseDir` when it is provided.
* @param options Options defining the base directory of `path`.
* @returns A promise resolving to the handle of the created file.
* @since 2.0.0
*/
async function create(
@@ -507,6 +527,8 @@ async function create(
}
/**
* Options for the `open` function, defining how the file is opened and which operations are allowed on it.
*
* @since 2.0.0
*/
interface OpenOptions {
@@ -573,6 +595,9 @@ interface OpenOptions {
* await file.close();
* ```
*
* @param path The path of the file, relative to `options.baseDir` when it is provided.
* @param options Options defining the base directory of `path` and how the file is opened.
* @returns A promise resolving to the handle of the open file.
* @since 2.0.0
*/
async function open(
@@ -592,6 +617,8 @@ async function open(
}
/**
* Options for the `copyFile` function, defining the base directory of each path.
*
* @since 2.0.0
*/
interface CopyFileOptions {
@@ -609,6 +636,9 @@ interface CopyFileOptions {
* await copyFile('app.conf', 'app.conf.bk', { fromPathBaseDir: BaseDirectory.AppConfig, toPathBaseDir: BaseDirectory.AppConfig });
* ```
*
* @param fromPath The path of the file to copy from.
* @param toPath The path of the file to copy to.
* @param options Options defining the base directory of each path.
* @since 2.0.0
*/
async function copyFile(
@@ -631,6 +661,8 @@ async function copyFile(
}
/**
* Options for the `mkdir` function, which creates a directory.
*
* @since 2.0.0
*/
interface MkdirOptions {
@@ -652,6 +684,8 @@ interface MkdirOptions {
* await mkdir('users', { baseDir: BaseDirectory.AppLocalData });
* ```
*
* @param path The path of the directory to create.
* @param options Options defining the base directory of `path`, the directory permissions and whether intermediate directories are created.
* @since 2.0.0
*/
async function mkdir(
@@ -669,6 +703,8 @@ async function mkdir(
}
/**
* Options for the `readDir` function, which lists the entries of a directory.
*
* @since 2.0.0
*/
interface ReadDirOptions {
@@ -700,20 +736,23 @@ interface DirEntry {
* ```typescript
* import { readDir, BaseDirectory } from '@tauri-apps/plugin-fs';
* import { join } from '@tauri-apps/api/path';
* const dir = "users"
* const entries = await readDir('users', { baseDir: BaseDirectory.AppLocalData });
* processEntriesRecursively(dir, entries);
* const dir = 'users';
* const entries = await readDir(dir, { baseDir: BaseDirectory.AppLocalData });
* await processEntriesRecursively(dir, entries);
* async function processEntriesRecursively(parent, entries) {
* for (const entry of entries) {
* console.log(`Entry: ${entry.name}`);
* if (entry.isDirectory) {
* const dir = await join(parent, entry.name);
* processEntriesRecursively(dir, await readDir(dir, { baseDir: BaseDirectory.AppLocalData }))
* const entryPath = await join(parent, entry.name);
* await processEntriesRecursively(entryPath, await readDir(entryPath, { baseDir: BaseDirectory.AppLocalData }));
* }
* }
* }
* ```
*
* @param path The path of the directory to read.
* @param options Options defining the base directory of `path`.
* @returns A promise resolving to the list of entries in the directory.
* @since 2.0.0
*/
async function readDir(
@@ -731,6 +770,8 @@ async function readDir(
}
/**
* Options for the functions that read a file, such as `readFile` and `readTextFile`.
*
* @since 2.0.0
*/
interface ReadFileOptions {
@@ -749,6 +790,9 @@ interface ReadFileOptions {
* const contents = await readFile('avatar.png', { baseDir: BaseDirectory.Resource });
* ```
*
* @param path The path of the file to read.
* @param options Options defining the base directory of `path`.
* @returns A promise resolving to the contents of the file as bytes.
* @since 2.0.0
*/
async function readFile(
@@ -775,6 +819,9 @@ async function readFile(
* const contents = await readTextFile('app.conf', { baseDir: BaseDirectory.AppConfig });
* ```
*
* @param path The path of the file to read.
* @param options Options defining the base directory of `path` and the text encoding.
* @returns A promise resolving to the contents of the file as a string.
* @since 2.0.0
*/
async function readTextFile(
@@ -808,6 +855,9 @@ async function readTextFile(
* You could also call {@linkcode AsyncIterableIterator.next} to advance the
* iterator so you can lazily read the next line whenever you want.
*
* @param path The path of the file to read.
* @param options Options defining the base directory of `path` and the text encoding.
* @returns A promise resolving to an iterator over the lines of the file.
* @since 2.0.0
*/
async function readTextFileLines(
@@ -873,6 +923,8 @@ async function readTextFileLines(
}
/**
* Options for the `remove` function, which deletes a file or a directory.
*
* @since 2.0.0
*/
interface RemoveOptions {
@@ -892,6 +944,8 @@ interface RemoveOptions {
* await remove('users', { baseDir: BaseDirectory.AppLocalData });
* ```
*
* @param path The path of the file or directory to remove.
* @param options Options defining the base directory of `path` and whether directories are removed recursively.
* @since 2.0.0
*/
async function remove(
@@ -909,6 +963,8 @@ async function remove(
}
/**
* Options for the `rename` function, defining the base directory of each path.
*
* @since 2.0.0
*/
interface RenameOptions {
@@ -931,6 +987,9 @@ interface RenameOptions {
* await rename('avatar.png', 'deleted.png', { oldPathBaseDir: BaseDirectory.App, newPathBaseDir: BaseDirectory.AppLocalData });
* ```
*
* @param oldPath The path of the file or directory to rename.
* @param newPath The path the file or directory is renamed to.
* @param options Options defining the base directory of each path.
* @since 2.0.0
*/
async function rename(
@@ -953,6 +1012,8 @@ async function rename(
}
/**
* Options for the `stat` and `lstat` functions, which read the metadata of a path.
*
* @since 2.0.0
*/
interface StatOptions {
@@ -971,6 +1032,9 @@ interface StatOptions {
* console.log(fileInfo.isFile); // true
* ```
*
* @param path The path of the file or directory to inspect.
* @param options Options defining the base directory of `path`.
* @returns A promise resolving to the metadata of the file or directory.
* @since 2.0.0
*/
async function stat(
@@ -997,6 +1061,9 @@ async function stat(
* console.log(fileInfo.isFile); // true
* ```
*
* @param path The path of the file, directory or symlink to inspect.
* @param options Options defining the base directory of `path`.
* @returns A promise resolving to the metadata of the path itself.
* @since 2.0.0
*/
async function lstat(
@@ -1012,6 +1079,8 @@ async function lstat(
}
/**
* Options for the `truncate` function, which truncates or extends a file.
*
* @since 2.0.0
*/
interface TruncateOptions {
@@ -1037,6 +1106,9 @@ interface TruncateOptions {
* console.log(data); // "Hello W"
* ```
*
* @param path The path of the file to truncate or extend.
* @param len The length the file is resized to, in bytes. Defaults to `0`.
* @param options Options defining the base directory of `path`.
* @since 2.0.0
*/
async function truncate(
@@ -1056,6 +1128,8 @@ async function truncate(
}
/**
* Options for the `writeFile` and `writeTextFile` functions, defining how the file is opened before writing to it.
*
* @since 2.0.0
*/
interface WriteFileOptions {
@@ -1082,6 +1156,9 @@ interface WriteFileOptions {
* await writeFile('file.txt', data, { baseDir: BaseDirectory.AppLocalData });
* ```
*
* @param path The path of the file to write to.
* @param data The bytes written to the file, either as a buffer or as a stream of chunks.
* @param options Options defining the base directory of `path` and how the file is opened.
* @since 2.0.0
*/
async function writeFile(
@@ -1123,16 +1200,20 @@ async function writeFile(
}
/**
* Writes UTF-8 string `data` to the given `path`, by default creating a new file if needed, else overwriting.
@example
* ```typescript
* import { writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
*
* await writeTextFile('file.txt', "Hello world", { baseDir: BaseDirectory.AppLocalData });
* ```
*
* @since 2.0.0
*/
* Writes UTF-8 string `data` to the given `path`, by default creating a new file if needed, else overwriting.
*
* @example
* ```typescript
* import { writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
*
* await writeTextFile('file.txt', "Hello world", { baseDir: BaseDirectory.AppLocalData });
* ```
*
* @param path The path of the file to write to.
* @param data The UTF-8 string written to the file.
* @param options Options defining the base directory of `path` and how the file is opened.
* @since 2.0.0
*/
async function writeTextFile(
path: string | URL,
data: string,
@@ -1153,6 +1234,8 @@ async function writeTextFile(
}
/**
* Options for the `exists` function, which checks whether a path exists.
*
* @since 2.0.0
*/
interface ExistsOptions {
@@ -1169,6 +1252,9 @@ interface ExistsOptions {
* await exists('avatar.png', { baseDir: BaseDirectory.AppData });
* ```
*
* @param path The path to check.
* @param options Options defining the base directory of `path`.
* @returns A promise resolving to `true` when the path exists, `false` otherwise.
* @since 2.0.0
*/
async function exists(
@@ -1186,6 +1272,8 @@ async function exists(
}
/**
* Options for the `watchImmediate` function, which reports file system changes as they happen.
*
* @since 2.0.0
*/
interface WatchOptions {
@@ -1196,23 +1284,35 @@ interface WatchOptions {
}
/**
* Options for the `watch` function, which reports file system changes after a debounce delay.
*
* @since 2.0.0
*/
interface DebouncedWatchOptions extends WatchOptions {
/** Debounce delay */
/**
* The debounce delay in milliseconds. Changes that happen within this
* window are grouped and reported together. Defaults to `2000`.
*/
delayMs?: number
}
/**
* A file system change reported to the callback of `watch` or `watchImmediate`.
*
* @since 2.0.0
*/
interface WatchEvent {
/** The kind of change that was detected. */
type: WatchEventKind
/** The paths affected by the change. */
paths: string[]
/** Additional attributes reported by the underlying file system watcher. */
attrs: unknown
}
/**
* The kind of file system change described by a `WatchEvent`.
*
* @since 2.0.0
*/
type WatchEventKind =
@@ -1224,6 +1324,8 @@ type WatchEventKind =
| 'other'
/**
* Describes how a file or directory was accessed.
*
* @since 2.0.0
*/
type WatchEventKindAccess =
@@ -1233,6 +1335,8 @@ type WatchEventKindAccess =
| { kind: 'other' }
/**
* Describes which kind of entry was created.
*
* @since 2.0.0
*/
type WatchEventKindCreate =
@@ -1242,6 +1346,8 @@ type WatchEventKindCreate =
| { kind: 'other' }
/**
* Describes what was modified on a file or directory.
*
* @since 2.0.0
*/
type WatchEventKindModify =
@@ -1262,6 +1368,8 @@ type WatchEventKindModify =
| { kind: 'other' }
/**
* Describes which kind of entry was removed.
*
* @since 2.0.0
*/
type WatchEventKindRemove =
@@ -1272,6 +1380,8 @@ type WatchEventKindRemove =
// TODO: Remove this in v3, return `Watcher` instead
/**
* Stops watching the paths it was created for. Returned by `watch` and `watchImmediate`.
*
* @since 2.0.0
*/
type UnwatchFn = () => void
@@ -1311,6 +1421,27 @@ async function watchInternal(
/**
* Watch changes (after a delay) on files or directories.
*
* Events that happen within the `delayMs` window are grouped and delivered in a single callback call.
* Requires the `watch` Cargo feature of the Rust plugin to be enabled.
*
* @example
* ```typescript
* import { watch, BaseDirectory } from '@tauri-apps/plugin-fs';
*
* const unwatch = await watch(
* 'app.conf',
* (event) => console.log(event.type, event.paths),
* { baseDir: BaseDirectory.AppConfig, delayMs: 500 }
* );
*
* // stop watching when you are done
* unwatch();
* ```
*
* @param paths The path or list of paths to watch. Each path can be a string or a `file://` URL.
* @param cb The callback executed for each batch of file system changes.
* @param options Options defining the base directory of the paths, the debounce delay and whether directories are watched recursively.
* @returns A promise resolving to a function that stops watching the given paths.
* @since 2.0.0
*/
async function watch(
@@ -1328,6 +1459,27 @@ async function watch(
/**
* Watch changes on files or directories.
*
* Unlike `watch`, changes are reported as soon as they are detected, without a debounce delay.
* Requires the `watch` Cargo feature of the Rust plugin to be enabled.
*
* @example
* ```typescript
* import { watchImmediate, BaseDirectory } from '@tauri-apps/plugin-fs';
*
* const unwatch = await watchImmediate(
* 'logs',
* (event) => console.log(event.type, event.paths),
* { baseDir: BaseDirectory.AppLog, recursive: true }
* );
*
* // stop watching when you are done
* unwatch();
* ```
*
* @param paths The path or list of paths to watch. Each path can be a string or a `file://` URL.
* @param cb The callback executed for each file system change.
* @param options Options defining the base directory of the paths and whether directories are watched recursively.
* @returns A promise resolving to a function that stops watching the given paths.
* @since 2.0.0
*/
async function watchImmediate(
@@ -1354,6 +1506,8 @@ async function watchImmediate(
* console.log(dirSize); // 1024
* ```
*
* @param path The path of the file or directory to measure.
* @returns A promise resolving to the size in bytes.
* @since 2.1.0
*/
async function size(path: string | URL): Promise<number> {
@@ -1390,6 +1544,7 @@ async function size(path: string | URL): Promise<number> {
* // ... use the resource ...
* ```
*
* @param path The path or `file://` URL of the resource to start accessing.
* @since 2.5.0
*/
async function startAccessingSecurityScopedResource(
@@ -1425,6 +1580,7 @@ async function startAccessingSecurityScopedResource(
* await stopAccessingSecurityScopedResource(filePath);
* ```
*
* @param path The path or `file://` URL of the resource to stop accessing.
* @since 2.5.0
*/
async function stopAccessingSecurityScopedResource(