@real1ty-obsidian-plugins/utils 2.6.0 → 2.8.0

package/dist/async/batch-operations.d.ts

@@ -8,4 +8,14 @@ export interface BatchOperationResult {
 }
 export declare function runBatchOperation<T>(items: T[], operationLabel: string, handler: (item: T) => Promise<void>, showResult?: boolean): Promise<BatchOperationResult>;
 export declare function showBatchOperationResult(operation: string, successCount: number, errorCount: number): void;
+/**
+ * Executes an async operation with a lock to prevent concurrent execution for the same key.
+ * If a lock already exists for the key, waits for it to complete instead of starting a new operation.
+ *
+ * @param lockMap - Map storing active locks by key
+ * @param key - Unique identifier for the lock
+ * @param operation - Async function to execute with the lock
+ * @returns Promise resolving to the operation's result
+ */
+export declare function withLock<T>(lockMap: Map<string, Promise<T>>, key: string, operation: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=batch-operations.d.ts.map

package/dist/async/batch-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch-operations.d.ts","sourceRoot":"","sources":["../../src/async/batch-operations.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACxC,KAAK,EAAE,CAAC,EAAE,EACV,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EACnC,UAAU,GAAE,OAAc,GACxB,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;AAED,wBAAgB,wBAAwB,CACvC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAChB,IAAI,CAUN"}
+{"version":3,"file":"batch-operations.d.ts","sourceRoot":"","sources":["../../src/async/batch-operations.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,qBAAqB;IACrC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACxC,KAAK,EAAE,CAAC,EAAE,EACV,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EACnC,UAAU,GAAE,OAAc,GACxB,OAAO,CAAC,oBAAoB,CAAC,CAmB/B;AAED,wBAAgB,wBAAwB,CACvC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GAChB,IAAI,CAUN;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAChC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAkBZ"}

package/dist/async/batch-operations.js

@@ -28,4 +28,33 @@ export function showBatchOperationResult(operation, successCount, errorCount) {
         new Notice(`${operation}: ${successCount} succeeded, ${errorCount} failed. Check console for details.`);
     }
 }
+/**
+ * Executes an async operation with a lock to prevent concurrent execution for the same key.
+ * If a lock already exists for the key, waits for it to complete instead of starting a new operation.
+ *
+ * @param lockMap - Map storing active locks by key
+ * @param key - Unique identifier for the lock
+ * @param operation - Async function to execute with the lock
+ * @returns Promise resolving to the operation's result
+ */
+export function withLock(lockMap, key, operation) {
+    return __awaiter(this, void 0, void 0, function* () {
+        // Check if there's already an operation in progress for this key
+        const existingLock = lockMap.get(key);
+        if (existingLock) {
+            // Wait for the existing operation to complete instead of starting a new one
+            return yield existingLock;
+        }
+        // Create a new locked operation
+        const lockPromise = operation();
+        lockMap.set(key, lockPromise);
+        try {
+            return yield lockPromise;
+        }
+        finally {
+            // Always remove the lock when done
+            lockMap.delete(key);
+        }
+    });
+}
 //# sourceMappingURL=batch-operations.js.map

package/dist/async/batch-operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"batch-operations.js","sourceRoot":"","sources":["../../src/async/batch-operations.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAYlC,MAAM,UAAgB,iBAAiB;yDACtC,KAAU,EACV,cAAsB,EACtB,OAAmC,EACnC,aAAsB,IAAI;QAE1B,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACJ,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;gBACpB,YAAY,EAAE,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,OAAO,CAAC,KAAK,CAAC,GAAG,cAAc,0BAA0B,EAAE,KAAK,CAAC,CAAC;gBAClE,UAAU,EAAE,CAAC;YACd,CAAC;QACF,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YAChB,wBAAwB,CAAC,cAAc,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;QACpE,CAAC;QAED,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;IACrC,CAAC;CAAA;AAED,MAAM,UAAU,wBAAwB,CACvC,SAAiB,EACjB,YAAoB,EACpB,UAAkB;IAElB,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACtB,IAAI,MAAM,CACT,GAAG,SAAS,KAAK,YAAY,QAAQ,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,yBAAyB,CAC3F,CAAC;IACH,CAAC;SAAM,CAAC;QACP,IAAI,MAAM,CACT,GAAG,SAAS,KAAK,YAAY,eAAe,UAAU,qCAAqC,CAC3F,CAAC;IACH,CAAC;AACF,CAAC","sourcesContent":["import { Notice } from \"obsidian\";\n\nexport interface BatchOperationOptions {\n\tcloseAfter?: boolean;\n\tcallOnComplete?: boolean;\n}\n\nexport interface BatchOperationResult {\n\tsuccessCount: number;\n\terrorCount: number;\n}\n\nexport async function runBatchOperation<T>(\n\titems: T[],\n\toperationLabel: string,\n\thandler: (item: T) => Promise<void>,\n\tshowResult: boolean = true\n): Promise<BatchOperationResult> {\n\tlet successCount = 0;\n\tlet errorCount = 0;\n\n\tfor (const item of items) {\n\t\ttry {\n\t\t\tawait handler(item);\n\t\t\tsuccessCount++;\n\t\t} catch (error) {\n\t\t\tconsole.error(`${operationLabel}: error processing item:`, error);\n\t\t\terrorCount++;\n\t\t}\n\t}\n\n\tif (showResult) {\n\t\tshowBatchOperationResult(operationLabel, successCount, errorCount);\n\t}\n\n\treturn { successCount, errorCount };\n}\n\nexport function showBatchOperationResult(\n\toperation: string,\n\tsuccessCount: number,\n\terrorCount: number\n): void {\n\tif (errorCount === 0) {\n\t\tnew Notice(\n\t\t\t`${operation}: ${successCount} item${successCount === 1 ? \"\" : \"s\"} processed successfully`\n\t\t);\n\t} else {\n\t\tnew Notice(\n\t\t\t`${operation}: ${successCount} succeeded, ${errorCount} failed. Check console for details.`\n\t\t);\n\t}\n}\n"]}
+{"version":3,"file":"batch-operations.js","sourceRoot":"","sources":["../../src/async/batch-operations.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAYlC,MAAM,UAAgB,iBAAiB;yDACtC,KAAU,EACV,cAAsB,EACtB,OAAmC,EACnC,aAAsB,IAAI;QAE1B,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,IAAI,UAAU,GAAG,CAAC,CAAC;QAEnB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACJ,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;gBACpB,YAAY,EAAE,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,OAAO,CAAC,KAAK,CAAC,GAAG,cAAc,0BAA0B,EAAE,KAAK,CAAC,CAAC;gBAClE,UAAU,EAAE,CAAC;YACd,CAAC;QACF,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YAChB,wBAAwB,CAAC,cAAc,EAAE,YAAY,EAAE,UAAU,CAAC,CAAC;QACpE,CAAC;QAED,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;IACrC,CAAC;CAAA;AAED,MAAM,UAAU,wBAAwB,CACvC,SAAiB,EACjB,YAAoB,EACpB,UAAkB;IAElB,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACtB,IAAI,MAAM,CACT,GAAG,SAAS,KAAK,YAAY,QAAQ,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,yBAAyB,CAC3F,CAAC;IACH,CAAC;SAAM,CAAC;QACP,IAAI,MAAM,CACT,GAAG,SAAS,KAAK,YAAY,eAAe,UAAU,qCAAqC,CAC3F,CAAC;IACH,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAgB,QAAQ,CAC7B,OAAgC,EAChC,GAAW,EACX,SAA2B;;QAE3B,iEAAiE;QACjE,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,YAAY,EAAE,CAAC;YAClB,4EAA4E;YAC5E,OAAO,MAAM,YAAY,CAAC;QAC3B,CAAC;QAED,gCAAgC;QAChC,MAAM,WAAW,GAAG,SAAS,EAAE,CAAC;QAChC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QAE9B,IAAI,CAAC;YACJ,OAAO,MAAM,WAAW,CAAC;QAC1B,CAAC;gBAAS,CAAC;YACV,mCAAmC;YACnC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACF,CAAC;CAAA","sourcesContent":["import { Notice } from \"obsidian\";\n\nexport interface BatchOperationOptions {\n\tcloseAfter?: boolean;\n\tcallOnComplete?: boolean;\n}\n\nexport interface BatchOperationResult {\n\tsuccessCount: number;\n\terrorCount: number;\n}\n\nexport async function runBatchOperation<T>(\n\titems: T[],\n\toperationLabel: string,\n\thandler: (item: T) => Promise<void>,\n\tshowResult: boolean = true\n): Promise<BatchOperationResult> {\n\tlet successCount = 0;\n\tlet errorCount = 0;\n\n\tfor (const item of items) {\n\t\ttry {\n\t\t\tawait handler(item);\n\t\t\tsuccessCount++;\n\t\t} catch (error) {\n\t\t\tconsole.error(`${operationLabel}: error processing item:`, error);\n\t\t\terrorCount++;\n\t\t}\n\t}\n\n\tif (showResult) {\n\t\tshowBatchOperationResult(operationLabel, successCount, errorCount);\n\t}\n\n\treturn { successCount, errorCount };\n}\n\nexport function showBatchOperationResult(\n\toperation: string,\n\tsuccessCount: number,\n\terrorCount: number\n): void {\n\tif (errorCount === 0) {\n\t\tnew Notice(\n\t\t\t`${operation}: ${successCount} item${successCount === 1 ? \"\" : \"s\"} processed successfully`\n\t\t);\n\t} else {\n\t\tnew Notice(\n\t\t\t`${operation}: ${successCount} succeeded, ${errorCount} failed. Check console for details.`\n\t\t);\n\t}\n}\n\n/**\n * Executes an async operation with a lock to prevent concurrent execution for the same key.\n * If a lock already exists for the key, waits for it to complete instead of starting a new operation.\n *\n * @param lockMap - Map storing active locks by key\n * @param key - Unique identifier for the lock\n * @param operation - Async function to execute with the lock\n * @returns Promise resolving to the operation's result\n */\nexport async function withLock<T>(\n\tlockMap: Map<string, Promise<T>>,\n\tkey: string,\n\toperation: () => Promise<T>\n): Promise<T> {\n\t// Check if there's already an operation in progress for this key\n\tconst existingLock = lockMap.get(key);\n\tif (existingLock) {\n\t\t// Wait for the existing operation to complete instead of starting a new one\n\t\treturn await existingLock;\n\t}\n\n\t// Create a new locked operation\n\tconst lockPromise = operation();\n\tlockMap.set(key, lockPromise);\n\n\ttry {\n\t\treturn await lockPromise;\n\t} finally {\n\t\t// Always remove the lock when done\n\t\tlockMap.delete(key);\n\t}\n}\n"]}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./async";
 export * from "./core";
 export * from "./date";
 export * from "./file";
+export * from "./inputs";
 export * from "./settings";
 export * from "./string";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,SAAS,CAAC;AAExB,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAEvB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAE3B,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,SAAS,CAAC;AAExB,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAEvB,cAAc,QAAQ,CAAC;AAEvB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAE3B,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -7,6 +7,8 @@ export * from "./core";
 export * from "./date";
 // File operations
 export * from "./file";
+// Input utilities
+export * from "./inputs";
 export * from "./settings";
 // String utilities
 export * from "./string";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,WAAW;AAEX,kBAAkB;AAClB,cAAc,SAAS,CAAC;AACxB,iBAAiB;AACjB,cAAc,QAAQ,CAAC;AAEvB,kBAAkB;AAClB,cAAc,QAAQ,CAAC;AACvB,kBAAkB;AAClB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,mBAAmB;AACnB,cAAc,UAAU,CAAC","sourcesContent":["// Settings\n\n// Async utilities\nexport * from \"./async\";\n// Core utilities\nexport * from \"./core\";\n\n// Date operations\nexport * from \"./date\";\n// File operations\nexport * from \"./file\";\nexport * from \"./settings\";\n// String utilities\nexport * from \"./string\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,WAAW;AAEX,kBAAkB;AAClB,cAAc,SAAS,CAAC;AACxB,iBAAiB;AACjB,cAAc,QAAQ,CAAC;AAEvB,kBAAkB;AAClB,cAAc,QAAQ,CAAC;AACvB,kBAAkB;AAClB,cAAc,QAAQ,CAAC;AACvB,kBAAkB;AAClB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,mBAAmB;AACnB,cAAc,UAAU,CAAC","sourcesContent":["// Settings\n\n// Async utilities\nexport * from \"./async\";\n// Core utilities\nexport * from \"./core\";\n\n// Date operations\nexport * from \"./date\";\n// File operations\nexport * from \"./file\";\n// Input utilities\nexport * from \"./inputs\";\nexport * from \"./settings\";\n// String utilities\nexport * from \"./string\";\n"]}

package/dist/inputs/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./input-filter-manager";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/inputs/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/inputs/index.js

@@ -0,0 +1,2 @@
+export * from "./input-filter-manager";
+//# sourceMappingURL=index.js.map

package/dist/inputs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/inputs/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC","sourcesContent":["export * from \"./input-filter-manager\";\n"]}

