@talex-touch/utils 1.0.13 → 1.0.15

package/renderer/ref.ts

@@ -1,55 +1,55 @@
-import { computed, customRef } from 'vue'
-
-export function useModelWrapper(props: any, emit: any, name = 'modelValue') {
-  return computed({
-      get: () => props[name],
-      set: (value) => emit(`update:${name}`, value)
-  })
-}
-
-export function throttleRef(value: any, time: number) {
-
-  let ts = 0
-
-  return customRef((track, trigger) => {
-      return {
-          get() {
-              track()
-              return value
-          },
-          set(newValue) {
-
-              if( new Date().getTime() - ts < time ) return
-
-              value = newValue
-              track()
-              trigger()
-              ts = new Date().getTime()
-          }
-      }
-  })
-
-}
-
-export function debounceRef(value: any, delay: number) {
-
-  let timer: any
-
-  return customRef((track, trigger) => {
-      return {
-          get() {
-              track()
-              return value
-          },
-          set(newValue) {
-              clearTimeout(timer)
-              timer = setTimeout(() => {
-                  value = newValue
-                  track()
-                  trigger()
-              }, delay)
-          }
-      }
-  })
-
+import { computed, customRef } from 'vue'
+
+export function useModelWrapper(props: any, emit: any, name = 'modelValue') {
+  return computed({
+      get: () => props[name],
+      set: (value) => emit(`update:${name}`, value)
+  })
+}
+
+export function throttleRef(value: any, time: number) {
+
+  let ts = 0
+
+  return customRef((track, trigger) => {
+      return {
+          get() {
+              track()
+              return value
+          },
+          set(newValue) {
+
+              if( new Date().getTime() - ts < time ) return
+
+              value = newValue
+              track()
+              trigger()
+              ts = new Date().getTime()
+          }
+      }
+  })
+
+}
+
+export function debounceRef(value: any, delay: number) {
+
+  let timer: any
+
+  return customRef((track, trigger) => {
+      return {
+          get() {
+              track()
+              return value
+          },
+          set(newValue) {
+              clearTimeout(timer)
+              timer = setTimeout(() => {
+                  value = newValue
+                  track()
+                  trigger()
+              }, delay)
+          }
+      }
+  })
+
 }

package/renderer/slots.ts

@@ -0,0 +1,124 @@
+import { VNode } from 'vue';
+
+type SlotSelector = string | string[] | ((name: string) => boolean);
+type VNodePredicate = (node: VNode) => boolean;
+
+/**
+ * Normalizes a slot input into a flat array of VNodes.
+ *
+ * @param input - Slot input, which can be a function, VNode, or array of VNodes.
+ * @returns A flat array of VNodes.
+ *
+ * @example
+ * ```ts
+ * // Normalize a mixed slot manually (VNode | VNode[] | () => VNode[])
+ * const vnodes = normalizeSlot(this.$slots.default);
+ * ```
+ */
+export function normalizeSlot(input: unknown): VNode[] {
+  if (!input) return [];
+
+  if (typeof input === 'function') {
+    return normalizeSlot(input());
+  }
+
+  if (Array.isArray(input)) {
+    return input.flatMap(normalizeSlot);
+  }
+
+  return [input as VNode];
+}
+
+/**
+ * Recursively flattens a list of VNodes and filters them using an optional predicate.
+ *
+ * @param nodes - The VNodes to flatten and filter.
+ * @param predicate - Optional function to filter VNodes.
+ * @returns A flat array of VNodes that satisfy the predicate.
+ *
+ * @example
+ * ```ts
+ * // Flatten children of a given vnode array, filtering by custom type
+ * const flat = flattenVNodes(vnodes, vnode => typeof vnode.type === 'object');
+ * ```
+ */
+export function flattenVNodes(
+  nodes: VNode[],
+  predicate?: VNodePredicate
+): VNode[] {
+  const result: VNode[] = [];
+
+  for (const node of nodes) {
+    if (!node) continue;
+
+    if (predicate?.(node)) {
+      result.push(node);
+    } else if (node.children) {
+      const children = normalizeSlot(node.children);
+      result.push(...flattenVNodes(children, predicate));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extracts and flattens VNodes from one or more named slots,
+ * optionally filtered by a VNode predicate.
+ *
+ * @param slots - The slots object (e.g., this.$slots).
+ * @param slotSelector - Slot name(s) or a function to select slot names.
+ * @param predicate - Optional function to filter VNodes.
+ * @returns A flat array of matching VNodes from the selected slots.
+ *
+ * @example
+ * ```ts
+ * // 1. Extract from default slot and keep only nodes with name === 'MyComponent'
+ * const result1 = extractFromSlots(this.$slots, 'default', vnode => vnode.type?.name === 'MyComponent');
+ *
+ * // 2. Extract all VNodes from 'header' and 'footer' slots
+ * const result2 = extractFromSlots(this.$slots, ['header', 'footer']);
+ *
+ * // 3. Extract all VNodes from slots whose names start with 'section-'
+ * const result3 = extractFromSlots(this.$slots, name => name.startsWith('section-'));
+ * ```
+ */
+export function extractFromSlots(
+  slots: Record<string, unknown>,
+  slotSelector: SlotSelector = 'default',
+  predicate?: VNodePredicate
+): VNode[] {
+  const selectedSlotNames = resolveSlotNames(slots, slotSelector);
+
+  const vnodes = selectedSlotNames.flatMap((name) =>
+    normalizeSlot(slots[name])
+  );
+
+  return flattenVNodes(vnodes, predicate);
+}
+
+/**
+ * Resolves slot names from the selector input.
+ *
+ * @param slots - The slots object.
+ * @param selector - A string, string array, or function.
+ * @returns An array of matched slot names.
+ */
+function resolveSlotNames(
+  slots: Record<string, unknown>,
+  selector: SlotSelector
+): string[] {
+  if (typeof selector === 'string') {
+    return slots[selector] ? [selector] : [];
+  }
+
+  if (Array.isArray(selector)) {
+    return selector.filter((name) => !!slots[name]);
+  }
+
+  if (typeof selector === 'function') {
+    return Object.keys(slots).filter(selector);
+  }
+
+  return [];
+}

package/renderer/storage/app-settings.ts

@@ -0,0 +1,34 @@
+import { TouchStorage } from '.';
+import { appSettingOriginData, StorageList, type AppSetting } from '../..';
+
+/**
+ * Application settings storage manager
+ *
+ * Manages application configuration using `TouchStorage`, providing reactive data
+ * and automatic persistence.
+ *
+ * @example
+ * ```ts
+ * import { appSettings } from './app-settings-storage';
+ *
+ * // Read a setting
+ * const isAutoStart = appSettings.data.autoStart;
+ *
+ * // Modify a setting (auto-saved)
+ * appSettings.data.autoStart = true;
+ * ```
+ */
+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);
+  }
+}
+
+/**
+ * Global instance of the application settings
+ */
+export const appSettings = new AppSettingsStorage();

package/renderer/storage/base-storage.ts

@@ -0,0 +1,335 @@
+import {
+  reactive,
+  watch,
+  type UnwrapNestedRefs,
+  type WatchHandle,
+} from 'vue';
+import { useDebounceFn } from '@vueuse/core'
+import type { ITouchClientChannel } from '../../channel';
+
+/**
+ * Interface representing the external communication channel.
+ * Must be initialized before any `TouchStorage` instance is used.
+ */
+export interface IStorageChannel extends ITouchClientChannel {
+  /**
+   * Asynchronous send interface
+   * @param event Event name
+   * @param payload Event payload
+   */
+  send(event: string, payload: unknown): Promise<unknown>;
+
+  /**
+   * Synchronous send interface
+   * @param event Event name
+   * @param payload Event payload
+   */
+  sendSync(event: string, payload: unknown): unknown;
+}
+
+let channel: IStorageChannel | null = null;
+
+/**
+ * Initializes the global channel for communication.
+ *
+ * @example
+ * ```ts
+ * import { initStorageChannel } from './TouchStorage';
+ * import { ipcRenderer } from 'electron';
+ *
+ * initStorageChannel({
+ *   send: ipcRenderer.invoke.bind(ipcRenderer),
+ *   sendSync: ipcRenderer.sendSync.bind(ipcRenderer),
+ * });
+ * ```
+ */
+export function initStorageChannel(c: IStorageChannel): void {
+  channel = c;
+}
+
+/**
+ * Global registry of storage instances.
+ */
+export const storages = new Map<string, TouchStorage<any>>();
+
+/**
+ * A reactive storage utility with optional auto-save and update subscriptions.
+ *
+ * @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> = [];
+
+  /**
+   * The reactive data exposed to users.
+   */
+  public data: UnwrapNestedRefs<T>;
+
+  /**
+   * Creates a new reactive storage instance.
+   *
+   * @param qName Globally unique name for the instance
+   * @param initData Initial data to populate the storage
+   * @param onUpdate Optional callback when data is updated
+   *
+   * @example
+   * ```ts
+   * const settings = new TouchStorage('settings', { darkMode: false });
+   * ```
+   */
+  constructor(qName: string, initData: T, onUpdate?: () => void) {
+    if (storages.has(qName)) {
+      throw new Error(`Storage "${qName}" already exists`);
+    }
+    if (!channel) {
+      throw new Error(
+        'TouchStorage: channel is not initialized. Please call initStorageChannel(...) before using.'
+      );
+    }
+
+    this.#qualifiedName = qName;
+    this.originalData = initData;
+
+    // const stored = (channel.sendSync('storage:get', qName) as Partial<T>) || {};
+    this.data = reactive({ ...initData }) as UnwrapNestedRefs<T>;
+    this.loadFromRemote()
+
+    if (onUpdate) this._onUpdate.push(onUpdate);
+
+    channel.regChannel('storage:update', ({ data }) => {
+      const { name } = data!
+
+      if (name === qName) {
+        this.loadFromRemote()
+      }
+    })
+
+    storages.set(qName, this);
+  }
+
+  /**
+   * Returns the unique identifier of this storage.
+   *
+   * @example
+   * ```ts
+   * console.log(userStore.getQualifiedName()); // "user"
+   * ```
+   */
+  getQualifiedName(): string {
+    return this.#qualifiedName;
+  }
+
+  /**
+   * Checks whether auto-save is currently enabled.
+   *
+   * @example
+   * ```ts
+   * if (store.isAutoSave()) console.log("Auto-save is on!");
+   * ```
+   */
+  isAutoSave(): boolean {
+    return this.#autoSave;
+  }
+
+  /**
+   * Saves the current data to remote storage.
+   *
+   * @param options Optional configuration
+   * @param options.force Force save even if data is being assigned
+   *
+   * @example
+   * ```ts
+   * await store.saveToRemote();
+   * ```
+   */
+  saveToRemote = useDebounceFn(async (options?: { force?: boolean }): Promise<void> => {
+    if (!channel) {
+      throw new Error("TouchStorage: channel not initialized");
+    }
+
+    if (this.#assigning && !options?.force) {
+      console.debug("[Storage] Skip saveToRemote for", this.getQualifiedName());
+      return;
+    }
+
+    console.debug("Storage saveToRemote triggered", this.getQualifiedName());
+
+    await channel.send('storage:save', {
+      key: this.#qualifiedName,
+      content: JSON.stringify(this.data),
+      clear: false,
+    });
+  }, 300);
+
+  /**
+   * Enables or disables auto-saving.
+   *
+   * @param autoSave Whether to enable auto-saving
+   * @returns The current instance for chaining
+   *
+   * @example
+   * ```ts
+   * store.setAutoSave(true);
+   * ```
+   */
+  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 },
+      );
+    }
+
+    return this;
+  }
+
+  /**
+   * Registers a callback that runs when data changes (only triggered in auto-save mode).
+   *
+   * @param fn Callback function
+   *
+   * @example
+   * ```ts
+   * store.onUpdate(() => {
+   *   console.log('Data changed');
+   * });
+   * ```
+   */
+  onUpdate(fn: () => void): void {
+    this._onUpdate.push(fn);
+  }
+
+  /**
+   * Removes a previously registered update callback.
+   *
+   * @param fn The same callback used in `onUpdate`
+   *
+   * @example
+   * ```ts
+   * const cb = () => console.log("Change!");
+   * store.onUpdate(cb);
+   * store.offUpdate(cb);
+   * ```
+   */
+  offUpdate(fn: () => void): void {
+    const index = this._onUpdate.indexOf(fn);
+    if (index !== -1) {
+      this._onUpdate.splice(index, 1);
+    }
+  }
+
+  /**
+   * Internal method to assign new values and trigger update events. (Debounced)
+   *
+   * @param newData Partial update data
+   * @param stopWatch Whether to stop the watcher after assignment
+   */
+  assignDataDebounced = useDebounceFn(this.assignData.bind(this), 100)
+
+  /**
+   * Internal method to assign new values and trigger update events.
+   *
+   * @param newData Partial update data
+   * @param stopWatch Whether to stop the watcher during assignment
+   */
+  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()}`);
+    }
+
+    Object.assign(this.data, newData);
+    console.debug(`[Storage] Assign data to ${this.getQualifiedName()}`);
+
+    if (stopWatch && this.#autoSave) {
+      setTimeout(() => {
+        this.#assigning = false;
+        console.debug(`[Storage] Resume auto-save watch handle for ${this.getQualifiedName()}`);
+      }, 0);
+    }
+  }
+
+  /**
+   * Applies new data to the current storage instance. Use with caution.
+   *
+   * @param data Partial object to merge into current data
+   * @returns The current instance for chaining
+   *
+   * @example
+   * ```ts
+   * store.applyData({ theme: 'dark' });
+   * ```
+   */
+  applyData(data: Partial<T>): this {
+    this.assignData(data);
+    return this;
+  }
+
+  /**
+   * Reloads data from remote storage and applies it.
+   *
+   * @returns The current instance
+   *
+   * @example
+   * ```ts
+   * await store.reloadFromRemote();
+   * ```
+   */
+  async reloadFromRemote(): Promise<this> {
+    if (!channel) {
+      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);
+
+    return this;
+  }
+  /**
+   * Loads data from remote storage and applies it.
+   *
+   * @returns The current instance
+   *
+   * @example
+   * ```ts
+   * store.loadFromRemote();
+   * ```
+   */
+  loadFromRemote(): this {
+    if (!channel) {
+      throw new Error("TouchStorage: channel not initialized");
+    }
+
+    const result = channel.sendSync('storage:get', this.#qualifiedName)
+    const parsed = result ? (result as Partial<T>) : {};
+    this.assignData(parsed, true);
+
+    return this;
+  }
+}

package/renderer/storage/index.ts

@@ -0,0 +1 @@
+export * from './base-storage'