@zk-tech/bedrock 0.0.1

package/src/lock/shared-mutex.ts

@@ -0,0 +1,242 @@
+import { lvAssert, lvAssertNotNil } from '@/assert';
+import { listenOnce } from '@/event';
+import { SharedCapability, Capability, CapabilityStatus } from './capability';
+import { Semaphore } from './semaphore';
+
+/**
+ * 提供读写能力的共享互斥量
+ *
+ * 参考C++17标准库双门思想实现
+ * 接口也与标准库保持一致
+ * 方法内部禁止promise，只可以对外暴露promise
+ *
+ * 核心
+ * - 写写互斥，读写互斥，读读可重入
+ *
+ * 使用举例：
+ * class Foo {
+ *   private _mutex = new SharedMutex();
+ *
+ *   async add() {
+ *     // 上写锁
+ *     await this._mutex.lock();
+ *     // ...write something
+ *     this._mutex.unlock();
+ *   }
+ *
+ *   async getSomething1() {
+ *     // 上读锁
+ *     await this._mutex.lockShared();
+ *     try {
+ *       return xxx;
+ *     } finally {
+ *       this._mutex.unlockShared();
+ *     }
+ *   }
+ *
+ *   async getSomething2() {
+ *     // 上读锁
+ *     await this._mutex.lockShared();
+ *     try {
+ *       return xxx;
+ *     } finally {
+ *       this._mutex.unlockShared();
+ *     }
+ *   }
+ * }
+ */
+export class SharedMutex {
+  // 在第一道门外等待的写者
+  private readonly _waitingWriters: Semaphore[] = [];
+
+  // 已经通过了第一道门的写者
+  // 如果在第二道门外等待，状态为sharedLocked
+  // 如果已经进入到第二道门内拿到了锁，状态为locked
+  private _writer?: Capability;
+
+  // 在第一道门外等待的读者
+  private _waitingReader?: Semaphore;
+
+  // 拿到锁的读者
+  private _reader?: SharedCapability;
+
+  /**
+   * 是否被锁住
+   */
+  public isLocked() {
+    return this._writer || this._readerCount !== 0;
+  }
+
+  /**
+   * 等待并获取写锁
+   */
+  public lock(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      // 第一道门
+      if (this._writer) {
+        // 如果已经有写者进入了，其他写者等待
+        const token = new Semaphore();
+        this._waitingWriters.push(token);
+        token.onActive(() => {
+          this._writerEnterGate1(resolve);
+        });
+      } else {
+        this._writerEnterGate1(resolve);
+      }
+    });
+  }
+
+  /**
+   * 尝试获取写锁，立刻返回结果
+   */
+  public tryLock(): boolean {
+    if (this._writer || this._readerCount > 0) {
+      return false;
+    }
+    // 这里不需要await，一定可以上锁
+    this.lock();
+    return true;
+  }
+
+  /**
+   * 解除写锁
+   */
+  public unLock(): void {
+    lvAssertNotNil(this._writer);
+
+    // 打开第一道门
+    this._writer.release();
+  }
+
+  /**
+   * 等待并获取读锁
+   */
+  public lockShared(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      // 读者只需要进第一道门
+      if (this._writer) {
+        // 如果有写者已经进入了第一道门，读者等待
+        if (!this._waitingReader) {
+          this._waitingReader = new Semaphore();
+        }
+        this._waitingReader.onActive(() => {
+          this._readerEnterGate1(resolve);
+        });
+      } else {
+        this._readerEnterGate1(resolve);
+      }
+    });
+  }
+
+  /**
+   * 尝试获取读锁，立刻返回结果
+   */
+  public tryLockShared(): boolean {
+    if (this._writer) {
+      return false;
+    }
+    // 不需要await，一定可以上锁
+    this.lockShared();
+    return true;
+  }
+
+  /**
+   * 解除读锁
+   */
+  public unLockShared(): void {
+    lvAssertNotNil(this._reader);
+    if (this._writer) {
+      // TODO(niurouwan): 暂时保留，方便验证，稳定后可以去掉
+      lvAssert(this._writer.status === CapabilityStatus.Unlocked);
+    }
+
+    this._reader.release();
+  }
+
+  /**
+   * 获取当前读者数量
+   */
+  private get _readerCount(): number {
+    return this._reader ? this._reader.counter : 0;
+  }
+
+  /**
+   * 写者进入第一道门
+   */
+  private _writerEnterGate1(resolve: () => void): void {
+    lvAssert(!this._writer);
+    // 确定写者，关第一道门
+    this._writer = new Capability();
+
+    // 第二道门
+    // 等待所有读者出去
+    if (this._readerCount > 0) {
+      listenOnce(this._reader!.onUnlocked)(() => {
+        this._writerEnterGate2(resolve);
+      });
+    } else {
+      this._writerEnterGate2(resolve);
+    }
+  }
+
+  /**
+   * 写者进入第二道门
+   */
+  private _writerEnterGate2(resolve: () => void): void {
+    lvAssertNotNil(this._writer);
+    lvAssert(this._readerCount === 0);
+
+    // 成功加锁
+    this._writer.acquire();
+    listenOnce(this._writer.onUnlocked)(() => {
+      lvAssertNotNil(this._writer);
+      // 不再持有
+      this._writer = undefined;
+      this._moveForward();
+    });
+    resolve();
+  }
+
+  /**
+   * 读者进入第一道门
+   */
+  private _readerEnterGate1(resolve: () => void): void {
+    lvAssert(!this._writer);
+
+    // 门外等待的读者清除
+    this._waitingReader = undefined;
+
+    if (!this._reader) {
+      this._reader = new SharedCapability();
+      this._reader.acquire();
+      listenOnce(this._reader.onUnlocked)(() => {
+        this._moveForward();
+      });
+    } else {
+      this._reader.acquire();
+    }
+    resolve();
+  }
+
+  /**
+   * 锁释放时推进流程
+   */
+  private _moveForward(): void {
+    // 如果有写者在等待在第二道门前面，那么此时推进的一定是读锁释放，直接return即可
+    if (this._writer) {
+      return;
+    }
+
+    // 写者优先，优先通知在第一道门前面的写者
+    if (this._waitingWriters.length > 0) {
+      const semaphore = this._waitingWriters.shift()!;
+      semaphore.notify();
+      return;
+    }
+
+    // 最后通知第一道门前面的读者
+    if (this._waitingReader) {
+      this._waitingReader.notify();
+    }
+  }
+}

