The DataAdapter interface provides low-level access to the file system. It is implemented by platform-specific adapters like FileSystemAdapter (desktop) and CapacitorAdapter (mobile). If possible, prefer using the Vault API over this interface.
Implementations
- FileSystemAdapter - Desktop implementation
- CapacitorAdapter - Mobile implementation (iOS/Android)
Methods
getName
Get the name of the adapter.
Returns: The adapter name (e.g., “file-system”, “capacitor”).
exists
exists(normalizedPath: string, sensitive?: boolean): Promise<boolean>
Vault.getAbstractFileByPath.
Path to file/folder, use normalizePath() to normalize beforehand.
Some file systems/operating systems are case-insensitive, set to true to force a case-sensitivity check.
true if the path exists.
stat
stat(normalizedPath: string): Promise<Stat | null>
Path to file/folder, use normalizePath() to normalize beforehand.
null if not found.
Since: 0.12.2
interface Stat {
type: 'file' | 'folder';
ctime: number; // Creation time (unix timestamp)
mtime: number; // Modification time (unix timestamp)
size: number; // Size in bytes
}
list
list(normalizedPath: string): Promise<ListedFiles>
Path to folder, use normalizePath() to normalize beforehand.
interface ListedFiles {
files: string[]; // Array of file paths
folders: string[]; // Array of folder paths
}
read
read(normalizedPath: string): Promise<string>
Path to file, use normalizePath() to normalize beforehand.
readBinary
readBinary(normalizedPath: string): Promise<ArrayBuffer>
Path to file, use normalizePath() to normalize beforehand.
write
write(normalizedPath: string, data: string, options?: DataWriteOptions): Promise<void>
Path to file, use normalizePath() to normalize beforehand.
Optional write options (ctime, mtime).
writeBinary
writeBinary(normalizedPath: string, data: ArrayBuffer, options?: DataWriteOptions): Promise<void>
Path to file, use normalizePath() to normalize beforehand.
Optional write options (ctime, mtime).
append
append(normalizedPath: string, data: string, options?: DataWriteOptions): Promise<void>
Path to file, use normalizePath() to normalize beforehand.
appendBinary
appendBinary(normalizedPath: string, data: ArrayBuffer, options?: DataWriteOptions): Promise<void>
Path to file, use normalizePath() to normalize beforehand.
process
process(normalizedPath: string, fn: (data: string) => string, options?: DataWriteOptions): Promise<string>
Path to file, use normalizePath() to normalize beforehand.
fn
(data: string) => string
required
A callback function which returns the new content of the file synchronously.
getResourcePath
getResourcePath(normalizedPath: string): string
Path to file, use normalizePath() to normalize beforehand.
mkdir
mkdir(normalizedPath: string): Promise<void>
Path to use for new folder, use normalizePath() to normalize beforehand.
trashSystem
trashSystem(normalizedPath: string): Promise<boolean>
Path to file/folder, use normalizePath() to normalize beforehand.
true if succeeded. This can fail due to system trash being disabled.
trashLocal
trashLocal(normalizedPath: string): Promise<void>
.trash folder at the root of the vault.
Path to file/folder, use normalizePath() to normalize beforehand.
rmdir
rmdir(normalizedPath: string, recursive: boolean): Promise<void>
Path to folder, use normalizePath() to normalize beforehand.
If true, delete folders under this folder recursively. If false, the folder needs to be empty.
remove
remove(normalizedPath: string): Promise<void>
Path to file, use normalizePath() to normalize beforehand.
rename
rename(normalizedPath: string, normalizedNewPath: string): Promise<void>
Current path to file/folder, use normalizePath() to normalize beforehand.
New path to file/folder, use normalizePath() to normalize beforehand.
copy
copy(normalizedPath: string, normalizedNewPath: string): Promise<void>
normalizedNewPath.
Path to file, use normalizePath() to normalize beforehand.
Path for the copy, use normalizePath() to normalize beforehand.
Types
DataWriteOptions
interface DataWriteOptions {
ctime?: number; // Creation time (unix timestamp in milliseconds)
mtime?: number; // Modification time (unix timestamp in milliseconds)
}
Usage
Access the adapter through the Vault:
const adapter = this.app.vault.adapter;
console.log('Adapter name:', adapter.getName());
Examples
Using the adapter directly
import { normalizePath } from 'obsidian';
const adapter = this.app.vault.adapter;
const path = normalizePath('MyFolder/MyFile.md');
// Check if file exists
const exists = await adapter.exists(path);
console.log('File exists:', exists);
if (exists) {
// Read file
const content = await adapter.read(path);
console.log('Content:', content);
// Get file stats
const stat = await adapter.stat(path);
console.log('File size:', stat?.size);
}
Listing directory contents
import { normalizePath } from 'obsidian';
const adapter = this.app.vault.adapter;
const folderPath = normalizePath('MyFolder');
const listed = await adapter.list(folderPath);
console.log('Files:', listed.files);
console.log('Folders:', listed.folders);
const adapter = this.app.vault.adapter;
if (adapter instanceof FileSystemAdapter) {
// Desktop-specific: Get base path
const basePath = adapter.getBasePath();
console.log('Vault location:', basePath);
}
if (adapter instanceof CapacitorAdapter) {
// Mobile-specific operations
console.log('Running on mobile');
}
Writing with custom timestamps
import { normalizePath } from 'obsidian';
const adapter = this.app.vault.adapter;
const path = normalizePath('MyFile.md');
const customTime = new Date('2024-01-01').getTime();
await adapter.write(path, 'File content', {
ctime: customTime,
mtime: customTime
});
console.log('File created with custom timestamp');
Notes
- Always use
normalizePath() to normalize paths before passing them to adapter methods.
- The adapter works with vault-relative paths, not absolute file system paths.
- Prefer using the Vault API when possible, as it provides additional features like event notifications and better integration with Obsidian’s caching system.
- Vault - Higher-level file operations
- TFile - File representation
- TFolder - Folder representation
