@talex-touch/utils 1.0.31 → 1.0.33

package/renderer/slots.ts

@@ -1,7 +1,7 @@
-import { VNode } from 'vue';
+import type { VNode } from 'vue'
 
-type SlotSelector = string | string[] | ((name: string) => boolean);
-type VNodePredicate = (node: VNode) => boolean;
+type SlotSelector = string | string[] | ((name: string) => boolean)
+type VNodePredicate = (node: VNode) => boolean
 
 /**
  * Normalizes a slot input into a flat array of VNodes.
@@ -16,17 +16,18 @@ type VNodePredicate = (node: VNode) => boolean;
  * ```
  */
 export function normalizeSlot(input: unknown): VNode[] {
-  if (!input) return [];
+  if (!input)
+    return []
 
   if (typeof input === 'function') {
-    return normalizeSlot(input());
+    return normalizeSlot(input())
   }
 
   if (Array.isArray(input)) {
-    return input.flatMap(normalizeSlot);
+    return input.flatMap(normalizeSlot)
   }
 
-  return [input as VNode];
+  return [input as VNode]
 }
 
 /**
@@ -44,22 +45,24 @@ export function normalizeSlot(input: unknown): VNode[] {
  */
 export function flattenVNodes(
   nodes: VNode[],
-  predicate?: VNodePredicate
+  predicate?: VNodePredicate,
 ): VNode[] {
-  const result: VNode[] = [];
+  const result: VNode[] = []
 
   for (const node of nodes) {
-    if (!node) continue;
+    if (!node)
+      continue
 
     if (predicate?.(node)) {
-      result.push(node);
-    } else if (node.children) {
-      const children = normalizeSlot(node.children);
-      result.push(...flattenVNodes(children, predicate));
+      result.push(node)
+    }
+    else if (node.children) {
+      const children = normalizeSlot(node.children)
+      result.push(...flattenVNodes(children, predicate))
     }
   }
 
-  return result;
+  return result
 }
 
 /**
@@ -86,15 +89,15 @@ export function flattenVNodes(
 export function extractFromSlots(
   slots: Record<string, unknown>,
   slotSelector: SlotSelector = 'default',
-  predicate?: VNodePredicate
+  predicate?: VNodePredicate,
 ): VNode[] {
-  const selectedSlotNames = resolveSlotNames(slots, slotSelector);
+  const selectedSlotNames = resolveSlotNames(slots, slotSelector)
 
-  const vnodes = selectedSlotNames.flatMap((name) =>
-    normalizeSlot(slots[name])
-  );
+  const vnodes = selectedSlotNames.flatMap(name =>
+    normalizeSlot(slots[name]),
+  )
 
-  return flattenVNodes(vnodes, predicate);
+  return flattenVNodes(vnodes, predicate)
 }
 
 /**
@@ -106,19 +109,19 @@ export function extractFromSlots(
  */
 function resolveSlotNames(
   slots: Record<string, unknown>,
-  selector: SlotSelector
+  selector: SlotSelector,
 ): string[] {
   if (typeof selector === 'string') {
-    return slots[selector] ? [selector] : [];
+    return slots[selector] ? [selector] : []
   }
 
   if (Array.isArray(selector)) {
-    return selector.filter((name) => !!slots[name]);
+    return selector.filter(name => !!slots[name])
   }
 
   if (typeof selector === 'function') {
-    return Object.keys(slots).filter(selector);
+    return Object.keys(slots).filter(selector)
   }
 
-  return [];
+  return []
 }

package/renderer/storage/app-settings.ts

@@ -1,5 +1,6 @@
-import { TouchStorage } from '.';
-import { appSettingOriginData, StorageList, type AppSetting } from '../..';
+import type { AppSetting } from '../..'
+import { appSettingOriginData, StorageList } from '../..'
+import { createStorageProxy, TouchStorage } from './base-storage'
 
 /**
  * Application settings storage manager
@@ -11,7 +12,7 @@ import { appSettingOriginData, StorageList, type AppSetting } from '../..';
  * ```ts
  * import { appSettings } from './app-settings-storage';
  *
- * // Read a setting
+ * // Access after initStorageChannel()
  * const isAutoStart = appSettings.data.autoStart;
  *
  * // Modify a setting (auto-saved)
@@ -23,12 +24,21 @@ class AppSettingsStorage extends TouchStorage<AppSetting> {
    * Initializes a new instance of the AppSettingsStorage class
    */
   constructor() {
-    super(StorageList.APP_SETTING, JSON.parse(JSON.stringify(appSettingOriginData)));
-    this.setAutoSave(true);
+    super(StorageList.APP_SETTING, JSON.parse(JSON.stringify(appSettingOriginData)))
+    this.setAutoSave(true)
   }
 }
 
 /**
  * Global instance of the application settings
  */
