@tauri-apps/plugin-fs 3.0.0-alpha.1 → 3.0.0-alpha.2

package/README.md

@@ -12,7 +12,7 @@ Access the file system.
 
 ## Install
 
-_This plugin requires a Rust version of at least **1.77.2**_
+_This plugin requires a Rust version of at least **1.95**_
 
 There are three general methods of installation that we can recommend.
 

package/dist-js/index.cjs

@@ -88,10 +88,16 @@ var core = require('@tauri-apps/api/core');
  *
  * @module
  */
+/**
+ * Defines how the offset given to {@linkcode FileHandle.seek} is interpreted.
+ */
 exports.SeekMode = void 0;
 (function (SeekMode) {
+    /** The offset is relative to the start of the file. */
     SeekMode[SeekMode["Start"] = 0] = "Start";
+    /** The offset is relative to the current cursor position. */
     SeekMode[SeekMode["Current"] = 1] = "Current";
+    /** The offset is relative to the end of the file. */
     SeekMode[SeekMode["End"] = 2] = "End";
 })(exports.SeekMode || (exports.SeekMode = {}));
 function parseFileInfo(r) {
@@ -165,6 +171,8 @@ class FileHandle extends core.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) {
@@ -215,6 +223,9 @@ class FileHandle extends core.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, whence) {
@@ -236,6 +247,7 @@ class FileHandle extends core.Resource {
      * await file.close();
      * ```
      *
+     * @returns A promise resolving to the metadata of this file.
      * @since 2.0.0
      */
     async stat() {
@@ -266,6 +278,7 @@ class FileHandle extends core.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) {
@@ -292,6 +305,8 @@ class FileHandle extends core.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) {
@@ -313,6 +328,9 @@ class FileHandle extends core.Resource {
  * 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(path, options) {
@@ -339,6 +357,9 @@ async function create(path, options) {
  * 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(path, options) {
@@ -359,6 +380,9 @@ async function open(path, options) {
  * 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(fromPath, toPath, options) {
@@ -380,6 +404,8 @@ async function copyFile(fromPath, toPath, options) {
  * 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(path, options) {
@@ -397,20 +423,23 @@ async function mkdir(path, options) {
  * ```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(path, options) {
@@ -431,6 +460,9 @@ async function readDir(path, options) {
  * 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(path, options) {
@@ -451,17 +483,13 @@ async function readFile(path, options) {
  * 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(path, options) {
-    if (path instanceof URL && path.protocol !== 'file:') {
-        throw new TypeError('Must be a file URL.');
-    }
-    const arr = await core.invoke('plugin:fs|read_text_file', {
-        path: path instanceof URL ? path.toString() : path,
-        options
-    });
-    const bytes = arr instanceof ArrayBuffer ? arr : Uint8Array.from(arr);
+    const bytes = await readFile(path, options);
     return new TextDecoder(options?.encoding ?? 'utf-8').decode(bytes);
 }
 /**
@@ -477,6 +505,9 @@ async function readTextFile(path, options) {
  * 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(path, options) {
@@ -497,7 +528,15 @@ async function readTextFileLines(path, options) {
                     options: options != null ? { ...options, encoding } : undefined
                 });
             }
-            const arr = await core.invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
+            let arr;
+            try {
+                arr = await core.invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
+            }
+            catch (error) {
+                // the resource is closed on errors, the next iteration starts over
+                this.rid = null;
+                throw error;
+            }
             const bytes = arr instanceof ArrayBuffer ? new Uint8Array(arr) : Uint8Array.from(arr);
             // Rust side will never return an empty array for this command and
             // ensure there is at least one elements there.
@@ -516,6 +555,16 @@ async function readTextFileLines(path, options) {
                 done
             };
         },
+        // called when a `for await` loop exits early (`break`, `return` or `throw`)
+        async return() {
+            if (this.rid !== null) {
+                const rid = this.rid;
+                this.rid = null;
+                // close the file, otherwise it stays open until the webview is destroyed
+                await new core.Resource(rid).close();
+            }
+            return { value: null, done: true };
+        },
         [Symbol.asyncIterator]() {
             return this;
         }
@@ -531,6 +580,8 @@ async function readTextFileLines(path, options) {
  * 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(path, options) {
@@ -555,6 +606,9 @@ async function remove(path, options) {
  * 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(oldPath, newPath, options) {
@@ -579,6 +633,9 @@ async function rename(oldPath, newPath, options) {
  * 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(path, options) {
@@ -600,6 +657,9 @@ async function stat(path, options) {
  * 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(path, options) {
@@ -627,6 +687,9 @@ async function lstat(path, options) {
  * 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(path, len, options) {
@@ -650,6 +713,9 @@ async function truncate(path, len, options) {
  * 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(path, data, options) {
@@ -687,27 +753,22 @@ async function writeFile(path, data, options) {
     }
 }
 /**
-  * 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, data, options) {
-    if (path instanceof URL && path.protocol !== 'file:') {
-        throw new TypeError('Must be a file URL.');
-    }
-    const encoder = new TextEncoder();
-    await core.invoke('plugin:fs|write_text_file', encoder.encode(data), {
-        headers: {
-            path: encodeURIComponent(path instanceof URL ? path.toString() : path),
-            options: JSON.stringify(options)
-        }
-    });
+    await writeFile(path, new TextEncoder().encode(data), options);
 }
 /**
  * Check if a path exists.
@@ -718,6 +779,9 @@ async function writeTextFile(path, data, options) {
  * 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(path, options) {
@@ -729,6 +793,11 @@ async function exists(path, options) {
         options
     });
 }
+/**
+ * A file system watcher. Call {@linkcode Watcher.close} to stop watching.
+ *
+ * @since 3.0.0
+ */
 class Watcher extends core.Resource {
 }
 async function watchInternal(paths, cb, options) {
@@ -745,15 +814,19 @@ async function watchInternal(paths, cb, options) {
         options,
         onEvent
     });
-    const watcher = new Watcher(rid);
-    return () => {
-        void watcher.close();
-    };
+    return new Watcher(rid);
 }
-// TODO: Return `Watcher` instead in v3
 /**
  * Watch changes (after a delay) on files or directories.
  *
+ * @example
+ * ```typescript
+ * import { watch, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * const watcher = await watch('app.conf', (event) => console.log(event), { baseDir: BaseDirectory.AppConfig });
+ * // when you're done watching:
+ * await watcher.close();
+ * ```
+ *
  * @since 2.0.0
  */
 async function watch(paths, cb, options) {
@@ -762,10 +835,17 @@ async function watch(paths, cb, options) {
         ...options
     });
 }
-// TODO: Return `Watcher` instead in v3
 /**
  * Watch changes on files or directories.
  *
+ * @example
+ * ```typescript
+ * import { watchImmediate, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * const watcher = await watchImmediate('app.conf', (event) => console.log(event), { baseDir: BaseDirectory.AppConfig });
+ * // when you're done watching:
+ * await watcher.close();
+ * ```
+ *
  * @since 2.0.0
  */
 async function watchImmediate(paths, cb, options) {
@@ -787,14 +867,18 @@ async function watchImmediate(paths, cb, options) {
  * console.log(dirSize); // 1024
  * ```
  *
+ * @param path The path of the file or directory to measure.
+ * @param options Options defining the base directory of `path` (since 2.6.0).
+ * @returns A promise resolving to the size in bytes.
  * @since 2.1.0
  */
-async function size(path) {
+async function size(path, options) {
     if (path instanceof URL && path.protocol !== 'file:') {
         throw new TypeError('Must be a file URL.');
     }
     return await core.invoke('plugin:fs|size', {
-        path: path instanceof URL ? path.toString() : path
+        path: path instanceof URL ? path.toString() : path,
+        options
     });
 }
 /**
@@ -821,6 +905,7 @@ async function size(path) {
  * // ... use the resource ...
  * ```
  *
+ * @param path The path or `file://` URL of the resource to start accessing.
  * @since 2.5.0
  */
 async function startAccessingSecurityScopedResource(path) {
@@ -852,6 +937,7 @@ async function startAccessingSecurityScopedResource(path) {
  * await stopAccessingSecurityScopedResource(filePath);
  * ```
  *
+ * @param path The path or `file://` URL of the resource to stop accessing.
  * @since 2.5.0
  */
 async function stopAccessingSecurityScopedResource(path) {
@@ -864,10 +950,11 @@ async function stopAccessingSecurityScopedResource(path) {
 }
 
 Object.defineProperty(exports, "BaseDirectory", {
-  enumerable: true,
-  get: function () { return path.BaseDirectory; }
+    enumerable: true,
+    get: function () { return path.BaseDirectory; }
 });
 exports.FileHandle = FileHandle;
+exports.Watcher = Watcher;
 exports.copyFile = copyFile;
 exports.create = create;
 exports.exists = exists;

package/dist-js/index.d.ts

@@ -82,9 +82,15 @@
  */
 import { BaseDirectory } from '@tauri-apps/api/path';
 import { Resource } from '@tauri-apps/api/core';
+/**
+ * Defines how the offset given to {@linkcode FileHandle.seek} is interpreted.
+ */
 declare 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
 }
 /**
@@ -251,6 +257,8 @@ declare 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
      */
     read(buffer: Uint8Array): Promise<number | null>;
@@ -284,6 +292,9 @@ declare 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
      */
     seek(offset: number, whence: SeekMode): Promise<number>;
@@ -299,6 +310,7 @@ declare class FileHandle extends Resource {
      * await file.close();
      * ```
      *
+     * @returns A promise resolving to the metadata of this file.
      * @since 2.0.0
      */
     stat(): Promise<FileInfo>;
@@ -324,6 +336,7 @@ declare 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
      */
     truncate(len?: number): Promise<void>;
@@ -345,11 +358,15 @@ declare 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
      */
     write(data: Uint8Array): Promise<number>;
 }
 /**
+ * Options for the `create` function, which creates or truncates a file.
+ *
  * @since 2.0.0
  */
 interface CreateOptions {
@@ -368,10 +385,15 @@ 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
  */
 declare function create(path: string | URL, options?: CreateOptions): Promise<FileHandle>;
 /**
+ * Options for the `open` function, defining how the file is opened and which operations are allowed on it.
+ *
  * @since 2.0.0
  */
 interface OpenOptions {
@@ -437,10 +459,15 @@ 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
  */
 declare function open(path: string | URL, options?: OpenOptions): Promise<FileHandle>;
 /**
+ * Options for the `copyFile` function, defining the base directory of each path.
+ *
  * @since 2.0.0
  */
 interface CopyFileOptions {
@@ -457,10 +484,15 @@ 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
  */
 declare function copyFile(fromPath: string | URL, toPath: string | URL, options?: CopyFileOptions): Promise<void>;
 /**
+ * Options for the `mkdir` function, which creates a directory.
+ *
  * @since 2.0.0
  */
 interface MkdirOptions {
@@ -481,10 +513,14 @@ 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
  */
 declare function mkdir(path: string | URL, options?: MkdirOptions): Promise<void>;
 /**
+ * Options for the `readDir` function, which lists the entries of a directory.
+ *
  * @since 2.0.0
  */
 interface ReadDirOptions {
@@ -514,24 +550,29 @@ 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
  */
 declare function readDir(path: string | URL, options?: ReadDirOptions): Promise<DirEntry[]>;
 /**
+ * Options for the functions that read a file, such as `readFile` and `readTextFile`.
+ *
  * @since 2.0.0
  */
 interface ReadFileOptions {
@@ -549,6 +590,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
  */
 declare function readFile(path: string | URL, options?: ReadFileOptions): Promise<Uint8Array<ArrayBuffer>>;
@@ -560,6 +604,9 @@ declare function readFile(path: string | URL, options?: ReadFileOptions): Promis
  * 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
  */
 declare function readTextFile(path: string | URL, options?: ReadFileOptions): Promise<string>;
@@ -576,10 +623,15 @@ declare function readTextFile(path: string | URL, options?: ReadFileOptions): Pr
  * 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
  */
 declare function readTextFileLines(path: string | URL, options?: ReadFileOptions): Promise<AsyncIterableIterator<string>>;
 /**
+ * Options for the `remove` function, which deletes a file or a directory.
+ *
  * @since 2.0.0
  */
 interface RemoveOptions {
@@ -598,10 +650,14 @@ 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
  */
 declare function remove(path: string | URL, options?: RemoveOptions): Promise<void>;
 /**
+ * Options for the `rename` function, defining the base directory of each path.
+ *
  * @since 2.0.0
  */
 interface RenameOptions {
@@ -623,10 +679,15 @@ 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
  */
 declare function rename(oldPath: string | URL, newPath: string | URL, options?: RenameOptions): Promise<void>;
 /**
+ * Options for the `stat` and `lstat` functions, which read the metadata of a path.
+ *
  * @since 2.0.0
  */
 interface StatOptions {
@@ -644,6 +705,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
  */
 declare function stat(path: string | URL, options?: StatOptions): Promise<FileInfo>;
@@ -659,10 +723,15 @@ declare function stat(path: string | URL, options?: StatOptions): Promise<FileIn
  * 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
  */
 declare function lstat(path: string | URL, options?: StatOptions): Promise<FileInfo>;
 /**
+ * Options for the `truncate` function, which truncates or extends a file.
+ *
  * @since 2.0.0
  */
 interface TruncateOptions {
@@ -687,10 +756,15 @@ 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
  */
 declare function truncate(path: string | URL, len?: number, options?: TruncateOptions): Promise<void>;
 /**
+ * Options for the `writeFile` and `writeTextFile` functions, defining how the file is opened before writing to it.
+ *
  * @since 2.0.0
  */
 interface WriteFileOptions {
@@ -716,22 +790,31 @@ 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
  */
 declare function writeFile(path: string | URL, data: Uint8Array | ReadableStream<Uint8Array>, options?: WriteFileOptions): Promise<void>;
 /**
-  * 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
+ */
 declare function writeTextFile(path: string | URL, data: string, options?: WriteFileOptions): Promise<void>;
 /**
+ * Options for the `exists` function, which checks whether a path exists.
+ *
  * @since 2.0.0
  */
 interface ExistsOptions {
@@ -747,10 +830,15 @@ 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
  */
 declare function exists(path: string | URL, options?: ExistsOptions): Promise<boolean>;
 /**
+ * Options for the `watchImmediate` function, which reports file system changes as they happen.
+ *
  * @since 2.0.0
  */
 interface WatchOptions {
@@ -760,33 +848,78 @@ interface WatchOptions {
     baseDir?: BaseDirectory;
 }
 /**
+ * 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;
 }
 /**
+ * Additional attributes of a {@linkcode WatchEvent}.
+ *
+ * @since 3.0.0
+ */
+interface WatchEventAttributes {
+    /** Tracker ID that groups related events, e.g. both sides of a rename. */
+    tracker?: number;
+    /**
+     * `rescan` means some events may have been missed, so any file or folder might have been modified.
+     */
+    flag?: 'rescan';
+    /** Short string identifying the details of an `other` event. */
+    info?: string;
+    /** Short string identifying the backend that generated the event. */
+    source?: string;
+}
+/**
+ * A file system event.
+ *
+ * The event kind is flattened into the event: `type` is the top-level kind and,
+ * for `access`, `create`, `modify` and `remove` events, `kind` (and `mode` when available)
+ * refines it.
+ *
+ * @example
+ * ```typescript
+ * import { watch } from '@tauri-apps/plugin-fs';
+ * await watch('/path/to/file', (event) => {
+ *   if (event.type === 'modify' && event.kind === 'data') {
+ *     console.log('data changed', event.paths, event.mode);
+ *   }
+ * });
+ * ```
+ *
  * @since 2.0.0
  */
-interface WatchEvent {
-    type: WatchEventKind;
+type WatchEvent = WatchEventKind & {
     paths: string[];
-    attrs: unknown;
-}
+    attrs: WatchEventAttributes;
+};
 /**
+ * The kind of file system change described by a `WatchEvent`.
+ *
  * @since 2.0.0
  */
-type WatchEventKind = 'any' | {
-    access: WatchEventKindAccess;
-} | {
-    create: WatchEventKindCreate;
-} | {
-    modify: WatchEventKindModify;
-} | {
-    remove: WatchEventKindRemove;
-} | 'other';
+type WatchEventKind = {
+    type: 'any';
+} | ({
+    type: 'access';
+} & WatchEventKindAccess) | ({
+    type: 'create';
+} & WatchEventKindCreate) | ({
+    type: 'modify';
+} & WatchEventKindModify) | ({
+    type: 'remove';
+} & WatchEventKindRemove) | {
+    type: 'other';
+};
 /**
+ * Describes how a file or directory was accessed.
+ *
  * @since 2.0.0
  */
 type WatchEventKindAccess = {
@@ -801,6 +934,8 @@ type WatchEventKindAccess = {
     kind: 'other';
 };
 /**
+ * Describes which kind of entry was created.
+ *
  * @since 2.0.0
  */
 type WatchEventKindCreate = {
@@ -813,6 +948,8 @@ type WatchEventKindCreate = {
     kind: 'other';
 };
 /**
+ * Describes what was modified on a file or directory.
+ *
  * @since 2.0.0
  */
 type WatchEventKindModify = {
@@ -830,6 +967,8 @@ type WatchEventKindModify = {
     kind: 'other';
 };
 /**
+ * Describes which kind of entry was removed.
+ *
  * @since 2.0.0
  */
 type WatchEventKindRemove = {
@@ -842,21 +981,49 @@ type WatchEventKindRemove = {
     kind: 'other';
 };
 /**
- * @since 2.0.0
+ * A file system watcher. Call {@linkcode Watcher.close} to stop watching.
+ *
+ * @since 3.0.0
  */
-type UnwatchFn = () => void;
+declare class Watcher extends Resource {
+}
 /**
  * Watch changes (after a delay) on files or directories.
  *
+ * @example
+ * ```typescript
+ * import { watch, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * const watcher = await watch('app.conf', (event) => console.log(event), { baseDir: BaseDirectory.AppConfig });
+ * // when you're done watching:
+ * await watcher.close();
+ * ```
+ *
  * @since 2.0.0
  */
-declare function watch(paths: string | string[] | URL | URL[], cb: (event: WatchEvent) => void, options?: DebouncedWatchOptions): Promise<UnwatchFn>;
+declare function watch(paths: string | string[] | URL | URL[], cb: (event: WatchEvent) => void, options?: DebouncedWatchOptions): Promise<Watcher>;
 /**
  * Watch changes on files or directories.
  *
+ * @example
+ * ```typescript
+ * import { watchImmediate, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * const watcher = await watchImmediate('app.conf', (event) => console.log(event), { baseDir: BaseDirectory.AppConfig });
+ * // when you're done watching:
+ * await watcher.close();
+ * ```
+ *
  * @since 2.0.0
  */
-declare function watchImmediate(paths: string | string[] | URL | URL[], cb: (event: WatchEvent) => void, options?: WatchOptions): Promise<UnwatchFn>;
+declare function watchImmediate(paths: string | string[] | URL | URL[], cb: (event: WatchEvent) => void, options?: WatchOptions): Promise<Watcher>;
+/**
+ * Options for the `size` function.
+ *
+ * @since 2.6.0
+ */
+interface SizeOptions {
+    /** Base directory for `path`. */
+    baseDir?: BaseDirectory;
+}
 /**
  * Get the size of a file or directory. For files, the `stat` functions can be used as well.
  *
@@ -870,9 +1037,12 @@ declare function watchImmediate(paths: string | string[] | URL | URL[], cb: (eve
  * console.log(dirSize); // 1024
  * ```
  *
+ * @param path The path of the file or directory to measure.
+ * @param options Options defining the base directory of `path` (since 2.6.0).
+ * @returns A promise resolving to the size in bytes.
  * @since 2.1.0
  */
-declare function size(path: string | URL): Promise<number>;
+declare function size(path: string | URL, options?: SizeOptions): Promise<number>;
 /**
  * Starts accessing a security-scoped resource for the given file URL.
  * This should be called when you're accessing a file that was opened
@@ -897,6 +1067,7 @@ declare 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
  */
 declare function startAccessingSecurityScopedResource(path: string | URL): Promise<void>;
@@ -921,8 +1092,9 @@ declare function startAccessingSecurityScopedResource(path: string | URL): Promi
  * await stopAccessingSecurityScopedResource(filePath);
  * ```
  *
+ * @param path The path or `file://` URL of the resource to stop accessing.
  * @since 2.5.0
  */
 declare function stopAccessingSecurityScopedResource(path: string | URL): Promise<void>;
-export type { CreateOptions, OpenOptions, CopyFileOptions, MkdirOptions, DirEntry, ReadDirOptions, ReadFileOptions, RemoveOptions, RenameOptions, StatOptions, TruncateOptions, WriteFileOptions, ExistsOptions, FileInfo, WatchOptions, DebouncedWatchOptions, WatchEvent, WatchEventKind, WatchEventKindAccess, WatchEventKindCreate, WatchEventKindModify, WatchEventKindRemove, UnwatchFn };
-export { BaseDirectory, FileHandle, create, open, copyFile, mkdir, readDir, readFile, readTextFile, readTextFileLines, remove, rename, SeekMode, stat, lstat, truncate, writeFile, writeTextFile, exists, watch, watchImmediate, size, startAccessingSecurityScopedResource, stopAccessingSecurityScopedResource };
+export type { CreateOptions, OpenOptions, CopyFileOptions, MkdirOptions, DirEntry, ReadDirOptions, ReadFileOptions, RemoveOptions, RenameOptions, StatOptions, TruncateOptions, WriteFileOptions, ExistsOptions, SizeOptions, FileInfo, WatchOptions, DebouncedWatchOptions, WatchEvent, WatchEventAttributes, WatchEventKind, WatchEventKindAccess, WatchEventKindCreate, WatchEventKindModify, WatchEventKindRemove };
+export { BaseDirectory, FileHandle, Watcher, create, open, copyFile, mkdir, readDir, readFile, readTextFile, readTextFileLines, remove, rename, SeekMode, stat, lstat, truncate, writeFile, writeTextFile, exists, watch, watchImmediate, size, startAccessingSecurityScopedResource, stopAccessingSecurityScopedResource };

package/dist-js/index.js

@@ -86,10 +86,16 @@ import { Resource, invoke, Channel } from '@tauri-apps/api/core';
  *
  * @module
  */
+/**
+ * Defines how the offset given to {@linkcode FileHandle.seek} is interpreted.
+ */
 var SeekMode;
 (function (SeekMode) {
+    /** The offset is relative to the start of the file. */
     SeekMode[SeekMode["Start"] = 0] = "Start";
+    /** The offset is relative to the current cursor position. */
     SeekMode[SeekMode["Current"] = 1] = "Current";
+    /** The offset is relative to the end of the file. */
     SeekMode[SeekMode["End"] = 2] = "End";
 })(SeekMode || (SeekMode = {}));
 function parseFileInfo(r) {
@@ -163,6 +169,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) {
@@ -213,6 +221,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, whence) {
@@ -234,6 +245,7 @@ class FileHandle extends Resource {
      * await file.close();
      * ```
      *
+     * @returns A promise resolving to the metadata of this file.
      * @since 2.0.0
      */
     async stat() {
@@ -264,6 +276,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) {
@@ -290,6 +303,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) {
@@ -311,6 +326,9 @@ class FileHandle extends Resource {
  * 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(path, options) {
@@ -337,6 +355,9 @@ async function create(path, options) {
  * 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(path, options) {
@@ -357,6 +378,9 @@ async function open(path, options) {
  * 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(fromPath, toPath, options) {
@@ -378,6 +402,8 @@ async function copyFile(fromPath, toPath, options) {
  * 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(path, options) {
@@ -395,20 +421,23 @@ async function mkdir(path, options) {
  * ```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(path, options) {
@@ -429,6 +458,9 @@ async function readDir(path, options) {
  * 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(path, options) {
@@ -449,17 +481,13 @@ async function readFile(path, options) {
  * 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(path, options) {
-    if (path instanceof URL && path.protocol !== 'file:') {
-        throw new TypeError('Must be a file URL.');
-    }
-    const arr = await invoke('plugin:fs|read_text_file', {
-        path: path instanceof URL ? path.toString() : path,
-        options
-    });
-    const bytes = arr instanceof ArrayBuffer ? arr : Uint8Array.from(arr);
+    const bytes = await readFile(path, options);
     return new TextDecoder(options?.encoding ?? 'utf-8').decode(bytes);
 }
 /**
@@ -475,6 +503,9 @@ async function readTextFile(path, options) {
  * 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(path, options) {
@@ -495,7 +526,15 @@ async function readTextFileLines(path, options) {
                     options: options != null ? { ...options, encoding } : undefined
                 });
             }
-            const arr = await invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
+            let arr;
+            try {
+                arr = await invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
+            }
+            catch (error) {
+                // the resource is closed on errors, the next iteration starts over
+                this.rid = null;
+                throw error;
+            }
             const bytes = arr instanceof ArrayBuffer ? new Uint8Array(arr) : Uint8Array.from(arr);
             // Rust side will never return an empty array for this command and
             // ensure there is at least one elements there.
@@ -514,6 +553,16 @@ async function readTextFileLines(path, options) {
                 done
             };
         },
+        // called when a `for await` loop exits early (`break`, `return` or `throw`)
+        async return() {
+            if (this.rid !== null) {
+                const rid = this.rid;
+                this.rid = null;
+                // close the file, otherwise it stays open until the webview is destroyed
+                await new Resource(rid).close();
+            }
+            return { value: null, done: true };
+        },
         [Symbol.asyncIterator]() {
             return this;
         }
@@ -529,6 +578,8 @@ async function readTextFileLines(path, options) {
  * 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(path, options) {
@@ -553,6 +604,9 @@ async function remove(path, options) {
  * 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(oldPath, newPath, options) {
@@ -577,6 +631,9 @@ async function rename(oldPath, newPath, options) {
  * 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(path, options) {
@@ -598,6 +655,9 @@ async function stat(path, options) {
  * 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(path, options) {
@@ -625,6 +685,9 @@ async function lstat(path, options) {
  * 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(path, len, options) {
@@ -648,6 +711,9 @@ async function truncate(path, len, options) {
  * 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(path, data, options) {
@@ -685,27 +751,22 @@ async function writeFile(path, data, options) {
     }
 }
 /**
-  * 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, data, options) {
-    if (path instanceof URL && path.protocol !== 'file:') {
-        throw new TypeError('Must be a file URL.');
-    }
-    const encoder = new TextEncoder();
-    await invoke('plugin:fs|write_text_file', encoder.encode(data), {
-        headers: {
-            path: encodeURIComponent(path instanceof URL ? path.toString() : path),
-            options: JSON.stringify(options)
-        }
-    });
+    await writeFile(path, new TextEncoder().encode(data), options);
 }
 /**
  * Check if a path exists.
@@ -716,6 +777,9 @@ async function writeTextFile(path, data, options) {
  * 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(path, options) {
@@ -727,6 +791,11 @@ async function exists(path, options) {
         options
     });
 }
+/**
+ * A file system watcher. Call {@linkcode Watcher.close} to stop watching.
+ *
+ * @since 3.0.0
+ */
 class Watcher extends Resource {
 }
 async function watchInternal(paths, cb, options) {
@@ -743,15 +812,19 @@ async function watchInternal(paths, cb, options) {
         options,
         onEvent
     });
-    const watcher = new Watcher(rid);
-    return () => {
-        void watcher.close();
-    };
+    return new Watcher(rid);
 }
-// TODO: Return `Watcher` instead in v3
 /**
  * Watch changes (after a delay) on files or directories.
  *
+ * @example
+ * ```typescript
+ * import { watch, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * const watcher = await watch('app.conf', (event) => console.log(event), { baseDir: BaseDirectory.AppConfig });
+ * // when you're done watching:
+ * await watcher.close();
+ * ```
+ *
  * @since 2.0.0
  */
 async function watch(paths, cb, options) {
@@ -760,10 +833,17 @@ async function watch(paths, cb, options) {
         ...options
     });
 }
-// TODO: Return `Watcher` instead in v3
 /**
  * Watch changes on files or directories.
  *
+ * @example
+ * ```typescript
+ * import { watchImmediate, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * const watcher = await watchImmediate('app.conf', (event) => console.log(event), { baseDir: BaseDirectory.AppConfig });
+ * // when you're done watching:
+ * await watcher.close();
+ * ```
+ *
  * @since 2.0.0
  */
 async function watchImmediate(paths, cb, options) {
@@ -785,14 +865,18 @@ async function watchImmediate(paths, cb, options) {
  * console.log(dirSize); // 1024
  * ```
  *
+ * @param path The path of the file or directory to measure.
+ * @param options Options defining the base directory of `path` (since 2.6.0).
+ * @returns A promise resolving to the size in bytes.
  * @since 2.1.0
  */
-async function size(path) {
+async function size(path, options) {
     if (path instanceof URL && path.protocol !== 'file:') {
         throw new TypeError('Must be a file URL.');
     }
     return await invoke('plugin:fs|size', {
-        path: path instanceof URL ? path.toString() : path
+        path: path instanceof URL ? path.toString() : path,
+        options
     });
 }
 /**
@@ -819,6 +903,7 @@ async function size(path) {
  * // ... use the resource ...
  * ```
  *
+ * @param path The path or `file://` URL of the resource to start accessing.
  * @since 2.5.0
  */
 async function startAccessingSecurityScopedResource(path) {
@@ -850,6 +935,7 @@ async function startAccessingSecurityScopedResource(path) {
  * await stopAccessingSecurityScopedResource(filePath);
  * ```
  *
+ * @param path The path or `file://` URL of the resource to stop accessing.
  * @since 2.5.0
  */
 async function stopAccessingSecurityScopedResource(path) {
@@ -861,4 +947,4 @@ async function stopAccessingSecurityScopedResource(path) {
     });
 }
 
-export { FileHandle, SeekMode, copyFile, create, exists, lstat, mkdir, open, readDir, readFile, readTextFile, readTextFileLines, remove, rename, size, startAccessingSecurityScopedResource, stat, stopAccessingSecurityScopedResource, truncate, watch, watchImmediate, writeFile, writeTextFile };
+export { FileHandle, SeekMode, Watcher, copyFile, create, exists, lstat, mkdir, open, readDir, readFile, readTextFile, readTextFileLines, remove, rename, size, startAccessingSecurityScopedResource, stat, stopAccessingSecurityScopedResource, truncate, watch, watchImmediate, writeFile, writeTextFile };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tauri-apps/plugin-fs",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.2",
   "description": "Access the file system.",
   "license": "MIT OR Apache-2.0",
   "authors": [