@todesktop/client-fs

ToDesktop FS

Securely interact with the file system.

Installation

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

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

readFile

Reads the entire contents of a file.

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

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

writeFile

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

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

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

appendFile

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

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

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

copyFile

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

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

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

readdir

Read a directory.

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

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

readdirWithFileTypes

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

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

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

mkdir

Create a directory.

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

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

rename

Change the name or location of a file or directory.

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

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

rm

Remove a file or directory.

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

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

stat

Get file status.

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

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

showOpenDialog

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

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"] },
  ],
});

showSaveDialog

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

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

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

createReadStream

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

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();
}

createWriteStream

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

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();
}

Changelog

• 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.