55ab-loach

loach

TypeScript 数据结构与算法工具库。

安装

npm install 55ab-loach

使用

import { Stack, Queue, QuadTree, AsyncQueue, math } from "55ab-loach";

---

Stack 栈

后进先出（LIFO）数据结构。

构造

const stack = new Stack<number>();
const stack = new Stack<number>({ maxCount: 100, items: [1, 2, 3] });

API

属性：maxCount（可读写，默认 1000）

---

Queue 队列

先进先出（FIFO）数据结构。

构造

const queue = new Queue<number>();
const queue = new Queue<number>({ maxCount: 100, items: [1, 2, 3] });

API

属性：maxCount（可读写，默认 1000）

---

QuadTree 四叉树

空间分区数据结构，适用于碰撞检测、空间查询等场景。支持矩形和圆形两种形状。

构造

const qt = new QuadTree<IQuadItemObject>({
  x: 0,
  y: 0,
  width: 800,
  height: 600,
  maxObjects: 10, // 每个节点最大对象数，默认 10
  maxLevels: 4, // 最大分割层级，默认 4
});

数据类型

// 矩形对象
const rect: IQuadItemObject = {
  shape: "rect",
  x: 10,
  y: 10,
  width: 20,
  height: 20,
};

// 圆形对象
const circle: IQuadItemObject = { shape: "circle", x: 50, y: 50, radius: 10 };

API

属性：x, y, width, height, level, maxObjects（可读写）, maxLevels（可读写）, nodes, objects

碰撞检测示例

const qt = new QuadTree<IQuadItemObject>({
  x: 0,
  y: 0,
  width: 800,
  height: 600,
  maxObjects: 4,
});

const player = { shape: "rect", x: 100, y: 100, width: 20, height: 20 };
qt.insert(player);

// 查询与 player 同象限的候选对象
const candidates = qt.query(player);

// 查询指定矩形范围内的对象
const nearby = qt.queryRange({
  shape: "rect",
  x: 90,
  y: 90,
  width: 40,
  height: 40,
});

---

AsyncQueue 异步队列

并发控制的异步函数执行队列，支持任务调度、暂停/恢复、优先级和事件订阅。

构造

const queue = new AsyncQueue<number, number>({
  concurrency: 3,       // 最大并发数，默认 1
  timeout: 5000,        // 任务超时时间（ms），默认 0（不超时）
  retryCount: 2,        // 失败重试次数，默认 0
  retryDelay: 1000,     // 重试间隔（ms），默认 1000
  autoStart: true,      // 是否自动开始，默认 true
});

API

事件

示例

const queue = new AsyncQueue<string, number>({ concurrency: 2 });

queue.on("taskEnd", ({ result }) => {
  console.log("任务完成:", result);
});

queue.enqueue(async () => {
  const response = await fetch("https://api.example.com/data");
  return response.json();
});

queue.enqueue(async () => "second task", 1); // 高优先级

queue.start();

---

math 数学工具

import { math } from "55ab-loach";

math.distance(x1, y1, x2, y2); // 两点距离
math.rad(v1, v2); // 两点角度（弧度）
math.abs(a); // 绝对值
math.random(from, to, fixed); // 随机数
math.randomUint(from, to, fixed); // 随机正数

---

开发

npm run build       # 构建
npm run test        # 运行测试
npm run test:watch  # 监听模式运行测试