@real1ty-obsidian-plugins/utils 2.8.0 → 2.9.0

package/dist/async/change-notifier.d.ts

@@ -0,0 +1,13 @@
+import { type Subscription } from "rxjs";
+/**
+ * Base class that provides observable change notification capabilities.
+ * Eliminates boilerplate for classes that need to notify observers of state changes.
+ */
+export declare abstract class ChangeNotifier {
+    private changeSubject;
+    readonly changes$: import("rxjs").Observable<void>;
+    protected notifyChange(): void;
+    subscribe(observer: () => void): Subscription;
+    destroy(): void;
+}
+//# sourceMappingURL=change-notifier.d.ts.map

package/dist/async/change-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-notifier.d.ts","sourceRoot":"","sources":["../../src/async/change-notifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AAElD;;;GAGG;AACH,8BAAsB,cAAc;IACnC,OAAO,CAAC,aAAa,CAAuB;IAC5C,SAAgB,QAAQ,kCAAqC;IAE7D,SAAS,CAAC,YAAY,IAAI,IAAI;IAQ9B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,YAAY;IAI7C,OAAO,IAAI,IAAI;CAGf"}

package/dist/async/change-notifier.js

@@ -0,0 +1,26 @@
+import { Subject } from "rxjs";
+/**
+ * Base class that provides observable change notification capabilities.
+ * Eliminates boilerplate for classes that need to notify observers of state changes.
+ */
+export class ChangeNotifier {
+    constructor() {
+        this.changeSubject = new Subject();
+        this.changes$ = this.changeSubject.asObservable();
+    }
+    notifyChange() {
+        try {
+            this.changeSubject.next();
+        }
+        catch (error) {
+            console.error("Error notifying change:", error);
+        }
+    }
+    subscribe(observer) {
+        return this.changes$.subscribe(observer);
+    }
+    destroy() {
+        this.changeSubject.complete();
+    }
+}
+//# sourceMappingURL=change-notifier.js.map

package/dist/async/change-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-notifier.js","sourceRoot":"","sources":["../../src/async/change-notifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAqB,MAAM,MAAM,CAAC;AAElD;;;GAGG;AACH,MAAM,OAAgB,cAAc;IAApC;QACS,kBAAa,GAAG,IAAI,OAAO,EAAQ,CAAC;QAC5B,aAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,CAAC;IAiB9D,CAAC;IAfU,YAAY;QACrB,IAAI,CAAC;YACJ,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;QACjD,CAAC;IACF,CAAC;IAED,SAAS,CAAC,QAAoB;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED,OAAO;QACN,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,CAAC;IAC/B,CAAC;CACD","sourcesContent":["import { Subject, type Subscription } from \"rxjs\";\n\n/**\n * Base class that provides observable change notification capabilities.\n * Eliminates boilerplate for classes that need to notify observers of state changes.\n */\nexport abstract class ChangeNotifier {\n\tprivate changeSubject = new Subject<void>();\n\tpublic readonly changes$ = this.changeSubject.asObservable();\n\n\tprotected notifyChange(): void {\n\t\ttry {\n\t\t\tthis.changeSubject.next();\n\t\t} catch (error) {\n\t\t\tconsole.error(\"Error notifying change:\", error);\n\t\t}\n\t}\n\n\tsubscribe(observer: () => void): Subscription {\n\t\treturn this.changes$.subscribe(observer);\n\t}\n\n\tdestroy(): void {\n\t\tthis.changeSubject.complete();\n\t}\n}\n"]}

package/dist/async/debounced-notifier.d.ts

@@ -0,0 +1,26 @@
+import { ChangeNotifier } from "./change-notifier";
+/**
+ * Extends ChangeNotifier with debounced notification capabilities.
+ * Prevents excessive notifications when many changes happen rapidly by batching them.
+ */
+export declare abstract class DebouncedNotifier extends ChangeNotifier {
+    private refreshTimeout;
+    private readonly debounceMs;
+    constructor(debounceMs?: number);
+    /**
+     * Schedules a debounced refresh to prevent excessive notifications.
+     * Batches rapid changes into a single notification after inactivity period.
+     */
+    protected scheduleRefresh(): void;
+    /**
+     * Flushes any pending debounced refresh and immediately notifies subscribers.
+     * Used after batch operations to ensure immediate updates without waiting for debounce.
+     */
+    protected flushPendingRefresh(): void;
+    /**
+     * Checks if there is a pending debounced refresh scheduled.
+     */
+    protected hasPendingRefresh(): boolean;
+    destroy(): void;
+}
+//# sourceMappingURL=debounced-notifier.d.ts.map

