Skip to content
dbx tools

Class: MemoryFileSystem

FileSystem that stores files and directories in process memory.

Example

Section titled “Example”
const fs = new MemoryFileSystem();
await fs.writeFile("note.txt", "hi");
const text = await fs.readFile("note.txt", { encoding: "utf8" });

Extends

Section titled “Extends”

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”

new MemoryFileSystem(options?): MemoryFileSystem

Parameters

Section titled “Parameters”
options?
Section titled “options?”

MemoryFileSystemOptions = {}

Returns

Section titled “Returns”

MemoryFileSystem

Overrides

Section titled “Overrides”

BaseFileSystem.constructor

Properties

Section titled “Properties”

_init

Section titled “_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

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem._init

backend

Section titled “backend”

readonly backend: "memory"

Identifier for the underlying implementation.

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

Inherited from

Section titled “Inherited from”

BaseFileSystem.backend

createRoot

Section titled “createRoot”

protected readonly createRoot: boolean

Inherited from

Section titled “Inherited from”

BaseFileSystem.createRoot

id

Section titled “id”

readonly id: string

Unique identifier for this filesystem instance.

Inherited from

Section titled “Inherited from”

BaseFileSystem.id

readOnly

Section titled “readOnly”

readonly readOnly: boolean

Inherited from

Section titled “Inherited from”

BaseFileSystem.readOnly

root

Section titled “root”

readonly root: string

POSIX-normalized root (see posixPath.normalizeRoot).

Inherited from

Section titled “Inherited from”

BaseFileSystem.root

Methods

Section titled “Methods”

appendFile()

Section titled “appendFile()”

appendFile(inputPath, content): Promise<void>

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

content
Section titled “content”

FileContent

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.appendFile

assertWritable()

Section titled “assertWritable()”

protected assertWritable(operation): void

Parameters

Section titled “Parameters”
operation
Section titled “operation”

string

Returns

Section titled “Returns”

void

Inherited from

Section titled “Inherited from”

BaseFileSystem.assertWritable

clear()

Section titled “clear()”

clear(): void

Drop every file and directory except the root.

Returns

Section titled “Returns”

void

close()

Section titled “close()”

close(): Promise<void>

Release connections or other resources.

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.close

copyFile()

Section titled “copyFile()”

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

Parameters

Section titled “Parameters”
sourcePath
Section titled “sourcePath”

string

destinationPath
Section titled “destinationPath”

string

options?
Section titled “options?”

CopyOptions = {}

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.copyFile

createDirectoryAt()

Section titled “createDirectoryAt()”

protected createDirectoryAt(resolvedPath): Promise<void>

Parameters

Section titled “Parameters”
resolvedPath
Section titled “resolvedPath”

string

Returns

Section titled “Returns”

Promise<void>

Overrides

Section titled “Overrides”

BaseFileSystem.createDirectoryAt

createRootDirectory()

Section titled “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

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.createRootDirectory

deleteFile()

Section titled “deleteFile()”

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

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

options?
Section titled “options?”

RemoveOptions = {}

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.deleteFile

deleteFileAt()

Section titled “deleteFileAt()”

protected deleteFileAt(resolvedPath): Promise<void>

Parameters

Section titled “Parameters”
resolvedPath
Section titled “resolvedPath”

string

Returns

Section titled “Returns”

Promise<void>

Overrides

Section titled “Overrides”

BaseFileSystem.deleteFileAt

ensureParentDirectory()

Section titled “ensureParentDirectory()”

protected ensureParentDirectory(inputPath): Promise<void>

Create parent directories for inputPath when it is nested.

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.ensureParentDirectory

exists()

Section titled “exists()”

exists(inputPath): Promise<boolean>

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

Returns

Section titled “Returns”

Promise<boolean>

Inherited from

Section titled “Inherited from”

BaseFileSystem.exists

init()

Section titled “init()”

init(): Promise<void>

Prepare, connect to, or validate the filesystem.

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.init

isNotFoundError()

Section titled “isNotFoundError()”

protected isNotFoundError(err): 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

Section titled “Parameters”
err
Section titled “err”

unknown

Returns

Section titled “Returns”

boolean

Inherited from

Section titled “Inherited from”

BaseFileSystem.isNotFoundError

joinNamespace()