-export const appSettings = new AppSettingsStorage();
+const APP_SETTINGS_SINGLETON_KEY = `storage:${StorageList.APP_SETTING}`
+
+/**
+ * Lazy-initialized application settings.
+ * The actual instance is created only when first accessed AND after initStorageChannel() is called.
+ */
+export const appSettings = createStorageProxy<AppSettingsStorage>(
+  APP_SETTINGS_SINGLETON_KEY,
+  () => new AppSettingsStorage(),
+)

package/renderer/storage/base-storage.ts

@@ -1,11 +1,12 @@
+import type { UnwrapNestedRefs, WatchHandle } from 'vue'
+import type { ITouchClientChannel } from '../../channel'
+import { useDebounceFn } from '@vueuse/core'
 import {
   reactive,
+
   watch,
-  type UnwrapNestedRefs,
-  type WatchHandle,
-} from 'vue';
-import { useDebounceFn } from '@vueuse/core'
-import type { ITouchClientChannel } from '../../channel';
+
+} from 'vue'
 
 /**
  * Interface representing the external communication channel.
@@ -17,26 +18,21 @@ export interface IStorageChannel extends ITouchClientChannel {
    * @param event Event name
    * @param payload Event payload
    */
-  send(event: string, payload: unknown): Promise<unknown>;
+  send: (event: string, payload: unknown) => Promise<unknown>
 
   /**
    * Synchronous send interface
    * @param event Event name
    * @param payload Event payload
    */
-  sendSync(event: string, payload: unknown): unknown;
+  sendSync: (event: string, payload: unknown) => unknown
 }
 
-let channel: IStorageChannel | null = null;
-
-/**
- * Queue of initialization callbacks waiting for channel initialization
- */
-const pendingInitializations: Array<() => void> = [];
+let channel: IStorageChannel | null = null
 
 /**
  * Initializes the global channel for communication.
- * Processes all pending storage initializations after initialization.
+ * Must be called before creating any TouchStorage instances.
  *
  * @example
  * ```ts
@@ -50,21 +46,72 @@ const pendingInitializations: Array<() => void> = [];
  * ```
  */
 export function initStorageChannel(c: IStorageChannel): void {
-  channel = c;
+  channel = c
+}
 
