feat: implement HybridSet class and createHybridSet function

Author: Simon-He95

src/perf/createHybridMap.ts

@@ -1,10 +1,27 @@
 type Primitive = string | number | symbol | boolean | null | undefined
 type KeyType = object | Primitive
 
+/**
+ * HybridMap 是一个支持对象和原始类型（如字符串、数字、布尔值等）作为 key 的 Map 实现。
+ * - 对象类型的 key 使用 WeakMap 存储，原始类型的 key 使用 Map 存储。
+ * - 这样既可以用对象做 key，也可以用字符串、数字等做 key，且对象 key 不会阻止垃圾回收。
+ * - 不支持遍历和 size 属性，因为 WeakMap 无法遍历。
+ *
+ * 示例用法：
+ * ```ts
+ * const map = createHybridMap<any, string>([[{}, 'obj'], ['a', 'str']])
+ * map.set(123, 'num')
+ * map.set({}, 'another obj')
+ * ```
+ */
 export class HybridMap<K extends KeyType, V> {
   private objectStore: WeakMap<object, V>
   private primitiveStore: Map<Primitive, V>
 
+  /**
+   * 构造函数，可选初始化 entries
+   * @param entries 初始键值对数组
+   */
   constructor(entries?: readonly (readonly [K, V])[] | null) {
     this.objectStore = new WeakMap()
     this.primitiveStore = new Map()
@@ -15,10 +32,16 @@ export class HybridMap<K extends KeyType, V> {
     }
   }
 
+  /** 判断 key 是否为 object 类型 */
   private isObjectKey(key: K): key is Record<any, any> {
     return typeof key === 'object' && key !== null
   }
 
+  /**
+   * 设置键值对
+   * @param key 键
+   * @param value 值
+   */
   set(key: K, value: V): this {
     if (this.isObjectKey(key)) {
       this.objectStore.set(key, value)
@@ -29,6 +52,10 @@ export class HybridMap<K extends KeyType, V> {
     return this
   }
 
+  /**
+   * 获取指定 key 的值
+   * @param key 键
+   */
   get(key: K): V | undefined {
     if (this.isObjectKey(key)) {
       return this.objectStore.get(key as object)
@@ -38,6 +65,10 @@ export class HybridMap<K extends KeyType, V> {
     }
   }
 
+  /**
+   * 判断是否存在指定 key
+   * @param key 键
+   */
   has(key: K): boolean {
     if (this.isObjectKey(key)) {
       return this.objectStore.has(key as object)
@@ -47,6 +78,10 @@ export class HybridMap<K extends KeyType, V> {
     }
   }
 
+  /**
+   * 删除指定 key
+   * @param key 键
+   */
   delete(key: K): boolean {
     if (this.isObjectKey(key)) {
       return this.objectStore.delete(key as object)
@@ -56,48 +91,68 @@ export class HybridMap<K extends KeyType, V> {
     }
   }
 
+  /** 清空所有 key */
   clear(): void {
     this.primitiveStore.clear()
     this.objectStore = new WeakMap()
   }
 
+  /** 不支持 size 属性，因 WeakMap 无法遍历 */
   get size(): number {
     throw new Error(
       'HybridMap does not support size due to WeakMap limitations.',
     )
   }
 
+  /** 不支持 forEach，因 WeakMap 无法遍历 */
   forEach(): void {
     throw new Error(
       'HybridMap does not support forEach due to WeakMap limitations.',
     )
   }
 
+  /** 不支持 keys 迭代，因 WeakMap 无法遍历 */
   keys() {
     throw new Error(
       'HybridMap does not support iteration due to WeakMap limitations.',
     )
   }
 
+  /** 不支持 values 迭代，因 WeakMap 无法遍历 */
   values() {
     throw new Error(
       'HybridMap does not support iteration due to WeakMap limitations.',
     )
   }
 
+  /** 不支持 entries 迭代，因 WeakMap 无法遍历 */
   entries() {
     throw new Error(
       'HybridMap does not support iteration due to WeakMap limitations.',
     )
   }
 
+  /** 不支持迭代器，因 WeakMap 无法遍历 */
   [Symbol.iterator]() {
     throw new Error(
       'HybridMap does not support iteration due to WeakMap limitations.',
     )
   }
 }
 
+/**
+ * createHybridMap 是 HybridMap 的工厂函数。
+ * 用于创建支持对象和原始类型作为 key 的 Map 实例。
+ * @param entries 可选的初始键值对数组
+ * @returns HybridMap 实例
+ *
+ * 示例用法：
+ * ```ts
+ * const map = createHybridMap<any, string>([[{}, 'obj'], ['a', 'str']])
+ * map.set(123, 'num')
+ * map.set({}, 'another obj')
+ * ```
+ */
 export function createHybridMap<K extends KeyType, V>(
   entries?: readonly (readonly [K, V])[] | null,
 ): HybridMap<K, V> {

src/perf/createHybridSet.ts

@@ -0,0 +1,104 @@
+type Primitive = string | number | symbol | boolean | null | undefined
+type KeyType = object | Primitive
+
+/**
+ * HybridSet 是一个支持对象和原始类型（如字符串、数字、布尔值等）作为元素的 Set 实现。
+ * - 对象类型的元素使用 WeakSet 存储，原始类型的元素使用 Set 存储。
+ * - 这样既可以用对象做元素，也可以用字符串、数字等做元素，且对象元素不会阻止垃圾回收。
+ * - 不支持遍历和 size 属性，因为 WeakSet 无法遍历。
+ *
+ * 示例用法：
+ * ```ts
+ * const set = createHybridSet<any>([{}, 'a', 123])
+ * set.add('b')
+ * set.add({})
+ * ```
+ */
+export class HybridSet<T extends KeyType> {
+  private objectStore: WeakSet<object>
+  private primitiveStore: Set<Primitive>
+
+  /**
+   * 构造函数，可选初始化 values
+   * @param values 初始元素数组
+   */
+  constructor(values?: readonly T[] | null) {
+    this.objectStore = new WeakSet()
+    this.primitiveStore = new Set()
+    if (values) {
+      for (const v of values) {
+        this.add(v)
+      }
+    }
+  }
+
+  /** 判断元素是否为 object 类型 */
+  private isObjectKey(key: T): key is Record<any, any> {
+    return typeof key === 'object' && key !== null
+  }
+
+  /**
+   * 添加元素
+   * @param value 元素
+   */
+  add(value: T): this {
+    if (this.isObjectKey(value)) {
+      this.objectStore.add(value)
+    }
+    else {
+      this.primitiveStore.add(value as Primitive)
+    }
+    return this
+  }
+
+  /**
+   * 判断是否存在指定元素
+   * @param value 元素
+   */
+  has(value: T): boolean {
+    if (this.isObjectKey(value)) {
+      return this.objectStore.has(value)
+    }
+    else {
+      return this.primitiveStore.has(value as Primitive)
+    }
+  }
+
+  /**
+   * 删除指定元素
+   * @param value 元素
+   */
+  delete(value: T): boolean {
+    if (this.isObjectKey(value)) {
+      return this.objectStore.delete(value)
+    }
+    else {
+      return this.primitiveStore.delete(value as Primitive)
+    }
+  }
+
+  /** 清空所有元素 */
+  clear(): void {
+    this.primitiveStore.clear()
+    this.objectStore = new WeakSet()
+  }
+}
+
+/**
+ * createHybridSet 是 HybridSet 的工厂函数。
+ * 用于创建支持对象和原始类型作为元素的 Set 实例。
+ * @param values 可选的初始元素数组
+ * @returns HybridSet 实例
+ *
+ * 示例用法：
+ * ```ts
+ * const set = createHybridSet<any>([{}, 'a', 123])
+ * set.add('b')
+ * set.add({})
+ * ```
+ */
+export function createHybridSet<T extends KeyType>(
+  values?: readonly T[] | null,
+): HybridSet<T> {
+  return new HybridSet(values)
+}

src/perf/index.ts

@@ -11,3 +11,4 @@ export * from './useRic'
 export * from './once'
 export * from './createChunk'
 export * from './createHybridMap'
+export * from './createHybridSet'