@zk-tech/bedrock 0.0.1

package/src/structure/min-heap.test.ts

@@ -0,0 +1,71 @@
+import { MinHeap } from './min-heap';
+
+describe('MinHeap', () => {
+  let heap: MinHeap<number>;
+
+  beforeEach(() => {
+    heap = new MinHeap();
+  });
+
+  test('insert adds a value and sifts it up the heap', () => {
+    heap.insert(2);
+    expect(heap.peek()).toEqual(2);
+
+    heap.insert(3);
+    expect(heap.peek()).toEqual(2);
+
+    heap.insert(1);
+    expect(heap.peek()).toEqual(1);
+  });
+
+  test('peek returns the minimum value without removing it', () => {
+    expect(heap.peek()).toBeNull();
+
+    heap.insert(1);
+    expect(heap.peek()).toEqual(1);
+
+    heap.insert(0);
+    expect(heap.peek()).toEqual(0);
+
+    heap.remove();
+    expect(heap.peek()).toEqual(1);
+  });
+
+  test('remove extracts the minimum value and returns it', () => {
+    expect(heap.remove()).toBeNull();
+
+    heap.insert(2);
+    heap.insert(3);
+    heap.insert(1);
+
+    expect(heap.remove()).toBe(1);
+    expect(heap.remove()).toBe(2);
+    expect(heap.remove()).toBe(3);
+    expect(heap.remove()).toBeNull();
+  });
+
+  test('size returns the number of elements in the heap', () => {
+    expect(heap.size()).toBe(0);
+
+    heap.insert(2);
+    heap.insert(3);
+    expect(heap.size()).toBe(2);
+
+    heap.remove();
+    expect(heap.size()).toBe(1);
+  });
+
+  test('heap maintains the heap property on inserts and removes', () => {
+    heap.insert(3);
+    heap.insert(4);
+    heap.insert(5);
+    heap.insert(1);
+    heap.insert(2);
+
+    expect(heap.remove()).toEqual(1);
+    expect(heap.remove()).toEqual(2);
+    expect(heap.remove()).toEqual(3);
+    expect(heap.remove()).toEqual(4);
+    expect(heap.remove()).toEqual(5);
+  });
+});

package/src/structure/min-heap.ts

@@ -0,0 +1,91 @@
+export class MinHeap<T> {
+  private readonly _heap: T[] = [];
+  private readonly _compare: (a: T, b: T) => number;
+
+  constructor(compareFunction?: (a: T, b: T) => number) {
+    if (compareFunction) {
+      this._compare = compareFunction;
+    } else {
+      this._compare = (a, b) => {
+        if (a < b) return -1;
+        if (a > b) return 1;
+        return 0;
+      };
+    }
+  }
+
+  public insert(value: T): void {
+    this._heap.push(value);
+    this._siftUp();
+  }
+
+  public peek(): T | null {
+    return this._heap.length > 0 ? this._heap[0] : null;
+  }
+
+  public remove(): T | null {
+    if (this._heap.length === 0) return null;
+    if (this._heap.length === 1) return this._heap.pop()!;
+
+    const item = this._heap[0];
+    this._heap[0] = this._heap.pop()!;
+    this._siftDown();
+    return item;
+  }
+
+  public size(): number {
+    return this._heap.length;
+  }
+
+  public clear(): void {
+    this._heap.length = 0;
+  }
+
+  private _getLeftChildIndex(parentIndex: number): number {
+    return 2 * parentIndex + 1;
+  }
+
+  private _getRightChildIndex(parentIndex: number): number {
+    return 2 * parentIndex + 2;
+  }
+
+  private _getParentIndex(childIndex: number): number {
+    return Math.floor((childIndex - 1) / 2);
+  }
+
+  private _swap(indexOne: number, indexTwo: number): void {
+    [this._heap[indexOne], this._heap[indexTwo]] = [this._heap[indexTwo], this._heap[indexOne]];
+  }
+
+  private _siftUp(): void {
+    let index = this._heap.length - 1;
+    while (index > 0 && this._compare(this._heap[this._getParentIndex(index)], this._heap[index]) > 0) {
+      const parentIndex = this._getParentIndex(index);
+      this._swap(index, parentIndex);
+      index = parentIndex;
+    }
+  }
+
+  private _siftDown(): void {
+    let index = 0;
+    let smallerChildIndex = this._getLeftChildIndex(index);
+
+    while (smallerChildIndex < this._heap.length) {
+      const rightChildIndex = this._getRightChildIndex(index);
+      if (
+        rightChildIndex < this._heap.length &&
+        this._compare(this._heap[rightChildIndex], this._heap[smallerChildIndex]) < 0
+      ) {
+        smallerChildIndex = rightChildIndex;
+      }
+
+      if (this._compare(this._heap[index], this._heap[smallerChildIndex]) <= 0) {
+        break;
+      }
+
+      this._swap(index, smallerChildIndex);
+      index = smallerChildIndex;
+      smallerChildIndex = this._getLeftChildIndex(index);
+    }
+  }
+}

