@real1ty-obsidian-plugins/utils 2.3.0 → 2.5.0

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";

package/src/file/child-reference.ts

@@ -0,0 +1,76 @@
+import { TFile } from "obsidian";
+import { createFileLink } from "./file-operations";
+import { extractFilePathFromLink } from "./link-parser";
+
+export interface VaultAdapter {
+	getAbstractFileByPath(path: string): TFile | null;
+}
+
+export function extractDirectoryPath(filePath: string): string {
+	const lastSlashIndex = filePath.lastIndexOf("/");
+	if (lastSlashIndex === -1) {
+		return "";
+	}
+	return filePath.substring(0, lastSlashIndex);
+}
+
+export function isRelativeChildReference(childRef: string): boolean {
+	const filePath = extractFilePathFromLink(childRef);
+	if (!filePath) {
+		return !childRef.includes("/");
+	}
+	return !filePath.includes("/");
+}
+
+export function normalizeChildReference(
+	childRef: string,
+	vault: VaultAdapter,
+	currentFileDirectory?: string
+): string {
+	const filePath = extractFilePathFromLink(childRef);
+
+	// Handle plain text references (not wrapped in [[]])
+	if (!filePath) {
+		// If it's not a link format, check if it should be converted to a link
+		if (!childRef.includes("/") && currentFileDirectory !== undefined) {
+			// This is a plain text reference that might need to be converted to a link
+			const potentialPath = currentFileDirectory
+				? `${currentFileDirectory}/${childRef.endsWith(".md") ? childRef : `${childRef}.md`}`
+				: childRef.endsWith(".md")
+					? childRef
+					: `${childRef}.md`;
+			const file = vault.getAbstractFileByPath(potentialPath);
+			if (file instanceof TFile) {
+				return createFileLink(file);
+			}
+		}
+		return childRef;
+	}
+
+	// Handle relative references by making them absolute
+	if (isRelativeChildReference(childRef) && currentFileDirectory) {
+		const absolutePath = `${currentFileDirectory}/${filePath}`;
+		const file = vault.getAbstractFileByPath(absolutePath);
+		if (file instanceof TFile) {
+			return createFileLink(file);
+		}
+	}
+
+	// For absolute references or when no directory context, try to find the file as-is
+	const file = vault.getAbstractFileByPath(filePath);
+	if (file instanceof TFile) {
+		return createFileLink(file);
+	}
+
+	return childRef;
+}
+
+export function normalizeChildReferences(
+	childRefs: string[],
+	vault: VaultAdapter,
+	currentFileDirectory?: string
+): string[] {
+	return childRefs.map((childRef) => {
+		return normalizeChildReference(childRef, vault, currentFileDirectory);
+	});
+}

package/src/file/file-operations.ts