package/dist/inputs/input-filter-manager.d.ts

@@ -0,0 +1,72 @@
+export type FilterChangeCallback = (filterValue: string) => void;
+export interface InputFilterManagerOptions {
+    placeholder: string;
+    cssClass: string;
+    cssPrefix: string;
+    onFilterChange: FilterChangeCallback;
+    initiallyVisible?: boolean;
+    onHide?: () => void;
+    debounceMs?: number;
+}
+/**
+ * Abstract base class for managing input-based filters with debouncing.
+ * Provides a reusable pattern for filter inputs with show/hide functionality,
+ * keyboard shortcuts, and debounced updates.
+ *
+ * @template T - The type of data being filtered (optional, defaults to unknown)
+ *
+ * @example
+ * ```ts
+ * class MyFilterManager extends InputFilterManager<MyDataType> {
+ *   shouldInclude(data: MyDataType): boolean {
+ *     const filter = this.getCurrentValue().toLowerCase();
+ *     return data.name.toLowerCase().includes(filter);
+ *   }
+ * }
+ *
+ * const manager = new MyFilterManager(
+ *   containerEl,
+ *   {
+ *     placeholder: "Filter items...",
+ *     cssClass: "my-filter-input",
+ *     onFilterChange: (value) => console.log("Filter changed:", value),
+ *     initiallyVisible: false,
+ *   }
+ * );
+ * ```
+ */
+export declare abstract class InputFilterManager<T> {
+    protected parentEl: HTMLElement;
+    protected containerEl: HTMLElement;
+    protected inputEl: HTMLInputElement | null;
+    protected debounceTimer: number | null;
+    protected currentValue: string;
+    protected persistentlyVisible: boolean;
+    protected onHide?: () => void;
+    protected readonly debounceMs: number;
+    protected readonly placeholder: string;
+    protected readonly cssClass: string;
+    protected readonly cssPrefix: string;
+    protected readonly onFilterChange: FilterChangeCallback;
+    constructor(parentEl: HTMLElement, options: InputFilterManagerOptions);
+    private render;
+    private handleInputChange;
+    private applyFilterImmediately;
+    protected updateFilterValue(value: string): void;
+    getCurrentValue(): string;
+    show(): void;
+    hide(): void;
+    focus(): void;
+    isVisible(): boolean;
+    setPersistentlyVisible(value: boolean): void;
+    destroy(): void;
+    /**
+     * Abstract method that subclasses must implement to determine
+     * whether a data item should be included based on the current filter.
+     *
+     * @param data - The data item to check
+     * @returns True if the item should be included, false otherwise
+     */
+    abstract shouldInclude(data: T): boolean;
+}
+//# sourceMappingURL=input-filter-manager.d.ts.map

