@zk-tech/bedrock 0.0.1

package/src/array/array.test.ts

@@ -0,0 +1,35 @@
+import { trimStart, trimEnd } from './array';
+
+describe('trimStart', () => {
+  it('trimStart', () => {
+    expect(trimStart([], () => true)).toEqual([]);
+
+    expect(trimStart([1, 2], () => true)).toEqual([]);
+
+    expect(trimStart([1, 2], (x) => x === 1)).toEqual([2]);
+
+    expect(trimStart([1, 2], (x) => x === 2)).toEqual([1, 2]);
+
+    expect(trimStart([1, 2], (x) => x === 3)).toEqual([1, 2]);
+
+    expect(trimStart([1, 1, 2], (x) => x === 1)).toEqual([2]);
+
+    expect(trimStart([1, 1, 1], (x) => x === 1)).toEqual([]);
+  });
+
+  it('trimEnd', () => {
+    expect(trimEnd([], () => true)).toEqual([]);
+
+    expect(trimEnd([2, 1], () => true)).toEqual([]);
+
+    expect(trimEnd([2, 1], (x) => x === 1)).toEqual([2]);
+
+    expect(trimEnd([2, 1], (x) => x === 2)).toEqual([2, 1]);
+
+    expect(trimEnd([2, 1], (x) => x === 3)).toEqual([2, 1]);
+
+    expect(trimEnd([2, 1, 1], (x) => x === 1)).toEqual([2]);
+
+    expect(trimEnd([1, 1, 1], (x) => x === 1)).toEqual([]);
+  });
+});

package/src/array/array.ts

@@ -0,0 +1,25 @@
+/**
+ * 提供一系列数组的辅助函数
+ */
+
+/**
+ * 去掉数组前面满足条件的项
+ */
+export function trimStart<T>(arr: T[], condition: (element: T) => boolean): T[] {
+  let index = 0;
+  while (index < arr.length && condition(arr[index])) {
+    index++;
+  }
+  return arr.slice(index);
+}
+
+/**
+ * 去掉数组后面满足条件的项
+ */
+export function trimEnd<T>(arr: T[], condition: (element: T) => boolean): T[] {
+  let index = arr.length - 1;
+  while (index >= 0 && condition(arr[index])) {
+    index--;
+  }
+  return arr.slice(0, index + 1);
+}

package/src/array/index.ts

@@ -0,0 +1 @@
+export { trimStart, trimEnd } from './array';

package/src/assert/assert.test.ts

@@ -0,0 +1,86 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { lvAssert, lvAssertNever, lvAssertNotHere, lvAssertNotNil } from './assert';
+
+describe('assert', () => {
+  it('lvAssert', () => {
+    expect(() => {
+      lvAssert(false);
+    }).toThrow('lvAssert(#expr is false)');
+
+    expect(() => {
+      lvAssert(true);
+    }).not.toThrowError();
+
+    expect(() => {
+      const bool = true as boolean;
+      lvAssert(bool);
+      // assert 可以自动去掉 false
+      const _true: true = bool;
+      const str = 'hello' as string | undefined;
+      lvAssert(str);
+      // assert 可以自动去掉 undefined
+      const _str: string = str;
+    }).not.toThrowError();
+  });
+
+  it('lvAssertNotHere', () => {
+    expect(() => {
+      lvAssertNotHere();
+      // @ts-expect-error 前面已经断言抛异常了，后面代码必定不会被执行，应该报错
+      const _a = 1;
+    }).toThrow('lvAssert(unreachable code flow)');
+  });
+
+  it('lvAssertNotNil', () => {
+    expect(() => {
+      lvAssertNotNil(undefined);
+    }).toThrow('lvAssert(#val is nil)');
+
+    expect(() => {
+      lvAssertNotNil(null);
+    }).toThrow('lvAssert(#val is nil)');
+
+    expect(() => {
+      lvAssertNotNil({});
+    }).not.toThrowError();
+
+    expect(() => {
+      const nullableString = '' as string | undefined;
+      lvAssertNotNil(nullableString);
+      const _str: string = nullableString;
+    }).not.toThrowError();
+  });
+
+  it('lvAssertNever', () => {
+    enum ErrorCode {
+      A,
+      B,
+      C,
+    }
+
+    const errorCode = ErrorCode.A as ErrorCode;
+    const _handler1: () => 1 = () => {
+      switch (errorCode) {
+        case ErrorCode.A:
+        case ErrorCode.B:
+          return 1;
+        default:
+          // @ts-expect-error switch case 没有覆盖所有的 case，应该报错
+          lvAssertNever(errorCode);
+      }
+    };
+
+    const _handler2: () => 1 = () => {
+      switch (errorCode) {
+        case ErrorCode.A:
+        case ErrorCode.B:
+        case ErrorCode.C:
+          return 1;
+        default:
+          // 已覆盖全部 case
+          lvAssertNever(errorCode);
+      }
+    };
+  });
+});

