@real1ty-obsidian-plugins/utils 2.14.0 → 2.16.0

package/src/core/indexer.ts

@@ -0,0 +1,353 @@
+import { type App, type MetadataCache, type TAbstractFile, TFile, type Vault } from "obsidian";
+import {
+	type BehaviorSubject,
+	from,
+	fromEventPattern,
+	lastValueFrom,
+	merge,
+	type Observable,
+	of,
+	BehaviorSubject as RxBehaviorSubject,
+	Subject,
+	type Subscription,
+} from "rxjs";
+import { debounceTime, filter, groupBy, map, mergeMap, switchMap, toArray } from "rxjs/operators";
+import { isFileInConfiguredDirectory } from "../file/file";
+import { compareFrontmatter, type FrontmatterDiff } from "../file/frontmatter-diff";
+
+/**
+ * Generic frontmatter object type for indexer
+ */
+export type IndexerFrontmatter = Record<string, unknown>;
+
+/**
+ * Configuration for the generic indexer
+ */
+export interface IndexerConfig {
+	/**
+	 * Directory to scan for files (e.g., "Calendar", "Notes")
+	 * If empty string or undefined, scans entire vault
+	 */
+	directory?: string;
+
+	/**
+	 * Properties to exclude when comparing frontmatter diffs
+	 */
+	excludedDiffProps?: Set<string>;
+
+	/**
+	 * Concurrency limit for file scanning operations
+	 */
+	scanConcurrency?: number;
+
+	/**
+	 * Debounce time in milliseconds for file change events
+	 */
+	debounceMs?: number;
+}
+
+/**
+ * Raw file source with frontmatter and metadata
+ */
+export interface FileSource {
+	filePath: string;
+	mtime: number;
+	frontmatter: IndexerFrontmatter;
+	folder: string;
+}
+
+/**
+ * Types of indexer events
+ */
+export type IndexerEventType = "file-changed" | "file-deleted";
+
+/**
+ * Generic indexer event
+ */
+export interface IndexerEvent {
+	type: IndexerEventType;
+	filePath: string;
+	oldPath?: string;
+	source?: FileSource;
+	oldFrontmatter?: IndexerFrontmatter;
+	frontmatterDiff?: FrontmatterDiff;
+}
+
+type VaultEvent = "create" | "modify" | "delete" | "rename";
+
+type FileIntent =
+	| { kind: "changed"; file: TFile; path: string; oldPath?: string }
+	| { kind: "deleted"; path: string };
+
+/**
+ * Generic indexer that listens to Obsidian vault events and emits
+ * RxJS observables with frontmatter diffs and metadata.
+ *
+ * This indexer is framework-agnostic and can be used by any plugin
+ * that needs to track file changes with frontmatter.
+ */
+export class Indexer {
+	private config: Required<IndexerConfig>;
+	private fileSub: Subscription | null = null;
+	private configSubscription: Subscription | null = null;
+	private vault: Vault;
+	private metadataCache: MetadataCache;
+	private scanEventsSubject = new Subject<IndexerEvent>();
+	private indexingCompleteSubject = new RxBehaviorSubject<boolean>(false);
+	private frontmatterCache: Map<string, IndexerFrontmatter> = new Map();
+
+	public readonly events$: Observable<IndexerEvent>;
+	public readonly indexingComplete$: Observable<boolean>;
+
+	constructor(_app: App, configStore: BehaviorSubject<IndexerConfig>) {
+		this.vault = _app.vault;
+		this.metadataCache = _app.metadataCache;
+
+		// Set defaults
+		this.config = {
+			directory: configStore.value.directory || "",
+			excludedDiffProps: configStore.value.excludedDiffProps || new Set(),
+			scanConcurrency: configStore.value.scanConcurrency || 10,
+			debounceMs: configStore.value.debounceMs || 100,
+		};
+
+		// Subscribe to config changes
+		this.configSubscription = configStore.subscribe((newConfig) => {
+			const directoryChanged = this.config.directory !== (newConfig.directory || "");
+
+			this.config = {
+				directory: newConfig.directory || "",
+				excludedDiffProps: newConfig.excludedDiffProps || new Set(),
+				scanConcurrency: newConfig.scanConcurrency || 10,
+				debounceMs: newConfig.debounceMs || 100,
+			};
+
+			// Rescan if directory changed
+			if (directoryChanged) {
+				this.indexingCompleteSubject.next(false);
+				void this.scanAllFiles();
+			}
+		});
+
+		this.events$ = this.scanEventsSubject.asObservable();
+		this.indexingComplete$ = this.indexingCompleteSubject.asObservable();
+	}
+
+	/**
+	 * Start the indexer and perform initial scan
+	 */
+	async start(): Promise<void> {
+		this.indexingCompleteSubject.next(false);
+
+		const fileSystemEvents$ = this.buildFileSystemEvents$();
+
+		this.fileSub = fileSystemEvents$.subscribe((event) => {
+			this.scanEventsSubject.next(event);
+		});
+
+		await this.scanAllFiles();
+	}
+
+	/**
+	 * Stop the indexer and clean up subscriptions
+	 */
+	stop(): void {
+		this.fileSub?.unsubscribe();
+		this.fileSub = null;
+		this.configSubscription?.unsubscribe();
+		this.configSubscription = null;
+		this.indexingCompleteSubject.complete();
+	}
+
+	/**
+	 * Clear cache and rescan all files
+	 */
+	resync(): void {
+		this.frontmatterCache.clear();
+		this.indexingCompleteSubject.next(false);
+		void this.scanAllFiles();
+	}
+
+	/**
+	 * Scan all markdown files in the configured directory
+	 */
+	private async scanAllFiles(): Promise<void> {
+		const allFiles = this.vault.getMarkdownFiles();
+		const relevantFiles = allFiles.filter((file) => this.isRelevantFile(file));
+
+		const events$ = from(relevantFiles).pipe(
+			mergeMap(async (file) => {
+				try {
+					return await this.buildEvent(file);
+				} catch (error) {
+					console.error(`Error processing file ${file.path}:`, error);
+					return null;
+				}
+			}, this.config.scanConcurrency),
+			filter((event): event is IndexerEvent => event !== null),
+			toArray()
+		);
+
+		try {
+			const allEvents = await lastValueFrom(events$);
+
+			for (const event of allEvents) {
+				this.scanEventsSubject.next(event);
+			}
+
+			this.indexingCompleteSubject.next(true);
+		} catch (error) {
+			console.error("❌ Error during file scanning:", error);
+			this.indexingCompleteSubject.next(true);
+		}
+	}
+
+	/**
+	 * Create an observable from a vault event
+	 */
+	private fromVaultEvent(eventName: VaultEvent): Observable<TAbstractFile> {
+		if (eventName === "create") {
+			return fromEventPattern<TAbstractFile>(
+				(handler) => this.vault.on("create", handler),
+				(handler) => this.vault.off("create", handler)
+			);
+		}
+
+		if (eventName === "modify") {
+			return fromEventPattern<TAbstractFile>(
+				(handler) => this.vault.on("modify", handler),
+				(handler) => this.vault.off("modify", handler)
+			);
+		}
+
+		if (eventName === "delete") {
+			return fromEventPattern<TAbstractFile>(
+				(handler) => this.vault.on("delete", handler),
+				(handler) => this.vault.off("delete", handler)
+			);
+		}
+
+		// eventName === "rename"
+		return fromEventPattern<[TAbstractFile, string]>(
+			(handler) => this.vault.on("rename", handler),
+			(handler) => this.vault.off("rename", handler)
+		).pipe(map(([file]) => file));
+	}
+
+	/**
+	 * Type guard to check if file is a markdown file
+	 */
+	private static isMarkdownFile(f: TAbstractFile): f is TFile {
+		return f instanceof TFile && f.extension === "md";
+	}
+
+	/**
+	 * Filter to only relevant markdown files in configured directory
+	 */
+	private toRelevantFiles<T extends TAbstractFile>() {
+		return (source: Observable<T>) =>
+			source.pipe(
+				filter((f: TAbstractFile): f is TFile => Indexer.isMarkdownFile(f)),
+				filter((f) => this.isRelevantFile(f))
+			);
+	}
+
+	/**
+	 * Debounce events by file path
+	 */
+	private debounceByPath<T>(ms: number, key: (x: T) => string) {
+		return (source: Observable<T>) =>
+			source.pipe(
+				groupBy(key),
+				mergeMap((g$) => g$.pipe(debounceTime(ms)))
+			);
+	}
+
+	/**
+	 * Build the file system events observable stream
+	 */
+	private buildFileSystemEvents$(): Observable<IndexerEvent> {
+		const created$ = this.fromVaultEvent("create").pipe(this.toRelevantFiles());
+		const modified$ = this.fromVaultEvent("modify").pipe(this.toRelevantFiles());
+		const deleted$ = this.fromVaultEvent("delete").pipe(this.toRelevantFiles());
+
+		const renamed$ = fromEventPattern<[TAbstractFile, string]>(
+			(handler) => this.vault.on("rename", handler),
+			(handler) => this.vault.off("rename", handler)
+		);
+
+		const changedIntents$ = merge(created$, modified$).pipe(
+			this.debounceByPath(this.config.debounceMs, (f) => f.path),
+			map((file): FileIntent => ({ kind: "changed", file, path: file.path }))
+		);
+
+		const deletedIntents$ = deleted$.pipe(
+			map((file): FileIntent => ({ kind: "deleted", path: file.path }))
+		);
+
+		const renamedIntents$ = renamed$.pipe(
+			map(([f, oldPath]) => [f, oldPath] as const),
+			filter(([f]) => Indexer.isMarkdownFile(f) && this.isRelevantFile(f)),
+			mergeMap(([f, oldPath]) => [
+				{ kind: "deleted", path: oldPath } as FileIntent,
+				{ kind: "changed", file: f, path: f.path, oldPath } as FileIntent,
+			])
+		);
+
+		const intents$ = merge(changedIntents$, deletedIntents$, renamedIntents$);
+
+		return intents$.pipe(
+			switchMap((intent) => {
+				if (intent.kind === "deleted") {
+					this.frontmatterCache.delete(intent.path);
+					return of<IndexerEvent>({ type: "file-deleted", filePath: intent.path });
+				}
+
+				return from(this.buildEvent(intent.file, intent.oldPath)).pipe(
+					filter((e): e is IndexerEvent => e !== null)
+				);
+			})
+		);
+	}
+
+	/**
+	 * Build an indexer event from a file
+	 */
+	private async buildEvent(file: TFile, oldPath?: string): Promise<IndexerEvent | null> {
+		const cache = this.metadataCache.getFileCache(file);
+		if (!cache || !cache.frontmatter) return null;
+
+		const { frontmatter } = cache;
+		const oldFrontmatter = this.frontmatterCache.get(file.path);
+
+		const source: FileSource = {
+			filePath: file.path,
+			mtime: file.stat.mtime,
+			frontmatter,
+			folder: file.parent?.path || "",
+		};
+
+		const event: IndexerEvent = {
+			type: "file-changed",
+			filePath: file.path,
+			oldPath,
+			source,
+			oldFrontmatter,
+			frontmatterDiff: oldFrontmatter
+				? compareFrontmatter(oldFrontmatter, frontmatter, this.config.excludedDiffProps)
+				: undefined,
+		};
+
+		// Update cache
+		this.frontmatterCache.set(file.path, { ...frontmatter });
+
+		return event;
+	}
+
+	/**
+	 * Check if file is in the configured directory
+	 */
+	private isRelevantFile(file: TFile): boolean {
+		return isFileInConfiguredDirectory(file.path, this.config.directory);
+	}
+}