-  // Process all pending storage initializations
-  for (const initFn of pendingInitializations) {
-    initFn();
+/**
+ * Global registry of storage instances.
+ */
+const GLOBAL_STORAGE_MAP_KEY = '__talex_touch_storages__'
+
+type GlobalStorageMap = Map<string, TouchStorage<any>>
+
+function getGlobalStorageMap(): GlobalStorageMap {
+  const globalObj = globalThis as typeof globalThis & {
+    [GLOBAL_STORAGE_MAP_KEY]?: GlobalStorageMap
   }
+  if (!globalObj[GLOBAL_STORAGE_MAP_KEY]) {
+    globalObj[GLOBAL_STORAGE_MAP_KEY] = new Map<string, TouchStorage<any>>()
+  }
+  return globalObj[GLOBAL_STORAGE_MAP_KEY]!
+}
 
-  // Clear the queue
-  pendingInitializations.length = 0;
+export const storages: GlobalStorageMap = getGlobalStorageMap()
+
+const GLOBAL_SINGLETON_KEY = '__talex_touch_storage_singletons__'
+type StorageSingletonMap = Map<string, unknown>
+
+function getSingletonMap(): StorageSingletonMap {
+  const globalObj = globalThis as typeof globalThis & {
+    [GLOBAL_SINGLETON_KEY]?: StorageSingletonMap
+  }
+  if (!globalObj[GLOBAL_SINGLETON_KEY]) {
+    globalObj[GLOBAL_SINGLETON_KEY] = new Map<string, unknown>()
+  }
+  return globalObj[GLOBAL_SINGLETON_KEY]!
 }
 
 /**
- * Global registry of storage instances.
+ * Retrieves an existing storage singleton registered on the global scope,
+ * or creates it lazily when missing. Useful to avoid duplicate TouchStorage
+ * instantiations under HMR or multi-renderer scenarios.
  */
-export const storages = new Map<string, TouchStorage<any>>();
+export function getOrCreateStorageSingleton<T>(key: string, factory: () => T): T {
+  const map = getSingletonMap()
+  if (map.has(key)) {
+    return map.get(key) as T
+  }
+  const instance = factory()
+  map.set(key, instance)
+  return instance
+}
+
+/**
+ * Creates a proxy that lazily initializes a singleton storage instance and
+ * ensures all method calls are bound to the real instance so private fields
+ * stay accessible (Proxy `this` would otherwise break private member access).
+ */
+export function createStorageProxy<T extends object>(key: string, factory: () => T): T {
+  return new Proxy({} as T, {
+    get(_target, prop) {
+      const instance = getOrCreateStorageSingleton(key, factory)
+      const property = (instance as Record<PropertyKey, unknown>)[prop as PropertyKey]
+      return typeof property === 'function'
+        ? property.bind(instance)
+        : property
+    },
+  })
+}
 
 /**
  * A reactive storage utility with optional auto-save and update subscriptions.
@@ -72,82 +119,94 @@ export const storages = new Map<string, TouchStorage<any>>();
  * @template T Shape of the stored data.
  */
 export class TouchStorage<T extends object> {
-  readonly #qualifiedName: string;
-  #autoSave = false;
-  #autoSaveStopHandle?: WatchHandle;
-  #assigning = false;
-  readonly originalData: T;
-  private readonly _onUpdate: Array<() => void> = [];
-  #channelInitialized = false;
+  readonly #qualifiedName: string
+  #autoSave = false
+  #autoSaveStopHandle?: WatchHandle
+  #assigning = false
+  readonly originalData: T
+  private readonly _onUpdate: Array<() => void> = []
+  #channelInitialized = false
+  #skipNextWatchTrigger = false
 
   /**
    * The reactive data exposed to users.
    */
-  public data: UnwrapNestedRefs<T>;
+  public data: UnwrapNestedRefs<T>
 
   /**
    * Creates a new reactive storage instance.
-   * If channel is not initialized, the instance will be queued for initialization.
+   * IMPORTANT: `initStorageChannel()` must be called before creating any TouchStorage instances.
    *
    * @param qName Globally unique name for the instance
    * @param initData Initial data to populate the storage
    * @param onUpdate Optional callback when data is updated
    *
+   * @throws {Error} If channel is not initialized or if storage with same name already exists
+   *
    * @example
    * ```ts
+   * // First initialize the channel
+   * initStorageChannel(touchChannel);
+   *
+   * // Then create storage instances
    * const settings = new TouchStorage('settings', { darkMode: false });
    * ```
    */
   constructor(qName: string, initData: T, onUpdate?: () => void) {
+    if (!channel) {
+      throw new Error(
+        `TouchStorage: Cannot create storage "${qName}" before channel is initialized. `
+        + 'Please call initStorageChannel() first.',
+      )
+    }
+
     if (storages.has(qName)) {
-      throw new Error(`Storage "${qName}" already exists`);
+      throw new Error(`Storage "${qName}" already exists`)
     }
 
-    this.#qualifiedName = qName;
-    this.originalData = initData;
-    this.data = reactive({ ...initData }) as UnwrapNestedRefs<T>;
+    this.#qualifiedName = qName
+    this.originalData = initData
+    this.data = reactive({ ...initData }) as UnwrapNestedRefs<T>
 
-    if (onUpdate) this._onUpdate.push(onUpdate);
+    if (onUpdate)
+      this._onUpdate.push(onUpdate)
 
     // Register to storages map immediately
-    storages.set(qName, this);
-
-    // Initialize channel-dependent operations
-    if (channel) {
-      this.#initializeChannel();
-    } else {
-      // Queue initialization callback for later
-      pendingInitializations.push(() => this.#initializeChannel());
-    }
+    storages.set(qName, this)
+
+    // Initialize channel-dependent operations immediately
+    this.#initializeChannel()
   }
 
   /**
-   * Initialize channel-dependent operations
+   * Initialize channel-dependent operations.
+   * Called immediately in constructor after channel validation.
    */
   #initializeChannel(): void {
     if (this.#channelInitialized) {
-      return;
+      return
     }
 
-    if (!channel) {
-      throw new Error(
-        'TouchStorage: channel is not initialized. Please call initStorageChannel(...) before using.'
-      );
-    }
+    this.#channelInitialized = true
 
-    this.#channelInitialized = true;
+    const result = channel!.sendSync('storage:get', this.#qualifiedName)
+    const parsed = result ? (result as Partial<T>) : {}
 
-    // Load data from remote
-    this.loadFromRemote();
+    this.assignData(parsed)
 
     // Register update listener
-    channel.regChannel('storage:update', ({ data }) => {
+    channel!.regChannel('storage:update', ({ data }) => {
       const { name } = data!
 
       if (name === this.#qualifiedName) {
         this.loadFromRemote()
       }
-    });
+    })
+
+    // Start auto-save watcher AFTER initial data load
+    if (this.#autoSave && !this.#autoSaveStopHandle) {
+      this.#startAutoSaveWatcher()
+    }
   }
 
   /**
@@ -159,7 +218,7 @@ export class TouchStorage<T extends object> {
    * ```
    */
   getQualifiedName(): string {
-    return this.#qualifiedName;
+    return this.#qualifiedName
   }
 
   /**
@@ -171,7 +230,7 @@ export class TouchStorage<T extends object> {
    * ```
    */
   isAutoSave(): boolean {
-    return this.#autoSave;
+    return this.#autoSave
   }
 
   /**
@@ -187,22 +246,19 @@ export class TouchStorage<T extends object> {
    */
   saveToRemote = useDebounceFn(async (options?: { force?: boolean }): Promise<void> => {
     if (!channel) {
-      throw new Error("TouchStorage: channel not initialized");
+      throw new Error('TouchStorage: channel not initialized')
     }
 
     if (this.#assigning && !options?.force) {
-      console.debug("[Storage] Skip saveToRemote for", this.getQualifiedName());
-      return;
+      return
     }
 
-    console.debug("Storage saveToRemote triggered", this.getQualifiedName());
-
     await channel.send('storage:save', {
       key: this.#qualifiedName,
       content: JSON.stringify(this.data),
       clear: false,
-    });
-  }, 300);
+    })
+  }, 300)
 
   /**
    * Enables or disables auto-saving.
@@ -216,34 +272,48 @@ export class TouchStorage<T extends object> {
    * ```
    */
   setAutoSave(autoSave: boolean): this {
-    this.#autoSave = autoSave;
-
-    this.#autoSaveStopHandle?.();
-
-    if (autoSave) {
-      this.#autoSaveStopHandle = watch(
-        this.data,
-        () => {
-          if (this.#assigning) {
-            console.debug("[Storage] Skip auto-save watch handle for", this.getQualifiedName());
-            return;
-          }
-
-          this._onUpdate.forEach((fn) => {
-            try {
-              fn();
-            } catch (e) {
-              console.error(`[TouchStorage] onUpdate error in "${this.#qualifiedName}":`, e);
-            }
-          });
-
-          this.saveToRemote();
-        },
-        { deep: true, immediate: true },
-      );
+    this.#autoSave = autoSave
+
+    this.#autoSaveStopHandle?.()
+    this.#autoSaveStopHandle = undefined
+
+    if (autoSave && this.#channelInitialized) {
+      this.#startAutoSaveWatcher()
     }
 
-    return this;
+    return this
+  }
+
+  #startAutoSaveWatcher(): void {
+    this.#autoSaveStopHandle = watch(
+      this.data,
+      () => {
+        if (this.#assigning) {
+          return
+        }
+
+        if (this.#skipNextWatchTrigger) {
+          this.#skipNextWatchTrigger = false
+          return
+        }
+
+        this.#runAutoSavePipeline()
+      },
+      { deep: true, immediate: true },
+    )
+  }
+
+  #runAutoSavePipeline(options?: { force?: boolean }): void {
+    this._onUpdate.forEach((fn) => {
+      try {
+        fn()
+      }
+      catch (e) {
+        console.error(`[TouchStorage] onUpdate error in "${this.#qualifiedName}":`, e)
+      }
+    })
+
+    this.saveToRemote(options)
   }
 
   /**
@@ -259,7 +329,7 @@ export class TouchStorage<T extends object> {
    * ```
    */
   onUpdate(fn: () => void): void {
-    this._onUpdate.push(fn);
+    this._onUpdate.push(fn)
   }
 
   /**
@@ -275,9 +345,9 @@ export class TouchStorage<T extends object> {
    * ```
    */
   offUpdate(fn: () => void): void {
-    const index = this._onUpdate.indexOf(fn);
+    const index = this._onUpdate.indexOf(fn)
     if (index !== -1) {
-      this._onUpdate.splice(index, 1);
+      this._onUpdate.splice(index, 1)
     }
   }
 
