@real1ty-obsidian-plugins/utils 2.3.0 → 2.5.0

package/src/async/async.ts

@@ -0,0 +1,117 @@
+/**
+ * Creates a function that ensures an async operation runs only once,
+ * returning the same promise for concurrent calls.
+ *
+ * Useful for initialization patterns where you want to ensure
+ * expensive async operations (like indexing, API calls, etc.)
+ * only happen once even if called multiple times.
+ *
+ * @param fn The async function to memoize
+ * @returns A function that returns the same promise on subsequent calls
+ *
+ * @example
+ * ```typescript
+ * const initializeOnce = onceAsync(async () => {
+ *   await heavyInitialization();
+ *   console.log("Initialized!");
+ * });
+ *
+ * // All these calls will share the same promise
+ * await initializeOnce();
+ * await initializeOnce(); // Won't run again
+ * await initializeOnce(); // Won't run again
+ * ```
+ */
+export function onceAsync<T>(fn: () => Promise<T>): () => Promise<T> {
+	let promise: Promise<T> | null = null;
+
+	return () => {
+		if (!promise) {
+			try {
+				promise = fn();
+			} catch (error) {
+				// Convert synchronous errors to rejected promises
+				promise = Promise.reject(error);
+			}
+		}
+		return promise;
+	};
+}
+
+/**
+ * Creates a function that ensures an async operation runs only once per key,
+ * useful for caching expensive operations with different parameters.
+ *
+ * @param fn The async function to memoize
+ * @returns A function that memoizes results by key
+ *
+ * @example
+ * ```typescript
+ * const fetchUserOnce = onceAsyncKeyed(async (userId: string) => {
+ *   return await api.getUser(userId);
+ * });
+ *
+ * // Each unique userId will only be fetched once
+ * await fetchUserOnce("user1");
+ * await fetchUserOnce("user1"); // Returns cached promise
+ * await fetchUserOnce("user2"); // New fetch for different key
+ * ```
+ */
+export function onceAsyncKeyed<TArgs extends readonly unknown[], TReturn>(
+	fn: (...args: TArgs) => Promise<TReturn>
+): (...args: TArgs) => Promise<TReturn> {
+	const cache = new Map<string, Promise<TReturn>>();
+
+	return (...args: TArgs) => {
+		const key = JSON.stringify(args);
+
+		if (!cache.has(key)) {
+			cache.set(key, fn(...args));
+		}
+
+		return cache.get(key)!;
+	};
+}
+
+/**
+ * Creates a resettable version of onceAsync that can be cleared and re-run.
+ *
+ * @param fn The async function to memoize
+ * @returns Object with execute and reset methods
+ *
+ * @example
+ * ```typescript
+ * const { execute: initialize, reset } = onceAsyncResettable(async () => {
+ *   await heavyInitialization();
+ * });
+ *
+ * await initialize(); // Runs
+ * await initialize(); // Cached
+ *
+ * reset(); // Clear cache
+ * await initialize(); // Runs again
+ * ```
+ */
+export function onceAsyncResettable<T>(fn: () => Promise<T>): {
+	execute: () => Promise<T>;
+	reset: () => void;
+} {
+	let promise: Promise<T> | null = null;
+
+	return {
+		execute: () => {
+			if (!promise) {
+				try {
+					promise = fn();
+				} catch (error) {
+					// Convert synchronous errors to rejected promises
+					promise = Promise.reject(error);
+				}
+			}
+			return promise;
+		},
+		reset: () => {
+			promise = null;
+		},
+	};
+}

package/src/async/batch-operations.ts

@@ -0,0 +1,53 @@
+import { Notice } from "obsidian";
+
+export interface BatchOperationOptions {
+	closeAfter?: boolean;
+	callOnComplete?: boolean;
+}
+
+export interface BatchOperationResult {
+	successCount: number;
+	errorCount: number;
+}
+
+export async function runBatchOperation<T>(
+	items: T[],
+	operationLabel: string,
+	handler: (item: T) => Promise<void>,
+	showResult: boolean = true
+): Promise<BatchOperationResult> {
+	let successCount = 0;
+	let errorCount = 0;
+
+	for (const item of items) {
+		try {
+			await handler(item);
+			successCount++;
+		} catch (error) {
+			console.error(`${operationLabel}: error processing item:`, error);
+			errorCount++;
+		}
+	}
+
+	if (showResult) {
+		showBatchOperationResult(operationLabel, successCount, errorCount);
+	}
+
+	return { successCount, errorCount };
+}
+
+export function showBatchOperationResult(
+	operation: string,
+	successCount: number,
+	errorCount: number
+): void {
+	if (errorCount === 0) {
+		new Notice(
+			`${operation}: ${successCount} item${successCount === 1 ? "" : "s"} processed successfully`
+		);
+	} else {
+		new Notice(
+			`${operation}: ${successCount} succeeded, ${errorCount} failed. Check console for details.`
+		);
+	}
+}