package/src/type/REAME.md

@@ -0,0 +1,2 @@
+# Typescript typing
+定义项目内用到的 typescript 高级类型

package/src/type/distributive-omit.interface.ts

@@ -0,0 +1,4 @@
+// Typescript 提供的 Omit 函数会导致联合结构丢失，额外包装实现
+// https://stackoverflow.com/questions/57103834/typescript-omit-a-property-from-all-interfaces-in-a-union-but-keep-the-union-s/57103940#57103940
+
+export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;

package/src/type/index.ts

@@ -0,0 +1,3 @@
+export type { DistributiveOmit } from './distributive-omit.interface';
+
+export type { ObjectKeyPaths, ValueAtPath } from './object-key-paths.interface';

package/src/type/object-key-paths.interface.ts

@@ -0,0 +1,40 @@
+/**
+ * 提取对象的 key 用 . 拼接成 path 形式
+ * type T1 = ObjectKeyPaths<{ name: string; age: number }>; // expected to be 'name' | 'age'
+ * type T2 = ObjectKeyPaths<{
+ *    refCount: number;
+ *    person: { name: string; age: number };
+ *  }>; // expected to be 'refCount' | 'person' | 'person.name' | 'person.age'
+ */
+
+type GenNode<K extends string | number, IsRoot extends boolean> = IsRoot extends true
+  ? `${K}`
+  : `.${K}` | (K extends number ? `[${K}]` : never);
+
+export type ObjectKeyPaths<
+  T extends Record<string, unknown>,
+  IsRoot extends boolean = true,
+  K extends keyof T = keyof T,
+> = K extends string | number
+  ?
+      | GenNode<K, IsRoot>
+      | (T[K] extends Record<string, unknown> ? `${GenNode<K, IsRoot>}${ObjectKeyPaths<T[K], false>}` : never)
+  : never;
+
+/**
+ * 获取对象 path 对应的类型
+ * type T = ValueAtPath<{ a: { b: number } }, 'a.b'>; // expected to be number
+ */
+export type ValueAtPath<
+  T extends Record<string, unknown>, // 泛型类型参数 T 表示对象类型
+  P extends ObjectKeyPaths<T>, // 泛型类型参数 P 表示路径字符串，必须是 T 可能存在的所有路径之一
+> = P extends `${infer K}.${infer R}` // 如果 P 包含 "." 分隔符，则将其拆分成两部分 K 和 R
+  ? K extends keyof T // 如果 K 是 T 的属性之一
+    ? T[K] extends Record<string, unknown>
+      ? // @ts-ignore
+        ValueAtPath<T[K], R> // 递归地获取 T[K] 对应的子对象中的 R 路径属性的值
+      : never // 否则返回 never 类型（表示不存在）
+    : never
+  : P extends keyof T // 如果 P 不包含 "." 分隔符，并且是 T 的属性之一
+    ? T[P] // 直接返回 T 中对应属性的值
+    : never; // 否则返回 never 类型（表示不存在）

