@real1ty-obsidian-plugins/utils 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real1ty-obsidian-plugins/utils",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Shared utilities for Obsidian plugins",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,10 +20,8 @@
     }
   },
   "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "dist/**/*.js.map",
-    "dist/**/*.d.ts.map",
+    "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],

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,118 @@
+import type { BehaviorSubject, Subscription } from "rxjs";
+
+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 compiledRules: Array<
+		TRule & { fn: (frontmatter: Record<string, unknown>) => boolean }
+	> = [];
+	private settingsSubscription: Subscription | null = null;
+
+	constructor(settingsStore: BehaviorSubject<TSettings>) {
+		const initialRules = this.extractRules(settingsStore.value);
+		this.compileRules(initialRules);
+
+		this.settingsSubscription = settingsStore.subscribe((settings) => {
+			const newRules = this.extractRules(settings);
+			this.compileRules(newRules);
+		});
+	}
+
+	/**
+	 * Extract rules from settings object. Must be implemented by subclasses.
+	 */
+	protected abstract extractRules(settings: TSettings): TRule[];
+
+	/**
+	 * Compile rules into executable functions with error handling.
+	 */
+	private compileRules(rules: TRule[]): void {
+		this.compiledRules = [];
+
+		for (const rule of rules) {
+			if (!rule.enabled || !rule.expression.trim()) continue;
+
+			try {
+				const cleanExpression = rule.expression.trim();
+
+				// Create a function that takes 'fm' (frontmatter) as parameter
+				// and evaluates the expression in that context
+				const fn = new Function("fm", `return (${cleanExpression});`) as (
+					frontmatter: Record<string, unknown>
+				) => boolean;
+
+				// Test the function with a dummy object to catch syntax errors early
+				fn({});
+
+				this.compiledRules.push({
+					...rule,
+					expression: cleanExpression,
+					fn,
+				});
+			} catch (error) {
+				console.warn(`Invalid rule expression "${rule.expression}":`, error);
+			}
+		}
+	}
+
+	/**
+	 * Evaluate a single rule against frontmatter. Returns the result or undefined if error.
+	 */
+	protected evaluateRule(
+		rule: TRule & { fn: (frontmatter: Record<string, unknown>) => boolean },
+		frontmatter: Record<string, unknown>
+	): boolean | undefined {
+		try {
+			return rule.fn(frontmatter);
+		} catch (error) {
+			console.warn(`Error evaluating rule "${rule.expression}":`, error);
+			return undefined;
+		}
+	}
+
+	/**
+	 * Convert evaluation result to boolean - only explicit true is considered truthy.
+	 */
+	protected isTruthy(result: boolean | undefined): boolean {
+		return result === true;
+	}
+
+	/**
+	 * Clean up subscriptions and compiled rules.
+	 */
+	destroy(): void {
+		if (this.settingsSubscription) {
+			this.settingsSubscription.unsubscribe();
+			this.settingsSubscription = null;
+		}
+		this.compiledRules = [];
+	}
+
+	/**
+	 * Get the number of active (compiled) rules.
+	 */
+	getActiveRuleCount(): number {
+		return this.compiledRules.length;
+	}
+
+	/**
+	 * Get information about all rules including their validity.
+	 */
+	getRuleInfo(): Array<{ expression: string; isValid: boolean; enabled: boolean }> {
+		const validExpressions = new Set(this.compiledRules.map((r) => r.expression));
+
+		return this.compiledRules.map((rule) => ({
+			expression: rule.expression,
+			isValid: validExpressions.has(rule.expression),
+			enabled: rule.enabled,
+		}));
+	}
+}

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,2 @@
+export * from "./evaluator-base";
+export * from "./generate";

package/src/date/date-recurrence.ts