package/src/lock/utils.test.ts

@@ -0,0 +1,165 @@
+import { SharedMutex } from './shared-mutex';
+import { transferSharedLock, transferLock, tryTransferLock } from './utils';
+
+function isMutexReleased(mutex: SharedMutex) {
+  return !mutex.isLocked();
+}
+
+describe('transferLock', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  // 正常上锁并且解锁
+  it('lock and unlock', async () => {
+    const mutex = new SharedMutex();
+    const unlockable = await transferLock(mutex);
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    unlockable.unlock();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+  });
+
+  // 上锁，超时导致释放锁
+  it('lock and timeout', async () => {
+    const mutex = new SharedMutex();
+    await transferLock(mutex, 10);
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+  });
+
+  // 超时后，重复解锁，不报错
+  it('timeout then unlock', async () => {
+    const mutex = new SharedMutex();
+    const unlockable = await transferLock(mutex, 10);
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+    expect(() => {
+      unlockable.unlock();
+      unlockable.dispose();
+    }).not.toThrowError();
+  });
+
+  // 上锁，超时导致释放锁，锁转移
+  it('repeatedly lock', async () => {
+    const mutex = new SharedMutex();
+    await transferLock(mutex, 10);
+    transferLock(mutex).then(() => {
+      // ...
+    });
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeFalsy();
+  });
+});
+
+describe('tryTransferLock', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  // 正常上锁并且解锁
+  it('lock and unlock', () => {
+    const mutex = new SharedMutex();
+    const unlockable = tryTransferLock(mutex);
+    expect(unlockable).not.toBeUndefined();
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    unlockable!.unlock();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+  });
+
+  // 上锁，超时导致释放锁
+  it('lock and timeout', async () => {
+    const mutex = new SharedMutex();
+    expect(tryTransferLock(mutex, 10)).not.toBeUndefined();
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+  });
+
+  // 超时后，重复解锁，不报错
+  it('timeout then unlock', async () => {
+    const mutex = new SharedMutex();
+    const unlockable = tryTransferLock(mutex, 10);
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+    expect(() => {
+      unlockable!.unlock();
+      unlockable!.dispose();
+    }).not.toThrowError();
+  });
+
+  // 上锁，超时导致释放锁，锁转移
+  it('repeatedly lock', async () => {
+    const mutex = new SharedMutex();
+    await transferLock(mutex, 10);
+    expect(tryTransferLock(mutex)).toBeUndefined();
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(tryTransferLock(mutex)).not.toBeUndefined();
+  });
+});
+
+describe('transferSharedLock', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  // 正常上锁并且解锁
+  it('lock and unlock', async () => {
+    const mutex = new SharedMutex();
+    const unlockable = await transferSharedLock(mutex);
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    unlockable.unlock();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+  });
+
+  // 上锁，超时导致释放锁
+  it('lock and timeout', async () => {
+    const mutex = new SharedMutex();
+    await transferSharedLock(mutex, 10);
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+  });
+
+  // 超时后，重复解锁，不报错
+  it('timeout then unlock', async () => {
+    const mutex = new SharedMutex();
+    const unlockable = await transferSharedLock(mutex, 10);
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+    expect(() => {
+      unlockable.unlock();
+      unlockable.dispose();
+    }).not.toThrowError();
+  });
+
+  // 上锁，超时导致释放锁，锁转移
+  it('repeatedly lock', async () => {
+    const mutex = new SharedMutex();
+    await transferSharedLock(mutex, 10);
+    transferSharedLock(mutex, 20).then(() => {
+      // ...
+    });
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeFalsy();
+    vi.advanceTimersByTime(15);
+    await Promise.resolve();
+    expect(isMutexReleased(mutex)).toBeTruthy();
+  });
+});

