@tauri-apps/plugin-fs 2.0.1 → 2.0.3

package/dist-js/index.cjs

@@ -18,16 +18,29 @@ var core = require('@tauri-apps/api/core');
  *
  * The API has a scope configuration that forces you to restrict the paths that can be accessed using glob patterns.
  *
- * The scope configuration is an array of glob patterns describing folder paths that are allowed.
- * For instance, this scope configuration only allows accessing files on the
- * *databases* folder of the {@link https://v2.tauri.app/reference/javascript/api/namespacepath/#appdatadir | `$APPDATA` directory}:
+ * The scope configuration is an array of glob patterns describing file/directory paths that are allowed.
+ * For instance, this scope configuration allows **all** enabled `fs` APIs to (only) access files in the
+ * *databases* directory of the {@link https://v2.tauri.app/reference/javascript/api/namespacepath/#appdatadir | `$APPDATA` directory}:
  * ```json
  * {
- *   "plugins": {
- *     "fs": {
- *       "scope": ["$APPDATA/databases/*"]
+ *   "permissions": [
+ *     {
+ *       "identifier": "fs:scope",
+ *       "allow": [{ "path": "$APPDATA/databases/*" }]
  *     }
- *   }
+ *   ]
+ * }
+ * ```
+ *
+ * Scopes can also be applied to specific `fs` APIs by using the API's identifier instead of `fs:scope`:
+ * ```json
+ * {
+ *   "permissions": [
+ *     {
+ *       "identifier": "fs:allow-exists",
+ *       "allow": [{ "path": "$APPDATA/databases/*" }]
+ *     }
+ *   ]
  * }
  * ```
  *
@@ -60,8 +73,6 @@ var core = require('@tauri-apps/api/core');
  *
  * Trying to execute any API with a URL not configured on the scope results in a promise rejection due to denied access.
  *
- * Note that this scope applies to **all** APIs on this module.
- *
  * @module
  */
 exports.SeekMode = void 0;
@@ -99,6 +110,7 @@ function fromBytes(buffer) {
     const size = bytes.byteLength;
     let x = 0;
     for (let i = 0; i < size; i++) {
+        // eslint-disable-next-line security/detect-object-injection
         const byte = bytes[i];
         x *= 0x100;
         x += byte;
@@ -250,11 +262,11 @@ class FileHandle extends core.Resource {
         });
     }
     /**
-     * Writes `p.byteLength` bytes from `p` to the underlying data stream. It
-     * resolves to the number of bytes written from `p` (`0` <= `n` <=
-     * `p.byteLength`) or reject with the error encountered that caused the
+     * Writes `data.byteLength` bytes from `data` to the underlying data stream. It
+     * resolves to the number of bytes written from `data` (`0` <= `n` <=
+     * `data.byteLength`) or reject with the error encountered that caused the
      * write to stop early. `write()` must reject with a non-null error if
-     * would resolve to `n` < `p.byteLength`. `write()` must not modify the
+     * would resolve to `n` < `data.byteLength`. `write()` must not modify the
      * slice data, even temporarily.
      *
      * @example
@@ -432,10 +444,12 @@ async function readTextFile(path, options) {
     if (path instanceof URL && path.protocol !== 'file:') {
         throw new TypeError('Must be a file URL.');
     }
-    return await core.invoke('plugin:fs|read_text_file', {
+    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);
+    return new TextDecoder().decode(bytes);
 }
 /**
  * Returns an async {@linkcode AsyncIterableIterator} over the lines of a file as UTF-8 string.
@@ -467,12 +481,22 @@ async function readTextFileLines(path, options) {
                     options
                 });
             }
-            const [line, done] = await core.invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
-            // an iteration is over, reset rid for next iteration
-            if (done)
+            const arr = await core.invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
+            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.
+            //
+            // This is an optimization to include whether we finished iteration or not (1 or 0)
+            // at the end of returned array to avoid serialization overhead of separate values.
+            const done = bytes[bytes.byteLength - 1] === 1;
+            if (done) {
+                // a full iteration is over, reset rid for next iteration
                 this.rid = null;
+                return { value: null, done };
+            }
+            const line = new TextDecoder().decode(bytes.slice(0, bytes.byteLength));
             return {
-                value: done ? '' : line,
+                value: line,
                 done
             };
         },
@@ -616,12 +640,21 @@ async function writeFile(path, data, options) {
     if (path instanceof URL && path.protocol !== 'file:') {
         throw new TypeError('Must be a file URL.');
     }
-    await core.invoke('plugin:fs|write_file', data, {
-        headers: {
-            path: encodeURIComponent(path instanceof URL ? path.toString() : path),
-            options: JSON.stringify(options)
+    if (data instanceof ReadableStream) {
+        const file = await open(path, options);
+        for await (const chunk of data) {
+            await file.write(chunk);
         }
-    });
+        await file.close();
+    }
+    else {
+        await core.invoke('plugin:fs|write_file', data, {
+            headers: {
+                path: encodeURIComponent(path instanceof URL ? path.toString() : path),
+                options: JSON.stringify(options)
+            }
+        });
+    }
 }
 /**
   * Writes UTF-8 string `data` to the given `path`, by default creating a new file if needed, else overwriting.
@@ -641,7 +674,7 @@ async function writeTextFile(path, data, options) {
     const encoder = new TextEncoder();
     await core.invoke('plugin:fs|write_text_file', encoder.encode(data), {
         headers: {
-            path: path instanceof URL ? path.toString() : path,
+            path: encodeURIComponent(path instanceof URL ? path.toString() : path),
             options: JSON.stringify(options)
         }
     });
@@ -725,6 +758,29 @@ async function watchImmediate(paths, cb, options) {
         void unwatch(rid);
     };
 }
+/**
+ * Get the size of a file or directory. For files, the `stat` functions can be used as well.
+ *
+ * If `path` is a directory, this function will recursively iterate over every file and every directory inside of `path` and therefore will be very time consuming if used on larger directories.
+ *
+ * @example
+ * ```typescript
+ * import { size, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * // Get the size of the `$APPDATA/tauri` directory.
+ * const dirSize = await size('tauri', { baseDir: BaseDirectory.AppData });
+ * console.log(dirSize); // 1024
+ * ```
+ *
+ * @since 2.1.0
+ */
+async function size(path) {
+    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
+    });
+}
 
 Object.defineProperty(exports, "BaseDirectory", {
   enumerable: true,
@@ -743,6 +799,7 @@ exports.readTextFile = readTextFile;
 exports.readTextFileLines = readTextFileLines;
 exports.remove = remove;
 exports.rename = rename;
+exports.size = size;
 exports.stat = stat;
 exports.truncate = truncate;
 exports.watch = watch;

package/dist-js/index.d.ts

@@ -10,16 +10,29 @@
  *
  * The API has a scope configuration that forces you to restrict the paths that can be accessed using glob patterns.
  *
- * The scope configuration is an array of glob patterns describing folder paths that are allowed.
- * For instance, this scope configuration only allows accessing files on the
- * *databases* folder of the {@link https://v2.tauri.app/reference/javascript/api/namespacepath/#appdatadir | `$APPDATA` directory}:
+ * The scope configuration is an array of glob patterns describing file/directory paths that are allowed.
+ * For instance, this scope configuration allows **all** enabled `fs` APIs to (only) access files in the
+ * *databases* directory of the {@link https://v2.tauri.app/reference/javascript/api/namespacepath/#appdatadir | `$APPDATA` directory}:
  * ```json
  * {
- *   "plugins": {
- *     "fs": {
- *       "scope": ["$APPDATA/databases/*"]
+ *   "permissions": [
+ *     {
+ *       "identifier": "fs:scope",
+ *       "allow": [{ "path": "$APPDATA/databases/*" }]
  *     }
- *   }
+ *   ]
+ * }
+ * ```
+ *
+ * Scopes can also be applied to specific `fs` APIs by using the API's identifier instead of `fs:scope`:
+ * ```json
+ * {
+ *   "permissions": [
+ *     {
+ *       "identifier": "fs:allow-exists",
+ *       "allow": [{ "path": "$APPDATA/databases/*" }]
+ *     }
+ *   ]
  * }
  * ```
  *
@@ -52,8 +65,6 @@
  *
  * Trying to execute any API with a URL not configured on the scope results in a promise rejection due to denied access.
  *
- * Note that this scope applies to **all** APIs on this module.
- *
  * @module
  */
 import { BaseDirectory } from '@tauri-apps/api/path';
@@ -304,11 +315,11 @@ declare class FileHandle extends Resource {
      */
     truncate(len?: number): Promise<void>;
     /**
-     * Writes `p.byteLength` bytes from `p` to the underlying data stream. It
-     * resolves to the number of bytes written from `p` (`0` <= `n` <=
-     * `p.byteLength`) or reject with the error encountered that caused the
+     * Writes `data.byteLength` bytes from `data` to the underlying data stream. It
+     * resolves to the number of bytes written from `data` (`0` <= `n` <=
+     * `data.byteLength`) or reject with the error encountered that caused the
      * write to stop early. `write()` must reject with a non-null error if
-     * would resolve to `n` < `p.byteLength`. `write()` must not modify the
+     * would resolve to `n` < `data.byteLength`. `write()` must not modify the
      * slice data, even temporarily.
      *
      * @example
@@ -692,7 +703,7 @@ interface WriteFileOptions {
  *
  * @since 2.0.0
  */
-declare function writeFile(path: string | URL, data: Uint8Array, options?: WriteFileOptions): Promise<void>;
+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
@@ -831,5 +842,21 @@ declare function watch(paths: string | string[] | URL | URL[], cb: (event: Watch
  * @since 2.0.0
  */
 declare function watchImmediate(paths: string | string[] | URL | URL[], cb: (event: WatchEvent) => void, options?: WatchOptions): Promise<UnwatchFn>;
+/**
+ * Get the size of a file or directory. For files, the `stat` functions can be used as well.
+ *
+ * If `path` is a directory, this function will recursively iterate over every file and every directory inside of `path` and therefore will be very time consuming if used on larger directories.
+ *
+ * @example
+ * ```typescript
+ * import { size, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * // Get the size of the `$APPDATA/tauri` directory.
+ * const dirSize = await size('tauri', { baseDir: BaseDirectory.AppData });
+ * console.log(dirSize); // 1024
+ * ```
+ *
+ * @since 2.1.0
+ */
+declare function size(path: string | URL): Promise<number>;
 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 };
+export { BaseDirectory, FileHandle, create, open, copyFile, mkdir, readDir, readFile, readTextFile, readTextFileLines, remove, rename, SeekMode, stat, lstat, truncate, writeFile, writeTextFile, exists, watch, watchImmediate, size };

package/dist-js/index.js

@@ -16,16 +16,29 @@ import { Resource, invoke, Channel } from '@tauri-apps/api/core';
  *
  * The API has a scope configuration that forces you to restrict the paths that can be accessed using glob patterns.
  *
- * The scope configuration is an array of glob patterns describing folder paths that are allowed.
- * For instance, this scope configuration only allows accessing files on the
- * *databases* folder of the {@link https://v2.tauri.app/reference/javascript/api/namespacepath/#appdatadir | `$APPDATA` directory}:
+ * The scope configuration is an array of glob patterns describing file/directory paths that are allowed.
+ * For instance, this scope configuration allows **all** enabled `fs` APIs to (only) access files in the
+ * *databases* directory of the {@link https://v2.tauri.app/reference/javascript/api/namespacepath/#appdatadir | `$APPDATA` directory}:
  * ```json
  * {
- *   "plugins": {
- *     "fs": {
- *       "scope": ["$APPDATA/databases/*"]
+ *   "permissions": [
+ *     {
+ *       "identifier": "fs:scope",
+ *       "allow": [{ "path": "$APPDATA/databases/*" }]
  *     }
- *   }
+ *   ]
+ * }
+ * ```
+ *
+ * Scopes can also be applied to specific `fs` APIs by using the API's identifier instead of `fs:scope`:
+ * ```json
+ * {
+ *   "permissions": [
+ *     {
+ *       "identifier": "fs:allow-exists",
+ *       "allow": [{ "path": "$APPDATA/databases/*" }]
+ *     }
+ *   ]
  * }
  * ```
  *
@@ -58,8 +71,6 @@ import { Resource, invoke, Channel } from '@tauri-apps/api/core';
  *
  * Trying to execute any API with a URL not configured on the scope results in a promise rejection due to denied access.
  *
- * Note that this scope applies to **all** APIs on this module.
- *
  * @module
  */
 var SeekMode;
@@ -97,6 +108,7 @@ function fromBytes(buffer) {
     const size = bytes.byteLength;
     let x = 0;
     for (let i = 0; i < size; i++) {
+        // eslint-disable-next-line security/detect-object-injection
         const byte = bytes[i];
         x *= 0x100;
         x += byte;
@@ -248,11 +260,11 @@ class FileHandle extends Resource {
         });
     }
     /**
-     * Writes `p.byteLength` bytes from `p` to the underlying data stream. It
-     * resolves to the number of bytes written from `p` (`0` <= `n` <=
-     * `p.byteLength`) or reject with the error encountered that caused the
+     * Writes `data.byteLength` bytes from `data` to the underlying data stream. It
+     * resolves to the number of bytes written from `data` (`0` <= `n` <=
+     * `data.byteLength`) or reject with the error encountered that caused the
      * write to stop early. `write()` must reject with a non-null error if
-     * would resolve to `n` < `p.byteLength`. `write()` must not modify the
+     * would resolve to `n` < `data.byteLength`. `write()` must not modify the
      * slice data, even temporarily.
      *
      * @example
@@ -430,10 +442,12 @@ async function readTextFile(path, options) {
     if (path instanceof URL && path.protocol !== 'file:') {
         throw new TypeError('Must be a file URL.');
     }
-    return await invoke('plugin:fs|read_text_file', {
+    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);
+    return new TextDecoder().decode(bytes);
 }
 /**
  * Returns an async {@linkcode AsyncIterableIterator} over the lines of a file as UTF-8 string.
@@ -465,12 +479,22 @@ async function readTextFileLines(path, options) {
                     options
                 });
             }
-            const [line, done] = await invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
-            // an iteration is over, reset rid for next iteration
-            if (done)
+            const arr = await invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
+            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.
+            //
+            // This is an optimization to include whether we finished iteration or not (1 or 0)
+            // at the end of returned array to avoid serialization overhead of separate values.
+            const done = bytes[bytes.byteLength - 1] === 1;
+            if (done) {
+                // a full iteration is over, reset rid for next iteration
                 this.rid = null;
+                return { value: null, done };
+            }
+            const line = new TextDecoder().decode(bytes.slice(0, bytes.byteLength));
             return {
-                value: done ? '' : line,
+                value: line,
                 done
             };
         },
@@ -614,12 +638,21 @@ async function writeFile(path, data, options) {
     if (path instanceof URL && path.protocol !== 'file:') {
         throw new TypeError('Must be a file URL.');
     }
-    await invoke('plugin:fs|write_file', data, {
-        headers: {
-            path: encodeURIComponent(path instanceof URL ? path.toString() : path),
-            options: JSON.stringify(options)
+    if (data instanceof ReadableStream) {
+        const file = await open(path, options);
+        for await (const chunk of data) {
+            await file.write(chunk);
         }
-    });
+        await file.close();
+    }
+    else {
+        await invoke('plugin:fs|write_file', data, {
+            headers: {
+                path: encodeURIComponent(path instanceof URL ? path.toString() : path),
+                options: JSON.stringify(options)
+            }
+        });
+    }
 }
 /**
   * Writes UTF-8 string `data` to the given `path`, by default creating a new file if needed, else overwriting.
@@ -639,7 +672,7 @@ async function writeTextFile(path, data, options) {
     const encoder = new TextEncoder();
     await invoke('plugin:fs|write_text_file', encoder.encode(data), {
         headers: {
-            path: path instanceof URL ? path.toString() : path,
+            path: encodeURIComponent(path instanceof URL ? path.toString() : path),
             options: JSON.stringify(options)
         }
     });
@@ -723,5 +756,28 @@ async function watchImmediate(paths, cb, options) {
         void unwatch(rid);
     };
 }
+/**
+ * Get the size of a file or directory. For files, the `stat` functions can be used as well.
+ *
+ * If `path` is a directory, this function will recursively iterate over every file and every directory inside of `path` and therefore will be very time consuming if used on larger directories.
+ *
+ * @example
+ * ```typescript
+ * import { size, BaseDirectory } from '@tauri-apps/plugin-fs';
+ * // Get the size of the `$APPDATA/tauri` directory.
+ * const dirSize = await size('tauri', { baseDir: BaseDirectory.AppData });
+ * console.log(dirSize); // 1024
+ * ```
+ *
+ * @since 2.1.0
+ */
+async function size(path) {
+    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
+    });
+}
 
-export { FileHandle, SeekMode, copyFile, create, exists, lstat, mkdir, open, readDir, readFile, readTextFile, readTextFileLines, remove, rename, stat, truncate, watch, watchImmediate, writeFile, writeTextFile };
+export { FileHandle, SeekMode, copyFile, create, exists, lstat, mkdir, open, readDir, readFile, readTextFile, readTextFileLines, remove, rename, size, stat, truncate, watch, watchImmediate, writeFile, writeTextFile };

package/package.json

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