Skip to content

Build your personal knowledge base with Trilium Notes

17.4 KB
Raw Blame
import { AttributeType, BUILTIN_ATTRIBUTES, type BuiltinLabel, type DefinitionObject, type LabelType, promotedAttributeDefinitionParser } from "@triliumnext/commons";

import type FAttribute from "../entities/fattribute.js";
import type FNote from "../entities/fnote.js";
import froca from "./froca.js";
import type { AttributeRow } from "./load_results.js";
import server from "./server.js";

async function addLabel(noteId: string, name: string, value: string = "", isInheritable = false) {
    await server.put(`notes/${noteId}/attribute`, {
        type: "label",
        name,
        value,
        isInheritable
    });
}

export async function setLabel(noteId: string, name: string, value: string = "", isInheritable = false, componentId?: string) {
    await server.put(`notes/${noteId}/set-attribute`, {
        type: "label",
        name,
        value,
        isInheritable,
    }, componentId);
}

export async function setRelation(noteId: string, name: string, value: string = "", isInheritable = false) {
    await server.put(`notes/${noteId}/set-attribute`, {
        type: "relation",
        name,
        value,
        isInheritable
    });
}

/**
 * Sets a boolean label on the given note, taking inheritance into account. If the desired value matches the inherited
 * value, any owned label will be removed to allow the inherited value to take effect. If the desired value differs
 * from the inherited value, an owned label will be created or updated to reflect the desired value.
 *
 * When checking if the boolean value is set, don't use `note.hasLabel`; instead use `note.isLabelTruthy`.
 *
 * @param note the note on which to set the boolean label.
 * @param labelName the name of the label to set.
 * @param value the boolean value to set for the label.
 */
export async function setBooleanWithInheritance(note: FNote, labelName: string, value: boolean) {
    if (note.isLabelTruthy(labelName) === value) return;

    const inheritedLabel = note.getLabels(labelName).find((label) => label.noteId !== note.noteId);
    const inheritedValue = !!inheritedLabel && inheritedLabel.value !== "false";

    if (value === inheritedValue) {
        await removeOwnedAttributesByNameOrType(note, "label", labelName);
        return;
    }

    // `set-attribute` updates one owned label and leaves its duplicates in effect.
    for (const duplicate of note.getOwnedLabels(labelName).slice(1)) {
        await removeAttributeById(note.noteId, duplicate.attributeId);
    }
    await setLabel(note.noteId, labelName, value ? "" : "false");
}

/**
 * Sets a label with a value on the given note, taking inheritance into account like
 * {@link setBooleanWithInheritance}: the owned labels are removed when the note inherits `value`, or
 * reads it as `defaultValue` without a label, and one owned label is created or updated otherwise.
 *
 * @param note the note on which to set the label.
 * @param labelName the name of the label to set.
 * @param value the value to set for the label.
 * @param defaultValue the value of a note without the label, or with an empty one.
 * @param isInheritable whether the note's children must read the value too. Without it, an owned
 * label keeps its inheritability, and a new one is not inheritable.
 */
export async function setLabelValueWithInheritance(
    note: FNote,
    labelName: string,
    value: string,
    defaultValue: string,
    isInheritable = false
) {
    const [ ownedLabel, ...duplicates ] = note.getOwnedLabels(labelName);
    const inheritedLabel = note.getLabels(labelName).find((label) => label.noteId !== note.noteId);

    if (ownedLabel && (ownedLabel.value || defaultValue) === value
            && (!isInheritable || ownedLabel.isInheritable)) {
        return;
    }

    // A label the note inherits reaches its children only when the label is inheritable itself.
    const reachesChildren = !isInheritable || !inheritedLabel || inheritedLabel.isInheritable;
    if (reachesChildren && (inheritedLabel?.value || defaultValue) === value) {
        await removeOwnedAttributesByNameOrType(note, "label", labelName);
        return;
    }

    // `set-attribute` changes the value of an owned label but not its inheritability.
    const replaced = isInheritable && ownedLabel && !ownedLabel.isInheritable
        ? [ ownedLabel, ...duplicates ]
        : duplicates;
    for (const label of replaced) {
        await removeAttributeById(note.noteId, label.attributeId);
    }
    await setLabel(note.noteId, labelName, value, isInheritable);
}

