ToDesktop FS

Securely interact with the file system.

Installation

Install @todesktop/client-fs in your client-side application using

``sh
npm install @todesktop/client-fs
`

Installation of the plugin package is also necessary. Using ToDesktop Builder, navigate to Plugins. Click on the Explore button for "File System" and install the package.

Security

For security considerations, usage of this plugin is restricted in the following ways:

- Paths accessed by this library must begin with one of our whitelisted directories:

- all: All directories (NOTE: This gives access to entire file system so only use it if absolutely necessary for your use case).
- home: The current user's home directory.
- userData: Directory for storing your app's configuration files.
- appData: Per-user application data directory.
- desktop: The current user's Desktop directory.
- documents: Directory for a user's 'My Documents'.
- downloads: Directory for a user's downloads.
- music: Directory for a user's music.
- pictures: Directory for a user's pictures.
- videos: Reads the entire contents of a file.
- recent: Directory for the user's recent files.
- temp: Temporary directory.

- FS functionality is enabled on a function-by-function basis via the ToDesktop Builder interface. This means that you can expose the readFile functionality to your client app, but prohibit writeFile.

Usage

$3

Reads the entire contents of a file.

`js
import { readFile } from "@todesktop/client-fs";

const fileContents = await readFile("temp", "file/path");
`

$3

Writes data to a file, replacing the file if it already exists.

`js
import { writeFile } from "@todesktop/client-fs";

await writeFile("temp", "file/path", "File Contents");
`

$3

Append data to a file, creating the file if it does not exist.

`js
import { appendFile } from "@todesktop/client-fs";

await appendFile("temp", "file/path", "File Contents");
`

$3

Copy a file from a source path to a destination path.

`js
import { copyFile } from "@todesktop/client-fs";

await copyFile(
{ dirName: "temp", path: "src/path" },
{ dirName: "temp", path: "dest/path" }
);
`

$3

Read a directory.

`js
import { readdir } from "@todesktop/client-fs";

const fileList = await readdir("temp", "file/path");
`

$3

Read a directory and return an object with the file name, path and whether it is a directory.

`js
import { readdirWithFileTypes } from "@todesktop/client-fs";

const fileList = await readdirWithFileTypes("temp", "file/path");
`

$3

Create a directory.

`js
import { mkdir } from "@todesktop/client-fs";

await mkdir("temp", "file/path");
`

$3

Change the name or location of a file or directory.

`js
import { rename } from "@todesktop/client-fs";

await rename(
{ dirName: "temp", path: "old/path" },
{ dirName: "temp", path: "new/path" }
);
`

$3

Remove a file or directory.

`js
import { rm } from "@todesktop/client-fs";

await rm("temp", "file/path");
`

$3

Get file status.

`js
import { stat } from "@todesktop/client-fs";

const stats = await stat("temp", "file/path");
`

$3

Show an open file dialog. Full list of options can be found here.

`js
import { showOpenDialog } from "@todesktop/client-fs";

const result = await showOpenDialog({
title: "Open File",
buttonLabel: "Select",
filters: [
{ name: "Text Files", extensions: ["txt"] },
{ name: "JavaScript Files", extensions: ["js"] },
],
});
`

$3

Show a save file dialog. Full list of options can be found here.

`js
import { showSaveDialog } from "@todesktop/client-fs";

const result = await showSaveDialog({
title: "Save File",
buttonLabel: "Save",
});
`

$3

Creates a readable stream for a file. This allows you to efficiently read large files in chunks and supports binary data.

`js
import {
createReadStream,
streamToText,
streamToArrayBuffer,
} from "@todesktop/client-fs";

// Create a readable stream
const stream = createReadStream("downloads", "large-file.zip");

// Read as text (for text files)
const text = await streamToText(stream);

// Or read as ArrayBuffer (for binary files)
const arrayBuffer = await streamToArrayBuffer(stream);

// Or process the stream directly
const reader = stream.getReader();
try {
while (true) {
const { done, value } = await reader.read();
if (done) break;
// Process chunk (value is a Uint8Array)
console.log(Received ${value.byteLength} bytes);
}
} finally {
reader.releaseLock();
}
`

$3

Creates a writable stream to a file. This allows you to efficiently write large files in chunks and supports binary data.

`js
import { createWriteStream, writeToStream } from "@todesktop/client-fs";

// Create a writable stream
const stream = await createWriteStream("downloads", "output-file.txt");

// Write text to the stream using the helper function
await writeToStream(stream, "Hello, world!");

// Or write binary data
const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
await writeToStream(stream, binaryData);

// Or use the WritableStream API directly
const writer = stream.getWriter();
try {
// Write text
const textEncoder = new TextEncoder();
await writer.write(textEncoder.encode("Hello, world!"));

// Write binary data
await writer.write(new Uint8Array([1, 2, 3, 4, 5]));
} finally {
// Always close the writer when done
await writer.close();
}
`

$3

- v1.7.0 - Add createWriteStream function with support for writing binary files.
- v1.6.0 - Add createReadStream function with support for streaming binary files.
- v1.4.0 - Add readdirWithFileTypes function.
- v1.3.0 - Add support for showOpenDialog and showSaveDialog.
- v1.2.0 - Add support for all directory.
- v1.0.0 - Marked as stable.
- v0.12.0 - Add support for home` directory.