# @blackglory/structures 中文文档

规范地址：https://npmcn.com/package/%40blackglory/structures/

版本：0\.15\.4
npm 元数据更新时间：2026-10-07T19:37:26.955Z
中文译文更新时间：2026-11-08T05:51:19.964Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40blackglory/structures
原文对照：https://npmcn.com/package/%40blackglory/structures/?lang=original
项目主页：https://github.com/BlackGlory/structures#readme
源码仓库：https://github.com/BlackGlory/structures

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：483 kB，239 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：6 个
- 首次发布：2020-12-19T12:33:11.007Z
- 最新版本发布：2026-10-07T19:37:26.746Z
- 近 30 天下载量：22023（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：112（近 12 个月 9 个）

## 中文简介

共同结构.

## 安装

```sh
npm install @blackglory/structures
```

也可以使用：`pnpm add @blackglory/structures`、`yarn add @blackglory/structures`、`bun add @blackglory/structures`

## README

# 结构

共同结构.

## 安装

```sh
npm install --save @blackglory/structures
# or
yarn add @blackglory/structures
```

## API 密码

### 方框

```ts
class Box<T> {
  get [Symbol.toStringTag](): string

  constructor(value: T)

  get(): T
  set(value: T): void
}
```

### 计数

#### 转换 ConstoArray 格式

```ts
function convertConsToArray<T>([value, next]: Cons<T>): T[]
```

#### 转换箭头

```ts
function convertArrayToCons<T>([value, ...next]: T[]): Cons<T>
```

### 阵列

#### 切片箭头

```ts
function sliceArrayLeft<T>(arr: readonly T[], num: number): T[]
```

#### 切片箭头右侧

```ts
function sliceArrayRight<T>(arr: readonly T[], num: number): T[]
```

#### 短线箭头左转

```ts
function truncateArrayLeft(arr: unknown[], num: number): void
```

#### 截线箭头右转

```ts
function truncateArrayRight(arr: unknown[], num: number): void
```

#### 清除箭头

```ts
function clearArray(arr: unknown[]): void
```

### 已键入阵列

#### 获取 MaxValeof 未签名的已签名图

```ts
function getMaxValueOfUnsignedTypedArray(array: UnsignedTypedArray): number
```

#### 获得MaxValeof 未签名的箭头构造器

```ts
function getMaxValueOfUnsignedTypedArrayConstructor(
  constructor: UnsignedTypedArrayConstructor
): number
```

### 发送器

```ts
type Listener<Args extends unknown[]> = (...args: Args) => void

class Emitter<
  EventToArgs extends Record<Event, unknown[]> = Record<
    string | number | symbol
  , unknown[]
  >
, Event extends string | number | symbol = keyof EventToArgs
> {
  get [Symbol.toStringTag](): string

  on<T extends Event>(event: T, listener: Listener<EventToArgs[T]>): () => void
  once<T extends Event>(event: T, listener: Listener<EventToArgs[T]>): () => void
  emit<T extends Event>(event: T, ...args: EventToArgs[T]): void
  removeAllListeners<T extends Event>(event: T): void
}
```

### 发电机

```ts
type Listener<Args extends unknown[], Yield, Next> = (...args: Args) =>
| void
| Generator<Yield, void, Next>

class GeneratorEmitter<
  EventToArgs extends Record<Event, unknown[]> = Record<
    string | number | symbol
  , unknown[]
  >
, Event extends string | number | symbol = keyof EventToArgs
, Yield = unknown
, Next = unknown
> {
  get [Symbol.toStringTag](): string

  on<T extends Event>(
    event: T
  , listener: Listener<EventToArgs[T], Yield, Next>
  ): () => void

  once<T extends Event>(
    event: T
  , listener: Listener<EventToArgs[T], Yield, Next>
  ): () => void

  emit<T extends Event>(
    event: T
  , ...args: EventToArgs[T]
  ): Generator<Yield, void, Next>

  removeAllListeners<T extends Event>(event: T): void
}
```

### AsyncGenerator 编辑器

