@blackglory/structures 0.13.3 → 0.14.0

package/src/dynamic-typed-array.ts

@@ -0,0 +1,201 @@
+import { TypedArrayConstructor, TypedArrayOfConstructor } from 'justypes'
+import { assert } from '@blackglory/errors'
+
+interface IDynamicTypedArrayOptions {
+  capacity?: number
+  growthFactor?: number
+}
+
+// 相关提案: https://github.com/tc39/proposal-resizablearraybuffer
+export class DynamicTypedArray<T extends TypedArrayConstructor> {
+  private array: TypedArrayOfConstructor<T>
+  private _length: number = 0
+  private initialCapacity: number
+  readonly growthFactor: number
+
+  get internalTypedArray(): TypedArrayOfConstructor<T> {
+    return this.array
+  }
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get BYTES_PER_ELEMENT(): number {
+    return this.typedArrayConstructor.BYTES_PER_ELEMENT
+  }
+
+  /**
+   * 数组当前的容量.
+   */
+  get capacity(): number {
+    return this.array.length
+  }
+
+  /**
+   * 数组逻辑上的长度, 总是小于或等于capacity.
+   */
+  get length(): number {
+    return this._length
+  }
+
+  constructor(
+    private typedArrayConstructor: T
+  , {
+      capacity = 0
+    , growthFactor = 1.5
+    }: IDynamicTypedArrayOptions = {}
+  ) {
+    assert(Number.isInteger(capacity), 'capacity must be an integer')
+    assert(capacity >= 0, 'capacity must be greater than or equal to 0')
+    assert(growthFactor >= 1, 'growthFactory must be greater than or equal to 1')
+
+    this.initialCapacity = capacity
+    this.array = new typedArrayConstructor(capacity) as TypedArrayOfConstructor<T>
+    this.growthFactor = growthFactor
+  }
+
+  set(index: number, value: number): void {
+    if (index >= this.capacity) {
+      const newCapacity = computeNewCapacity(
+        this.capacity
+      , index + 1
+      , this.growthFactor
+      )
+      this.resize(newCapacity)
+    }
+
+    if (index >= this._length) {
+      this._length = index + 1
+    }
+
+    this.array[index] = value
+  }
+
+  setValues(index: number, values: TypedArrayOfConstructor<T>): void {
+    if (index + values.length >= this.capacity) {
+      const newCapacity = computeNewCapacity(
+        this.capacity
+      , index + values.length
+      , this.growthFactor
+      )
+      this.resize(newCapacity)
+    }
+
+    if (index + values.length > this._length) {
+      this._length = index + values.length
+    }
+
+    this.internalTypedArray.set(values, index)
+  }
+
+  get(index: number): number | undefined {
+    return index < this._length
+         ? this.array[index]
+         : undefined
+  }
+
+  push(...values: number[]): void {
+    const newLength = this._length + values.length
+    if (newLength > this.capacity) {
+      const newCapacity = computeNewCapacity(
+        this.capacity
+      , newLength
+      , this.growthFactor
+      )
+      this.resize(newCapacity)
+    }
+
+    for (const value of values) {
+      this.array[this._length++] = value
+    }
+  }
+
+  pop(): number | undefined {
+    if (this._length > 0) {
+      const value = this.array[this._length - 1]
+      this._length--
+
+      const newCapacity = computeNewCapacity(
+        this.capacity
+      , this.length
+      , this.growthFactor
+      )
+      this.resize(newCapacity)
+
+      return value
+    } else {
+      return undefined
+    }
+  }
+
+  clear(): void {
+    this._length = 0
+    const newArray = new this.typedArrayConstructor(this.initialCapacity)
+    this.array = newArray as TypedArrayOfConstructor<T>
+  }
+
+  sort(compare?: (a: number, b: number) => number): void {
+    const capacity = this.capacity
+    this.resize(this.length)
+    this.array.sort(compare)
+    this.resize(capacity)
+  }
+
+  private resize(newCapacity: number): void {
+    if (this.array.length === newCapacity) {
+      return
+    } else if (this.array.length < newCapacity) {
+      const newArray = new this.typedArrayConstructor(newCapacity)
+      newArray.set(this.array)
+      this.array = newArray as TypedArrayOfConstructor<T>
+    } else if (this.array.length > newCapacity) {
+      const newArray = new this.typedArrayConstructor(newCapacity)
+      // 不需要的部分将被舍弃.
+      for (let i = newCapacity; i--;) {
+        newArray[i] = this.array[i]
+      }
+      this.array = newArray as TypedArrayOfConstructor<T>
+    }
+  }
+}
+
+export function computeNewCapacity(
+  oldCapacity: number
+, targetLength: number
+, growthFactor: number
+): number {
+  if (growthFactor === 1) {
+    return targetLength
+  } else {
+    if (oldCapacity === targetLength) {
+      return targetLength
+    } else if (oldCapacity < targetLength) { 
+      // 增加容量以适配targetLength
+      let newCapacity = Math.max(oldCapacity, 1)
+      while (newCapacity < targetLength) {
+        newCapacity *= growthFactor
+      }
+      return Math.floor(newCapacity)
+    } else {
+      // 尝试减少容量以适配targetLength
+
+      // `targetLength = 0`是特殊情况,
+      // 此时无论怎么将oldCapacity除以growthFactory几次, 都不可能得到比targetLength小的结果.
+      if (targetLength === 0) {
+        return 0
+      } else {
+        let newCapacity = oldCapacity
+        while (true) {
+          const temp = newCapacity / growthFactor
+          if (temp < targetLength) {
+            break
+          } else {
+            newCapacity = temp
+          }
+        }
+        return Math.floor(newCapacity)
+      }
+    }
+  }
+}

