@zk-tech/bedrock 0.0.1

package/src/dispose/disposable-t.test.ts

@@ -0,0 +1,123 @@
+import { makeSafeDisposable, makeTransferDisposable } from './disposable-utils';
+import {
+  Disposable,
+  MutableDisposable,
+  RefCountedDisposable,
+  SafeDisposable,
+  TransferDisposable,
+} from './disposable-t';
+import type { IDisposable } from './dispose-base';
+
+class Bar extends Disposable {
+  constructor(mockFunc: () => void) {
+    super();
+    this._register(makeSafeDisposable(mockFunc));
+  }
+}
+
+class Foo extends Disposable {
+  constructor(mockFunc: () => void) {
+    super();
+    this._register(makeSafeDisposable(mockFunc));
+  }
+}
+
+class Test extends Disposable {
+  constructor(value: IDisposable) {
+    super();
+    this._register(value);
+  }
+}
+
+describe('mutable disposable', () => {
+  it('set value', () => {
+    const barMock = vi.fn();
+    const fooMock = vi.fn();
+    const mutable = new MutableDisposable();
+    mutable.value = new Bar(barMock);
+    mutable.value = new Foo(barMock);
+    expect(barMock).toHaveBeenCalled();
+    expect(fooMock).not.toHaveBeenCalled();
+  });
+
+  it('clear', () => {
+    const barMock = vi.fn();
+    const mutable = new MutableDisposable(new Bar(barMock));
+    mutable.clear();
+    expect(barMock).toHaveBeenCalled();
+  });
+
+  it('release', () => {
+    const barMock = vi.fn();
+    const fooMock = vi.fn();
+    const mutable = new MutableDisposable();
+    mutable.value = new Bar(barMock);
+    mutable.release();
+    mutable.value = new Foo(barMock);
+    // 因为调用的是release，所以没有触发dispose
+    expect(barMock).not.toHaveBeenCalled();
+    expect(fooMock).not.toHaveBeenCalled();
+  });
+
+  it('dispose', () => {
+    const barMock = vi.fn();
+    const mutable = new MutableDisposable();
+    mutable.value = new Bar(barMock);
+    mutable.dispose();
+    expect(barMock).toHaveBeenCalled();
+  });
+});
+
+describe('safe disposable', () => {
+  it('dispose', () => {
+    const barMock = vi.fn();
+    const safe = new SafeDisposable(new Bar(barMock));
+    safe.dispose();
+    safe.dispose();
+    expect(barMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('RefCountedDisposable', () => {
+  it('test', () => {
+    const fnMock = vi.fn();
+    const disposable = makeSafeDisposable(fnMock);
+    const refCounted = new RefCountedDisposable(new Test(disposable));
+    refCounted.acquire();
+
+    refCounted.release();
+    expect(fnMock).toHaveBeenCalledTimes(0);
+    refCounted.dispose();
+    expect(fnMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('TransferDisposable', () => {
+  class FooInternal implements IDisposable {
+    public count = 0;
+
+    dispose() {
+      this.count++;
+    }
+  }
+
+  class BarInternal implements IDisposable {
+    private readonly _foo: FooInternal;
+
+    constructor(foo: TransferDisposable<FooInternal>) {
+      this._foo = foo.release();
+    }
+
+    dispose() {
+      this._foo.dispose();
+    }
+  }
+
+  it('transfer', () => {
+    const foo = new FooInternal();
+    const bar = new BarInternal(makeTransferDisposable(foo));
+
+    bar.dispose();
+    expect(foo.count).toBe(1);
+  });
+});

package/src/dispose/disposable-t.ts

@@ -0,0 +1,238 @@
+import { Logger } from '@/_internal/logger';
+import { lvAssertNotNil } from '@/assert';
+import { DisposableStore } from './disposable-store';
+import type { IDisposable } from './dispose-base';
+import { BRANCH_DISPOSE } from './logger';
+import { MARK_AS_DISPOSED, SET_PARENT_OF_DISPOSABLE, TRACK_DISPOSABLE } from './tracker';
+
+//
+// Disposable基类
+//
+// 自动添加DisposableStore，提供默认的dispose和register方法
+//
+export abstract class Disposable implements IDisposable {
+  protected readonly _store = new DisposableStore();
+
+  constructor() {
+    TRACK_DISPOSABLE(this);
+    SET_PARENT_OF_DISPOSABLE(this._store, this);
+  }
+
+  // 销毁该节点和所有的子节点
+  dispose(): void {
+    MARK_AS_DISPOSED(this);
+    BRANCH_DISPOSE(this.constructor.name, this._store.constructor.name);
+
+    this._store.dispose();
+  }
+
+  // 挂载子节点
+  protected _register<T extends IDisposable>(o: T): T {
+    if ((o as unknown as Disposable) === this) {
+      throw new Error('Cannot register a disposable on itself!');
+    }
+    return this._store.add(o);
+  }
+}
+
+/**
+ * 容器类
+ * 提供一个容器，容器内部的IDisposable对象可以切换更新，每次更新的时候，旧的IDisposable对象会自动进行dispose
+ *
+ * 使用方式:
+ * class Foo {
+ *   private readonly _barRef: MutableDisposable;
+ *
+ *   toggle() {
+ *     this._barRef.setValue(new Bar());
+ *   }
+ *
+ *   doSomething() {
+ *     this._barRef.value.xxx();
+ *   }
+ * }
+ */
+export class MutableDisposable<T extends IDisposable> implements IDisposable {
+  private _value?: T;
+  private _isDisposed = false;
+
+  constructor(value?: T) {
+    TRACK_DISPOSABLE(this);
+    this.value = value;
+  }
+
+  get value(): T | undefined {
+    return this._isDisposed ? undefined : this._value;
+  }
+
+  set value(value: T | undefined) {
+    if (this._isDisposed || value === this._value) {
+      return;
+    }
+
+    this._value?.dispose();
+    if (value) {
+      SET_PARENT_OF_DISPOSABLE(value, this);
+    }
+    this._value = value;
+  }
+
+  clear(): void {
+    this.value = undefined;
+  }
+
+  dispose(): void {
+    this._isDisposed = true;
+    MARK_AS_DISPOSED(this);
+    this._value?.dispose();
+    this._value = undefined;
+  }
+
+  release(): T | undefined {
+    const oldValue = this._value;
+    this._value = undefined;
+    if (oldValue) {
+      SET_PARENT_OF_DISPOSABLE(oldValue, null);
+    }
+    return oldValue;
+  }
+}
+
+/**
+ * 容器类
+ * 通过该容器进行dispose试，可以保证内部的IDisposable一会进行一次dispose
+ * 本质是一种防御性质的处理，如果需要使用时，最好有明确的理由
+ */
+export class SafeDisposable<T extends IDisposable> implements IDisposable {
+  private _value?: T;
+
+  constructor(value: T) {
+    this._value = value;
+    TRACK_DISPOSABLE(this);
+  }
+
+  get value(): T | undefined {
+    return this._value;
+  }
+
+  isEmpty() {
+    return this._value === undefined;
+  }
+
+  dispose() {
+    if (!this._value) {
+      return;
+    }
+    this._value.dispose();
+    this._value = undefined;
+    MARK_AS_DISPOSED(this);
+  }
+}
+
+/**
+ * 容器类
+ * 引用计数容器，当引用为0时自动执行dispose
+ * 注意：初始计数为1，默认构造的地方自动获得引用，如果在栈上构造，记得最后调用release
+ *
+ * 使用实例:
+ * class Foo {
+ *   private _bar: RefCountedDisposable = new RefCountedDisposable(new Bar());
+ *
+ *   getBar() {
+ *     this._bar.acquire();
+ *     return this._bar;
+ *   }
+ * }
+ *
+ * // 如果在栈上构造
+ * const bar = new RefCountedDisposable(new Bar());
+ * makeFoo(bar);
+ * makeFoo(bar);
+ * bar.release();
+ */
+export class RefCountedDisposable<T extends IDisposable> implements IDisposable {
+  private _counter: number = 1;
+  private _value?: T;
+
+  constructor(value: T) {
+    this._value = value;
+    TRACK_DISPOSABLE(this);
+  }
+
+  get value(): T | undefined {
+    return this._value;
+  }
+
+  acquire() {
+    if (!this._value) {
+      return this;
+    }
+    this._counter++;
+    return this;
+  }
+
+  release() {
+    if (--this._counter === 0) {
+      this._value!.dispose();
+      this._value = undefined;
+      MARK_AS_DISPOSED(this);
+    }
+    return this;
+  }
+
+  dispose() {
+    this.release();
+  }
+}
+
+/**
+ * 容器类，表示了一个T生命周期的转移
+ *
+ * 由于js引用传递的特性，正常情况下，我们默认为传递过来的对象不具备dispose权利
+ * class Foo extends Disposable {
+ *   private readonly _bar = new Bar();
+ *
+ *   constructor(
+ *     thirdparty: Thirdparty,
+ *   ) {
+ *     this._register(this._bar);  // class内部构造的，具备dispose权利
+ *     this._register(thirdparty);  // ❌，很少会直接这么写，除非能很确定存在生命周期转移
+ *   }
+ *
+ *   constructor(
+ *     thirdparty: TransferDisposable<Thirdparty>,  // ✅，明确表示了我依赖了Thirdparty，但是该对象生命周期要归我所有
+ *   ) {
+ *     this._register(this._bar);
+ *     this._register(thirdparty.release());  // ✅，可以直接register
+ *   }
+ * }
+ *
+ * 注意：
+ * 不同于C++中的unique_ptr，该class只作用于转移场景。
+ * 所以class理论上只在栈上出现，不应该在堆上存在。
+ * 如果出现了需要在堆上存储的场景，可以联系架构侧
+ */
+export class TransferDisposable<T extends IDisposable> extends Disposable {
+  private _val?: T;
+
+  constructor(val: T) {
+    super();
+
+    this._val = val;
+  }
+
+  release() {
+    // 只能release一次
+    lvAssertNotNil(this._val);
+    const v = this._val;
+    this._val = undefined;
+    return v;
+  }
+
+  dispose(): void {
+    // 虽然它有dispose，但是不应该被执行，应该直接被gc才对
+    Logger.warn(new Error('TransferDisposable call dispose.'));
+    this._val?.dispose();
+    super.dispose();
+  }
+}

package/src/dispose/disposable-utils.test.ts

@@ -0,0 +1,15 @@
+import { makeSafeDisposable } from './disposable-utils';
+
+describe('dispose store', () => {
+  it('tracker success', () => {
+    const mock = vi.fn();
+    const safeDisposable = makeSafeDisposable(mock);
+    // 正常dispose
+    safeDisposable.dispose();
+    expect(mock).toHaveBeenCalled();
+
+    // 只会真正dispose一次
+    safeDisposable.dispose();
+    expect(mock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/dispose/disposable-utils.ts

@@ -0,0 +1,28 @@
+import { SafeDisposable, TransferDisposable } from './disposable-t';
+import { EmptyDispose, type IDisposable } from './dispose-base';
+import { MARK_AS_LEAKED } from './tracker';
+
+export function makeSafeDisposable(fn: (...args: any) => any) {
+  const disposable = new SafeDisposable({
+    dispose: fn,
+  });
+  return disposable;
+}
+
+export function makeEmptyDisposable() {
+  return EmptyDispose;
+}
+
+// 忽略dispose
+export function ignoreDispose(x: IDisposable) {
+  MARK_AS_LEAKED(x);
+}
+
+// 判断一个thing是否是disposable
+export function isDisposable<E = any>(thing: E): thing is E & IDisposable {
+  return typeof (thing as IDisposable).dispose === 'function' && (thing as IDisposable).dispose.length === 0;
+}
+
+export function makeTransferDisposable<T extends IDisposable>(val: T) {
+  return new TransferDisposable(val);
+}

package/src/dispose/dispose-base.ts

@@ -0,0 +1,9 @@
+//
+// Disposable特征约束
+//
+export interface IDisposable {
+  dispose: () => void;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export const EmptyDispose = Object.freeze<IDisposable>({ dispose() {} });

package/src/dispose/index.ts

@@ -0,0 +1,34 @@
+// dispose核心接口
+export type { IDisposable } from './dispose-base';
+
+// 记录持有关系的核心数据结构
+export { DisposableStore } from './disposable-store';
+
+// dispose常用类型
+// 可以作为IDisposable的基类，自带disposableStore
+export { Disposable } from './disposable-t';
+
+// 容器类，允许替换内部的IDisposable，每次替换时，旧value自动dispose
+export { MutableDisposable } from './disposable-t';
+
+// 容器类，内部IDisposable对象最多只执行一次dispose
+export { SafeDisposable } from './disposable-t';
+export { makeSafeDisposable } from './disposable-utils';
+
+// 容器类，表示一个IDisposable的转移
+export { TransferDisposable } from './disposable-t';
+export { makeTransferDisposable } from './disposable-utils';
+
+// 辅助常量，空的IDisposable对象
+export { EmptyDispose } from './dispose-base';
+
+// 辅助函数，判断是否是disposable对象
+export { isDisposable } from './disposable-utils';
+
+// 辅助函数，定时器disposable化
+export { setDisposableTimeout } from './timer';
+export { setDisposableInterval } from './timer';
+
+// 开发阶段辅助函数，忽略disposable泄漏检测
+export { ignoreDispose } from './disposable-utils';
+export { enableTrack, disableTrack, SET_PARENT_OF_DISPOSABLE } from './tracker';

package/src/dispose/logger.test.ts

@@ -0,0 +1,65 @@
+import { Disposable } from './disposable-t';
+import { makeSafeDisposable } from './disposable-utils';
+import { disposeWithLog } from './logger';
+import type { IDisposableLogger } from './logger';
+
+class Bar extends Disposable {
+  constructor() {
+    super();
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    this._register(makeSafeDisposable(() => {}));
+  }
+}
+
+class Foo extends Disposable {
+  constructor(mockFunc: () => void) {
+    super();
+    this._register(new Bar());
+    this._register(makeSafeDisposable(mockFunc));
+  }
+}
+
+describe('dispose store', () => {
+  it('log success', () => {
+    /* eslint-disable no-console */
+    console.log = vi.fn();
+    const mockDispose = vi.fn();
+    const foo1 = new Foo(mockDispose);
+    // 默认log
+    disposeWithLog(foo1);
+    /* eslint-disable no-console */
+    expect(console.log).toHaveBeenCalledTimes(1);
+    /* eslint-disable no-console */
+    expect(console.log).toHaveBeenLastCalledWith([
+      ['Foo', 'DisposableStore'],
+      ['DisposableStore', 'Bar'],
+      ['DisposableStore', 'SafeDisposable'],
+      ['Bar', 'DisposableStore'],
+      ['DisposableStore', 'SafeDisposable'],
+    ]);
+
+    // 自定义log
+    const foo2 = new Foo(mockDispose);
+    const branchMock = vi.fn();
+    const endMock = vi.fn();
+    disposeWithLog(
+      foo2,
+      new (class implements IDisposableLogger {
+        branch(from: string, to: string) {
+          branchMock(from, to);
+        }
+
+        end() {
+          endMock();
+        }
+      })(),
+    );
+    expect(branchMock).toHaveBeenCalledTimes(5);
+    expect(branchMock).toHaveBeenNthCalledWith(1, 'Foo', 'DisposableStore');
+    expect(branchMock).toHaveBeenNthCalledWith(2, 'DisposableStore', 'Bar');
+    expect(branchMock).toHaveBeenNthCalledWith(3, 'DisposableStore', 'SafeDisposable');
+    expect(branchMock).toHaveBeenNthCalledWith(4, 'Bar', 'DisposableStore');
+    expect(branchMock).toHaveBeenNthCalledWith(5, 'DisposableStore', 'SafeDisposable');
+    expect(endMock).toHaveBeenCalled();
+  });
+});

package/src/dispose/logger.ts

@@ -0,0 +1,39 @@
+import { Logger } from '@/_internal/logger';
+import type { IDisposable } from './dispose-base';
+
+let disposableLogger: IDisposableLogger | null = null;
+
+export interface IDisposableLogger {
+  branch: (from: string, to: string) => void;
+  end: () => void;
+}
+
+function setDisposableLogger(logger: IDisposableLogger | null): void {
+  disposableLogger = logger;
+}
+
+function makeDefaultLogger() {
+  return new (class implements IDisposableLogger {
+    private readonly _dep: [string, string][] = [];
+
+    branch(from: string, to: string): void {
+      this._dep.push([from, to]);
+    }
+
+    end(): void {
+      Logger.log(this._dep);
+    }
+  })();
+}
+
+// 辅助能力 dispose触发时记录
+export function BRANCH_DISPOSE(from: string, to: string) {
+  disposableLogger?.branch(from, to);
+}
+
+export function disposeWithLog<T extends IDisposable>(x: T, logger: IDisposableLogger = makeDefaultLogger()) {
+  setDisposableLogger(logger);
+  x.dispose();
+  logger.end();
+  setDisposableLogger(null);
+}

package/src/dispose/timer.test.ts

@@ -0,0 +1,30 @@
+import { setDisposableTimeout, setDisposableInterval } from './timer';
+
+describe('Timeout', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  it('setDisposableTimeout', () => {
+    let a = 0;
+    const disposable = setDisposableTimeout(() => {
+      a++;
+    }, 10);
+    vi.advanceTimersByTime(6);
+    disposable.dispose();
+    vi.advanceTimersByTime(10);
+    expect(a).toBe(0);
+  });
+
+  it('setDisposableInterval', () => {
+    let a = 0;
+    const disposable = setDisposableInterval(() => {
+      a++;
+    }, 20);
+    vi.advanceTimersByTime(25);
+    expect(a).toBe(1);
+    disposable.dispose();
+    vi.advanceTimersByTime(25);
+    expect(a).toBe(1);
+  });
+});

package/src/dispose/timer.ts

@@ -0,0 +1,16 @@
+import type { IDisposable } from './dispose-base';
+import { makeSafeDisposable } from './disposable-utils';
+
+export function setDisposableTimeout(fn: (...args: any[]) => void, timeout: number): IDisposable {
+  const handle = setTimeout(() => {
+    fn();
+  }, timeout);
+  return makeSafeDisposable(() => clearTimeout(handle));
+}
+
+export function setDisposableInterval(fn: (...args: any[]) => void, timeout: number): IDisposable {
+  const handle = setInterval(() => {
+    fn();
+  }, timeout);
+  return makeSafeDisposable(() => clearInterval(handle));
+}

package/src/dispose/tracker.test.ts

@@ -0,0 +1,51 @@
+import { Disposable } from './disposable-t';
+import { makeSafeDisposable } from './disposable-utils';
+import { disableTrack, enableTrack } from './tracker';
+import type { IDisposableTracker } from './tracker';
+import type { IDisposable } from './dispose-base';
+
+vi.useFakeTimers();
+vi.spyOn(global, 'setTimeout');
+
+class Bar extends Disposable {
+  constructor() {
+    super();
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    this._register(makeSafeDisposable(() => {}));
+  }
+}
+
+class Foo extends Disposable {
+  constructor(mockFunc: () => void) {
+    super();
+    this._register(new Bar());
+    this._register(makeSafeDisposable(mockFunc));
+  }
+}
+
+describe('dispose store', () => {
+  it('tracker success', () => {
+    let count = 0;
+    enableTrack(
+      new (class implements IDisposableTracker {
+        trackDisposable(x: IDisposable): void {
+          count++;
+        }
+
+        setParent(child: IDisposable, parent: IDisposable | null): void {
+          count--;
+        }
+
+        markAsDisposed(disposable: IDisposable): void {
+          count--;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-empty-function
+        markAsLeaked(disposable: IDisposable): void {}
+      })(),
+    );
+    new Foo(vi.fn());
+    // 只剩下根节点
+    expect(count).toBe(1);
+    disableTrack();
+  });
+});