VaultMD / VaultIo
Type Alias: VaultIo
VaultIo =
object
Defined in: src/vault-io/models/vault-io.ts:16
The IO chokepoint for a vault: canonicalization, allowlist enforcement, and atomic file operations, all scoped to the vault root and prefix allowlists. Obtain an instance via createVaultIo or from Vault.io.
Every path-taking member shares one gate. Beyond the allowlist and ..-escape rejection, hidden state is unreachable: a path with a dot-segment is refused — on both the requested path and the symlink- resolved target — so .git, .env, .obsidian and the index's own .db sidecars stay out of reach even behind a link that never leaves the vault.
Methods
can()
can(
rel,access):boolean
Defined in: src/vault-io/models/vault-io.ts:39
Test whether rel falls within the given access allowlist. A hidden (dot-segment) path is never permitted, whatever the allowlist says.
Parameters
rel
string
Vault-relative path to test.
access
'read' or 'write' allowlist to check against.
Returns
boolean
true if the path is permitted; false otherwise.
listFolders()
listFolders(
dir?):Promise<string[]>
Defined in: src/vault-io/models/vault-io.ts:149
Enumerate the folders under dir (default: vault root) that pass the read allowlist, skipping dot-folders, ignore matches, and directories whose real target escapes the vault root — the same walk listMarkdown uses. Empty folders are listed: a directory exists on disk whether or not it holds markdown. The root is never included, and a folder whose own parent is outside the read scope still appears, so treat a missing parent as implied when building a tree from the returned paths.
Parameters
dir?
string
Optional vault-relative subdirectory to constrain the listing.
Returns
Promise<string[]>
Sorted vault-relative paths of enumerated folders.
listMarkdown()
listMarkdown(
dir?):Promise<string[]>
Defined in: src/vault-io/models/vault-io.ts:137
Enumerate all .md files under dir (default: vault root) that pass the read allowlist and are not matched by the ignore patterns.
Parameters
dir?
string
Optional vault-relative subdirectory to constrain the listing.
Returns
Promise<string[]>
Sorted vault-relative paths of enumerated .md files.
readBinary()
readBinary(
rel):Promise<Uint8Array<ArrayBufferLike> |null>
Defined in: src/vault-io/models/vault-io.ts:98
Read any vault file as raw bytes, .md or not — the read path for attachments (images, PDFs, audio). Enforced by the same chokepoint as readVaultFile: canonicalization, the read allowlist, symlink containment, and the hidden-state guard. Only the .md requirement is lifted.
Attachments are not indexed and there is no matching write path — this is read-only access to bytes already on disk.
Parameters
rel
string
Vault-relative path, any extension.
Returns
Promise<Uint8Array<ArrayBufferLike> | null>
The file's bytes, or null if the path is absent, dangling, or a directory.
Throws
MdVaultError ALLOWLIST_VIOLATION if rel is outside the read allowlist, escapes the root, or names a hidden (dot-segment) path.
readVaultFile()
readVaultFile(
rel):Promise<{content:string;sig:Sig; } |null>
Defined in: src/vault-io/models/vault-io.ts:76
Read a vault file consistently, returning its content and filesystem signature for optimistic-concurrency checks.
Parameters
rel
string
Vault-relative .md path.
Returns
Promise<{ content: string; sig: Sig; } | null>
{ content, sig } if the file exists, or null if absent.
resolveVaultPath()
resolveVaultPath(
rel,access?):string
Defined in: src/vault-io/models/vault-io.ts:49
Resolve a vault-relative path to its absolute filesystem path, enforcing the allowlist and the .md extension requirement.
Parameters
rel
string
Vault-relative .md path.
access?
Allowlist tier to enforce (default 'read').
Returns
string
The absolute filesystem path.
Throws
MdVaultError NOT_MARKDOWN if rel is not a .md path.
Throws
MdVaultError ALLOWLIST_VIOLATION if rel is outside the allowlist.
resolveWriteTarget()
resolveWriteTarget(
rel):object
Defined in: src/vault-io/models/vault-io.ts:62
Resolve everything a write-path mutator needs in a single canonicalization pass: the absolute filesystem path (write-allowlist + symlink enforced), the case-folded index/lock key, and the canonical vault-relative path. Equivalent to calling resolveVaultPath ('write'), toKey, and toVaultRelative together, but canonicalizes rel only once.
Parameters
rel
string
Vault-relative .md path.
Returns
{ full, key, relative } for the write target.
full
full:
string
Absolute filesystem path of the write target.
key
key:
string
Case-folded index/lock key — see toKey.
relative
relative:
string
Canonical vault-relative path — see toVaultRelative.
Throws
MdVaultError NOT_MARKDOWN if rel is not a .md path.
Throws
MdVaultError ALLOWLIST_VIOLATION if rel is outside the write allowlist or escapes the root via a symlink.
rewriteIfUnchanged()
rewriteIfUnchanged(
rel,content,expected):Promise<Sig>
Defined in: src/vault-io/models/vault-io.ts:114
Atomically overwrite a file only if its current signature matches expected. Throws MdVaultError MTIME_CONFLICT on mismatch.
Parameters
rel
string
Vault-relative .md path.
content
string
New UTF-8 content.
expected
Signature the file must currently have.
Returns
Promise<Sig>
The Sig of the written file.
stat()
stat(
rel):Promise<Sig|null>
Defined in: src/vault-io/models/vault-io.ts:130
Stat a vault file, returning its filesystem signature.
Parameters
rel
string
Vault-relative .md path.
Returns
Promise<Sig | null>
The Sig of the file, or null if absent.
toKey()
toKey(
rel):string
Defined in: src/vault-io/models/vault-io.ts:31
Derive the index look-up key for a vault-relative path. On case-insensitive volumes this lower-cases the canonical path; on case-sensitive volumes it is identical to toVaultRelative.
Parameters
rel
string
Vault-relative path to key.
Returns
string
The case-folded (or canonical) key string.
toVaultRelative()
toVaultRelative(
rel):string
Defined in: src/vault-io/models/vault-io.ts:23
Canonicalize a vault-relative path (normalize separators and ./.. segments) without applying case-folding.
Parameters
rel
string
Vault-relative path to canonicalize.
Returns
string
The canonical vault-relative form of rel.
unlinkIfUnchanged()
unlinkIfUnchanged(
rel,expected):Promise<boolean>
Defined in: src/vault-io/models/vault-io.ts:124
Unlink a file only if its current signature matches expected.
Parameters
rel
string
Vault-relative .md path.
expected
Signature the file must currently have.
Returns
Promise<boolean>
true if the file was deleted; false only if the file was already absent.
Throws
MdVaultError MTIME_CONFLICT if the file's current signature differs from expected (concurrent modification detected).
writeVaultFile()
writeVaultFile(
rel,content):Promise<Sig>
Defined in: src/vault-io/models/vault-io.ts:105
Atomically write content to a vault file, creating it if necessary.
Parameters
rel
string
Vault-relative .md path.
content
string
New UTF-8 content.
Returns
Promise<Sig>
The Sig of the written file.