@blackglory/structures 0.13.2 → 0.13.4

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)
+    }
+  }
+}

package/src/radix-tree.ts

@@ -0,0 +1,264 @@
+import { toArray, first, map, find } from 'iterable-operator'
+import { isntUndefined } from 'extra-utils'
+
+class TreeNode<T, U> {
+  children = new Map<T[], TreeNode<T, U>>()
+
+  constructor(public value?: U) {}
+}
+
+export class RadixTree<K extends Iterable<T>, V, T = unknown> {
+  private root = new TreeNode<T, V>()
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  entries(): IterableIterator<[key: T[], value: V]> {
+    return dfs(this.root, [])
+
+    function* dfs(
+      node: TreeNode<T, V>
+    , path: T[]
+    ): IterableIterator<[key: T[], value: V]> {
+      for (const [prefix, childNode] of node.children) {
+        const newPath = [...path, ...prefix]
+        if (isntUndefined(childNode.value)) {
+          yield [newPath, childNode.value]
+        }
+
+        yield* dfs(childNode, newPath)
+      }
+    }
+  }
+
+  keys(): IterableIterator<T[]> {
+    return map(this.entries(), ([key]) => key)
+  }
+
+  values(): IterableIterator<V> {
+    return map(this.entries(), ([, value]) => value)
+  }
+
+  set(key: K, value: V): this {
+    set(toArray(key), value, this.root)
+    return this
+
+    function set(key: T[], value: V, node: TreeNode<T, V>): void {
+      const commonPrefix = findCommonPrefix(node.children.keys(), key)
+      if (isntUndefined(commonPrefix)) {
+        const { prefix, commonPartLength } = commonPrefix
+        if (prefix.length === commonPartLength) {
+          // 现有节点的前缀整个都被使用的情况, 不需要在这一级创建新的前缀节点.
+          const prefixNode = node.children.get(prefix)!
+
+          if (key.length === prefix.length) {
+            // 前缀节点就是目标节点.
+            prefixNode.value = value
+          } else {
+            // 前缀节点不是目标节点
+            const newKey = key.slice(prefix.length)
+            set(newKey, value, prefixNode)
+          }
+        } else {
+          // 并非整个现有节点的前缀都被使用, 说明需要在这一级创建新的前缀节点,
+          // 并将原前缀节点作为子节点接在新前缀节点之后.
+          const oldPrefixNode = node.children.get(prefix)!
+          const commonPrefix = prefix.slice(0, commonPartLength)
+          const newPrefixNode = new TreeNode<T, V>()
+          node.children.set(commonPrefix, newPrefixNode)
+          newPrefixNode.children.set(prefix.slice(commonPartLength), oldPrefixNode)
+          newPrefixNode.children.set(key.slice(commonPartLength), new TreeNode<T, V>(value))
+          node.children.delete(prefix)
+        }
+      } else {
+        node.children.set(key, new TreeNode(value))
+      }
+    }
+  }
+
+  has(key: K): boolean {
+    return has(toArray(key), this.root)
+
+    function has(key: T[], node: TreeNode<T, V>): boolean {
+      const matchedPrefix = matchPrefix(node.children.keys(), key)
+      if (isntUndefined(matchedPrefix)) {
+        const restKey = key.slice(matchedPrefix.length)
+        if (restKey.length === 0) {
+          return true
+        } else {
+          return has(restKey, node.children.get(matchedPrefix)!)
+        }
+      } else {
+        return false
+      }
+    }
+  }
+
+  get(key: K): V | undefined {
+    return get(toArray(key), this.root)
+
+    function get(key: T[], node: TreeNode<T, V>): V | undefined {
+      const matchedPrefix = matchPrefix(node.children.keys(), key)
+      if (isntUndefined(matchedPrefix)) {
+        const restKey = key.slice(matchedPrefix.length)
+        const nextNode = node.children.get(matchedPrefix)!
+        if (restKey.length === 0) {
+          return nextNode.value
+        } else {
+          return get(restKey, nextNode)
+        }
+      } else {
+        return undefined
+      }
+    }
+  }
+
+  delete(key: K): boolean {
+    return _delete(toArray(key), this.root)
+
+    function _delete(key: T[], node: TreeNode<T, V>): boolean {
+      const matchedPrefix = matchPrefix(node.children.keys(), key)
+      if (isntUndefined(matchedPrefix)) {
+        if (key.length === matchedPrefix.length) {
+          // 下一个子节点就是目标节点.
+          const targetNode = node.children.get(matchedPrefix)!
+          if (targetNode.children.size === 0) {
+            // 要删除的目标节点不是一个父节点, 可以直接删除.
+            // 与目标节点共享相同前缀的其他节点可能会因此这次的删除而导致发生与父节点的合并.
+            node.children.delete(matchedPrefix)
+          } else {
+            // 要删除的目标节点是一个父节点, 首先删除目标节点包含的值, 然后检查它的子节点是否只有一个.
+            delete node.value
+            if (targetNode.children.size === 1) {
+              // 如果子节点只有一个, 说明目标节点的子节点可以与目标节点合并.
+              // 即`(prefix, child)`合并为`(prefixchild)`.
+              const [key, value] = first(targetNode.children.entries())!
+              node.children.set([...matchedPrefix, ...key], value)
+              node.children.delete(matchedPrefix)
+            }
+          }
+          return true
+        } else {
+          // 下一个子节点不是目标节点.
+          const nextNode = node.children.get(matchedPrefix)!
+          const nextKey = key.slice(matchedPrefix.length)
+          const deleted = _delete(nextKey, nextNode)
+          if (deleted) {
+            // 最终找到了目标节点并删除了它, 现在执行与nextNode有关的合并操作, 以删除不必要的节点.
+            if (!('value' in nextNode)) {
+              // 只有在nextNode自身不具有值的情况下, nextNode才是能够被合并的.
+              switch (nextNode.children.size) {
+                case 0: {
+                  // 自身没有值的nextNode节点是不必要的, 因为它不是一个父节点.
+                  node.children.delete(matchedPrefix)
+                  break
+                }
+                case 1: {
+                  // 自身没有值的nextNode节点是不必要的, 虽然它是一个父节点, 但它只有一个子节点.
+                  // 这说明nextNode的子节点可以与nextNode合并, 替代nextNode当前的位置.
+                  // 即`(prefix, child)`合并为`(prefixchild)`.
+                  const [key, value] = first(nextNode.children.entries())!
+                  node.children.set([...matchedPrefix, ...key], value)
+                  node.children.delete(matchedPrefix)
+                  break
+                }
+                default: {
+                  // 自身没有值, 但起前缀作用的nextNode节点是必要的,
+                  // 但在有后代被删除的情况下, 可能会需要合并子节点的前缀.
+                  // 在此检查子节点的前缀, 如果子节点具有共同前缀, 则合并前缀.
+                  const entries = toArray(nextNode.children.entries())
+                  const keys = entries.map(([key]) => key)
+                  const commonPrefix = getCommonPrefix(keys)
+                  if (commonPrefix) {
+                    const newPrefix = [...matchedPrefix, ...commonPrefix]
+                    const childNode = new TreeNode<T, V>()
+                    for (const [key, value] of entries) {
+                      childNode.children.set(key.slice(commonPrefix.length), value)
+                    }
+                    node.children.set(newPrefix, childNode)
+                    node.children.delete(matchedPrefix)
+                  }
+                }
+              }
+            }
+            return true
+          } else {
+            // 最终没有找到目标节点.
+            return false
+          }
+        }
+      } else {
+        return false
+      }
+    }
+  }
+}
+
+/**
+ * 查找prefixes里与path的前缀匹配的项目.
+ * 
+ * @param prefixes 所有前缀都不能在首部有重合.
+ */
+export function matchPrefix<T>(prefixes: Iterable<T[]>, path: T[]): T[] | undefined {
+  return find(prefixes, prefix => path[0] === prefix[0])
+}
+
+/**
+ * 查找prefixes与path的共同前缀, 结果可能是其中一整个prefix, 或者其中一个prefix的前缀部分.
+ * 
+ * @param prefixes 所有前缀都不能在首部有重合.
+ */
+export function findCommonPrefix<T>(prefixes: Iterable<T[]>, path: T[]): {
+  prefix: T[]
+  commonPartLength: number
+} | undefined {
+  for (const prefix of prefixes) {
+    let commonPartLength = 0
+    for (let i = 0; i < prefix.length; i++) {
+      if (path[i] === prefix[i]) {
+        commonPartLength++
+      } else {
+        if (commonPartLength > 0) {
+          return { prefix, commonPartLength }
+        }
+      }
+    }
+    if (commonPartLength > 0) {
+      return { prefix, commonPartLength }
+    }
+  }
+}
+
+
+/**
+ * 返回一组可迭代值的共同前缀.
+ */
+export function getCommonPrefix<T>(paths: T[][]): T[] {
+  if (paths.length > 0) {
+    const commonPrefix: T[] = []
+
+    loop: for (
+      let elementIndex = 0, firstPathLength = paths[0].length
+    ; elementIndex < firstPathLength
+    ; elementIndex++
+    ) {
+      const element = paths[0][elementIndex]
+      for (let pathIndex = 1; pathIndex < paths.length; pathIndex++) {
+        const path = paths[pathIndex]
+        if (elementIndex < path.length) {
+          if (path[elementIndex] !== element) {
+            break loop
+          }
+        } else {
+          break loop
+        }
+      }
+      commonPrefix.push(element)
+    }
+
+    return commonPrefix
+  } else {
+    return []
+  }
+}

package/src/sorted-set.ts

@@ -0,0 +1,34 @@
+import { SkipList } from '@utils/skip-list.js'
+import { map } from 'iterable-operator'
+
+export class SortedSet<T> implements Iterable<T> {
+  private skipList: SkipList<T>
+
+  get [Symbol.toStringTag](): string {
+    return this.constructor.name
+  }
+
+  [Symbol.iterator](): IterableIterator<T> {
+    return this.values()
+  }
+
+  constructor(compare: (a: T, b: T) => number) {
+    this.skipList = new SkipList(compare)
+  }
+
+  values(): IterableIterator<T> {
+    return map(this.skipList.elements(), node => node.value!)
+  }
+
+  has(value: T): boolean {
+    return this.skipList.has(value)
+  }
+
+  add(value: T): void {
+    this.skipList.add(value)
+  }
+
+  delete(value: T): void {
+    this.skipList.delete(value)
+  }
+}