package/dist/inputs/input-filter-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-filter-manager.d.ts","sourceRoot":"","sources":["../../src/inputs/input-filter-manager.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;AAIjE,MAAM,WAAW,yBAAyB;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,oBAAoB,CAAC;IACrC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,8BAAsB,kBAAkB,CAAC,CAAC;IAcxC,SAAS,CAAC,QAAQ,EAAE,WAAW;IAbhC,SAAS,CAAC,WAAW,EAAE,WAAW,CAAC;IACnC,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAQ;IAClD,SAAS,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC9C,SAAS,CAAC,YAAY,SAAM;IAC5B,SAAS,CAAC,mBAAmB,UAAS;IACtC,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IACtC,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IACvC,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IACpC,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,cAAc,EAAE,oBAAoB,CAAC;gBAG7C,QAAQ,EAAE,WAAW,EAC/B,OAAO,EAAE,yBAAyB;IA2BnC,OAAO,CAAC,MAAM;IA0Bd,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,sBAAsB;IAQ9B,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAKhD,eAAe,IAAI,MAAM;IAIzB,IAAI,IAAI,IAAI;IAKZ,IAAI,IAAI,IAAI;IAgBZ,KAAK,IAAI,IAAI;IAIb,SAAS,IAAI,OAAO;IAIpB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAU5C,OAAO,IAAI,IAAI;IAUf;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO;CACxC"}