package/src/assert/assert.ts

@@ -0,0 +1,42 @@
+function abort(reason: string): never {
+  throw new Error(`lvAssert(${reason})`);
+}
+
+/**
+ * 断言表达式为真
+ * @param expr 
+ * @param reason 
+ */
+export function lvAssert(expr: unknown, reason?: string): asserts expr {
+  if (!expr) {
+    abort(reason ?? '#expr is false');
+  }
+}
+
+/**
+ * 断言deadcode路径
+ * @param reason 
+ */
+export function lvAssertNotHere(reason?: string): never {
+  abort(reason ?? 'unreachable code flow');
+}
+
+/**
+ * 断言类型不可达
+ * @param member 
+ * @param message 
+ */
+export function lvAssertNever(member: never, message = 'Illegal value:'): never {
+  abort(`${message}: ${member}`);
+}
+
+/**
+ * 断言变量为null或者undefined
+ * @param val 
+ * @param reason 
+ */
+export function lvAssertNotNil<T>(val: T, reason?: string): asserts val is NonNullable<T> {
+  if (val === null || val === undefined) {
+    abort(reason ?? '#val is nil');
+  }
+}

package/src/assert/index.ts

@@ -0,0 +1,2 @@
+// 提供断言能力
+export { lvAssert, lvAssertNotHere, lvAssertNever, lvAssertNotNil } from './assert';

package/src/async/barrier.test.ts

@@ -0,0 +1,90 @@
+import { Barrier, makeBarrierByPromise } from './barrier';
+
+describe('barrier', () => {
+  it('barriers promise', async () => {
+    vi.useFakeTimers();
+    const before = Date.now();
+    const barrier = new Barrier();
+    expect(barrier.isOpen()).toBe(false);
+    setTimeout(() => {
+      barrier.open();
+    }, 300);
+    vi.advanceTimersByTime(300);
+    await barrier.wait();
+    expect(barrier.isOpen()).toBe(true);
+    expect(Date.now() - before).toBe(300);
+  });
+
+  // resolve成功
+  it('makeBarrierByPromise1', async () => {
+    vi.useFakeTimers();
+    const barrier = makeBarrierByPromise(
+      new Promise<void>((resolve) => {
+        setTimeout(() => {
+          resolve();
+        }, 300);
+      }),
+    );
+    vi.advanceTimersByTime(400);
+    // 涉及到promise，等待一次tick
+    await Promise.resolve();
+    expect(barrier.isOpen()).toBe(true);
+  });
+
+  // 一直在pending中
+  it('makeBarrierByPromise2', async () => {
+    vi.useFakeTimers();
+    const barrier = makeBarrierByPromise(
+      new Promise<void>((resolve) => {
+        setTimeout(() => {
+          resolve();
+        }, 500);
+      }),
+    );
+    vi.advanceTimersByTime(300);
+    // 涉及到promise，等待一次tick
+    await Promise.resolve();
+    expect(barrier.isOpen()).toBe(false);
+  });
+
+  // reject，没有扭转
+  it('makeBarrierByPromise3', async () => {
+    try {
+      vi.useFakeTimers();
+      const barrier = makeBarrierByPromise(
+        expect(
+          new Promise<void>((resolve, reject) => {
+            setTimeout(() => {
+              reject(new Error('123'));
+            }, 300);
+          }),
+        ).rejects.toThrow(new Error('123')),
+      );
+      vi.advanceTimersByTime(400);
+      // 涉及到promise，等待一次tick
+      await Promise.resolve();
+      expect(barrier.isOpen()).toBe(false);
+    } catch (error) {}
+  });
+
+  // reject，进行扭转
+  it('makeBarrierByPromise4', async () => {
+    try {
+      vi.useFakeTimers();
+      const barrier = makeBarrierByPromise(
+        expect(
+          new Promise<void>((resolve, reject) => {
+            setTimeout(() => {
+              reject(new Error('123'));
+            }, 300);
+          }),
+        ).rejects.toThrow(new Error('123')),
+        true,
+      );
+      vi.advanceTimersByTime(400);
+      // 涉及到promise，等待一次tick
+      await Promise.resolve();
+      expect(barrier.isOpen()).toBe(true);
+    } catch (error) {}
+  });
+});