package/src/undo-redo-stack/README.md

@@ -0,0 +1,61 @@
+# UndoRedo栈
+提供了基础的undoredo栈规范，具体业务方可以直接使用或者继承使用。  
+
+## StateUndoRedoStack
+state形式undoredo栈的实现，类似Redux这种形式，使用方只需要消费当前的state。  
+```
+// 用法举例
+const stack = new StateUndoRedoStack<T>(initialState);
+
+stack.onDidRedo((state) => {
+  UI.reset(state);
+});
+stack.onDidUndo((state) => {
+  UI.reset(state);
+});
+
+```
+
+特点：
+- 每次只会有一个state变更，不会undo的时候，连续触发两个state行为。  
+- 不建议继承并重写方法，因为这种模式的undoRedoStack，本身就是简单场景使用。  
+
+## ActionUndoRedoStack
+action形式undoredo栈的实现，相比较state形式会复杂一些，业务方需要明确action存在undo和redo两种行为。
+
+### ActionStackElement
+action形式栈中的元素，需要使用方满足接口。  
+需要提供`undo`方法和`redo`方法即可。  
+下面是一个简单的`IActionStackElement`实现举例：  
+```
+class CommandElement<T> implement IUndoRedoElement {
+  private _currentCommand: T;
+  private _invertCommand: T;
+
+  undo() {
+    this._invertCommand.execute();
+    this._reverse();
+  }
+
+  redo() {
+    this._invertCommand.execute();
+    this._reverse();
+  }
+
+  private _reverse() {
+    swap(this._currentCommand, this._invertCommand);
+  }
+}
+```
+
+特点：  
+- 禁止继承时重写`undo`，`redo`，`pushElement`这三个方法，因为重写的话会影响生命周期行为。  
+- 提供默认的容量能力控制，可以重写`isOverflow`方法来业务精细化判断容量大小。
+- **可以复写`popPastElements`和`popFutureElements`来实现定制化的出栈逻辑。**
+
+
+## 其他
+- 如果需要其他生命周期，请联系基建侧同学。  
+- ActionUndoRedoStack中每一次undo、redo执行的粒度是数组，是因为业务场景中可能有联动出栈的情况。  
+- **如果本身是state场景，但是有一些复杂的逻辑，可以使用Action形式栈模拟。**  
+- Past、Future命名参考于vscode和redux。  

package/src/undo-redo-stack/action-stack.test.ts

