@talex-touch/utils 1.0.30 → 1.0.32

package/types/modules/module-manager.ts

@@ -1,6 +1,6 @@
-import { MaybePromise, ModuleDirectory, ModuleFileConfig, ModuleKey, ResolvedModuleFileConfig } from "./base";
-import { IBaseModule, ModuleCtor, ModuleRegistrant } from "./module";
-import { ModuleStopContext } from "./module-lifecycle";
+import type { MaybePromise, ModuleDirectory, ModuleFileConfig, ModuleKey, ResolvedModuleFileConfig } from './base'
+import type { IBaseModule, ModuleCtor, ModuleRegistrant } from './module'
+import type { ModuleStopContext } from './module-lifecycle'
 
 /**
  * Interface of the Module Manager.
@@ -32,7 +32,7 @@ export interface IBaseModuleManager<E = any> {
    * - If an instance is provided, step (2) is skipped; the same lifecycle calls apply.
    * - The manager must preserve **singleton semantics** per {@link ModuleKey}.
    */
-  loadModule<T extends IBaseModule<E>>(module: ModuleRegistrant<T, E>): boolean | Promise<boolean>;
+  loadModule: <T extends IBaseModule<E>>(module: ModuleRegistrant<T, E>) => boolean | Promise<boolean>
 
   /**
    * Unloads a module by key.
@@ -45,7 +45,7 @@ export interface IBaseModuleManager<E = any> {
    * The manager should invoke `stop?()` (with a `ModuleStopContext`) followed by `destroy()`
    * (with a `ModuleDestroyContext`), then remove the singleton instance.
    */
-  unloadModule(moduleKey: ModuleKey, reason?: ModuleStopContext<E>["reason"]): boolean | Promise<boolean>;
+  unloadModule: (moduleKey: ModuleKey, reason?: ModuleStopContext<E>['reason']) => boolean | Promise<boolean>
 
   /**
    * Retrieves a module instance by key.
@@ -54,7 +54,7 @@ export interface IBaseModuleManager<E = any> {
    * @param moduleKey - The unique key of the module.
    * @returns The module instance if loaded; otherwise `undefined`.
    */
-  getModule<T extends IBaseModule<E> = IBaseModule<E>>(moduleKey: ModuleKey): T | undefined;
+  getModule: <T extends IBaseModule<E> = IBaseModule<E>>(moduleKey: ModuleKey) => T | undefined
 
   /**
    * Optional class-based getter for stronger typing.
@@ -63,17 +63,17 @@ export interface IBaseModuleManager<E = any> {
    * @param ctor - The module class used at registration time (or a class with the same static `key`).
    * @returns The module instance if loaded; otherwise `undefined`.
    */
-  get<T extends IBaseModule<E>>(ctor: ModuleCtor<T, E>): T | undefined;
+  get: <T extends IBaseModule<E>>(ctor: ModuleCtor<T, E>) => T | undefined
 
   /**
    * Returns whether a module is currently loaded.
    */
-  hasModule(moduleKey: ModuleKey): boolean;
+  hasModule: (moduleKey: ModuleKey) => boolean
 
   /**
    * Lists keys of all currently loaded modules.
    */
-  listModules(): readonly ModuleKey[];
+  listModules: () => readonly ModuleKey[]
 }
 
 /**
@@ -89,11 +89,11 @@ export interface IModuleDirectoryService {
   /**
    * Resolves a {@link ModuleFileConfig} to {@link ResolvedModuleFileConfig} without creating anything.
    */
-  resolve(moduleKey: ModuleKey, input?: ModuleFileConfig): ResolvedModuleFileConfig;
+  resolve: (moduleKey: ModuleKey, input?: ModuleFileConfig) => ResolvedModuleFileConfig
 
   /**
    * Creates (or returns) the single {@link ModuleDirectory} for a module if configured to `create: true`.
    * If `create !== true`, implementations should return `undefined`.
    */
