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, readSection, 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:75
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:123
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:95
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:69
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:137
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.
readSection()
readSection(
path,heading):Promise<string>
Defined in: src/notes/models/notes-api.ts:58
Read the body of the section opened by a heading — everything after the heading line up to the next heading of the same or a shallower level, or the end of the file. Subsections are included; blank lines directly after the heading and directly before the next one are not, so the result can be written straight back with updateNote({ setSection }) without disturbing the file's spacing.
The heading is matched by exact, case-sensitive text against a CLOSED frontmatter block's body; an unterminated --- is not frontmatter and its headings are addressable like any other content.
This is a plain read and takes no lock. Pairing it with setSection is therefore last-writer-wins across the two calls — use transformNote with extractHeadings when a concurrent writer must not be lost.
A section whose span runs into an unterminated code fence is not addressable and throws VALIDATION_ERROR. Per CommonMark such a fence runs to the end of the file, so the section would swallow every heading after it — reading it would return content the author never meant as this section, and writing it back would delete that content. Close the fence, or reach for NotesApi.transformNote.
Parameters
path
string
Vault-relative path to the .md file.
heading
string
Exact heading text, without the leading # characters.
Returns
Promise<string>
The section body, verbatim, or '' when the section is empty.
Throws
MdVaultError NOT_FOUND if the file does not exist, NO_MATCH if no heading has that text, AMBIGUOUS_MATCH if more than one does — drop to extractHeadings to disambiguate — or VALIDATION_ERROR if the section runs into an unterminated fence.
transformNote()
transformNote(
path,transform):Promise<TransformOutcome>
Defined in: src/notes/models/notes-api.ts:115
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:89
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, editByMatch replaces a single unique substring, and setSection replaces the body under one heading.
Parameters
path
string
op
Returns
Promise<void>
Throws
MdVaultError NO_MATCH / AMBIGUOUS_MATCH for editByMatch and setSection, REFUSE_CREATE when setBody targets a missing note, or VALIDATION_ERROR when a setSection body would restructure the document outside its own section.