package/src/file/frontmatter-diff.ts

@@ -0,0 +1,198 @@
+export type Frontmatter = Record<string, unknown>;
+
+export interface FrontmatterChange {
+	key: string;
+	oldValue: unknown;
+	newValue: unknown;
+	changeType: "added" | "modified" | "deleted";
+}
+
+export interface FrontmatterDiff {
+	hasChanges: boolean;
+	changes: FrontmatterChange[];
+	added: FrontmatterChange[];
+	modified: FrontmatterChange[];
+	deleted: FrontmatterChange[];
+}
+
+/**
+ * Compares two frontmatter objects and returns a detailed diff.
+ * Excludes specified properties from comparison (e.g., Prisma-managed properties).
+ *
+ * @param oldFrontmatter - The original frontmatter
+ * @param newFrontmatter - The updated frontmatter
+ * @param excludeProps - Set of property keys to exclude from comparison
+ * @returns Detailed diff with categorized changes
+ */
+export function compareFrontmatter(
+	oldFrontmatter: Frontmatter,
+	newFrontmatter: Frontmatter,
+	excludeProps: Set<string> = new Set()
+): FrontmatterDiff {
+	const changes: FrontmatterChange[] = [];
+	const added: FrontmatterChange[] = [];
+	const modified: FrontmatterChange[] = [];
+	const deleted: FrontmatterChange[] = [];
+
+	const allKeys = new Set([...Object.keys(oldFrontmatter), ...Object.keys(newFrontmatter)]);
+
+	for (const key of allKeys) {
+		if (excludeProps.has(key)) {
+			continue;
+		}
+
+		const oldValue = oldFrontmatter[key];
+		const newValue = newFrontmatter[key];
+
+		if (!(key in oldFrontmatter) && key in newFrontmatter) {
+			const change: FrontmatterChange = {
+				key,
+				oldValue: undefined,
+				newValue,
+				changeType: "added",
+			};
+
+			changes.push(change);
+			added.push(change);
+		} else if (key in oldFrontmatter && !(key in newFrontmatter)) {
+			const change: FrontmatterChange = {
+				key,
+				oldValue,
+				newValue: undefined,
+				changeType: "deleted",
+			};
+
+			changes.push(change);
+			deleted.push(change);
+		} else if (!deepEqual(oldValue, newValue)) {
+			const change: FrontmatterChange = {
+				key,
+				oldValue,
+				newValue,
+				changeType: "modified",
+			};
+
+			changes.push(change);
+			modified.push(change);
+		}
+	}
+
+	return {
+		hasChanges: changes.length > 0,
+		changes,
+		added,
+		modified,
+		deleted,
+	};
+}
+
+/**
+ * Deep equality check for frontmatter values.
+ * Handles primitives, arrays, and objects.
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+
+	if (a === null || b === null || a === undefined || b === undefined) {
+		return a === b;
+	}
+
+	if (typeof a !== typeof b) return false;
+
+	if (Array.isArray(a) && Array.isArray(b)) {
+		if (a.length !== b.length) return false;
+		return a.every((val, idx) => deepEqual(val, b[idx]));
+	}
+
+	if (typeof a === "object" && typeof b === "object") {
+		const keysA = Object.keys(a as Record<string, unknown>);
+		const keysB = Object.keys(b as Record<string, unknown>);
+
+		if (keysA.length !== keysB.length) return false;
+
+		return keysA.every((key) =>
+			deepEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])
+		);
+	}
+
+	return false;
+}
+
+/**
+ * Merges multiple frontmatter diffs into a single accumulated diff.
+ * Later diffs override earlier ones for the same key.
+ *
+ * @param diffs - Array of diffs to merge (in chronological order)
+ * @returns A single merged diff containing all accumulated changes
+ */
+export function mergeFrontmatterDiffs(diffs: FrontmatterDiff[]): FrontmatterDiff {
+	if (diffs.length === 0) {
+		return {
+			hasChanges: false,
+			changes: [],
+			added: [],
+			modified: [],
+			deleted: [],
+		};
+	}
+
+	if (diffs.length === 1) {
+		return diffs[0];
+	}
+
+	const changesByKey = new Map<string, FrontmatterChange>();
+
+	for (const diff of diffs) {
+		for (const change of diff.changes) {
+			const existing = changesByKey.get(change.key);
+
+			if (!existing) {
+				changesByKey.set(change.key, { ...change });
+			} else {
+				existing.newValue = change.newValue;
+				existing.changeType = change.changeType;
+
+				if (existing.oldValue === change.newValue) {
+					changesByKey.delete(change.key);
+				}
+			}
+		}
+	}
+
+	const allChanges = Array.from(changesByKey.values());
+	const added = allChanges.filter((c) => c.changeType === "added");
+	const modified = allChanges.filter((c) => c.changeType === "modified");
+	const deleted = allChanges.filter((c) => c.changeType === "deleted");
+
+	return {
+		hasChanges: allChanges.length > 0,
+		changes: allChanges,
+		added,
+		modified,
+		deleted,
+	};
+}
+
+/**
+ * Formats a frontmatter change for display in a modal.
+ * Returns a human-readable string describing the change.
+ */
+export function formatChangeForDisplay(change: FrontmatterChange): string {
+	const formatValue = (value: unknown): string => {
+		if (value === undefined) return "(not set)";
+		if (value === null) return "null";
+		if (typeof value === "string") return `"${value}"`;
+		if (typeof value === "object") return JSON.stringify(value);
+		if (typeof value === "number" || typeof value === "boolean") return String(value);
+		return JSON.stringify(value);
+	};
+
+	switch (change.changeType) {
+		case "added":
+			return `+ ${change.key}: ${formatValue(change.newValue)}`;
+		case "deleted":
+			return `- ${change.key}: ${formatValue(change.oldValue)}`;
+		case "modified":
+			return `~ ${change.key}: ${formatValue(change.oldValue)} → ${formatValue(change.newValue)}`;
+	}
+}

