vaultmd / VaultIo
Type Alias: VaultIo
VaultIo =
object
Defined in: src/vault-io/models/vault-io.ts:10
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.
Methods
can()
can(
rel,access):boolean
Defined in: src/vault-io/models/vault-io.ts:32
Test whether rel falls within the given access allowlist.
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.
listMarkdown()
listMarkdown(
dir?):Promise<string[]>
Defined in: src/vault-io/models/vault-io.ts:113
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.
readVaultFile()
readVaultFile(
rel):Promise<{content:string;sig:Sig; } |null>
Defined in: src/vault-io/models/vault-io.ts:69
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:42
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:55
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:90
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:106
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:25
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:17
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:100
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:81
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.