vaultmd / NotesApi
Type Alias: NotesApi
NotesApi =
object
Defined in: src/notes/models/notes-api.ts:14
The notes CRUD surface, exposed as vault.notes. Every method takes a vault-relative path; the five mutating methods (createNote, updateNote, editFrontmatter, transformNote, deleteNote) run inside the per-file lock so the .md file and its index row never drift. readNote is a consistent read and does not acquire the lock.
Methods
createNote()
createNote(
path,input):Promise<void>
Defined in: src/notes/models/notes-api.ts:31
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:73
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:45
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.
readNote()
readNote(
path,opts?):Promise<ReadNoteResult>
Defined in: src/notes/models/notes-api.ts:22
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:65
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:39
Mutate a note body — either append text or replace a single unique match.
Parameters
path
string
op
Returns
Promise<void>
Throws
MdVaultError NO_MATCH / AMBIGUOUS_MATCH for editByMatch.