package/src/async/index.ts

@@ -0,0 +1,2 @@
+export * from "./async";
+export * from "./batch-operations";

package/src/core/evaluator/base.ts

@@ -0,0 +1,71 @@
+import type { BehaviorSubject, Subscription } from "rxjs";
+
+import { buildPropertyMapping, sanitizeExpression } from "../expression-utils";
+
+export interface BaseRule {
+	id: string;
+	expression: string;
+	enabled: boolean;
+}
+
+/**
+ * Generic base class for evaluating JavaScript expressions against frontmatter objects.
+ * Provides reactive compilation of rules via RxJS subscription and safe evaluation.
+ */
+export abstract class BaseEvaluator<TRule extends BaseRule, TSettings> {
+	protected rules: TRule[] = [];
+	private compiledFunctions = new Map<string, ((...args: any[]) => boolean) | null>();
+	private propertyMapping = new Map<string, string>();
+	private subscription: Subscription | null = null;
+
+	constructor(settingsStore: BehaviorSubject<TSettings>) {
+		this.subscription = settingsStore.subscribe((settings) => {
+			this.rules = this.extractRules(settings);
+			this.compiledFunctions.clear();
+			this.propertyMapping.clear();
+		});
+	}
+
+	protected abstract extractRules(settings: TSettings): TRule[];
+
+	destroy(): void {
+		this.subscription?.unsubscribe();
+		this.compiledFunctions.clear();
+		this.propertyMapping.clear();
+	}
+
+	protected evaluateRule(rule: TRule, frontmatter: Record<string, unknown>): boolean {
+		if (!rule.enabled || !rule.expression) {
+			return false;
+		}
+
+		try {
+			if (this.propertyMapping.size === 0) {
+				this.propertyMapping = buildPropertyMapping(Object.keys(frontmatter));
+			}
+
+			let compiledFunc = this.compiledFunctions.get(rule.id);
+
+			if (!compiledFunc) {
+				const sanitized = sanitizeExpression(rule.expression, this.propertyMapping);
+				const params = Array.from(this.propertyMapping.values());
+				compiledFunc = new Function(...params, `"use strict"; return ${sanitized};`) as (
+					...args: any[]
+				) => boolean;
+				this.compiledFunctions.set(rule.id, compiledFunc);
+			}
+
+			const values = Array.from(this.propertyMapping.keys()).map((key) => frontmatter[key]);
+			const result = compiledFunc(...values);
+
+			return result === true;
+		} catch (error) {
+			console.warn(`Invalid expression (${rule.id}):`, rule.expression, error);
+			return false;
+		}
+	}
+
+	protected isTruthy(value: any): boolean {
+		return value === true;
+	}
+}

package/src/core/evaluator/color.ts

@@ -0,0 +1,37 @@
+import type { BehaviorSubject } from "rxjs";
+
+import { BaseEvaluator, type BaseRule } from "./base";
+
+export interface ColorRule extends BaseRule {
+	color: string;
+}
+
+/**
+ * Generic evaluator for determining colors based on frontmatter rules.
+ * Extends BaseEvaluator to evaluate color rules against frontmatter.
+ */
+export class ColorEvaluator<
+	TSettings extends { defaultNodeColor: string; colorRules: ColorRule[] },
+> extends BaseEvaluator<ColorRule, TSettings> {
+	private defaultColor: string;
+
+	constructor(settingsStore: BehaviorSubject<TSettings>) {
+		super(settingsStore);
+		this.defaultColor = settingsStore.value.defaultNodeColor;
+
+		settingsStore.subscribe((settings) => {
+			if (settings.defaultNodeColor) {
+				this.defaultColor = settings.defaultNodeColor;
+			}
+		});
+	}
+
+	protected extractRules(settings: TSettings): ColorRule[] {
+		return settings.colorRules;
+	}
+
+	evaluateColor(frontmatter: Record<string, unknown>): string {
+		const match = this.rules.find((rule) => this.isTruthy(this.evaluateRule(rule, frontmatter)));
+		return match?.color ?? this.defaultColor;
+	}
+}

package/src/core/evaluator/excluded.ts