@@ -0,0 +1,330 @@
+import type { IActionStackElement } from './element';
+import { BaseActionUndoRedoStack } from './action-stack';
+
+class Data implements IActionStackElement {
+  constructor(
+    private readonly _undo: () => void,
+    private readonly _redo: () => void,
+  ) {}
+
+  undo() {
+    this._undo();
+  }
+
+  redo() {
+    this._redo();
+  }
+}
+
+describe('BaseActionUndoRedoStack', () => {
+  // 默认情况不能undo
+  it('canUndo1', () => {
+    const stack = new BaseActionUndoRedoStack();
+    expect(stack.canUndo()).toBeFalsy();
+  });
+
+  // 有了数据，可以undo
+  it('canUndo2', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const elem = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem);
+    expect(stack.canUndo()).toBeTruthy();
+  });
+
+  // 有数据，但是被undo过了
+  it('canUndo3', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const elem = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem);
+    stack.undo();
+    expect(stack.canUndo()).toBeFalsy();
+  });
+
+  // 默认情况不能redo
+  it('canRedo1', () => {
+    const stack = new BaseActionUndoRedoStack();
+    expect(stack.canRedo()).toBeFalsy();
+  });
+
+  // 添加了数据，还是不能redo
+  it('canRedo2', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const elem = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem);
+    expect(stack.canRedo()).toBeFalsy();
+  });
+
+  // undo过了，可以redo
+  it('canRedo3', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const elem = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem);
+    stack.undo();
+    expect(stack.canRedo()).toBeTruthy();
+  });
+
+  // 本来可以redo，但是添加了新数据
+  it('canRedo4', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const elem = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem);
+    stack.undo();
+    expect(stack.canRedo()).toBeTruthy();
+    stack.pushElement(elem);
+    expect(stack.canRedo()).toBeFalsy();
+  });
+
+  it('pushElements', () => {
+    const stack = new BaseActionUndoRedoStack(2);
+    const fn = vi.fn();
+    stack.onStackChange(fn);
+    const elem1 = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem1);
+    expect(fn).toBeCalledTimes(1);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'].length).toBe(1);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_future'].length).toBe(0);
+
+    const elem2 = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem2);
+    expect(fn).toBeCalledTimes(2);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'].length).toBe(2);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_future'].length).toBe(0);
+
+    stack.undo();
+    expect(fn).toBeCalledTimes(3);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'].length).toBe(1);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_future'].length).toBe(1);
+
+    const elem3 = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem3);
+    expect(fn).toBeCalledTimes(4);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'].length).toBe(2);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_future'].length).toBe(0);
+
+    const elem4 = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem4);
+    expect(fn).toBeCalledTimes(5);
+    // 命中了最大限制，长度还是2个
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'].length).toBe(2);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'][1]).toBe(elem4);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'][0]).toBe(elem3);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_future'].length).toBe(0);
+  });
+
+  // 没有数据时候undo
+  it('undo1', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const fn = vi.fn();
+    stack.onDidUndo(fn);
+    stack.undo();
+    expect(fn).toBeCalledTimes(0);
+  });
+
+  // 有数据时候undo
+  it('undo2', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const fn = vi.fn();
+    stack.onDidUndo(fn);
+    const undoFn = vi.fn();
+    const redoFn = vi.fn();
+    const elem = new Data(undoFn, redoFn);
+    stack.pushElement(elem);
+    stack.undo();
+    expect(fn).toBeCalledTimes(1);
+    expect(undoFn).toBeCalledTimes(1);
+    expect(redoFn).toBeCalledTimes(0);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'].length).toBe(0);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_future'].length).toBe(1);
+  });
+
+  // 没有数据时候redo
+  it('redo1', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const fn = vi.fn();
+    stack.onDidUndo(fn);
+    stack.redo();
+    expect(fn).toBeCalledTimes(0);
+  });
+
+  // 有数据时候redo
+  it('redo2', () => {
+    const stack = new BaseActionUndoRedoStack();
+    const fn = vi.fn();
+    stack.onDidRedo(fn);
+    const undoFn = vi.fn();
+    const redoFn = vi.fn();
+    const elem = new Data(undoFn, redoFn);
+    stack.pushElement(elem);
+    stack.undo();
+    expect(fn).toBeCalledTimes(0);
+    expect(undoFn).toBeCalledTimes(1);
+    expect(redoFn).toBeCalledTimes(0);
+
+    stack.redo();
+    expect(fn).toBeCalledTimes(1);
+    expect(undoFn).toBeCalledTimes(1);
+    expect(redoFn).toBeCalledTimes(1);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_past'].length).toBe(1);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_future'].length).toBe(0);
+  });
+
+  it('clear', () => {
+    const fn = vi.fn();
+    const stack = new BaseActionUndoRedoStack();
+    stack.onStackChange(fn);
+
+    const undoFn = vi.fn();
+    const redoFn = vi.fn();
+    const elem = new Data(undoFn, redoFn);
+
+    // 本身没有元素，所以没有抛出事件
+    stack.clearRedo();
+    stack.clearUndo();
+    stack.reset();
+    expect(fn).toBeCalledTimes(0);
+
+    // 有undo元素，但是清除
+    stack.pushElement(elem);
+    fn.mockReset();
+    expect(stack.canUndo()).toBeTruthy();
+    stack.clearUndo();
+    expect(fn).toBeCalledTimes(1);
+    expect(stack.canUndo()).toBeFalsy();
+
+    // 有redo元素，但是清除
+    stack.pushElement(elem);
+    stack.pushElement(elem);
+    stack.pushElement(elem);
+    stack.undo();
+    fn.mockReset();
+    expect(stack.canRedo()).toBeTruthy();
+    stack.clearRedo();
+    expect(fn).toBeCalledTimes(1);
+    expect(stack.canRedo()).toBeFalsy();
+
+    stack.undo();
+    expect(stack.canUndo()).toBeTruthy();
+    expect(stack.canRedo()).toBeTruthy();
+    fn.mockReset();
+    stack.reset();
+    expect(fn).toBeCalledTimes(1);
+    expect(stack.canUndo()).toBeFalsy();
+    expect(stack.canRedo()).toBeFalsy();
+  });
+});
+
+describe('DerivedUndoRedoStack', () => {
+  // 整一个奇怪的undoredostack，主要是测试复写基类方法
+  class UntrustedUndoRedoStack extends BaseActionUndoRedoStack<IActionStackElement> {
+    canUndo() {
+      return true;
+    }
+
+    canRedo() {
+      return true;
+    }
+
+    protected _popPastElements(): IActionStackElement[] {
+      const elems = [...this._past];
+      this._past.length = 0;
+      return elems;
+    }
+
+    protected _popFutureElements(): IActionStackElement[] {
+      const elems = [...this._future];
+      this._future.length = 0;
+      return elems;
+    }
+
+    protected _isOverflow(_elem: IActionStackElement) {
+      if (this._future.length > 0) {
+        return true;
+      }
+      return false;
+    }
+  }
+
+  // 虽然canUndo永远是true，但是undo没有真的触发，所以不会抛出事件
+  it('undo1', () => {
+    const stack = new UntrustedUndoRedoStack();
+    const fn = vi.fn();
+    stack.onDidUndo(fn);
+    stack.undo();
+    expect(fn).toBeCalledTimes(0);
+  });
+
+  // 验证_popPastElements重写成功
+  it('undo2', () => {
+    const stack = new UntrustedUndoRedoStack();
+    const fn = vi.fn();
+    stack.onDidUndo(fn);
+    const undoFn = vi.fn();
+    const redoFn = vi.fn();
+    const elem = new Data(undoFn, redoFn);
+    // 添加了三次
+    stack.pushElement(elem);
+    stack.pushElement(elem);
+    stack.pushElement(elem);
+    stack.undo();
+    expect(fn).toBeCalledTimes(1);
+    expect(undoFn).toBeCalledTimes(3);
+    expect(redoFn).toBeCalledTimes(0);
+  });
+
+  // 虽然canRedo永远是true，但是redo没有真的触发，所以不会抛出事件
+  it('redo1', () => {
+    const stack = new UntrustedUndoRedoStack();
+    const fn = vi.fn();
+    stack.onDidRedo(fn);
+    stack.redo();
+    expect(fn).toBeCalledTimes(0);
+  });
+
+  // 验证_popFutureElements重写成功
+  it('redo2', () => {
+    const stack = new UntrustedUndoRedoStack();
+    const fn = vi.fn();
+    stack.onDidRedo(fn);
+    const undoFn = vi.fn();
+    const redoFn = vi.fn();
+    const elem = new Data(undoFn, redoFn);
+    // 添加了三次
+    stack.pushElement(elem);
+    stack.pushElement(elem);
+    stack.pushElement(elem);
+    stack.undo();
+    stack.redo();
+    expect(fn).toBeCalledTimes(1);
+    expect(undoFn).toBeCalledTimes(3);
+    expect(redoFn).toBeCalledTimes(3);
+  });
+
+  // 验证_isOverflow重写成功
+  it('isOverflow', () => {
+    const stack = new UntrustedUndoRedoStack(1);
+    const elem = new Data(vi.fn(), vi.fn());
+    stack.pushElement(elem);
+    stack.pushElement(elem);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_isOverflow'](elem)).toBeFalsy();
+    stack.undo();
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(stack['_isOverflow'](elem)).toBeTruthy();
+  });
+});