async function removeAttributeById(noteId: string, attributeId: string) {
    await server.remove(`notes/${noteId}/attributes/${attributeId}`);
}

export async function removeOwnedAttributesByNameOrType(note: FNote, type: AttributeType, name: string) {
    for (const attr of note.getOwnedAttributes()) {
        if (attr.type === type && attr.name === name) {
            await server.remove(`notes/${note.noteId}/attributes/${attr.attributeId}`);
        }
    }
}

/**
 * Removes a label identified by its name from the given note, if it exists. Note that the label must be owned, i.e.
 * it will not remove inherited attributes.
 *
 * @param note the note from which to remove the label.
 * @param labelName the name of the label to remove.
 * @returns `true` if an attribute was identified and removed, `false` otherwise.
 */
async function removeOwnedLabelByName(note: FNote, labelName: string) {
    const label = note.getOwnedLabel(labelName);
    if (label) {
        await removeAttributeById(note.noteId, label.attributeId);
        return true;
    }
    return false;
}

/**
 * Removes a relation identified by its name from the given note, if it exists. Note that the relation must be owned, i.e.
 * it will not remove inherited attributes.
 *
 * @param note the note from which to remove the relation.
 * @param relationName the name of the relation to remove.
 * @returns `true` if an attribute was identified and removed, `false` otherwise.
 */
async function removeOwnedRelationByName(note: FNote, relationName: string) {
    const relation = note.getOwnedRelation(relationName);
    if (relation) {
        await removeAttributeById(note.noteId, relation.attributeId);
        return true;
    }
    return false;
}

/**
 * Sets the labels of one name on a note to exactly `values`, for a field holding a set of them.
 *
 * Writes as few labels as it can while keeping the order the set reads in: a value that stays
 * keeps its label untouched, a removed value deletes its own label, and a replaced value rewrites
 * the label in its place. A new label is always created after the others, so a value inserted
 * before a kept one rewrites the labels that follow it. Each write runs `runOnAttributeChange` on
 * the label it touches. Only owned labels are touched: an inherited one belongs to the note it is
 * written on.
 */
export async function setLabelValues(note: FNote, name: string, values: string[], componentId?: string) {
    await setAttributeValues(note, "label", name, values, componentId);
}

/**
 * Sets the relations of one name on a note to exactly `values` — the targets' noteIds — as
 * {@link setLabelValues} sets a set of labels.
 */
export async function setRelationValues(note: FNote, name: string, values: string[], componentId?: string) {
    await setAttributeValues(note, "relation", name, values, componentId);
}

async function setAttributeValues(note: FNote, type: "label" | "relation", name: string, values: string[], componentId?: string) {
    const existing = type === "label" ? note.getOwnedLabels(name) : note.getOwnedRelations(name);

    for (const write of planValueWrites(existing.map((attr) => attr.value), values)) {
        const attributeId = write.index !== undefined
            ? existing[write.index].attributeId
            : undefined;
        if (write.kind === "remove") {
            await server.remove(`notes/${note.noteId}/attributes/${attributeId}`, componentId);
        } else {
            await server.put(
                `notes/${note.noteId}/attribute`,
                { attributeId, type, name, value: write.value },
                componentId
            );
        }
    }
}

type ValueWrite =
    | { kind: "remove"; index: number }
    | { kind: "put"; index: number | undefined; value: string };

/**
 * Lists the fewest writes that turn the attribute values `current` into `wanted`, in order.
 *
 * Each existing attribute either keeps its value, is rewritten or is removed, and the attributes
 * it keeps hold the start of `wanted` in order. The rest of `wanted` is created, since the server
 * adds a new attribute after the note's other attributes. `cost[i][j]` counts the writes for
 * `current[i..]` and `wanted[j..]`.
 */