```ts
type Listener<Args extends unknown[], Yield, Next> = (...args: Args) =>
| void
| Generator<Yield, void, Next>
| AsyncGenerator<Yield, void, Next>

class AsyncGeneratorEmitter<
  EventToArgs extends Record<Event, unknown[]> = Record<
    string | number | symbol
  , unknown[]
  >
, Event extends string | number | symbol = keyof EventToArgs
, Yield = unknown
, Next = unknown
> {
  get [Symbol.toStringTag](): string

  on<T extends Event>(event: T
  , listener: Listener<EventToArgs[T], Yield, Next>
  ): () => void

  once<T extends Event>(
    event: T
  , listener: Listener<EventToArgs[T], Yield, Next>
  ): () => void

  emit<T extends Event>(
    event: T
  , ...args: EventToArgs[T]
  ): AsyncGenerator<Yield, void, Next>

  removeAllListeners<T extends Event>(event: T): void
}
```

### 大地图

```ts
class BigMap<K, V> implements Iterable<[K, V]> {
  get [Symbol.toStringTag](): string

  get size(): number

  set(key: K, value: V): void
  has(key: K): boolean
  get(key: K): V | undefined
  delete(key: K): boolean
  clear(): void

  entries(): IterableIterator<[K, V]>
  keys(): IterableIterator<K>
  values(): IterableIterator<V>
}
```

这个 `Map` 支持无限元素.

请注意: `BigMap` 无法保留元素的插入顺序.

```ts
// Map
const map = new Map()
for (let i = 0; i < 100_000_000; i++) {
  map.set(i, null) // RangeError
}
console.log('Never')

// BigMap
const { BigMap } = require('.')
const map = new BigMap()
for (let i = 0; i < 100_000_000; i++) {
  map.set(i, null)
}
console.log('Done')
```

### 大队

```ts
class BigSet<T> implements Iterable<T> {
  get [Symbol.toStringTag]: string

  get size(): number

  add(value: T): this
  has(value: T): boolean
  delete(value: T): boolean
  clear(): void

  values(): IterableIterator<T>
}
```

这个 `Set` 支持无限元素.

请注意: `BigSet` 无法保留元素的插入顺序.

```ts
// Set
const set = new Set()
for (let i = 0; i < 100_000_000; i++) {
  set.add(i) // RangeError
}
console.log('Never')

// BigSet
const set = new BigSet()
for (let i = 0; i < 100_000_000; i++) {
  set.add(i)
}
console.log('Done')
```

### 散列图

```ts
class HashMap<K, V, Hash = unknown> {
  get [Symbol.toStringTag](): string
  get size(): number

  constructor(hash: (key: K) => Hash)

  set(key: K, value: V): this
  has(key: K): boolean
  get(key: K): V | undefined
  delete(key: K): boolean
  clear(): void
  values(): IterableIterator<V>
}
```

### 散装

```ts
class HashSet<V, Hash = unknown> implements Iterable<V> {
  get [Symbol.toStringTag](): string
  get size(): number

  constructor(hash: (value: V) => Hash)

  add(value: V): this
  delete(value: V): boolean
  has(value: V): boolean
  get(value: V): V | undefined
  clear(): void
  keys(): IterableIterator<V>
  values(): IterableIterator<V>
}
```

### 半径

```ts
class LRUMap<K, V> {
  get [Symbol.toStringTag](): string
  get size(): number

  constructor(limit: number)

  set(key: K, value: V): this
  has(key: K): boolean
  get(key: K): V | undefined
  delete(key: K): boolean
  clear(): void
}
```

### 可过期映射

```ts
class ExpirableMap<K, V> {
  get[Symbol.toStringTag](): string
  get size(): number

  constructor()

  set(key: K, value: V, timeToLive?: number = Infinity): this
  has(key: K): boolean
  get(key: K): V | undefined
  delete(key: K): boolean
  clear(): void
}
```

### TLRUMAP (法语)

```ts
class TLRUMap<K, V> {
  get[Symbol.toStringTag](): string
  get size(): number

  constructor(limit: number)

  set(key: K, value: V, timeToLive?: number = Infinity): this
  has(key: K): boolean
  get(key: K): V | undefined
  delete(key: K): boolean
  clear(): void
}
```

### 队列

```ts
class Queue<T> {
  get [Symbol.toStringTag](): string
  get size(): number

  empty(): void
  enqueue(...items: T[]): void
  dequeue(): T | undefined

  // O(n)
  remove(item: T): void
}
```

### 唯一队列

