mirror of
https://github.com/callumalpass/tasknotes.git
synced 2026-07-22 12:50:26 +00:00
b4d52c707d
This commit introduces the UTC Anchor principle to eliminate timezone-related bugs and provide consistent date handling across all user timezones. ## Key Changes: ### Core Implementation - Add `parseDateToUTC()` function that creates UTC anchors for date-only strings - Add `parseDateToLocal` alias for existing `parseDate` function - Deprecate direct `parseDate` usage with clear migration path - Update date comparison functions to use UTC anchors ### Updated Components - **dateUtils.ts**: New UTC parsing functions and updated comparisons - **main.ts**: Use UTC anchor for selectedDate initialization - **MiniCalendarView**: Navigate using UTC anchors - **TimeblockCreationModal**: Fix timezone handling - **Multiple test files**: Fix timezone assumptions in tests ### Refactored parseDate Usage - **UnscheduledTasksSelectorModal**: Use parseDateToLocal for UI display - **AdvancedCalendarView**: Use parseDateToLocal for calendar events - **helpers.ts**: Use parseDateToUTC for internal date logic - **FilterService**: Already using updated utilities ### Documentation - Add comprehensive UTC Anchor implementation docs - Update development guidelines with date handling best practices - Add migration guide for existing code - Include quick reference for date functions ## Benefits: - Eliminates "off-by-one day" errors across timezones - Provides consistent sorting and filtering behavior - Simplifies date comparison logic - Future-proofs against timezone-related bugs ## Testing: - All 798 tests passing - New UTC anchor test suite (11 tests) - No regression in existing functionality Fixes #327, #322, #314 and other timezone-related issues
907 lines
No EOL
41 KiB
Markdown
907 lines
No EOL
41 KiB
Markdown
# TaskNotes Plugin: Architecture & Developer's Guide
|
|
|
|
## 1. Introduction & Guiding Principles
|
|
|
|
This guide is designed to help you understand the architecture of the TaskNotes plugin, ensuring that new features and updates are implemented in a way that is consistent, maintainable, and performant.
|
|
|
|
The architecture of this plugin is built on several key principles:
|
|
|
|
* **Separation of Concerns:** Logic is separated into distinct layers: UI (Views & Components), Business Logic (Services), and Data (Minimal Cache & Obsidian Native Cache). This makes the codebase easier to reason about and test.
|
|
* **Native-First Data Access:** Obsidian's `metadataCache` is the primary source of truth for all task and note data. The minimal cache layer exists primarily to coordinate event signals and maintain only performance-critical indexes.
|
|
* **Unidirectional Data Flow:** Changes flow in one direction: User Action -> Service -> File System -> Native Cache -> Event Coordination -> UI Update. This predictable pattern prevents complex state management issues and race conditions.
|
|
* **Event-Driven Communication:** Components are decoupled through centralized event coordination. The minimal cache coordinates view updates efficiently, preventing multiple views from redundantly scanning files.
|
|
* **Performance Through Coordination:** Rather than complex indexing, performance is achieved through intelligent event coordination, lazy computation, and leveraging Obsidian's optimized native cache.
|
|
* **Configuration-Driven:** Core functionalities like statuses, priorities, and field names are not hard-coded. They are managed by dedicated services (`StatusManager`, `PriorityManager`, `FieldMapper`) that interpret user settings, making the plugin highly customizable.
|
|
* **Obsidian Optimization Compliance:** The plugin follows Obsidian's best practices for load time optimization and deferred view compatibility, ensuring fast startup and smooth integration with the latest Obsidian versions.
|
|
|
|
## 2. High-Level Architecture Diagram
|
|
|
|
This diagram illustrates the flow of data and events within the plugin, emphasizing the native-first approach:
|
|
|
|
```
|
|
+----------------+ +------------------+ +------------------+
|
|
| User Input |------>| UI / Views |------>| Services |
|
|
| (Click, Drag) | | (Agenda, Kanban) | | (TaskService, etc) |
|
|
+----------------+ +------------------+ +------------------+
|
|
^ |
|
|
| | (1. Write to file)
|
|
| v
|
|
| +------------+
|
|
| (5. UI Update via | File System|
|
|
| DOMReconciler) | (.md) |
|
|
| +------------+
|
|
| |
|
|
| | (2. Native metadata update)
|
|
+---------------------+ v
|
|
+---------------------+ | +------------------+
|
|
| DOMReconciler | | (4. Coordinated view | Obsidian Native | (Primary Source
|
|
| (Efficient Updates) |<----+ updates) | MetadataCache | of Truth)
|
|
+---------------------+ | +------------------+
|
|
| |
|
|
| | (3. Event coordination)
|
|
| v
|
|
+-----------------------------------+
|
|
| MinimalCache (Event Coordinator)|
|
|
| - Essential indexes only |
|
|
| - Coordinates view refreshes |
|
|
+-----------------------------------+
|
|
```
|
|
|
|
## 3. Directory Structure
|
|
|
|
The project is organized to reflect the architectural layers:
|
|
|
|
* `/src/`
|
|
* `main.ts`: The plugin's entry point. It initializes all services, views, and commands.
|
|
* `types.ts`: **Crucial.** Contains all shared type definitions. All new types should be added here.
|
|
* `/views/`: Contains the primary UI views (`TaskListView`, `AgendaView`, `KanbanView`, etc.), which are `ItemView` implementations registered with Obsidian.
|
|
* `/ui/`: Contains reusable, "dumb" UI components like `TaskCard`, `NoteCard`, and `FilterBar`. These components are responsible for rendering data, not fetching it.
|
|
* `/modals/`: Contains all modals for user interaction (`TaskCreationModal`, `TaskEditModal`, etc.).
|
|
* `/services/`: The core business logic of the plugin resides here. Each service has a specific responsibility (e.g., `TaskService` for CRUD, `FilterService` for querying, `PomodoroService` for timers).
|
|
* `/editor/`: Contains CodeMirror extensions that enhance the Obsidian editor, like `TaskLinkWidget` and `InstantConvertButtons`.
|
|
* `/utils/`: Contains helper classes and functions that support the entire plugin, such as `MinimalNativeCache`, `dateUtils`, and `DOMReconciler`.
|
|
* `/settings/`: Contains the settings tab UI and default settings configuration.
|
|
* `/styles/`: Contains all CSS files, which are compiled into a single `styles.css`.
|
|
|
|
## 4. Key Architectural Concepts
|
|
|
|
### 4.1. The Data Flow: A Step-by-Step Guide
|
|
|
|
Understanding this native-first flow is the most important part of contributing to the plugin.
|
|
|
|
1. **User Action**: A user interacts with the UI (e.g., clicks "Archive" on a `TaskCard`).
|
|
2. **Service Call**: The UI component's event handler calls the relevant method in a service (e.g., `plugin.taskService.toggleArchive(task)`). **UI components should never modify data directly.**
|
|
3. **File System Write**: The service performs the necessary changes on the Markdown file's frontmatter.
|
|
4. **Native Cache Update**: Obsidian's native metadata cache automatically updates with the new file content.
|
|
5. **Minimal Cache Coordination**: The minimal cache detects the native change and updates only essential indexes, then coordinates view refresh events.
|
|
6. **Event Emission**: The minimal cache emits coordinated events (e.g., `EVENT_TASK_UPDATED`) to prevent redundant view updates.
|
|
7. **Coordinated View Refresh**: Views receive coordinated events and refresh efficiently, fetching fresh data directly from the native metadata cache.
|
|
8. **DOM Reconciliation**: Views use the `DOMReconciler` to efficiently update only the parts of the UI that have changed.
|
|
|
|
### 4.2. The Minimal Cache - Event Coordinator & Performance Guardian
|
|
|
|
The `MinimalNativeCache` serves as an intelligent coordinator rather than a data warehouse. Its primary purpose is **view performance coordination**, not data storage.
|
|
|
|
* **Core Philosophy**: Leverage Obsidian's native metadata cache maximally while coordinating view updates efficiently.
|
|
|
|
* **What it Does**:
|
|
* **Event Coordination**: Prevents multiple views from simultaneously scanning files by coordinating refresh signals
|
|
* **Essential Indexing**: Maintains only 3 performance-critical indexes: `tasksByDate`, `tasksByStatus`, `overdueTasks`
|
|
* **Native Integration**: Listens to Obsidian's native metadata events and translates them to coordinated view updates
|
|
* **Lazy Computation**: Computes tags, contexts, and priorities on-demand rather than pre-indexing
|
|
|
|
* **What it Doesn't Do**:
|
|
* **Data Storage**: Task data comes directly from `app.metadataCache.getFileCache()`
|
|
* **Complex Indexing**: No redundant data structures duplicating native cache
|
|
* **Note Management**: Notes handled by Obsidian's daily notes interface
|
|
|
|
* **The 3 Essential Indexes Explained**:
|
|
```typescript
|
|
// Only these are indexed for performance:
|
|
tasksByDate: Map<string, Set<string>> // Calendar view optimization
|
|
tasksByStatus: Map<string, Set<string>> // FilterService optimization
|
|
overdueTasks: Set<string> // Overdue query optimization
|
|
|
|
// Everything else computed on-demand:
|
|
getAllTags() -> scans native cache when called
|
|
getAllPriorities() -> scans native cache when called
|
|
getTasksByPriority() -> filters all tasks when called
|
|
```
|
|
|
|
* **Performance Benefits of Coordination**:
|
|
```typescript
|
|
// Without coordination: Multiple views scan independently
|
|
CalendarView -> scans 1000 files for date tasks
|
|
AgendaView -> scans 1000 files for date tasks
|
|
KanbanView -> scans 1000 files for status tasks
|
|
// Result: 3000 file scans on data change
|
|
|
|
// With coordination: Single coordinated update
|
|
MinimalCache -> coordinates single refresh signal
|
|
All views -> refresh once with targeted data
|
|
// Result: 1 coordinated update cycle
|
|
```
|
|
|
|
* **Developer Best Practices**:
|
|
* **Read from native cache**: Use `app.metadataCache.getFileCache(file)` for direct data access
|
|
* **Coordinate through minimal cache**: Use cache for event coordination and essential indexes only
|
|
* **Never duplicate data**: Don't store data that's already in the native cache
|
|
* **Leverage lazy computation**: Compute infrequently-accessed data on-demand
|
|
* **Update essential indexes**: When adding date/status-related features, consider index impact
|
|
|
|
### 4.3. The Event System - Coordinated Communication
|
|
|
|
The event system now focuses on **coordination efficiency** rather than complex pub/sub patterns.
|
|
|
|
* **Purpose**: Coordinate view updates efficiently while preventing redundant operations. The minimal cache serves as an intelligent event dispatcher.
|
|
|
|
* **Coordination Patterns**:
|
|
```typescript
|
|
// Efficient: Coordinated update
|
|
minimalCache.on('file-updated', (data) => {
|
|
// All views receive coordinated signal
|
|
// Each view refreshes with fresh native cache data
|
|
});
|
|
|
|
// Inefficient: Direct native listening (avoided)
|
|
app.metadataCache.on('changed', (file) => {
|
|
// Each view independently processes the same change
|
|
// Results in redundant scanning and processing
|
|
});
|
|
```
|
|
|
|
* **Event Coordination Benefits**:
|
|
* **Prevents Duplicate Work**: Single file change doesn't trigger multiple view scans
|
|
* **Batched Updates**: Multiple rapid changes can be batched into single refresh
|
|
* **Performance Isolation**: Slow views don't impact fast views through coordination
|
|
|
|
* **Developer Best Practices**:
|
|
* **Use coordinated events**: Listen to minimal cache events, not native cache directly
|
|
* **Fetch fresh data**: On event receipt, fetch fresh data from native cache
|
|
* **Avoid event proliferation**: Don't create multiple event types for the same data change
|
|
|
|
### 4.4. Date and Time Management (`dateUtils.ts`)
|
|
|
|
Handling dates and times is notoriously difficult due to timezones and different formats. This plugin standardizes date/time handling through `dateUtils.ts` and implements the UTC Anchor principle for robust timezone-independent logic.
|
|
|
|
#### The UTC Anchor Principle
|
|
|
|
The UTC Anchor principle is a fundamental architectural decision that ensures timezone-independent date handling throughout the plugin.
|
|
|
|
* **The Problem**: JavaScript's `new Date()` is inconsistent. `new Date('2023-10-27')` creates a UTC date, while `new Date('2023-10-27T10:00:00')` creates a local timezone date. This leads to "off-by-one-day" errors and inconsistent behavior across timezones.
|
|
|
|
* **The Solution**: The UTC Anchor principle establishes that all date-only strings (e.g., "2025-08-01") are represented internally as Date objects anchored to midnight UTC. This provides a canonical representation where the string "2025-08-01" maps to the exact same internal timestamp for every user on Earth.
|
|
|
|
* **Implementation**:
|
|
```typescript
|
|
// For internal logic (comparisons, sorting, filtering)
|
|
const date = parseDateToUTC('2025-08-01'); // Always 2025-08-01T00:00:00.000Z
|
|
|
|
// For UI display (showing dates to users)
|
|
const date = parseDateToLocal('2025-08-01'); // Midnight in user's timezone
|
|
|
|
// Deprecated - do not use directly
|
|
const date = parseDate('2025-08-01'); // Legacy function, aliased to parseDateToLocal
|
|
```
|
|
|
|
* **Key Benefits**:
|
|
* **Absolute Consistency**: Same date string always produces same timestamp internally
|
|
* **Simplified Logic**: Direct timestamp comparisons work correctly
|
|
* **Timezone Independence**: Users in different timezones see consistent behavior
|
|
* **Future-Proof**: Eliminates entire classes of timezone bugs
|
|
|
|
* **Developer Best Practices**:
|
|
* **Never use `new Date(dateString)` directly.** Always use the appropriate parsing function from `dateUtils.ts`.
|
|
* **For internal logic**: Use `parseDateToUTC()` for all date comparisons, sorting, filtering, and business logic.
|
|
* **For UI display**: Use `parseDateToLocal()` when showing dates to users or handling user input.
|
|
* **Check for time components**: Use `hasTimeComponent(dateString)` to determine if a date string includes time information:
|
|
```typescript
|
|
if (hasTimeComponent(dateString)) {
|
|
// Has time - use local parsing for display
|
|
const dateTime = parseDateToLocal(dateString);
|
|
} else {
|
|
// Date-only - use UTC anchor for logic
|
|
const date = parseDateToUTC(dateString);
|
|
}
|
|
```
|
|
* **For comparisons**: Use the provided safe functions that implement UTC anchors: `isSameDateSafe`, `isBeforeDateSafe`, `isOverdueTimeAware`.
|
|
* **For storage**: Always store dates in YYYY-MM-DD format using `formatDateForStorage()`.
|
|
* **For timestamps**: When creating `dateCreated` or `dateModified`, use `getCurrentTimestamp()` for timezone-aware ISO strings.
|
|
|
|
* **Migration Pattern**: When updating existing code:
|
|
```typescript
|
|
// Old pattern (fragile)
|
|
const date = parseDate(task.due);
|
|
if (isBefore(date, today)) { ... }
|
|
|
|
// New pattern (robust)
|
|
const date = parseDateToUTC(task.due); // For logic
|
|
if (isBeforeDateSafe(task.due, getTodayString())) { ... }
|
|
```
|
|
|
|
### 4.5. The UI Layer (Views and Components)
|
|
|
|
* **Views (`/views/`)**: These are the main panels of the plugin (e.g., `AgendaView`). They are stateful and responsible for fetching data (via direct native cache access or `FilterService`), managing user interactions, and orchestrating the rendering of their content. They should contain the `FilterBar` and the main content display.
|
|
|
|
* **Native-First Data Access**:
|
|
```typescript
|
|
// Views now access data directly from native cache
|
|
async refreshTasks(): Promise<void> {
|
|
// Get task paths from minimal cache (indexed)
|
|
const taskPaths = this.plugin.cacheManager.getTasksForDate(dateStr);
|
|
|
|
// Get fresh task data from native cache
|
|
const tasks = await Promise.all(
|
|
taskPaths.map(path => {
|
|
const file = this.app.vault.getAbstractFileByPath(path);
|
|
const metadata = this.app.metadataCache.getFileCache(file);
|
|
return this.extractTaskInfo(path, metadata.frontmatter);
|
|
})
|
|
);
|
|
|
|
this.renderTasks(tasks);
|
|
}
|
|
```
|
|
|
|
* **Reusable Components (`/ui/`)**: These are "dumb" components like `TaskCard` and `NoteCard`.
|
|
* They receive data as props (`createTaskCard(task, plugin, options)`).
|
|
* They are responsible only for rendering that data into HTML.
|
|
* They should not contain business logic. Any user interaction (like a button click) should call a method on the `plugin` or a `service` passed in as a prop.
|
|
|
|
* **DOMReconciler**: To ensure high performance, views do not re-render their entire HTML on every data change. Instead, they use `plugin.domReconciler.updateList()`. This utility efficiently diffs the new data against the existing DOM, only adding, removing, or updating the elements that have changed.
|
|
|
|
### 4.6. The Field Mapper (`FieldMapper.ts`) - The Data Translator
|
|
|
|
This is a critical architectural component that enables user customization.
|
|
|
|
* **Purpose**: The `FieldMapper` is a "translator" service. Its primary purpose is to decouple the plugin's internal `TaskInfo` property names (e.g., `scheduled`, `timeEstimate`) from the user-configurable property names in the YAML frontmatter of their task files. This allows users to name their properties whatever they like (e.g., `schedule_on`, `estimate_minutes`) without breaking the plugin.
|
|
|
|
* **How it Works**: It provides a two-way mapping.
|
|
* **Reading (File -> `TaskInfo`)**: When processing native metadata cache data, the frontmatter is passed to `fieldMapper.mapFromFrontmatter(frontmatter)`. The service uses the mapping in `settings.fieldMapping` to create a standardized `TaskInfo` object. For example, if the user setting is `{ due: "deadline" }`, the mapper will take `frontmatter.deadline` and put its value into the `taskInfo.due` field.
|
|
* **Writing (`TaskInfo` -> File)**: When `TaskService` saves a task, it passes the internal `TaskInfo` object to `fieldMapper.mapToFrontmatter(taskInfo)`. This creates a frontmatter object ready for serialization. For example, `taskInfo.due` will be written as `deadline: ...` in the YAML.
|
|
|
|
* **Developer Best Practices**:
|
|
* **Central Point of Interaction**: Any service that directly reads or writes task frontmatter (`MinimalNativeCache`, `TaskService`) **must** use the `FieldMapper`.
|
|
* **Stable Internal API**: Within the plugin's TypeScript code (views, components, other services), you should **always** interact with the standardized `TaskInfo` properties (`task.due`, `task.priority`, etc.). The `FieldMapper` is the boundary layer that handles the translation to/from the user's world.
|
|
* **Avoid Hard-coding**: **Never** write code that directly accesses a frontmatter property like `frontmatter.due`. Always use the mapper to get the user-configured field name first.
|
|
* **Extensibility**: When adding a new persistent property to tasks, you must add it to the `FieldMapping` type in `types.ts`, the `DEFAULT_FIELD_MAPPING` in `settings.ts`, and the mapping logic in `FieldMapper.ts`.
|
|
|
|
## 5. Developer's Guide: How to Implement Common Changes
|
|
|
|
### 5.1. Adding a New Property to Tasks
|
|
|
|
Let's say you want to add a `complexity: 'simple' | 'medium' | 'hard'` property to tasks.
|
|
|
|
1. **Update `types.ts`**: Add `complexity?: string;` to the `TaskInfo` interface.
|
|
2. **Update `settings.ts`**:
|
|
* Add `complexity: string;` to the `FieldMapping` interface in `DEFAULT_FIELD_MAPPING`.
|
|
* Add a new setting in the `TaskNotesSettingTab` to allow users to configure the property name.
|
|
3. **Update `FieldMapper.ts`**: Add logic to `mapFromFrontmatter` and `mapToFrontmatter` to handle the new `complexity` field.
|
|
4. **Update `TaskService.ts`**:
|
|
* In `createTask`, handle the new property, possibly applying a default value.
|
|
* In `updateTask`, ensure the new property can be updated.
|
|
5. **Update `TaskModal.ts`**: Add a dropdown or input field to `TaskCreationModal` and `TaskEditModal` to allow users to set the complexity.
|
|
6. **Update `TaskCard.ts`**: In `createTaskCard` and `updateTaskCard`, add logic to display the new complexity information (e.g., an icon or text in the metadata line).
|
|
7. **Update `FilterService.ts` (Optional)**: If you want to filter by complexity frequently:
|
|
* Consider whether an index is needed (probably not - compute on-demand)
|
|
* Add logic to `FilterService.matchesQuery` to filter by complexity.
|
|
* Add a complexity filter control to `FilterBar.ts`.
|
|
|
|
**Note**: With the minimal cache approach, most new properties should be computed on-demand rather than indexed. Only add indexes for frequently-accessed, performance-critical queries.
|
|
|
|
### 5.2. Adding View-Specific Options to Saved Views
|
|
|
|
The plugin supports capturing and restoring view-specific display options as part of saved views. This feature allows views to preserve their display preferences (toggles, visibility options) alongside filter configurations.
|
|
|
|
#### Implementation Pattern
|
|
|
|
**Step 1: Define View Options in the View Class**
|
|
```typescript
|
|
export class MyView extends ItemView {
|
|
private showOption1: boolean = true;
|
|
private showOption2: boolean = false;
|
|
|
|
private setupViewOptions(): void {
|
|
// Configure FilterBar with view options
|
|
this.filterBar.setViewOptions([
|
|
{ id: 'showOption1', label: 'Show Option 1', value: this.showOption1 },
|
|
{ id: 'showOption2', label: 'Show Option 2', value: this.showOption2 }
|
|
]);
|
|
}
|
|
}
|
|
```
|
|
|
|
**Step 2: Handle View Options Events**
|
|
```typescript
|
|
private setupEventListeners(): void {
|
|
// Save view options along with filter state
|
|
this.filterBar.on('saveView', ({ name, query, viewOptions }) => {
|
|
this.plugin.viewStateManager.saveView(name, query, viewOptions);
|
|
});
|
|
|
|
// Apply loaded view options
|
|
this.filterBar.on('loadViewOptions', (viewOptions: {[key: string]: boolean}) => {
|
|
this.applyViewOptions(viewOptions);
|
|
});
|
|
}
|
|
|
|
private applyViewOptions(viewOptions: {[key: string]: boolean}): void {
|
|
// Apply options to internal state
|
|
if (viewOptions.hasOwnProperty('showOption1')) {
|
|
this.showOption1 = viewOptions.showOption1;
|
|
}
|
|
if (viewOptions.hasOwnProperty('showOption2')) {
|
|
this.showOption2 = viewOptions.showOption2;
|
|
}
|
|
|
|
// Update FilterBar to reflect loaded state
|
|
this.setupViewOptions();
|
|
|
|
// Refresh view to apply changes
|
|
this.refresh();
|
|
}
|
|
```
|
|
|
|
**Step 3: FilterBar Integration**
|
|
The FilterBar automatically handles:
|
|
- Capturing current view options when saving views
|
|
- Emitting `loadViewOptions` events when loading saved views
|
|
- Providing UI controls for view-specific options
|
|
|
|
#### Architecture Components
|
|
|
|
**SavedView Interface Enhancement:**
|
|
```typescript
|
|
export interface SavedView {
|
|
id: string;
|
|
name: string;
|
|
query: FilterQuery;
|
|
viewOptions?: {[key: string]: boolean}; // View-specific display options
|
|
}
|
|
```
|
|
|
|
**ViewStateManager Integration:**
|
|
```typescript
|
|
saveView(name: string, query: FilterQuery, viewOptions?: {[key: string]: boolean}): SavedView {
|
|
const view: SavedView = {
|
|
id: this.generateId(),
|
|
name,
|
|
query: FilterUtils.deepCloneFilterQuery(query),
|
|
viewOptions: viewOptions ? { ...viewOptions } : undefined
|
|
};
|
|
// ... save logic
|
|
}
|
|
```
|
|
|
|
#### Current Implementation Examples
|
|
|
|
**Agenda View Options:**
|
|
- `showOverdueOnToday`: Shows overdue tasks in today's section
|
|
- `showNotes`: Controls display of daily notes
|
|
|
|
**Advanced Calendar View Options:**
|
|
- `showScheduled`: Display tasks with scheduled dates
|
|
- `showDue`: Display tasks with due dates
|
|
- `showTimeblocks`: Display time-blocking entries
|
|
- `showRecurring`: Display recurring task events
|
|
- `showICSEvents`: Display imported calendar events
|
|
- `showTimeEntries`: Display time tracking entries
|
|
|
|
#### Developer Best Practices
|
|
|
|
**View Option Design:**
|
|
- Use boolean options for simple toggles
|
|
- Keep option IDs descriptive and unique per view
|
|
- Provide sensible defaults for all options
|
|
- Consider backward compatibility when adding new options
|
|
|
|
**State Management:**
|
|
- Always use defensive programming when checking for option existence
|
|
- Apply options to internal state before updating UI
|
|
- Refresh the view after applying loaded options
|
|
- Maintain option state independently of saved views
|
|
|
|
**Performance Considerations:**
|
|
- View options are cloned when saving/loading for data safety
|
|
- Options are applied synchronously to avoid UI state conflicts
|
|
- FilterBar updates are batched to prevent unnecessary re-renders
|
|
|
|
### 5.3. Migrating to UTC Anchor Pattern
|
|
|
|
When updating existing code or adding new date-handling features, follow this migration guide:
|
|
|
|
**Step 1: Identify Date Usage Context**
|
|
```typescript
|
|
// Is this for internal logic?
|
|
if (purposeIsLogic) {
|
|
// Use UTC anchor: comparisons, sorting, filtering, storage
|
|
const date = parseDateToUTC(dateString);
|
|
}
|
|
|
|
// Is this for UI display?
|
|
if (purposeIsDisplay) {
|
|
// Use local parsing: showing to users, form inputs
|
|
const date = parseDateToLocal(dateString);
|
|
}
|
|
```
|
|
|
|
**Step 2: Update Import Statements**
|
|
```typescript
|
|
// Old
|
|
import { parseDate, isBeforeDate } from '../utils/dateUtils';
|
|
|
|
// New
|
|
import { parseDateToUTC, parseDateToLocal, isBeforeDateSafe } from '../utils/dateUtils';
|
|
```
|
|
|
|
**Step 3: Replace parseDate Calls**
|
|
```typescript
|
|
// Old pattern
|
|
const dueDate = parseDate(task.due);
|
|
const scheduledDate = parseDate(task.scheduled);
|
|
|
|
// New pattern - for logic
|
|
const dueDate = parseDateToUTC(task.due);
|
|
const scheduledDate = parseDateToUTC(task.scheduled);
|
|
|
|
// New pattern - for display
|
|
const dueDateDisplay = parseDateToLocal(task.due);
|
|
const formattedDate = format(dueDateDisplay, 'MMM d, yyyy');
|
|
```
|
|
|
|
**Step 4: Update Comparisons**
|
|
```typescript
|
|
// Old pattern
|
|
const date1 = parseDate(dateStr1);
|
|
const date2 = parseDate(dateStr2);
|
|
if (isBefore(date1, date2)) { ... }
|
|
|
|
// New pattern - use safe comparison functions
|
|
if (isBeforeDateSafe(dateStr1, dateStr2)) { ... }
|
|
|
|
// Or if you need the Date objects
|
|
const date1 = parseDateToUTC(dateStr1);
|
|
const date2 = parseDateToUTC(dateStr2);
|
|
if (date1.getTime() < date2.getTime()) { ... }
|
|
```
|
|
|
|
**Step 5: Handle Mixed Date/DateTime**
|
|
```typescript
|
|
// When dealing with both date-only and datetime strings
|
|
function processTaskDate(dateString: string) {
|
|
if (hasTimeComponent(dateString)) {
|
|
// Has time - might need local handling for display
|
|
const dateTime = parseDateToLocal(dateString);
|
|
return format(dateTime, 'MMM d, h:mm a');
|
|
} else {
|
|
// Date only - use UTC anchor for consistency
|
|
const date = parseDateToUTC(dateString);
|
|
return format(date, 'MMM d');
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5.4. Walkthrough: Modifying a Task Property (Native-First Approach)
|
|
|
|
Let's trace the flow of changing a task's priority from a `TaskCard`.
|
|
|
|
1. **UI (`TaskCard.ts`)**: The user right-clicks the card and selects a new priority from the context menu.
|
|
2. **Event Handler**: The `onClick` handler for the menu item calls `plugin.updateTaskProperty(task, 'priority', newPriorityValue)`.
|
|
3. **Main Plugin (`main.ts`)**: The `updateTaskProperty` method is a convenience wrapper that calls `this.taskService.updateProperty(...)`.
|
|
4. **Service (`TaskService.ts`)**: The `updateProperty` method is executed.
|
|
a. It finds the `TFile` for the task.
|
|
b. It uses `app.fileManager.processFrontMatter()` to open the file and update the YAML. It uses the `fieldMapper` to get the correct property name (e.g., it might write `prio: high` instead of `priority: high` if the user configured it that way). It also updates the `dateModified` property.
|
|
c. **Native cache automatically updates** when the file is saved.
|
|
d. The minimal cache detects the native change and **coordinates view updates**.
|
|
5. **Event Coordination**:
|
|
* **`MinimalNativeCache`**: Detects the native metadata change, updates essential indexes (if priority indexing was needed), and emits coordinated `EVENT_TASK_UPDATED`.
|
|
* **Views receive coordinated signal**: All views get a single, coordinated update event rather than multiple native events.
|
|
6. **View Updates**:
|
|
* **`TaskListView.ts`**: The view's listener for `EVENT_TASK_UPDATED` fires. It fetches fresh task data from native cache and uses `updateTaskCard(element, updatedTask, ...)` to efficiently re-render just that one card.
|
|
* **`AgendaView.ts`**: Its listener fires. Since a priority change might affect sorting, it triggers a `refresh()`, fetching fresh data directly from native cache and using the `DOMReconciler` to update the view.
|
|
* **Editor (`TaskLinkOverlay.ts`)**: The global listener in `main.ts` dispatches a `taskUpdateEffect` to all open editors. The `TaskLinkField` sees this effect and redraws any `TaskLinkWidget`s for the affected task path with fresh native cache data.
|
|
|
|
This entire flow happens almost instantaneously, with minimal cache coordination ensuring efficient updates while native cache provides always-fresh data.
|
|
|
|
### 5.3. When to Add an Index vs Compute On-Demand
|
|
|
|
**Add to Essential Indexes When**:
|
|
- The query is performance-critical (sub-100ms response needed)
|
|
- It's accessed very frequently (multiple times per second)
|
|
- The computation would involve scanning many files
|
|
- Examples: `tasksByDate` (calendar navigation), `tasksByStatus` (kanban boards)
|
|
|
|
**Compute On-Demand When**:
|
|
- The query is infrequent or user-initiated
|
|
- The dataset is small (< 1000 items)
|
|
- The computation is lightweight
|
|
- Examples: `getAllTags()`, `getTasksByPriority()`, `getAllContexts()`
|
|
|
|
**Decision Framework**:
|
|
```typescript
|
|
// Performance test: Is this query slow?
|
|
console.time('query');
|
|
const result = computeOnDemand();
|
|
console.timeEnd('query');
|
|
// If > 10ms and frequent -> consider indexing
|
|
// If < 10ms or infrequent -> keep on-demand
|
|
```
|
|
|
|
## 6. Performance Optimization & Obsidian Best Practices
|
|
|
|
### 6.1. Plugin Load Time Optimization
|
|
|
|
Following Obsidian's performance guidelines is crucial for user experience. The plugin implements several key optimizations:
|
|
|
|
**Load Time Pattern:**
|
|
```typescript
|
|
async onload() {
|
|
// Essential initialization only
|
|
await this.loadSettings();
|
|
this.initializeLightweightServices();
|
|
|
|
// Register view types and commands
|
|
this.registerViews();
|
|
this.addCommands();
|
|
|
|
// Defer expensive operations
|
|
this.app.workspace.onLayoutReady(() => {
|
|
this.initializeAfterLayoutReady();
|
|
});
|
|
}
|
|
|
|
private async initializeAfterLayoutReady() {
|
|
// Minimal cache initialization (lightweight)
|
|
this.cacheManager.initialize();
|
|
|
|
// Heavy service initialization
|
|
await this.pomodoroService.initialize();
|
|
|
|
// Editor services with async imports
|
|
const { TaskLinkDetectionService } = await import('./services/TaskLinkDetectionService');
|
|
}
|
|
```
|
|
|
|
**Developer Best Practices:**
|
|
* **Keep `onload()` lightweight**: Only include essential setup (settings, service constructors, view registration)
|
|
* **Defer expensive operations**: Move heavy service initialization to `onLayoutReady`
|
|
* **Use lazy index building**: Let minimal cache build essential indexes only when first accessed
|
|
* **Use async imports**: Load large services dynamically to reduce initial bundle size
|
|
* **Avoid vault events in constructors**: Register file watchers after layout is ready
|
|
|
|
### 6.2. Native Cache Integration Performance
|
|
|
|
The plugin maximizes Obsidian's native metadata cache performance:
|
|
|
|
**Efficient Native Access Pattern:**
|
|
```typescript
|
|
// Efficient: Direct native cache access
|
|
getTaskInfo(path: string): TaskInfo | null {
|
|
const file = this.app.vault.getAbstractFileByPath(path);
|
|
const metadata = this.app.metadataCache.getFileCache(file); // Already cached!
|
|
return this.extractTaskInfo(path, metadata.frontmatter);
|
|
}
|
|
|
|
// Efficient: Batch native operations
|
|
getAllTasksOfStatus(status: string): TaskInfo[] {
|
|
// Use essential index for paths
|
|
const taskPaths = this.minimalCache.getTaskPathsByStatus(status);
|
|
|
|
// Batch native cache access
|
|
return taskPaths.map(path => this.getTaskInfo(path)).filter(Boolean);
|
|
}
|
|
```
|
|
|
|
**Performance Guidelines:**
|
|
* **Trust native cache speed**: `getFileCache()` is already optimized by Obsidian
|
|
* **Use essential indexes for filtering**: Date and status indexes prevent full scans
|
|
* **Batch operations**: Process multiple files in single operations
|
|
* **Avoid redundant scanning**: Let minimal cache coordinate view updates
|
|
|
|
### 6.3. Memory Efficiency Through Minimal Indexing
|
|
|
|
**Memory Optimization Strategy:**
|
|
```typescript
|
|
// Minimal cache memory footprint
|
|
class MinimalNativeCache {
|
|
// Only 3 essential indexes (~70% reduction from previous approach)
|
|
private tasksByDate: Map<string, Set<string>> = new Map();
|
|
private tasksByStatus: Map<string, Set<string>> = new Map();
|
|
private overdueTasks: Set<string> = new Set();
|
|
|
|
// No redundant data storage - everything comes from native cache
|
|
getTaskInfo(path) {
|
|
return this.extractFromNativeCache(path); // Always fresh
|
|
}
|
|
}
|
|
```
|
|
|
|
**Memory Benefits:**
|
|
* **No duplicate data**: Task info comes directly from native cache
|
|
* **Minimal index storage**: Only path strings in essential indexes
|
|
* **Lazy computation**: Tags, contexts, priorities computed when needed
|
|
* **Automatic cleanup**: Native cache handles file lifecycle
|
|
|
|
### 6.4. Deferred View Compatibility
|
|
|
|
The plugin is compatible with Obsidian v1.7.2+ deferred views:
|
|
|
|
**View Implementation Pattern:**
|
|
```typescript
|
|
export class MyView extends ItemView {
|
|
constructor(leaf: WorkspaceLeaf, plugin: TaskNotesPlugin) {
|
|
super(leaf);
|
|
this.plugin = plugin;
|
|
// Lightweight constructor only
|
|
}
|
|
|
|
async onOpen() {
|
|
// Wait for plugin readiness
|
|
await this.plugin.onReady();
|
|
|
|
// Initialize view with native cache access
|
|
this.initializeView();
|
|
}
|
|
|
|
private async refreshData() {
|
|
// Direct native cache access for fresh data
|
|
const taskPaths = this.plugin.cacheManager.getTasksForDate(this.selectedDate);
|
|
const tasks = await Promise.all(
|
|
taskPaths.map(path => {
|
|
const file = this.app.vault.getAbstractFileByPath(path);
|
|
const metadata = this.app.metadataCache.getFileCache(file);
|
|
return this.extractTaskInfo(path, metadata.frontmatter);
|
|
})
|
|
);
|
|
this.renderTasks(tasks);
|
|
}
|
|
}
|
|
```
|
|
|
|
## 7. External Data Integration
|
|
|
|
### 7.1. ICS Calendar Integration Architecture
|
|
|
|
The plugin supports both remote ICS subscriptions and local ICS files through a unified service architecture:
|
|
|
|
**Service Structure:**
|
|
```typescript
|
|
interface ICSSubscription {
|
|
id: string;
|
|
name: string;
|
|
type: 'remote' | 'local';
|
|
url?: string; // For remote subscriptions
|
|
filePath?: string; // For local files
|
|
color: string;
|
|
enabled: boolean;
|
|
refreshInterval: number;
|
|
}
|
|
```
|
|
|
|
**Implementation Pattern:**
|
|
```typescript
|
|
async fetchSubscription(id: string): Promise<void> {
|
|
const subscription = this.getSubscription(id);
|
|
|
|
let icsData: string;
|
|
if (subscription.type === 'remote') {
|
|
icsData = await this.fetchRemoteICS(subscription.url);
|
|
} else {
|
|
icsData = await this.readLocalICS(subscription.filePath);
|
|
}
|
|
|
|
const events = this.parseICS(icsData);
|
|
this.updateCache(id, events);
|
|
}
|
|
```
|
|
|
|
### 7.2. File Watching for Local Resources
|
|
|
|
Local ICS files are automatically monitored for changes:
|
|
|
|
**File Watcher Pattern:**
|
|
```typescript
|
|
private startFileWatcher(subscription: ICSSubscription): void {
|
|
const modifyRef = this.plugin.app.vault.on('modify', (file) => {
|
|
if (file.path === subscription.filePath) {
|
|
// Debounce changes
|
|
setTimeout(() => this.refreshSubscription(subscription.id), 1000);
|
|
}
|
|
});
|
|
|
|
// Store cleanup function
|
|
this.fileWatchers.set(subscription.id, () => {
|
|
this.plugin.app.vault.offref(modifyRef);
|
|
});
|
|
}
|
|
```
|
|
|
|
**Developer Best Practices:**
|
|
* **Debounce file changes**: Prevent excessive refreshes on rapid file modifications
|
|
* **Store cleanup references**: Always provide proper cleanup in `destroy()` methods
|
|
* **Handle file deletion**: Gracefully handle cases where watched files are removed
|
|
* **Unified interface**: Keep local and remote data sources compatible through consistent interfaces
|
|
|
|
## 8. Error Handling & Data Validation
|
|
|
|
### 8.1. Date/Time Error Prevention
|
|
|
|
The plugin implements robust date parsing to handle various formats with UTC Anchor support:
|
|
|
|
**Safe Date Parsing Pattern:**
|
|
```typescript
|
|
// Always use dateUtils for parsing
|
|
import { parseDateToUTC, parseDateToLocal, validateDateInput, hasTimeComponent } from '../utils/dateUtils';
|
|
|
|
// Good - UTC Anchor approach
|
|
try {
|
|
if (hasTimeComponent(dateString)) {
|
|
// DateTime with explicit time - use local parsing
|
|
const dateTime = parseDateToLocal(dateString);
|
|
// Use for UI display
|
|
} else {
|
|
// Date-only - use UTC anchor
|
|
const date = parseDateToUTC(dateString);
|
|
// Use for internal logic, comparisons
|
|
}
|
|
} catch (error) {
|
|
// Handle invalid date
|
|
}
|
|
|
|
// Bad - Direct Date constructor
|
|
const date = new Date(dateString); // May create unexpected results
|
|
|
|
// Bad - Using deprecated parseDate
|
|
const date = parseDate(dateString); // Use parseDateToUTC or parseDateToLocal instead
|
|
```
|
|
|
|
**Supported Date Formats:**
|
|
* ISO datetime: `2025-02-23T20:28:49`
|
|
* Space-separated: `2025-02-23 20:28:49`
|
|
* Date-only: `2025-02-23` (UTC anchored internally)
|
|
* ISO week: `2025-W02`
|
|
* Timezone-aware: `2025-02-23T20:28:49-05:00`
|
|
|
|
**Common Pitfalls to Avoid:**
|
|
```typescript
|
|
// WRONG: Direct date construction varies by timezone
|
|
const date = new Date('2025-08-01'); // Different results in Tokyo vs LA
|
|
|
|
// RIGHT: UTC anchor ensures consistency
|
|
const date = parseDateToUTC('2025-08-01'); // Same result everywhere
|
|
|
|
// WRONG: Mixing parsing methods
|
|
const date1 = new Date(task.due);
|
|
const date2 = parseDate(task.scheduled);
|
|
|
|
// RIGHT: Consistent parsing approach
|
|
const date1 = parseDateToUTC(task.due);
|
|
const date2 = parseDateToUTC(task.scheduled);
|
|
```
|
|
|
|
### 8.2. Type Safety & Validation
|
|
|
|
**Interface Extension Pattern:**
|
|
```typescript
|
|
// When adding new optional properties
|
|
interface TaskInfo {
|
|
// ... existing properties
|
|
newProperty?: string; // Always optional for backward compatibility
|
|
}
|
|
|
|
// Provide defaults in service layer
|
|
const taskWithDefaults = {
|
|
...existingTask,
|
|
newProperty: existingTask.newProperty || defaultValue
|
|
};
|
|
```
|
|
|
|
**Developer Best Practices:**
|
|
* **Make new properties optional**: Ensures backward compatibility
|
|
* **Validate external data**: Always validate data from external sources
|
|
* **Provide meaningful errors**: Help users understand what went wrong
|
|
* **Graceful degradation**: Continue functioning when optional features fail
|
|
|
|
## 9. Testing & Quality Assurance
|
|
|
|
### 9.1. Manual Testing Checklist
|
|
|
|
When implementing new features, test these scenarios:
|
|
|
|
**Plugin Load Testing:**
|
|
* [ ] Clean Obsidian startup (no existing plugin data)
|
|
* [ ] Startup with existing plugin data
|
|
* [ ] Startup with large vaults (1000+ files)
|
|
* [ ] Hot reload during development
|
|
|
|
**View Testing:**
|
|
* [ ] View opens correctly when deferred
|
|
* [ ] View responds to coordinated data changes
|
|
* [ ] View handles no data gracefully
|
|
* [ ] View cleanup on close
|
|
|
|
**Cache Coordination Testing:**
|
|
* [ ] Multiple views update efficiently on file changes
|
|
* [ ] Essential indexes remain consistent
|
|
* [ ] Native cache integration works correctly
|
|
* [ ] Memory usage remains minimal
|
|
|
|
### 9.2. Performance Testing
|
|
|
|
**Load Time Metrics:**
|
|
* Plugin should add <50ms to Obsidian startup (improved with minimal cache)
|
|
* Views should render within 200ms of opening
|
|
* File operations should not block UI
|
|
|
|
**Memory Usage:**
|
|
* Monitor minimal cache index sizes
|
|
* Ensure proper cleanup of event listeners
|
|
* Verify no memory leaks in long-running sessions
|
|
* Check that native cache integration doesn't duplicate data
|
|
|
|
**Coordination Efficiency:**
|
|
* Single file change should trigger one coordinated update cycle
|
|
* Multiple rapid changes should be batched efficiently
|
|
* View updates should not redundantly scan files
|
|
|
|
This streamlined architecture ensures the plugin remains performant, maintainable, and maximally leverages Obsidian's native capabilities while providing intelligent coordination for optimal view performance.
|
|
|
|
## 10. Quick Reference: UTC Anchor Date Handling
|
|
|
|
### When to Use Each Function
|
|
|
|
| Function | Use Case | Example |
|
|
|----------|----------|---------|
|
|
| `parseDateToUTC()` | Internal logic, comparisons, sorting | `const date = parseDateToUTC('2025-08-01')` |
|
|
| `parseDateToLocal()` | UI display, user input | `const date = parseDateToLocal('2025-08-01')` |
|
|
| `hasTimeComponent()` | Check if string has time | `if (hasTimeComponent(str)) { ... }` |
|
|
| `isBeforeDateSafe()` | Compare date-only strings | `if (isBeforeDateSafe(date1, date2)) { ... }` |
|
|
| `isSameDateSafe()` | Check if same calendar day | `if (isSameDateSafe(date1, date2)) { ... }` |
|
|
| `isOverdueTimeAware()` | Check if task is overdue | `if (isOverdueTimeAware(task.due)) { ... }` |
|
|
| `formatDateForStorage()` | Save to YAML/storage | `const stored = formatDateForStorage(date)` |
|
|
| `getCurrentTimestamp()` | Create timestamps | `task.dateModified = getCurrentTimestamp()` |
|
|
|
|
### Common Patterns
|
|
|
|
```typescript
|
|
// Pattern 1: Processing task dates for logic
|
|
const tasks = allTasks
|
|
.map(task => ({
|
|
...task,
|
|
dueDate: task.due ? parseDateToUTC(task.due) : null
|
|
}))
|
|
.sort((a, b) => a.dueDate.getTime() - b.dueDate.getTime());
|
|
|
|
// Pattern 2: Displaying dates to users
|
|
const displayDate = hasTimeComponent(task.due)
|
|
? format(parseDateToLocal(task.due), 'MMM d, h:mm a')
|
|
: format(parseDateToLocal(task.due), 'MMM d');
|
|
|
|
// Pattern 3: Filtering by date
|
|
const todayTasks = tasks.filter(task =>
|
|
task.due && isSameDateSafe(task.due, getTodayString())
|
|
);
|
|
|
|
// Pattern 4: Consistent date storage
|
|
const updatedTask = {
|
|
...task,
|
|
due: formatDateForStorage(selectedDate),
|
|
dateModified: getCurrentTimestamp()
|
|
};
|
|
```
|
|
|
|
### Do's and Don'ts
|
|
|
|
**DO:**
|
|
- ✅ Use `parseDateToUTC()` for all internal logic
|
|
- ✅ Use `parseDateToLocal()` for UI display
|
|
- ✅ Check `hasTimeComponent()` when handling mixed date types
|
|
- ✅ Use safe comparison functions
|
|
- ✅ Store dates in YYYY-MM-DD format
|
|
|
|
**DON'T:**
|
|
- ❌ Use `new Date(dateString)` directly
|
|
- ❌ Use deprecated `parseDate()` function
|
|
- ❌ Mix parsing methods in the same logic flow
|
|
- ❌ Assume timezone behavior without testing
|
|
- ❌ Compare Date objects from different parsing methods |