@@ -0,0 +1,244 @@
+import type { DateTime } from "luxon";
+
+export type RecurrenceType = "daily" | "weekly" | "bi-weekly" | "monthly" | "bi-monthly" | "yearly";
+
+export type Weekday =
+	| "sunday"
+	| "monday"
+	| "tuesday"
+	| "wednesday"
+	| "thursday"
+	| "friday"
+	| "saturday";
+
+export const WEEKDAY_TO_NUMBER: Record<Weekday, number> = {
+	sunday: 0,
+	monday: 1,
+	tuesday: 2,
+	wednesday: 3,
+	thursday: 4,
+	friday: 5,
+	saturday: 6,
+};
+
+/**
+ * Calculates the next occurrence date based on recurrence type and optional weekdays
+ */
+export function getNextOccurrence(
+	currentDate: DateTime,
+	recurrenceType: RecurrenceType,
+	weekdays?: Weekday[]
+): DateTime {
+	switch (recurrenceType) {
+		case "daily":
+			return currentDate.plus({ days: 1 });
+		case "weekly":
+			if (weekdays && weekdays.length > 0) {
+				return getNextWeekdayOccurrence(currentDate, weekdays);
+			}
+			return currentDate.plus({ weeks: 1 });
+		case "bi-weekly":
+			if (weekdays && weekdays.length > 0) {
+				return getNextBiWeeklyOccurrence(currentDate, weekdays);
+			}
+			return currentDate.plus({ weeks: 2 });
+		case "monthly":
+			return currentDate.plus({ months: 1 });
+		case "bi-monthly":
+			return currentDate.plus({ months: 2 });
+		case "yearly":
+			return currentDate.plus({ years: 1 });
+		default:
+			return currentDate.plus({ days: 1 });
+	}
+}
+
+/**
+ * Checks if a given date matches any of the specified weekdays
+ */
+export function isDateOnWeekdays(date: DateTime, weekdays: Weekday[]): boolean {
+	const dateWeekday = date.weekday;
+	const luxonWeekdays = weekdays.map((day) => {
+		const dayNumber = WEEKDAY_TO_NUMBER[day];
+		return dayNumber === 0 ? 7 : dayNumber; // Convert Sunday from 0 to 7 for Luxon
+	});
+
+	return luxonWeekdays.includes(dateWeekday);
+}
+
+/**
+ * Finds the next occurrence on specified weekdays
+ */
+export function getNextWeekdayOccurrence(currentDate: DateTime, weekdays: Weekday[]): DateTime {
+	const currentWeekday = currentDate.weekday;
+	const luxonWeekdays = weekdays.map((day) => {
+		const dayNumber = WEEKDAY_TO_NUMBER[day];
+		return dayNumber === 0 ? 7 : dayNumber; // Convert Sunday from 0 to 7 for Luxon
+	});
+
+	// Find next weekday in the current week (after today)
+	const nextWeekday = luxonWeekdays.find((day) => day > currentWeekday);
+	if (nextWeekday) {
+		return currentDate.set({ weekday: nextWeekday as 1 | 2 | 3 | 4 | 5 | 6 | 7 });
+	}
+
+	// No more weekdays this week, go to first weekday of next week
+	const firstWeekday = Math.min(...luxonWeekdays);
+	return currentDate.plus({ weeks: 1 }).set({ weekday: firstWeekday as 1 | 2 | 3 | 4 | 5 | 6 | 7 });
+}
+
+/**
+ * Finds the next bi-weekly occurrence on specified weekdays
+ */
+export function getNextBiWeeklyOccurrence(currentDate: DateTime, weekdays: Weekday[]): DateTime {
+	const nextWeekly = getNextWeekdayOccurrence(currentDate, weekdays);
+	// Add one more week to make it bi-weekly
+	return nextWeekly.plus({ weeks: 1 });
+}
+
+export function* iterateOccurrencesInRange(
+	startDate: DateTime,
+	rrules: { type: RecurrenceType; weekdays?: Weekday[] },
+	rangeStart: DateTime,
+	rangeEnd: DateTime
+): Generator<DateTime, void, unknown> {
+	// Normalize to start of day for comparison
+	const normalizedStart = startDate.startOf("day");
+	const normalizedRangeStart = rangeStart.startOf("day");
+	const normalizedRangeEnd = rangeEnd.startOf("day");
+
+	// Start from the later of startDate or rangeStart
+	let currentDate =
+		normalizedStart >= normalizedRangeStart ? normalizedStart : normalizedRangeStart;
+
+	// For weekly/bi-weekly with weekdays, we need to track which week we're in
+	if (
+		(rrules.type === "weekly" || rrules.type === "bi-weekly") &&
+		rrules.weekdays &&
+		rrules.weekdays.length > 0
+	) {
+		// Calculate week offset from start date
+		const weeksFromStart = Math.floor(currentDate.diff(normalizedStart, "weeks").weeks);
+
+		// For bi-weekly, we only want even weeks (0, 2, 4...) from the start date
+		const weekInterval = rrules.type === "bi-weekly" ? 2 : 1;
+
+		// Adjust to the correct week if we're in an off-week
+		const weekOffset = weeksFromStart % weekInterval;
+		if (weekOffset !== 0) {
+			currentDate = currentDate.plus({ weeks: weekInterval - weekOffset });
+		}
+
+		// Now iterate through weeks, checking each day
+		while (currentDate <= normalizedRangeEnd) {
+			// Check all 7 days of the current week
+			for (let dayOffset = 0; dayOffset < 7; dayOffset++) {
+				const checkDate = currentDate.plus({ days: dayOffset });
+
+				// Only yield if within range and matches a target weekday
+				if (
+					checkDate >= normalizedRangeStart &&
+					checkDate <= normalizedRangeEnd &&
+					isDateOnWeekdays(checkDate, rrules.weekdays)
+				) {
+					yield checkDate;
+				}
+			}
+
+			// Move to next occurrence week (1 week for weekly, 2 weeks for bi-weekly)
+			currentDate = currentDate.plus({ weeks: weekInterval });
+		}
+	} else {
+		// For other recurrence types (daily, monthly, yearly, or weekly without weekdays)
+		while (currentDate <= normalizedRangeEnd) {
+			if (currentDate >= normalizedRangeStart) {
+				yield currentDate;
+			}
+
+			const nextDate = getNextOccurrence(currentDate, rrules.type, rrules.weekdays);
+
+			if (nextDate <= normalizedRangeEnd) {
+				currentDate = nextDate;
+			} else {
+				break;
+			}
+		}
+	}
+}
+
+/**
+ * Calculates a DateTime for a specific date with optional time
+ */
+export function calculateInstanceDateTime(instanceDate: DateTime, timeString?: string): DateTime {
+	if (!timeString) {
+		return instanceDate.startOf("day");
+	}
+
+	const [hours, minutes] = timeString.split(":").map(Number);
+	return instanceDate.set({ hour: hours, minute: minutes, second: 0, millisecond: 0 });
+}
+
+export function calculateRecurringInstanceDateTime(
+	nextInstanceDateTime: DateTime,
+	nodeRecuringEventDateTime: DateTime,
+	recurrenceType: RecurrenceType,
+	allDay?: boolean
+): DateTime {
+	// Convert the original event time to the target timezone once to preserve local time
+	const originalInTargetZone = nodeRecuringEventDateTime.setZone(nextInstanceDateTime.zone);
+
+	switch (recurrenceType) {
+		case "daily":
+		case "weekly":
+		case "bi-weekly": {
+			if (allDay) {
+				return nextInstanceDateTime.startOf("day");
+			}
+
+			return nextInstanceDateTime.set({
+				hour: originalInTargetZone.hour,
+				minute: originalInTargetZone.minute,
+				second: 0,
+				millisecond: 0,
+			});
+		}
+
+		case "monthly":
+		case "bi-monthly": {
+			if (allDay) {
+				return nextInstanceDateTime.set({ day: originalInTargetZone.day }).startOf("day");
+			}
+
+			return nextInstanceDateTime.set({
+				day: originalInTargetZone.day,
+				hour: originalInTargetZone.hour,
+				minute: originalInTargetZone.minute,
+				second: 0,
+				millisecond: 0,
+			});
+		}
+
+		case "yearly": {
+			if (allDay) {
+				return nextInstanceDateTime
+					.set({
+						month: originalInTargetZone.month,
+						day: originalInTargetZone.day,
+					})
+					.startOf("day");
+			}
+
+			return nextInstanceDateTime.set({
+				month: originalInTargetZone.month,
+				day: originalInTargetZone.day,
+				hour: originalInTargetZone.hour,
+				minute: originalInTargetZone.minute,
+				second: 0,
+				millisecond: 0,
+			});
+		}
+
+		default:
+			return nextInstanceDateTime.startOf("day");
+	}
+}