function planValueWrites(current: string[], wanted: string[]): ValueWrite[] {
    const cost = Array.from(
        { length: current.length + 1 },
        () => new Array<number>(wanted.length + 1).fill(0)
    );
    for (let i = current.length; i >= 0; i--) {
        for (let j = wanted.length; j >= 0; j--) {
            if (i === current.length) {
                cost[i][j] = wanted.length - j;
            } else if (j === wanted.length) {
                cost[i][j] = 1 + cost[i + 1][j];
            } else {
                const pair = (current[i] === wanted[j] ? 0 : 1) + cost[i + 1][j + 1];
                cost[i][j] = Math.min(pair, 1 + cost[i + 1][j]);
            }
        }
    }

    const writes: ValueWrite[] = [];
    let i = 0;
    let j = 0;
    while (i < current.length) {
        const isEqual = current[i] === wanted[j];
        if (j < wanted.length && cost[i][j] === (isEqual ? 0 : 1) + cost[i + 1][j + 1]) {
            if (!isEqual) {
                writes.push({ kind: "put", index: i, value: wanted[j] });
            }
            j++;
        } else {
            writes.push({ kind: "remove", index: i });
        }
        i++;
    }
    for (const value of wanted.slice(j)) {
        writes.push({ kind: "put", index: undefined, value });
    }
    return writes;
}

/**
 * Adds an option to a `select` definition, for a field offering to create the choice being typed
 * into it.
 *
 * Written back to the very attribute the definition was read from — which is to say to whichever
 * note owns it, typically a parent or a template, rather than to the note being edited — so that
 * every note the field reaches offers the new option from now on.
 *
 * @param definitionAttr the `label:foo` attribute declaring the field.
 * @param option the option to add; already offered, it is left as it stands.
 * @returns the definition as it now reads, for a caller holding a parsed copy of its own.
 */
export async function addSelectOption(definitionAttr: FAttribute, option: string, componentId?: string) {
    const definition = definitionAttr.getDefinition();
    const options = definition.selectOptions ?? [];
    if (options.includes(option)) {
        return definition;
    }

    const newDefinition: DefinitionObject = { ...definition, selectOptions: [ ...options, option ] };
    await server.put(
        `notes/${definitionAttr.noteId}/attribute`,
        {
            attributeId: definitionAttr.attributeId,
            type: "label",
            name: definitionAttr.name,
            value: promotedAttributeDefinitionParser.serialize(newDefinition, "label")
        },
        componentId
    );
    return newDefinition;
}

/**
 * Sets the attribute of the given note to the provided value if its truthy, or removes the attribute if the value is falsy.
 * For an attribute with an empty value, pass an empty string instead.
 *
 * @param note the note to set the attribute to.
 * @param type the type of attribute (label or relation).
 * @param name the name of the attribute to set.
 * @param value the value of the attribute to set.
 */
export async function setAttribute(note: FNote, type: "label" | "relation", name: string, value: string | null | undefined, componentId?: string) {
    if (value !== null && value !== undefined) {
        // Create or update the attribute.
        await server.put(`notes/${note.noteId}/set-attribute`, { type, name, value }, componentId);
    } else {
        // Remove the attribute if it exists on the server but we don't define a value for it.
        const attributeId = note.getAttribute(type, name)?.attributeId;
        if (attributeId) {
            await server.remove(`notes/${note.noteId}/attributes/${attributeId}`, componentId);
        }
    }
}

/**
 * @returns - returns true if this attribute has the potential to influence the note in the argument.
 *         That can happen in multiple ways:
 *         1. attribute is owned by the note
 *         2. attribute is owned by the template of the note
 *         3. attribute is owned by some note's ancestor and is inheritable
 */
function isAffecting(attrRow: AttributeRow, affectedNote: FNote | null | undefined) {
    if (!affectedNote || !attrRow) {
        return false;
    }

    const attrNote = attrRow.noteId && froca.notes[attrRow.noteId];

    if (!attrNote) {
        // the note (owner of the attribute) is not even loaded into the cache, so it should not affect anything else
        return false;
    }

    const owningNotes = [affectedNote, ...affectedNote.getNotesToInheritAttributesFrom()];

    for (const owningNote of owningNotes) {
        if (owningNote.noteId === attrNote.noteId) {
            return true;
        }
    }

    if (attrRow.isInheritable) {
        for (const owningNote of owningNotes) {
            if (owningNote.hasAncestor(attrNote.noteId, true)) {
                return true;
            }
        }
    }

    return false;
}