package/src/file/frontmatter-propagation.ts

@@ -0,0 +1,59 @@
+import type { App } from "obsidian";
+import { TFile } from "obsidian";
+import type { Frontmatter, FrontmatterDiff } from "./frontmatter-diff";
+
+export interface NexusPropertiesSettings {
+	excludedPropagatedProps?: string;
+	parentProp: string;
+	childrenProp: string;
+	relatedProp: string;
+	zettelIdProp: string;
+}
+
+export function parseExcludedProps(settings: NexusPropertiesSettings): Set<string> {
+	const excludedPropsStr = settings.excludedPropagatedProps || "";
+	const userExcluded = excludedPropsStr
+		.split(",")
+		.map((prop) => prop.trim())
+		.filter((prop) => prop.length > 0);
+
+	const alwaysExcluded = [
+		settings.parentProp,
+		settings.childrenProp,
+		settings.relatedProp,
+		settings.zettelIdProp,
+	];
+
+	return new Set([...alwaysExcluded, ...userExcluded]);
+}
+
+export async function applyFrontmatterChanges(
+	app: App,
+	targetPath: string,
+	sourceFrontmatter: Frontmatter,
+	diff: FrontmatterDiff
+): Promise<void> {
+	try {
+		const file = app.vault.getAbstractFileByPath(targetPath);
+		if (!(file instanceof TFile)) {
+			console.warn(`Target file not found: ${targetPath}`);
+			return;
+		}
+
+		await app.fileManager.processFrontMatter(file, (fm) => {
+			for (const change of diff.added) {
+				fm[change.key] = sourceFrontmatter[change.key];
+			}
+
+			for (const change of diff.modified) {
+				fm[change.key] = sourceFrontmatter[change.key];
+			}
+
+			for (const change of diff.deleted) {
+				delete fm[change.key];
+			}
+		});
+	} catch (error) {
+		console.error(`Error applying frontmatter changes to ${targetPath}:`, error);
+	}
+}

