Architecture

​

Overview

​

Core Components

​

SyncFolds Plugin Class

export default class SyncFolds extends Plugin {
    settings: SyncFoldSettings
    private debounceTimer: number | null = null
    private originalSetItem: typeof Storage.prototype.setItem
    private originalRemoveItem: typeof Storage.prototype.removeItem
    private cachedFolds: FoldStateData = {}

    async onload() { /* ... */ }
    onunload() { /* ... */ }
}

• Initialize localStorage interception
• Manage bidirectional sync between localStorage and plugin settings
• Handle external settings changes from file sync
• Provide manual export/import commands
• Maintain a cached copy of fold states for change detection

​

localStorage Interception Mechanism

interceptLocalStorage() {
    const app = this.app
    const appId = app.appId
    const foldPrefix = `${appId}-note-fold-`

    this.originalSetItem = localStorage.setItem.bind(localStorage)
    this.originalRemoveItem = localStorage.removeItem.bind(localStorage)

    localStorage.setItem = (key: string, value: string) => {
        this.originalSetItem(key, value)
        if (key.startsWith(foldPrefix)) {
            const filePath = key.replace(foldPrefix, '')
            this.debouncedSyncFile(filePath, value)
        }
    }

    localStorage.removeItem = (key: string) => {
        this.originalRemoveItem(key)
        if (key.startsWith(foldPrefix)) {
            const filePath = key.replace(foldPrefix, '')
            this.debouncedSyncFile(filePath, null)
        }
    }
}

• Obsidian stores fold states in localStorage using the pattern {appId}-note-fold-{filePath}
• By intercepting setItem and removeItem, the plugin captures all fold changes without modifying Obsidian’s core behavior
• Original methods are preserved and restored on unload to prevent conflicts

​

Debouncing System

debouncedSyncFile(filePath: string, value: string | null) {
    if (this.debounceTimer !== null) {
        window.clearTimeout(this.debounceTimer)
    }

    this.debounceTimer = window.setTimeout(async () => {
        await this.upsertFoldStateForFile(filePath, value)
        this.debounceTimer = null
    }, 150)
}

• Rapid fold/unfold operations (e.g., keyboard shortcuts) trigger only one write
• Reduces I/O operations and prevents settings file thrashing
• Each new change resets the timer, ensuring only the final state is saved

​

Settings Management

export interface SyncFoldSettings {
    enableSync: boolean
    folds: string  // JSON-serialized FoldStateData
}

export const DEFAULT_SETTINGS: SyncFoldSettings = {
    enableSync: true,
    folds: '{}'
}

// Parse the JSON string into a FoldStateData object
private getFoldsObject(): FoldStateData {
    try {
        return JSON.parse(this.settings.folds)
    } catch (e) {
        console.error('Failed to parse folds string:', e)
        return {}
    }
}

// Serialize FoldStateData object to JSON string
private setFoldsObject(folds: FoldStateData): void {
    this.settings.folds = JSON.stringify(folds)
}

​

External Change Detection

public async onExternalSettingsChange(): Promise<void> {
    const previousFolds = { ...this.cachedFolds }
    await this.loadSettings()
    const currentFolds = this.getFoldsObject()

    const app = this.app 
    const appId = app.appId

    // Remove folds that were deleted
    for (const filePath of Object.keys(previousFolds)) {
        if (!currentFolds[filePath]) {
            const key = `${appId}-note-fold-${filePath}`
            this.originalRemoveItem.call(localStorage, key)
        }
    }

    // Upsert folds that changed
    for (const [filePath, foldData] of Object.entries(currentFolds)) {
        if (JSON.stringify(previousFolds[filePath]) !== JSON.stringify(foldData)) {
            const key = `${appId}-note-fold-${filePath}`
            const value = JSON.stringify(foldData)
            this.originalSetItem.call(localStorage, key, value)
        }
    }

    this.cachedFolds = currentFolds
}

1. Cache the previous fold states before reloading
2. Compare previous and current states by serializing to JSON
3. Remove localStorage entries for deleted folds
4. Update localStorage entries for modified folds
5. Update the cache to reflect the new state

​

Data Structures

​

Fold

export interface Fold {
    from: number  // Starting line number
    to: number    // Ending line number
}

​

FoldedProperties

export interface FoldedProperties {
    folds: Fold[]  // Array of all folded regions in the file
    lines: number  // Total number of lines in the document
}

​

FoldStateData

export interface FoldStateData {
    [filePath: string]: FoldedProperties
}

