Abstract Class: BaseFileSystem\<TBackend\>
Base implementation for local, remote, and virtual filesystems.
Subclasses implement the low-level *At primitives. This class provides:
- Memoized _init (so an explicit init call is optional)
- Optional root creation via createRootDirectory
- POSIX-only rooted path normalization and traversal protection
- toBackendPath for host/separator conversion at the boundary
- Text encoding and decoding
- exists
- Parent-directory creation on write / append / copy / move
- Append / copy / move fallbacks (override
try*for native ops) - Recursive mkdir, readdir, and rmdir
- Extension filtering for readdir
Namespace paths always use /. Host adapters convert with
posixPath.toPosix / posixPath.toHost in toBackendPath.
Extended by
Section titled “Extended by”Type Parameters
Section titled “Type Parameters”TBackend
Section titled “TBackend”TBackend extends string = string
Implements
Section titled “Implements”FileSystem<TBackend>
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”
protectednew BaseFileSystem<TBackend>(options):BaseFileSystem<TBackend>
Parameters
Section titled “Parameters”options
Section titled “options”BaseFileSystemOptions<TBackend>
Returns
Section titled “Returns”BaseFileSystem<TBackend>
Properties
Section titled “Properties”
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>
backend
Section titled “backend”
readonlybackend:TBackend
Identifier for the underlying implementation.
Examples: “disk”, “ftp”, “sftp”, “memory”, “s3”, or “dbfs”.
Implementation of
Section titled “Implementation of”createRoot
Section titled “createRoot”
protectedreadonlycreateRoot:boolean
readonlyid:string
Unique identifier for this filesystem instance.
Implementation of
Section titled “Implementation of”readOnly
Section titled “readOnly”
readonlyreadOnly:boolean
Implementation of
Section titled “Implementation of”
readonlyroot:string
POSIX-normalized root (see posixPath.normalizeRoot).
Implementation of
Section titled “Implementation of”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”Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”assertWritable()
Section titled “assertWritable()”
protectedassertWritable(operation):void
Parameters
Section titled “Parameters”operation
Section titled “operation”string
Returns
Section titled “Returns”void
close()
Section titled “close()”close():
Promise<void>
Release connections or other resources.
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”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>
Implementation of
Section titled “Implementation of”createDirectoryAt()
Section titled “createDirectoryAt()”
abstractprotectedcreateDirectoryAt(resolvedPath):Promise<void>
Parameters
Section titled “Parameters”resolvedPath
Section titled “resolvedPath”string
Returns
Section titled “Returns”Promise<void>
createRootDirectory()
Section titled “createRootDirectory()”
protectedcreateRootDirectory():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>
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>
Implementation of
Section titled “Implementation of”deleteFileAt()
Section titled “deleteFileAt()”
abstractprotecteddeleteFileAt(resolvedPath):Promise<void>
Parameters
Section titled “Parameters”resolvedPath
Section titled “resolvedPath”string
Returns
Section titled “Returns”Promise<void>
ensureParentDirectory()
Section titled “ensureParentDirectory()”
protectedensureParentDirectory(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>
exists()
Section titled “exists()”exists(
inputPath):Promise<boolean>
Parameters
Section titled “Parameters”inputPath
Section titled “inputPath”string
Returns
Section titled “Returns”Promise<boolean>
Implementation of
Section titled “Implementation of”init()
Section titled “init()”init():
Promise<void>
Prepare, connect to, or validate the filesystem.
Returns
Section titled “Returns”Promise<void>
Implementation of
Section titled “Implementation of”isNotFoundError()
Section titled “isNotFoundError()”
protectedisNotFoundError(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”unknown
Returns
Section titled “Returns”boolean
joinNamespace()
Section titled “joinNamespace()”
protectedjoinNamespace(parent,child):string
Parameters
Section titled “Parameters”parent
Section titled “parent”string
string
Returns
Section titled “Returns”string
listDirectoryAt()
Section titled “listDirectoryAt()”
abstractprotectedlistDirectoryAt(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[]>
mapError()
Section titled “mapError()”
protectedmapError(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”unknown
filePath
Section titled “filePath”string
Returns
Section titled “Returns”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>
Implementation of
Section titled “Implementation of”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>
Implementation of
Section titled “Implementation of”normalizePath()
Section titled “normalizePath()”
protectednormalizePath(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
onClose()
Section titled “onClose()”
protectedonClose():Promise<void>
Override when the backend owns connections or other resources.
Returns
Section titled “Returns”Promise<void>
onInit()
Section titled “onInit()”
protectedonInit():Promise<void>
Override when the backend requires connection or validation work.
Returns
Section titled “Returns”Promise<void>
preparePath()
Section titled “preparePath()”
protectedpreparePath(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>
readBytesAt()
Section titled “readBytesAt()”
abstractprotectedreadBytesAt(resolvedPath):Promise<Uint8Array<ArrayBufferLike>>
Parameters
Section titled “Parameters”resolvedPath
Section titled “resolvedPath”string
Returns
Section titled “Returns”Promise<Uint8Array<ArrayBufferLike>>
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[]>
Implementation of
Section titled “Implementation of”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>>
Implementation of
Section titled “Implementation of”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>
Implementation of
Section titled “Implementation of”removeDirectoryAt()
Section titled “removeDirectoryAt()”
abstractprotectedremoveDirectoryAt(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>
resolveBackendPath()
Section titled “resolveBackendPath()”
protectedresolveBackendPath(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
resolveFor()
Section titled “resolveFor()”
protectedresolveFor(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>
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
Implementation of
Section titled “Implementation of”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>
Implementation of
Section titled “Implementation of”stat()
Section titled “stat()”stat(
inputPath):Promise<FileStat>
Parameters
Section titled “Parameters”inputPath
Section titled “inputPath”string
Returns
Section titled “Returns”Promise<FileStat>
Implementation of
Section titled “Implementation of”statAt()
Section titled “statAt()”
abstractprotectedstatAt(resolvedPath):Promise<Omit<FileStat,"path">>
Parameters
Section titled “Parameters”resolvedPath
Section titled “resolvedPath”string
Returns
Section titled “Returns”Promise<Omit<FileStat, "path">>
toBackendPath()
Section titled “toBackendPath()”
protectedtoBackendPath(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
toBytes()
Section titled “toBytes()”
protectedtoBytes(content):Uint8Array
Parameters
Section titled “Parameters”content
Section titled “content”Returns
Section titled “Returns”Uint8Array
toRelativePath()
Section titled “toRelativePath()”
protectedtoRelativePath(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
tryAppendFileAt()
Section titled “tryAppendFileAt()”
protectedtryAppendFileAt(_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>
tryCopyFileAt()
Section titled “tryCopyFileAt()”
protectedtryCopyFileAt(_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>
tryMoveFileAt()
Section titled “tryMoveFileAt()”
protectedtryMoveFileAt(_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>
writeBytesAt()
Section titled “writeBytesAt()”
abstractprotectedwriteBytesAt(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>
writeFile()
Section titled “writeFile()”writeFile(
inputPath,content,options?):Promise<void>
Parameters
Section titled “Parameters”inputPath
Section titled “inputPath”string
content
Section titled “content”options?
Section titled “options?”WriteFileOptions = {}
Returns
Section titled “Returns”Promise<void>