Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
/**
* Public type surface for Trilium **user scripts** — the shape of the `api`
* global available inside frontend/backend script notes.
*
* This is the single source of truth for script API types, consumed by:
* - the in-editor TypeScript language service (bundled into the script-note vfs),
* - the `script-deployer` app (script authoring/typechecking),
* and kept honest against the real implementations by member-presence drift
* guards (see `frontend_script_api.ts` / `backend_script_api.ts`).
*
* It is intentionally **self-contained** (no imports): the real `Api` interfaces
* drag in the whole client/server graph (froca, widgets, jQuery, Vite `?raw`
* imports) which can't be resolved by a browser-based language service. These
* are faithful, decoupled re-declarations of the public surface — heavy or
* advanced members (widget base classes, editor instances, the Preact API) are
* typed as `unknown` rather than pulling in their real types.
*/
/** One thing a picker offers, as `pickSingleItem` takes and answers with. */
export interface PickerItem {
/**
* The ID of the item. It must be unique within its group, and tells the script which item the
* user picked.
*/
key: string;
/** The text shown for the item. The search field filters items by it. */
caption: string;
/** An icon class, `bx` prefix included. */
icon?: string;
/** HTML shown in a tooltip while the item is hovered. */
tooltip?: string;
}
/** A run of picker items under a heading of their own. */
export interface PickerItemGroup {
/** The ID of the group. It must be unique among the groups. */
key: string;
/**
* The heading shown above the group's items. An empty string shows the items without a heading.
*/
groupHeader: string;
/** The items in the group, in the order the picker shows them. */
items: PickerItem[];
}
/** A label or relation attached to a note. */
export interface ScriptAttribute {
/** The ID of the attribute. */
attributeId: string;
/** The type of the attribute: `label` or `relation`. */
type: "label" | "relation";
/** The name of the attribute, without the `#` or `~` prefix. */
name: string;
/**
* The value of the attribute. For a relation, it is the ID of the target note. For a label
* without a value, it is an empty string.
*/
value: string;
/** Whether the note's descendants inherit the attribute. */
isInheritable: boolean;
/**
* Not set by Trilium: neither frontend nor backend attributes carry this property, so it reads
* `undefined`.
*/
isOwned: boolean;
}
/** An attachment as seen by frontend scripts (subset of the client's `FAttachment`). */
export interface ScriptAttachment {
/** The ID of the attachment. */
attachmentId: string;
/**
* The ID of the note the attachment belongs to. For an attachment of a revision, it is the ID
* of the revision.
*/
ownerId: string;
/**
* The purpose of the attachment, such as `image` for an image shown in a text note or `file`
* for an attached file. Trilium also uses roles of its own, such as `viewConfig` for a
* collection's view settings.
*/
role: string;
/** The MIME type of the attachment's content, such as `image/png`. */
mime: string;
/** The title of the attachment, usually its file name. */
title: string;
/**
* The date and time, in UTC, that the attachment was last saved, such as `2026-10-22
* 12:03:05.123Z`. Replacing the content counts as saving.
*/
utcDateModified: string;
/**
* The length of the attachment's content. Only some ways of loading an attachment fill it in,
* such as `getAttachments()`.
*/
contentLength: number;
}
/** Creation/modification timestamps returned by {@link ScriptFNote.getMetadata}. */
export interface ScriptNoteMetadata {
/**
* The local date and time the note was created, with the UTC offset, such as `2026-10-22
* 14:03:05.123+0200`.
*/
dateCreated: string;
/** The date and time, in UTC, that the note was created, such as `2026-10-22 12:03:05.123Z`. */
utcDateCreated: string;
/**
* The local date and time the note was last modified, with the UTC offset, such as `2026-10-22
* 14:03:05.123+0200`. A change to the note's content counts as a modification.
*/
dateModified: string;
/**
* The date and time, in UTC, that the note was last modified, such as `2026-10-22
* 12:03:05.123Z`. A change to the note's content counts as a modification.
*/
utcDateModified: string;
}
/** A note's binary/text content blob (subset of the client's `FBlob`). */
export interface ScriptBlob {
/**
* The ID of the blob, derived from its content. Notes, attachments and revisions with identical
* content share one blob.
*/
blobId: string;
/**
* The content as text. It is `null` when the content is binary, as in images and files.
*/
content: string;
/**
* The length of the content as stored: characters for text, bytes for binary content. For a
* protected note, it measures the encrypted content.
*/
contentLength: number;
/**
* The local date and time this content was first stored, with the UTC offset, such as
* `2026-10-22 14:03:05.123+0200`. A blob never changes, so new content gets a new blob.
*/
dateModified: string;
/**
* The date and time, in UTC, that this content was first stored, such as `2026-10-22
* 12:03:05.123Z`.
*/
utcDateModified: string;
}
/** One resolved tree path to a note (subset of the client's `NotePathRecord`). */
export interface ScriptNotePathRecord {
/**
* Whether a note on the path, the note itself included, is archived, which means it has the
* `#archived` label, owned or inherited.
*/
isArchived: boolean;
/**
* Whether the path passes through the hoisted note passed to `getSortedNotePathRecords()`. It
* is always `true` when the hoisted note is `root`.
*/
isInHoistedSubTree: boolean;
/**
* Whether the note itself is a search note. Only frontend scripts get this property; backend
* records leave it out.
*/
isSearch?: boolean;
/** The note IDs along the path, from `root` to the note itself. */
notePath: string[];
/**
* Whether the path passes through the hidden subtree, `_hidden`, which holds Trilium's system
* notes.
*/
isHidden: boolean;
}
/** A note as seen by frontend scripts (subset of the client's `FNote`). */
export interface ScriptFNote {
/** The ID of the note. */
noteId: string;
/**
* The title of the note. For a protected note, it is `[protected]` until a protected session is
* started.
*/
title: string;
/**
* The note type, such as `text`, `code`, `file`, `image`, `search`, `book`, `render` or
* `launcher`.
*/
type: string;
/** The MIME type of the note's content, such as `application/json`. */
mime: string;
/** Whether the note is protected (encrypted). */
isProtected: boolean;
/** Whether the note is archived (has the `archived` label). */
isArchived: boolean;
/**
* Whether the note's title and icon cannot be edited, which is the case for the system notes
* behind the options, the in-app help and the launch bar configuration.
*/
isMetadataReadOnly: boolean;
/** IDs of this note's owned attributes. */
attributes: string[];
/** IDs of relations pointing *at* this note. */
targetRelations: string[];
/** Parent note IDs. */
parents: string[];
/** Child note IDs. */
children: string[];
// --- Hierarchy ---------------------------------------------------------
/**
* Returns the parent notes that the client has already loaded. A parent that is not loaded is
* skipped, and a search note that shows this note in its results counts as a parent.
*/
getParentNotes(): ScriptFNote[];
/**
* Loads any missing child notes from the server, then returns all child notes in tree order.
* Archived children are included.
*/
getChildNotes(): Promise<ScriptFNote[]>;
/**
* Returns the IDs of the parent notes. The returned array is the note's own list, so do not
* change it.
*/
getParentNoteIds(): string[];
/**
* Returns the IDs of the child notes in tree order, archived ones included. The returned array
* is the note's own list, so do not change it.
*/
getChildNoteIds(): string[];
/**
* Returns the IDs of the child notes in tree order, leaving out archived notes unless
* `includeArchived` is `true`. Leaving out archived notes takes a search on the server; for a
* search note or a note in the hidden subtree, all children are returned.
*
* @param includeArchived whether to keep archived children. Defaults to `false`.
*/
getChildNoteIdsWithArchiveFiltering(includeArchived?: boolean): Promise<string[]>;
/**
* Returns all descendants of the note, loading missing ones from the server one level at a
* time. An archived note and everything below it are left out, and the note itself is not
* included.
*/
getSubtreeNotes(): Promise<ScriptFNote[]>;
/**
* Returns the IDs of all the note's descendants, depth-first, without the note itself. Archived
* notes and the notes below them are left out unless `includeArchived` is `true`.
*/
getSubtreeNoteIds(includeArchived?: boolean): Promise<string[]>;
/**
* Returns `true` if the note has at least one child, archived ones included. For a search note,
* the results count as children only once they are loaded.
*/
hasChildren(): boolean;
/**
* Returns `true` if the note with the given ID is this note or one of its ancestors. It walks
* only parents the client has already loaded.
*
* @param followTemplates whether to also walk up from the notes this note takes attributes from
* through `~template` and `~inherit` relations. Defaults to `false`.
*/
hasAncestor(ancestorNoteId: string, followTemplates?: boolean): boolean;
/** Returns `true` if this is the root note of the tree. */
isRoot(): boolean;
/** Returns the IDs of the branches that place this note under each of its parents. */
getParentBranchIds(): string[];
/**
* Returns the IDs of the branches that place the note under its parents.
*
* @deprecated Use `getParentBranchIds()` instead.
*/
getBranchIds(): string[];
/**
* Returns the branches that place this note under each of its parents. A branch the client has
* not loaded is skipped.
*/
getParentBranches(): ScriptFBranch[];
/**
* Returns the branches to this note's children, in tree order. A branch the client has not
* loaded is skipped.
*/
getChildBranches(): ScriptFBranch[];
/**
* Returns the branches that place the note under its parents.
*
* @deprecated Use `getParentBranches()` instead.
*/
getBranches(): ScriptFBranch[];
/**
* Returns the same branches as `getChildBranches()`. Despite the name, archived children are
* not filtered out.
*/
getFilteredChildBranches(): ScriptFBranch[];
/**
* Returns every path from the root to the note, each as a list of note IDs that starts with
* `root`. Paths that pass through a search note are left out.
*/
getAllNotePaths(): string[][];
/**
* Returns the note's best path as a list of note IDs that starts with `root`. Paths inside the
* hoisted note's subtree come first, then paths without archived or hidden notes; among equal
* paths, the one sharing the longest start with `activeNotePath` wins, then the shortest.
*
* @param hoistedNoteId The hoisted note, `root` by default.
* @param activeNotePath The path of the active note, as note IDs joined by `/`.
*/
getBestNotePath(hoistedNoteId?: string, activeNotePath?: string | null): string[];
/**
* Returns the note's best path, as `getBestNotePath()` chooses it, as note IDs joined by `/`,
* such as `root/a1h315/js725h`.
*
* @param hoistedNoteId The hoisted note, `root` by default.
*/
getBestNotePathString(hoistedNoteId?: string): string;
/**
* Returns every path from the root to this note, best first. Paths inside the hoisted note come
* first, then paths that do not pass through an archived note or the hidden subtree, then paths
* that share the most with `activeNotePath`, then shorter paths. Paths through search notes are
* left out, and only parents the client has loaded are followed.
*
* @param hoistedNoteId the ID of the hoisted note. Defaults to `root`.
* @param activeNotePath a note path such as `root/abc123/def456`, used to prefer paths close to
* it.
*/
getSortedNotePathRecords(
hoistedNoteId?: string,
activeNotePath?: string | null
): ScriptNotePathRecord[];
// --- Attributes (inherited + own) --------------------------------------
/**
* Returns the note's attributes, including inherited ones, optionally only those of the given
* type and name. The note's own attributes come first, then the ones inherited from its
* parents, then the ones from its templates.
*
* @param type `label` or `relation`; any other value throws an error.
* @param name The attribute name, without the `#` or `~` prefix.
*/
getAttributes(type?: string, name?: string): ScriptAttribute[];
/**
* Returns the note's own attributes, without inherited ones, optionally only those of the given
* type and name.
*
* @param type `label` or `relation`; any other value throws an error.
* @param name The attribute name, without the `#` or `~` prefix.
*/
getOwnedAttributes(type?: string, name?: string): ScriptAttribute[];
/**
* Returns the first attribute of the given type and name, including inherited ones, or
* `undefined` if the note has none.
*
* @param type `label` or `relation`.
*/
getAttribute(type: string, name: string): ScriptAttribute | null;
/**
* Returns the first of the note's own attributes with the given type and name, or `undefined`
* if the note has none.
*
* @param type `label` or `relation`.
*/
getOwnedAttribute(type: string, name: string): ScriptAttribute | null;
/**
* Returns the value of the first attribute of the given type and name, including inherited
* ones, or `null` if the note has none.
*
* @param type `label` or `relation`.
*/
getAttributeValue(type: string, name: string): string | null;
/**
* Returns the value of the first of the note's own attributes with the given type and name, or
* `null` if the note has none.
*
* @param type `label` or `relation`.
*/
getOwnedAttributeValue(type: string, name: string): string | null;
/**
* Returns whether the note has an attribute of the given type and name, including inherited
* ones.
*
* @param type `label` or `relation`.
*/
hasAttribute(type: string, name: string): boolean;
/**
* Returns whether the note itself has an attribute of the given type and name, without
* inherited ones.
*
* @param type `label` or `relation`.
*/
hasOwnedAttribute(type: string, name: string): boolean;
/**
* Returns the attribute definitions that apply to the note, at most one per defined name.
* When the note gets a definition from several places, such as its own, an ancestor's and a
* template's, the nearest one wins, in the order `getAttributes()` lists them.
*/
getAttributeDefinitions(): ScriptAttribute[];
/**
* Returns the attribute definitions that are marked as promoted, at most one per name, grouped
* by the note that owns them and ordered by position. Returns an empty array if the note has a
* truthy `hidePromotedAttributes` label.
*/
getPromotedDefinitionAttributes(): ScriptAttribute[];
// --- Labels ------------------------------------------------------------
/** Returns the note's labels, including inherited ones, optionally only those with `name`. */
getLabels(name?: string): ScriptAttribute[];
/** Returns the note's own labels, without inherited ones, optionally only those with `name`. */
getOwnedLabels(name?: string): ScriptAttribute[];
/**
* Returns the first label with the given name, including inherited ones, or `undefined` if the
* note has none.
*/
getLabel(name: string): ScriptAttribute | null;
/**
* Returns the first of the note's own labels with the given name, or `undefined` if the note
* has none.
*/
getOwnedLabel(name: string): ScriptAttribute | null;
/**
* Returns the value of the first label with the given name, including inherited ones, or
* `null` if the note has none.
*/
getLabelValue(name: string): string | null;
/**
* Returns the value of the first of the note's own labels with the given name, or `null` if the
* note has none.
*/
getOwnedLabelValue(name: string): string | null;
/** Returns whether the note has a label with the given name, including inherited ones. */
hasLabel(name: string): boolean;
/** Returns whether the note itself has a label with the given name, without inherited ones. */
hasOwnedLabel(name: string): boolean;
/**
* Returns whether the note has a label with the given name, including inherited ones, or the
* same label with the `disabled:` prefix, which a safe import gives it.
*/
hasLabelOrDisabled(name: string): boolean;
/**
* Returns whether the note has a label with the given name, including inherited ones, whose
* value is anything but `false`. A label without a value counts as true.
*/
isLabelTruthy(name: string): boolean;
// --- Relations ---------------------------------------------------------
/**
* Returns the note's relations, including inherited ones, optionally only those with `name`.
*/
getRelations(name?: string): ScriptAttribute[];
/**
* Returns the note's own relations, without inherited ones, optionally only those with `name`.
*/
getOwnedRelations(name: string): ScriptAttribute[];
/**
* Returns the first relation with the given name, including inherited ones, or `undefined` if
* the note has none.
*/
getRelation(name: string): ScriptAttribute | null;
/**
* Returns the first of the note's own relations with the given name, or `undefined` if the note
* has none.
*/
getOwnedRelation(name: string): ScriptAttribute | null;
/**
* Returns the target note ID of the first relation with the given name, including inherited
* ones, or `null` if the note has none.
*/
getRelationValue(name: string): string | null;
/**
* Returns the target note ID of the first of the note's own relations with the given name, or
* `null` if the note has none.
*/
getOwnedRelationValue(name: string): string | null;
/** Returns whether the note has a relation with the given name, including inherited ones. */
hasRelation(name: string): boolean;
/**
* Returns whether the note itself has a relation with the given name, without inherited ones.
*/
hasOwnedRelation(name: string): boolean;
/**
* Returns the value of a label or relation, inherited ones included, or `null` if the note has
* none. A relation's value is the ID of its target note.
*
* @param nameWithPrefix the attribute name prefixed with `#` for a label or `~` for a relation.
* A name without a prefix is looked up as a label.
*/
getLabelOrRelation(nameWithPrefix: string): string | null;
/**
* Returns the target note of the first relation with the given name, including inherited ones.
* Returns `null` if the note has no such relation, the relation has no target, or the target
* note does not exist.
*/
getRelationTarget(name: string): Promise<ScriptFNote | null>;
/**
* Returns the target notes of the note's relations with the given name, including inherited
* ones, in the order of the relations. A relation whose target is missing gives `null`.
*/
getRelationTargets(name: string): Promise<(ScriptFNote | null)[]>;
/** Returns the relations, owned by any note, that point at this note. */
getTargetRelations(): ScriptAttribute[];
/** Returns the notes that own a relation pointing at this note. */
getTargetRelationSourceNotes(): Promise<ScriptFNote[]>;
// --- Content & attachments ---------------------------------------------
/**
* Fetches the note's content from the server. Resolves to a string for text-based notes; for a
* binary note such as an image or file, the content is not sent, and for a protected note
* without a protected session, it is an empty string.
*/
getContent(): Promise<string | Uint8Array>;
/**
* Fetches the note's content and parses it as JSON. Resolves to `null` if the content is empty,
* is not a string, or is not valid JSON.
*/
getJsonContent(): Promise<unknown>;
/**
* Fetches the note's content together with its blob ID, length and modification date. Resolves
* to `null` if the request fails.
*/
getBlob(): Promise<ScriptBlob | null>;
/**
* Returns the blob that holds the note's content.
*
* @deprecated Use `getBlob()` instead.
*/
getNoteComplement(): Promise<ScriptBlob | null>;
/** Returns the note's creation and modification dates, which it requests from the server. */
getMetadata(): Promise<ScriptNoteMetadata>;
/**
* The note's attachments, or `null` until `getAttachments()` loads them. Use `getAttachments()`
* instead of reading this property.
*/
attachments: ScriptAttachment[] | null;
/**
* Returns the note's attachments. The first call loads them from the server, and later calls
* reuse that list.
*/
getAttachments(): Promise<ScriptAttachment[]>;
/** Returns the note's attachments with the given role, such as `image` or `file`. */
getAttachmentsByRole(role: string): Promise<ScriptAttachment[]>;
/**
* Returns the note's attachment with the given ID, or `undefined` if this note has no such
* attachment.
*/
getAttachmentById(attachmentId: string): Promise<ScriptAttachment | undefined>;
/**
* Returns the target notes of this note's `~template` and `~inherit` relations, inherited
* relations included. A target note that the client has not loaded appears as `undefined`.
*/
getNotesToInheritAttributesFrom(): ScriptFNote[];
// --- Type & state predicates -------------------------------------------
/**
* Returns the CSS classes of the note's icon, such as `tn-icon bx bx-note`. The icon comes from
* the `iconClass` label, then the `workspaceIconClass` label, then a default for the note type.
*/
getIcon(): string;
/**
* Returns `true` if the note shows as a folder in the tree: a search note, or a note with
* children (archived ones included). Always `false` when the note has a truthy `subtreeHidden`
* label.
*/
isFolder(): boolean;
/**
* Returns `true` if the note is placed, directly or through ancestors the client has loaded,
* under the shared notes root (`_share`).
*/
isShared(): boolean;
/**
* Returns `true` if the note's content can be read: the note is not protected, or a protected
* session is active.
*/
isContentAvailable(): boolean;
/** Returns `true` if the note's MIME type is `application/json`. */
isJson(): boolean;
/**
* Returns whether the note is a code, file or launcher note with a JavaScript MIME type.
*/
isJavaScript(): boolean;
/** Returns `true` if the note is a code note with the MIME type `text/jsx`. */
isJsx(): boolean;
/** Returns whether the note is a code, file or render note with the `text/html` MIME type. */
isHtml(): boolean;
/**
* Returns `true` if the note is a code note with a Markdown MIME type (`text/markdown`,
* `text/x-markdown` or `text/x-gfm`).
*/
isMarkdown(): boolean;
/** Returns `true` if the note is one of Trilium's settings pages. */
isOptions(): boolean;
/**
* Returns `true` if the note's MIME type starts with `application/javascript`, which covers
* both frontend and backend scripts. The note type is not checked.
*/
isTriliumScript(): boolean;
/**
* Returns `true` if the note is a SQL console note, which has the MIME type
* `text/x-sqlite;schema=trilium`.
*/
isTriliumSqlite(): boolean;
/**
* Returns `true` if the note is a launcher or one of the notes that hold the launch bar's
* launchers.
*/
isLaunchBarConfig(): boolean;
/**
* Returns whether every path to the note runs through the hidden subtree, so that no clone of
* it appears in the visible tree. Paths through search notes are not counted.
*/
isHiddenCompletely(): boolean;
/**
* Returns `true` if the note is the hidden subtree's root (`_hidden`) or has it as an ancestor
* through any of its loaded parents, even when the note is also cloned into the visible tree.
*/
isInHiddenSubtree(): boolean;
/**
* Returns `true` if the image note can be converted into an attachment of its parent: it is an
* image note without children, it has exactly one parent, that parent is a text note, the
* content of both is available, and no note other than the parent links to the image.
*/
isEligibleForConversionToAttachment(): boolean;
// --- Presentation ------------------------------------------------------
/**
* Returns the CSS class that applies the note's `color` label, such as `color-ff0000`, or an
* empty string if the label is missing or not a valid color. The first call for a color adds
* the class's style rule to the page.
*/
getColorClass(): string;
/**
* Returns the values of all the note's `cssClass` labels, inherited ones included, separated by
* spaces.
*/
getCssClass(): string;
/**
* Returns the value of the note's `workspaceIconClass` label, or an empty string if it has
* none.
*/
getWorkspaceIconClass(): string;
/**
* Returns the value of the note's `workspaceTabBackgroundColor` label, or an empty string if it
* has none.
*/
getWorkspaceTabBackgroundColor(): string;
// --- Scripting runtime -------------------------------------------------
/**
* Returns where the note runs as a script: `frontend` for HTML, JSX, render notes and
* JavaScript with `env=frontend` in its MIME type, `backend` for JavaScript with `env=backend`,
* and `null` for any other note.
*/
getScriptEnv(): "frontend" | "backend" | null;
/**
* Runs the note as a frontend or backend script, depending on `getScriptEnv()`. For a frontend
* script, the promise resolves to the value the script returns; for a backend script, it
* resolves to `undefined` once the script has run. A frontend script that fails shows its error
* and resolves to `undefined`.
*
* @throws Error if the note is neither JavaScript nor JSX, or its MIME type names no
* environment.
*/
executeScript(): Promise<unknown>;
// --- Low-level / Froca-managed -----------------------------------------
// Exposed for completeness; most scripts should use the higher-level
// accessors above rather than these cache fields and mutators.
/** Blob ID of the current content; changes when content changes. */
blobId: string;
/** Map of parent note ID → branch ID. */
parentToBranch: Record<string, string>;
/** Map of child note ID → branch ID. */
childToBranch: Record<string, string>;
/**
* For a search note, `true` once its results have been loaded as its children; otherwise not
* set.
*/
searchResultsLoaded?: boolean;
/**
* For a search note whose results are loaded, the search words to highlight in those results;
* otherwise not set.
*/
highlightedTokens?: string[];
/** Plain data representation of the note (the live object minus its cache handle). */
dto: Record<string, unknown>;
/**
* Adds a parent to this note in the client's cache only. Trilium calls it when it loads
* branches; scripts do not normally call it, and the change is not saved. To place a note under
* another, use `api.runOnBackend()` with the backend API.
*
* @param branchId the ID of the branch that links the two notes.
* @param sort whether to reorder the parents afterwards. Defaults to `true`.
*/
addParent(parentNoteId: string, branchId: string, sort?: boolean): void;
/**
* Adds a child to this note in the client's cache only. Trilium calls it when it loads
* branches; scripts do not normally call it, and the change is not saved.
*
* @param branchId the ID of the branch that links the two notes.
* @param sort whether to reorder the children by their position afterwards. Defaults to `true`.
*/
addChild(childNoteId: string, branchId: string, sort?: boolean): void;
/**
* Reorders the parent list in the client's cache so that ordinary parents come before search
* notes, archived notes and notes outside the visible tree. Trilium calls it itself; scripts do
* not normally call it.
*/
sortParents(): void;
/**
* Reorders the child list in the client's cache by each branch's position. Trilium calls it
* itself; scripts do not normally call it, and it does not change the order saved in the
* database.
*/
sortChildren(): void;
/**
* Overwrites the note's ID, title, type, MIME type, protection flag and blob ID in the client's
* cache with the values in `row`. Trilium calls it when changes arrive from the server; scripts
* do not normally call it, and the change is not saved.
*/
update(row: Record<string, unknown>): void;
/**
* Does nothing; the note's attributes stay up to date without it.
*
* @deprecated Remove the call.
*/
invalidateAttributeCache(): void;
/**
* Returns a short description of the note for logging, such as `Note(noteId=abc123, title=My
* note)`.
*/
toString(): string;
}
/** A branch (parent↔child link) as seen by frontend scripts (subset of `FBranch`). */
export interface ScriptFBranch {
/** The unique ID of the branch. */
branchId: string;
/** The ID of the child note that this branch places in the tree. */
noteId: string;
/** The ID of the parent note. */
parentNoteId: string;
/**
* The place of the note among its siblings; the note tree lists siblings by ascending
* `notePosition`. Trilium spaces positions 10 apart.
*/
notePosition: number;
/**
* The prefix shown before the note's title in the note tree, for this placement of the note
* only. It is empty or missing when the branch has none.
*/
prefix?: string;
/** Whether the note tree shows this branch expanded, with the note's children visible. */
isExpanded?: boolean;
/**
* Returns the child note, loading it from the server if the frontend cache does not hold it
* yet. Resolves to `null` if the note does not exist.
*/
getNote(): Promise<ScriptFNote | null>;
/**
* Returns the child note from the frontend cache, without contacting the server. Returns
* `undefined` if the note is not loaded yet.
*/
getNoteFromCache(): ScriptFNote | undefined;
/**
* Returns the parent note, loading it from the server if the frontend cache does not hold it
* yet. Resolves to `null` if the note does not exist.
*/
getParentNote(): Promise<ScriptFNote | null>;
/** Returns whether the branch places its note directly under the root note. */
isTopLevel(): boolean;
}
/** A split/tab context as seen by frontend scripts (subset of `NoteContext`). */
export interface ScriptNoteContext {
/** The ID of the note context, which identifies one tab or split. */
ntxId: string | null;
/** The note this context shows, or `null` if the context is empty. */
note: ScriptFNote | null;
/**
* The path of the note this context shows, as note IDs from `root` joined by `/`, such as
* `root/abc123/def456`. It is `null` when the context is empty.
*/
notePath: string | null;
/**
* Returns the CodeMirror editor of the code note this context shows. Resolves to `null` if the
* context shows no code editor within 200 ms.
*/
getCodeEditor(): Promise<ScriptCodeEditor | null>;
/**
* Returns the CKEditor instance of the editable text note this context shows. Resolves to
* `null` if the context shows no editable text note within 200 ms.
*/
getTextEditor(): Promise<ScriptTextEditor | null>;
}
/**
* A jQuery object: one or more page elements with jQuery's methods, as `$(…)` returns. The
* [jQuery API documentation](https://api.jquery.com/) describes them, and the script editor
* offers them as completions.
*/
// The script editor's frontend environment extends this interface with jQuery's own `JQuery`.
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface ScriptJQuery {}
/**
* The editor of a text note, a CKEditor 5 editor. The
* [CKEditor 5 API documentation](https://ckeditor.com/docs/ckeditor5/latest/api/module_core_editor_editor-Editor.html)
* describes it; `editor.model` and `editor.getData()` are the usual starting points.
*/
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface ScriptTextEditor {}
/**
* The editor of a code note, a CodeMirror 6 `EditorView`. The
* [CodeMirror reference](https://codemirror.net/docs/ref/#view.EditorView) describes it;
* `editor.state.doc.toString()` reads the code.
*/
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface ScriptCodeEditor {}
/**
* The Preact API that render notes import from `trilium:preact`: Preact's own functions and hooks,
* and Trilium's components and `defineWidget()`. In a JSX note, the script editor offers its full
* type.
*/
// The script editor's JSX environment extends this interface with the `trilium:preact` module.
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface ScriptPreact {}
/**
* The [xml2js](https://github.com/Leonidas-from-XIV/node-xml2js) library, version 0.6, which
* converts between XML and JavaScript objects, such as with `xml2js.parseStringPromise(xml)`.
*/
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface ScriptXml2js {}
/**
* The [node-html-parser](https://github.com/taoqf/node-html-parser) library, version 9, which
* parses HTML into elements that can be queried, such as with
* `htmlParser.parse(html).querySelectorAll("a")`.
*/
// eslint-disable-next-line @typescript-eslint/no-empty-object-type
export interface ScriptHtmlParser {}
/** Minimal day.js surface (the real API exposes the full day.js factory). */
export type ScriptDayjs = (date?: string | number | Date) => ScriptDayjsInstance;
/** A date as day.js wraps it (subset). */
export interface ScriptDayjsInstance {
/**
* Formats the date, such as `"YYYY-MM-DD"` for `2026-10-22`. Without a template, it returns the
* ISO 8601 form with the UTC offset, such as `2026-10-22T14:03:05+02:00`.
*/
format(template?: string): string;
/**
* Returns a new date, `value` units later. The date it is called on stays unchanged.
*
* @param unit The unit, such as `"day"`, `"week"`, `"month"` or `"year"`.
*/
add(value: number, unit: string): ScriptDayjsInstance;
/**
* Returns a new date, `value` units earlier. The date it is called on stays unchanged.
*
* @param unit The unit, such as `"day"`, `"week"`, `"month"` or `"year"`.
*/
subtract(value: number, unit: string): ScriptDayjsInstance;
/** Returns the date as a JavaScript `Date`. */
toDate(): Date;
}
type Func = ((...args: unknown[]) => unknown) | string;
/** Instance shape of `BasicWidget` (subset) — the base for custom frontend widgets. */
interface BasicWidget {
/** The widget's root element, which `doRender()` assigns, such as `this.$widget = $(TPL)`. */
$widget: ScriptJQuery;
/**
* Returns whether the widget is shown: always for a `BasicWidget`, and only while a note is
* active for a `NoteContextAwareWidget`. A disabled widget stays in the DOM, hidden, and a
* `NoteContextAwareWidget` does not call `refreshWithNote()` while it is disabled.
*/
isEnabled(): boolean | null | undefined;
/**
* Builds the widget's DOM. Override it to create the root element and assign it to
* `this.$widget` as a jQuery object.
*/
doRender(): void;
/** Renders the widget and returns its root element. */
render(): ScriptJQuery;
/** Tears down the widget; override to release resources. */
cleanup(): void;
/**
* Shows or hides the widget from inside the widget itself, such as from `refreshWithNote()`
* when the note does not apply.
*/
toggleInt(show: boolean | null | undefined): void;
/** Fluent builder: set the element id. Chainable. */
id(id: string): this;
/** Fluent builder: add a CSS class. Chainable. */
class(className: string): this;
/**
* Sets an inline CSS property on the widget's root element, such as
* `css("padding-inline-start", "12px")`, and returns the widget for chaining. It takes effect
* when the widget renders.
*/
css(name: string, value: string): this;
/** Fluent builder: append child components. Chainable. */
child(...components: unknown[]): this;
}
/** Instance shape of `NoteContextAwareWidget` (subset) — reacts to the active note. */
interface NoteContextAwareWidget extends BasicWidget {
/** The note currently shown in this widget's context. */
note: ScriptFNote | null;
/** The ID of `note`, such as for `loadResults.isNoteContentReloaded(this.noteId)`. */
readonly noteId: string | undefined;
/** The path of `note` in the tree, such as `root/abc123/def456`. */
readonly notePath: string | null | undefined;
/** The ID of the note context (split) this widget is attached to. */
readonly ntxId: string | null | undefined;
/** The note context (split) this widget is attached to. */
noteContext?: ScriptNoteContext;
/** Returns whether `noteId` is the note shown in this widget's context. */
isNote(noteId: string): boolean;
/**
* Updates the widget for the note in its context. Override it to refresh the widget's content;
* it runs when that note changes and on `refresh()`, as long as `isEnabled()` returns `true`.
*/
refreshWithNote(note: ScriptFNote | null | undefined): void | Promise<void>;
/** Forces a refresh against the current note. */
refresh(): void | Promise<void>;
}
/** Instance shape of `RightPanelWidget` (subset) — a widget shown in the right sidebar. */
interface RightPanelWidget extends NoteContextAwareWidget {
/**
* The title shown in the panel's header, `Untitled widget` unless overridden. The panel reads
* it once, when it renders.
*/
readonly widgetTitle: string;
/**
* Builds the panel's body. Override it to fill `this.$body`, the jQuery element the panel
* creates for the content, instead of `doRender()`. It can return a promise when the body
* needs asynchronous work; an error that promise rejects with is logged.
*/
doRenderBody(): void | Promise<void>;
}
/** Constructor type allowing `class X extends api.Widget { … }`. */
type WidgetClass<T> = new (...args: unknown[]) => T;
/** An attribute to create together with a note (see {@link ScriptCreateNoteOpts.attributes}). */
export interface ScriptCreateAttribute {
/** The type of the attribute: `label` or `relation`. */
type: "label" | "relation";
/** The name of the attribute, without the `#` or `~` prefix. */
name: string;
/**
* The value of the attribute. For a relation, it is the ID of the target note. Defaults to an
* empty string.
*/
value?: string;
/** Whether the note's descendants inherit the attribute. Defaults to `false`. */
isInheritable?: boolean;
/**
* The place of the attribute among the note's attributes, which are listed by ascending
* `position`. Defaults to 10 more than the highest position among the note's attributes.
*/
position?: number;
}
/** Options accepted by {@link FrontendApi.createNote}. */
export interface ScriptCreateNoteOpts {
/** Title of the new note. */
title?: string | null;
/** Content of the new note (HTML for text notes, source for code notes, etc.). */
content?: string | null;
/** Note type, e.g. "text" (default), "code", "book". */
type?: string;
/** MIME type, e.g. "application/javascript;env=frontend" for a frontend code note. */
mime?: string;
/** Note ID of a template to apply to the new note. */
templateNoteId?: string;
/** Create the note as protected (only takes effect when a protected session is available). */
isProtected?: boolean;
/** Activate (open) the new note after creation. Defaults to `true`. */
activate?: boolean;
/** Which part of the activated note to focus. Defaults to "title". */
focus?: "title" | "content";
/** Where to place the note relative to the parent/target: "into" (default) or "after". */
target?: string;
/** Branch ID used together with `target: "after"`. */
targetBranchId?: string;
/** Attributes to set atomically on creation. */
attributes?: ScriptCreateAttribute[];
}
/** Options of `api.createLink()`. */
export interface ScriptLinkOptions {
/** The text of the link. Defaults to the note's title. */
title?: string;
/**
* Whether a preview of the note shows while the mouse pointer rests on the link. Defaults to
* `true`.
*/
showTooltip?: boolean;
/** Whether the path of the note's parents shows below the link. Defaults to `false`. */
showNotePath?: boolean;
/** Whether the note's icon shows before the link. Defaults to `false`. */
showNoteIcon?: boolean;
/** Whether the link is styled as a reference link, as in text notes. Defaults to `false`. */
referenceLink?: boolean;
/**
* Whether an image, canvas or Mermaid note shows as its picture instead of a link. Defaults to
* `false`.
*/
autoConvertToImage?: boolean;
/** Text shown right after the link's title. */
titleSuffix?: string;
}
/**
* The `api` global available inside **frontend** script notes
* (`application/javascript;env=frontend`).
*/
export interface FrontendApi {
/**
* The element a render note's script renders into: the script of a note that a `~renderNote`
* relation points to. It is `null` for scripts that run any other way.
*/
$container: ScriptJQuery | null;
/**
* Note where the script execution started — the entry point of the current script bundle
* (in C terms, the file containing `main()`). When a script is spread across multiple code
* notes (descendant code notes loaded as modules via `require()`), every note in the
* bundle shares the same `startNote`, while {@link currentNote} differs per note.
* Messages from `api.log()` are grouped under this note.
*/
startNote: ScriptFNote;
/**
* Note containing the source code that is currently executing (in C terms, `__FILE__`).
* Equal to {@link startNote} unless execution has moved into a descendant module note
* loaded via `require()`. Don't confuse this with the note open in the UI — use
* `api.getActiveContextNote()` for that.
*/
currentNote: ScriptFNote;
/**
* Entity whose event triggered this execution, or `null`.
*
* Most frontend scripts are started by the user or by the UI (startup scripts, widgets),
* so this is usually `null`. It is set to a note when:
* - the script runs through a `~renderNote` relation — then it's the note being rendered
* (the one carrying the relation), not the script note;
* - a backend script calls `api.runOnFrontend()` — then it's the backend execution's
* `originEntity`, provided that entity was a note.
*/
originEntity: ScriptFNote | null;
/**
* day.js library for date manipulation.
* See {@link https://day.js.org} for documentation
* @see https://day.js.org
*/
dayjs: ScriptDayjs;
/** Base class for right-panel widgets — `class X extends api.RightPanelWidget { … }`. */
RightPanelWidget: WidgetClass<RightPanelWidget>;
/** Base class for note-context-aware widgets — `class X extends api.NoteContextAwareWidget { … }`. */
NoteContextAwareWidget: WidgetClass<NoteContextAwareWidget>;
/** Base class for basic widgets — `class X extends api.BasicWidget { … }`. */
BasicWidget: WidgetClass<BasicWidget>;
/**
* Activates note in the tree and in the note detail.
*
* @param notePath (or noteId)
*/
activateNote(notePath: string): Promise<void>;
/**
* Activates newly created note. Compared to this.activateNote() also makes sure that frontend has been fully synced.
*
* @param notePath (or noteId)
*/
activateNewNote(notePath: string): Promise<void>;
/**
* Open a note in a new tab.
*
* @method
* @param notePath (or noteId)
* @param activate - set to true to activate the new tab, false to stay on the current tab
*/
openTabWithNote(notePath: string, activate: boolean): Promise<void>;
/**
* Open a note in a new split.
*
* @param notePath (or noteId)
* @param activate - set to true to activate the new split, false to stay on the current split
*/
openSplitWithNote(notePath: string, activate: boolean): Promise<void>;
/**
* Executes given anonymous function on the backend.
* Internally this serializes the anonymous function into string and sends it to backend via AJAX.
* Please make sure that the supplied function is synchronous. Only sync functions will work correctly
* with transaction management. If you really know what you're doing, you can call api.runAsyncOnBackendWithManualTransactionHandling()
*
* @method
* @param func - (synchronous) function to be executed on the backend
* @param params - list of parameters to the anonymous function to be sent to backend
* @returns return value of the executed function on the backend
*/
runOnBackend(func: Func, params?: unknown[]): Promise<unknown>;
/**
* Executes given anonymous function on the backend.
* Internally this serializes the anonymous function into string and sends it to backend via AJAX.
* This function is meant for advanced needs where an async function is necessary.
* In this case, the automatic request-scoped transaction management is not applied,
* and you need to manually define transaction via api.transactional().
*
* If you have a synchronous function, please use api.runOnBackend().
*
* @method
* @param func - (synchronous) function to be executed on the backend
* @param params - list of parameters to the anonymous function to be sent to backend
* @returns return value of the executed function on the backend
*/
runAsyncOnBackendWithManualTransactionHandling(func: Func, params?: unknown[]): Promise<unknown>;
/**
* Whether backend script execution is enabled on the server (the
* `[Security] backendScriptingEnabled` config toggle). When it's disabled,
* `api.runOnBackend()` / `api.runAsyncOnBackendWithManualTransactionHandling()`
* reject with a "Backend script execution is disabled" error, so check this
* first to let a script degrade gracefully instead of throwing.
*/
isBackendScriptingEnabled(): boolean;
/**
* Whether the SQL console is enabled on the server (the
* `[Security] sqlConsoleEnabled` config toggle). When it's disabled, backend
* scripts that run raw SQL (`api.sql.*`) fail, so check this before invoking
* SQL-backed logic via `api.runOnBackend()`.
*/
isSqlConsoleEnabled(): boolean;
/**
* This is a powerful search method - you can search by attributes and their values, e.g.:
* "#dateModified =* MONTH AND #log". See full documentation for all options at: https://triliumnext.github.io/Docs/Wiki/search.html
*/
searchForNotes(searchString: string): Promise<ScriptFNote[]>;
/**
* This is a powerful search method - you can search by attributes and their values, e.g.:
* "#dateModified =* MONTH AND #log". See full documentation for all options at: https://triliumnext.github.io/Docs/Wiki/search.html
*/
searchForNote(searchString: string): Promise<ScriptFNote | null>;
/**
* Returns note by given noteId. If note is missing from the cache, it's loaded.
*/
getNote(noteId: string): Promise<ScriptFNote | null>;
/**
* Returns list of notes. If note is missing from the cache, it's loaded.
*
* This is often used to bulk-fill the cache with notes which would have to be picked one by one
* otherwise (by e.g. createLink())
*
* @param [silentNotFoundError] - don't report error if the note is not found
*/
getNotes(noteIds: string[], silentNotFoundError?: boolean): Promise<ScriptFNote[]>;
/**
* Update frontend tree (note) cache from the backend.
*/
reloadNotes(noteIds: string[]): Promise<void>;
/**
* Creates a new note as a child of the given parent, entirely on the frontend — no backend
* scripting required (unlike `api.runOnBackend(() => api.createTextNote(...))`). By default the
* new note is activated in the current tab with its title focused for editing; pass
* `{ activate: false }` to create it silently.
*
* @param parentNotePath note path (or noteId) of the parent under which to create the note
* @param opts creation options — e.g. `{ title, content, type, mime, activate }`
* @returns the created note and its branch, resolved from the frontend cache
*/
createNote(parentNotePath: string, opts?: ScriptCreateNoteOpts): Promise<{ note: ScriptFNote | null; branch: ScriptFBranch | undefined }>;
/**
* Instance name identifies particular Trilium instance. It can be useful for scripts
* if some action needs to happen on only one specific instance.
*/
getInstanceName(): string | null;
/**
* Adds given text to the editor cursor
*
* @param text - this must be clear text, HTML is not supported.
*/
addTextToActiveContextEditor(text: string): void;
/**
* @returns active note (loaded into center pane)
*/
getActiveContextNote(): ScriptFNote;
/**
* Obtains the currently active/focused split in the current tab.
*
* Note that this method does not return the note context of the "Quick edit" panel, it will return the note context behind it.
*/
getActiveContext(): ScriptNoteContext;
/**
* Obtains the main context of the current tab. This is the left-most split.
*
* Note that this method does not return the note context of the "Quick edit" panel, it will return the note context behind it.
*/
getActiveMainContext(): ScriptNoteContext;
/**
* @returns returns all note contexts (splits) in all tabs
*/
getNoteContexts(): ScriptNoteContext[];
/**
* @returns returns all main contexts representing tabs
*/
getMainNoteContexts(): ScriptNoteContext[];
/**
* Returns the editor of the text note in the active tab or split. Resolves to `null` if it
* shows no editable text note within 200 ms, and throws an error when no tab is active.
*/
getActiveContextTextEditor(): Promise<ScriptTextEditor | null>;
/**
* Returns the editor of the code note in the active tab or split. Resolves to `null` if it
* shows no code editor within 200 ms, and throws an error when no tab is active.
*/
getActiveContextCodeEditor(): Promise<ScriptCodeEditor | null>;
/**
* Get access to the widget handling note detail. Methods like `getWidgetType()` and `getTypeWidget()` to get to the
* implementation of actual widget type.
*/
getActiveNoteDetailWidget(): Promise<unknown>;
/**
* @returns returns a note path of active note or null if there isn't active note
*/
getActiveContextNotePath(): string | null;
/**
* Returns component which owns the given DOM element (the nearest parent component in DOM tree)
*
* @method
* @param el DOM element
*/
getComponentByEl(el: HTMLElement): unknown;
/**
* Show an info toast message to the user.
*/
showMessage(message: string, delay?: number): void;
/**
* Show an error toast message to the user.
*/
showError(message: string, delay?: number): void;
/**
* Show an info dialog to the user.
*/
showInfoDialog(message: string): Promise<void>;
/**
* Show confirm dialog to the user.
* @returns promise resolving to true if the user confirmed
*/
showConfirmDialog(message: string): Promise<boolean>;
/**
* Show prompt dialog to the user.
*
* @returns promise resolving to the answer provided by the user
*/
showPromptDialog(props: { title?: string; message?: string; defaultValue?: string }): Promise<string | null>;
/**
* Show a dialog for picking one item out of many, grouped and searchable.
*
* `items` are either the items themselves or groups of them, never the two mixed. Named for the
* one thing it does now: picking several at once will be a method of its own beside this.
*
* @returns promise resolving to the item picked, or null where the user backed out.
*/
pickSingleItem(props: {
title?: string;
items: PickerItem[] | PickerItemGroup[];
placeholder?: string;
}): Promise<PickerItem | null>;
/**
* Create a note link (jQuery object) for given note.
*
* @param {string} notePath (or noteId)
* @param {object} [params]
* @param {boolean} [params.showTooltip] - enable/disable tooltip on the link
* @param {boolean} [params.showNotePath] - show also whole note's path as part of the link
* @param {boolean} [params.showNoteIcon] - show also note icon before the title
* @param {string} [params.title] - custom link tile with note's title as default
* @param {string} [params.title=] - custom link tile with note's title as default
* @returns {jQuery} - jQuery element with the link (wrapped in <span>)
*/
createLink(notePath: string, params?: ScriptLinkOptions): Promise<ScriptJQuery>;
/** @deprecated - use api.createLink() instead */
createNoteLink(notePath: string, params?: ScriptLinkOptions): Promise<ScriptJQuery>;
/**
* Trigger command. This is a very low-level API which should be avoided if possible.
*/
triggerCommand(name: string, data?: Record<string, unknown>): Promise<unknown>;
/**
* Trigger event. This is a very low-level API which should be avoided if possible.
*/
triggerEvent(name: string, data?: Record<string, unknown>): Promise<unknown>;
/**
* Shows a preview of the linked note while the mouse pointer rests on the element, as Trilium
* does for links in note content. The element must be a link whose `href` or `data-href`
* points to a note, such as `#root/abc123`.
*
* @param el The link, as a jQuery object.
*/
setupElementTooltip(el: ScriptJQuery): void;
/**
* @param {boolean} protect - true to protect note, false to unprotect
*/
protectNote(noteId: string, protect: boolean): Promise<void>;
/**
* @param noteId
* @param protect - true to protect subtree, false to unprotect
*/
protectSubTree(noteId: string, protect: boolean): Promise<void>;
/**
* Returns date-note for today. If it doesn't exist, it is automatically created.
*/
getTodayNote(): Promise<ScriptFNote>;
/**
* Returns day note for a given date. If it doesn't exist, it is automatically created.
*
* @param date - e.g. "2019-04-29"
*/
getDayNote(date: string): Promise<ScriptFNote>;
/**
* Returns day note for the first date of the week of the given date. If it doesn't exist, it is automatically created.
*
* @param date - e.g. "2019-04-29"
*/
getWeekFirstDayNote(date: string): Promise<ScriptFNote>;
/**
* Returns week note for given date. If such a note doesn't exist, it is automatically created.
*
* @param date in YYYY-MM-DD format
* @param rootNote - specify calendar root note, normally leave empty to use the default calendar
*/
getWeekNote(date: string): Promise<ScriptFNote>;
/**
* Returns month-note. If it doesn't exist, it is automatically created.
*
* @param month - e.g. "2019-04"
*/
getMonthNote(month: string): Promise<ScriptFNote>;
/**
* Returns quarter note for given date. If such a note doesn't exist, it is automatically created.
*
* @param date in YYYY-MM format
* @param rootNote - specify calendar root note, normally leave empty to use the default calendar
*/
getQuarterNote(date: string): Promise<ScriptFNote>;
/**
* Returns year-note. If it doesn't exist, it is automatically created.
*
* @method
* @param {string} year - e.g. "2019"
* @returns {Promise<FNote>}
*/
getYearNote(year: string): Promise<ScriptFNote>;
/**
* Hoist note in the current tab. See https://triliumnext.github.io/Docs/Wiki/note-hoisting.html
*
* @param {string} noteId - set hoisted note. 'root' will effectively unhoist
*/
setHoistedNoteId(noteId: string): void;
/**
* @param keyboardShortcut - e.g. "ctrl+shift+a"
* @param [namespace] specify namespace of the handler for the cases where call for bind may be repeated.
* If a handler with this ID exists, it's replaced by the new handler.
*/
bindGlobalShortcut(keyboardShortcut: string, handler: () => void, namespace?: string): void;
/**
* Trilium runs in a backend and frontend process, when something is changed on the backend from a script,
* frontend will get asynchronously synchronized.
*
* This method returns a promise which resolves once all the backend -> frontend synchronization is finished.
* Typical use case is when a new note has been created, we should wait until it is synced into frontend and only then activate it.
*/
waitUntilSynced(): Promise<unknown>;
/**
* This will refresh all currently opened notes which have included note specified in the parameter
*
* @param includedNoteId - noteId of the included note
*/
refreshIncludedNote(includedNoteId: string): void;
/**
* Return randomly generated string of given length. This random string generation is NOT cryptographically secure.
*
* @method
* @param length of the string
* @returns random string
*/
randomString(length: number): string;
/**
* @param size in bytes
* @return formatted string
*/
formatSize(size: number): string;
/**
* @param size in bytes
* @return formatted string
* @deprecated - use api.formatSize()
*/
formatNoteSize(size: number): string;
/**
* Converts the given HTML string to Markdown.
*
* Unlike the backend API, this runs on the server (the HTML→Markdown
* converter is backend-only), so it returns a promise.
*
* @param html - HTML content to convert
* @returns Markdown representation of the input HTML
*/
htmlToMarkdown(html: string): Promise<string>;
/**
* Converts the given Markdown string to HTML.
*
* Runs entirely in the browser; the promise is only needed because the
* Markdown renderer is loaded on demand.
*
* @param markdown - Markdown content to convert
* @returns HTML representation of the input Markdown
*/
markdownToHtml(markdown: string): Promise<string>;
/**
* @returns date in YYYY-MM-DD format
*/
formatDateISO(date: Date): string;
/** Parses a date string into a Date. */
parseDate(str: string): Date;
/** Per-note log message buffers shown in the UI log pane. */
logMessages: Record<string, string[]>;
/** Per-note spaced-update handlers for the log pane. */
logSpacedUpdates: Record<string, unknown>;
/**
* Log given message to the log pane in UI.
* Accepts multiple arguments which are joined with spaces, similar to `console.log`.
*/
log(...args: unknown[]): void;
/** The Preact API surface (components, hooks) for render scripts. */
preact: ScriptPreact;
}
/** A branch (note→parent placement) as seen by backend scripts (subset of `BBranch`). */
export interface ScriptBBranch {
/**
* The ID of the branch. Moving a note to another parent replaces its branch with a new one, so
* store the note ID rather than the branch ID when you need a stable reference.
*/
branchId: string;
/** The ID of the child note this branch places in the tree. */
noteId: string;
/** The ID of the parent note. For the root note's branch, it is `"none"`. */
parentNoteId: string;
/**
* The text shown before the note's title in the note tree for this placement only, or `null` if
* there is none.
*/
prefix: string | null;
/**
* The position of the note among its siblings under this parent; notes with lower values come
* first.
*/
notePosition: number;
/** Whether the note is expanded in the note tree at this placement, showing its children. */
isExpanded: boolean;
/** Returns the child note this branch places in the tree. */
getNote(): ScriptBNote;
/** Returns the parent note. The root note's branch has no parent note. */
getParentNote(): ScriptBNote | null;
}
/** A note revision as seen by backend scripts (subset of trilium-core's `BRevision`). */
export interface ScriptBRevision {
/** The ID of the revision. */
revisionId?: string;
/** The ID of the note this revision belongs to. */
noteId: string;
/** The note's type at the time of the revision, such as `"text"` or `"code"`. */
type: string;
/** The note's MIME type at the time of the revision. */
mime: string;
/**
* The note's title at the time of the revision. For a protected revision outside a protected
* session, it is `"[protected]"`.
*/
title: string;
/**
* When the note was last edited before the revision was saved, in local time with its UTC
* offset, formatted as `YYYY-MM-DD HH:mm:ss.SSS+ZZZZ` (for example, `2026-10-22
* 14:05:09.123+0200`).
*/
dateLastEdited?: string;
/**
* When the note was last edited before the revision was saved, in UTC, formatted as `YYYY-MM-DD
* HH:mm:ss.SSSZ` (for example, `2026-10-22 12:05:09.123Z`).
*/
utcDateLastEdited?: string;
/**
* The size of the revision's content in bytes, when it was loaded together with the revision.
* Revisions returned by `note.getRevisions()` and `note.saveRevision()` leave it `undefined`.
*/
contentLength?: number;
/**
* Returns the content of the revision: a string for text-based note types, a `Uint8Array` for
* binary ones such as images and files. For a protected revision outside a protected session,
* it returns an empty string.
*/
getContent(): string | Uint8Array;
/**
* Returns the revision's content parsed as JSON. Returns `null` when the content is empty,
* blank or binary, and throws an error when it is not valid JSON.
*/
getJsonContent(): unknown;
}
/** An attachment as seen by backend scripts (subset of trilium-core's `BAttachment`). */
export interface ScriptBAttachment {
/** The ID of the attachment. It is `undefined` until a new attachment is first saved. */
attachmentId?: string;
/**
* The ID of the note the attachment belongs to. For an attachment of a revision, it is the ID
* of the revision.
*/
ownerId: string;
/**
* The purpose of the attachment: `image` for an image shown in a text note, `file` for an
* attached file. Trilium also uses roles of its own, such as `viewConfig` for a collection's
* view settings.
*/
role: string;
/** The MIME type of the attachment's content, such as `image/png`. */
mime: string;
/**
* The title of the attachment, usually its file name. For a protected attachment outside a
* protected session, it holds the encrypted title; use `getTitleOrProtected()` to show it.
*/
title: string;
/** The place of the attachment among its owner's attachments, listed by ascending position. */
position?: number;
/** Whether the attachment is protected (encrypted). */
isProtected?: boolean;
/** The ID of the blob that stores the content. It changes whenever the content changes. */
blobId?: string;
/** The date and time, in UTC, that the attachment was last saved. */
utcDateModified?: string;
/**
* The length of the attachment's content, when it was loaded together with the attachment.
* Attachments returned by `note.getAttachmentsByRole()` leave it `undefined`.
*/
contentLength?: number;
/** Returns the note the attachment belongs to, or `undefined` for a revision's attachment. */
getNote(): ScriptBNote | undefined;
/**
* Returns the content: a string for text-based content, a `Uint8Array` for binary content
* such as images. For a protected attachment outside a protected session, it returns an empty
* string.
*/
getContent(): string | Uint8Array;
/**
* Replaces the content and saves it immediately. Throws an error for a protected attachment
* outside a protected session.
*/
setContent(
content: string | Uint8Array,
opts?: { forceSave?: boolean; forceFrontendReload?: boolean }
): void;
/** Returns whether the content is text rather than binary, judged by the MIME type. */
hasStringContent(): boolean;
/**
* Returns whether the title and content can be read: the attachment is not protected, or a
* protected session is active.
*/
isContentAvailable(): boolean;
/** Returns the title, or `[protected]` when the title cannot be read. */
getTitleOrProtected(): string;
/** Returns the file name the attachment downloads under: its title with a fitting extension. */
getFileName(): string;
/**
* Turns the attachment into a child note of its owner and deletes the attachment. In a text
* note, images and links that point to the attachment are rewritten to point to the new note.
* Throws an error for a revision's attachment, and for a protected one outside a protected
* session.
*/
convertToNote(): ScriptNoteAndBranch;
/** Saves changes made to the attachment's properties, such as `title`. */
save(): this;
/**
* Deletes the attachment. Deleted attachments stay recoverable until they are erased.
*
* @param deleteId An ID that groups items deleted together, so that they can be restored
* together.
*/
markAsDeleted(deleteId?: string | null): void;
}
/** An option, one of Trilium's settings (subset of trilium-core's `BOption`). */
export interface ScriptBOption {
/** The name of the option, such as `theme` or `locale`. */
name: string;
/** The value of the option. Every value is a string, numbers and booleans included. */
value: string;
/** Whether the option syncs to other devices; device-specific options do not. */
isSynced?: boolean;
/** The date and time, in UTC, that the option last changed. */
utcDateModified?: string;
}
/**
* An ETAPI token, which grants an external program access to the ETAPI (subset of trilium-core's
* `BEtapiToken`). The token itself is not available, only its hash, which this type leaves out.
*/
export interface ScriptBEtapiToken {
/** The ID of the token. */
etapiTokenId?: string;
/** The name given to the token when it was created. */
name: string;
/** The date and time, in UTC, that the token was created. */
utcDateCreated: string;
/** The date and time, in UTC, that the token was last changed, such as renamed. */
utcDateModified?: string;
/** Whether the token has been deleted, which revokes it. */
isDeleted: boolean;
}
/** Options of `api.searchForNotes()` and `api.searchForNote()`. */
export interface ScriptSearchParams {
/**
* Whether to search only titles and attributes, leaving out note content, which is faster.
* Defaults to `false`.
*/
fastSearch?: boolean;
/** Whether to include archived notes. Defaults to `true`. */
includeArchivedNotes?: boolean;
/**
* Whether to include the hidden subtree's notes, such as settings and launchers. Defaults to
* `false`.
*/
includeHiddenNotes?: boolean;
/**
* Whether to search the whole tree even while a note is hoisted. Defaults to `true`; with
* `false` and no `ancestorNoteId`, only the hoisted note's subtree is searched.
*/
ignoreHoistedNote?: boolean;
/** The ID of a note to search under: only its descendants are found. */
ancestorNoteId?: string;
/**
* How deep under `ancestorNoteId` the found notes can lie: `eq`, `gt` or `lt` followed by a
* depth, such as `eq1` for its children only or `lt4` for less than four levels down.
*/
ancestorDepth?: string;
/**
* What to order the results by: a note property such as `title`, `dateCreated` or
* `dateModified`, or `relevancy`, the default.
*/
orderBy?: string;
/** `asc` or `desc`; the direction of `orderBy`. */
orderDirection?: string;
/** The largest number of results to return. */
limit?: number | null;
/** Whether to write how the query was parsed to the backend log. */
debug?: boolean;
/**
* Whether attribute conditions match loosely: `#status=done` also matches values that contain
* `done`, and `#stat` matches attributes whose name starts with `stat`. Defaults to `false`.
*/
fuzzyAttributeSearch?: boolean;
}
/** Information about the running Trilium, as `api.getAppInfo()` returns it. */
export interface ScriptAppInfo {
/** The version of Trilium, such as `0.106.0`. */
appVersion: string;
/** The version of the database schema. */
dbVersion: number;
/** The version of Node.js; absent in the standalone and mobile apps, which have no Node.js. */
nodeVersion?: string;
/** The version of the sync protocol, which both sides of a sync must share. */
syncVersion: number;
/** When this build of Trilium was made. */
buildDate: string;
/** The Git commit this build of Trilium was made from. */
buildRevision: string;
/**
* The directory that holds the database and the other data; absent in the standalone and
* mobile apps.
*/
dataDirectory?: string;
/** The version of the protocol the web clipper speaks with Trilium. */
clipperProtocolVersion: string;
/** The date and time, in UTC, that Trilium started, in ISO 8601 form. */
utcDateTime: string;
}
/**
* Direct access to Trilium's SQLite database (subset of trilium-core's `SqlService`). Queries mark
* parameters with `?` and take their values in an array, in order. Changes made here bypass
* Trilium's own bookkeeping: they do not sync, and Trilium's in-memory copy of the notes does not
* see them until the next restart. Change notes through the note methods instead.
*/
export interface ScriptSql {
/**
* Returns the first row of the result, as an object of column names to values, or `undefined`
* when the query returns no rows.
*/
getRow<T>(query: string, params?: unknown[]): T;
/** Returns the first row of the result, or `null` when the query returns no rows. */
getRowOrNull<T>(query: string, params?: unknown[]): T | null;
/**
* Returns the first column of the first row, such as the count of `SELECT COUNT(*) FROM notes`,
* or `undefined` when the query returns no rows.
*/
getValue<T>(query: string, params?: unknown[]): T;
/** Returns every row of the result, each as an object of column names to values. */
getRows<T>(query: string, params?: unknown[]): T[];
/** Returns the first column of every row of the result. */
getColumn<T>(query: string, params?: unknown[]): T[];
/** Returns an object that maps the first column of each row to its second column. */
getMap<K extends string | number | symbol, V>(query: string, params?: unknown[]): Record<K, V>;
/** Returns the rows of the result one at a time, which keeps a large result out of memory. */
iterateRows<T>(query: string, params?: unknown[]): IterableIterator<T>;
/**
* Runs a statement that changes data, such as `UPDATE` or `INSERT`.
*
* @returns `changes`, the number of rows changed, and `lastInsertRowid`, the ID of the row an
* `INSERT` added.
*/
execute(query: string, params?: unknown[]): { changes: number; lastInsertRowid: number };
/** Runs several statements separated by semicolons, without parameters. */
executeScript(query: string): void;
/**
* Calls `func` in a transaction: when it throws, every change it made is undone. Inside a
* transaction already running, it runs as a nested savepoint.
*
* @returns What `func` returns.
*/
transactional<T>(func: () => T): T;
}
/** Result of a clone operation ({@link ScriptBNote.cloneTo}); mirrors `CloneResponse`. */
export interface ScriptCloneResponse {
/** Whether the note was cloned. */
success: boolean;
/**
* Why the clone failed, such as the note already being in that parent. Present only when
* `success` is `false`.
*/
message?: string;
/**
* The ID of the new branch that places the note under the new parent. Present only when
* `success` is `true`.
*/
branchId?: string;
/**
* The path of the clone, as note IDs from `root` joined by `/`, ending in the note's ID.
* Present only when `success` is `true`.
*/
notePath?: string;
}
/** A single parent→child link in a subtree ({@link ScriptBNote.getSubtree}). */
export interface ScriptSubtreeRelationship {
/**
* The ID of the parent note. With `resolveSearch`, it can be a search note and the child one of
* its results.
*/
parentNoteId: string;
/**
* The ID of the child note. With `includeArchived: false`, it can name an archived note that
* the list of notes leaves out.
*/
childNoteId: string;
}
/** Options accepted by the subtree traversal helpers on {@link ScriptBNote}. */
export interface ScriptSubtreeOpts {
/** Whether to include archived notes and their descendants. Defaults to `true`. */
includeArchived?: boolean;
/**
* Whether to descend into the hidden subtree, `_hidden`, which holds Trilium's system notes.
* Defaults to `false`.
*/
includeHidden?: boolean;
/**
* Whether to run each search note and include its results as its children. Defaults to `false`,
* which includes the search note but none of its results.
*/
resolveSearch?: boolean;
}
/** Input accepted by {@link ScriptBNote.saveAttachment}. */
export interface ScriptSaveAttachmentInput {
/**
* The ID of the attachment to update. Omit it to create a new attachment, which gets an ID of
* its own.
*/
attachmentId?: string;
/**
* The purpose of the attachment, such as `image` or `file`. Used only when a new attachment is
* created.
*/
role: string;
/**
* The MIME type of the content, such as `image/png`. Used only when a new attachment is
* created.
*/
mime: string;
/**
* The title of the attachment, usually its file name. Used when a new attachment is created,
* and to find the attachment to update when `matchBy` is `"title"`.
*/
title: string;
/**
* The content of the attachment: a string, or bytes for binary content. Defaults to an empty
* string.
*/
content?: string | Uint8Array;
/**
* The place of the attachment among the note's attachments, which `getAttachments()` lists by
* ascending `position`. Used only when a new attachment is created.
*/
position?: number;
}
/** A note as seen by backend scripts (subset of trilium-core's `BNote`). */
export interface ScriptBNote {
/**
* The ID of the note. The root note's ID is `root`. System notes have IDs that start with `_`,
* such as `_hidden`.
*/
noteId: string;
/**
* The title of the note. For a protected note read outside a protected session, this holds the
* encrypted title. Use `getTitleOrProtected()` to show a title safely.
*/
title: string;
/**
* The note type, such as `text`, `code`, `file`, `image`, `search` or `book`. Together with
* `mime`, it decides how Trilium renders the content.
*/
type: string;
/**
* The MIME type of the note's content, such as `text/html` for a text note or
* `application/javascript;env=backend` for a backend script.
*/
mime: string;
/**
* Whether the note is protected. The title and content of a protected note are encrypted, and
* can be read or changed only while a protected session is active.
*/
isProtected: boolean;
/**
* Whether the note is archived: it has an `archived` label of its own or inherits one. A
* non-inheritable `archived` label on an ancestor does not count; see
* `areAllNotePathsArchived()`.
*/
isArchived: boolean;
/**
* Whether the note has been deleted, or its deletion is in progress. It becomes `true` on an
* object a script still holds after the note is deleted.
*/
isDeleted: boolean;
/** Share root ID this note is published under, if any. */
shareId: string;
/**
* The ID of the blob that stores the note's content. It changes whenever the content changes,
* and notes with identical content share a blob.
*/
blobId: string;
/**
* The date and time the note was created, in local time with its UTC offset, for example
* `2026-10-22 14:03:05.123+0200`.
*/
dateCreated: string;
/**
* The date and time the note was last modified, in local time with its UTC offset, for example
* `2026-10-22 14:03:05.123+0200`. It changes when the content changes or the note itself is
* saved, such as after a title change.
*/
dateModified: string;
/** The date and time the note was created, in UTC, for example `2026-10-22 12:03:05.123Z`. */
utcDateCreated: string;
/**
* The date and time the note was last modified, in UTC, for example `2026-10-22 12:03:05.123Z`.
* It changes when the content changes or the note itself is saved.
*/
utcDateModified: string;
// --- Content -----------------------------------------------------------
/**
* Returns the content of the note: a string for text-based notes (see `hasStringContent()`), a
* `Uint8Array` for binary ones such as images and files. The content is read from the database
* on each call. For a protected note outside a protected session, it returns an empty string.
*/
getContent(): string | Uint8Array;
/**
* Replaces the content of the note and saves it immediately; there is no need to call `save()`
* afterwards. If the content is unchanged, nothing is saved and `dateModified` stays the same.
*
* The call throws an error when `content` is `null` or `undefined`, when the note is protected
* and no protected session is active, and when the note is read-only, such as a page of the
* in-app help.
*
* @param content The new content: a string for text-based notes, or a `Uint8Array` for binary
* ones such as images and files.
* @param opts.forceFrontendReload Whether open editors showing this note reload the new
* content, even when the change appears to come from them.
*/
setContent(content: string | Uint8Array, opts?: { forceFrontendReload?: boolean }): void;
/**
* Returns the note's content parsed as JSON. Returns `null` when the content is empty, blank or
* binary, and throws an error when it is not valid JSON.
*/
getJsonContent<T = unknown>(): T | null;
/**
* Returns the note's content parsed as JSON, like `getJsonContent()`, but returns `null`
* instead of throwing an error when the content is not valid JSON.
*/
getJsonContentSafely(): unknown;
/**
* Serializes `content` to JSON, indented with tabs, and saves it as the note's content through
* `setContent()`, with the same errors.
*/
setJsonContent(content: unknown): void;
/**
* Returns whether `getContent()` returns a string rather than a `Uint8Array`. This holds for
* text, code, canvas, Mermaid and other text-based note types, and for MIME types such as
* `text/*`, `application/json`, `application/javascript` and `image/svg+xml`.
*/
hasStringContent(): boolean;
/**
* Returns a file name for the note, as used when it is downloaded or exported: the title with
* characters invalid in file names removed (`untitled` when the title is empty), plus an
* extension. The extension is `.html` for text notes, `.json` for relation maps, canvases and
* saved searches, and otherwise comes from the MIME type, unless the title already ends in a
* matching one.
*/
getFileName(): string;
/**
* Returns a single line of text that Trilium searches when matching notes: the note ID, type,
* MIME type, branch prefixes, title and attributes (as `#name=value` and `~name=value`,
* inherited ones included), lowercased and with diacritics removed. The content is not
* included.
*/
getFlatText(): string;
/** Plain serialisable representation of the note (the real return type is `NotePojo`). */
getPojo(): Record<string, unknown>;
/**
* Returns the note's title, or the literal string `[protected]` when the note is protected and
* no protected session is active.
*/
getTitleOrProtected(): string;
/**
* Returns the CSS classes of the note's icon, for example `tn-icon bx bx-note`. The icon comes
* from the note's `iconClass` label (its own or inherited) when it has one, and otherwise from
* its type.
*/
getIcon(): string;
// --- Hierarchy ---------------------------------------------------------
/**
* The parent notes of this note: one per place the note appears in the tree, so a cloned note
* has several. Parents that are not archived come first. This is the same array
* `getParentNotes()` returns; don't modify it.
*/
parents: ScriptBNote[];
/**
* The child notes of this note, in their order in the tree. This is the same array
* `getChildNotes()` returns; don't modify it.
*/
children: ScriptBNote[];
/**
* The branches that place this note under each of its parents, in the same order as `parents`.
* This is the same array `getParentBranches()` returns; don't modify it.
*/
parentBranches: ScriptBBranch[];
/** The number of parent notes, which is greater than 1 for a cloned note. */
parentCount: number;
/** The number of child notes, including hidden and system notes. */
childrenCount: number;
/**
* Returns the parent notes of this note, one per place the note appears in the tree. Parents
* that are not archived come first. The result is the `parents` array itself; don't modify it.
*/
getParentNotes(): ScriptBNote[];
/**
* Returns the child notes of this note, in their order in the tree. The result is the
* `children` array itself; don't modify it.
*/
getChildNotes(): ScriptBNote[];
/**
* Returns the child notes that are shown in a shared note's navigation tree, in tree order. It
* leaves out system notes, whose IDs start with `_`, and notes with a `shareHiddenFromTree`
* label, their own or inherited. Archived notes are included.
*/
getVisibleChildNotes(): ScriptBNote[];
/**
* Returns the branches that place this note under each of its parents. The result is the
* `parentBranches` array itself; don't modify it.
*/
getParentBranches(): ScriptBBranch[];
/**
* Returns the branches that connect this note to each of its children, in their order in the
* tree. A branch holds the child's position and prefix.
*/
getChildBranches(): ScriptBBranch[];
/**
* Returns the child branches whose notes are shown in a shared note's navigation tree, in tree
* order. It leaves out system notes, whose IDs start with `_`, and notes with a
* `shareHiddenFromTree` label, their own or inherited. Archived notes are included.
*/
getVisibleChildBranches(): ScriptBBranch[];
/**
* Returns the parent branches the user created, leaving out the automatic placements under the
* shared notes (`_share`) and the bookmarks (`_lbBookmarks`). A note whose last such branch is
* deleted is deleted too.
*/
getStrongParentBranches(): ScriptBBranch[];
/**
* Returns the same branches as `getChildBranches()`. Despite its name, it filters nothing:
* archived and hidden children are included.
*/
getFilteredChildBranches(): ScriptBBranch[];
/**
* Returns the branches that place this note under each of its parents.
*
* @deprecated Use `getParentBranches()` instead.
*/
getBranches(): ScriptBBranch[];
/** Returns whether the note has at least one child note, including hidden and system notes. */
hasChildren(): boolean;
/** Returns whether `getVisibleChildNotes()` returns at least one note. */
hasVisibleChildren(): boolean;
/**
* Returns every ancestor of the note across all of its paths in the tree, each note once, up to
* and including the root note. The note itself is not included. The order follows the parents:
* each parent comes first, followed by its own ancestors.
*/
getAncestors(): ScriptBNote[];
/** Returns the IDs of the notes `getAncestors()` returns, in the same order. */
getAncestorNoteIds(): string[];
/**
* Returns the IDs of this note and all its descendants.
*
* @deprecated Use `getSubtreeNoteIds()` instead.
*/
getDescendantNoteIds(): string[];
/**
* Returns the number of levels between this note and the given ancestor along the shortest
* path: `1` for a parent, `2` for a grandparent, and `0` for the note itself. If the note is
* not a descendant of the given note, it returns `999999`.
*
* @param ancestorNoteId The ID of the ancestor note to measure the distance to.
*/
getDistanceToAncestor(ancestorNoteId: string): number;
/**
* Returns whether the given note is an ancestor of this note on any of its paths. It returns
* `false` for the note's own ID.
*
* @param ancestorNoteId The ID of the note to look for among the ancestors.
*/
hasAncestor(ancestorNoteId: string): boolean;
/**
* Returns whether the given note lies on at least one of this note's paths from the root.
* Unlike `hasAncestor()`, it returns `true` for the note's own ID.
*/
isDescendantOfNote(ancestorNoteId: string): boolean;
/** Returns whether this note is the root of the note tree, whose ID is `root`. */
isRoot(): boolean;
/**
* Returns the note and all its descendants, each note once, together with every parent-child
* relationship among them, including those of cloned notes.
*
* @param opts.includeArchived Whether archived notes, and the subtrees below them, are
* included. Defaults to `true`.
* @param opts.includeHidden Whether the hidden subtree (`_hidden`) is included when it lies
* within the subtree. Defaults to `false`.
* @param opts.resolveSearch Whether the results of saved search notes are included as their
* children. Defaults to `false`.
* @returns An object with `notes`, the notes of the subtree including this note, and
* `relationships`, the `{ parentNoteId, childNoteId }` pairs connecting them.
*/
getSubtree(opts?: ScriptSubtreeOpts): {
notes: ScriptBNote[];
relationships: ScriptSubtreeRelationship[];
};
/**
* Returns the IDs of this note and all its descendants, each once. Takes the same options as
* `getSubtree()`.
*/
getSubtreeNoteIds(opts?: ScriptSubtreeOpts): string[];
/**
* Returns the notes that this note's inheritable attributes reach: the note itself, its
* descendants, and every note that uses one of them as a `template` or `inherit` relation
* target, along with that note's descendants. Each note appears once; the hidden subtree
* (`_hidden`) is skipped.
*/
getSubtreeNotesIncludingTemplated(): ScriptBNote[];
/**
* Returns the notes that this note's non-inheritable attributes apply to: the note itself and
* every note that uses it as a `template` or `inherit` relation target. Their descendants are
* not included.
*/
getInheritingNotes(): ScriptBNote[];
// --- Note paths --------------------------------------------------------
/**
* Returns every path from the root note to this note, one per placement in the tree. Each path
* is an array of note IDs that starts with `root` and ends with this note's ID.
*/
getAllNotePaths(): string[][];
/**
* Returns the best path from the root note to this note as an array of note IDs, ranked as in
* `getSortedNotePathRecords()`.
*
* @param hoistedNoteId The ID of the note whose subtree is preferred. Defaults to `root`.
*/
getBestNotePath(hoistedNoteId?: string): string[];
/**
* Returns the best path from the root note to this note as a string of note IDs joined by `/`,
* for example `root/a1h315/js725h`.
*
* @param hoistedNoteId The ID of the note whose subtree is preferred. Defaults to `root`.
*/
getBestNotePathString(hoistedNoteId?: string): string;
/**
* Returns a record for every path from the root note to this note, best path first. Paths
* within the hoisted note's subtree come first, then paths without archived notes, then paths
* outside the hidden subtree, then shorter paths.
*
* @param hoistedNoteId The ID of the note whose subtree is preferred. Defaults to `root`.
* @returns Records whose `notePath` holds the note IDs from the root to this note, with flags
* telling whether the path lies within the hoisted subtree (`isInHoistedSubTree`), passes
* through an archived note, the note itself included (`isArchived`), or lies within the hidden
* subtree (`isHidden`).
*/
getSortedNotePathRecords(hoistedNoteId?: string): ScriptNotePathRecord[];
/**
* Returns whether every path to this note passes through an archived note. Unlike `isArchived`,
* this also counts a non-inheritable `archived` label on an ancestor. It throws an error if the
* note has no path from the root.
*/
areAllNotePathsArchived(): boolean;
// --- Attributes (read) -------------------------------------------------
/** The labels and relations defined directly on this note, without inherited ones. */
ownedAttributes: ScriptAttribute[];
/**
* The relations in other notes (or this one) that point to this note. This includes the link
* relations Trilium creates automatically for links in note content, such as `internalLink` and
* `imageLink`.
*/
targetRelations: ScriptAttribute[];
/**
* The number of labels and relations on this note, inherited ones and automatic link relations
* included.
*/
attributeCount: number;
/**
* The number of labels and relations defined directly on this note, automatic link relations
* included.
*/
ownedAttributeCount: number;
/** The number of labels on this note, inherited ones included. */
labelCount: number;
/** The number of labels defined directly on this note. */
ownedLabelCount: number;
/**
* The number of relations on this note, inherited ones included. Excludes the link relations
* Trilium creates automatically for links in note content (`internalLink`, `imageLink`,
* `relationMapLink`, `includeNoteLink`).
*/
relationCount: number;
/**
* The number of relations on this note, inherited ones included, together with the link
* relations Trilium creates automatically for links in note content.
*/
relationCountIncludingLinks: number;
/**
* The number of relations defined directly on this note, excluding the link relations Trilium
* creates automatically for links in note content.
*/
ownedRelationCount: number;
/**
* The number of relations defined directly on this note, together with the link relations
* Trilium creates automatically for links in note content.
*/
ownedRelationCountIncludingLinks: number;
/**
* The number of relations in other notes that point to this note, excluding the link relations
* Trilium creates automatically for links in note content.
*/
targetRelationCount: number;
/**
* The number of relations in other notes that point to this note, together with the link
* relations Trilium creates automatically for links in note content.
*/
targetRelationCountIncludingLinks: number;
/**
* Returns the labels and relations of this note, inherited ones included, optionally filtered
* by type and name. Without a filter, the result is the note's own cached array; don't modify
* it.
*
* @param type `"label"` or `"relation"`; any other value throws an error.
* @param name The attribute name, without the leading `#` or `~`.
*/
getAttributes(type?: string, name?: string): ScriptAttribute[];
/**
* Returns the labels and relations defined directly on this note, optionally filtered by type
* and name. Without a filter, the result is the `ownedAttributes` array itself; don't modify
* it.
*
* @param type `"label"` or `"relation"`; any other value throws an error.
* @param name The attribute name, without the leading `#` or `~`.
*/
getOwnedAttributes(type?: string, name?: string): ScriptAttribute[];
/**
* Returns the first attribute of the given type and name, inherited ones included, or `null` if
* there is none.
*
* @param type `"label"` or `"relation"`.
*/
getAttribute(type: string, name: string): ScriptAttribute | null;
/**
* Returns the first attribute of the given type and name defined directly on this note, or
* `null` if there is none. It skips inheritance, so it can be much faster than
* `getAttribute()`.
*
* @param type `"label"` or `"relation"`.
* @param value The value to match; when omitted, any value matches.
*/
getOwnedAttribute(type: string, name: string, value?: string | null): ScriptAttribute | null;
/**
* Returns the value of the first attribute of the given type and name, inherited ones
* included, or `null` if there is none. For a relation, the value is the target note's ID.
*
* @param type `"label"` or `"relation"`.
*/
getAttributeValue(type: string, name: string): string | null;
/**
* Returns the value of the first attribute of the given type and name defined directly on this
* note, or `null` if there is none. For a relation, the value is the target note's ID.
*
* @param type `"label"` or `"relation"`.
*/
getOwnedAttributeValue(type: string, name: string): string | null;
/**
* Returns the attribute of this note with the given ID, inherited ones included, or `undefined`
* if there is none.
*/
getAttributeById(attributeId: string): ScriptAttribute | undefined;
/**
* Returns the first attribute of the given type whose name, and optionally value, matches
* regardless of letter case, or `undefined` if none does. Inherited attributes are included.
*
* @param type `"label"` or `"relation"`.
* @param value The value to match; an empty or omitted value matches any value.
*/
getAttributeCaseInsensitive(
type: string,
name: string,
value?: string | null
): ScriptAttribute | undefined;
/**
* Returns `true` if the note has a label or relation of the given type and name, inherited ones
* included.
*
* @param type `"label"` or `"relation"`.
*/
hasAttribute(type: string, name: string): boolean;
/**
* Returns whether the note has a label or relation of the given type and name defined directly
* on it. Inherited attributes don't count.
*
* @param type `"label"` or `"relation"`.
* @param value The value to match; when omitted, any value matches.
*/
hasOwnedAttribute(type: string, name: string, value?: string): boolean;
/**
* Returns the attribute definitions on this note, inherited ones included. Currently returns
* the same `#relation:*` definitions as `getRelationDefinitions()`, not the `#label:*` ones; to
* read label definitions, filter `getLabels()` by names that start with `label:`.
*/
getLabelDefinitions(): ScriptAttribute[];
/**
* Returns the relation definitions on this note, inherited ones included: the `#relation:*`
* labels that declare promoted relations, such as `#relation:author="promoted,single"`.
*/
getRelationDefinitions(): ScriptAttribute[];
/**
* Returns the relations in other notes (or this one) that point to this note, the automatic
* link relations included. Same as `targetRelations`.
*/
getTargetRelations(): ScriptAttribute[];
// --- Labels ------------------------------------------------------------
/**
* Returns the first label with the given name, inherited ones included, or `null` if there is
* none. Pass the name without the leading `#`.
*/
getLabel(name: string): ScriptAttribute | null;
/**
* Returns the first label with the given name defined directly on this note, or `null` if there
* is none.
*/
getOwnedLabel(name: string): ScriptAttribute | null;
/**
* Returns the labels of this note, inherited ones included. When `name` is given, only labels
* with that name are returned.
*/
getLabels(name?: string): ScriptAttribute[];
/** Returns the labels with the given name defined directly on this note. */
getOwnedLabels(name: string): ScriptAttribute[];
/**
* Returns the value of the first label with the given name, inherited ones included, or `null`
* if there is none. A label without a value returns an empty string.
*/
getLabelValue(name: string): string | null;
/**
* Returns the value of the first label with the given name defined directly on this note, or
* `null` if there is none.
*/
getOwnedLabelValue(name: string): string | null;
/**
* Returns the values of all labels with the given name, inherited ones included, for labels
* that can occur more than once.
*/
getLabelValues(name: string): string[];
/** Returns the values of all labels with the given name defined directly on this note. */
getOwnedLabelValues(name: string): string[];
/** Returns whether the note has a label with the given name, inherited ones included. */
hasLabel(name: string): boolean;
/**
* Returns whether the note has a label with the given name defined directly on it.
*
* @param value The value to match; when omitted, any value matches.
*/
hasOwnedLabel(name: string, value?: string): boolean;
/**
* Returns whether the note has a label with the given name, inherited ones included, whose
* value is not `"false"`. A label without a value counts as `true`.
*/
isLabelTruthy(name: string): boolean;
/**
* Returns `true` if the note has an inheritable `#archived` label, owned or inherited, so that
* the note's descendants are archived too.
*/
hasInheritableArchivedLabel(): boolean;
// --- Relations ---------------------------------------------------------
/**
* Returns the first relation with the given name, inherited ones included, or `null` if there
* is none. Pass the name without the leading `~`.
*/
getRelation(name: string): ScriptAttribute | null;
/**
* Returns the first relation with the given name defined directly on this note, or `null` if
* there is none.
*/
getOwnedRelation(name: string): ScriptAttribute | null;
/**
* Returns the relations of this note, inherited ones included. When `name` is given, only
* relations with that name are returned.
*/
getRelations(name?: string): ScriptAttribute[];
/**
* Returns the relations defined directly on this note. When `name` is given, only relations
* with that name are returned.
*/
getOwnedRelations(name?: string | null): ScriptAttribute[];
/**
* Returns the ID of the note that the first relation with the given name points to, inherited
* relations included, or `null` if there is none. To get the note itself, use
* `getRelationTarget()`.
*/
getRelationValue(name: string): string | null;
/**
* Returns the ID of the note that the first relation with the given name defined directly on
* this note points to, or `null` if there is none.
*/
getOwnedRelationValue(name: string): string | null;
/**
* Returns the note that the first relation with the given name points to, or `null` if the note
* has no such relation. Inherited relations are included.
*/
getRelationTarget(name: string): ScriptBNote | null;
/**
* Returns whether the note has a relation with the given name, inherited ones included.
*
* @param value The ID of the target note to match; when omitted, any target matches.
*/
hasRelation(name: string, value?: string): boolean;
/**
* Returns whether the note has a relation with the given name defined directly on it.
*
* @param value The ID of the target note to match; when omitted, any target matches.
*/
hasOwnedRelation(name: string, value?: string): boolean;
// --- Attributes (write) ------------------------------------------------
/**
* Adds a label to this note, saves it and returns it. It adds a new label even when the note
* already has one with that name; to change an existing label instead, use `setLabel()`.
*
* @param name The label name, without the leading `#`.
* @param value The label value. Defaults to an empty string.
* @param isInheritable Whether the note's descendants inherit the label. Defaults to `false`.
*/
addLabel(name: string, value?: string, isInheritable?: boolean): ScriptAttribute;
/**
* Adds a relation from this note to another note, saves it and returns it. It adds a new
* relation even when the note already has one with that name; to change an existing relation
* instead, use `setRelation()`.
*
* @param name The relation name, without the leading `~`.
* @param isInheritable Whether the note's descendants inherit the relation. Defaults to
* `false`.
*/
addRelation(name: string, targetNoteId: string, isInheritable?: boolean): ScriptAttribute;
/**
* Adds a label or relation to this note, saves it and returns it. `addLabel()` and
* `addRelation()` do the same for one type.
*
* @param type `"label"` or `"relation"`.
* @param name The attribute name, without the leading `#` or `~`.
* @param value The label's text, or the relation's target note ID. Defaults to an empty string.
* @param isInheritable Whether the note's descendants inherit the attribute. Defaults to
* `false`.
*/
addAttribute(
type: string,
name: string,
value?: string,
isInheritable?: boolean
): ScriptAttribute;
/**
* Sets the value of the first label with the given name defined directly on this note, or adds
* a non-inheritable label if the note has none of its own. Inherited labels are left alone. The
* change is saved immediately.
*
* @param value The new value. Defaults to an empty string.
*/
setLabel(name: string, value?: string): void;
/**
* Points the first relation with the given name defined directly on this note to another note,
* or adds a non-inheritable relation if the note has none of its own. Inherited relations are
* left alone. The change is saved immediately.
*
* @param value The ID of the target note.
*/
setRelation(name: string, value?: string): void;
/**
* Sets the value of the first attribute of the given type and name defined directly on this
* note, or adds a non-inheritable one if the note has none of its own. `setLabel()` and
* `setRelation()` do the same for one type. The change is saved immediately.
*
* @param type `"label"` or `"relation"`.
* @param value The label's text, or the relation's target note ID. Defaults to an empty string.
*/
setAttribute(type: string, name: string, value?: string): void;
/**
* Sets the value of the attribute with the given ID, which must be defined directly on this
* note, and saves it. Throws an error if the note has no such attribute of its own.
*
* @param value The new value. Defaults to an empty string.
*/
setAttributeValueById(attributeId: string, value?: string): void;
/**
* Sets the label like `setLabel()` when `enabled` is `true`, and removes it like
* `removeLabel()` when it is `false`.
*/
toggleLabel(enabled: boolean, name: string, value?: string): void;
/**
* Sets the relation like `setRelation()` when `enabled` is `true`, and removes it like
* `removeRelation()` when it is `false`.
*
* @param value The ID of the target note.
*/
toggleRelation(enabled: boolean, name: string, value?: string): void;
/**
* Sets the attribute like `setAttribute()` when `enabled` is `true`, and removes it like
* `removeAttribute()` when it is `false`.
*
* @param type `"label"` or `"relation"`.
*/
toggleAttribute(type: string, enabled: boolean, name: string, value?: string): void;
/**
* Removes every label with the given name defined directly on this note. Inherited labels are
* not affected.
*
* @param value The value to match; when omitted, labels with any value are removed.
*/
removeLabel(name: string, value?: string): void;
/**
* Removes every relation with the given name defined directly on this note. Inherited
* relations are not affected.
*
* @param value The ID of the target note to match; when omitted, relations to any note are
* removed.
*/
removeRelation(name: string, value?: string): void;
/**
* Removes every attribute of the given type and name defined directly on this note. Inherited
* attributes are not affected.
*
* @param type `"label"` or `"relation"`.
* @param value The value to match; when omitted, attributes with any value are removed.
*/
removeAttribute(type: string, name: string, value?: string): void;
/**
* Returns `true` if another note uses this note as its template or inheritance source, through
* a `~template` or `~inherit` relation. Despite the name, it does not tell whether this note
* inherits attributes itself.
*/
isInherited(): boolean;
// --- Revisions & attachments -------------------------------------------
/**
* The number of revisions of this note. It is `null` until a search that filters or sorts by
* `revisionCount` or one of the size properties has run; `getRevisions().length` always works.
*/
revisionCount: number | null;
/** Returns the saved revisions of this note, oldest first. */
getRevisions(): ScriptBRevision[];
/**
* Saves a revision that snapshots the note's current title, content and attachments, and
* returns it. Afterwards, Trilium erases the oldest revisions beyond the number the revision
* settings keep.
*
* @param opts `description` names the revision; `source` records what created it: `"auto"` (the
* default), `"manual"`, `"etapi"`, `"llm"` or `"restore"`.
*/
saveRevision(opts?: { description?: string; source?: string }): ScriptBRevision;
/**
* Returns the attachments of this note, ordered by position. Deleted attachments are excluded.
*/
getAttachments(): ScriptBAttachment[];
/**
* Returns the attachment of this note with the given ID. Returns `undefined` if this note has
* no such attachment, although the type does not say so.
*/
getAttachmentById(attachmentId: string): ScriptBAttachment;
/**
* Returns the first attachment of this note whose title matches exactly, or `undefined` if none
* does.
*/
getAttachmentByTitle(title: string): ScriptBAttachment | undefined;
/**
* Returns the attachments of this note with the given role, such as `"image"` or `"file"`,
* ordered by position.
*/
getAttachmentsByRole(role: string): ScriptBAttachment[];
/**
* Saves an attachment of this note and returns it. If an existing attachment matches, only its
* content is replaced; otherwise a new attachment is created from `attachment`, protected if
* the note is. Missing content is saved as an empty string.
*
* @param matchBy How to find an existing attachment to update: `"attachmentId"` (the default)
* by `attachment.attachmentId`, which throws an error if no attachment has that ID, or
* `"title"` by `attachment.title` among this note's attachments.
*/
saveAttachment(
attachment: ScriptSaveAttachmentInput,
matchBy?: "attachmentId" | "title"
): ScriptBAttachment;
/**
* Converts this image note into an image attachment of its parent text note, points the
* parent's content at the attachment, deletes this note and returns the attachment. Returns
* `null` and changes nothing when `isEligibleForConversionToAttachment()` returns `false`.
*
* @param opts Pass `{ autoConversion: true }` to also require that the parent links the image.
*/
convertToParentAttachment(opts?: { autoConversion?: boolean }): ScriptBAttachment | null;
/**
* Returns `true` if this note can be converted into an attachment of its parent: it is an image
* note with no children and a single parent, the parent is a text note, both are readable in
* the current session, and at most one `~imageLink` relation points to the image, from the
* parent.
*
* @param opts Pass `{ autoConversion: true }` to also require that the parent links the image.
*/
isEligibleForConversionToAttachment(opts?: { autoConversion?: boolean }): boolean;
// --- Sizes -------------------------------------------------------------
/**
* The size of the note's content in bytes. Like the other size properties, it is `null` until a
* search that filters or sorts by one of them, or by `revisionCount`, has run.
*/
contentSize: number | null;
/**
* The size in bytes of the note's content together with its attachments, counting content
* that several of them share once. It is `null` until a search that uses it has run.
*/
contentAndAttachmentsSize: number | null;
/**
* The size in bytes of the note's content together with its attachments and its revisions and
* their attachments, counting shared content once. It is `null` until a search that uses it has
* run.
*/
contentAndAttachmentsAndRevisionsSize: number | null;
// --- Tree operations ---------------------------------------------------
/**
* Places this note under another parent note as well, keeping its existing placements, and
* expands the new parent in the note tree. The result does not throw on failure; check
* `success`, and read `message` for why it failed (for example, the note is already in that
* parent, the target is a search note, or the clone would create a cycle).
*
* @param parentNoteId The ID of the note to clone into.
* @returns On success, `branchId` of the new branch and `notePath` of the clone.
*/
cloneTo(parentNoteId: string): ScriptCloneResponse;
/**
* Deletes the note from every place in the tree, together with its descendants that have no
* other placement, and runs its `runOnNoteDeletion` relations first. Deleted notes stay
* recoverable until they are erased. Does nothing if the note is already deleted.
*
* @param deleteId An ID that groups the deleted notes, branches and attributes so that they can
* be restored together. Defaults to a new random ID.
*/
deleteNote(deleteId?: string | null): void;
/**
* Reorders this note's `parents` and `parentBranches` in memory so that archived and hidden
* parents come last, which makes Trilium prefer the other paths when it picks a note path.
* Saves nothing.
*/
sortParents(): void;
/**
* Reorders this note's `children` array in memory by each child's `notePosition`. Saves nothing
* and does not change the order shown in the note tree.
*/
sortChildren(): void;
// --- Search ------------------------------------------------------------
/**
* Returns the notes that match a search query. Despite the name, the search covers the whole
* tree, not only this note's subtree, and leaves out archived and hidden notes; to limit it to
* this note's subtree, call `api.searchForNotes(query, { ancestorNoteId: note.noteId })`.
*/
searchNotesInSubtree(searchString: string): ScriptBNote[];
/**
* Returns the first note that matches a search query, or `undefined` if none does. Like
* `searchNotesInSubtree()`, the search covers the whole tree, not only this note's subtree.
*/
searchNoteInSubtree(searchString: string): ScriptBNote | null;
/**
* Runs the saved search of a search note and returns the notes it finds. Returns an empty array
* for other note types, and when the search fails (the error goes to the backend log).
*/
getSearchResultNotes(): ScriptBNote[];
// --- Type & state predicates -------------------------------------------
/**
* Returns `true` if this note is a search note or has at least one child, archived children
* included.
*/
isFolder(): boolean;
/**
* Returns `true` if the note's title and content can be read: the note is not protected, or a
* protected session is open. Otherwise the content reads as an empty string and the title as
* `"[protected]"`.
*/
isContentAvailable(): boolean;
/**
* Returns whether `getContent()` returns a string rather than a `Uint8Array`.
*
* @deprecated Use `hasStringContent()` instead.
*/
isStringNote(): boolean;
/** Returns whether this is a code, file or render note with the MIME type `text/html`. */
isHtml(): boolean;
/** Returns whether this is an image note, or a file note with an `image/*` MIME type. */
isImage(): boolean;
/** Returns whether this is a code, file or launcher note with a JavaScript MIME type. */
isJavaScript(): boolean;
/** Returns `true` if this is a code note with the MIME type `text/jsx`. */
isJsx(): boolean;
/** Returns whether the note's MIME type is `application/json`, whatever its type. */
isJson(): boolean;
/** Returns whether this is a code note with a Markdown MIME type. */
isMarkdown(): boolean;
/**
* Returns `true` if this note is one of the settings pages in the hidden subtree, whose IDs
* start with `_options`.
*/
isOptions(): boolean;
/**
* Returns `true` if this note is a launcher or one of the containers that configure the desktop
* or mobile launch bar.
*/
isLaunchBarConfig(): boolean;
/**
* Returns whether every path to this note passes through the hidden subtree (`_hidden`), so
* that the note has no placement in the visible tree. Returns `false` for the root note and for
* `_hidden` itself.
*/
isHiddenCompletely(): boolean;
/**
* Returns `true` if this note is the hidden root note (`_hidden`) or lies under it in any of
* its placements. The hidden subtree holds Trilium's system notes, such as settings, launchers
* and templates.
*/
isInHiddenSubtree(): boolean;
// --- Scripting runtime -------------------------------------------------
/**
* Returns where the note runs as a script: `"backend"` for JavaScript with `env=backend` in its
* MIME type, `"frontend"` for frontend JavaScript, JSX, HTML and render notes, and `null` for
* notes that are not scripts.
*/
getScriptEnv(): "frontend" | "backend" | null;
/**
* Runs this note as a backend script and returns the script's return value, which is a promise
* for an async script. The note must be a backend JavaScript code note; for any other note it
* runs nothing and returns `undefined`. Throws an error if the note is protected and no
* protected session is active, or if backend scripting is disabled.
*/
executeScript(): unknown;
}
/** Result of the backend note-creation helpers. */
export interface ScriptNoteAndBranch {
/** The new note. For `duplicateSubtree()`, it is the copy of the original note. */
note: ScriptBNote;
/** The branch that places the new note under its parent. */
branch: ScriptBBranch;
}
/**
* Minimal Express `Request` surface available to **custom request handlers**
* (a subset of Express's `Request` — re-declared here to keep this module
* self-contained). Only the commonly used members are typed; the real object is
* a full Express request.
*/
export interface ScriptRequest {
/** Route/path parameters. */
params: Record<string, string>;
/** Parsed query-string parameters. */
query: Record<string, unknown>;
/** Parsed request body (requires a matching body parser). */
body: unknown;
/** Request headers (lower-cased names). */
headers: Record<string, string | string[] | undefined>;
/** HTTP method, e.g. "GET", "POST". */
method: string;
/** Request URL (path + query string). */
url: string;
/** Returns the value of the given (case-insensitive) header. */
get(headerName: string): string | undefined;
}
/**
* Minimal Express `Response` surface available to **custom request handlers**
* (a subset of Express's `Response`). Write the HTTP response through this
* object, e.g. `api.res.status(200).json({ ok: true })`.
*/
export interface ScriptResponse {
/** Sets the HTTP status code (chainable). */
status(code: number): ScriptResponse;
/** Sends the response body (string, Buffer, object, …) and ends the response. */
send(body?: unknown): ScriptResponse;
/** Sends a JSON response and ends the response. */
json(body: unknown): ScriptResponse;
/** Sets a response header (chainable). */
setHeader(name: string, value: string | string[]): ScriptResponse;
/** Sets a response header (Express alias of `setHeader`, chainable). */
set(field: string, value?: string): ScriptResponse;
/** Redirects to the given URL. */
redirect(url: string): void;
/** Ends the response without further data. */
end(): void;
}
/**
* The `api` global available inside **backend** script notes
* (`application/javascript;env=backend`). Runs server-side: no DOM, no jQuery.
*/
export interface BackendApi {
/**
* Note where the script execution started — the entry point of the current script bundle
* (in C terms, the file containing `main()`). When a script is spread across multiple code
* notes (descendant code notes loaded as modules via `require()`), every note in the
* bundle shares the same `startNote`, while {@link currentNote} differs per note.
* Messages from `api.log()` are grouped under this note.
*
* When a frontend script calls `api.runOnBackend()`, the frontend's `startNote` is
* preserved here; since that note may not be resolvable on the backend, this can be null.
*/
startNote?: ScriptBNote | null;
/**
* Note containing the source code that is currently executing (in C terms, `__FILE__`).
* Equal to {@link startNote} unless execution has moved into a descendant module note
* loaded via `require()`. Don't confuse this with the concept of the active note in
* the UI.
*/
currentNote: ScriptBNote;
/**
* Entity whose event triggered this execution; `undefined` when the run was not
* event-driven (e.g. started manually via "Execute script" or `note.executeScript()`).
*
* What it holds depends on the trigger:
* - `~runOnNoteCreation`, `~runOnNoteChange`, `~runOnNoteTitleChange`,
* `~runOnNoteContentChange` — the affected note;
* - `~runOnChildNoteCreation` — the newly created child note;
* - `~runOnAttributeCreation`, `~runOnAttributeChange` — the attribute;
* - `~runOnBranchCreation`, `~runOnBranchChange`, `~runOnBranchDeletion` — the branch;
* - scheduled scripts (`#run=backendStartup` / `#run=hourly` / `#run=daily`) — the
* script note itself;
* - search scripts (`~searchScript`) — the search note.
*/
originEntity?: ScriptBNote | ScriptBBranch | ScriptAttribute | null;
/**
* The HTTP request, present only when the script runs as a custom request handler: a note
* with the `#customRequestHandler` label, invoked through a `/custom/...` URL. It is
* `undefined` in every other backend script. The object is Express's own request, so it has
* more members than `ScriptRequest` lists.
*/
req: ScriptRequest;
/**
* The HTTP response to write the reply to, such as `api.res.status(200).json({ ok: true })`.
* Like `req`, it is present only in custom request handlers, and is Express's own response.
*/
res: ScriptResponse;
/**
* The capture groups from the `#customRequestHandler` regex that matched this
* request's URL, in order. Available only inside custom request handlers.
*/
pathParams: string[];
/**
* day.js library for date manipulation. See {@link https://day.js.org} for documentation
*/
dayjs: ScriptDayjs;
/** The xml2js library, which converts between XML and JavaScript objects. */
xml2js: ScriptXml2js;
/** The node-html-parser library, which parses HTML into elements that can be queried. */
htmlParser: ScriptHtmlParser;
/**
* Instance name identifies particular Trilium instance. It can be useful for scripts
* if some action needs to happen on only one specific instance.
*/
getInstanceName(): string | null;
/** Returns a note by its ID, or null. */
getNote(noteId: string): ScriptBNote | null;
/** Returns a branch by its ID, or null. */
getBranch(branchId: string): ScriptBBranch | null;
/** Returns an attribute by its ID, or null. */
getAttribute(attributeId: string): ScriptAttribute | null;
/** Returns an attachment by its ID, or null. */
getAttachment(attachmentId: string): ScriptBAttachment | null;
/** Returns a revision by its ID, or null. */
getRevision(revisionId: string): ScriptBRevision | null;
/** Returns an ETAPI token by its ID, or null. */
getEtapiToken(etapiTokenId: string): ScriptBEtapiToken | null;
/** Returns all ETAPI tokens. */
getEtapiTokens(): ScriptBEtapiToken[];
/** Returns an option by name, or null. */
getOption(optionName: string): ScriptBOption | null;
/** Returns all options. */
getOptions(): ScriptBOption[];
/**
* This is a powerful search method - you can search by attributes and their values, e.g.:
* "#dateModified =* MONTH AND #log". See {@link https://triliumnext.github.io/Docs/Wiki/search.html} for full documentation for all options
*/
searchForNotes(query: string, searchParams?: ScriptSearchParams): ScriptBNote[];
/**
* This is a powerful search method - you can search by attributes and their values, e.g.:
* "#dateModified =* MONTH AND #log". See {@link https://triliumnext.github.io/Docs/Wiki/search.html} for full documentation for all options
*/
searchForNote(query: string, searchParams?: ScriptSearchParams): ScriptBNote | null;
/**
* Retrieves notes with given label name & value
*
* @param name - attribute name
* @param value - attribute value
*/
getNotesWithLabel(name: string, value?: string): ScriptBNote[];
/**
* Retrieves first note with given label name & value
*
* @param name - attribute name
* @param value - attribute value
*/
getNoteWithLabel(name: string, value?: string): ScriptBNote | null;
/**
* If there's no branch between note and parent note, create one. Otherwise, do nothing. Returns the new or existing branch.
*
* @param prefix - if branch is created between note and parent note, set this prefix
*/
ensureNoteIsPresentInParent(noteId: string, parentNoteId: string, prefix?: string): { branch: ScriptBBranch | null };
/**
* If there's a branch between note and parent note, remove it. Otherwise, do nothing.
*/
ensureNoteIsAbsentFromParent(noteId: string, parentNoteId: string): void;
/**
* Based on the value, either create or remove branch between note and parent note.
*
* @param present - true if we want the branch to exist, false if we want it gone
* @param prefix - if branch is created between note and parent note, set this prefix
*/
toggleNoteInParent(present: boolean, noteId: string, parentNoteId: string, prefix?: string): void;
/**
* Create text note. See also createNewNote() for more options.
*/
createTextNote(parentNoteId: string, title: string, content: string): ScriptNoteAndBranch;
/**
* Create data note - data in this context means object serializable to JSON. Created note will be of type 'code' and
* JSON MIME type. See also createNewNote() for more options.
*/
createDataNote(parentNoteId: string, title: string, content: object): ScriptNoteAndBranch;
/**
* @returns object contains newly created entities note and branch
*/
createNewNote(params: {
parentNoteId: string;
title: string;
content: string | Uint8Array;
type: string;
mime?: string;
[key: string]: unknown;
}): ScriptNoteAndBranch;
/** Per-note log message buffers shown in the UI log pane. */
logMessages: Record<string, string[]>;
/** Per-note spaced-update handlers for the log pane. */
logSpacedUpdates: Record<string, unknown>;
/**
* Log given message to trilium logs and log pane in UI.
* Accepts multiple arguments which are joined with spaces, similar to `console.log`.
*/
log(...args: unknown[]): void;
/**
* Returns root note of the calendar.
*/
getRootCalendarNote(): ScriptBNote | null;
/**
* Returns day note for given date. If such note doesn't exist, it is created.
*
* @method
* @param date in YYYY-MM-DD format
* @param rootNote - specify calendar root note, normally leave empty to use the default calendar
*/
getDayNote(date: string, rootNote?: ScriptBNote): ScriptBNote | null;
/**
* Returns today's day note. If such note doesn't exist, it is created.
*
* @param rootNote specify calendar root note, normally leave empty to use the default calendar
*/
getTodayNote(rootNote?: ScriptBNote): ScriptBNote | null;
/**
* Returns note for the first date of the week of the given date.
*
* @param date in YYYY-MM-DD format
* @param rootNote - specify calendar root note, normally leave empty to use the default calendar
*/
getWeekFirstDayNote(date: string, rootNote?: ScriptBNote): ScriptBNote | null;
/**
* Returns week note for given date. If such a note doesn't exist, it is created.
*
* <p>
* If the calendar does not support week notes, this method will return `null`.
*
* @param date in YYYY-MM-DD format
* @param rootNote - specify calendar root note, normally leave empty to use the default calendar
* @return an existing or newly created week note, or `null` if the calendar does not support week notes.
*/
getWeekNote(date: string, rootNote?: ScriptBNote): ScriptBNote | null;
/**
* Returns month note for given date. If such a note doesn't exist, it is created.
*
* @param date in YYYY-MM format
* @param rootNote - specify calendar root note, normally leave empty to use the default calendar
*/
getMonthNote(date: string, rootNote?: ScriptBNote): ScriptBNote | null;
/**
* Returns quarter note for given date. If such a note doesn't exist, it is created.
*
* @param date in YYYY-MM format
* @param rootNote - specify calendar root note, normally leave empty to use the default calendar
*/
getQuarterNote(date: string, rootNote?: ScriptBNote): ScriptBNote | null;
/**
* Returns year note for given year. If such a note doesn't exist, it is created.
*
* @param year in YYYY format
* @param rootNote - specify calendar root note, normally leave empty to use the default calendar
*/
getYearNote(year: string, rootNote?: ScriptBNote): ScriptBNote | null;
/**
* Sort child notes of a given note. `sortBy` takes the `#sorted` grammar — comma-separated
* levels of `title`, `dateCreated`, `dateModified` or a label name, each optionally followed by
* `asc` or `desc` (`priority desc, dueDate`); `reverse` is the direction of the levels without
* their own, of the folders grouping and of ties.
*/
sortNotes(parentNoteId: string, sortConfig: { sortBy?: string; reverse?: boolean; foldersFirst?: boolean }): void;
/**
* This method finds note by its noteId and prefix and either sets it to the given parentNoteId
* or removes the branch (if parentNoteId is not given).
*
* This method looks similar to toggleNoteInParent() but differs because we're looking up branch by prefix.
*
* @deprecated this method is pretty confusing and serves specialized purpose only
*/
setNoteToParent(noteId: string, prefix: string, parentNoteId: string | null): void;
/**
* This functions wraps code which is supposed to be running in transaction. If transaction already
* exists, then we'll use that transaction.
*
* @param func
* @returns result of func callback
*/
transactional<T>(func: () => T): T;
/**
* Return randomly generated string of given length. This random string generation is NOT cryptographically secure.
*
* @param length of the string
* @returns random string
*/
randomString(length: number): string;
/**
* @param to escape
* @returns escaped string
*/
escapeHtml(str: string): string;
/**
* @param string to unescape
* @returns unescaped string
*/
unescapeHtml(str: string): string;
/**
* Converts the given HTML string to Markdown.
*
* @param html - HTML content to convert
* @returns Markdown representation of the input HTML
*/
htmlToMarkdown(html: string): string;
/**
* Converts the given Markdown string to HTML.
*
* @param markdown - Markdown content to convert
* @returns HTML representation of the input Markdown
*/
markdownToHtml(markdown: string): string;
/** Direct access to Trilium's SQLite database. */
sql: ScriptSql;
/** Application info (version, build date, etc.). */
getAppInfo(): ScriptAppInfo;
/**
* Creates a new launcher to the launchbar. If the launcher (id) already exists, it will be updated.
*/
createOrUpdateLauncher(opts: {
id: string;
type: "note" | "script" | "customWidget";
title: string;
isVisible: boolean;
icon: string;
keyboardShortcut: string;
targetNoteId?: string;
scriptNoteId?: string;
widgetNoteId?: string;
}): { note: ScriptBNote };
/**
* @param format - either 'html' or 'markdown'
*/
exportSubtreeToZipFile(noteId: string, format: "markdown" | "html", zipFilePath: string): Promise<void>;
/**
* Executes given anonymous function on the frontend(s).
* Internally, this serializes the anonymous function into string and sends it to frontend(s) via WebSocket.
* Note that there can be multiple connected frontend instances (e.g. in different tabs). In such case, all
* instances execute the given function.
*
* @param script - script to be executed on the frontend
* @param params - list of parameters to the anonymous function to be sent to frontend
* @returns no return value is provided.
*/
runOnFrontend(script: (() => void) | string, params?: unknown[]): void;
/**
* Sync process can make data intermittently inconsistent. Scripts which require strong data consistency
* can use this function to wait for a possible sync process to finish and prevent new sync process from starting
* while it is running.
*
* Because this is an async process, the inner callback doesn't have automatic transaction handling, so in case
* you need to make some DB changes, you need to surround your call with api.transactional(...)
*
* @param callback - function to be executed while sync process is not running
* @returns resolves once the callback is finished (callback is awaited)
*/
runOutsideOfSync(callback: () => void): Promise<void>;
/**
* @param backupName - If the backupName is e.g. "now", then the backup will be written to "backup-now.db" file
* @returns resolves once the backup is finished
*/
backupNow(backupName: string): Promise<string>;
/**
* Enables the complete duplication of the specified original note and all its children into the specified parent note.
* The new note will be named the same as the original, with (Dup) added to the end of it.
*
* @param origNoteId - the noteId for the original note to be duplicated
* @param newParentNoteId - the noteId for the parent note where the duplication is to be placed.
*
* @returns the note and the branch of the newly created note.
*/
duplicateSubtree(origNoteId: string, newParentNoteId: string): ScriptNoteAndBranch;
}