package/src/lock/utils.ts

@@ -0,0 +1,135 @@
+import type { IDisposable } from '@/dispose';
+import { setDisposableTimeout } from '@/dispose';
+import type { SharedMutex } from './shared-mutex';
+
+export interface IUnlockable extends IDisposable {
+  unlock: () => void;
+}
+
+/**
+ * 转移独占锁
+ */
+export async function transferLock(mutex: SharedMutex, timeout?: number): Promise<IUnlockable> {
+  await mutex.lock();
+  let didUnlock = false;
+  let timerDisposable: IDisposable | undefined;
+
+  if (timeout !== undefined) {
+    timerDisposable = setDisposableTimeout(() => {
+      if (!didUnlock) {
+        mutex.unLock();
+        didUnlock = true;
+      }
+    }, timeout);
+  }
+
+  const unlock = () => {
+    timerDisposable?.dispose();
+    if (!didUnlock) {
+      mutex.unLock();
+      didUnlock = true;
+    }
+  };
+
+  return {
+    dispose: unlock,
+    unlock,
+  };
+}
+
+/**
+ * 尝试转移独占锁
+ */
+export function tryTransferLock(mutex: SharedMutex, timeout?: number): IUnlockable | undefined {
+  if (!mutex.tryLock()) {
+    return;
+  }
+  let didUnlock = false;
+  let timerDisposable: IDisposable | undefined;
+
+  if (timeout !== undefined) {
+    timerDisposable = setDisposableTimeout(() => {
+      if (!didUnlock) {
+        mutex.unLock();
+        didUnlock = true;
+      }
+    }, timeout);
+  }
+
+  const unlock = () => {
+    timerDisposable?.dispose();
+    if (!didUnlock) {
+      mutex.unLock();
+      didUnlock = true;
+    }
+  };
+
+  return {
+    dispose: unlock,
+    unlock,
+  };
+}
+
+/**
+ * 转移共享锁
+ */
+export async function transferSharedLock(mutex: SharedMutex, timeout?: number): Promise<IUnlockable> {
+  await mutex.lockShared();
+  let didUnlock = false;
+  let timerDisposable: IDisposable | undefined;
+
+  if (timeout !== undefined) {
+    timerDisposable = setDisposableTimeout(() => {
+      if (!didUnlock) {
+        mutex.unLockShared();
+        didUnlock = true;
+      }
+    }, timeout);
+  }
+
+  const unlock = () => {
+    timerDisposable?.dispose();
+    if (!didUnlock) {
+      mutex.unLockShared();
+      didUnlock = true;
+    }
+  };
+
+  return {
+    dispose: unlock,
+    unlock,
+  };
+}
+
+/**
+ * 尝试转移共享锁
+ */
+export function tryTransferSharedLock(mutex: SharedMutex, timeout?: number): IUnlockable | undefined {
+  if (!mutex.tryLockShared()) {
+    return;
+  }
+  let didUnlock = false;
+  let timerDisposable: IDisposable | undefined;
+
+  if (timeout !== undefined) {
+    timerDisposable = setDisposableTimeout(() => {
+      if (!didUnlock) {
+        mutex.unLockShared();
+        didUnlock = true;
+      }
+    }, timeout);
+  }
+
+  const unlock = () => {
+    timerDisposable?.dispose();
+    if (!didUnlock) {
+      mutex.unLockShared();
+      didUnlock = true;
+    }
+  };
+
+  return {
+    dispose: unlock,
+    unlock,
+  };
+}

