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

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) {
@@ -661,7 +727,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,27 +755,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 +781,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 +795,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 +816,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 +837,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 +869,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 +907,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 +939,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 +952,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;