package/dist/inputs/input-filter-manager.js

@@ -0,0 +1,140 @@
+const DEFAULT_DEBOUNCE_MS = 150;
+/**
+ * Abstract base class for managing input-based filters with debouncing.
+ * Provides a reusable pattern for filter inputs with show/hide functionality,
+ * keyboard shortcuts, and debounced updates.
+ *
+ * @template T - The type of data being filtered (optional, defaults to unknown)
+ *
+ * @example
+ * ```ts
+ * class MyFilterManager extends InputFilterManager<MyDataType> {
+ *   shouldInclude(data: MyDataType): boolean {
+ *     const filter = this.getCurrentValue().toLowerCase();
+ *     return data.name.toLowerCase().includes(filter);
+ *   }
+ * }
+ *
+ * const manager = new MyFilterManager(
+ *   containerEl,
+ *   {
+ *     placeholder: "Filter items...",
+ *     cssClass: "my-filter-input",
+ *     onFilterChange: (value) => console.log("Filter changed:", value),
+ *     initiallyVisible: false,
+ *   }
+ * );
+ * ```
+ */
+export class InputFilterManager {
+    constructor(parentEl, options) {
+        this.parentEl = parentEl;
+        this.inputEl = null;
+        this.debounceTimer = null;
+        this.currentValue = "";
+        this.persistentlyVisible = false;
+        const { placeholder, cssClass, cssPrefix, onFilterChange, initiallyVisible = false, onHide, debounceMs = DEFAULT_DEBOUNCE_MS, } = options;
+        this.debounceMs = debounceMs;
+        this.placeholder = placeholder;
+        this.cssClass = cssClass;
+        this.cssPrefix = cssPrefix;
+        this.onFilterChange = onFilterChange;
+        this.onHide = onHide;
+        const classes = `${cssClass}-container${initiallyVisible ? "" : ` ${cssPrefix}-hidden`}`;
+        this.containerEl = this.parentEl.createEl("div", {
+            cls: classes,
+        });
+        this.render();
+    }
+    render() {
+        this.inputEl = this.containerEl.createEl("input", {
+            type: "text",
+            cls: this.cssClass,
+            placeholder: this.placeholder,
+        });
+        this.inputEl.addEventListener("input", () => {
+            this.handleInputChange();
+        });
+        this.inputEl.addEventListener("keydown", (evt) => {
+            var _a;
+            if (evt.key === "Escape") {
+                // Only allow hiding if not persistently visible
+                if (!this.persistentlyVisible) {
+                    this.hide();
+                }
+                else {
+                    // Just blur the input if persistently visible
+                    (_a = this.inputEl) === null || _a === void 0 ? void 0 : _a.blur();
+                }
+            }
+            else if (evt.key === "Enter") {
+                this.applyFilterImmediately();
+            }
+        });
+    }
+    handleInputChange() {
+        if (this.debounceTimer !== null) {
+            window.clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = window.setTimeout(() => {
+            this.applyFilterImmediately();
+        }, this.debounceMs);
+    }
+    applyFilterImmediately() {
+        var _a, _b;
+        const newValue = (_b = (_a = this.inputEl) === null || _a === void 0 ? void 0 : _a.value.trim()) !== null && _b !== void 0 ? _b : "";
+        if (newValue !== this.currentValue) {
+            this.updateFilterValue(newValue);
+        }
+    }
+    updateFilterValue(value) {
+        this.currentValue = value;
+        this.onFilterChange(value);
+    }
+    getCurrentValue() {
+        return this.currentValue;
+    }
+    show() {
+        var _a;
+        this.containerEl.removeClass(`${this.cssPrefix}-hidden`);
+        (_a = this.inputEl) === null || _a === void 0 ? void 0 : _a.focus();
+    }
+    hide() {
+        var _a;
+        // Don't allow hiding if persistently visible
+        if (this.persistentlyVisible) {
+            return;
+        }
+        this.containerEl.addClass(`${this.cssPrefix}-hidden`);
+        if (this.inputEl) {
+            this.inputEl.value = "";
+        }
+        this.updateFilterValue("");
+        (_a = this.onHide) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    focus() {
+        var _a;
+        (_a = this.inputEl) === null || _a === void 0 ? void 0 : _a.focus();
+    }
+    isVisible() {
+        return !this.containerEl.hasClass(`${this.cssPrefix}-hidden`);
+    }
+    setPersistentlyVisible(value) {
+        this.persistentlyVisible = value;
+        if (value) {
+            this.show();
+        }
+        else {
+            this.hide();
+        }
+    }
+    destroy() {
+        if (this.debounceTimer !== null) {
+            window.clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        this.containerEl.remove();
+        this.inputEl = null;
+    }
+}
+//# sourceMappingURL=input-filter-manager.js.map

package/dist/inputs/input-filter-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-filter-manager.js","sourceRoot":"","sources":["../../src/inputs/input-filter-manager.ts"],"names":[],"mappings":"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","sourcesContent":["export type FilterChangeCallback = (filterValue: string) => void;\n\nconst DEFAULT_DEBOUNCE_MS = 150;\n\nexport interface InputFilterManagerOptions {\n\tplaceholder: string;\n\tcssClass: string;\n\tcssPrefix: string;\n\tonFilterChange: FilterChangeCallback;\n\tinitiallyVisible?: boolean;\n\tonHide?: () => void;\n\tdebounceMs?: number;\n}\n\n/**\n * Abstract base class for managing input-based filters with debouncing.\n * Provides a reusable pattern for filter inputs with show/hide functionality,\n * keyboard shortcuts, and debounced updates.\n *\n * @template T - The type of data being filtered (optional, defaults to unknown)\n *\n * @example\n * ```ts\n * class MyFilterManager extends InputFilterManager<MyDataType> {\n *   shouldInclude(data: MyDataType): boolean {\n *     const filter = this.getCurrentValue().toLowerCase();\n *     return data.name.toLowerCase().includes(filter);\n *   }\n * }\n *\n * const manager = new MyFilterManager(\n *   containerEl,\n *   {\n *     placeholder: \"Filter items...\",\n *     cssClass: \"my-filter-input\",\n *     onFilterChange: (value) => console.log(\"Filter changed:\", value),\n *     initiallyVisible: false,\n *   }\n * );\n * ```\n */\nexport abstract class InputFilterManager<T> {\n\tprotected containerEl: HTMLElement;\n\tprotected inputEl: HTMLInputElement | null = null;\n\tprotected debounceTimer: number | null = null;\n\tprotected currentValue = \"\";\n\tprotected persistentlyVisible = false;\n\tprotected onHide?: () => void;\n\tprotected readonly debounceMs: number;\n\tprotected readonly placeholder: string;\n\tprotected readonly cssClass: string;\n\tprotected readonly cssPrefix: string;\n\tprotected readonly onFilterChange: FilterChangeCallback;\n\n\tconstructor(\n\t\tprotected parentEl: HTMLElement,\n\t\toptions: InputFilterManagerOptions\n\t) {\n\t\tconst {\n\t\t\tplaceholder,\n\t\t\tcssClass,\n\t\t\tcssPrefix,\n\t\t\tonFilterChange,\n\t\t\tinitiallyVisible = false,\n\t\t\tonHide,\n\t\t\tdebounceMs = DEFAULT_DEBOUNCE_MS,\n\t\t} = options;\n\n\t\tthis.debounceMs = debounceMs;\n\t\tthis.placeholder = placeholder;\n\t\tthis.cssClass = cssClass;\n\t\tthis.cssPrefix = cssPrefix;\n\t\tthis.onFilterChange = onFilterChange;\n\t\tthis.onHide = onHide;\n\n\t\tconst classes = `${cssClass}-container${initiallyVisible ? \"\" : ` ${cssPrefix}-hidden`}`;\n\t\tthis.containerEl = this.parentEl.createEl(\"div\", {\n\t\t\tcls: classes,\n\t\t});\n\n\t\tthis.render();\n\t}\n\n\tprivate render(): void {\n\t\tthis.inputEl = this.containerEl.createEl(\"input\", {\n\t\t\ttype: \"text\",\n\t\t\tcls: this.cssClass,\n\t\t\tplaceholder: this.placeholder,\n\t\t});\n\n\t\tthis.inputEl.addEventListener(\"input\", () => {\n\t\t\tthis.handleInputChange();\n\t\t});\n\n\t\tthis.inputEl.addEventListener(\"keydown\", (evt) => {\n\t\t\tif (evt.key === \"Escape\") {\n\t\t\t\t// Only allow hiding if not persistently visible\n\t\t\t\tif (!this.persistentlyVisible) {\n\t\t\t\t\tthis.hide();\n\t\t\t\t} else {\n\t\t\t\t\t// Just blur the input if persistently visible\n\t\t\t\t\tthis.inputEl?.blur();\n\t\t\t\t}\n\t\t\t} else if (evt.key === \"Enter\") {\n\t\t\t\tthis.applyFilterImmediately();\n\t\t\t}\n\t\t});\n\t}\n\n\tprivate handleInputChange(): void {\n\t\tif (this.debounceTimer !== null) {\n\t\t\twindow.clearTimeout(this.debounceTimer);\n\t\t}\n\n\t\tthis.debounceTimer = window.setTimeout(() => {\n\t\t\tthis.applyFilterImmediately();\n\t\t}, this.debounceMs);\n\t}\n\n\tprivate applyFilterImmediately(): void {\n\t\tconst newValue = this.inputEl?.value.trim() ?? \"\";\n\n\t\tif (newValue !== this.currentValue) {\n\t\t\tthis.updateFilterValue(newValue);\n\t\t}\n\t}\n\n\tprotected updateFilterValue(value: string): void {\n\t\tthis.currentValue = value;\n\t\tthis.onFilterChange(value);\n\t}\n\n\tgetCurrentValue(): string {\n\t\treturn this.currentValue;\n\t}\n\n\tshow(): void {\n\t\tthis.containerEl.removeClass(`${this.cssPrefix}-hidden`);\n\t\tthis.inputEl?.focus();\n\t}\n\n\thide(): void {\n\t\t// Don't allow hiding if persistently visible\n\t\tif (this.persistentlyVisible) {\n\t\t\treturn;\n\t\t}\n\n\t\tthis.containerEl.addClass(`${this.cssPrefix}-hidden`);\n\n\t\tif (this.inputEl) {\n\t\t\tthis.inputEl.value = \"\";\n\t\t}\n\n\t\tthis.updateFilterValue(\"\");\n\t\tthis.onHide?.();\n\t}\n\n\tfocus(): void {\n\t\tthis.inputEl?.focus();\n\t}\n\n\tisVisible(): boolean {\n\t\treturn !this.containerEl.hasClass(`${this.cssPrefix}-hidden`);\n\t}\n\n\tsetPersistentlyVisible(value: boolean): void {\n\t\tthis.persistentlyVisible = value;\n\n\t\tif (value) {\n\t\t\tthis.show();\n\t\t} else {\n\t\t\tthis.hide();\n\t\t}\n\t}\n\n\tdestroy(): void {\n\t\tif (this.debounceTimer !== null) {\n\t\t\twindow.clearTimeout(this.debounceTimer);\n\t\t\tthis.debounceTimer = null;\n\t\t}\n\n\t\tthis.containerEl.remove();\n\t\tthis.inputEl = null;\n\t}\n\n\t/**\n\t * Abstract method that subclasses must implement to determine\n\t * whether a data item should be included based on the current filter.\n\t *\n\t * @param data - The data item to check\n\t * @returns True if the item should be included, false otherwise\n\t */\n\tabstract shouldInclude(data: T): boolean;\n}\n"]}

package/package.json

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

package/src/async/batch-operations.ts

@@ -51,3 +51,36 @@ export function showBatchOperationResult(
 		);
 	}
 }