package/src/async/barrier.ts

@@ -0,0 +1,58 @@
+export interface IBarrier {
+  isOpen: () => boolean;
+  open: () => void;
+  wait: () => Promise<boolean>;
+}
+
+/**
+ * A barrier that is initially closed and then becomes opened permanently after a certain period of
+ * time or when open is called explicitly
+ */
+export class Barrier {
+  private _isOpen: boolean;
+  private readonly _promise: Promise<boolean>;
+  private _completePromise!: (v: boolean) => void;
+  private _rejectPromise!: (e: unknown) => void;
+
+  constructor() {
+    this._isOpen = false;
+    this._promise = new Promise<boolean>((c, e) => {
+      this._completePromise = c;
+      this._rejectPromise = e;
+    });
+  }
+
+  isOpen(): boolean {
+    return this._isOpen;
+  }
+
+  open(): void {
+    this._isOpen = true;
+    this._completePromise(true);
+  }
+
+  reject(e: unknown): void {
+    this._rejectPromise(e);
+  }
+
+  wait(): Promise<boolean> {
+    return this._promise;
+  }
+}
+
+export function makeBarrierByPromise(promise: Promise<any>, openWhenReject: boolean = false) {
+  const barrier = new Barrier();
+
+  promise
+    .then(() => barrier.open())
+    .catch((err) => {
+      if (openWhenReject) {
+        barrier.open();
+        throw err;
+      } else {
+        barrier.reject(err);
+      }
+    });
+
+  return barrier;
+}

package/src/async/cancellation.test.ts

@@ -0,0 +1,85 @@
+import type { ICancellationToken } from './cancellation';
+import { CancellationTokenSource } from './cancellation';
+
+vi.useFakeTimers();
+vi.spyOn(global, 'setTimeout');
+vi.spyOn(global, 'clearTimeout');
+
+function mockFetchData(token: ICancellationToken, mockTime: number) {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      resolve(true);
+    }, 4000);
+    token.onCancellationRequested(() => {
+      resolve(false);
+    });
+    vi.advanceTimersByTime(mockTime);
+  });
+}
+
+describe('CancellationToken', () => {
+  it('token cancelled', async () => {
+    const tokenSource = new CancellationTokenSource();
+    const { token } = tokenSource;
+    tokenSource.cancel();
+    const result = await mockFetchData(token, 0);
+    expect(result).toBe(false);
+  });
+
+  it('token cancel when waiting', async () => {
+    const tokenSource = new CancellationTokenSource();
+    const { token } = tokenSource;
+    setTimeout(() => {
+      tokenSource.cancel();
+    }, 1000);
+    const result = await mockFetchData(token, 1000);
+    expect(result).toBe(false);
+  });
+
+  it('fetch success', async () => {
+    const tokenSource = new CancellationTokenSource();
+    const { token } = tokenSource;
+    setTimeout(() => {
+      tokenSource.cancel();
+    }, 5000);
+    const result = await mockFetchData(token, 4000);
+    expect(result).toBe(true);
+  });
+
+  /**
+   * 取消前先获取signal
+   */
+  it('signal change1', async () => {
+    const tokenSource = new CancellationTokenSource();
+    const { signal, token } = tokenSource;
+    expect(signal.aborted).toBe(false);
+    setTimeout(() => {
+      tokenSource.cancel();
+    }, 1000);
+    await mockFetchData(token, 4000);
+    expect(signal.aborted).toBe(true);
+  });
+
+  /**
+   * 取消后再获取signal
+   */
+  it('signal change2', async () => {
+    const tokenSource = new CancellationTokenSource();
+    const { token } = tokenSource;
+    setTimeout(() => {
+      tokenSource.cancel();
+    }, 1000);
+    await mockFetchData(token, 4000);
+    expect(tokenSource.signal.aborted).toBe(true);
+  });
+
+  it('reason', async () => {
+    const tokenSource = new CancellationTokenSource();
+    const { token } = tokenSource;
+    setTimeout(() => {
+      tokenSource.cancel('unknown');
+    }, 1000);
+    await mockFetchData(token, 4000);
+    expect(token.reason).toBe('unknown');
+  });
+});

