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

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) {
@@ -659,7 +725,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,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 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 +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) {
@@ -727,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 Resource {
 }
 async function watchInternal(paths, cb, options) {
@@ -743,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) {
@@ -760,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) {
@@ -785,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 invoke('plugin:fs|size', {
-        path: path instanceof URL ? path.toString() : path
+        path: path instanceof URL ? path.toString() : path,
+        options
     });
 }
 /**
@@ -819,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) {
@@ -850,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) {
@@ -861,4 +949,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.3",
   "description": "Access the file system.",
   "license": "MIT OR Apache-2.0",
   "authors": [
@@ -25,6 +25,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tauri-apps/api": "^3.0.0-alpha.1"
+    "@tauri-apps/api": "^3.0.0-alpha.2"
   }
 }