```ts
class UniqueQueue<T> {
  get [Symbol.toStringTag](): string
  get size(): number

  empty(): void
  enqueue(...items: T[]): void
  dequeue(): T | undefined

  // Better than O(n)
  remove(item: T): void
}
```

### 三进制图

```ts
class TrieMap<K extends Iterable<T>, V, T = unknown> {
  get [Symbol.toStringTag](): string

  keys(): IterableIterator<T[]>
  values(): IterableIterator<V>
  entries(): IterableIterator<[key: T[], value: V]>

  set(key: K, value: V): this
  has(key: K): boolean
  get(key: K): V | undefined
  delete(key: K): boolean
}
```

请注意,您可能期望这一数据结构比 `BigMap`但它没有. 在V8中,它只能存储大约80%的数据 `BigMap`。 。 。 .

### 字符串图

```ts
class StringTrieMap<T> {
  get [Symbol.toStringTag](): string

  keys(): IterableIterator<string>
  values(): IterableIterator<T>
  entries(): IterableIterator<[key: string, value: T]>

  set(key: string, value: T): this
  has(key: string): boolean
  get(key: string): T | undefined
  delete(key: string): boolean
}
```

请注意,您可能期望这一数据结构比 `BigMap`但它没有. 在V8中,它只能存储大约80%的数据 `BigMap`。 。 。 .

### 半径

```ts
class RadixTree<K extends Iterable<T>, V, T = unknown> {
  get [Symbol.toStringTag](): string

  entries(): IterableIterator<[key: T[], value: V]>
  keys(): IterableIterator<T[]>
  values(): IterableIterator<V>

  set(key: K, value: V): this
  has(key: K): boolean
  get(key: K): V | undefined
  delete(key: K): boolean
}
```

请注意,您可能期望这一数据结构比 `BigMap`但它没有. 在V8中,它只能存储大约80%的数据 `BigMap`。 。 。 .

### 字符串RadixTree 键

```ts
class StringRadixTree<T> {
  get [Symbol.toStringTag](): string

  keys(): IterableIterator<string>
  values(): IterableIterator<T>
  entries(): IterableIterator<[key: string, value: T]>

  set(key: string, value: T): this
  has(key: string): boolean
  get(key: string): T | undefined
  delete(key: string): boolean
}
```

请注意,您可能期望这一数据结构比 `BigMap`但它没有. 在V8中,它只能存储大约80%的数据 `BigMap`。 。 。 .

### 动态串行阵列

```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
}
```

这一实施适用于ES-2024之前的版本, 你可能更喜欢使用 `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
}
```

这一实施基于可调整阵列缓冲器, eS2024号文件提出了这方面的支持.

### 排序的设置

```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
}
```

### 断开组合

```ts
class DisjointSet {
  has(value: number): boolean
  sets(): number[][]

  makeSet(value: number): number
  union(a: number, b: number): void
  find(value: number): number
}
```

### 位集

#### 位元组

```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
}
```

由于JavaScript支持的数组长度, `BitSet` 无法支持非常大的值.

#### 键入BitSet

```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
}
```

#### 动态 Typed BitSet

```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
}
```

由于JavaScript支持的数组长度, `DynamicTypedBitSit` 无法支持非常大的值.

#### 可调整的 Typed BitSet

```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
}
```

由于JavaScript支持的数组长度, `ResizableTypedBitSit` 无法支持非常大的值.

### 组合

执行工作很多. 根据基准结果, `TypedCleanSparseSet` 这是最快的, 接下来是 `TypedCleanSparseSetLite`。 。 。 . 如果需要阵列调整大小, 选择 `DynamicTypedCleanSparseSetLite` 或者说 `ResizableTypedCleanSparseSetLite`。 。 。 .

#### 组合

```ts
class SparseSet implements Iterable<number> {
  get [Symbol.toStringTag](): string
  get size(): number

  values(): IterableIterator<number>

  has(value: number): boolean
  add(value: number): boolean
  delete(value: number): boolean

  clear(): void

  clone(): SparseSet
}
```

#### 清除分隔套件

```ts
class CleanSparseSet implements Iterable<number> {
  get [Symbol.toStringTag](): string
  get size(): number

  values(): IterableIterator<number>

  has(value: number): boolean
  add(value: number): boolean
  delete(value: number): boolean

  clear(): void

  clone(): CleanSparseSet
}
```

