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
import utils from "../services/utils.js";
import type { CommandMappings, CommandNames, EventData, EventNames } from "./app_context.js";
type EventHandler = ((data: any) => unknown);
/**
* Abstract class for all components in the Trilium's frontend.
*
* Contains also event implementation with following properties:
* - event / command distribution is synchronous which among others mean that events are well-ordered - event
* which was sent out first will also be processed first by the component
* - execution of the event / command is asynchronous - each component executes the event on its own without regard for
* other components.
* - although the execution is async, we are collecting all the promises, and therefore it is possible to wait until the
* event / command is executed in all components - by simply awaiting the `triggerEvent()`.
*/
export class TypedComponent<ChildT extends TypedComponent<ChildT>> {
$widget!: JQuery<HTMLElement>;
componentId: string;
children: ChildT[];
initialized: Promise<void> | null;
parent?: TypedComponent<any>;
_position!: number;
// Held in a set so that registering and removing cost the same whatever the list already
// holds: every froca hook re-subscribes whenever its handler changes identity, and a view of
// thousands of components keeps thousands of handlers for one event.
private listeners: Record<string, Set<EventHandler>> | null = {};
constructor() {
this.componentId = `${this.sanitizedClassName}-${utils.randomString(8)}`;
this.children = [];
this.initialized = null;
}
get sanitizedClassName() {
// webpack mangles names and sometimes uses unsafe characters
return this.constructor.name.replace(/[^A-Z0-9]/gi, "_");
}
get position() {
return this._position;
}
set position(newPosition: number) {
this._position = newPosition;
}
setParent(parent: TypedComponent<any>) {
this.parent = parent;
return this;
}
child(...components: ChildT[]) {
for (const component of components) {
component.setParent(this);
this.children.push(component);
}
return this;
}
/**
* Removes a child component from this component's children array.
* This is used for cleanup when a widget is unmounted to prevent event listener accumulation.
*/
removeChild(component: ChildT) {
const index = this.children.indexOf(component);
if (index !== -1) {
this.children.splice(index, 1);
component.parent = undefined;
}
}
handleEvent<T extends EventNames>(name: T, data: EventData<T>): Promise<unknown[] | unknown> | null | undefined {
try {
const callMethodPromise = this.initialized ? this.initialized.then(() => this.callMethod((this as any)[`${name}Event`], data)) : this.callMethod((this as any)[`${name}Event`], data);
const childrenPromise = this.handleEventInChildren(name, data);
// don't create promises if not needed (optimization)
return callMethodPromise && childrenPromise ? Promise.all([callMethodPromise, childrenPromise]) : callMethodPromise || childrenPromise;
} catch (e: unknown) {
console.error(`Handling of event '${name}' failed in ${this.constructor.name} with error`, e);
return null;
}
}
triggerEvent<T extends EventNames>(name: T, data: EventData<T>): Promise<unknown> | undefined | null {
return this.parent?.triggerEvent(name, data);
}
handleEventInChildren<T extends EventNames>(name: T, data: EventData<T>): Promise<unknown[] | unknown> | null {
const promises: Promise<unknown>[] = [];
// Handle React children. Iterate over a copy: a listener can cause handlers to be
// (un)registered while the event is being distributed.
if (this.listeners?.[name]) {
for (const listener of [ ...this.listeners[name] ]) {
const ret = listener(data);
// Collect the promise so that awaiting triggerEvent() waits for async React
// listeners too (the contract documented on this class). Failures are logged
// rather than propagated, so one broken listener cannot abort the operation
// (e.g. a note switch) for everyone else.
if (ret instanceof Promise) {
promises.push(ret.catch((e) =>
console.error(`Handling of event '${name}' failed in a React listener with error`, e)));
}
}
}
// Handle legacy children.
for (const child of this.children) {
const ret = child.handleEvent(name, data) as Promise<void>;
if (ret) {
promises.push(ret);
}
}
// don't create promises if not needed (optimization)
return promises.length > 0 ? Promise.all(promises) : null;
}
triggerCommand<K extends CommandNames>(name: K, data?: CommandMappings[K]): Promise<unknown> | undefined | null {
const fun = (this as any)[`${name}Command`];
if (fun) {
return this.callMethod(fun, data);
} else if (this.parent) {
return this.parent.triggerCommand(name, data);
}
}
callMethod(fun: (arg: unknown) => Promise<unknown>, data: unknown) {
if (typeof fun !== "function") {
return;
}
const startTime = Date.now();
const promise = fun.call(this, data);
const took = Date.now() - startTime;
if (glob.isDev && took > 20) {
// measuring only sync handlers
console.log(`Call to ${fun.name} in ${this.componentId} took ${took}ms`);
}
if (glob.isDev && promise) {
return utils.timeLimit(promise, 20000, `Time limit failed on ${this.constructor.name} with ${fun.name}`);
}
return promise;
}
registerHandler<T extends EventNames>(name: T, handler: EventHandler) {
if (!this.listeners) {
this.listeners = {};
}
if (!this.listeners[name]) {
this.listeners[name] = new Set();
}
this.listeners[name].add(handler);
}
removeHandler<T extends EventNames>(name: T, handler: EventHandler) {
const listeners = this.listeners?.[name];
if (!listeners) {
return;
}
listeners.delete(handler);
if (!listeners.size) {
delete this.listeners?.[name];
}
}
}
export default class Component extends TypedComponent<Component> {}