@@ -0,0 +1,63 @@
+import type { BehaviorSubject } from "rxjs";
+
+export interface PathExcludedProperties {
+	id: string;
+	path: string;
+	excludedProperties: string[];
+	enabled: boolean;
+}
+
+/**
+ * Generic evaluator for determining which frontmatter properties to exclude when creating new nodes.
+ *
+ * Logic:
+ * 1. ALWAYS includes the default excluded properties (e.g., Parent, Child, Related, _ZettelID)
+ * 2. Checks if the source file's path matches any path-based exclusion rules
+ * 3. First matching path rule's properties are ADDED to the default exclusion list
+ * 4. Returns the combined set of excluded properties
+ */
+export class ExcludedPropertiesEvaluator<
+	TSettings extends {
+		defaultExcludedProperties: string[];
+		pathExcludedProperties: PathExcludedProperties[];
+	},
+> {
+	private defaultExcludedProperties: string[];
+
+	private pathRules: PathExcludedProperties[];
+
+	constructor(settingsObservable: BehaviorSubject<TSettings>) {
+		const assignSettings = (settings: TSettings) => {
+			this.defaultExcludedProperties = settings.defaultExcludedProperties;
+			this.pathRules = settings.pathExcludedProperties.filter((rule) => rule.enabled);
+		};
+
+		assignSettings(settingsObservable.value);
+		settingsObservable.subscribe(assignSettings);
+	}
+
+	/**
+	 * Evaluate which properties should be excluded for a given file path.
+	 *
+	 * @param filePath - The file path to match against path rules
+	 * @returns Array of property names to exclude (always includes defaults + path rule matches)
+	 */
+	evaluateExcludedProperties(filePath: string): string[] {
+		// Always start with default excluded properties
+		const excludedProperties = [...this.defaultExcludedProperties];
+
+		// Find first matching path rule and add its excluded properties
+		const match = this.pathRules.find((rule) => filePath.startsWith(rule.path));
+
+		if (match) {
+			// Add path-specific excluded properties to the defaults
+			for (const prop of match.excludedProperties) {
+				if (!excludedProperties.includes(prop)) {
+					excludedProperties.push(prop);
+				}
+			}
+		}
+
+		return excludedProperties;
+	}
+}

package/src/core/evaluator/filter.ts

@@ -0,0 +1,35 @@
+import type { BehaviorSubject } from "rxjs";
+
+import { BaseEvaluator, type BaseRule } from "./base";
+
+export interface FilterRule extends BaseRule {}
+
+/**
+ * Generic evaluator for filtering based on frontmatter expressions.
+ * Extends BaseEvaluator to evaluate filter rules against frontmatter.
+ * Returns true only if ALL rules evaluate to true.
+ */
+export class FilterEvaluator<
+	TSettings extends { filterExpressions: string[] },
+> extends BaseEvaluator<FilterRule, TSettings> {
+	protected extractRules(settings: TSettings): FilterRule[] {
+		return settings.filterExpressions.map((expression, index) => ({
+			id: `filter-${index}`,
+			expression: expression.trim(),
+			enabled: true,
+		}));
+	}
+
+	evaluateFilters(frontmatter: Record<string, unknown>): boolean {
+		if (this.rules.length === 0) {
+			return true;
+		}
+
+		return this.rules.every((rule) => {
+			if (!rule.enabled || !rule.expression) {
+				return true;
+			}
+			return this.evaluateRule(rule, frontmatter);
+		});
+	}
+}

package/src/core/evaluator/included.ts

