@tauri-apps/plugin-fs 2.5.2 → 2.7.0

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.90**_
 
 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,6 +483,9 @@ 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) {
@@ -477,6 +512,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 +535,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 +562,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 +587,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 +613,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 +640,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 +664,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 +694,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 +720,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) {
@@ -661,7 +734,9 @@ async function writeFile(path, data, options) {
             read: false,
             create: true,
             write: true,
-            ...options
+            ...options,
+            // overwrite the previous contents, like when writing a buffer
+            truncate: !options?.append
         });
         const reader = data.getReader();
         try {
@@ -687,16 +762,20 @@ 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.');
@@ -718,6 +797,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) {
@@ -754,6 +836,27 @@ async function watchInternal(paths, cb, options) {
 /**
  * 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(paths, cb, options) {
@@ -766,6 +869,27 @@ async function watch(paths, cb, options) {
 /**
  * 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(paths, cb, options) {
@@ -787,14 +911,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 +949,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 +981,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,8 +994,8 @@ 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.copyFile = copyFile;

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,21 +848,33 @@ 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;
 }
 /**
+ * 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 = 'any' | {
@@ -787,6 +887,8 @@ type WatchEventKind = 'any' | {
     remove: WatchEventKindRemove;
 } | 'other';
 /**
+ * Describes how a file or directory was accessed.
+ *
  * @since 2.0.0
  */
 type WatchEventKindAccess = {
@@ -801,6 +903,8 @@ type WatchEventKindAccess = {
     kind: 'other';
 };
 /**
+ * Describes which kind of entry was created.
+ *
  * @since 2.0.0
  */
 type WatchEventKindCreate = {
@@ -813,6 +917,8 @@ type WatchEventKindCreate = {
     kind: 'other';
 };
 /**
+ * Describes what was modified on a file or directory.
+ *
  * @since 2.0.0
  */
 type WatchEventKindModify = {
@@ -830,6 +936,8 @@ type WatchEventKindModify = {
     kind: 'other';
 };
 /**
+ * Describes which kind of entry was removed.
+ *
  * @since 2.0.0
  */
 type WatchEventKindRemove = {
@@ -842,21 +950,74 @@ type WatchEventKindRemove = {
     kind: 'other';
 };
 /**
+ * Stops watching the paths it was created for. Returned by `watch` and `watchImmediate`.
+ *
  * @since 2.0.0
  */
 type UnwatchFn = () => void;
 /**
  * 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
  */
 declare function watch(paths: string | string[] | URL | URL[], cb: (event: WatchEvent) => void, options?: DebouncedWatchOptions): Promise<UnwatchFn>;
 /**
  * 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
  */
 declare function watchImmediate(paths: string | string[] | URL | URL[], cb: (event: WatchEvent) => void, options?: WatchOptions): Promise<UnwatchFn>;
+/**
+ * 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 +1031,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 +1061,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 +1086,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 type { CreateOptions, OpenOptions, CopyFileOptions, MkdirOptions, DirEntry, ReadDirOptions, ReadFileOptions, RemoveOptions, RenameOptions, StatOptions, TruncateOptions, WriteFileOptions, ExistsOptions, SizeOptions, 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 };

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,6 +481,9 @@ 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) {
@@ -475,6 +510,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 +533,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 +560,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 +585,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 +611,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 +638,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 +662,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 +692,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 +718,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) {
@@ -659,7 +732,9 @@ async function writeFile(path, data, options) {
             read: false,
             create: true,
             write: true,
-            ...options
+            ...options,
+            // overwrite the previous contents, like when writing a buffer
+            truncate: !options?.append
         });
         const reader = data.getReader();
         try {
@@ -685,16 +760,20 @@ 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.');
@@ -716,6 +795,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) {
@@ -752,6 +834,27 @@ async function watchInternal(paths, cb, options) {
 /**
  * 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(paths, cb, options) {
@@ -764,6 +867,27 @@ async function watch(paths, cb, options) {
 /**
  * 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(paths, cb, options) {
@@ -785,14 +909,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 +947,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 +979,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tauri-apps/plugin-fs",
-  "version": "2.5.2",
+  "version": "2.7.0",
   "description": "Access the file system.",
   "license": "MIT OR Apache-2.0",
   "authors": [
@@ -25,6 +25,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tauri-apps/api": "^2.11.0"
+    "@tauri-apps/api": "^2.12.0"
   }
 }