/**
 * Toggles whether a dangerous attribute is enabled or not. When an attribute is disabled, its name is prefixed with `disabled:`.
 *
 * Note that this work for non-dangerous attributes as well.
 *
 * If there are multiple attributes with the same name, all of them will be toggled at the same time.
 *
 * @param note the note whose attribute to change.
 * @param type the type of dangerous attribute (label or relation).
 * @param name the name of the dangerous attribute.
 * @param willEnable whether to enable or disable the attribute.
 * @returns a promise that will resolve when the request to the server completes.
 */
async function toggleDangerousAttribute(note: FNote, type: "label" | "relation", name: string, willEnable: boolean) {
    const attrs = [
        ...note.getOwnedAttributes(type, name),
        ...note.getOwnedAttributes(type, `disabled:${name}`)
    ];

    for (const attr of attrs) {
        const baseName = getNameWithoutDangerousPrefix(attr.name);
        const newName = willEnable ? baseName : `disabled:${baseName}`;
        if (newName === attr.name) continue;

        // We are adding and removing afterwards to avoid a flicker (because for a moment there would be no active content attribute anymore) because the operations are done in sequence and not atomically.
        if (attr.type === "label") {
            await setLabel(note.noteId, newName, attr.value);
        } else {
            await setRelation(note.noteId, newName, attr.value);
        }
        await removeAttributeById(note.noteId, attr.attributeId);
    }
}

/**
 * Returns the name of an attribute without the `disabled:` prefix, or the same name if it's not disabled.
 * @param name the name of an attribute.
 * @returns the name without the `disabled:` prefix.
 */
function getNameWithoutDangerousPrefix(name: string) {
    return name.startsWith("disabled:") ? name.substring(9) : name;
}

/**
 * Whether the name is one Trilium itself attaches a meaning to, rather than one the user invented.
 *
 * Matched exactly, on purpose: a definition (`label:archived`) describes a system attribute without
 * being one, and a disabled one (`disabled:run`) has been deliberately made inert. Both are ordinary
 * attributes as far as the name alone is concerned.
 */
export function isBuiltinAttribute(type: "label" | "relation", name: string) {
    return BUILTIN_ATTRIBUTE_KEYS.has(`${type}:${name}`);
}

/**
 * The built-ins keyed by type and name. There is no ambiguity in joining the two with a colon: the
 * type is always exactly `label` or `relation`, so the first segment of a key is never in doubt.
 */
const BUILTIN_ATTRIBUTE_KEYS = new Set(BUILTIN_ATTRIBUTES.map(({ type, name }) => `${type}:${name}`));

/**
 * What kind of value a built-in label holds, or `undefined` for a name Trilium attaches no meaning to.
 *
 * Matched exactly, as {@link isBuiltinAttribute} is: a `disabled:` attribute is inert and a definition
 * carries a definition string rather than a value of the type it describes.
 */
export function getBuiltinLabelValueType(name: string): LabelType | undefined {
    return BUILTIN_LABELS.get(name)?.valueType;
}

/**
 * The values a built-in label of the `select` type accepts, or `undefined` for every other name —
 * whether it is a label of another type or none of Trilium's at all.
 *
 * The list is what to *offer*, not what to allow: a value outside it is kept and shown, since the sets
 * grow between versions and a note may have been written by a newer one.
 */
export function getBuiltinLabelSelectOptions(name: string): readonly string[] | undefined {
    return BUILTIN_LABELS.get(name)?.selectOptions;
}

const BUILTIN_LABELS = new Map<string, BuiltinLabel>(
    BUILTIN_ATTRIBUTES.flatMap((attr) => attr.type === "label" ? [ [ attr.name, attr ] as const ] : [])
);

export default {
    addLabel,
    setLabel,
    setRelation,
    setAttribute,
    setLabelValues,
    setRelationValues,
    addSelectOption,
    setBooleanWithInheritance,
    removeAttributeById,
    removeOwnedLabelByName,
    removeOwnedRelationByName,
    isAffecting,
    toggleDangerousAttribute,
    getNameWithoutDangerousPrefix
};