package/src/emitter.ts

@@ -0,0 +1,76 @@
+import { go } from '@blackglory/go'
+
+type Listener<Args extends unknown[]> = (...args: Args) => void
+
+export class Emitter<
+  EventToArgs extends Record<Event, unknown[]> = Record<
+    string | number | symbol
+  , unknown[]
+  >
+, Event extends string | number | symbol = keyof EventToArgs
+> {
+  private map = new Map<
+    Event
+  , Set<Listener<EventToArgs[Event]>>
+  >()
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  on<T extends Event>(
+    event: T
+  , listener: Listener<EventToArgs[T]>
+  ): () => void {
+    const set = go(() => {
+      const set = this.map.get(event)
+      if (set) {
+        return set
+      } else {
+        const set = new Set<Listener<EventToArgs[keyof EventToArgs]>>()
+        this.map.set(event, set)
+        return set
+      }
+    })
+    set.add(handler as Listener<EventToArgs[Event]>)
+
+    return () => {
+      const handlers = this.map.get(event)
+      if (handlers) {
+        const deleted = handlers.delete(
+          handler as Listener<EventToArgs[Event]>
+        )
+        if (deleted && handlers.size === 0) {
+          this.map.delete(event)
+        }
+      }
+    }
+
+    function handler(...args: Parameters<Listener<EventToArgs[T]>>): void {
+      listener(...args)
+    }
+  }
+
+  once<T extends Event>(
+    event: T
+  , listener: Listener<EventToArgs[T]>
+  ): () => void {
+    const removeListener = this.on(
+      event
+    , (...args: Parameters<Listener<EventToArgs[T]>>) => {
+        listener(...args)
+        removeListener()
+      }
+    )
+
+    return removeListener
+  }
+
+  emit<T extends Event>(event: T, ...args: EventToArgs[T]): void {
+    this.map.get(event)?.forEach(cb => cb(...args))
+  }
+
+  removeAllListeners<T extends Event>(event: T): void {
+    this.map.get(event)?.clear()
+  }
+}

package/src/expirable-map.ts

