VaultMD / NotesApi
Type Alias: NotesApi
NotesApi =
object
Defined in: src/notes/models/notes-api.ts:15
The notes CRUD surface, exposed as vault.notes. Every method takes a vault-relative path; the six mutating methods (createNote, updateNote, editFrontmatter, transformNote, deleteNote, moveNote) run inside the per-file lock so the .md file and its index row never drift (moveNote holds both ends' locks). readNote and exists are consistent reads and do not acquire the lock.
Methods
createNote()
createNote(
path,input):Promise<void>
Defined in: src/notes/models/notes-api.ts:43
Create a new note, writing frontmatter + body. Never clobbers an existing file.
Parameters
path
string
input
body
string
frontmatter?
Record<string, unknown>
Returns
Promise<void>
Throws
MdVaultError ALREADY_EXISTS if the path is taken.
deleteNote()
deleteNote(
path):Promise<boolean>
Defined in: src/notes/models/notes-api.ts:89
Delete a note and drop its index row.
Parameters
path
string
Returns
Promise<boolean>
true if a file was deleted, false if it was already absent.
editFrontmatter()
editFrontmatter(
path,mutate):Promise<EditOutcome>
Defined in: src/notes/models/notes-api.ts:61
Edit a note's frontmatter in place via a mutator callback.
Parameters
path
string
mutate
(fm) => void
Returns
Promise<EditOutcome>
Whether the frontmatter was edited, unchanged, or unverifiable.
exists()
exists(
path):Promise<boolean>
Defined in: src/notes/models/notes-api.ts:37
Whether a note exists at path — the non-throwing probe that turns the create-or-update dance into a plain branch instead of a try/catch on ALREADY_EXISTS. Checked against the READ allowlist.
Parameters
path
string
Vault-relative path to the .md file.
Returns
Promise<boolean>
true if a file is present, false if not.
Throws
MdVaultError NOT_MARKDOWN if path is not a .md path, or ALLOWLIST_VIOLATION if it is outside the read scope — an unreadable path is a caller bug, not an absent note.
moveNote()
moveNote(
from,to):Promise<void>
Defined in: src/notes/models/notes-api.ts:103
Move a note to a new vault-relative path, byte-for-byte: the content and its frontmatter are carried over untouched, and the index row follows to the new path. Both ends are allowlist- and containment-checked; the destination is never clobbered. Runs under BOTH per-file locks, so a concurrent write to either end serializes against it.
Parameters
from
string
Vault-relative path of the note to move.
to
string
Vault-relative destination path (must be a free .md path).
Returns
Promise<void>
Throws
MdVaultError VALIDATION_ERROR if from and to resolve to the same note, NOT_FOUND if from does not exist, ALREADY_EXISTS if to is taken (the source is left in place), or MTIME_CONFLICT if the source changed mid-move (the destination is rolled back).
readNote()
readNote(
path,opts?):Promise<ReadNoteResult>
Defined in: src/notes/models/notes-api.ts:23
Read a note's parsed frontmatter, tags, body, and frontmatter validity.
Parameters
path
string
Vault-relative path to the .md file.
opts?
When withLinks is true, also resolve outbound and backlinks for the note.
withLinks?
boolean
Returns
Promise<ReadNoteResult>
Throws
MdVaultError NOT_FOUND if the file does not exist.
transformNote()
transformNote(
path,transform):Promise<TransformOutcome>
Defined in: src/notes/models/notes-api.ts:81
Run a free-form transform over a note's FULL content inside the per-file lock, with write-through indexing. allowCreate is always false: existing file, transform → string : write + index → 'edited' any file, transform → null : no write → 'unchanged' MISSING file, transform → string : throws REFUSE_CREATE MISSING file, transform → null : 'unchanged' (no throw) The callback is RE-INVOKED on each MTIME_CONFLICT retry, so it must be a pure function of current (side-effects must overwrite, not accumulate). A null or undefined return is a no-op; a return byte-identical to the current content is also a no-op (no rewrite, no reindex) → 'unchanged'.
Parameters
path
string
transform
(current) => string | null
Returns
Promise<TransformOutcome>
Throws
MdVaultError REFUSE_CREATE if asked to write a missing file, MTIME_CONFLICT if a concurrent writer keeps winning past the retry budget, or COMMIT_FAILED if the write-through index update or the onCommit hook throws.
updateNote()
updateNote(
path,op):Promise<void>
Defined in: src/notes/models/notes-api.ts:55
Mutate a note's body, leaving any frontmatter block verbatim: append and prepend add text at either end (both create the note when it is absent), setBody replaces the body wholesale, and editByMatch replaces a single unique substring.
Parameters
path
string
op
Returns
Promise<void>
Throws
MdVaultError NO_MATCH / AMBIGUOUS_MATCH for editByMatch, or REFUSE_CREATE when setBody targets a missing note.