Section titled “joinNamespace()”

protected joinNamespace(parent, child): string

Parameters

Section titled “Parameters”
parent
Section titled “parent”

string

child
Section titled “child”

string

Returns

Section titled “Returns”

string

Inherited from

Section titled “Inherited from”

BaseFileSystem.joinNamespace

listDirectoryAt()

Section titled “listDirectoryAt()”

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

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

Parameters

Section titled “Parameters”
resolvedPath
Section titled “resolvedPath”

string

Returns

Section titled “Returns”

Promise<FileEntry[]>

Overrides

Section titled “Overrides”

BaseFileSystem.listDirectoryAt

mapError()

Section titled “mapError()”

protected mapError(err, filePath): FileSystemError

Normalize a backend failure into a FileSystemError.

Every *At / try* primitive is invoked through guard, so an adapter never writes its own try/catch and cannot forget to normalize. Override only to classify backend-specific codes (e.g. Node errno).

Parameters

Section titled “Parameters”
err
Section titled “err”

unknown

filePath
Section titled “filePath”

string

Returns

Section titled “Returns”

FileSystemError

Inherited from

Section titled “Inherited from”

BaseFileSystem.mapError

mkdir()

Section titled “mkdir()”

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

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

options?
Section titled “options?”

MakeDirectoryOptions = {}

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.mkdir

moveFile()

Section titled “moveFile()”

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

Parameters

Section titled “Parameters”
sourcePath
Section titled “sourcePath”

string

destinationPath
Section titled “destinationPath”

string

options?
Section titled “options?”

CopyOptions = {}

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.moveFile

normalizePath()

Section titled “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

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

Returns

Section titled “Returns”

string

Inherited from

Section titled “Inherited from”

BaseFileSystem.normalizePath

onClose()

Section titled “onClose()”

protected onClose(): Promise<void>

Override when the backend owns connections or other resources.

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.onClose

onInit()

Section titled “onInit()”

protected onInit(): Promise<void>

Override when the backend requires connection or validation work.

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.onInit

preparePath()

Section titled “preparePath()”

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

Hook after lexical resolution. Override for realpath containment or similar backend-specific checks. Default is a no-op.

Parameters

Section titled “Parameters”
resolvedPath
Section titled “resolvedPath”

string

_options?
Section titled “_options?”
allowMissing?
Section titled “allowMissing?”

boolean

Returns

Section titled “Returns”

Promise<string>

Inherited from

Section titled “Inherited from”

BaseFileSystem.preparePath

readBytesAt()

Section titled “readBytesAt()”

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

Parameters

Section titled “Parameters”
resolvedPath
Section titled “resolvedPath”

string

Returns

Section titled “Returns”

Promise<Uint8Array<ArrayBufferLike>>

Overrides

Section titled “Overrides”

BaseFileSystem.readBytesAt

readdir()

Section titled “readdir()”

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

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

options?
Section titled “options?”

ListOptions = {}

Returns

Section titled “Returns”

Promise<FileEntry[]>

Inherited from

Section titled “Inherited from”

BaseFileSystem.readdir

readFile()

Section titled “readFile()”

Call Signature

Section titled “Call Signature”

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

Read a file as binary data.

Parameters
Section titled “Parameters”
inputPath
Section titled “inputPath”

string

Returns
Section titled “Returns”

Promise<Uint8Array<ArrayBufferLike>>

Inherited from
Section titled “Inherited from”

BaseFileSystem.readFile

Call Signature

Section titled “Call Signature”

readFile(inputPath, options): Promise<string>

Read and decode a file as text.

Parameters
Section titled “Parameters”
inputPath
Section titled “inputPath”

string

options
Section titled “options”

ReadFileOptions & object

Returns
Section titled “Returns”

Promise<string>

Inherited from
Section titled “Inherited from”

BaseFileSystem.readFile

removeDirectoryAt()

Section titled “removeDirectoryAt()”

protected removeDirectoryAt(resolvedPath): Promise<void>

Remove an empty directory.

Recursive deletion is implemented by BaseFileSystem.

Parameters

Section titled “Parameters”
resolvedPath
Section titled “resolvedPath”

string

Returns

Section titled “Returns”

Promise<void>

Overrides

Section titled “Overrides”

BaseFileSystem.removeDirectoryAt