+
+/**
+ * Executes an async operation with a lock to prevent concurrent execution for the same key.
+ * If a lock already exists for the key, waits for it to complete instead of starting a new operation.
+ *
+ * @param lockMap - Map storing active locks by key
+ * @param key - Unique identifier for the lock
+ * @param operation - Async function to execute with the lock
+ * @returns Promise resolving to the operation's result
+ */
+export async function withLock<T>(
+	lockMap: Map<string, Promise<T>>,
+	key: string,
+	operation: () => Promise<T>
+): Promise<T> {
+	// Check if there's already an operation in progress for this key
+	const existingLock = lockMap.get(key);
+	if (existingLock) {
+		// Wait for the existing operation to complete instead of starting a new one
+		return await existingLock;
+	}
+
+	// Create a new locked operation
+	const lockPromise = operation();
+	lockMap.set(key, lockPromise);
+
+	try {
+		return await lockPromise;
+	} finally {
+		// Always remove the lock when done
+		lockMap.delete(key);
+	}
+}

package/src/index.ts

@@ -9,6 +9,8 @@ export * from "./core";
 export * from "./date";
 // File operations
 export * from "./file";
+// Input utilities
+export * from "./inputs";
 export * from "./settings";
 // String utilities
 export * from "./string";

package/src/inputs/index.ts