@@ -297,18 +367,25 @@ export class TouchStorage<T extends object> {
    */
   private assignData(newData: Partial<T>, stopWatch: boolean = true): void {
     if (stopWatch && this.#autoSave) {
-      this.#assigning = true;
-      console.debug(`[Storage] Stop auto-save watch handle for ${this.getQualifiedName()}`);
+      this.#assigning = true
     }
 
-    Object.assign(this.data, newData);
-    console.debug(`[Storage] Assign data to ${this.getQualifiedName()}`);
+    Object.assign(this.data, newData)
 
     if (stopWatch && this.#autoSave) {
-      setTimeout(() => {
-        this.#assigning = false;
-        console.debug(`[Storage] Resume auto-save watch handle for ${this.getQualifiedName()}`);
-      }, 0);
+      this.#skipNextWatchTrigger = true
+      const resetAssigning = () => {
+        this.#assigning = false
+      }
+
+      if (typeof queueMicrotask === 'function') {
+        queueMicrotask(resetAssigning)
+      }
+      else {
+        Promise.resolve().then(resetAssigning)
+      }
+
+      this.#runAutoSavePipeline({ force: true })
     }
   }
 
@@ -324,8 +401,8 @@ export class TouchStorage<T extends object> {
    * ```
    */
   applyData(data: Partial<T>): this {
-    this.assignData(data);
-    return this;
+    this.assignData(data)
+    return this
   }
 
   /**
@@ -340,15 +417,16 @@ export class TouchStorage<T extends object> {
    */
   async reloadFromRemote(): Promise<this> {
     if (!channel) {
-      throw new Error("TouchStorage: channel not initialized");
+      throw new Error('TouchStorage: channel not initialized')
     }
 
-    const result = await channel.send('storage:reload', this.#qualifiedName);
-    const parsed = result ? (result as Partial<T>) : {};
-    this.assignData(parsed, true);
+    const result = await channel.send('storage:reload', this.#qualifiedName)
+    const parsed = result ? (result as Partial<T>) : {}
+    this.assignData(parsed, true)
 
-    return this;
+    return this
   }
+
   /**
    * Loads data from remote storage and applies it.
    * If channel is not initialized yet, this method will do nothing.
@@ -363,13 +441,43 @@ export class TouchStorage<T extends object> {
   loadFromRemote(): this {
     if (!channel) {
       // Channel not initialized yet, data will be loaded when channel is ready
-      return this;
+      return this
     }
 
     const result = channel.sendSync('storage:get', this.#qualifiedName)
-    const parsed = result ? (result as Partial<T>) : {};
-    this.assignData(parsed, true);
+    const parsed = result ? (result as Partial<T>) : {}
+    this.assignData(parsed, true)
 
-    return this;
+    return this
+  }
+
+  /**
+   * Gets the current data state.
+   *
+   * @returns Current data
+   *
+   * @example
+   * ```ts
+   * const currentData = store.get();
+   * ```
+   */
+  get(): T {
+    return this.data as T
+  }
+
+  /**
+   * Sets the entire data state.
+   *
+   * @param newData New data to replace current state
+   * @returns The current instance for chaining
+   *
+   * @example
+   * ```ts
+   * store.set({ theme: 'dark', lang: 'en' });
+   * ```
+   */
+  set(newData: T): this {
+    this.assignData(newData as Partial<T>)
+    return this
   }
 }

package/renderer/storage/index.ts

@@ -1 +1,4 @@
+export * from './app-settings'
 export * from './base-storage'
+export * from './intelligence-storage'
+export * from './openers'