package/src/lodash-es/index.ts

@@ -0,0 +1 @@
+export * from 'lodash-es';

package/src/math/degree.ts

@@ -0,0 +1,16 @@
+const DEG2RAD = Math.PI / 180;
+const RAD2DEG = 180 / Math.PI;
+
+/**
+ * 弧度转角度
+ */
+export function radToDeg(radians: number): number {
+  return radians * RAD2DEG;
+}
+
+/**
+ * 角度转弧度
+ */
+export function degToRad(degree: number): number {
+  return degree * DEG2RAD;
+}

package/src/math/index.ts

@@ -0,0 +1,7 @@
+export { toFixedDecimal } from './math';
+// 向量
+export { Vector } from './vector';
+// 弧度转角度
+export { radToDeg } from './degree';
+// 角度转弧度
+export { degToRad } from './degree';

package/src/math/math.test.ts

@@ -0,0 +1,40 @@
+import { toFixedDecimal } from './math';
+
+describe('Math', () => {
+  it('toFixedDecimal', () => {
+    expect(toFixedDecimal(0.6 * 3, 1)).toEqual(1.8);
+
+    // 整数没问题
+    expect(toFixedDecimal(1 * 3, 1)).toEqual(3);
+
+    // 负数没问题
+    expect(toFixedDecimal(-0.6 * 3, 1)).toEqual(-1.8);
+
+    expect(toFixedDecimal(1.44, 1)).toEqual(1.4);
+    expect(toFixedDecimal(1.45, 1)).toEqual(1.5);
+
+    // js直接计算2.333 * 9.452结果为22.051516000000003
+    expect(toFixedDecimal(2.333 * 9.452, 3)).toEqual(22.052);
+
+    // 外部用例
+    const arr = [
+      0.01, 0.0149, 0.015, 0.016, 0.017, 0.019, 0.026, 0.029, 0.02111, 0.078, 0.0711, 0.0701, 0.1, 0.11,
+      0.145, 0.149, 0.15, 0.151, 0.155, 0.159, 1.001, 1.004, 1.005, 1.006, 1.009, 1.105, 1.104, 1.109, 1.6,
+      1.0, 1.423, 1.531, 1.555, 1.504, 1.506, 1.669, 1.998, 998, 996, 910, 1, 12, 33, 151, 99999, 333.01232,
+      333.09139, 333.93153, 148.898342, 231.09002, 231.000002329, 21.98, 67.473, 33.234, 12.982, 12.238,
+      896.023, 99999.99999,
+    ];
+    const res = [
+      0.01, 0.01, 0.02, 0.02, 0.02, 0.02, 0.03, 0.03, 0.02, 0.08, 0.07, 0.07, 0.1, 0.11, 0.15, 0.15, 0.15,
+      0.15, 0.16, 0.16, 1, 1, 1.01, 1.01, 1.01, 1.11, 1.1, 1.11, 1.6, 1, 1.42, 1.53, 1.56, 1.5, 1.51, 1.67, 2,
+      998, 996, 910, 1, 12, 33, 151, 99999, 333.01, 333.09, 333.93, 148.9, 231.09, 231, 21.98, 67.47, 33.23,
+      12.98, 12.24, 896.02, 100000,
+    ];
+    for (let i = 0; i < arr.length; i++) {
+      expect(toFixedDecimal(arr[i], 2)).toEqual(res[i]);
+    }
+    for (let i = 0; i < arr.length; i++) {
+      expect(toFixedDecimal(-1 * arr[i], 2)).toEqual(-1 * res[i]);
+    }
+  });
+});