package/dist/async/debounced-notifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounced-notifier.d.ts","sourceRoot":"","sources":["../../src/async/debounced-notifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,8BAAsB,iBAAkB,SAAQ,cAAc;IAC7D,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,UAAU,SAAM;IAK5B;;;OAGG;IACH,SAAS,CAAC,eAAe,IAAI,IAAI;IAUjC;;;OAGG;IACH,SAAS,CAAC,mBAAmB,IAAI,IAAI;IAQrC;;OAEG;IACH,SAAS,CAAC,iBAAiB,IAAI,OAAO;IAI7B,OAAO,IAAI,IAAI;CAOxB"}

package/dist/async/debounced-notifier.js

@@ -0,0 +1,50 @@
+import { ChangeNotifier } from "./change-notifier";
+/**
+ * Extends ChangeNotifier with debounced notification capabilities.
+ * Prevents excessive notifications when many changes happen rapidly by batching them.
+ */
+export class DebouncedNotifier extends ChangeNotifier {
+    constructor(debounceMs = 150) {
+        super();
+        this.refreshTimeout = null;
+        this.debounceMs = debounceMs;
+    }
+    /**
+     * Schedules a debounced refresh to prevent excessive notifications.
+     * Batches rapid changes into a single notification after inactivity period.
+     */
+    scheduleRefresh() {
+        if (this.refreshTimeout) {
+            clearTimeout(this.refreshTimeout);
+        }
+        this.refreshTimeout = setTimeout(() => {
+            this.notifyChange();
+            this.refreshTimeout = null;
+        }, this.debounceMs);
+    }
+    /**
+     * Flushes any pending debounced refresh and immediately notifies subscribers.
+     * Used after batch operations to ensure immediate updates without waiting for debounce.
+     */
+    flushPendingRefresh() {
+        if (this.refreshTimeout) {
+            clearTimeout(this.refreshTimeout);
+            this.refreshTimeout = null;
+            this.notifyChange();
+        }
+    }
+    /**
+     * Checks if there is a pending debounced refresh scheduled.
+     */
+    hasPendingRefresh() {
+        return this.refreshTimeout !== null;
+    }
+    destroy() {
+        if (this.refreshTimeout) {
+            clearTimeout(this.refreshTimeout);
+            this.refreshTimeout = null;
+        }
+        super.destroy();
+    }
+}
+//# sourceMappingURL=debounced-notifier.js.map

package/dist/async/debounced-notifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debounced-notifier.js","sourceRoot":"","sources":["../../src/async/debounced-notifier.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD;;;GAGG;AACH,MAAM,OAAgB,iBAAkB,SAAQ,cAAc;IAI7D,YAAY,UAAU,GAAG,GAAG;QAC3B,KAAK,EAAE,CAAC;QAJD,mBAAc,GAAyC,IAAI,CAAC;QAKnE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACO,eAAe;QACxB,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;YACrC,IAAI,CAAC,YAAY,EAAE,CAAC;YACpB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC5B,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACrB,CAAC;IAED;;;OAGG;IACO,mBAAmB;QAC5B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAClC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAC3B,IAAI,CAAC,YAAY,EAAE,CAAC;QACrB,CAAC;IACF,CAAC;IAED;;OAEG;IACO,iBAAiB;QAC1B,OAAO,IAAI,CAAC,cAAc,KAAK,IAAI,CAAC;IACrC,CAAC;IAEQ,OAAO;QACf,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACzB,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAClC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC5B,CAAC;QACD,KAAK,CAAC,OAAO,EAAE,CAAC;IACjB,CAAC;CACD","sourcesContent":["import { ChangeNotifier } from \"./change-notifier\";\n\n/**\n * Extends ChangeNotifier with debounced notification capabilities.\n * Prevents excessive notifications when many changes happen rapidly by batching them.\n */\nexport abstract class DebouncedNotifier extends ChangeNotifier {\n\tprivate refreshTimeout: ReturnType<typeof setTimeout> | null = null;\n\tprivate readonly debounceMs: number;\n\n\tconstructor(debounceMs = 150) {\n\t\tsuper();\n\t\tthis.debounceMs = debounceMs;\n\t}\n\n\t/**\n\t * Schedules a debounced refresh to prevent excessive notifications.\n\t * Batches rapid changes into a single notification after inactivity period.\n\t */\n\tprotected scheduleRefresh(): void {\n\t\tif (this.refreshTimeout) {\n\t\t\tclearTimeout(this.refreshTimeout);\n\t\t}\n\t\tthis.refreshTimeout = setTimeout(() => {\n\t\t\tthis.notifyChange();\n\t\t\tthis.refreshTimeout = null;\n\t\t}, this.debounceMs);\n\t}\n\n\t/**\n\t * Flushes any pending debounced refresh and immediately notifies subscribers.\n\t * Used after batch operations to ensure immediate updates without waiting for debounce.\n\t */\n\tprotected flushPendingRefresh(): void {\n\t\tif (this.refreshTimeout) {\n\t\t\tclearTimeout(this.refreshTimeout);\n\t\t\tthis.refreshTimeout = null;\n\t\t\tthis.notifyChange();\n\t\t}\n\t}\n\n\t/**\n\t * Checks if there is a pending debounced refresh scheduled.\n\t */\n\tprotected hasPendingRefresh(): boolean {\n\t\treturn this.refreshTimeout !== null;\n\t}\n\n\toverride destroy(): void {\n\t\tif (this.refreshTimeout) {\n\t\t\tclearTimeout(this.refreshTimeout);\n\t\t\tthis.refreshTimeout = null;\n\t\t}\n\t\tsuper.destroy();\n\t}\n}\n"]}