@@ -0,0 +1,197 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { type App, Notice, TFile } from "obsidian";
+import { generateZettelId } from "../core";
+import { generateUniqueFilePath } from "./file";
+import { extractFilePathFromLink } from "./link-parser";
+
+export const fromRoot = (relativePath: string): string => {
+	return path.resolve(__dirname, `../../../${relativePath}`);
+};
+
+export const getActiveFileOrThrow = (app: App): TFile => {
+	const activeFile: TFile | null = app.workspace.getActiveFile();
+	if (!activeFile) {
+		new Notice(`⚠️  Open a note first.`);
+		throw new Error(`Open a note first.`);
+	}
+	return activeFile;
+};
+
+export const getTemplateContent = async (app: App, templatePath: string): Promise<string> => {
+	const templateFile = app.vault.getAbstractFileByPath(templatePath);
+	if (!templateFile) {
+		new Notice(`❌  Template not found: ${templatePath}`);
+		throw new Error(`Template not found: ${templatePath}`);
+	}
+
+	return await app.vault.read(templateFile as TFile);
+};
+
+export const ensureFolderExists = async (app: App, folderPath: string): Promise<void> => {
+	if (!app.vault.getAbstractFileByPath(folderPath)) {
+		await app.vault.createFolder(folderPath).catch(() => {});
+	}
+};
+
+export const openFileInNewLeaf = async (app: App, file: TFile): Promise<void> => {
+	await app.workspace.getLeaf(true).openFile(file);
+};
+
+export const getNoteFilesFromDir = async (directoryPath: string): Promise<string[]> => {
+	const files = await fs.readdir(directoryPath);
+	const directoryName = path.basename(directoryPath);
+
+	return files.filter((file) => {
+		if (!file.endsWith(".md")) return false;
+
+		const fileNameWithoutExt = path.parse(file).name;
+		if (fileNameWithoutExt === directoryName) {
+			console.log(`⏭️ Skipping directory-level file: ${file}`);
+			return false;
+		}
+
+		return true;
+	});
+};
+
+export const getTargetFileFromLink = (app: App, relationshipLink: string): TFile | null => {
+	const targetFilePath = extractFilePathFromLink(relationshipLink);
+	if (!targetFilePath) {
+		console.warn(`Failed to extract file path from link: ${relationshipLink}`);
+		return null;
+	}
+
+	const targetFile = app.vault.getAbstractFileByPath(targetFilePath) as TFile;
+	if (!targetFile) {
+		console.warn(`Target file not found for link: ${relationshipLink}`);
+		return null;
+	}
+
+	return targetFile;
+};
+
+export const createFileLink = (file: TFile): string => {
+	const folder = file.parent?.path && file.parent.path !== "/" ? file.parent.path : "";
+	return folder ? `[[${folder}/${file.basename}|${file.basename}]]` : `[[${file.basename}]]`;
+};
+
+export const normalizeArray = (value: string | string[] | undefined): string[] => {
+	if (!value) {
+		return [];
+	}
+	if (typeof value === "string") {
+		return [value];
+	}
+	if (Array.isArray(value)) {
+		return value;
+	}
+	return [];
+};
+
+export const arraysEqual = (a: string[], b: string[]): boolean => {
+	return a.length === b.length && a.every((val, index) => val === b[index]);
+};
+
+/**
+ * Normalizes frontmatter content by converting quoted numeric _ZettelIDs to numbers.
+ * This handles edge cases where YAML parsers treat numeric strings inconsistently.
+ */
+export const normalizeContent = (content: string): string => {
+	let normalized = content;
+	let hasChanges = false;
+
+	// Normalize _ZettelID: "string" → number (remove quotes)
+	const zettelIdMatch = normalized.match(/^_ZettelID:\s*"(\d+)"/m);
+	if (zettelIdMatch) {
+		const [fullMatch, numericId] = zettelIdMatch;
+		const replacement = `_ZettelID: ${numericId}`;
+		normalized = normalized.replace(fullMatch, replacement);
+		hasChanges = true;
+		console.log(`  ✅ _ZettelID: "${numericId}" → ${numericId}`);
+	}
+
+	return hasChanges ? normalized : content;
+};
+
+/**
+ * Safely performs a file operation with error handling and file validation.
+ * Reduces boilerplate for common file operations.
+ */
+export const withFileOperation = async <T>(
+	app: App,
+	event: any,
+	operation: (file: TFile) => Promise<T>,
+	errorMessage: string = "Operation failed"
+): Promise<T | null> => {
+	try {
+		const filePath = event.extendedProps.filePath;
+		const file = app.vault.getAbstractFileByPath(filePath);
+
+		if (!(file instanceof TFile)) {
+			new Notice("Could not find the file");
+			return null;
+		}
+
+		return await operation(file);
+	} catch (error) {
+		console.error(`Error in file operation:`, error);
+		new Notice(errorMessage);
+		return null;
+	}
+};
+
+/**
+ * Safely performs a file operation by file path with error handling and file validation.
+ */
+export const withFile = async <T>(
+	app: App,
+	filePath: string,
+	operation: (file: TFile) => Promise<T>,
+	errorMessage: string = "Operation failed"
+): Promise<T | null> => {
+	try {
+		const file = app.vault.getAbstractFileByPath(filePath);
+
+		if (!(file instanceof TFile)) {
+			new Notice("Could not find the file");
+			return null;
+		}
+
+		return await operation(file);
+	} catch (error) {
+		console.error(`Error in file operation:`, error);
+		new Notice(errorMessage);
+		return null;
+	}
+};
+
+/**
+ * Duplicates a file with a new ZettelID, preserving the original content
+ * but updating the ZettelID in frontmatter if configured.
+ */
+export const duplicateFileWithNewZettelId = async (
+	app: App,
+	file: TFile,
+	zettelIdProp?: string
+): Promise<TFile> => {
+	const content = await app.vault.read(file);
+
+	const parentPath = file.parent?.path || "";
+	const baseNameWithoutZettel = file.basename.replace(/-\d{14}$/, "");
+	const zettelId = generateZettelId();
+	const newBasename = `${baseNameWithoutZettel}-${zettelId}`;
+	const newFilePath = generateUniqueFilePath(app, parentPath, newBasename);
+
+	// Create the new file with original content
+	const newFile = await app.vault.create(newFilePath, content);
+
+	// Update the ZettelID in frontmatter if configured
+	if (zettelIdProp) {
+		await app.fileManager.processFrontMatter(newFile, (fm) => {
+			fm[zettelIdProp] = zettelId;
+		});
+	}
+
+	return newFile;
+};