@talex-touch/utils 1.0.18 → 1.0.21

package/channel/index.ts

@@ -21,6 +21,7 @@ export interface ITouchChannel {
   regChannel(type: ChannelType, eventName: string, callback: (data: StandardChannelData) => any): () => void
 
   /**
+   * @deprecated Use sendMain instead
    * Send a message to a channel
    * @param type {@link ChannelType} The type of channel
    * @param eventName {string} The name of event, must be unique in the channel {@link ChannelType}
@@ -29,6 +30,7 @@ export interface ITouchChannel {
   send(type: ChannelType, eventName: string, arg?: any): Promise<any>
 
   /**
+   * @deprecated Use sendToMain instead
    * Send a message to a channel with settled window
    * @param win {@link Electron.BrowserWindow} the window you want to sent
    * @param type {@link ChannelType} The type of channel
@@ -36,6 +38,51 @@ export interface ITouchChannel {
    * @param arg {any} The arguments of the message
    */
   sendTo(win: Electron.BrowserWindow, type: ChannelType, eventName: string, arg: any): Promise<any>
+
+  /**
+   * Send a message to main process
+   * @param eventName {string} The name of event, must be unique in the channel {@link ChannelType}
+   * @param arg {any} The arguments of the message
+   */
+  sendMain(eventName: string, arg?: any): Promise<any>
+
+  /**
+   * Send a message to main process with settled window
+   * @param win {@link Electron.BrowserWindow} the window you want to sent
+   * @param eventName {string} The name of event, must be unique in the channel {@link ChannelType}
+   * @param arg {any} The arguments of the message
+   */
+  sendToMain(win: Electron.BrowserWindow, eventName: string, arg?: any): Promise<any>
+
+  /**
+   * Send a message to all plugin process with settled window
+   * @param eventName {string} The name of event, must be unique in the channel {@link ChannelType}
+   * @param arg {any} The arguments of the message
+   */
+  sendPlugin(pluginName: string, eventName: string, arg?: any): Promise<any>
+
+  /**
+   * Send a message to plugin process with settled window
+   * @param pluginName {string} The name of plugin
+   * @param eventName {string} The name of event, must be unique in the channel {@link ChannelType}
+   * @param arg {any} The arguments of the message
+   */
+  sendToPlugin(pluginName: string, eventName: string, arg?: any): Promise<any>
+
+  /**
+   * Request a encrypted name key. This key cannot decrypted to get the original name.
+   * After use, you should revoke this key.
+   * @description Request a encrypted name key, and return the encrypted key
+   * @param name {string} The name of key
+   */
+  requestKey: (name: string) => string
+
+  /**
+   * Unregister a encrypted name key
+   * @description Unregister a encrypted name key, and return the encrypted key
+   * @param key {string} The encrypted key
+   */
+  revokeKey: (key: string) => boolean
 }
 
 export interface ITouchClientChannel {
@@ -84,6 +131,7 @@ export interface RawChannelHeaderData {
   status: "reply" | "request";
   type: ChannelType;
   _originData?: any;
+  uniqueKey?: string
   event?: Electron.IpcMainEvent | Electron.IpcRendererEvent;
 }
 
@@ -105,4 +153,4 @@ export interface StandardChannelData extends RawStandardChannelData {
 
 export type IChannelData = any //boolean | number | string | null | undefined | {
   // [prop: string]: any
-// }
+// }

package/common/index.ts

@@ -1,2 +1,4 @@
 export * from './storage/index'
 export * from './utils'
+export * from './search'
+export * from '../electron/file-parsers'

package/common/search/gather.ts

@@ -0,0 +1,45 @@
+import { TuffUpdate } from "."
+
+/**
+ * @interface ITuffGatherOptions
+ * @description Configuration options for the search result aggregator.
+ */
+export interface ITuffGatherOptions {
+  /**
+   * The number of providers to run in parallel.
+   * @default 3
+   */
+  concurrency?: number
+  /**
+   * The time to wait for more results before flushing the buffer.
+   * @default 100
+   */
+  coalesceGapMs?: number
+  /**
+   * A shorter grace period for the first batch to ensure a quick initial response.
+   * @default 50
+   */
+  firstBatchGraceMs?: number
+  /**
+   * A small debounce delay for the push function to avoid rapid-fire updates.
+   * @default 10
+   */
+  debouncePushMs?: number
+  /**
+   * The maximum time to wait for a single provider to return results.
+   * @default 5000
+   */
+  taskTimeoutMs?: number
+}
+
+/**
+ * Defines the type signature for the real-time update callback function.
+ * @param update - The data object containing update information.
+ */
+export type TuffAggregatorCallback = (update: TuffUpdate) => void
+
+export interface IGatherController {
+  abort: () => void
+  promise: Promise<number>
+  signal: AbortSignal
+}

package/common/search/index.ts

@@ -0,0 +1,67 @@
+import { ISearchProvider, TuffQuery, TuffSearchResult } from '@talex-touch/utils'
+
+export * from './gather'
+
+/**
+ * Represents a single update pushed from the search-gatherer.
+ * It provides a snapshot of the search progress at a point in time.
+ */
+export interface TuffUpdate {
+  /**
+   * New search results from the current push batch.
+   * Each element is a complete TuffSearchResult from a provider.
+   */
+  newResults: TuffSearchResult[]
+  /**
+   * Total number of items aggregated so far.
+   */
+  totalCount: number
+  /**
+   * Flag indicating whether all search tasks (both default and fallback queues) have completed.
+   */
+  isDone: boolean
+  /**
+   * Flag indicating whether the search was cancelled.
+   */
+  cancelled?: boolean
+  /**
+   * Statistics about the performance of each search provider.
+   */
+  sourceStats?: TuffSearchResult['sources']
+}
+
+
+/**
+ * Search Engine Interface (formerly ISearchEngine)
+ *
+ * Defines the core functionality of the search aggregator and orchestrator.
+ */
+export interface ISearchEngine<C> {
+  /**
+   * Registers a search provider with the engine.
+   * @param provider - An instance of ISearchProvider.
+   */
+  registerProvider(provider: ISearchProvider<C>): void
+
+  /**
+   * Unregisters a search provider by its unique ID.
+   * @param providerId - The unique ID of the provider to remove.
+   */
+  unregisterProvider(providerId: string): void
+
+  /**
+   * Executes a search across all registered and relevant providers.
+   * It aggregates, scores, and ranks the results.
+   *
+   * @param query - The search query object.
+   * @returns A promise that resolves to a TuffSearchResult object,
+   *          containing the ranked items and metadata about the search operation.
+   */
+  search(query: TuffQuery): Promise<TuffSearchResult>
+
+  /**
+   * Performs background maintenance tasks, such as pre-heating caches,
+   * refreshing indexes, etc.
+   */
+  maintain(): void
+}

package/common/storage/constants.ts

@@ -1,3 +1,17 @@
 export enum StorageList {
-  APP_SETTING = "app-setting.ini"
-}
+  APP_SETTING = 'app-setting.ini',
+  SHORTCUT_SETTING = 'shortcut-setting.ini',
+  OPENERS = 'openers.json'
+}
+
+/**
+ * Defines keys for the global configuration stored in the database `config` table.
+ * Using an enum prevents magic strings and ensures consistency across the application.
+ */
+export enum ConfigKeys {
+  /**
+   * Stores the timestamp of the last successful full application scan using mdfind.
+   * This is used to schedule the next comprehensive scan.
+   */
+  APP_PROVIDER_LAST_MDFIND_SCAN = 'app_provider_last_mdfind_scan'
+}

package/common/storage/entity/index.ts

@@ -1 +1,2 @@
-export * from './app-settings'
+export * from './app-settings'
+export * from './openers'

package/common/storage/entity/openers.ts

@@ -0,0 +1,32 @@
+export interface OpenerInfo {
+  /**
+   * Bundle identifier of the application responsible for handling the file type.
+   */
+  bundleId: string
+
+  /**
+   * Display name of the application.
+   */
+  name: string
+
+  /**
+   * Icon for the application (data URL or resolvable path).
+   */
+  logo: string
+
+  /**
+   * Absolute path of the application bundle/executable.
+   */
+  path?: string
+
+  /**
+   * ISO timestamp representing when this mapping was last refreshed.
+   */
+  lastResolvedAt?: string
+}
+
+export type OpenersMap = Record<string, OpenerInfo>
+
+const _openersOriginData: OpenersMap = {}
+
+export const openersOriginData = Object.freeze(_openersOriginData)

package/common/storage/entity/shortcut-settings.ts

@@ -0,0 +1,22 @@
+export enum ShortcutType {
+  MAIN = 'main',
+  RENDERER = 'renderer',
+}
+
+export interface ShortcutMeta {
+  creationTime: number;
+  modificationTime: number;
+  author: string;
+  description?: string;
+}
+
+export interface Shortcut {
+  id: string;
+  accelerator: string;
+  type: ShortcutType;
+  meta: ShortcutMeta;
+}
+
+export type ShortcutSetting = Shortcut[];
+
+export const shortcutSettingOriginData: ShortcutSetting = [];

package/common/storage/shortcut-storage.ts

@@ -0,0 +1,58 @@
+import { StorageList } from './constants'
+import { shortcutSettingOriginData, ShortcutSetting, Shortcut } from './entity/shortcut-settings'
+
+class ShortcutStorage {
+  private _config: ShortcutSetting = []
+
+  constructor(private readonly storage: {
+    getConfig: (name: string) => any,
+    saveConfig: (name: string, content?: string) => void,
+  }) {
+    this.init()
+  }
+
+  private init() {
+    const config = this.storage.getConfig(StorageList.SHORTCUT_SETTING)
+    if (!config || !Array.isArray(config) || config.length === 0) {
+      this._config = [...shortcutSettingOriginData]
+      this._save()
+    } else {
+      this._config = config
+    }
+  }
+
+  private _save() {
+    this.storage.saveConfig(StorageList.SHORTCUT_SETTING, JSON.stringify(this._config, null, 2))
+  }
+
+  getAllShortcuts(): Shortcut[] {
+    return this._config
+  }
+
+  getShortcutById(id: string): Shortcut | undefined {
+    return this._config.find(s => s.id === id)
+  }
+
+  addShortcut(shortcut: Shortcut): boolean {
+    if (this.getShortcutById(shortcut.id)) {
+      console.warn(`Shortcut with ID ${shortcut.id} already exists.`)
+      return false
+    }
+    this._config.push(shortcut)
+    this._save()
+    return true
+  }
+
+  updateShortcutAccelerator(id: string, newAccelerator: string): boolean {
+    const shortcut = this.getShortcutById(id)
+    if (!shortcut) {
+      return false
+    }
+    shortcut.accelerator = newAccelerator
+    shortcut.meta.modificationTime = Date.now()
+    this._save()
+    return true
+  }
+}
+
+export default ShortcutStorage

package/common/utils/file.ts

@@ -0,0 +1,62 @@
+import path from 'path-browserify'
+
+/**
+ * Enum for various file types.
+ * @enum {string}
+ */
+export enum FileType {
+  Image = 'Image',
+  Document = 'Document',
+  Audio = 'Audio',
+  Video = 'Video',
+  Archive = 'Archive',
+  Code = 'Code',
+  Text = 'Text',
+  Design = 'Design',
+  Model3D = '3D Model',
+  Font = 'Font',
+  Spreadsheet = 'Spreadsheet',
+  Presentation = 'Presentation',
+  Ebook = 'Ebook',
+  Other = 'Other'
+}
+
+const extensionMap: Map<FileType, Set<string>> = new Map([
+  [FileType.Image, new Set(['.jpg', '.jpeg', '.png', '.gif', '.bmp', '.webp', '.svg', '.ico', '.tiff'])],
+  [FileType.Document, new Set(['.doc', '.docx', '.pdf', '.odt', '.rtf'])],
+  [FileType.Audio, new Set(['.mp3', '.wav', '.ogg', '.flac', '.aac', '.m4a'])],
+  [FileType.Video, new Set(['.mp4', '.avi', '.mov', '.wmv', '.mkv', '.flv', '.webm'])],
+  [FileType.Archive, new Set(['.zip', '.rar', '.7z', '.tar', '.gz', '.bz2'])],
+  [FileType.Code, new Set(['.js', '.ts', '.jsx', '.tsx', '.html', '.css', '.scss', '.json', '.xml', '.java', '.py', '.c', '.cpp', '.go', '.rs', '.php', '.sh'])],
+  [FileType.Text, new Set(['.txt', '.md', '.log'])],
+  [FileType.Design, new Set(['.psd', '.ai', '.fig', '.sketch', '.xd', '.afdesign'])],
+  [FileType.Model3D, new Set(['.obj', '.fbx', '.stl', '.dae', '.blend', '.3ds'])],
+  [FileType.Font, new Set(['.ttf', '.otf', '.woff', '.woff2'])],
+  [FileType.Spreadsheet, new Set(['.xls', '.xlsx', '.csv', '.numbers'])],
+  [FileType.Presentation, new Set(['.ppt', '.pptx', '.key'])],
+  [FileType.Ebook, new Set(['.epub', '.mobi', '.azw'])]
+]);
+
+/**
+ * Get the file type from a file path.
+ * @param {string} filePath - The path to the file.
+ * @returns {FileType} The type of the file.
+ */
+export function getFileTypeFromPath(filePath: string): FileType {
+  const extension = path.extname(filePath).toLowerCase()
+  return getFileTypeFromExtension(extension)
+}
+
+/**
+ * Get the file type from a file extension.
+ * @param {string} extension - The file extension, including the dot.
+ * @returns {FileType} The type of the file.
+ */
+export function getFileTypeFromExtension(extension: string): FileType {
+  for (const [type, extensions] of extensionMap.entries()) {
+    if (extensions.has(extension)) {
+      return type
+    }
+  }
+  return FileType.Other
+}

package/common/{utils.ts → utils/index.ts}

@@ -101,7 +101,7 @@ export function structuredStrictStringify(value: unknown): string {
     if (typeof Document !== 'undefined') {
       if (val instanceof Node) return 'DOMNode';
     }
-    if (val instanceof Error) return 'Error';
+    // if (val instanceof Error) return 'Error';
     if (val instanceof WeakMap) return 'WeakMap';
     if (val instanceof WeakSet) return 'WeakSet';
     if (typeof val === 'object' && val !== null && val.constructor?.name === 'Proxy') return 'Proxy';
@@ -112,7 +112,7 @@ export function structuredStrictStringify(value: unknown): string {
   function serialize(val: any, path: string): any {
     const type = getType(val);
     // Block disallowed/unsafe types and edge cases for structured-clone
-    if (badTypes.includes(typeof val) || type === 'DOMNode' || type === 'Error' || type === 'Proxy' || type === 'WeakMap' || type === 'WeakSet' || type === 'BigInt') {
+    if (badTypes.includes(typeof val) || type === 'DOMNode' || type === 'Proxy' || type === 'WeakMap' || type === 'WeakSet' || type === 'BigInt') {
       throw new Error(`Cannot serialize property at path "${path}": type "${type}"`);
     }
     // JSON doesn't support undefined, skip it for values in objects, preserve in arrays as null
@@ -130,6 +130,13 @@ export function structuredStrictStringify(value: unknown): string {
         return `[Circular ~${seen.get(val)}]`; // You could just throw if you dislike this fallback!
       }
       seen.set(val, path);
+      if (val instanceof Error) {
+        return {
+          name: val.name,
+          message: val.message,
+          stack: val.stack,
+        };
+      }
       if (Array.isArray(val)) {
         return val.map((item, idx) => serialize(item, `${path}[${idx}]`));
       }
@@ -158,3 +165,8 @@ export function structuredStrictStringify(value: unknown): string {
 
   return JSON.stringify(serialize(value, 'root'));
 }
+
+export { runAdaptiveTaskQueue, type AdaptiveTaskQueueOptions } from './task-queue'
+
+export * from './time'
+export * from './file'

package/common/utils/polling.ts

@@ -0,0 +1,184 @@
+/**
+ * @module polling
+ * A high-precision, efficient, singleton polling service for scheduling periodic tasks.
+ * This service uses a dynamic setTimeout approach, ensuring tasks are executed
+ * with high accuracy while minimizing CPU usage and battery consumption.
+ */
+
+interface PollingTask {
+  id: string;
+  callback: () => void | Promise<void>;
+  intervalMs: number;
+  nextRunMs: number;
+}
+
+type TimeUnit = 'seconds' | 'minutes' | 'hours';
+
+export class PollingService {
+  private static instance: PollingService;
+  private tasks = new Map<string, PollingTask>();
+  private timerId: NodeJS.Timeout | null = null;
+  private isRunning = false;
+
+  private constructor() {
+    // Private constructor to enforce singleton pattern
+  }
+
+  public static getInstance(): PollingService {
+    if (!PollingService.instance) {
+      PollingService.instance = new PollingService();
+    }
+    return PollingService.instance;
+  }
+
+  private convertToMs(interval: number, unit: TimeUnit): number {
+    switch (unit) {
+      case 'seconds':
+        return interval * 1000;
+      case 'minutes':
+        return interval * 60 * 1000;
+      case 'hours':
+        return interval * 60 * 60 * 1000;
+      default:
+        throw new Error(`Invalid time unit: ${unit}`);
+    }
+  }
+
+  /**
+   * Registers a new periodic task with the service.
+   * @param id - A unique identifier for the task.
+   * @param callback - The function to be executed.
+   * @param options - The execution interval.
+   */
+  public register(
+    id: string,
+    callback: () => void | Promise<void>,
+    options: { interval: number; unit: TimeUnit; runImmediately?: boolean }
+  ): void {
+    if (this.tasks.has(id)) {
+      console.warn(`[PollingService] Task with ID '${id}' is already registered. Overwriting.`);
+    }
+
+    const intervalMs = this.convertToMs(options.interval, options.unit);
+    if (intervalMs <= 0) {
+      console.error(`[PollingService] Task '${id}' has an invalid interval of ${intervalMs}ms. Registration aborted.`);
+      return;
+    }
+    
+    const nextRunMs = options.runImmediately ? Date.now() : Date.now() + intervalMs;
+
+    this.tasks.set(id, {
+      id,
+      callback,
+      intervalMs,
+      nextRunMs,
+    });
+
+    console.log(`[PollingService] Task '${id}' registered to run every ${options.interval} ${options.unit}.`);
+
+    if (this.isRunning) {
+      this._reschedule();
+    }
+  }
+
+  /**
+   * Unregisters a task, preventing it from being executed in the future.
+   * @param id - The unique identifier of the task to remove.
+   */
+  public unregister(id: string): void {
+    if (this.tasks.delete(id)) {
+      console.log(`[PollingService] Task '${id}' unregistered.`);
+      if (this.isRunning) {
+        this._reschedule();
+      }
+    } else {
+      console.warn(`[PollingService] Attempted to unregister a non-existent task with ID '${id}'.`);
+    }
+  }
+
+  /**
+   * Checks if a task is already registered.
+   * @param id - The unique identifier of the task.
+   * @returns - True if the task is registered, false otherwise.
+   */
+  public isRegistered(id: string): boolean {
+    return this.tasks.has(id);
+  }
+
+  /**
+   * Starts the polling service.
+   * It's safe to call this method multiple times.
+   */
+  public start(): void {
+    if (this.isRunning) {
+      return;
+    }
+    this.isRunning = true;
+    console.log('[PollingService] Service started.');
+    this._reschedule();
+  }
+
+  /**
+   * Stops the polling service and clears all scheduled tasks.
+   */
+  public stop(): void {
+    if (!this.isRunning) {
+      return;
+    }
+    this.isRunning = false;
+    if (this.timerId) {
+      clearTimeout(this.timerId);
+      this.timerId = null;
+    }
+    console.log('[PollingService] Service stopped.');
+  }
+
+  private _reschedule(): void {
+    if (this.timerId) {
+      clearTimeout(this.timerId);
+      this.timerId = null;
+    }
+
+    if (!this.isRunning || this.tasks.size === 0) {
+      return;
+    }
+
+    const now = Date.now();
+    const nextTask = Array.from(this.tasks.values()).reduce((prev, curr) =>
+      prev.nextRunMs < curr.nextRunMs ? prev : curr
+    );
+
+    const delay = Math.max(0, nextTask.nextRunMs - now);
+    this.timerId = setTimeout(() => this._tick(), delay);
+  }
+
+  private async _tick(): Promise<void> {
+    const now = Date.now();
+    const tasksToRun: PollingTask[] = [];
+
+    for (const task of this.tasks.values()) {
+      if (task.nextRunMs <= now) {
+        tasksToRun.push(task);
+      }
+    }
+    
+    if (tasksToRun.length > 0) {
+        // console.debug(`[PollingService] Executing ${tasksToRun.length} tasks.`);
+        for (const task of tasksToRun) {
+          try {
+            await task.callback();
+          } catch (error) {
+            console.error(`[PollingService] Error executing task '${task.id}':`, error);
+          }
+          // Update next run time based on its last scheduled run time, not 'now'.
+          // This prevents drift if a task takes a long time to execute.
+          task.nextRunMs += task.intervalMs;
+        }
+    }
+
+
+    this._reschedule();
+  }
+}
+
+export const pollingService = PollingService.getInstance();