​

appId-Based Key System

const app = this.app
const appId = app.appId
const foldPrefix = `${appId}-note-fold-`

• Multiple Obsidian vaults on the same device use different appId values
• This prevents fold state collisions between vaults sharing the same localStorage
• The plugin must use the same appId when reading/writing to match Obsidian’s keys

​

Sync Flow Diagrams

​

Local Change → Storage

​

External Change → Local

​

Performance Considerations

​

Caching Strategy

private cachedFolds: FoldStateData = {}

• Enables efficient change detection without re-parsing JSON repeatedly
• Reduces unnecessary localStorage operations when external changes arrive
• Provides a rollback point if settings loading fails

​

Debouncing Parameters

• Be imperceptible to users (< 200ms is considered instant)
• Catch rapid sequences of folds/unfolds (e.g., Ctrl+Shift+[ repeatedly)
• Balance between responsiveness and write reduction

​

Lazy Initialization

if (!this.settings.enableSync) {
    log('Sync disabled, skipping initialization')
    return
}

​

Logging System

declare const DEBUG: boolean

export const log = (...args: unknown[]) => {
    if (DEBUG) {
        console.debug('[SyncFolds]', ...args)
    }
}

• All internal operations are logged via log() calls throughout main.ts
• Logs are only output when DEBUG is true (controlled by build configuration)
• Prefixed with [SyncFolds] for easy filtering in the console
• Uses console.debug() rather than console.log() for semantic clarity

​

Design Decisions

​

Why localStorage Interception?

• File system watching: Would miss in-memory fold changes until file save
• DOM mutation observers: Too low-level, tightly coupled to Obsidian’s rendering
• Polling localStorage: Inefficient, high CPU usage, delayed detection

• Captures changes immediately when Obsidian updates folds
• No dependency on Obsidian’s internal APIs (more stable across updates)
• Clean separation: Obsidian manages folds, plugin syncs them

​

Why Store as JSON String?

folds: string  // JSON-serialized FoldStateData

• Obsidian’s saveData() API requires serializable values
• Storing pre-serialized JSON gives the plugin control over formatting
• Easier to inspect/edit the data.json file manually if needed
• Reduces risk of Obsidian’s serialization introducing inconsistencies

​

Why Manual Commands?

this.addCommand({
    id: 'export-fold-states',
    name: 'Export folds from local storage',
    callback: async () => {
        await this.exportFoldsToFile()
        new Notice('Fold states saved to settings')
    }
})

• Force a sync before switching devices
• Recover from a corrupted cache
• Debugging: verify what’s currently stored
• Manual control for users who prefer explicit actions

​

Thread Safety and Edge Cases

​

Concurrent Changes

1. Rapid local changes: Debouncing ensures only the final state is saved
2. External changes during debounce: The cache comparison in onExternalSettingsChange() detects conflicts
3. Plugin reload: Fresh load from data.json during onload() ensures consistency

​

Cleanup on Unload

onunload() {
    log('Plugin unloading')
    this.restoreLocalStorage()

    if (this.debounceTimer !== null) {
        window.clearTimeout(this.debounceTimer)
    }
}

• Restores original localStorage methods to prevent memory leaks
• Cancels any pending debounced writes to avoid orphaned timers
• Prevents the plugin from interfering with localStorage after unload

​

Mobile Compatibility

• localStorage API is available on mobile WebView environments
• No Node.js or Electron APIs are used
• File I/O is handled through Obsidian’s Plugin base class APIs
• Debouncing uses window.setTimeout, available in all browsers

• Desktop: Windows, macOS, Linux
• Mobile: iOS (via Obsidian mobile app), Android

​

Security and Privacy

• No network requests: All data stays local to the device
• No telemetry: The log() function outputs to the local console only
• Vault-only access: Only reads/writes plugin settings through Obsidian’s API
• No external dependencies: Pure TypeScript, no third-party runtime libraries
• Open source: Code is auditable at the source repository

​

Future Considerations

​

Scalability

• Current approach: Manageable up to ~10,000 files (< 1MB of fold data)
• Potential optimization: Shard fold states across multiple setting keys if needed
• Alternative: Implement a custom file-based storage system

​

Conflict Resolution

• Timestamp-based merge conflict detection
• Per-file merge rather than whole-settings replacement
• User-configurable conflict resolution strategies

​

Selective Sync

• Exclude patterns (e.g., don’t sync folds in .trash/ folder)
• Per-folder sync toggles
• Sync only specific file types