@@ -0,0 +1,74 @@
+import type { BehaviorSubject } from "rxjs";
+
+export interface PathIncludedProperties {
+	id: string;
+	path: string;
+	includedProperties: string[];
+	enabled: boolean;
+}
+
+/**
+ * Generic evaluator for determining which properties to include in Bases view columns.
+ *
+ * Logic:
+ * 1. ALWAYS includes the default included properties
+ * 2. Checks if the file's path matches any path-based inclusion rules
+ * 3. First matching path rule's properties are ADDED to the default inclusion list
+ * 4. Returns the combined set of included properties in order:
+ *    - file.name (always first)
+ *    - default included properties (in specified order)
+ *    - path-specific included properties (in specified order)
+ */
+export class IncludedPropertiesEvaluator<
+	TSettings extends {
+		defaultBasesIncludedProperties: string[];
+		pathBasesIncludedProperties: PathIncludedProperties[];
+	},
+> {
+	private defaultIncludedProperties: string[];
+
+	private pathRules: PathIncludedProperties[];
+
+	constructor(settingsObservable: BehaviorSubject<TSettings>) {
+		const assignSettings = (settings: TSettings) => {
+			this.defaultIncludedProperties = settings.defaultBasesIncludedProperties;
+			this.pathRules = settings.pathBasesIncludedProperties.filter((rule) => rule.enabled);
+		};
+
+		assignSettings(settingsObservable.value);
+		settingsObservable.subscribe(assignSettings);
+	}
+
+	/**
+	 * Evaluate which properties should be included in the order array for a given file path.
+	 * Returns an array with "file.name" as the first element, followed by default and path-specific properties.
+	 *
+	 * @param filePath - The file path to match against path rules
+	 * @returns Array of property names to include in the order (file.name + defaults + path rule matches)
+	 */
+	evaluateIncludedProperties(filePath: string): string[] {
+		// Always start with file.name
+		const includedProperties = ["file.name"];
+
+		// Add default included properties
+		for (const prop of this.defaultIncludedProperties) {
+			if (!includedProperties.includes(prop)) {
+				includedProperties.push(prop);
+			}
+		}
+
+		// Find first matching path rule and add its included properties
+		const match = this.pathRules.find((rule) => filePath.startsWith(rule.path));
+
+		if (match) {
+			// Add path-specific included properties to the defaults
+			for (const prop of match.includedProperties) {
+				if (!includedProperties.includes(prop)) {
+					includedProperties.push(prop);
+				}
+			}
+		}
+
+		return includedProperties;
+	}
+}

package/src/core/evaluator/index.ts

@@ -0,0 +1,5 @@
+export * from "./base";
+export * from "./color";
+export * from "./excluded";
+export * from "./filter";
+export * from "./included";

package/src/core/expression-utils.ts

@@ -0,0 +1,53 @@
+/**
+ * Sanitizes a property name for use as a JavaScript function parameter
+ * by replacing spaces and special characters with underscores.
+ * Adds a prefix to avoid conflicts with JavaScript reserved words.
+ */
+export function sanitizePropertyName(name: string): string {
+	const sanitized = name.replace(/[^a-zA-Z0-9_]/g, "_");
+	return `prop_${sanitized}`;
+}
+
+/**
+ * Builds a mapping of original property names to sanitized versions
+ * suitable for use as JavaScript function parameters.
+ */
+export function buildPropertyMapping(properties: string[]): Map<string, string> {
+	const mapping = new Map<string, string>();
+
+	for (const prop of properties) {
+		mapping.set(prop, sanitizePropertyName(prop));
+	}
+
+	return mapping;
+}
+
+/**
+ * Replaces property names in an expression with their sanitized versions.
+ * Sorts by length descending to replace longer property names first and avoid partial matches.
+ */
+export function sanitizeExpression(
+	expression: string,
+	propertyMapping: Map<string, string>
+): string {
+	let sanitized = expression;
+
+	// Sort by length descending to replace longer property names first
+	const sortedEntries = Array.from(propertyMapping.entries()).sort(
+		([a], [b]) => b.length - a.length
+	);
+
+	for (const [original, sanitizedName] of sortedEntries) {
+		if (original !== sanitizedName) {
+			const escaped = original.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+			// Use a regex that matches the property name not preceded or followed by word characters
+			// This allows matching properties with special characters like "My-Property"
+			const regex = new RegExp(`(?<!\\w)${escaped}(?!\\w)`, "g");
+
+			sanitized = sanitized.replace(regex, sanitizedName);
+		}
+	}
+
+	return sanitized;
+}

package/src/core/generate.ts

@@ -0,0 +1,22 @@
+export interface TimestampData {
+	startDate: string;
+	zettelId: number;
+}
+
+export const generateZettelId = (): number => {
+	const currentTimestamp = new Date();
+	const padWithZero = (number: number) => String(number).padStart(2, "0");
+	return Number(
+		`${currentTimestamp.getFullYear()}${padWithZero(currentTimestamp.getMonth() + 1)}${padWithZero(currentTimestamp.getDate())}${padWithZero(currentTimestamp.getHours())}${padWithZero(currentTimestamp.getMinutes())}${padWithZero(currentTimestamp.getSeconds())}`
+	);
+};
+
+export const generateTimestamps = (): TimestampData => {
+	const padWithZero = (number: number): string => String(number).padStart(2, "0");
+	const currentDate = new Date();
+
+	const formattedStartDate: string = `${currentDate.getFullYear()}-${padWithZero(currentDate.getMonth() + 1)}-${padWithZero(currentDate.getDate())}`;
+	const uniqueZettelId: number = generateZettelId();
+
+	return { startDate: formattedStartDate, zettelId: uniqueZettelId };
+};

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export * from "./evaluator";
+export * from "./expression-utils";
+export * from "./generate";