@talex-touch/utils 1.0.17 → 1.0.20

package/search/types.ts

@@ -2,7 +2,7 @@
  * @fileoverview Search Types and Utilities
  *
  * This module provides comprehensive type definitions and utility functions
- * for search result items across the Talex Touch application. It defines
+ * for search result items across the Tuff application. It defines
  * the core interfaces and factory functions used by the search system,
  * plugins, and UI components.
  *
@@ -11,7 +11,7 @@
  * - {@link IDataItem} - Extended interface for data processing results
  * - {@link createDataItem} - Factory function for creating data items
  *
- * @author Talex Touch Team
+ * @author Tuff Team
  * @since 1.0.0
  * @version 1.0.0
  */
@@ -399,7 +399,7 @@ export interface IDataItem extends ISearchItem {
  */
 export enum SearchMode {
   INPUT = 'INPUT',
-  COMMAND = 'COMMAND', 
+  COMMAND = 'COMMAND',
   IMAGE = 'IMAGE',
   FILE = 'FILE',
   FEATURE = 'FEATURE'
@@ -411,13 +411,13 @@ export enum SearchMode {
 export interface ISearchOptions {
   /** 搜索模式 */
   mode: SearchMode;
-  
+
   /** 最大结果数量 */
   maxResults?: number;
-  
+
   /** 是否启用模糊匹配 */
   fuzzyMatch?: boolean;
-  
+
   /** 搜索超时时间（毫秒） */
   timeout?: number;
 }
@@ -428,19 +428,19 @@ export interface ISearchOptions {
 export interface IPluginSearchResult {
   /** 插件名称 */
   pluginName: string;
-  
+
   /** 搜索结果列表 */
   items: ISearchItem[];
-  
+
   /** 推送时间戳 */
   timestamp: number;
-  
+
   /** 查询关键词 */
   query: string;
-  
+
   /** 结果总数 */
   total: number;
-  
+
   /** 是否有更多结果 */
   hasMore?: boolean;
 }
@@ -451,19 +451,19 @@ export interface IPluginSearchResult {
 export interface ISearchResultManager {
   /** 推送搜索结果 */
   pushItems(items: ISearchItem[]): void;
-  
+
   /** 清空搜索结果 */
   clearItems(): void;
-  
+
   /** 获取当前搜索结果 */
   getItems(): ISearchItem[];
-  
+
   /** 更新单个搜索结果 */
   updateItem(id: string, item: Partial<ISearchItem>): boolean;
-  
+
   /** 删除单个搜索结果 */
   removeItem(id: string): boolean;
-  
+
   /** 获取结果数量 */
   getCount(): number;
 }

package/types/index.ts

@@ -1 +1,2 @@
-export * from './touch-app-core'
+export * from './touch-app-core'
+export * from './modules'

package/types/modules/base.ts

@@ -0,0 +1,146 @@
+/**
+ * Unique key for a module.
+ * @public
+ */
+export type ModuleKey = symbol;
+
+/**
+ * Utility type representing a synchronous or asynchronous value.
+ * @public
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Declarative file/directory configuration for a module (input).
+ *
+ * @remarks
+ * - **Single-directory rule**: Each module can own at most **one** directory.
+ * - If `create` is `false` (or omitted), the manager will not create a directory for the module.
+ * - If `create` is `true`, the directory name will default to a name derived from the module key/name,
+ *   but can be overridden with `dirName` (e.g., use `"clipboard"` instead of `"ClipBoardModule"`).
+ * - `root` specifies the absolute root path under which the module directory will be created.
+ *   If omitted, the manager can fall back to an application default (e.g., `app.modulesRoot`).
+ *
+ * This configuration is typically provided by the module author or the application at registration time.
+ *
+ * @public
+ */
+export interface ModuleFileConfig {
+  /**
+   * Whether to create a dedicated directory for this module.
+   *
+   * @defaultValue false
+   */
+  create?: boolean;
+
+  /**
+   * Optional custom directory name (basename only, no slashes).
+   *
+   * @example "clipboard"
+   */
+  dirName?: string;
+
+  /**
+   * Optional absolute root path under which the module directory will be created.
+   *
+   * @example "/var/app/modules"
+   */
+  root?: string;
+}
+
+/**
+ * Resolved and normalized file/directory configuration for a module (output).
+ *
+ * @remarks
+ * Produced by the manager during module loading. It captures the final decision:
+ * - whether a directory will exist for the module (`create`)
+ * - the final directory name (`dirName`) if created
+ * - the final absolute directory path (`dirPath`) if created
+ *
+ * If the module does not own a directory (i.e., `create === false`), both `dirName` and `dirPath`
+ * will be `undefined`.
+ *
+ * @public
+ */
+export interface ResolvedModuleFileConfig {
+  /**
+   * Final boolean indicating if the module has a dedicated directory.
+   */
+  create: boolean;
+
+  /**
+   * Final directory name (basename), if a directory is created.
+   */
+  dirName?: string;
+
+  /**
+   * Final absolute path to the module directory, if a directory is created.
+   */
+  dirPath?: string;
+}
+
+/**
+ * Lightweight abstraction over a module-owned directory.
+ *
+ * @remarks
+ * - **Single-directory rule**: A module can have **at most one** directory. If the module isn't configured
+ *   to create/own a directory, the `directory` field in lifecycle contexts will be `undefined`.
+ * - Implementations can be backed by Node.js `fs`, a virtual filesystem, or any storage adapter.
+ *
+ * @public
+ */
+export interface ModuleDirectory {
+  /**
+   * Absolute path to the module directory.
+   */
+  readonly path: string;
+
+  /**
+   * Joins one or more path segments to the module directory path. Does not touch the filesystem.
+   *
+   * @param segments - One or more relative path segments.
+   * @returns The combined absolute path string.
+   */
+  join(...segments: string[]): string;
+
+  /**
+   * Ensures the directory exists, creating it if necessary.
+   */
+  ensure(): MaybePromise<void>;
+
+  /**
+   * Checks whether the directory exists.
+   */
+  exists(): MaybePromise<boolean>;
+
+  /**
+   * Lists entries in the directory (filenames/subdirectory names).
+   *
+   * @returns An array of entry names (not absolute paths).
+   */
+  list(): MaybePromise<string[]>;
+
+  /**
+   * Reads a file within the module directory.
+   *
+   * @param relativePath - Path relative to the module directory.
+   * @returns File contents as a Buffer or string (implementation-dependent).
+   */
+  readFile(relativePath: string): MaybePromise<Buffer | string>;
+
+  /**
+   * Writes a file within the module directory, creating parent folders if needed.
+   *
+   * @param relativePath - Path relative to the module directory.
+   * @param data - File content.
+   */
+  writeFile(relativePath: string, data: string | Uint8Array): MaybePromise<void>;
+
+  /**
+   * Removes a file or subdirectory within the module directory.
+   *
+   * @param relativePath - Path relative to the module directory. If omitted, implementations
+   * may remove the entire directory (use with caution).
+   */
+  remove(relativePath?: string): MaybePromise<void>;
+}

package/types/modules/index.ts

@@ -0,0 +1,4 @@
+export * from './base'
+export * from './module-lifecycle'
+export * from './module'
+export * from './module-manager'

package/types/modules/module-lifecycle.ts

@@ -0,0 +1,148 @@
+import { ITouchEventBus } from "packages/utils/eventbus";
+import { ModuleKey } from ".";
+import { TalexTouch } from "../touch-app-core";
+import { ModuleDirectory, ResolvedModuleFileConfig } from "./base";
+
+/**
+ * Base context available to all lifecycle phases.
+ *
+ * @typeParam E - Event map type for the touch event bus.
+ * @public
+ */
+export interface ModuleBaseContext<E> {
+  /**
+   * The application root object (TalexTouch).
+   */
+  app: TalexTouch.TouchApp;
+
+  /**
+   * The module manager controlling creation, lifecycle, and lookup.
+   */
+  manager: TalexTouch.IModuleManager<E>;
+
+  /**
+   * The unique key for the current module (same as the module's `name`).
+   */
+  moduleKey: ModuleKey;
+
+  /**
+   * Optional configuration accessor bound to the application or module.
+   *
+   * @param key - Configuration key.
+   * @returns The typed configuration value.
+   */
+  config?<T = unknown>(key: string): T;
+
+  /**
+   * Optional event bus bound to the application or module layer.
+   */
+  events?: ITouchEventBus<E>;
+
+  /**
+   * The module's directory instance if a directory was created; otherwise `undefined`.
+   *
+   * @remarks
+   * **Single-directory rule**: Each module can expose at most one `ModuleDirectory` instance here.
+   */
+  directory?: ModuleDirectory;
+}
+
+/**
+ * Context for the "create" phase (around instantiation and initial wiring).
+ *
+ * @typeParam E - Event map type for the touch event bus.
+ * @public
+ */
+export interface ModuleCreateContext<E> extends ModuleBaseContext<E> {
+  /**
+   * Resolved file/directory configuration for the module.
+   */
+  file: ResolvedModuleFileConfig;
+
+  /**
+   * Fully resolved module entry file path if a custom path was provided,
+   * or a default path computed by the manager; otherwise `undefined`.
+   */
+  resolvedPath?: string;
+
+  /**
+   * Indicates whether this load is part of a hot-reload/replace cycle.
+   */
+  hot?: boolean;
+}
+
+/**
+ * Context for the "init" phase (resource preparation, subscriptions, scaffolding).
+ *
+ * @typeParam E - Event map type for the touch event bus.
+ * @public
+ */
+export interface ModuleInitContext<E> extends ModuleBaseContext<E> {
+  /**
+   * Optional hint that dependencies have been verified and are ready.
+   */
+  depsReady?: boolean;
+
+  /**
+   * Resolved file/directory configuration for the module.
+   */
+  file: ResolvedModuleFileConfig;
+}
+
+/**
+ * Context for the "start" phase (module enters active/working state).
+ *
+ * @typeParam E - Event map type for the touch event bus.
+ * @public
+ */
+export interface ModuleStartContext<E> extends ModuleBaseContext<E> {
+  /**
+   * Optional startup arguments or mode flags.
+   */
+  startArgs?: Record<string, unknown>;
+
+  /**
+   * Resolved file/directory configuration for the module.
+   */
+  file: ResolvedModuleFileConfig;
+}
+
+/**
+ * Context for the "stop" phase (module leaves the active/working state).
+ *
+ * @typeParam E - Event map type for the touch event bus.
+ * @public
+ */
+export interface ModuleStopContext<E> extends ModuleBaseContext<E> {
+  /**
+   * Reason for stopping. Useful for telemetry and cleanup branching.
+   * - `"normal"`: Voluntary shutdown or planned stop.
+   * - `"error"`: Unhandled error or fault.
+   * - `"hot-reload"`: Stop as part of a hot reload / replacement cycle.
+   * - `string`: Custom reason.
+   */
+  reason?: "normal" | "error" | "hot-reload" | string;
+
+  /**
+   * Resolved file/directory configuration for the module.
+   */
+  file: ResolvedModuleFileConfig;
+}
+
+/**
+ * Context for the "destroy" phase (final teardown and resource release).
+ *
+ * @typeParam E - Event map type for the touch event bus.
+ * @public
+ */
+export interface ModuleDestroyContext<E> extends ModuleBaseContext<E> {
+  /**
+   * Indicates the module is being destroyed as part of application shutdown.
+   */
+  appClosing?: boolean;
+
+  /**
+   * Resolved file/directory configuration for the module.
+   */
+  file: ResolvedModuleFileConfig;
+}

package/types/modules/module-manager.ts

@@ -0,0 +1,99 @@
+import { MaybePromise, ModuleDirectory, ModuleFileConfig, ModuleKey, ResolvedModuleFileConfig } from "./base";
+import { IBaseModule, ModuleCtor, ModuleRegistrant } from "./module";
+import { ModuleStopContext } from "./module-lifecycle";
+
+/**
+ * Interface of the Module Manager.
+ *
+ * @typeParam E - Event map type used by the application's touch event bus.
+ * @remarks
+ * The manager is responsible for:
+ * - Registering modules (singletons), constructing instances when given a class.
+ * - Resolving {@link ModuleFileConfig} into a concrete {@link ResolvedModuleFileConfig} and, if requested,
+ *   provisioning a single {@link ModuleDirectory} per module.
+ * - Driving lifecycle: `created?` → `init` → `start?` → `stop?` → `destroy`.
+ * - Providing lookup utilities (by key or, optionally, by constructor).
+ *
+ * @public
+ */
+export interface IBaseModuleManager<E = any> {
+  /**
+   * Registers and loads a module (instance or class).
+   *
+   * @typeParam T - Concrete module type.
+   * @param module - Either a prebuilt module instance or a class constructor.
+   * @returns `true` on success, `false` on no-op/failure (sync or async).
+   *
+   * @remarks
+   * - If a constructor is provided, the manager:
+   *   1) Builds a `ModuleCreateContext` (including resolved file config and optionally a directory).
+   *   2) Calls `new (createCtx)` to construct the module.
+   *   3) Invokes `created?()` (if present), then `init()`, then `start?()`.
+   * - 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>;
+
+  /**
+   * Unloads a module by key.
+   *
+   * @param moduleKey - The unique key of the module to unload.
+   * @param reason - Optional stop reason, forwarded to the stop context.
+   * @returns `true` on success, `false` if not found or failed (sync or async).
+   *
+   * @remarks
+   * 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>;
+
+  /**
+   * Retrieves a module instance by key.
+   *
+   * @typeParam T - Expected module type.
+   * @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;
+
+  /**
+   * Optional class-based getter for stronger typing.
+   *
+   * @typeParam T - Concrete module type.
+   * @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;
+
+  /**
+   * Returns whether a module is currently loaded.
+   */
+  hasModule(moduleKey: ModuleKey): boolean;
+
+  /**
+   * Lists keys of all currently loaded modules.
+   */
+  listModules(): readonly ModuleKey[];
+}
+
+/**
+ * Optional helper interface some managers expose to centralize directory creation.
+ *
+ * @remarks
+ * This can be useful if module authors want to compute file paths before the module
+ * is actually loaded, or for tooling and diagnostics. Implementation is up to you.
+ *
+ * @public
+ */
+export interface IModuleDirectoryService {
+  /**
+   * Resolves a {@link ModuleFileConfig} to {@link ResolvedModuleFileConfig} without creating anything.
+   */
+  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>;
+}

package/types/modules/module.ts

@@ -0,0 +1,112 @@
+import { MaybePromise, ModuleFileConfig, ModuleKey } from "./base";
+import { ModuleCreateContext, ModuleDestroyContext, ModuleInitContext, ModuleStartContext, ModuleStopContext } from "./module-lifecycle";
+
+/**
+ * Contract that every module must implement.
+ *
+ * @typeParam E - Event map type used by the application's touch event bus.
+ * @remarks
+ * - A module is identified by a unique {@link ModuleKey} stored in {@link IModule.name}.
+ * - Each module may own **at most one** directory. Use {@link IModule.file} to declare
+ *   if/where a directory should be created. If no directory is created, contexts will expose
+ *   `directory: undefined`.
+ * - Lifecycle methods receive **phase-specific contexts** so that modules can access
+ *   the manager, app, configuration, event bus, and (if any) the directory instance.
+ *
+ * @public
+ */
+export interface IBaseModule<E = any> {
+  /**
+   * Unique module key. Prefer `Symbol.for("your-module")` for global uniqueness.
+   */
+  name: ModuleKey;
+
+  /**
+   * Optional custom module entry file path.
+   *
+   * @remarks
+   * 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;
+
+  /**
+   * Declarative directory configuration for this module.
+   *
+   * @remarks
+   * - If `file.create === true`, the manager will compute a final directory name/path and
+   *   expose a `ModuleDirectory` on all lifecycle contexts.
+   * - If `file.create !== true`, no directory will be created and `context.directory` will be `undefined`.
+   */
+  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>;
+
+  /**
+   * Called to perform resource preparation and subscription wiring.
+   */
+  init(ctx: ModuleInitContext<E>): MaybePromise<void>;
+
+  /**
+   * Called when the module should start its active work.
+   */
+  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>;
+
+  /**
+   * Called to perform final teardown and resource release.
+   */
+  destroy(ctx: ModuleDestroyContext<E>): MaybePromise<void>;
+}
+
+/**
+ * Class-based module constructor signature (for OOP-style modules).
+ *
+ * @typeParam T - Concrete module type produced by this constructor.
+ * @typeParam E - Event map type used by the application's touch event bus.
+ * @remarks
+ * - The constructor receives a **create-phase** context so a class can read resolved paths
+ *   or the computed directory before `created()` and `init()` run.
+ * - You may optionally expose `key` and `requires` as static metadata if you plan to add
+ *   declarative dependency ordering later.
+ *
+ * @public
+ */
+export interface ModuleCtor<T extends IBaseModule<E>, E = any> {
+  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;
+
+  /**
+   * Optional declarative dependencies expressed as other module keys.
+   * Useful if the manager performs topological ordering.
+   */
+  readonly requires?: readonly ModuleKey[];
+}
+
+/**
+ * Registration input accepted by the manager.
+ *
+ * @typeParam T - Concrete module type.
+ * @typeParam E - Event map type used by the application's touch event bus.
+ * @remarks
+ * - You can register either an already-built instance or a class constructor.
+ * - When a constructor is provided, the manager will call `new (createCtx)` to construct the instance.
+ *
+ * @public
+ */
+export type ModuleRegistrant<T extends IBaseModule<E>, E = any> =
+  | T
+  | ModuleCtor<T, E>;