Class: LocalFileSystem

FileSystem implementation that stores files in a folder on the local machine.

Example

const fs = new LocalFileSystem({ root: "./data" });
await fs.init();
await fs.writeFile("hello.txt", "hi");

const home = new LocalFileSystem({ root: "~/projects/data" });
const scratch = tmpFS("my-job");
const cache = homeFS(".cache/app");

Extends

BaseFileSystem<"local">

Constructors

Constructor

new LocalFileSystem(options): LocalFileSystem

Parameters

options

LocalFileSystemOptions

Returns

LocalFileSystem

Overrides

BaseFileSystem<"local">.constructor

Properties

_init

protected _init: () => Promise<void>

Memoized initialization. Every operation that needs a ready backend awaits this, so callers (e.g. Mastra) may call init every time or never; both are fine.

Returns

Promise<void>

Inherited from

BaseFileSystem._init

backend

readonly backend: "local"

Identifier for the underlying implementation.

Examples: “disk”, “ftp”, “sftp”, “memory”, “s3”, or “dbfs”.

Inherited from

BaseFileSystem.backend

createRoot

protected readonly createRoot: boolean

Inherited from

BaseFileSystem.createRoot

id

readonly id: string

Unique identifier for this filesystem instance.

Inherited from

BaseFileSystem.id

readOnly

readonly readOnly: boolean

Inherited from

BaseFileSystem.readOnly

root

readonly root: string

POSIX-normalized root (see posixPath.normalizeRoot).

Inherited from

BaseFileSystem.root

Methods

appendFile()

appendFile(inputPath, content): Promise<void>

Parameters

inputPath

string

content

FileContent

Returns

Promise<void>

Inherited from

BaseFileSystem.appendFile

assertWritable()

protected assertWritable(operation): void

Parameters

operation

string

Returns

void

Inherited from

BaseFileSystem.assertWritable

close()

close(): Promise<void>

Release connections or other resources.

Returns

Promise<void>

Inherited from

BaseFileSystem.close

copyFile()

copyFile(sourcePath, destinationPath, options?): Promise<void>

Parameters

sourcePath

string

destinationPath

string

options?

CopyOptions = {}

Returns

Promise<void>

Inherited from

BaseFileSystem.copyFile

createDirectoryAt()

protected createDirectoryAt(resolvedPath): Promise<void>

Parameters

resolvedPath

string

Returns

Promise<void>

Overrides

BaseFileSystem.createDirectoryAt

createRootDirectory()

protected createRootDirectory(): Promise<void>

Ensure root exists when createRoot is true.

Default is a no-op. Local adapters typically mkdir -p; remote adapters leave the default when the root is provisioned out of band.

Returns

Promise<void>

Overrides

BaseFileSystem.createRootDirectory

deleteFile()

deleteFile(inputPath, options?): Promise<void>

Parameters

inputPath

string

options?

RemoveOptions = {}

Returns

Promise<void>

Inherited from

BaseFileSystem.deleteFile

deleteFileAt()

protected deleteFileAt(resolvedPath): Promise<void>

Parameters

resolvedPath

string

Returns

Promise<void>

Overrides

BaseFileSystem.deleteFileAt

ensureParentDirectory()

protected ensureParentDirectory(inputPath): Promise<void>

Create parent directories for inputPath when it is nested.

Parameters

inputPath

string

Returns

Promise<void>

Inherited from

BaseFileSystem.ensureParentDirectory

exists()

exists(inputPath): Promise<boolean>

Parameters

inputPath

string

Returns

Promise<boolean>

Inherited from

BaseFileSystem.exists

init()

init(): Promise<void>

Prepare, connect to, or validate the filesystem.

Returns

Promise<void>

Inherited from

BaseFileSystem.init

isNotFoundError()

protected isNotFoundError(error): boolean

Recognize the backend’s not-found error.

Default accepts FileSystemError NOT_FOUND plus common SDK / HTTP “not found” shapes via inferFileSystemErrorCode. Override for backend-specific codes (e.g. Node ENOENT) that do not carry a message.

Parameters

error

unknown

Returns

boolean

Overrides

BaseFileSystem.isNotFoundError

joinNamespace()

protected joinNamespace(parent, child): string

Parameters

parent

string

child

string

Returns

string

Inherited from

BaseFileSystem.joinNamespace

listDirectoryAt()

protected listDirectoryAt(resolvedPath): Promise<FileEntry[]>

Return only the direct children of a directory (name is the basename).

Parameters

resolvedPath

string

Returns

Promise<FileEntry[]>

Overrides

BaseFileSystem.listDirectoryAt

mapError()

protected mapError(err, filePath): FileSystemError

Classify Node errno codes; BaseFileSystem wraps every primitive.

Parameters

err

unknown

filePath

string

Returns

FileSystemError

Overrides

BaseFileSystem.mapError

mkdir()

mkdir(inputPath, options?): Promise<void>

Parameters

inputPath

string

options?

MakeDirectoryOptions = {}

Returns

Promise<void>

Inherited from

BaseFileSystem.mkdir

moveFile()

moveFile(sourcePath, destinationPath, options?): Promise<void>

Parameters

sourcePath

string

destinationPath

string

options?

CopyOptions = {}

Returns

Promise<void>

Inherited from

BaseFileSystem.moveFile

normalizePath()

protected normalizePath(inputPath): string

Normalize an input path into an absolute POSIX path inside the virtual filesystem namespace (/a/b). Backslashes are converted; .. escaping the root throws FileSystemError PERMISSION_DENIED.

Parameters

inputPath

string

Returns

string

Inherited from

BaseFileSystem.normalizePath

onClose()

protected onClose(): Promise<void>

