Trigger metadata events for Obsidian Canvas files

obsidian-canvas-metadata.ts

/**
This snippet was originally a part of PDF++ v1 (which is under development and not public yet).
https://github.com/RyotaUshio/obsidian-pdf-plus
 
Obsidian internally indexes Canvas files, but does not emit any events when metadata change.
Calling the `patchCanvasIndex` function allows you to listen to the `canvas-index-initialized`
and `canvas-index-changed` events.

The signatures are:
on(evt: 'canvas-index-changed', callback: (file: TFile, cache: CanvasCachedMetadata | null) => any, context?: any): EventRef;
on(evt: 'canvas-index-initialized', callback: () => any, context?: any): EventRef;

---

MIT License
Copyright (c) 2025 Ryota Ushio

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/

import { App, CachedMetadata, Component, Events, Plugin, Reference, TFile } from 'obsidian';
import { around } from 'monkey-around';


/**
 * Patch the `CanvasIndex` to emit events when the index is changed or initialized.
 * @param plugin Your plugin instance.
 * @param events The `Events` instance to emit events on. It can be a built-in one like `MetadataCache`, 
 * but I recommend using your own one to avoid conflicts.
 */
export const patchCanvasIndex = (plugin: Plugin, events: Events) => {
    const app = plugin.app;
    const index = app.internalPlugins.plugins.canvas.instance.index;

    if (isIndexInitialized(index)) {
        registerCanvasIndexChanged(plugin, index, events);
    } else {
        const uninstaller = around(index.constructor.prototype, {
            run(old) {
                return async function (this: CanvasIndex) {
                    await old.call(this);
                    if (isIndexInitialized(this)) {
                        uninstaller();
                        events.trigger('canvas-index-initialized');
                        registerCanvasIndexChanged(plugin, this, events);
                    }
                };
            },
        });
    }
};

const isIndexInitialized = (index: CanvasIndex) => {
    return index._loaded && index.frame === null && index.fileQueue.length === 0;
};

const registerCanvasIndexChanged = (plugin: Plugin, index: CanvasIndex, events: Events) => {
    plugin.register(around(index.constructor.prototype, {
        process(old) {
            return async function (this: CanvasIndex, file: TFile) {
                const cache = await old.call(this, file);
                events.trigger('canvas-index-changed', file, cache);
                return cache;
            };
        },
    }));
};

// Type augmentation

declare class InternalPlugin<Instance> extends Events {
    instance: Instance;
    enabled: boolean;
    enable(): Promise<void>;
    disable(): void;
}


interface CanvasPlugin {
    index: CanvasIndex;
}

declare module 'obsidian' {
    interface App {
        internalPlugins: {
            plugins: {
                'canvas': InternalPlugin<CanvasPlugin>;
            }
        };
    }

    interface Component {
        _loaded: boolean;
    }
}

declare abstract class FileIndex<Metadata> extends Component {
    app: App;
    /** Internal map from a file path to the corresponding metadata. No metadata will be created for an empty canvas. */
    index: Record<string, Metadata>;
    fileQueue: Array<TFile>;
    frame: object | null;

    getAll(): typeof this.index;
    /** Note that it returns `null` for an empty canvas. */
    getForPath(path: string): Metadata | null;
    /** Note that it returns `null` for an empty canvas. */
    get(file: TFile): Metadata | null;

    abstract canProcess(file: TFile): boolean;
    abstract process(file: TFile): Promise<Metadata | null>;

    onCreate(file: TFile): void;
    onModify(file: TFile): void;
    onRename(file: TFile, oldPath: string): void;
    onDelete(file: TFile): void;
    queue(file: TFile): void;
    run(): Promise<void>;
}

declare class CanvasIndex extends FileIndex<CanvasCachedMetadata> {
    /** WeakMap from a reference to the ID of the node contains the reference. */
    refNodeIds: WeakMap<Reference, string>;
    canProcess(file: TFile): boolean;
    process(file: TFile): Promise<CanvasCachedMetadata | null>;
    parseText(text: string): Promise<CachedMetadata>;
}

/** No metadata ara available for group nodes without background and link nodes. */
interface CanvasCachedMetadata {
    /** Metadata for file nodes, or group nodes with background */
    embeds: Array<{ file: string, subpath?: string }>;
    /** Cached metadata for text nodes. Each key is a node id. */
    caches: Record<string, CachedMetadata>;
}