@tauri-apps/plugin-fs 2.4.5 → 2.5.1

package/dist-js/index.cjs

@@ -9,6 +9,19 @@ var core = require('@tauri-apps/api/core');
 /**
  * Access the file system.
  *
+ * ## iOS security-scoped resources
+ *
+ * On iOS, the `fs` plugin automatically manages access to security-scoped resources when a file URL is accessed.
+ * This is required for files outside the app's sandbox (e.g., from file picker).
+ *
+ * @example
+ * ```typescript
+ * import { open } from '@tauri-apps/plugin-fs';
+ *
+ * const file = await open('file:///path/to/file.txt');
+ * await file.close();
+ * ```
+ *
  * ## Security
  *
  * This module prevents path traversal, not allowing parent directory accessors to be used
@@ -431,7 +444,7 @@ async function readFile(path, options) {
     return arr instanceof ArrayBuffer ? new Uint8Array(arr) : Uint8Array.from(arr);
 }
 /**
- * Reads and returns the entire contents of a file as UTF-8 string.
+ * Reads and returns the entire contents of a file as a string using the specified encoding (default: UTF-8).
  * @example
  * ```typescript
  * import { readTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
@@ -449,10 +462,10 @@ async function readTextFile(path, options) {
         options
     });
     const bytes = arr instanceof ArrayBuffer ? arr : Uint8Array.from(arr);
-    return new TextDecoder().decode(bytes);
+    return new TextDecoder(options?.encoding ?? 'utf-8').decode(bytes);
 }
 /**
- * Returns an async {@linkcode AsyncIterableIterator} over the lines of a file as UTF-8 string.
+ * Returns an async {@linkcode AsyncIterableIterator} over the lines of a file, decoded using the specified encoding (default: UTF-8).
  * @example
  * ```typescript
  * import { readTextFileLines, BaseDirectory } from '@tauri-apps/plugin-fs';
@@ -475,10 +488,13 @@ async function readTextFileLines(path, options) {
         path: pathStr,
         rid: null,
         async next() {
+            const decoder = new TextDecoder(options?.encoding ?? 'utf-8');
             if (this.rid === null) {
+                // Use the normalized encoding label for options.
+                const encoding = decoder.encoding;
                 this.rid = await core.invoke('plugin:fs|read_text_file_lines', {
                     path: pathStr,
-                    options
+                    options: options != null ? { ...options, encoding } : undefined
                 });
             }
             const arr = await core.invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
@@ -494,7 +510,7 @@ async function readTextFileLines(path, options) {
                 this.rid = null;
                 return { value: null, done };
             }
-            const line = new TextDecoder().decode(bytes.slice(0, bytes.byteLength - 1));
+            const line = decoder.decode(bytes.slice(0, bytes.byteLength - 1));
             return {
                 value: line,
                 done
@@ -781,6 +797,71 @@ async function size(path) {
         path: path instanceof URL ? path.toString() : path
     });
 }
+/**
+ * Starts accessing a security-scoped resource for the given file URL.
+ * This should be called when you're accessing a file that was opened
+ * using a security-scoped URL (e.g., from a file picker).
+ *
+ * Note that accessing security-scoped resources is automatically managed by the plugin on iOS, so you don't need to call this function
+ * unless you want to manage the scope manually.
+ *
+ * You must call {@linkcode stopAccessingSecurityScopedResource} when you're done accessing the resource.
+ *
+ * #### Platform-specific
+ *
+ * - **iOS:** Starts accessing the security-scoped resource.
+ * - **Other platforms:** does nothing.
+ *
+ * @example
+ * ```typescript
+ * import { startAccessingSecurityScopedResource } from '@tauri-apps/plugin-fs';
+ *
+ * const filePath = 'file:///path/to/file.txt';
+ * await startAccessingSecurityScopedResource(filePath);
+ * // ... use the resource ...
+ * ```
+ *
+ * @since 2.5.0
+ */
+async function startAccessingSecurityScopedResource(path) {
+    if (path instanceof URL && path.protocol !== 'file:') {
+        throw new TypeError('Must be a file URL.');
+    }
+    await core.invoke('plugin:fs|start_accessing_security_scoped_resource', {
+        path: path instanceof URL ? path.toString() : path
+    });
+}
+/**
+ * Stops accessing a security-scoped resource for the given file URL.
+ * This should be called when you're done accessing a file that was opened
+ * using a security-scoped URL (e.g., from a file picker) when using manual tracking via {@linkcode startAccessingSecurityScopedResource}.
+ *
+ * #### Platform-specific
+ *
+ * - **iOS:** Stops accessing the security-scoped resource.
+ * - **Other platforms:** does nothing.
+ *
+ * @example
+ * ```typescript
+ * import { stopAccessingSecurityScopedResource } from '@tauri-apps/plugin-fs';
+ *
+ * const filePath = 'file:///path/to/file.txt';
+ * await startAccessingSecurityScopedResource(filePath);
+ * // ... use the resource ...
+ * // when you're done with the resource:
+ * await stopAccessingSecurityScopedResource(filePath);
+ * ```
+ *
+ * @since 2.5.0
+ */
+async function stopAccessingSecurityScopedResource(path) {
+    if (path instanceof URL && path.protocol !== 'file:') {
+        throw new TypeError('Must be a file URL.');
+    }
+    await core.invoke('plugin:fs|stop_accessing_security_scoped_resource', {
+        path: path instanceof URL ? path.toString() : path
+    });
+}
 
 Object.defineProperty(exports, "BaseDirectory", {
   enumerable: true,
@@ -800,7 +881,9 @@ exports.readTextFileLines = readTextFileLines;
 exports.remove = remove;
 exports.rename = rename;
 exports.size = size;
+exports.startAccessingSecurityScopedResource = startAccessingSecurityScopedResource;
 exports.stat = stat;
+exports.stopAccessingSecurityScopedResource = stopAccessingSecurityScopedResource;
 exports.truncate = truncate;
 exports.watch = watch;
 exports.watchImmediate = watchImmediate;

package/dist-js/index.d.ts

@@ -1,6 +1,19 @@
 /**
  * Access the file system.
  *
+ * ## iOS security-scoped resources
+ *
+ * On iOS, the `fs` plugin automatically manages access to security-scoped resources when a file URL is accessed.
+ * This is required for files outside the app's sandbox (e.g., from file picker).
+ *
+ * @example
+ * ```typescript
+ * import { open } from '@tauri-apps/plugin-fs';
+ *
+ * const file = await open('file:///path/to/file.txt');
+ * await file.close();
+ * ```
+ *
  * ## Security
  *
  * This module prevents path traversal, not allowing parent directory accessors to be used
@@ -524,6 +537,8 @@ declare function readDir(path: string | URL, options?: ReadDirOptions): Promise<
 interface ReadFileOptions {
     /** Base directory for `path` */
     baseDir?: BaseDirectory;
+    /** Text encoding to use when reading a text file. Defaults to 'utf-8'. */
+    encoding?: string;
 }
 /**
  * Reads and resolves to the entire contents of a file as an array of bytes.
@@ -538,7 +553,7 @@ interface ReadFileOptions {
  */
 declare function readFile(path: string | URL, options?: ReadFileOptions): Promise<Uint8Array<ArrayBuffer>>;
 /**
- * Reads and returns the entire contents of a file as UTF-8 string.
+ * Reads and returns the entire contents of a file as a string using the specified encoding (default: UTF-8).
  * @example
  * ```typescript
  * import { readTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
@@ -549,7 +564,7 @@ declare function readFile(path: string | URL, options?: ReadFileOptions): Promis
  */
 declare function readTextFile(path: string | URL, options?: ReadFileOptions): Promise<string>;
 /**
- * Returns an async {@linkcode AsyncIterableIterator} over the lines of a file as UTF-8 string.
+ * Returns an async {@linkcode AsyncIterableIterator} over the lines of a file, decoded using the specified encoding (default: UTF-8).
  * @example
  * ```typescript
  * import { readTextFileLines, BaseDirectory } from '@tauri-apps/plugin-fs';
@@ -858,5 +873,56 @@ declare function watchImmediate(paths: string | string[] | URL | URL[], cb: (eve
  * @since 2.1.0
  */
 declare function size(path: string | URL): 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
+ * using a security-scoped URL (e.g., from a file picker).
+ *
+ * Note that accessing security-scoped resources is automatically managed by the plugin on iOS, so you don't need to call this function
+ * unless you want to manage the scope manually.
+ *
+ * You must call {@linkcode stopAccessingSecurityScopedResource} when you're done accessing the resource.
+ *
+ * #### Platform-specific
+ *
+ * - **iOS:** Starts accessing the security-scoped resource.
+ * - **Other platforms:** does nothing.
+ *
+ * @example
+ * ```typescript
+ * import { startAccessingSecurityScopedResource } from '@tauri-apps/plugin-fs';
+ *
+ * const filePath = 'file:///path/to/file.txt';
+ * await startAccessingSecurityScopedResource(filePath);
+ * // ... use the resource ...
+ * ```
+ *
+ * @since 2.5.0
+ */
+declare function startAccessingSecurityScopedResource(path: string | URL): Promise<void>;
+/**
+ * Stops accessing a security-scoped resource for the given file URL.
+ * This should be called when you're done accessing a file that was opened
+ * using a security-scoped URL (e.g., from a file picker) when using manual tracking via {@linkcode startAccessingSecurityScopedResource}.
+ *
+ * #### Platform-specific
+ *
+ * - **iOS:** Stops accessing the security-scoped resource.
+ * - **Other platforms:** does nothing.
+ *
+ * @example
+ * ```typescript
+ * import { stopAccessingSecurityScopedResource } from '@tauri-apps/plugin-fs';
+ *
+ * const filePath = 'file:///path/to/file.txt';
+ * await startAccessingSecurityScopedResource(filePath);
+ * // ... use the resource ...
+ * // when you're done with the resource:
+ * await stopAccessingSecurityScopedResource(filePath);
+ * ```
+ *
+ * @since 2.5.0
+ */
+declare function stopAccessingSecurityScopedResource(path: string | URL): Promise<void>;
 export type { CreateOptions, OpenOptions, CopyFileOptions, MkdirOptions, DirEntry, ReadDirOptions, ReadFileOptions, RemoveOptions, RenameOptions, StatOptions, TruncateOptions, WriteFileOptions, ExistsOptions, FileInfo, WatchOptions, DebouncedWatchOptions, WatchEvent, WatchEventKind, WatchEventKindAccess, WatchEventKindCreate, WatchEventKindModify, WatchEventKindRemove, UnwatchFn };
-export { BaseDirectory, FileHandle, create, open, copyFile, mkdir, readDir, readFile, readTextFile, readTextFileLines, remove, rename, SeekMode, stat, lstat, truncate, writeFile, writeTextFile, exists, watch, watchImmediate, size };
+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

@@ -7,6 +7,19 @@ import { Resource, invoke, Channel } from '@tauri-apps/api/core';
 /**
  * Access the file system.
  *
+ * ## iOS security-scoped resources
+ *
+ * On iOS, the `fs` plugin automatically manages access to security-scoped resources when a file URL is accessed.
+ * This is required for files outside the app's sandbox (e.g., from file picker).
+ *
+ * @example
+ * ```typescript
+ * import { open } from '@tauri-apps/plugin-fs';
+ *
+ * const file = await open('file:///path/to/file.txt');
+ * await file.close();
+ * ```
+ *
  * ## Security
  *
  * This module prevents path traversal, not allowing parent directory accessors to be used
@@ -429,7 +442,7 @@ async function readFile(path, options) {
     return arr instanceof ArrayBuffer ? new Uint8Array(arr) : Uint8Array.from(arr);
 }
 /**
- * Reads and returns the entire contents of a file as UTF-8 string.
+ * Reads and returns the entire contents of a file as a string using the specified encoding (default: UTF-8).
  * @example
  * ```typescript
  * import { readTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
@@ -447,10 +460,10 @@ async function readTextFile(path, options) {
         options
     });
     const bytes = arr instanceof ArrayBuffer ? arr : Uint8Array.from(arr);
-    return new TextDecoder().decode(bytes);
+    return new TextDecoder(options?.encoding ?? 'utf-8').decode(bytes);
 }
 /**
- * Returns an async {@linkcode AsyncIterableIterator} over the lines of a file as UTF-8 string.
+ * Returns an async {@linkcode AsyncIterableIterator} over the lines of a file, decoded using the specified encoding (default: UTF-8).
  * @example
  * ```typescript
  * import { readTextFileLines, BaseDirectory } from '@tauri-apps/plugin-fs';
@@ -473,10 +486,13 @@ async function readTextFileLines(path, options) {
         path: pathStr,
         rid: null,
         async next() {
+            const decoder = new TextDecoder(options?.encoding ?? 'utf-8');
             if (this.rid === null) {
+                // Use the normalized encoding label for options.
+                const encoding = decoder.encoding;
                 this.rid = await invoke('plugin:fs|read_text_file_lines', {
                     path: pathStr,
-                    options
+                    options: options != null ? { ...options, encoding } : undefined
                 });
             }
             const arr = await invoke('plugin:fs|read_text_file_lines_next', { rid: this.rid });
@@ -492,7 +508,7 @@ async function readTextFileLines(path, options) {
                 this.rid = null;
                 return { value: null, done };
             }
-            const line = new TextDecoder().decode(bytes.slice(0, bytes.byteLength - 1));
+            const line = decoder.decode(bytes.slice(0, bytes.byteLength - 1));
             return {
                 value: line,
                 done
@@ -779,5 +795,70 @@ async function size(path) {
         path: path instanceof URL ? path.toString() : path
     });
 }
+/**
+ * Starts accessing a security-scoped resource for the given file URL.
+ * This should be called when you're accessing a file that was opened
+ * using a security-scoped URL (e.g., from a file picker).
+ *
+ * Note that accessing security-scoped resources is automatically managed by the plugin on iOS, so you don't need to call this function
+ * unless you want to manage the scope manually.
+ *
+ * You must call {@linkcode stopAccessingSecurityScopedResource} when you're done accessing the resource.
+ *
+ * #### Platform-specific
+ *
+ * - **iOS:** Starts accessing the security-scoped resource.
+ * - **Other platforms:** does nothing.
+ *
+ * @example
+ * ```typescript
+ * import { startAccessingSecurityScopedResource } from '@tauri-apps/plugin-fs';
+ *
+ * const filePath = 'file:///path/to/file.txt';
+ * await startAccessingSecurityScopedResource(filePath);
+ * // ... use the resource ...
+ * ```
+ *
+ * @since 2.5.0
+ */
+async function startAccessingSecurityScopedResource(path) {
+    if (path instanceof URL && path.protocol !== 'file:') {
+        throw new TypeError('Must be a file URL.');
+    }
+    await invoke('plugin:fs|start_accessing_security_scoped_resource', {
+        path: path instanceof URL ? path.toString() : path
+    });
+}
+/**
+ * Stops accessing a security-scoped resource for the given file URL.
+ * This should be called when you're done accessing a file that was opened
+ * using a security-scoped URL (e.g., from a file picker) when using manual tracking via {@linkcode startAccessingSecurityScopedResource}.
+ *
+ * #### Platform-specific
+ *
+ * - **iOS:** Stops accessing the security-scoped resource.
+ * - **Other platforms:** does nothing.
+ *
+ * @example
+ * ```typescript
+ * import { stopAccessingSecurityScopedResource } from '@tauri-apps/plugin-fs';
+ *
+ * const filePath = 'file:///path/to/file.txt';
+ * await startAccessingSecurityScopedResource(filePath);
+ * // ... use the resource ...
+ * // when you're done with the resource:
+ * await stopAccessingSecurityScopedResource(filePath);
+ * ```
+ *
+ * @since 2.5.0
+ */
+async function stopAccessingSecurityScopedResource(path) {
+    if (path instanceof URL && path.protocol !== 'file:') {
+        throw new TypeError('Must be a file URL.');
+    }
+    await invoke('plugin:fs|stop_accessing_security_scoped_resource', {
+        path: path instanceof URL ? path.toString() : path
+    });
+}
 
-export { FileHandle, SeekMode, copyFile, create, exists, lstat, mkdir, open, readDir, readFile, readTextFile, readTextFileLines, remove, rename, size, stat, truncate, watch, watchImmediate, writeFile, writeTextFile };
+export { FileHandle, SeekMode, 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": "2.4.5",
+  "version": "2.5.1",
   "description": "Access the file system.",
   "license": "MIT OR Apache-2.0",
   "authors": [
@@ -25,6 +25,6 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tauri-apps/api": "^2.8.0"
+    "@tauri-apps/api": "^2.11.0"
   }
 }