package/dist/async/index.d.ts

@@ -1,3 +1,5 @@
 export * from "./async";
 export * from "./batch-operations";
+export * from "./change-notifier";
+export * from "./debounced-notifier";
 //# sourceMappingURL=index.d.ts.map

package/dist/async/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/async/index.js

@@ -1,3 +1,5 @@
 export * from "./async";
 export * from "./batch-operations";
+export * from "./change-notifier";
+export * from "./debounced-notifier";
 //# sourceMappingURL=index.js.map

package/dist/async/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC","sourcesContent":["export * from \"./async\";\nexport * from \"./batch-operations\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC","sourcesContent":["export * from \"./async\";\nexport * from \"./batch-operations\";\nexport * from \"./change-notifier\";\nexport * from \"./debounced-notifier\";\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real1ty-obsidian-plugins/utils",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Shared utilities for Obsidian plugins",
   "type": "module",
   "main": "./dist/index.js",

package/src/async/change-notifier.ts

@@ -0,0 +1,26 @@
+import { Subject, type Subscription } from "rxjs";
+
+/**
+ * Base class that provides observable change notification capabilities.
+ * Eliminates boilerplate for classes that need to notify observers of state changes.
+ */
+export abstract class ChangeNotifier {
+	private changeSubject = new Subject<void>();
+	public readonly changes$ = this.changeSubject.asObservable();
+
+	protected notifyChange(): void {
+		try {
+			this.changeSubject.next();
+		} catch (error) {
+			console.error("Error notifying change:", error);
+		}
+	}
+
+	subscribe(observer: () => void): Subscription {
+		return this.changes$.subscribe(observer);
+	}
+
+	destroy(): void {
+		this.changeSubject.complete();
+	}
+}

package/src/async/debounced-notifier.ts

@@ -0,0 +1,56 @@
+import { ChangeNotifier } from "./change-notifier";
+
+/**
+ * Extends ChangeNotifier with debounced notification capabilities.
+ * Prevents excessive notifications when many changes happen rapidly by batching them.
+ */
+export abstract class DebouncedNotifier extends ChangeNotifier {
+	private refreshTimeout: ReturnType<typeof setTimeout> | null = null;
+	private readonly debounceMs: number;
+
+	constructor(debounceMs = 150) {
+		super();
+		this.debounceMs = debounceMs;
+	}
+
+	/**
+	 * Schedules a debounced refresh to prevent excessive notifications.
+	 * Batches rapid changes into a single notification after inactivity period.
+	 */
+	protected scheduleRefresh(): void {
+		if (this.refreshTimeout) {
+			clearTimeout(this.refreshTimeout);
+		}
+		this.refreshTimeout = setTimeout(() => {
+			this.notifyChange();
+			this.refreshTimeout = null;
+		}, this.debounceMs);
+	}
+
+	/**
+	 * Flushes any pending debounced refresh and immediately notifies subscribers.
+	 * Used after batch operations to ensure immediate updates without waiting for debounce.
+	 */
+	protected flushPendingRefresh(): void {
+		if (this.refreshTimeout) {
+			clearTimeout(this.refreshTimeout);
+			this.refreshTimeout = null;
+			this.notifyChange();
+		}
+	}
+
+	/**
+	 * Checks if there is a pending debounced refresh scheduled.
+	 */
+	protected hasPendingRefresh(): boolean {
+		return this.refreshTimeout !== null;
+	}
+
+	override destroy(): void {
+		if (this.refreshTimeout) {
+			clearTimeout(this.refreshTimeout);
+			this.refreshTimeout = null;
+		}
+		super.destroy();
+	}
+}

package/src/async/index.ts

@@ -1,2 +1,4 @@
 export * from "./async";
 export * from "./batch-operations";
+export * from "./change-notifier";
+export * from "./debounced-notifier";