package/src/math/math.ts

@@ -0,0 +1,64 @@
+/**
+ * 安全的toFixed，不会出现小数精度的特殊情况
+ */
+function safeToFixed(value: string, precision = 0) {
+  let formattedValue = value;
+  if (!precision) {
+    precision = 0;
+  }
+  if (formattedValue.indexOf('.') === -1) {
+    formattedValue += '.';
+  }
+  formattedValue += '0'.repeat(precision + 1);
+
+  const regex = new RegExp(`^(-|\\+)?(\\d+(\\.\\d{0,${precision + 1}})?)\\d*$`);
+  if (!regex.test(formattedValue)) {
+    return value;
+  }
+  const match = regex.exec(formattedValue)!;
+  let integerPart = `0${match[2]}`;
+  const pm = match[1] ?? '';
+  const decimalPartLength = match[3].length;
+  let shouldRoundUp = true;
+
+  if (decimalPartLength === precision + 2) {
+    const decimalArray = integerPart.match(/\d/g)!;
+
+    if (parseInt(decimalArray[decimalArray.length - 1], 10) > 4) {
+      for (let i = decimalArray.length - 2; i >= 0; i--) {
+        const temp = parseInt(decimalArray[i], 10) + 1;
+
+        // eslint-disable-next-line max-depth
+        if (temp === 10) {
+          decimalArray[i] = '0';
+          shouldRoundUp = i !== 1;
+        } else {
+          decimalArray[i] = String(temp);
+          break;
+        }
+      }
+    }
+    integerPart = decimalArray.join('').replace(new RegExp(`(\\d+)(\\d{${precision}})\\d$`), '$1.$2');
+  }
+
+  if (shouldRoundUp) {
+    integerPart = integerPart.substring(1);
+  }
+
+  return (pm + integerPart).replace(/\.$/, '');
+}
+
+/**
+ * 将某个double转为指定精度小数位
+ *
+ * 注意：
+ * 0.6 * 3 = 1.7999999999999998
+ * toFixedDecimal(0.6 * 3, 1) = 1.8
+ * 没有使用系统默认的toFixed()，会有精度问题
+ *
+ * @param value 原始double类型值
+ * @param precision 期望小数的精度
+ */
+export function toFixedDecimal(value: number, precision: number): number {
+  return Number(safeToFixed(String(value), precision));
+}

package/src/math/node_modules/.vitest/results.json

@@ -0,0 +1 @@
+{"version":"1.0.1","results":[[":math.test.ts",{"duration":4,"failed":false}],[":vector.test.ts",{"duration":0,"failed":false}]]}