@@ -0,0 +1 @@
+export * from "./input-filter-manager";

package/src/inputs/input-filter-manager.ts

@@ -0,0 +1,194 @@
+export type FilterChangeCallback = (filterValue: string) => void;
+
+const DEFAULT_DEBOUNCE_MS = 150;
+
+export interface InputFilterManagerOptions {
+	placeholder: string;
+	cssClass: string;
+	cssPrefix: string;
+	onFilterChange: FilterChangeCallback;
+	initiallyVisible?: boolean;
+	onHide?: () => void;
+	debounceMs?: number;
+}
+
+/**
+ * Abstract base class for managing input-based filters with debouncing.
+ * Provides a reusable pattern for filter inputs with show/hide functionality,
+ * keyboard shortcuts, and debounced updates.
+ *
+ * @template T - The type of data being filtered (optional, defaults to unknown)
+ *
+ * @example
+ * ```ts
+ * class MyFilterManager extends InputFilterManager<MyDataType> {
+ *   shouldInclude(data: MyDataType): boolean {
+ *     const filter = this.getCurrentValue().toLowerCase();
+ *     return data.name.toLowerCase().includes(filter);
+ *   }
+ * }
+ *
+ * const manager = new MyFilterManager(
+ *   containerEl,
+ *   {
+ *     placeholder: "Filter items...",
+ *     cssClass: "my-filter-input",
+ *     onFilterChange: (value) => console.log("Filter changed:", value),
+ *     initiallyVisible: false,
+ *   }
+ * );
+ * ```
+ */
+export abstract class InputFilterManager<T> {
+	protected containerEl: HTMLElement;
+	protected inputEl: HTMLInputElement | null = null;
+	protected debounceTimer: number | null = null;
+	protected currentValue = "";
+	protected persistentlyVisible = false;
+	protected onHide?: () => void;
+	protected readonly debounceMs: number;
+	protected readonly placeholder: string;
+	protected readonly cssClass: string;
+	protected readonly cssPrefix: string;
+	protected readonly onFilterChange: FilterChangeCallback;
+
+	constructor(
+		protected parentEl: HTMLElement,
+		options: InputFilterManagerOptions
+	) {
+		const {
+			placeholder,
+			cssClass,
+			cssPrefix,
+			onFilterChange,
+			initiallyVisible = false,
+			onHide,
+			debounceMs = DEFAULT_DEBOUNCE_MS,
+		} = options;
+
+		this.debounceMs = debounceMs;
+		this.placeholder = placeholder;
+		this.cssClass = cssClass;
+		this.cssPrefix = cssPrefix;
+		this.onFilterChange = onFilterChange;
+		this.onHide = onHide;
+
+		const classes = `${cssClass}-container${initiallyVisible ? "" : ` ${cssPrefix}-hidden`}`;
+		this.containerEl = this.parentEl.createEl("div", {
+			cls: classes,
+		});
+
+		this.render();
+	}
+
+	private render(): void {
+		this.inputEl = this.containerEl.createEl("input", {
+			type: "text",
+			cls: this.cssClass,
+			placeholder: this.placeholder,
+		});
+
+		this.inputEl.addEventListener("input", () => {
+			this.handleInputChange();
+		});
+
+		this.inputEl.addEventListener("keydown", (evt) => {
+			if (evt.key === "Escape") {
+				// Only allow hiding if not persistently visible
+				if (!this.persistentlyVisible) {
+					this.hide();
+				} else {
+					// Just blur the input if persistently visible
+					this.inputEl?.blur();
+				}
+			} else if (evt.key === "Enter") {
+				this.applyFilterImmediately();
+			}
+		});
+	}
+
+	private handleInputChange(): void {
+		if (this.debounceTimer !== null) {
+			window.clearTimeout(this.debounceTimer);
+		}
+
+		this.debounceTimer = window.setTimeout(() => {
+			this.applyFilterImmediately();
+		}, this.debounceMs);
+	}
+
+	private applyFilterImmediately(): void {
+		const newValue = this.inputEl?.value.trim() ?? "";
+
+		if (newValue !== this.currentValue) {
+			this.updateFilterValue(newValue);
+		}
+	}
+
+	protected updateFilterValue(value: string): void {
+		this.currentValue = value;
+		this.onFilterChange(value);
+	}
+
+	getCurrentValue(): string {
+		return this.currentValue;
+	}
+
+	show(): void {
+		this.containerEl.removeClass(`${this.cssPrefix}-hidden`);
+		this.inputEl?.focus();
+	}
+
+	hide(): void {
+		// Don't allow hiding if persistently visible
+		if (this.persistentlyVisible) {
+			return;
+		}
+
+		this.containerEl.addClass(`${this.cssPrefix}-hidden`);
+
+		if (this.inputEl) {
+			this.inputEl.value = "";
+		}
+
+		this.updateFilterValue("");
+		this.onHide?.();
+	}
+
+	focus(): void {
+		this.inputEl?.focus();
+	}
+
+	isVisible(): boolean {
+		return !this.containerEl.hasClass(`${this.cssPrefix}-hidden`);
+	}
+
+	setPersistentlyVisible(value: boolean): void {
+		this.persistentlyVisible = value;
+
+		if (value) {
+			this.show();
+		} else {
+			this.hide();
+		}
+	}
+
+	destroy(): void {
+		if (this.debounceTimer !== null) {
+			window.clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+
+		this.containerEl.remove();
+		this.inputEl = null;
+	}
+
+	/**
+	 * Abstract method that subclasses must implement to determine
+	 * whether a data item should be included based on the current filter.
+	 *
+	 * @param data - The data item to check
+	 * @returns True if the item should be included, false otherwise
+	 */
+	abstract shouldInclude(data: T): boolean;
+}