-  ensure(moduleKey: ModuleKey, input?: ModuleFileConfig): MaybePromise<ModuleDirectory | undefined>;
+  ensure: (moduleKey: ModuleKey, input?: ModuleFileConfig) => MaybePromise<ModuleDirectory | undefined>
 }

package/types/modules/module.ts

@@ -1,5 +1,5 @@
-import { MaybePromise, ModuleFileConfig, ModuleKey } from "./base";
-import { ModuleCreateContext, ModuleDestroyContext, ModuleInitContext, ModuleStartContext, ModuleStopContext } from "./module-lifecycle";
+import type { MaybePromise, ModuleFileConfig, ModuleKey } from './base'
+import type { ModuleCreateContext, ModuleDestroyContext, ModuleInitContext, ModuleStartContext, ModuleStopContext } from './module-lifecycle'
 
 /**
  * Contract that every module must implement.
@@ -19,7 +19,7 @@ export interface IBaseModule<E = any> {
   /**
    * Unique module key. Prefer `Symbol.for("your-module")` for global uniqueness.
    */
-  name: ModuleKey;
+  name: ModuleKey
 
   /**
    * Optional custom module entry file path.
@@ -28,7 +28,7 @@ export interface IBaseModule<E = any> {
    * If omitted, the manager can resolve a default location (e.g., inside the module's directory
    * when one exists, or from an app-level modules root).
    */
-  filePath?: string;
+  filePath?: string
 
   /**
    * Declarative directory configuration for this module.
@@ -38,33 +38,33 @@ export interface IBaseModule<E = any> {
    *   expose a `ModuleDirectory` on all lifecycle contexts.
    * - If `file.create !== true`, no directory will be created and `context.directory` will be `undefined`.
    */
-  file?: ModuleFileConfig;
+  file?: ModuleFileConfig
 
   /**
    * Optional hook invoked after construction/registration and before `init`.
    * Use this for last-moment wiring that depends on resolved paths or file config.
    */
-  created?(ctx: ModuleCreateContext<E>): MaybePromise<void>;
+  created?: (ctx: ModuleCreateContext<E>) => MaybePromise<void>
 
   /**
    * Called to perform resource preparation and subscription wiring.
    */
-  init(ctx: ModuleInitContext<E>): MaybePromise<void>;
+  init: (ctx: ModuleInitContext<E>) => MaybePromise<void>
 
   /**
    * Called when the module should start its active work.
    */
-  start?(ctx: ModuleStartContext<E>): MaybePromise<void>;
+  start?: (ctx: ModuleStartContext<E>) => MaybePromise<void>
 
   /**
    * Called when the module should leave the active state but may still keep allocated resources.
    */
-  stop?(ctx: ModuleStopContext<E>): MaybePromise<void>;
+  stop?: (ctx: ModuleStopContext<E>) => MaybePromise<void>
 
   /**
    * Called to perform final teardown and resource release.
    */
-  destroy(ctx: ModuleDestroyContext<E>): MaybePromise<void>;
+  destroy: (ctx: ModuleDestroyContext<E>) => MaybePromise<void>
 }
 
 /**
@@ -81,19 +81,19 @@ export interface IBaseModule<E = any> {
  * @public
  */
 export interface ModuleCtor<T extends IBaseModule<E>, E = any> {
-  new (ctx: ModuleCreateContext<E>): T;
+  new (ctx: ModuleCreateContext<E>): T
 
   /**
    * Optional class-level unique key.
    * If omitted, the instance {@link IModule.name | name} must be used as the key.
    */
-  readonly key?: ModuleKey;
+  readonly key?: ModuleKey
 
   /**
    * Optional declarative dependencies expressed as other module keys.
    * Useful if the manager performs topological ordering.
    */
-  readonly requires?: readonly ModuleKey[];
+  readonly requires?: readonly ModuleKey[]
 }
 
 /**
@@ -107,6 +107,6 @@ export interface ModuleCtor<T extends IBaseModule<E>, E = any> {
  *
  * @public
  */