Override when the backend owns connections or other resources.

Returns

Promise<void>

Inherited from

BaseFileSystem.onClose

onInit()

protected onInit(): Promise<void>

Override when the backend requires connection or validation work.

Returns

Promise<void>

Overrides

BaseFileSystem.onInit

preparePath()

protected preparePath(resolvedPath, options?): Promise<string>

When contained, resolve symlinks and ensure the real path still sits under root. Missing leaf paths are allowed when allowMissing is set so writes can create new files.

Parameters

resolvedPath

string

options?

allowMissing?

boolean

Returns

Promise<string>

Overrides

BaseFileSystem.preparePath

readBytesAt()

protected readBytesAt(resolvedPath): Promise<Uint8Array<ArrayBufferLike>>

Parameters

resolvedPath

string

Returns

Promise<Uint8Array<ArrayBufferLike>>

Overrides

BaseFileSystem.readBytesAt

readdir()

readdir(inputPath, options?): Promise<FileEntry[]>

Parameters

inputPath

string

options?

ListOptions = {}

Returns

Promise<FileEntry[]>

Inherited from

BaseFileSystem.readdir

readFile()

Call Signature

readFile(inputPath): Promise<Uint8Array<ArrayBufferLike>>

Read a file as binary data.

Parameters

inputPath

string

Returns

Promise<Uint8Array<ArrayBufferLike>>

Inherited from

BaseFileSystem.readFile

Call Signature

readFile(inputPath, options): Promise<string>

Read and decode a file as text.

Parameters

inputPath

string

options

ReadFileOptions & object

Returns

Promise<string>

Inherited from

BaseFileSystem.readFile

removeDirectoryAt()

protected removeDirectoryAt(resolvedPath): Promise<void>

Remove an empty directory.

Recursive deletion is implemented by BaseFileSystem.

Parameters

resolvedPath

string

Returns

Promise<void>

Overrides

BaseFileSystem.removeDirectoryAt

resolveBackendPath()

protected resolveBackendPath(namespacePath): string

Convert a normalized namespace path (/a/b) into a backend path.

Joins root with the namespace using POSIX /, then applies toBackendPath. Override toBackendPath instead of this method unless the join itself must change.

Parameters

namespacePath

string

Returns

string

Inherited from

BaseFileSystem.resolveBackendPath

resolveFor()

protected resolveFor(inputPath, options?): Promise<string>

Resolve inputPath, ensure init, and run preparePath.

Parameters

inputPath

string

options?

allowMissing?

boolean

Returns

Promise<string>

Inherited from

BaseFileSystem.resolveFor

resolvePath()

resolvePath(inputPath): string

Parameters

inputPath

string

Returns

string

Overrides

BaseFileSystem.resolvePath

rmdir()

rmdir(inputPath, options?): Promise<void>

Parameters

inputPath

string

options?

RemoveOptions = {}

Returns

Promise<void>

Inherited from

BaseFileSystem.rmdir

stat()

stat(inputPath): Promise<FileStat>

Parameters

inputPath

string

Returns

Promise<FileStat>

Inherited from

BaseFileSystem.stat

statAt()

protected statAt(resolvedPath): Promise<Omit<FileStat, "path">>

Parameters

resolvedPath

string

Returns

Promise<Omit<FileStat, "path">>

Overrides

BaseFileSystem.statAt

toBackendPath()

protected toBackendPath(posixBackendPath): string

Convert a POSIX backend path (under root) into the form the underlying API expects.

Default is identity. Local disk overrides with posixPath.toHost. Databricks / object-store adapters usually leave the default.

Parameters

posixBackendPath

string

Returns

string

Overrides

BaseFileSystem.toBackendPath

toBytes()

protected toBytes(content): Uint8Array

Parameters

content

FileContent

Returns

Uint8Array

Inherited from

BaseFileSystem.toBytes

toRelativePath()

protected toRelativePath(namespacePath): string

Namespace path without a leading slash (. for the root).

Parameters

namespacePath

string

Returns

string

Inherited from

BaseFileSystem.toRelativePath

tryAppendFileAt()

protected tryAppendFileAt(resolvedPath, content): Promise<boolean>

Override when the backend supports native append.

Parent directories are already created by appendFile. Return true when the operation was performed. The default causes BaseFileSystem to use read-concatenate-write.

Parameters

resolvedPath

string

content

Uint8Array

Returns

Promise<boolean>

Overrides

BaseFileSystem.tryAppendFileAt

tryCopyFileAt()

protected tryCopyFileAt(sourcePath, destinationPath, options): Promise<boolean>

Override when the backend supports native server-side copying.

Parent directories of the destination are already created by copyFile.

Parameters

sourcePath

string

destinationPath

string

options

Required<CopyOptions>

Returns

Promise<boolean>

Overrides

BaseFileSystem.tryCopyFileAt

tryMoveFileAt()

protected tryMoveFileAt(sourcePath, destinationPath, options): Promise<boolean>

Override for native rename or move support.

Parent directories of the destination are already created by moveFile.

Parameters

sourcePath

string

destinationPath

string

options

Required<CopyOptions>

Returns

Promise<boolean>

Overrides

BaseFileSystem.tryMoveFileAt

writeBytesAt()

protected writeBytesAt(resolvedPath, content, options): Promise<void>

Parameters

resolvedPath

string

content

Uint8Array

options

Required<WriteFileOptions>

Returns

Promise<void>

Overrides

BaseFileSystem.writeBytesAt

writeFile()

writeFile(inputPath, content, options?): Promise<void>

Parameters

inputPath

string

content

FileContent

options?

WriteFileOptions = {}

Returns

Promise<void>

Inherited from

BaseFileSystem.writeFile