#### 已键入SparseSet

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 已键入SparseSetLite

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 已键入的 CleanSparse 集

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 已键入的 CleanSparseSetLite

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 动态磁盘组合

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 动态编程SparseSetLite

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 动态 Typed 清除程序

```ts
class DynamicTypedCleanSparseSet implements Iterable<number> {
  get [Symbol.toStringTag](): string
  get size(): number

  constructor(array: DynamicTypedArray<UnsignedTypedArrayConstructor>)

  values(): IterableIterator<number>

  has(value: number): boolean
  add(value: number): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 动态 Typed 清理SparseetLite

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 可调整的 Typed 组合

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 可缩放的 TypedSparseSetLite

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 可调整的 Typed 清空相册

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

#### 可缩放的 Typed 清空SparseSetLite

```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): boolean
  delete(value: number): boolean

  clear(): void
}
```

### 映射图

执行工作很多. 根据基准结果, `TypedCleanSparseMap` 这是最快的, 接下来是 `TypedCleanSparseMapLite`。 。 。 . 如果需要阵列调整大小, 选择 `DynamicTypedCleanSparseMapLite` 或者说 `ResizableTypedCleanSparseMapLite`。 。 。 .

#### 图像

```ts
class SparseMap<T> {
  get [Symbol.toStringTag](): string
  get size(): number

  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
}
```

#### 清理图像

```ts
class CleanSparseMap<T> {
  get [Symbol.toStringTag](): string
  get size(): number

  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
}
```

#### 键入Sparse映射

```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(
    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
}
```

#### 已键入SparseMapLite

```ts
class TypedSparseMapLite<
  K extends UnsignedTypedArrayConstructor
, V extends TypedArrayConstructor
> {
  get [Symbol.toStringTag](): string
  get size(): number

  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>

  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
}
```

#### 已键入的 CleanSparseMap

```ts
class TypedCleanSparseMap<
  K extends UnsignedTypedArrayConstructor
, V extends TypedArrayConstructor
> {
  get [Symbol.toStringTag](): string
  get size(): number

  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>

  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
}
```

#### 已键入的 CleanSparseMapLite

```ts
class TypedCleanSparseMapLite<
  K extends UnsignedTypedArrayConstructor
, V extends TypedArrayConstructor
> {
  get [Symbol.toStringTag](): string
  get size(): number

  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>

  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
}
```

#### 动态磁盘平面图

```ts
class DynamicTypedSparseMapLite<
  K extends UnsignedTypedArrayConstructor
, V extends TypedArrayConstructor
> {
  get [Symbol.toStringTag](): string
  get size(): number

  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>

  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
}
```

#### 动态Typed 清理图

```ts
class DynamicTypedCleanSparseMapLite<
  K extends UnsignedTypedArrayConstructor
, V extends TypedArrayConstructor
> {
  get [Symbol.toStringTag](): string
  get size(): number

  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>

  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
}
```

#### 可缩放的 TypedSparse 地图

```ts
class ResizableTypedSparseMapLite<
  K extends UnsignedTypedArrayConstructor
, V extends TypedArrayConstructor
> {
  get [Symbol.toStringTag](): string
  get size(): 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
}
```

#### 可缩放的 Typed 清除地图

```ts
class ResizableTypedCleanSparseMapLite<
  K extends UnsignedTypedArrayConstructor
, V extends TypedArrayConstructor
> {
  get [Symbol.toStringTag](): string
  get size(): 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
}
```

## 常见问题

### @blackglory/structures 是什么？

共同结构\.

### 如何安装 @blackglory/structures？

在项目目录运行 npm install @blackglory/structures，或使用 pnpm add / yarn add / bun add。

### @blackglory/structures 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @blackglory/structures 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @blackglory/structures 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @blackglory/structures 可以商用吗？

@blackglory/structures 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @blackglory/structures 的下载量有多少？

根据 npm 官方下载统计，@blackglory/structures 在 2026/10/09 – 2026/11/07 这 30 天内被下载 22,023 次，日均约 734 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @blackglory/structures 还在维护吗？

最新版本 0\.15\.4 发布于 2026/10/08（1 个月前）；至今共发布 112 个版本，其中过去 12 个月发布了 9 个；首次发布于 2020/12/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。