-export type ModuleRegistrant<T extends IBaseModule<E>, E = any> =
-  | T
-  | ModuleCtor<T, E>;
+export type ModuleRegistrant<T extends IBaseModule<E>, E = any>
+  = | T
+    | ModuleCtor<T, E>

package/types/storage.ts

@@ -53,4 +53,3 @@ export interface FileDetails {
   /** Whether content was truncated due to size */
   truncated?: boolean
 }
-

package/types/touch-app-core.ts

@@ -1,38 +1,38 @@
-import { BrowserWindowConstructorOptions, OpenDevToolsOptions } from "electron";
-import { IBaseModuleManager, IBaseModule } from './modules'
+import type { BrowserWindowConstructorOptions, OpenDevToolsOptions } from 'electron'
+import type { IBaseModule, IBaseModuleManager } from './modules'
 
 export namespace TalexTouch {
   export interface TouchApp {
-    app: Electron.App;
-    window: ITouchWindow;
-    version: AppVersion;
-    moduleManager: IBaseModuleManager;
-    config: IConfiguration;
-    rootPath: string;
+    app: Electron.App
+    window: ITouchWindow
+    version: AppVersion
+    moduleManager: IBaseModuleManager
+    config: IConfiguration
+    rootPath: string
   }
 
   export enum AppVersion {
     // ALPHA = "alpha",
     // BETA = "beta",
-    DEV = "dev",
-    RELEASE = "release",
+    DEV = 'dev',
+    RELEASE = 'release',
   }
 
   export interface ITouchWindow {
-    window: Electron.BrowserWindow;
+    window: Electron.BrowserWindow
 
     /**
      * Try to close the window. This has the same effect as a user manually clicking
      * the close button of the window. The web page may cancel the close though. See
      * the close event.
      */
-    close(): void;
+    close(): void
 
     /**
      * Minimizes the window. On some platforms the minimized window will be shown in
      * the Dock.
      */
-    minimize(): void;
+    minimize(): void
 
     /**
      * Opens the devtools.
@@ -43,29 +43,29 @@ export namespace TalexTouch {
      * On Windows, if Windows Control Overlay is enabled, Devtools will be opened with
      * `mode: 'detach'`.
      */
-    openDevTools(options?: OpenDevToolsOptions): void;
+    openDevTools(options?: OpenDevToolsOptions): void
 
     loadURL(
       url: string,
       options?: LoadURLOptions | undefined,
-    ): Promise<Electron.WebContents>;
+    ): Promise<Electron.WebContents>
     loadFile(
       filePath: string,
       options?: LoadFileOptions | undefined,
-    ): Promise<Electron.WebContents>;
+    ): Promise<Electron.WebContents>
   }
 
-  export type TouchWindowConstructorOptions =
-    BrowserWindowConstructorOptions & {
-      autoShow?: boolean;
-    };
+  export type TouchWindowConstructorOptions
+    = BrowserWindowConstructorOptions & {
+      autoShow?: boolean
+    }
 
   export type LoadFileOptions = Electron.LoadFileOptions & {
-    devtools?: boolean | "detach" | "left" | "right" | "bottom" | "undocked";
-  };
+    devtools?: boolean | 'detach' | 'left' | 'right' | 'bottom' | 'undocked'
+  }
   export type LoadURLOptions = Electron.LoadURLOptions & {
-    devtools?: boolean | "detach" | "left" | "right" | "bottom" | "undocked";
-  };
+    devtools?: boolean | 'detach' | 'left' | 'right' | 'bottom' | 'undocked'
+  }
 
   export interface IModuleManager<E> extends IBaseModuleManager<E> {
 
@@ -74,17 +74,17 @@ export namespace TalexTouch {
   export interface IModule<E> extends IBaseModule<E> {}
 
   export interface IConfiguration {
-    configPath: string;
-    data: TouchAppConfig;
-    triggerSave: Function;
+    configPath: string
+    data: TouchAppConfig
+    triggerSave: Function
   }
 
   export interface TouchAppConfig {
     frame: {
-      width: number;
-      height: number;
-      left?: number;
-      top?: number;
-    };
+      width: number
+      height: number
+      left?: number
+      top?: number
+    }
   }
 }