package/src/file/index.ts

@@ -3,6 +3,8 @@ export * from "./file";
 export * from "./file-operations";
 export * from "./file-utils";
 export * from "./frontmatter";
+export * from "./frontmatter-diff";
+export * from "./frontmatter-propagation";
 export * from "./link-parser";
 export * from "./property-utils";
 export * from "./templater";

package/src/file/templater.ts

@@ -1,4 +1,4 @@
-import { type App, Notice, normalizePath, type TFile } from "obsidian";
+import { type App, Notice, normalizePath, TFile } from "obsidian";
 
 const TEMPLATER_ID = "templater-obsidian";
 
@@ -13,6 +13,16 @@ interface TemplaterLike {
 	create_new_note_from_template: CreateFn;
 }
 
+export interface FileCreationOptions {
+	title: string;
+	targetDirectory: string;
+	filename?: string;
+	content?: string;
+	frontmatter?: Record<string, unknown>;
+	templatePath?: string;
+	useTemplater?: boolean;
+}
+
 async function waitForTemplater(app: App, timeoutMs = 8000): Promise<TemplaterLike | null> {
 	await new Promise<void>((resolve) => app.workspace.onLayoutReady(resolve));
 
@@ -73,3 +83,49 @@ export async function createFromTemplate(
 		return null;
 	}
 }