@@ -0,0 +1,122 @@
+import { setSchedule } from 'extra-timers'
+
+export class ExpirableMap<K, V> {
+  private map = new Map<K, V>()
+  private cancelScheduledCleaner?: () => void
+
+  /**
+   * 按过期时间升序排列所有项目的元数据
+   */
+  protected itemMetadataSortedByExpirationTime: Array<{
+    key: K
+    expirationTime: number
+  }> = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+
+  set(key: K, value: V, timeToLive: number = Infinity): this {
+    this.map.set(key, value)
+
+    this.removeItemMetadata(key)
+    this.addItemMetadata(key, Date.now() + timeToLive)
+
+    return this
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key)
+  }
+
+  get(key: K): V | undefined {
+    return this.map.get(key)
+  }
+
+  delete(key: K): boolean {
+    const exists = this.map.delete(key)
+    if (exists) {
+      const index = this.itemMetadataSortedByExpirationTime.findIndex(x => x.key === key)
+      this.itemMetadataSortedByExpirationTime.splice(index, 1)
+
+      // 如果被删除的项目是第一个项目, 则需要重新规划过期清理器
+      if (index === 0) {
+        this.cancelScheduledCleaner?.()
+        this.scheduleCleaner()
+      }
+    }
+    return exists
+  }
+
+  clear(): void {
+    this.map.clear()
+    this.cancelScheduledCleaner?.()
+    this.itemMetadataSortedByExpirationTime = []
+  }
+
+  private addItemMetadata(key: K, expirationTime: number): void {
+    for (let i = 0; i < this.itemMetadataSortedByExpirationTime.length; i++) {
+      const item = this.itemMetadataSortedByExpirationTime[i]
+      if (expirationTime < item.expirationTime) {
+        this.itemMetadataSortedByExpirationTime.splice(i, 0, { key, expirationTime })
+
+        // 如果本次插入导致原先的第一个项目不再是第一个项目, 则需要重新规划过期清理器
+        if (i === 0) {
+          this.cancelScheduledCleaner?.()
+          this.scheduleCleaner()
+        }
+
+        return
+      }
+    }
+
+    // 如果代码运行到此处, 意味着数组要么为空, 要么新项目过期时间大于数组内的所有项目, 故直接插入到数组尾端.
+    this.itemMetadataSortedByExpirationTime.push({ key, expirationTime })
+    // 如果新插入的项目是唯一而项目, 则需要重新规划过期清理器
+    if (this.itemMetadataSortedByExpirationTime.length === 1) {
+      this.cancelScheduledCleaner?.()
+      this.scheduleCleaner()
+    }
+  }
+
+  private removeItemMetadata(key: K): void {
+    const index = this.itemMetadataSortedByExpirationTime.findIndex(x => x.key === key)
+    if (index >= 0) {
+      this.itemMetadataSortedByExpirationTime.splice(index, 1)
+
+      // 如果被移除的是第一个项目, 则需要重新规划过期清理器
+      if (index === 0) {
+        this.cancelScheduledCleaner?.()
+        this.scheduleCleaner()
+      }
+    }
+  }
+
+  private scheduleCleaner(): void {
+    if (this.itemMetadataSortedByExpirationTime.length > 0) {
+      const item = this.itemMetadataSortedByExpirationTime[0]
+      if (Number.isFinite(item.expirationTime)) {
+        this.cancelScheduledCleaner = setSchedule(item.expirationTime, () => {
+          this.clearExpiredItems(Date.now())
+          this.cancelScheduledCleaner?.()
+          this.scheduleCleaner()
+        })
+      }
+    }
+  }
+
+  private clearExpiredItems(timestamp: number): void {
+    const indexOfFirstUnexpired = this.itemMetadataSortedByExpirationTime.findIndex(
+      x => x.expirationTime > timestamp
+    )
+    const expiredItemKeys =
+      indexOfFirstUnexpired >= 0
+      ? this.itemMetadataSortedByExpirationTime.splice(0, indexOfFirstUnexpired)
+      : this.itemMetadataSortedByExpirationTime.splice(0, this.itemMetadataSortedByExpirationTime.length)
+    expiredItemKeys.forEach(x => this.map.delete(x.key))
+  }
+}

package/src/hash-map.ts

@@ -0,0 +1,34 @@
+export class HashMap<K, V, Hash = unknown> {
+  private map = new Map<Hash, V>()
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+
+  constructor(private hash: (key: K) => Hash) {}
+
+  set(key: K, value: V): this {
+    this.map.set(this.hash(key), value)
+    return this
+  }
+
+  has(key: K): boolean {
+    return this.map.has(this.hash(key))
+  }
+
+  get(key: K): V | undefined {
+    return this.map.get(this.hash(key))
+  }
+
+  delete(key: K): boolean {
+    return this.map.delete(this.hash(key))
+  }
+
+  clear(): void {
+    this.map.clear()
+  }
+}