package/src/date/date.ts

@@ -0,0 +1,111 @@
+import { DateTime } from "luxon";
+
+export const formatDateTimeForInput = (dateString: string): string => {
+	if (!dateString) return "";
+
+	try {
+		const date = new Date(dateString);
+		// Format for datetime-local input (YYYY-MM-DDTHH:mm)
+		const year = date.getFullYear();
+		const month = String(date.getMonth() + 1).padStart(2, "0");
+		const day = String(date.getDate()).padStart(2, "0");
+		const hours = String(date.getHours()).padStart(2, "0");
+		const minutes = String(date.getMinutes()).padStart(2, "0");
+
+		return `${year}-${month}-${day}T${hours}:${minutes}`;
+	} catch {
+		return "";
+	}
+};
+
+export const formatDateForInput = (dateString: string): string => {
+	if (!dateString) return "";
+
+	try {
+		const date = new Date(dateString);
+		const year = date.getFullYear();
+		const month = String(date.getMonth() + 1).padStart(2, "0");
+		const day = String(date.getDate()).padStart(2, "0");
+
+		return `${year}-${month}-${day}`;
+	} catch {
+		return "";
+	}
+};
+
+/**
+ * Converts input value to ISO string, handling edge cases where
+ * browser datetime-local inputs behave differently across platforms.
+ * Returns null for invalid dates to prevent silent failures.
+ */
+export const inputValueToISOString = (inputValue: string): string | null => {
+	try {
+		return new Date(inputValue).toISOString();
+	} catch {
+		return null;
+	}
+};
+
+export const formatDuration = (minutes: number): string => {
+	const hours = Math.floor(minutes / 60);
+	const mins = minutes % 60;
+	return `${String(hours).padStart(2, "0")}:${String(mins).padStart(2, "0")}:00`;
+};
+
+/**
+ * Parse time string from datetime value - returns DateTime object
+ * Rejects plain HH:mm format, requires full datetime
+ */
+export const parseTimeString = (value: string | null): DateTime | undefined => {
+	if (value === null) return undefined;
+
+	const v = value.trim();
+
+	// Reject plain HH:mm format - require full datetime
+	if (/^\d{2}:\d{2}$/.test(v)) {
+		return undefined; // Reject plain time format
+	}
+
+	// Try ISO format first (most common) - EXACT same logic as recurring events
+	let dt = DateTime.fromISO(v, { setZone: true }); // ISO: with/without seconds, Z/offset, T
+	if (!dt.isValid) dt = DateTime.fromSQL(v, { setZone: true }); // "YYYY-MM-DD HH:mm[:ss]" etc.
+	if (!dt.isValid) dt = DateTime.fromFormat(v, "yyyy-MM-dd HH:mm", { setZone: true });
+
+	return dt.isValid ? dt : undefined;
+};
+
+/**
+ * Parse and validate datetime strings for event parsing
+ * Supports multiple formats including date-only and datetime formats
+ */
+export const parseDateTimeString = (value: string | null): DateTime | undefined => {
+	if (value === null) return undefined;
+
+	const v = value.trim();
+	if (!v) return undefined;
+
+	// Try multiple datetime formats in order of preference
+	let dt: DateTime;
+
+	// 1. Try ISO format first (most common)
+	dt = DateTime.fromISO(v, { setZone: true });
+	if (dt.isValid) return dt;
+
+	// 2. Try SQL format (YYYY-MM-DD HH:mm:ss)
+	dt = DateTime.fromSQL(v, { setZone: true });
+	if (dt.isValid) return dt;
+
+	// 3. Try common format with space (YYYY-MM-DD HH:mm)
+	dt = DateTime.fromFormat(v, "yyyy-MM-dd HH:mm", { setZone: true });
+	if (dt.isValid) return dt;
+
+	// 4. Try date-only format (YYYY-MM-DD) - treat as start of day
+	dt = DateTime.fromFormat(v, "yyyy-MM-dd", { setZone: true });
+	if (dt.isValid) return dt;
+
+	// 5. Try ISO date format (YYYY-MM-DD)
+	dt = DateTime.fromISO(v, { setZone: true });
+	if (dt.isValid) return dt;
+
+	return undefined;
+};

package/src/date/index.ts

@@ -0,0 +1,2 @@
+export * from "./date";
+export * from "./date-recurrence";