+
+export async function createFileWithTemplate(
+	app: App,
+	options: FileCreationOptions
+): Promise<TFile> {
+	const { title, targetDirectory, filename, content, frontmatter, templatePath, useTemplater } =
+		options;
+
+	const finalFilename = filename || title;
+	const baseName = finalFilename.replace(/\.md$/, "");
+	const filePath = normalizePath(`${targetDirectory}/${baseName}.md`);
+
+	const existingFile = app.vault.getAbstractFileByPath(filePath);
+	if (existingFile instanceof TFile) {
+		return existingFile;
+	}
+
+	if (useTemplater && templatePath && templatePath.trim() !== "" && isTemplaterAvailable(app)) {
+		const templateFile = await createFromTemplate(
+			app,
+			templatePath,
+			targetDirectory,
+			finalFilename
+		);
+
+		if (templateFile) {
+			if (frontmatter && Object.keys(frontmatter).length > 0) {
+				await app.fileManager.processFrontMatter(templateFile, (fm) => {
+					Object.assign(fm, frontmatter);
+				});
+			}
+			return templateFile;
+		}
+	}
+
+	const fileContent = content || "";
+	const file = await app.vault.create(filePath, fileContent);
+
+	if (frontmatter && Object.keys(frontmatter).length > 0) {
+		await app.fileManager.processFrontMatter(file, (fm) => {
+			Object.assign(fm, frontmatter);
+		});
+	}
+
+	return file;
+}