package/src/hash-set.ts

@@ -0,0 +1,38 @@
+export class HashSet<V, Hash = unknown> implements Iterable<V> {
+  private map = new Map<Hash, V>()
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+
+  [Symbol.iterator](): IterableIterator<V> {
+    return this.map.values()
+  }
+
+  constructor(private hash: (value: V) => Hash) {}
+
+  add(value: V): this {
+    this.map.set(this.hash(value), value)
+    return this
+  }
+
+  delete(value: V): boolean {
+    return this.map.delete(this.hash(value))
+  }
+
+  has(value: V): boolean {
+    return this.map.has(this.hash(value))
+  }
+
+  clear(): void {
+    this.map.clear()
+  }
+
+  values(): IterableIterator<V> {
+    return this.map.values()
+  }
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export * from './box.js'
+export * from './cons.js'
+export * from './array.js'
+export * from './emitter.js'
+export * from './big-map.js'
+export * from './big-set.js'
+export * from './hash-map.js'
+export * from './hash-set.js'
+export * from './queue.js'
+export * from './lru-map.js'
+export * from './expirable-map.js'
+export * from './tlru-map.js'
+export * from './trie-map.js'
+export * from './string-trie-map.js'
+export { RadixTree } from './radix-tree.js'
+export { StringRadixTree } from './string-radix-tree.js'
+export * from './sparse-set.js'
+export * from './sparse-map.js'
+export * from './typed-sparse-map.js'
+export * from './typed-sparse-set.js'
+export { DynamicTypedArray } from './dynamic-typed-array.js'
+export * from './sorted-set.js'
+export * from './bit-set.js'
+export * from './typed-bit-set.js'

package/src/lru-map.ts

@@ -0,0 +1,69 @@
+import { assert } from '@blackglory/errors'
+import { first } from 'iterable-operator'
+
+export class LRUMap<K, V> {
+  private limit: number
+  private map = new Map<K, V>()
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.map.size
+  }
+
+  constructor(limit: number) {
+    assert(Number.isInteger(limit), 'The parameter limit must be an integer')
+    assert(limit > 0, 'The parameter limit must be a positive value')
+
+    this.limit = limit
+  }
+
+  set(key: K, value: V): this {
+    if (this.map.has(key)) {
+      this.updateItem(key, value)
+    } else {
+      if (this.map.size === this.limit) {
+        this.map.delete(this.getColdestKey()!)
+      }
+      this.map.set(key, value)
+    }
+    return this
+  }
+
+  has(key: K): boolean {
+    return this.map.has(key)
+  }
+
+  get(key: K): V | undefined {
+    if (!this.has(key)) return undefined
+
+    const value = this.map.get(key)!
+    this.updateItem(key, value)
+    return value
+  }
+
+  delete(key: K): boolean {
+    return this.map.delete(key)
+  }
+
+  clear(): void {
+    this.map.clear()
+  }
+
+  /**
+   * Reinsert the item.
+   */
+  private updateItem(key: K, value: V): void {
+    this.map.delete(key)
+    this.map.set(key, value)
+  }
+
+  /**
+   * Return the earliest key inserted in the Map
+   */
+  private getColdestKey(): K | undefined {
+    return first(this.map.keys())
+  }
+}

package/src/queue.ts

@@ -0,0 +1,30 @@
+export class Queue<T> {
+  private items: T[] = []
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  get size(): number {
+    return this.items.length
+  }
+
+  empty(): void {
+    this.items.length = 0
+  }
+
+  enqueue(...items: T[]): void {
+    this.items.push(...items)
+  }
+
+  dequeue(): T | undefined {
+    return this.items.shift()
+  }
+
+  remove(item: T): void {
+    let index: number
+    while ((index = this.items.indexOf(item)) >= 0) {
+      this.items.splice(index, 1)
+    }
+  }
+}