package/types/update.ts

@@ -1,11 +1,15 @@
-// 更新源类型枚举
+/**
+ * Known update provider types.
+ */
 export enum UpdateProviderType {
   GITHUB = 'github',
   OFFICIAL = 'official',
-  CUSTOM = 'custom'
+  CUSTOM = 'custom',
 }
 
-// 更新源配置接口
+/**
+ * Describes the remote endpoint that serves release metadata.
+ */
 export interface UpdateSourceConfig {
   type: UpdateProviderType
   name: string
@@ -14,7 +18,9 @@ export interface UpdateSourceConfig {
   priority: number
 }
 
-// 下载资源接口
+/**
+ * Represents a downloadable build artifact.
+ */
 export interface DownloadAsset {
   name: string
   url: string
@@ -24,7 +30,9 @@ export interface DownloadAsset {
   checksum?: string
 }
 
-// GitHub Release接口（兼容GitHub API格式）
+/**
+ * Minimal subset of the GitHub release payload that the updater consumes.
+ */
 export interface GitHubRelease {
   tag_name: string
   name: string
@@ -33,7 +41,9 @@ export interface GitHubRelease {
   assets: DownloadAsset[]
 }
 
-// 更新检查结果接口
+/**
+ * Standardized shape of an update check response.
+ */
 export interface UpdateCheckResult {
   hasUpdate: boolean
   release?: GitHubRelease
@@ -41,7 +51,9 @@ export interface UpdateCheckResult {
   source: string
 }
 
-// 自定义更新源配置
+/**
+ * Custom provider definition used to extend the updater beyond the built-ins.
+ */
 export interface CustomUpdateConfig {
   name: string
   url: string
@@ -49,49 +61,95 @@ export interface CustomUpdateConfig {
   headers?: Record<string, string>
 }
 
-// 应用预览渠道枚举
+/**
+ * Build channels supported by the desktop client.
+ */
 export enum AppPreviewChannel {
-  MASTER = 'master',
-  SNAPSHOT = 'snapshot'
+  RELEASE = 'RELEASE',
+  BETA = 'BETA',
+  SNAPSHOT = 'SNAPSHOT',
 }
 
-// 更新设置配置
+/**
+ * Scheduler presets used by the polling worker.
+ */
+export type UpdateFrequency = 'everyday' | '1day' | '3day' | '7day' | '1month' | 'never'
+
+/**
+ * User and system configurable update preferences.
+ */
 export interface UpdateSettings {
   enabled: boolean
-  frequency: 'startup' | 'daily' | 'weekly' | 'manual'
+  frequency: UpdateFrequency
   source: UpdateSourceConfig
-  crossChannel: boolean
+  updateChannel: AppPreviewChannel
   ignoredVersions: string[]
   customSources: CustomUpdateConfig[]
+  /**
+   * Timestamp (ms) of the last successful update check.
+   */
+  lastCheckedAt?: number | null
+  /**
+   * Enable/disable local caching of remote responses.
+   */
+  cacheEnabled?: boolean
+  /**
+   * Cache TTL in minutes.
+   */
+  cacheTTL?: number
+  /**
+   * Enable retry logic for transient failures.
+   */
+  rateLimitEnabled?: boolean
+  /**
+   * Maximum retry attempts when the provider throttles requests.
+   */
+  maxRetries?: number
+  /**
+   * Base retry delay in milliseconds.
+   */
+  retryDelay?: number
 }
 
-// 默认更新设置
+/**
+ * Safe defaults used when no user configuration exists yet.
+ */
 export const defaultUpdateSettings: UpdateSettings = {
   enabled: true,
-  frequency: 'startup',
+  frequency: 'everyday',
   source: {
     type: UpdateProviderType.GITHUB,
     name: 'GitHub Releases',
     url: 'https://api.github.com/repos/talex-touch/tuff/releases',
     enabled: true,
-    priority: 1
+    priority: 1,
   },
-  crossChannel: false,
+  updateChannel: AppPreviewChannel.RELEASE,
   ignoredVersions: [],
-  customSources: []
+  customSources: [],
+  lastCheckedAt: null,
+  cacheEnabled: true,
+  cacheTTL: 30,
+  rateLimitEnabled: true,
+  maxRetries: 3,
+  retryDelay: 2000,
 }
 
-// 更新错误类型
+/**
+ * Categorized error types emitted by the updater pipeline.
+ */
 export enum UpdateErrorType {
   NETWORK_ERROR = 'network_error',
   TIMEOUT_ERROR = 'timeout_error',
   API_ERROR = 'api_error',
   PARSE_ERROR = 'parse_error',
   VERSION_ERROR = 'version_error',
-  UNKNOWN_ERROR = 'unknown_error'
+  UNKNOWN_ERROR = 'unknown_error',
 }
 
-// 更新错误接口
+/**
+ * Error type used across providers.
+ */
 export interface UpdateError extends Error {
   type: UpdateErrorType
   code?: string

package/core-box/README.md

@@ -1,218 +0,0 @@
-# Core Box Package
-
-The Core Box package provides unified type definitions and utility functions for the TUFF search box system. This package contains the foundational types and tools used across the entire project for search result management and plugin integration.
-
-## Features
-
-### 🎯 Unified Type System
-- **ISearchItem**: Universal search result item interface
-- **IRenderConfig**: Flexible rendering configuration with multiple modes
-- **IDataItem**: Extended interface for data processing results
-- **IAppItem**: Specialized interface for application results
-- **IFileItem**: Specialized interface for file results
-- **IFeatureItem**: Specialized interface for plugin feature results
-
-### 🎨 Render Modes
-The package supports multiple rendering modes for search results:
-
-- **STANDARD**: Default text-based rendering
-- **URL**: URL rendering - loads and displays remote URL content
-- **HTML**: Rich HTML content rendering
-- **JAVASCRIPT**: JavaScript code with syntax highlighting
-- **JSX**: React JSX component rendering
-- **VUE_SFC**: Vue Single File Component rendering
-
-### 🛠️ Utility Functions
-Comprehensive set of utility functions for creating and managing search results:
-
-- `SearchUtils.createSearchItem()`: Create basic search items
-- `SearchUtils.createDataItem()`: Create data processing results
-- `SearchUtils.createAppItem()`: Create application results
-- `SearchUtils.createFileItem()`: Create file results
-- `SearchUtils.createFeatureItem()`: Create plugin feature results
-- `SearchUtils.createErrorItem()`: Create error state items
-- `SearchUtils.sortByPriority()`: Sort results by relevance
-- `SearchUtils.removeDuplicates()`: Remove duplicate results
-- `SearchUtils.filterByConfidence()`: Filter by confidence score
-- `SearchUtils.groupByPluginType()`: Group results by type
-
-## Usage Examples
-
-### Basic Search Item
-```typescript
-import { SearchUtils, RenderMode } from '@talex-touch/utils';
-
-const basicItem = SearchUtils.createSearchItem({
-  name: "My Feature",
-  desc: "A useful plugin feature",
-  pluginName: "my-plugin",
-  keyWords: ["feature", "utility"],
-  render: {
-    mode: RenderMode.STANDARD
-  }
-});
-```
-
-### Data Processing Result
-```typescript
-const dataItem = SearchUtils.createDataItem({
-  name: "Translation Result",
-  desc: "English to Chinese translation",
-  pluginName: "translator",
-  source: "google-translate",
-  dataType: "translation",
-  originalData: "Hello World",
-  processedData: "你好世界",
-  confidence: 95,
-  duration: 120,
-  render: {
-    mode: RenderMode.STANDARD
-  }
-});
-```
-
-### HTML Rendering
-```typescript
-const htmlItem = SearchUtils.createSearchItem({
-  name: "Rich Content",
-  desc: "HTML formatted result",
-  pluginName: "content-plugin",
-  render: {
-    mode: RenderMode.HTML,
-    content: "<div><h3>Title</h3><p>Content</p></div>",
-    options: {
-      trusted: true,
-      className: "custom-content"
-    }
-  }
-});
-```
-
-### Code Rendering
-```typescript
-const codeItem = SearchUtils.createDataItem({
-  name: "JavaScript Function",
-  desc: "Generated code snippet",
-  pluginName: "code-generator",
-  dataType: "javascript",
-  processedData: "function hello() { return 'world'; }",
-  render: {
-    mode: RenderMode.JAVASCRIPT,
-    content: "function hello() { return 'world'; }",
-    options: {
-      syntaxHighlight: true,
-      showLineNumbers: true,
-      theme: "dark"
-    }
-  }
-});
-```
-
-### URL Rendering with Preview
-```typescript
-const urlItem = SearchUtils.createSearchItem({
-  name: "GitHub Repository",
-  desc: "TUFF project",
-  pluginName: "web-search",
-  render: {
-    mode: RenderMode.URL,
-    content: "https://github.com/talex-touch/talex-touch", // The actual URL to load
-    preview: {
-      enabled: true,
-      title: "Tuff",                                // Preview metadata
-      description: "Modern desktop application framework", // Preview description
-      image: "https://github.com/talex-touch.png"         // Preview image
-    }
-  }
-});
-```
-
-**Note**:
-- `content`: The remote URL that will be loaded and displayed
-- `preview`: Metadata shown before/alongside the loaded URL content
-
-## Type Definitions
-
-### ISearchItem
-The core interface for all search results:
-
-```typescript
-interface ISearchItem {
-  name: string;                    // Display name
-  desc: string;                    // Description
-  icon: ITuffIcon;              // Icon configuration
-  push: boolean;                   // Push mode support
-  names: string[];                 // Searchable names
-  keyWords: string[];             // Search keywords
-  pluginType: string;             // Plugin type
-  type: string;                   // General type
-  value: string;                  // Associated value
-  render?: IRenderConfig;         // Render configuration
-  // ... additional properties
-}
-```
-
-### IRenderConfig
-Configuration for custom rendering:
-
-```typescript
-interface IRenderConfig {
-  mode: RenderMode;               // Rendering mode
-  content?: string;               // Content to render
-  options?: {                     // Render options
-    syntaxHighlight?: boolean;
-    theme?: string;
-    showLineNumbers?: boolean;
-    className?: string;
-    style?: Record<string, string>;
-    trusted?: boolean;
-  };
-  preview?: {                     // URL preview config
-    enabled?: boolean;
-    image?: string;
-    title?: string;
-    description?: string;
-  };
-}
-```
-
-## Integration
-
-This package is automatically exported from `@talex-touch/utils`:
-
-```typescript
-import {
-  ISearchItem,
-  IDataItem,
-  SearchUtils,
-  RenderMode
-} from '@talex-touch/utils';
-```
-
-## Best Practices
-
-1. **Always specify render mode**: Even for standard rendering, explicitly set the render mode
-2. **Use appropriate specialized interfaces**: Use IDataItem for data processing, IAppItem for applications, etc.
-3. **Include confidence scores**: For data processing results, always include confidence levels
-4. **Sanitize HTML content**: When using HTML render mode, ensure content is safe
-5. **Provide meaningful keywords**: Include relevant search terms in the keyWords array
-6. **Use consistent naming**: Follow established naming conventions for plugin types
-
-## Migration Guide
-
-If you're migrating from the old type system:
-
-1. Replace `ITranslationItem` with `IDataItem`
-2. Update render configurations to use the new `IRenderConfig` interface
-3. Use `SearchUtils` functions instead of manual object creation
-4. Update import paths to use `@talex-touch/utils`
-
-## Contributing
-
-When adding new types or utilities:
-
-1. Add comprehensive TSDoc comments in English
-2. Include usage examples in documentation
-3. Follow the established naming conventions
-4. Add appropriate unit tests
-5. Update this README with new features