@blackglory/structures 0.14.14 → 0.15.0

package/README.md

@@ -248,7 +248,6 @@ class HashMap<K, V, Hash = unknown> {
 class HashSet<V, Hash = unknown> implements Iterable<V> {
   get [Symbol.toStringTag](): string
   get size(): number
-  [Symbol.iterator](): IterableIterator<V>
 
   constructor(hash: (value: V) => Hash)
 
@@ -416,39 +415,480 @@ class StringRadixTree<T> {
 Note that you might expect this data structure to be more space efficient than `BigMap`, but it doesn't.
 In V8, it can only store about 80% of data of `BigMap`.
 
-### SparseSet
+### DynamicTypedArray
+```ts
+class DynamicTypedArray<
+  T extends TypedArrayConstructor
+> implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get capacity(): number
+  get length(): number
+  readonly BYTES_PER_ELEMENT: number
+  readonly growthFactor: number
+
+  /**
+   * `DynamicTypedArray` cannot respond to any operations on the internal array,
+   * you must ensure that indexes accessed are less than the length of `DynamicTypedArray`.
+   */
+  get internalTypedArray(): TypedArrayOfConstructor<T>
+
+  constructor(
+    typedArrayConstructor: T
+  , options?: {
+      initialCapacity?: number = 0
+      growthFactor?: number = 1.5
+      fillValue?: number = 0
+    }
+  )
+
+  values(): IterableIterator<number>
+
+  set(index: number, value: number): void
+  setValues(index: number, values: ArrayLike<number>): void
+
+  get(index: number): number | undefined
+
+  push(...values: number[]): void
+  pop(): number | undefined
+
+  clear(): void
+  shrink(): void
+
+  sort(compare?: (a: number, b: number) => number): void
+}
+```
+
+This implementation applies to versions prior to ES2024,
+you might prefer using `ResizableTypedArray`.
+
+### ResizableTypedArray
+```ts
+class ResizableTypedArray<T extends TypedArrayConstructor> {
+  readonly maxCapacity: number
+  readonly growthFactor: number
+  readonly BYTES_PER_ELEMENT: number
+  readonly internalTypedArray: TypedArrayOfConstructor<T>
+
+  get [Symbol.toStringTag](): string
+  get capacity(): number
+  get length(): number
+
+  constructor(
+    typedArrayConstructor: T
+  , options: {
+      maxCapacity: number
+
+      initialCapacity?: capacity = 0
+      growthFactor?: number = 1.5
+      fillValue?: number = 0
+    }
+  )
+
+  set(index: number, value: number): void
+  setValues(index: number, values: ArrayLike<number>): void
+
+  get(index: number): number | undefined
+
+  push(...values: number[]): void
+  pop(): number | undefined
+
+  clear(): void
+  shrink(): void
+
+  sort(compare?: (a: number, b: number) => number): void
+}
+```
+
+This implementation is based on Resizable Array Buffers,
+support for which was introduced in ES2024.
+
+### SortedSet
+```ts
+class SortedSet<T> implements Iterable<T> {
+  get [Symbol.toStringTag](): string
+
+  constructor(compare: (a: T, b: T) => number)
+
+  values(): IterableIterator<T>
+
+  has(value: T): boolean
+  add(value: T): void
+  delete(value: T): void
+}
+```
+
+### DisjointSet
+```ts
+class DisjointSet {
+  has(value: number): boolean
+  sets(): number[][]
+
+  makeSet(value: number): number
+  union(a: number, b: number): void
+  find(value: number): number
+}
+```
+
+### Bit Set
+#### BitSet
+```ts
+class BitSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(bitsPerElement: number = 8)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): boolean
+  delete(value: number): boolean
+
+  clear(): void
+
+  clone(): BitSet
+}
+```
+
+Due to the length of arrays supported by JavaScript,
+`BitSet` cannot support very large values.
+
+#### TypedBitSet
+```ts
+class TypedBitSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get capacity(): number
+  get size(): number
+
+  constructor(array: UnsignedTypedArray)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): boolean
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### DynamicTypedBitSet
+```ts
+class DynamicTypedBitSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get capacity(): number
+  get size(): number
+
+  constructor(array: array: DynamicTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): boolean
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+Due to the length of arrays supported by JavaScript,
+`DynamicTypedBitSit` cannot support very large values.
+
+#### ResizableTypedBitSet
+```ts
+class ResizableTypedBitSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: ResizableTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): boolean
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+Due to the length of arrays supported by JavaScript,
+`ResizableTypedBitSit` cannot support very large values.
+
+### Sparse Set
+There are many implementations.
+Based on benchmark results, `TypedCleanSparseSet` is the fastest,
+followed by `TypedCleanSparseSetLite`.
+If array resizing is required,
+choose `DynamicTypedCleanSparseSetLite` or `ResizableTypedCleanSparseSetLite`.
+
+#### SparseSet
+```ts
+class SparseSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+
+  clone(): SparseSet
+}
+```
+
+#### CleanSparseSet
+```ts
+class CleanSparseSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+
+  clone(): CleanSparseSet
+}
+```
+
+#### TypedSparseSet
+```ts
+class TypedSparseSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: UnsignedTypedArray<ArrayBuffer>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### TypedSparseSetLite
+```ts
+class TypedSparseSetLite implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: UnsignedTypedArray<ArrayBuffer>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### TypedCleanSparseSet
+```ts
+class TypedCleanSparseSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: UnsignedTypedArray<ArrayBuffer>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### TypedCleanSparseSetLite
+```ts
+class TypedCleanSparseSetLite implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: UnsignedTypedArray<ArrayBuffer>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### DynamicTypedSparseSet
+```ts
+class DynamicTypedSparseSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### DynamicTypedSparseSetLite
+```ts
+class DynamicTypedSparseSetLite implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### DynamicTypedCleanSparseSet
 ```ts
-class SparseSet implements Iterable<number> {
+class DynamicTypedCleanSparseSet implements Iterable<number> {
   get [Symbol.toStringTag](): string
-  get [Symbol.iterator](): IterableIterator<number>
   get size(): number
 
-  constructor(array?: number[])
+  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>)
 
   values(): IterableIterator<number>
 
   has(value: number): boolean
   add(value: number): void
   delete(value: number): boolean
+
   clear(): void
+}
+```
 
-  clone(): SparseSet
+#### DynamicTypedCleanSparseSetLite
+```ts
+class DynamicTypedCleanSparseSetLite implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### ResizableTypedSparseSet
+```ts
+class ResizableTypedSparseSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: ResizableTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### ResizableTypedSparseSetLite
+```ts
+class ResizableTypedSparseSetLite implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: ResizableTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### ResizableTypedCleanSparseSet
+```ts
+class ResizableTypedCleanSparseSet implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: ResizableTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
+}
+```
+
+#### ResizableTypedCleanSparseSetLite
+```ts
+class ResizableTypedCleanSparseSetLite implements Iterable<number> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  constructor(array: ResizableTypedArray<UnsignedTypedArrayConstructor>)
+
+  values(): IterableIterator<number>
+
+  has(value: number): boolean
+  add(value: number): void
+  delete(value: number): boolean
+
+  clear(): void
 }
 ```
 
-### SparseMap
+### Sparse Map
+There are many implementations.
+Based on benchmark results, `TypedCleanSparseMap` is the fastest,
+followed by `TypedCleanSparseMapLite`.
+If array resizing is required,
+choose `DynamicTypedCleanSparseMapLite` or `ResizableTypedCleanSparseMapLite`.
+
+#### SparseMap
 ```ts
 class SparseMap<T> {
   get [Symbol.toStringTag](): string
   get size(): number
 
-  /**
-   * `SparseMap` cannot respond to any operations on the internal array,
-   * you must ensure that indexes accessed are less than the length of `SparseMap`.
-   * 
-   * Keys do not correspond to indexes of the array.
-   */
-  get internalArray(): T[]
+  readonly internalKeyArray: readonly number[]
+  readonly internalValueArray: T[]
 
   entries(): IterableIterator<[key: number, value: T]>
   keys(): IterableIterator<number>
@@ -459,77 +899,116 @@ class SparseMap<T> {
   has(key: number): boolean
   get(key: number): T | undefined
   set(key: number, value: T): void
-  delete(key: number): void
+  delete(key: number): boolean
+
   clear(): void
 }
 ```
 
-### DynamicTypedArray
+#### CleanSparseMap
 ```ts
-class DynamicTypedArray<T extends TypedArrayConstructor> {
+class CleanSparseMap<T> {
   get [Symbol.toStringTag](): string
-  get BYTES_PER_ELEMENT(): number
-  get capacity(): number
-  get length(): number
-  readonly growthFactor: number
+  get size(): number
 
-  /**
-   * `DynamicTypedArray` cannot respond to any operations on the internal array,
-   * you must ensure that indexes accessed are less than the length of `DynamicTypedArray`.
-   */
-  get internalTypedArray(): TypedArrayOfConstructor<T>
+  readonly internalKeyArray: readonly number[]
+  readonly internalValueArray: T[]
+
+  entries(): IterableIterator<[key: number, value: T]>
+  keys(): IterableIterator<number>
+  values(): IterableIterator<T>
+
+  getInternalIndexOfKey(key: number): number | undefined
+
+  has(key: number): boolean
+  get(key: number): T | undefined
+  set(key: number, value: T): void
+  delete(key: number): boolean
+
+  clear(): void
+}
+```
+
+#### TypedSparseMap
+```ts
+class TypedSparseMap<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
+  get [Symbol.toStringTag](): string
+  get size(): number
+
+  readonly internalKeyArray: TypedArrayOfConstructor<K, ArrayBuffer>
+  readonly internalValueArray: TypedArrayOfConstructor<V, ArrayBuffer>
 
   constructor(
-    typedArrayConstructor: T
-  , options?: {
-      capacity?: number = 0
-      growthFactor?: number = 1.5
-    }
+    keys: TypedArrayOfConstructor<K, ArrayBuffer>
+  , values: TypedArrayOfConstructor<V, ArrayBuffer>
   )
 
-  set(index: number, value: number): void
-  setValues(index: number, values: TypedArrayOfConstructor<T>): void
-  get(index: number): number | undefined
-  push(...values: number[]): void
-  pop(): number | undefined
+  entries(): IterableIterator<[key: number, value: number]>
+  keys(): IterableIterator<number>
+  values(): IterableIterator<number>
+
+  getInternalIndexOfKey(key: number): number | undefined
+
+  has(key: number): boolean
+  get(key: number): number | undefined
+  set(key: number, value: number): void
+  delete(key: number): boolean
+
   clear(): void
-  sort(compare?: (a: number, b: number) => number): void
 }
 ```
 
-### TypedSparseSet
+#### TypedSparseMapLite
 ```ts
-class TypedSparseSet<T extends UnsignedTypedArrayConstructor> {
+class TypedSparseMapLite<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
   get [Symbol.toStringTag](): string
-  get [Symbol.iterator](): IterableIterator<number>
   get size(): number
 
-  constructor(array: DynamicTypedArray<T>)
+  readonly internalKeyArray: TypedArrayOfConstructor<K, ArrayBuffer>
+  readonly internalValueArray: TypedArrayOfConstructor<V, ArrayBuffer>
 
+  constructor(
+    keys: TypedArrayOfConstructor<K, ArrayBuffer>
+  , values: TypedArrayOfConstructor<V, ArrayBuffer>
+  )
+
+  entries(): IterableIterator<[key: number, value: number]>
+  keys(): IterableIterator<number>
   values(): IterableIterator<number>
 
-  has(value: number): boolean
-  add(value: number): void
-  delete(value: number): boolean
+  getInternalIndexOfKey(key: number): number | undefined
+
+  has(key: number): boolean 
+  get(key: number): number | undefined
+  set(key: number, value: number): void
+  delete(key: number): boolean
+
   clear(): void
 }
 ```
 
-### TypedSparseMap
+#### TypedCleanSparseMap
 ```ts
-class TypedSparseMap<T extends TypedArrayConstructor> {
+class TypedCleanSparseMap<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
   get [Symbol.toStringTag](): string
   get size(): number
 
-  /**
-   * `SparseMap` cannot respond to any operations on the internal array,
-   * you must ensure that indexes accessed are less than the length of `SparseMap`.
-   * 
-   * Keys do not correspond to indexes of the array.
-   */
-  get internalTypedArray(): TypedArrayOfConstructor<T>
+  readonly internalKeyArray: TypedArrayOfConstructor<K, ArrayBuffer>
+  readonly internalValueArray: TypedArrayOfConstructor<V, ArrayBuffer>
 
-  constructor(array: DynamicTypedArray<T>)
+  constructor(
+    keys: TypedArrayOfConstructor<K, ArrayBuffer>
+  , values: TypedArrayOfConstructor<V, ArrayBuffer>
+  )
 
   entries(): IterableIterator<[key: number, value: number]>
   keys(): IterableIterator<number>
@@ -538,80 +1017,170 @@ class TypedSparseMap<T extends TypedArrayConstructor> {
   getInternalIndexOfKey(key: number): number | undefined
 
   has(key: number): boolean
-  get(key: number): T | undefined
+  get(key: number): number | undefined
   set(key: number, value: number): void
-  delete(key: number): void
+  delete(key: number): boolean
+
   clear(): void
 }
 ```
 
-### SortedSet
+#### TypedCleanSparseMapLite
 ```ts
-class SortedSet<T> {
+class TypedCleanSparseMapLite<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
   get [Symbol.toStringTag](): string
-  [Symbol.iterator](): IterableIterator<T>
+  get size(): number
 
-  constructor(compare: (a: T, b: T) => number)
+  readonly internalKeyArray: TypedArrayOfConstructor<K, ArrayBuffer>
+  readonly internalValueArray: TypedArrayOfConstructor<V, ArrayBuffer>
 
-  values(): IterableIterator<T>
-  has(value: T): boolean
-  add(value: T): void
-  delete(value: T): void
+  constructor(
+    keys: TypedArrayOfConstructor<K, ArrayBuffer>
+  , values: TypedArrayOfConstructor<V, ArrayBuffer>
+  )
+
+  entries(): IterableIterator<[key: number, value: number]>
+  keys(): IterableIterator<number>
+  values(): IterableIterator<number>
+
+  getInternalIndexOfKey(key: number): number | undefined
+
+  has(key: number): boolean 
+  get(key: number): number | undefined 
+  set(key: number, value: number): void
+  delete(key: number): boolean
+
+  clear(): void
 }
 ```
 
-### BitSet
+#### DynamicTypedSparseMapLite
 ```ts
-class BitSet {
+class DynamicTypedSparseMapLite<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
   get [Symbol.toStringTag](): string
   get size(): number
-  [Symbol.iterator](): IterableIterator<number>
 
-  constructor(bitsPerElement: number = 8)
+  get internalKeyArray(): TypedArrayOfConstructor<K>
+  get internalValueArray(): TypedArrayOfConstructor<V>
+
+  constructor(
+    keys: DynamicTypedArray<K>
+  , values: DynamicTypedArray<V>
+  )
 
+  entries(): IterableIterator<[key: number, value: number]>
+  keys(): IterableIterator<number>
   values(): IterableIterator<number>
 
-  has(value: number): boolean
-  add(value: number): boolean
-  delete(value: number): boolean
-  clear(): void
+  getInternalIndexOfKey(key: number): number | undefined
 
-  clone(): BitSet
+  has(key: number): boolean
+  get(key: number): number | undefined
+  set(key: number, value: number): void
+  delete(key: number): boolean
+
+  clear(): void
 }
 ```
 
-Due to the length of arrays supported by JavaScript,
-`BitSet` cannot support very large values.
-
-### TypedBitSet
+#### DynamicTypedCleanSparseMapLite
 ```ts
-class TypedBitSet<T extends UnsignedTypedArrayConstructor> {
+class DynamicTypedCleanSparseMapLite<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
   get [Symbol.toStringTag](): string
   get size(): number
-  [Symbol.iterator](): IterableIterator<number>
 
-  constructor(array: DynamicTypedArray<T>)
+  get internalKeyArray(): TypedArrayOfConstructor<K>
+  get internalValueArray(): TypedArrayOfConstructor<V>
+
+  constructor(
+    keys: DynamicTypedArray<K>
+  , values: DynamicTypedArray<V>
+  )
 
+  entries(): IterableIterator<[key: number, value: number]>
+  keys(): IterableIterator<number>
   values(): IterableIterator<number>
 
-  has(value: number): boolean
-  add(value: number): boolean
-  delete(value: number): boolean
+  getInternalIndexOfKey(key: number): number | undefined
+
+  has(key: number): boolean
+  get(key: number): number | undefined
+  set(key: number, value: number): void
+  delete(key: number): boolean
+
   clear(): void
 }
 ```
 
-Due to the length of arrays supported by JavaScript,
-`TypedBitSit` cannot support very large values.
+#### ResizableTypedSparseMapLite
+```ts
+class ResizableTypedSparseMapLite<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
+  get [Symbol.toStringTag](): string
+  get size(): number
 
-### DisjointSet
+  readonly internalKeyArray: TypedArrayOfConstructor<K>
+  readonly internalValueArray: TypedArrayOfConstructor<V>
+
+  constructor(
+    keys: ResizableTypedArray<K>
+  , values: ResizableTypedArray<V>
+  )
+
+  entries(): IterableIterator<[key: number, value: number]>
+  keys(): IterableIterator<number>
+  values(): IterableIterator<number>
+
+  getInternalIndexOfKey(key: number): number | undefined
+
+  has(key: number): boolean
+  get(key: number): number | undefined
+  set(key: number, value: number): void
+  delete(key: number): boolean
+
+  clear(): void
+}
+```
+
+#### ResizableTypedCleanSparseMapLite
 ```ts
-class DisjointSet {
-  has(value: number): boolean
-  sets(): number[][]
+class ResizableTypedCleanSparseMapLite<
+  K extends UnsignedTypedArrayConstructor
+, V extends TypedArrayConstructor
+> {
+  get [Symbol.toStringTag](): string
+  get size(): number
 
-  makeSet(value: number): number
-  union(a: number, b: number): void
-  find(value: number): number
+  readonly internalKeyArray: TypedArrayOfConstructor<K>
+  readonly internalValueArray: TypedArrayOfConstructor<V>
+
+  constructor(
+    keys: ResizableTypedArray<K>
+  , values: ResizableTypedArray<V>
+  )
+
+  entries(): IterableIterator<[key: number, value: number]>
+  keys(): IterableIterator<number>
+  values(): IterableIterator<number>
+
+  getInternalIndexOfKey(key: number): number | undefined
+
+  has(key: number): boolean
+  get(key: number): number | undefined
+  set(key: number, value: number): void
+  delete(key: number): boolean
+
+  clear(): void
 }
 ```