resolveBackendPath()

Section titled “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

Section titled “Parameters”
namespacePath
Section titled “namespacePath”

string

Returns

Section titled “Returns”

string

Inherited from

Section titled “Inherited from”

BaseFileSystem.resolveBackendPath

resolveFor()

Section titled “resolveFor()”

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

Resolve inputPath, ensure init, and run preparePath.

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

options?
Section titled “options?”
allowMissing?
Section titled “allowMissing?”

boolean

Returns

Section titled “Returns”

Promise<string>

Inherited from

Section titled “Inherited from”

BaseFileSystem.resolveFor

resolvePath()

Section titled “resolvePath()”

resolvePath(inputPath): string

Resolve a filesystem-relative path into the path understood by the underlying backend.

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

Returns

Section titled “Returns”

string

Inherited from

Section titled “Inherited from”

BaseFileSystem.resolvePath

rmdir()

Section titled “rmdir()”

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

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

options?
Section titled “options?”

RemoveOptions = {}

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.rmdir

stat()

Section titled “stat()”

stat(inputPath): Promise<FileStat>

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

Returns

Section titled “Returns”

Promise<FileStat>

Inherited from

Section titled “Inherited from”

BaseFileSystem.stat

statAt()

Section titled “statAt()”

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

Parameters

Section titled “Parameters”
resolvedPath
Section titled “resolvedPath”

string

Returns

Section titled “Returns”

Promise<Omit<FileStat, "path">>

Overrides

Section titled “Overrides”

BaseFileSystem.statAt

toBackendPath()

Section titled “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

Section titled “Parameters”
posixBackendPath
Section titled “posixBackendPath”

string

Returns

Section titled “Returns”

string

Inherited from

Section titled “Inherited from”

BaseFileSystem.toBackendPath

toBytes()

Section titled “toBytes()”

protected toBytes(content): Uint8Array

Parameters

Section titled “Parameters”
content
Section titled “content”

FileContent

Returns

Section titled “Returns”

Uint8Array

Inherited from

Section titled “Inherited from”

BaseFileSystem.toBytes

toRelativePath()

Section titled “toRelativePath()”

protected toRelativePath(namespacePath): string

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

Parameters

Section titled “Parameters”
namespacePath
Section titled “namespacePath”

string

Returns

Section titled “Returns”

string

Inherited from

Section titled “Inherited from”

BaseFileSystem.toRelativePath

tryAppendFileAt()

Section titled “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

Section titled “Parameters”
_resolvedPath
Section titled “_resolvedPath”

string

_content
Section titled “_content”

Uint8Array

Returns

Section titled “Returns”

Promise<boolean>

Inherited from

Section titled “Inherited from”

BaseFileSystem.tryAppendFileAt

tryCopyFileAt()

Section titled “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

Section titled “Parameters”
_sourcePath
Section titled “_sourcePath”

string

_destinationPath
Section titled “_destinationPath”

string

_options
Section titled “_options”

Required<CopyOptions>

Returns

Section titled “Returns”

Promise<boolean>

Inherited from

Section titled “Inherited from”

BaseFileSystem.tryCopyFileAt

tryMoveFileAt()

Section titled “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

Section titled “Parameters”
_sourcePath
Section titled “_sourcePath”

string

_destinationPath
Section titled “_destinationPath”

string

_options
Section titled “_options”

Required<CopyOptions>

Returns

Section titled “Returns”

Promise<boolean>

Inherited from

Section titled “Inherited from”

BaseFileSystem.tryMoveFileAt

writeBytesAt()

Section titled “writeBytesAt()”

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

Parameters

Section titled “Parameters”
resolvedPath
Section titled “resolvedPath”

string

content
Section titled “content”

Uint8Array

options
Section titled “options”

Required<WriteFileOptions>

Returns

Section titled “Returns”

Promise<void>

Overrides

Section titled “Overrides”

BaseFileSystem.writeBytesAt

writeFile()

Section titled “writeFile()”

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

Parameters

Section titled “Parameters”
inputPath
Section titled “inputPath”

string

content
Section titled “content”

FileContent

options?
Section titled “options?”

WriteFileOptions = {}

Returns

Section titled “Returns”

Promise<void>

Inherited from

Section titled “Inherited from”

BaseFileSystem.writeFile