package/src/async/cancellation.ts

@@ -0,0 +1,193 @@
+import { EmptyDispose, type IDisposable } from '@/dispose';
+import type { Event } from '@/event';
+import { Emitter } from '@/event';
+
+//
+// 任何可取消的异步调用 的令牌接口
+// 因为异步调用无法真正意义上取消，但是可以在异步任务的回调中增加该令牌作为参数
+// 以便在操作被取消时停止执行
+//
+export interface ICancellationToken {
+  // 标记是否进行过了cancel
+  readonly isCancellationRequested: boolean;
+
+  // 取消的原因
+  readonly reason?: string;
+
+  // 令牌调用cancel后触发的回调
+  // 有如下特点
+  // 1. 只会触发一次
+  // 2. 当监听的时候token已经cancelled，仍然会触发一次
+  readonly onCancellationRequested: (
+    listener: () => any,
+    thisArgs?: any,
+    disposables?: IDisposable[],
+  ) => IDisposable;
+}
+
+//
+// 编译时常量，一个快捷的事件响应
+// 用于当外界监听令牌取消时，直接触发回调
+//
+const shortcutEvent: Event<[]> = Object.freeze(function (callback, context?): IDisposable {
+  const handle = setTimeout(callback.bind(context), 0);
+
+  return {
+    dispose() {
+      clearTimeout(handle);
+    },
+  };
+});
+
+//
+// 可取消异步调用的令牌实现
+// 默认是未取消状态，可以调用cancel进行取消
+//
+class MutableToken implements ICancellationToken, IDisposable {
+  // 是否已经取消该异步调用
+  private _isCancelled = false;
+  private _emitter: Emitter<[]> | null = null;
+  private _reason?: string;
+
+  public get reason(): undefined | string {
+    return this._reason;
+  }
+
+  // 获取当前是否已经取消该异步调用
+  public get isCancellationRequested(): boolean {
+    return this._isCancelled;
+  }
+
+  // 外界可以监听异步取消发起
+  public get onCancellationRequested(): Event<[]> {
+    if (this._isCancelled) {
+      return shortcutEvent;
+    }
+    if (!this._emitter) {
+      this._emitter = new Emitter<[]>();
+    }
+    return this._emitter.event;
+  }
+
+  public cancel(reason?: string) {
+    if (!this._isCancelled) {
+      this._reason = reason;
+      this._isCancelled = true;
+      if (this._emitter) {
+        this._emitter.fire();
+        this.dispose();
+      }
+    }
+  }
+
+  public dispose(): void {
+    if (this._emitter) {
+      this._emitter.dispose();
+      this._emitter = null;
+    }
+  }
+}
+
+//
+// 编译期提供的一些常量Token
+// 不可修改
+//
+// eslint-disable-next-line unicorn/no-static-only-class, @typescript-eslint/no-extraneous-class
+export class CancellationToken {
+  static None = Object.freeze<ICancellationToken>({
+    isCancellationRequested: false,
+    onCancellationRequested: () => EmptyDispose,
+  });
+
+  static Cancelled = Object.freeze<ICancellationToken>({
+    isCancellationRequested: true,
+    onCancellationRequested: shortcutEvent,
+  });
+
+  static Make = (reason: string) => {
+    return Object.freeze<ICancellationToken>({
+      isCancellationRequested: true,
+      onCancellationRequested: shortcutEvent,
+      reason,
+    });
+  };
+}
+
+//
+// 任何可取消的异步调用 的控制类
+// 参考ICancellationToken，我们通过在异步调用的回调中添加token参数来判断异步调用的状态
+// token来源于CancellationTokenSource
+// CancellationTokenSource也会暴露cancel的接口
+//
+// 使用方式
+// const tokenSource = new CancellationTokenSource();
+//
+// asyncCall(() => {
+//   if (token.isCancellationRequested) { return; }  // 如果cancelled
+//   doSomething();
+// });
+//
+// tokenSource.cancel();  // 因为某些情况，可能会cancel
+// tokenSource.dispose();  // dispose时一定会cancel
+//
+export class CancellationTokenSource implements IDisposable {
+  // 真正的token
+  private _token?: ICancellationToken = undefined;
+  // 可能存在父级CancellationTokenSource
+  private readonly _parentListener?: IDisposable = undefined;
+  // 为了支持signal场景，所以在需要时会初始化浏览器提供的abortController原生结构
+  private _abortController?: AbortController = undefined;
+
+  constructor(parent?: ICancellationToken) {
+    // 如果存在父级，当父对象cancel时，子对象也必须cancel
+    this._parentListener = parent?.onCancellationRequested(this.cancel, this);
+  }
+
+  /**
+   * 传统的cancellation用法
+   */
+  public get token(): ICancellationToken {
+    if (!this._token) {
+      this._token = new MutableToken();
+    }
+    return this._token;
+  }
+
+  /**
+   * 对齐浏览器提供的abortSignal，支持给fetch、axios等传参使用
+   */
+  public get signal(): AbortSignal {
+    if (this._abortController) {
+      return this._abortController.signal;
+    }
+    this._abortController = new AbortController();
+    if (this._token?.isCancellationRequested) {
+      this._abortController.abort();
+    }
+    return this._abortController.signal;
+  }
+
+  public cancel(reason?: string): void {
+    if (!this._token) {
+      // 如果没有使用过token就直接cancel，那么就返回一个常量即可
+      this._token = reason === undefined ? CancellationToken.Cancelled : CancellationToken.Make(reason);
+    } else if (this._token instanceof MutableToken) {
+      this._token.cancel(reason);
+    }
+    if (this._abortController) {
+      this._abortController.abort(reason);
+    }
+  }
+
+  public dispose(cancel = false): void {
+    if (cancel) {
+      this.cancel();
+    }
+    this._parentListener?.dispose();
+    if (!this._token) {
+      this._token = CancellationToken.None;
+    } else if (this._token instanceof MutableToken) {
+      this._token.dispose();
+    }
+  }
+}

package/src/async/index.ts

@@ -0,0 +1,18 @@
+// 异步任务可取消的token
+export type { ICancellationToken } from './cancellation';
+// 异步任务可取消的源
+export { CancellationTokenSource } from './cancellation';
+
+// 通用的wait函数，提供异步等待能力
+export { wait, sleep } from './wait';
+
+// 提供调用 open 后 resolve promise 的能力
+export { Barrier } from './barrier';
+export { makeBarrierByPromise } from './barrier';
+
+// 提供异步队列控制器
+export { AsyncQueue } from './queue/queue';
+export type { IAsyncTask } from './queue/task';
+
+// 下一次eventloop再执行方法
+export { invokeNextLoop } from './utils';