Skip to content

Commit 5f68990

Browse files
chore(fs): update API documentation (#1645)
* chore(fs): update API documentation * fmt --------- Co-authored-by: Tillmann <[email protected]>
1 parent 9467805 commit 5f68990

File tree

2 files changed

+61
-50
lines changed

2 files changed

+61
-50
lines changed

.changes/update-fs-api-docs.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"fs-js": patch
3+
---
4+
5+
Update documentation.

plugins/fs/guest-js/index.ts

Lines changed: 56 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@
77
*
88
* ## Security
99
*
10-
* This module prevents path traversal, not allowing absolute paths or parent dir components
11-
* (i.e. "/usr/path/to/file" or "../path/to/file" paths are not allowed).
12-
* Paths accessed with this API must be relative to one of the {@link BaseDirectory | base directories}
13-
* so if you need access to arbitrary filesystem paths, you must write such logic on the core layer instead.
10+
* This module prevents path traversal, not allowing parent directory accessors to be used
11+
* (i.e. "/usr/path/to/../file" or "../path/to/file" paths are not allowed).
12+
* Paths accessed with this API must be either relative to one of the {@link BaseDirectory | base directories}
13+
* or created with the {@link https://v2.tauri.app/reference/javascript/api/namespacepath | path API}.
1414
*
1515
* The API has a scope configuration that forces you to restrict the paths that can be accessed using glob patterns.
1616
*
@@ -32,7 +32,7 @@
3232
* The available variables are:
3333
* {@linkcode https://v2.tauri.app/reference/javascript/api/namespacepath/#appconfigdir | $APPCONFIG},
3434
* {@linkcode https://v2.tauri.app/reference/javascript/api/namespacepath/#appdatadir | $APPDATA},
35-
* {@linkcode https://v2.tauri.app/reference/javascript/api/namespacepath/#appLocaldatadir | $APPLOCALDATA},
35+
* {@linkcode https://v2.tauri.app/reference/javascript/api/namespacepath/#applocaldatadir | $APPLOCALDATA},
3636
* {@linkcode https://v2.tauri.app/reference/javascript/api/namespacepath/#appcachedir | $APPCACHE},
3737
* {@linkcode https://v2.tauri.app/reference/javascript/api/namespacepath/#applogdir | $APPLOG},
3838
* {@linkcode https://v2.tauri.app/reference/javascript/api/namespacepath/#audiodir | $AUDIO},
@@ -269,13 +269,13 @@ class FileHandle extends Resource {
269269
*
270270
* @example
271271
* ```typescript
272-
* import { open, read, close, BaseDirectory } from "@tauri-apps/plugin-fs"
272+
* import { open, BaseDirectory } from "@tauri-apps/plugin-fs"
273273
* // if "$APP/foo/bar.txt" contains the text "hello world":
274-
* const file = await open("foo/bar.txt", { baseDir: BaseDirectory.App });
274+
* const file = await open("foo/bar.txt", { baseDir: BaseDirectory.AppConfig });
275275
* const buf = new Uint8Array(100);
276276
* const numberOfBytesRead = await file.read(buf); // 11 bytes
277277
* const text = new TextDecoder().decode(buf); // "hello world"
278-
* await close(file.rid);
278+
* await file.close();
279279
* ```
280280
*
281281
* @since 2.0.0
@@ -309,18 +309,20 @@ class FileHandle extends Resource {
309309
*
310310
* @example
311311
* ```typescript
312-
* import { open, seek, write, SeekMode, BaseDirectory } from '@tauri-apps/plugin-fs';
312+
* import { open, SeekMode, BaseDirectory } from '@tauri-apps/plugin-fs';
313313
*
314314
* // Given hello.txt pointing to file with "Hello world", which is 11 bytes long:
315-
* const file = await open('hello.txt', { read: true, write: true, truncate: true, create: true, baseDir: BaseDirectory.App });
316-
* await file.write(new TextEncoder().encode("Hello world"), { baseDir: BaseDirectory.App });
315+
* const file = await open('hello.txt', { read: true, write: true, truncate: true, create: true, baseDir: BaseDirectory.AppLocalData });
316+
* await file.write(new TextEncoder().encode("Hello world"));
317317
*
318318
* // Seek 6 bytes from the start of the file
319319
* console.log(await file.seek(6, SeekMode.Start)); // "6"
320320
* // Seek 2 more bytes from the current position
321321
* console.log(await file.seek(2, SeekMode.Current)); // "8"
322322
* // Seek backwards 2 bytes from the end of the file
323323
* console.log(await file.seek(-2, SeekMode.End)); // "9" (e.g. 11-2)
324+
*
325+
* await file.close();
324326
* ```
325327
*
326328
* @since 2.0.0
@@ -338,10 +340,11 @@ class FileHandle extends Resource {
338340
*
339341
* @example
340342
* ```typescript
341-
* import { open, fstat, BaseDirectory } from '@tauri-apps/plugin-fs';
342-
* const file = await open("file.txt", { read: true, baseDir: BaseDirectory.App });
343-
* const fileInfo = await fstat(file.rid);
343+
* import { open, BaseDirectory } from '@tauri-apps/plugin-fs';
344+
* const file = await open("file.txt", { read: true, baseDir: BaseDirectory.AppLocalData });
345+
* const fileInfo = await file.stat();
344346
* console.log(fileInfo.isFile); // true
347+
* await file.close();
345348
* ```
346349
*
347350
* @since 2.0.0
@@ -360,19 +363,20 @@ class FileHandle extends Resource {
360363
*
361364
* @example
362365
* ```typescript
363-
* import { ftruncate, open, write, read, BaseDirectory } from '@tauri-apps/plugin-fs';
366+
* import { open, BaseDirectory } from '@tauri-apps/plugin-fs';
364367
*
365368
* // truncate the entire file
366-
* const file = await open("my_file.txt", { read: true, write: true, create: true, baseDir: BaseDirectory.App });
367-
* await ftruncate(file.rid);
369+
* const file = await open("my_file.txt", { read: true, write: true, create: true, baseDir: BaseDirectory.AppLocalData });
370+
* await file.truncate();
368371
*
369372
* // truncate part of the file
370-
* const file = await open("my_file.txt", { read: true, write: true, create: true, baseDir: BaseDirectory.App });
371-
* await write(file.rid, new TextEncoder().encode("Hello World"));
372-
* await ftruncate(file.rid, 7);
373+
* const file = await open("my_file.txt", { read: true, write: true, create: true, baseDir: BaseDirectory.AppLocalData });
374+
* await file.write(new TextEncoder().encode("Hello World"));
375+
* await file.truncate(7);
373376
* const data = new Uint8Array(32);
374-
* await read(file.rid, data);
377+
* await file.read(data);
375378
* console.log(new TextDecoder().decode(data)); // Hello W
379+
* await file.close();
376380
* ```
377381
*
378382
* @since 2.0.0
@@ -394,12 +398,12 @@ class FileHandle extends Resource {
394398
*
395399
* @example
396400
* ```typescript
397-
* import { open, write, close, BaseDirectory } from '@tauri-apps/plugin-fs';
401+
* import { open, write, BaseDirectory } from '@tauri-apps/plugin-fs';
398402
* const encoder = new TextEncoder();
399403
* const data = encoder.encode("Hello world");
400-
* const file = await open("bar.txt", { write: true, baseDir: BaseDirectory.App });
401-
* const bytesWritten = await write(file.rid, data); // 11
402-
* await close(file.rid);
404+
* const file = await open("bar.txt", { write: true, baseDir: BaseDirectory.AppLocalData });
405+
* const bytesWritten = await file.write(data); // 11
406+
* await file.close();
403407
* ```
404408
*
405409
* @since 2.0.0
@@ -427,7 +431,9 @@ interface CreateOptions {
427431
* @example
428432
* ```typescript
429433
* import { create, BaseDirectory } from "@tauri-apps/plugin-fs"
430-
* const file = await create("foo/bar.txt", { baseDir: BaseDirectory.App });
434+
* const file = await create("foo/bar.txt", { baseDir: BaseDirectory.AppConfig });
435+
* await file.write(new TextEncoder().encode("Hello world"));
436+
* await file.close();
431437
* ```
432438
*
433439
* @since 2.0.0
@@ -510,9 +516,9 @@ interface OpenOptions {
510516
* @example
511517
* ```typescript
512518
* import { open, BaseDirectory } from "@tauri-apps/plugin-fs"
513-
* const file = await open("foo/bar.txt", { read: true, write: true, baseDir: BaseDirectory.App });
519+
* const file = await open("foo/bar.txt", { read: true, write: true, baseDir: BaseDirectory.AppLocalData });
514520
* // Do work with file
515-
* await close(file.rid);
521+
* await file.close();
516522
* ```
517523
*
518524
* @since 2.0.0
@@ -548,7 +554,7 @@ interface CopyFileOptions {
548554
* @example
549555
* ```typescript
550556
* import { copyFile, BaseDirectory } from '@tauri-apps/plugin-fs';
551-
* await copyFile('app.conf', 'app.conf.bk', { fromPathBaseDir: BaseDirectory.App, toPathBaseDir: BaseDirectory.App });
557+
* await copyFile('app.conf', 'app.conf.bk', { fromPathBaseDir: BaseDirectory.AppConfig, toPathBaseDir: BaseDirectory.AppConfig });
552558
* ```
553559
*
554560
* @since 2.0.0
@@ -591,7 +597,7 @@ interface MkdirOptions {
591597
* @example
592598
* ```typescript
593599
* import { mkdir, BaseDirectory } from '@tauri-apps/plugin-fs';
594-
* await mkdir('users', { baseDir: BaseDirectory.App });
600+
* await mkdir('users', { baseDir: BaseDirectory.AppLocalData });
595601
* ```
596602
*
597603
* @since 2.0.0
@@ -643,14 +649,14 @@ interface DirEntry {
643649
* import { readDir, BaseDirectory } from '@tauri-apps/plugin-fs';
644650
* import { join } from '@tauri-apps/api/path';
645651
* const dir = "users"
646-
* const entries = await readDir('users', { baseDir: BaseDirectory.App });
647-
* processEntriesRecursive(dir, entries);
648-
* async function processEntriesRecursive(parent, entries) {
652+
* const entries = await readDir('users', { baseDir: BaseDirectory.AppLocalData });
653+
* processEntriesRecursively(dir, entries);
654+
* async function processEntriesRecursively(parent, entries) {
649655
* for (const entry of entries) {
650656
* console.log(`Entry: ${entry.name}`);
651657
* if (entry.isDirectory) {
652658
* const dir = await join(parent, entry.name);
653-
* processEntriesRecursive(dir, await readDir(dir, { baseDir: BaseDirectory.App }))
659+
* processEntriesRecursively(dir, await readDir(dir, { baseDir: BaseDirectory.AppLocalData }))
654660
* }
655661
* }
656662
* }
@@ -714,7 +720,7 @@ async function readFile(
714720
* @example
715721
* ```typescript
716722
* import { readTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
717-
* const contents = await readTextFile('app.conf', { baseDir: BaseDirectory.App });
723+
* const contents = await readTextFile('app.conf', { baseDir: BaseDirectory.AppConfig });
718724
* ```
719725
*
720726
* @since 2.0.0
@@ -738,7 +744,7 @@ async function readTextFile(
738744
* @example
739745
* ```typescript
740746
* import { readTextFileLines, BaseDirectory } from '@tauri-apps/plugin-fs';
741-
* const lines = await readTextFileLines('app.conf', { baseDir: BaseDirectory.App });
747+
* const lines = await readTextFileLines('app.conf', { baseDir: BaseDirectory.AppConfig });
742748
* for await (const line of lines) {
743749
* console.log(line);
744750
* }
@@ -804,8 +810,8 @@ interface RemoveOptions {
804810
* @example
805811
* ```typescript
806812
* import { remove, BaseDirectory } from '@tauri-apps/plugin-fs';
807-
* await remove('users/file.txt', { baseDir: BaseDirectory.App });
808-
* await remove('users', { baseDir: BaseDirectory.App });
813+
* await remove('users/file.txt', { baseDir: BaseDirectory.AppLocalData });
814+
* await remove('users', { baseDir: BaseDirectory.AppLocalData });
809815
* ```
810816
*
811817
* @since 2.0.0
@@ -844,7 +850,7 @@ interface RenameOptions {
844850
* @example
845851
* ```typescript
846852
* import { rename, BaseDirectory } from '@tauri-apps/plugin-fs';
847-
* await rename('avatar.png', 'deleted.png', { oldPathBaseDir: BaseDirectory.App, newPathBaseDir: BaseDirectory.App });
853+
* await rename('avatar.png', 'deleted.png', { oldPathBaseDir: BaseDirectory.App, newPathBaseDir: BaseDirectory.AppLocalData });
848854
* ```
849855
*
850856
* @since 2.0.0
@@ -883,7 +889,7 @@ interface StatOptions {
883889
* @example
884890
* ```typescript
885891
* import { stat, BaseDirectory } from '@tauri-apps/plugin-fs';
886-
* const fileInfo = await stat("hello.txt", { baseDir: BaseDirectory.App });
892+
* const fileInfo = await stat("hello.txt", { baseDir: BaseDirectory.AppLocalData });
887893
* console.log(fileInfo.isFile); // true
888894
* ```
889895
*
@@ -909,7 +915,7 @@ async function stat(
909915
* @example
910916
* ```typescript
911917
* import { lstat, BaseDirectory } from '@tauri-apps/plugin-fs';
912-
* const fileInfo = await lstat("hello.txt", { baseDir: BaseDirectory.App });
918+
* const fileInfo = await lstat("hello.txt", { baseDir: BaseDirectory.AppLocalData });
913919
* console.log(fileInfo.isFile); // true
914920
* ```
915921
*
@@ -941,16 +947,16 @@ interface TruncateOptions {
941947
*
942948
* @example
943949
* ```typescript
944-
* import { truncate, readFile, writeFile, BaseDirectory } from '@tauri-apps/plugin-fs';
950+
* import { truncate, readTextFile, writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
945951
* // truncate the entire file
946-
* await truncate("my_file.txt", 0, { baseDir: BaseDirectory.App });
952+
* await truncate("my_file.txt", 0, { baseDir: BaseDirectory.AppLocalData });
947953
*
948954
* // truncate part of the file
949-
* let file = "file.txt";
950-
* await writeFile(file, new TextEncoder().encode("Hello World"), { baseDir: BaseDirectory.App });
951-
* await truncate(file, 7);
952-
* const data = await readFile(file, { baseDir: BaseDirectory.App });
953-
* console.log(new TextDecoder().decode(data)); // "Hello W"
955+
* const filePath = "file.txt";
956+
* await writeTextFile(filePath, "Hello World", { baseDir: BaseDirectory.AppLocalData });
957+
* await truncate(filePath, 7, { baseDir: BaseDirectory.AppLocalData });
958+
* const data = await readTextFile(filePath, { baseDir: BaseDirectory.AppLocalData });
959+
* console.log(data); // "Hello W"
954960
* ```
955961
*
956962
* @since 2.0.0
@@ -995,7 +1001,7 @@ interface WriteFileOptions {
9951001
*
9961002
* let encoder = new TextEncoder();
9971003
* let data = encoder.encode("Hello World");
998-
* await writeFile('file.txt', data, { baseDir: BaseDirectory.App });
1004+
* await writeFile('file.txt', data, { baseDir: BaseDirectory.AppLocalData });
9991005
* ```
10001006
*
10011007
* @since 2.0.0
@@ -1023,7 +1029,7 @@ async function writeFile(
10231029
* ```typescript
10241030
* import { writeTextFile, BaseDirectory } from '@tauri-apps/plugin-fs';
10251031
*
1026-
* await writeTextFile('file.txt', "Hello world", { baseDir: BaseDirectory.App });
1032+
* await writeTextFile('file.txt', "Hello world", { baseDir: BaseDirectory.AppLocalData });
10271033
* ```
10281034
*
10291035
* @since 2.0.0

0 commit comments

Comments
 (0)