Filesystem

Usage

import { fs } from "/42/api/fs.js"
// or
const { fs } = sys42

fs is an instance of FileSystem.

caution

Do not create new instances of FileSystem.

tip

View the driver internals page to learn more about mount configuration.

Type notes

Signatures below use TypeScript-style notation for clarity.

type FsPath = string
type AnyArgs = unknown[]

Some methods forward extra arguments to the active driver, so exact parameter and return shapes can vary by backend.

Check methods

access(path, ...args)

access(path: FsPath, ...args: AnyArgs): Promise<unknown>

Checks whether a path can be accessed. Result shape is driver-specific.

getURL(path, ...args)

getURL(path: FsPath | URL, ...args: AnyArgs): Promise<string | URL>

Resolves a usable URL for a filesystem path.

Behavior:

• accepts string or URL
• external origin/protocol is returned unchanged
• local URL/path is resolved through the active filesystem driver

isFile(path, ...args)

isFile(path: FsPath, ...args: AnyArgs): Promise<boolean>

Returns whether path points to a file.

isDir(path, ...args)

isDir(path: FsPath, ...args: AnyArgs): Promise<boolean>

Returns whether path points to a directory.

isLink(path, ...args)

isLink(path: FsPath, ...args: AnyArgs): Promise<boolean>

Returns whether path points to a symbolic link.

link(path, ...args)

link(path: FsPath, ...args: AnyArgs): Promise<void>

Creates or updates a link entry. Exact link semantics depend on the driver and args.

File methods

open(path, ...args)

open(path: FsPath, ...args: AnyArgs): Promise<unknown>

Opens a file handle/resource. Return type is backend-specific.

read(path, ...args)

read(path: FsPath, ...args: AnyArgs): Promise<unknown>

Reads file content. Return type depends on the encoding/options passed.

write(path, ...args)

write(path: FsPath, ...args: AnyArgs): Promise<void>

Writes content to a file. Concurrent writes to the same path are serialized.

append(path, ...args)

append(path: FsPath, ...args: AnyArgs): Promise<void>

Appends content to a file. Concurrent appends/writes to the same path are serialized.

delete(path, ...args)

delete(path: FsPath, ...args: AnyArgs): Promise<void>

Deletes a file.

Directory methods

writeDir(path)

writeDir(path: FsPath): Promise<void>

Creates a directory.

readDir(path, ...args)

readDir(path: FsPath, ...args: AnyArgs): Promise<string[]>

Reads directory entries. Common option patterns include recursive listing.

deleteDir(path)

deleteDir(path: FsPath): Promise<void>

Deletes a directory.

Stream methods

sink(path, options)

sink(
	path: FsPath,
	options?: { queuingStrategy?: QueuingStrategy<Uint8Array> } & Record<string, unknown>,
): WritableStream<Uint8Array>

Returns a writable stream that persists chunks to path.

source(path, options)

source(
	path: FsPath,
	options?: { queuingStrategy?: QueuingStrategy<Uint8Array> } & Record<string, unknown>,
): ReadableStream<Uint8Array>

Returns a readable stream for file content.

Notes:

• source initialization is lazy (first pull)
• if the stream has no chunks, it emits a single empty Uint8Array before close

Copy and move

copy(from, to, options)

copy(
	from: FsPath,
	to: FsPath,
	options?: {
		delete?: boolean
		silent?: boolean
		progress?: () => TransformStream<Uint8Array, Uint8Array>
	} & Record<string, unknown>,
): Promise<void>

Copies a file or directory tree.

Behavior:

• file copy uses stream piping (source -> optional progress transform -> sink)
• directory copy walks recursively
• when options.delete is true, copy behaves as move
• emits copy or move unless options.silent is true

move(from, to, options)

move(
	from: FsPath,
	to: FsPath,
	options?: {
		silent?: boolean
		progress?: () => TransformStream<Uint8Array, Uint8Array>
	} & Record<string, unknown>,
): Promise<void>

Moves a file or directory tree.

Guard:

• throws if destination is inside source directory

Text and data helpers

writeText(path, value, encoding = "utf-8")

writeText(path: FsPath, value: string, encoding?: string): Promise<void>

Writes text content.

readText(path, encoding = "utf-8")

readText(path: FsPath, encoding?: string): Promise<string>

Reads text content.

writeJSON(path, value, replacer, space = 2)

writeJSON(
	path: FsPath,
	value: unknown,
	replacer?: (this: unknown, key: string, value: unknown) => unknown,
	space?: number,
): Promise<void>

Serializes a value with JSON.stringify and writes UTF-8 text.

readJSON(path, options)

readJSON(path: FsPath, options?: { strict?: boolean }): Promise<unknown>

Reads and parses JSON text.

• strict: true uses JSON.parse
• default mode uses JSON5.parse

readJSON5(path)

readJSON5(path: FsPath): Promise<unknown>

Reads and parses JSON5 text.

writeJSON5(path, value, options)

writeJSON5(path: FsPath, value: unknown, options?: Record<string, unknown>): Promise<void>

Writes JSON5 content.

Behavior:

• value === undefined writes an empty string
• attempts patch write against previous content when possible
• falls back to full JSON5.stringify output

writeCBOR(path, value)

writeCBOR(path: FsPath, value: unknown): Promise<void>

Encodes value as CBOR and writes binary data.

readCBOR(path)

readCBOR(path: FsPath): Promise<unknown>

Reads binary data and decodes CBOR.

Events

The class emits at least:

• copy with (from, to)
• move with (from, to)

Emission can be suppressed in recursive/internal calls by passing silent: true.

tip

View the events reference

Practical examples

Basic file operations

await fs.writeText("~/notes/todo.txt", "hello")
const text = await fs.readText("~/notes/todo.txt")
await fs.delete("~/notes/todo.txt")

JSON and JSON5

await fs.writeJSON("~/config/app.json")
const config = await fs.readJSON("~/config/app.json")

await fs.writeJSON5("~/config/dev.json5")
const dev = await fs.readJSON5("~/config/dev.json5")

Directory copy and move

await fs.copy("~/projects/demo", "~/backup/demo")
await fs.move("~/backup/demo", "~/archive/demo")