@zk-tech/bedrock 0.0.1

package/src/scheduler/core/task.test.ts

@@ -0,0 +1,34 @@
+import { Task } from './task';
+
+describe('Task', () => {
+  test('initialize', () => {
+    const callback = vi.fn();
+    const task = new Task(callback, 10, 20);
+    expect(task.getCallback()).toBe(callback);
+    expect(task.getStartTime()).toBe(10);
+    expect(task.getExpirationTime()).toBe(20);
+    expect(task.getSortIndex()).toBe(-1);
+  });
+
+  test('setCallback1', () => {
+    const callback = vi.fn();
+    const task = new Task(callback, 10, 20);
+    const callback2 = vi.fn();
+    expect(() => {
+      task.setCallback(callback2);
+    }).toThrowError();
+  });
+
+  test('setCallback2', () => {
+    const callback = vi.fn();
+    const task = new Task(callback, 10, 20);
+    task.clearCallback();
+    expect(task.getCallback()).toBeUndefined();
+
+    const callback2 = vi.fn();
+    expect(() => {
+      task.setCallback(callback2);
+    }).not.toThrowError();
+    expect(task.getCallback()).toBe(callback2);
+  });
+});

package/src/scheduler/core/task.ts

@@ -0,0 +1,52 @@
+import { lvAssert } from '../../assert';
+import type { IScheduledCallback } from '../type';
+
+export class Task {
+  private _callback?: IScheduledCallback;
+  private _sortIndex: number = -1;
+
+  constructor(
+    callback: IScheduledCallback,
+    private _startTime: number,
+    private _expirationTime: number,
+  ) {
+    this._callback = callback;
+  }
+
+  getCallback() {
+    return this._callback;
+  }
+
+  setCallback(callback: IScheduledCallback) {
+    lvAssert(this._callback === undefined, 'cant overlay callback.');
+    this._callback = callback;
+  }
+
+  clearCallback() {
+    this._callback = undefined;
+  }
+
+  getStartTime() {
+    return this._startTime;
+  }
+
+  setStartTime(startTime: number) {
+    this._startTime = startTime;
+  }
+
+  getExpirationTime() {
+    return this._expirationTime;
+  }
+
+  setExpirationTime(expirationTime: number) {
+    this._expirationTime = expirationTime;
+  }
+
+  setSortIndex(index: number) {
+    this._sortIndex = index;
+  }
+
+  getSortIndex() {
+    return this._sortIndex;
+  }
+}

package/src/scheduler/core/utils.ts

@@ -0,0 +1,48 @@
+// Max 31 bit integer. The max integer size in V8 for 32-bit systems.
+// Math.pow(2, 30) - 1
+
+import { Task } from './task';
+import { PriorityLevel, type IScheduledCallback, type IOptions } from '../type';
+
+// 0b111111111111111111111111111111
+const maxSigned31BitInt = 1073741823;
+
+// Times out immediately
+const IMMEDIATE_PRIORITY_TIMEOUT = -1;
+// Eventually times out
+const USER_BLOCKING_PRIORITY_TIMEOUT = 250;
+const NORMAL_PRIORITY_TIMEOUT = 5000;
+const LOW_PRIORITY_TIMEOUT = 10000;
+// Never times out
+const IDLE_PRIORITY_TIMEOUT = maxSigned31BitInt;
+
+export function getCurrentTime() {
+  return Date.now();
+}
+
+export function getTimeout(priorityLevel: PriorityLevel = PriorityLevel.NormalPriority) {
+  switch (priorityLevel) {
+    case PriorityLevel.ImmediatePriority:
+      return IMMEDIATE_PRIORITY_TIMEOUT;
+    case PriorityLevel.UserBlockingPriority:
+      return USER_BLOCKING_PRIORITY_TIMEOUT;
+    case PriorityLevel.IdlePriority:
+      return IDLE_PRIORITY_TIMEOUT;
+    case PriorityLevel.LowPriority:
+      return LOW_PRIORITY_TIMEOUT;
+    case PriorityLevel.NormalPriority:
+    default:
+      return NORMAL_PRIORITY_TIMEOUT;
+  }
+}
+
+export function makeTask(callback: IScheduledCallback, options: IOptions = {}) {
+  const currentTime = getCurrentTime();
+  const delay = options.delay ?? 0;
+  const timeout = getTimeout(options.priorityLevel);
+  const startTime = delay + currentTime;
+  const expirationTime = startTime + timeout;
+
+  const newTask = new Task(callback, startTime, expirationTime);
+  return newTask;
+}

package/src/scheduler/executor/abstract-executor.test.ts

@@ -0,0 +1,44 @@
+import { AbstractExecutor } from './abstract-executor';
+import type { IExecutedCallback } from './executor.interface';
+
+class TestExecutor extends AbstractExecutor {
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  public requestHostCallback(fn: IExecutedCallback) {}
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  public cancelHostCallback() {}
+}
+
+describe('AbstractExecutor', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  // 延迟任务调度正常执行
+  test('requestHostTimeout1', () => {
+    const testExecutor = new TestExecutor();
+    const fn = vi.fn();
+    testExecutor.requestHostTimeout(fn, 3);
+    vi.advanceTimersByTime(10);
+    expect(fn).toBeCalled();
+  });
+
+  // 重复进行延迟任务调度，报错
+  test('requestHostTimeout2', () => {
+    const testExecutor = new TestExecutor();
+    const fn = vi.fn();
+    testExecutor.requestHostTimeout(fn, 3);
+    expect(() => {
+      testExecutor.requestHostTimeout(fn, 3);
+    }).toThrowError();
+  });
+
+  test('cancelHostTimeout', () => {
+    const testExecutor = new TestExecutor();
+    const fn = vi.fn();
+    testExecutor.requestHostTimeout(fn, 3);
+    testExecutor.cancelHostTimeout();
+    vi.advanceTimersByTime(10);
+    expect(fn).not.toBeCalled();
+  });
+});

package/src/scheduler/executor/abstract-executor.ts

@@ -0,0 +1,38 @@
+import { lvAssert } from '../../assert';
+import type { IExecutedCallback, IExecutor } from './executor.interface';
+
+export abstract class AbstractExecutor implements IExecutor {
+  private _timeoutId: number = -1;
+  protected _deadline: number = 0;
+  protected _yieldInterval: number = 16;
+
+  get deadline() {
+    return this._deadline;
+  }
+
+  setFrameRate(fps: number) {
+    lvAssert(fps > 0 && fps <= 125);
+    this._yieldInterval = Math.floor(1000 / fps);
+  }
+
+  resetFrameRate() {
+    this._yieldInterval = 16;
+  }
+
+  public abstract requestHostCallback(fn: IExecutedCallback): void;
+  public abstract cancelHostCallback(): void;
+
+  public requestHostTimeout(fn: () => void, delayMs: number) {
+    lvAssert(this._timeoutId === -1, 'has request host timeout.');
+    clearTimeout(this._timeoutId);
+    this._timeoutId = setTimeout(() => {
+      this._timeoutId = -1;
+      fn();
+    }, delayMs) as unknown as number;
+  }
+
+  public cancelHostTimeout() {
+    clearTimeout(this._timeoutId);
+    this._timeoutId = -1;
+  }
+}

package/src/scheduler/executor/executor.interface.ts

@@ -0,0 +1,39 @@
+export interface IExecutedCallback {
+  /**
+   * hasTimeRemaining 该回调执行时还有没有剩余时间片
+   * currentTime 执行该回调时时间
+   */
+  (hasTimeRemaining: boolean, currentTime: number, deadline: number): boolean;
+}
+
+export interface IExecutor {
+  /**
+   * 设置帧率，该值会影响每次执行的deadline
+   */
+  setFrameRate: (fps: number) => void;
+
+  /**
+   * 重置帧率
+   */
+  resetFrameRate: () => void;
+
+  /**
+   * 请求及时任务调用
+   */
+  requestHostCallback: (fn: IExecutedCallback) => void;
+
+  /**
+   * 取消及时任务调用
+   */
+  cancelHostCallback: () => void;
+
+  /**
+   * 请求延迟任务调用
+   */
+  requestHostTimeout: (fn: () => void, delayMs: number) => void;
+
+  /**
+   * 取消延迟任务调用
+   */
+  cancelHostTimeout: () => void;
+}

package/src/scheduler/executor/idle-callback-executor.test.ts

@@ -0,0 +1,70 @@
+import { IdleCallbackExecutor } from './idle-callback-executor';
+
+describe('IdleCallbackExecutor', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  test('requestHostCallback1', async () => {
+    const idleCallbackExecutor = new IdleCallbackExecutor();
+    const fn1 = vi.fn();
+
+    idleCallbackExecutor.requestHostCallback(fn1);
+
+    vi.advanceTimersByTime(50);
+    expect(fn1).toBeCalled();
+  });
+
+  // 多次调度及时任务，后者覆盖
+  test('requestHostCallback2', async () => {
+    const idleCallbackExecutor = new IdleCallbackExecutor();
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+
+    idleCallbackExecutor.requestHostCallback(fn1);
+    idleCallbackExecutor.requestHostCallback(fn2);
+
+    vi.advanceTimersByTime(50);
+    expect(fn1).not.toBeCalled();
+    expect(fn2).toBeCalled();
+  });
+
+  // 成功取消
+  test('cancelHostCallback1', async () => {
+    const idleCallbackExecutor = new IdleCallbackExecutor();
+    const fn1 = vi.fn();
+
+    idleCallbackExecutor.requestHostCallback(fn1);
+    idleCallbackExecutor.cancelHostCallback();
+
+    vi.advanceTimersByTime(50);
+    expect(fn1).not.toBeCalled();
+  });
+
+  // 成功取消，后续添加正常
+  test('cancelHostCallback2', async () => {
+    const idleCallbackExecutor = new IdleCallbackExecutor();
+    const fn1 = vi.fn();
+
+    idleCallbackExecutor.requestHostCallback(fn1);
+    idleCallbackExecutor.cancelHostCallback();
+    vi.advanceTimersByTime(50);
+    expect(fn1).not.toBeCalled();
+
+    idleCallbackExecutor.requestHostCallback(fn1);
+    vi.advanceTimersByTime(50);
+    expect(fn1).toBeCalled();
+  });
+
+  // 针对场景2的同步行为
+  test('cancelHostCallback3', async () => {
+    const idleCallbackExecutor = new IdleCallbackExecutor();
+    const fn1 = vi.fn();
+
+    idleCallbackExecutor.requestHostCallback(fn1);
+    idleCallbackExecutor.cancelHostCallback();
+    idleCallbackExecutor.requestHostCallback(fn1);
+    vi.advanceTimersByTime(50);
+    expect(fn1).toBeCalledTimes(1);
+  });
+});

package/src/scheduler/executor/idle-callback-executor.ts

@@ -0,0 +1,98 @@
+import type { IDisposable } from '../../dispose';
+import { getCurrentTime } from '../core/utils';
+import { AbstractExecutor } from './abstract-executor';
+import type { IExecutedCallback } from './executor.interface';
+
+declare function requestIdleCallback(
+  callback: (args: IdleDeadline) => void,
+  options?: { timeout: number },
+): number;
+declare function cancelIdleCallback(handle: number): void;
+
+export class IdleCallbackExecutor extends AbstractExecutor {
+  private _scheduledCallback?: IExecutedCallback;
+  private _disposable?: IDisposable;
+  private _runWhenIdle: (callback: (idle: IdleDeadline) => void, timeout?: number) => IDisposable;
+
+  constructor() {
+    super();
+    if (typeof requestIdleCallback !== 'function' || typeof cancelIdleCallback !== 'function') {
+      this._runWhenIdle = (runner) => {
+        let disposed = false;
+        setTimeout(() => {
+          if (disposed) {
+            return;
+          }
+          const end = Date.now() + 15; // one frame at 64fps
+          runner(
+            Object.freeze({
+              didTimeout: true,
+              timeRemaining() {
+                return Math.max(0, end - Date.now());
+              },
+            }),
+          );
+        });
+        return {
+          dispose() {
+            if (disposed) {
+              return;
+            }
+            disposed = true;
+          },
+        };
+      };
+    } else {
+      this._runWhenIdle = (runner, timeout?) => {
+        const handle: number = requestIdleCallback(
+          runner,
+          typeof timeout === 'number' ? { timeout } : undefined,
+        );
+        let disposed = false;
+        return {
+          dispose() {
+            if (disposed) {
+              return;
+            }
+            disposed = true;
+            cancelIdleCallback(handle);
+          },
+        };
+      };
+    }
+  }
+
+  public requestHostCallback(fn: IExecutedCallback) {
+    this._scheduledCallback = fn;
+    if (!this._disposable) {
+      this._disposable = this._runWhenIdle(this._flushCallback);
+    }
+  }
+
+  public cancelHostCallback() {
+    this._disposable?.dispose();
+    this._scheduledCallback = undefined;
+    this._disposable = undefined;
+  }
+
+  private readonly _flushCallback = () => {
+    if (!this._scheduledCallback) {
+      return;
+    }
+    const currentTime = getCurrentTime();
+    const deadline = currentTime + this._yieldInterval;
+
+    try {
+      const hasMoreWork = this._scheduledCallback(true, currentTime, deadline);
+      if (!hasMoreWork) {
+        this._scheduledCallback = undefined;
+        this._disposable = undefined;
+      } else {
+        this._disposable = this._runWhenIdle(this._flushCallback);
+      }
+    } catch (err) {
+      this._disposable = this._runWhenIdle(this._flushCallback);
+      throw err;
+    }
+  };
+}

package/src/scheduler/executor/make-executor.ts

@@ -0,0 +1,18 @@
+import type { IExecutor } from './executor.interface';
+import { IdleCallbackExecutor } from './idle-callback-executor';
+import { PostMessageExecutor } from './post-message-executor';
+
+declare const global: {
+  window?: any;
+};
+
+export function makeExecutor(): IExecutor {
+  try {
+    if (global.window) {
+      return new PostMessageExecutor();
+    }
+  } catch (e) {
+    // ...
+  }
+  return new IdleCallbackExecutor();
+}

package/src/scheduler/executor/post-message-executor.test.ts

@@ -0,0 +1,66 @@
+import { wait } from '../../async';
+import { PostMessageExecutor } from './post-message-executor';
+
+describe('PostMessageExecutor', () => {
+  test('requestHostCallback1', async () => {
+    const postMessageExecutor = new PostMessageExecutor();
+    const fn1 = vi.fn();
+
+    postMessageExecutor.requestHostCallback(fn1);
+
+    await wait(150);
+    expect(fn1).toBeCalled();
+  });
+
+  // 多次调度及时任务，后者覆盖
+  test('requestHostCallback2', async () => {
+    const postMessageExecutor = new PostMessageExecutor();
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+
+    postMessageExecutor.requestHostCallback(fn1);
+    postMessageExecutor.requestHostCallback(fn2);
+
+    await wait(150);
+    expect(fn1).not.toBeCalled();
+    expect(fn2).toBeCalled();
+  });
+
+  // 成功取消
+  test('cancelHostCallback1', async () => {
+    const postMessageExecutor = new PostMessageExecutor();
+    const fn1 = vi.fn();
+
+    postMessageExecutor.requestHostCallback(fn1);
+    postMessageExecutor.cancelHostCallback();
+
+    await wait(150);
+    expect(fn1).not.toBeCalled();
+  });
+
+  // 成功取消，后续添加正常
+  test('cancelHostCallback2', async () => {
+    const postMessageExecutor = new PostMessageExecutor();
+    const fn1 = vi.fn();
+
+    postMessageExecutor.requestHostCallback(fn1);
+    postMessageExecutor.cancelHostCallback();
+    await wait(150);
+    expect(fn1).not.toBeCalled();
+
+    postMessageExecutor.requestHostCallback(fn1);
+    await wait(150);
+    expect(fn1).toBeCalled();
+  });
+
+  test('cancelHostCallback3', async () => {
+    const postMessageExecutor = new PostMessageExecutor();
+    const fn1 = vi.fn();
+
+    postMessageExecutor.requestHostCallback(fn1);
+    postMessageExecutor.cancelHostCallback();
+    postMessageExecutor.requestHostCallback(fn1);
+    await wait(150);
+    expect(fn1).toBeCalledTimes(1);
+  });
+});

package/src/scheduler/executor/post-message-executor.ts

@@ -0,0 +1,52 @@
+import { getCurrentTime } from '../core/utils';
+import { AbstractExecutor } from './abstract-executor';
+import type { IExecutedCallback } from './executor.interface';
+
+export class PostMessageExecutor extends AbstractExecutor {
+  private _scheduledCallback?: IExecutedCallback;
+  private _isMessageLoopRunning: boolean = false;
+  private readonly _channel = new MessageChannel();
+
+  constructor() {
+    super();
+
+    this._channel.port1.onmessage = () => {
+      this._flushCallback();
+    };
+  }
+
+  public requestHostCallback(fn: IExecutedCallback) {
+    this._scheduledCallback = fn;
+    if (!this._isMessageLoopRunning) {
+      this._isMessageLoopRunning = true;
+      this._channel.port2.postMessage(null);
+    }
+  }
+
+  public cancelHostCallback() {
+    this._scheduledCallback = undefined;
+  }
+
+  private readonly _flushCallback = () => {
+    if (!this._scheduledCallback) {
+      this._isMessageLoopRunning = false;
+      return;
+    }
+
+    const currentTime = getCurrentTime();
+    const deadline = currentTime + this._yieldInterval;
+
+    try {
+      const hasMoreWork = this._scheduledCallback(true, currentTime, deadline);
+      if (!hasMoreWork) {
+        this._isMessageLoopRunning = false;
+        this._scheduledCallback = undefined;
+      } else {
+        this._channel.port2.postMessage(null);
+      }
+    } catch (err) {
+      this._channel.port2.postMessage(null);
+      throw err;
+    }
+  };
+}

package/src/scheduler/index.ts

@@ -0,0 +1,15 @@
+// 任务调度优先级
+export { PriorityLevel } from './type';
+
+// 分片调度器
+export type { IChunkScheduler, IOptions as ISchedulerCallbackOptions } from './type';
+
+// 执行一个调度任务
+export { lvSchedulerCallback } from './lv-scheduler-callback';
+export type { ILvCallbackToken } from './lv-scheduler-callback';
+
+// 设置调度器配置
+export { lvSchedulerConfig } from './lv-scheduler-config';
+
+// 重置调度器配置
+export { lvSchedulerResetConfig } from './lv-scheduler-config';

package/src/scheduler/lv-scheduler-callback.ts

@@ -0,0 +1,19 @@
+import { type IDisposable } from '../dispose';
+import { getScheduler } from './core/scheduler';
+import type { IOptions, IScheduledCallback, PriorityLevel } from './type';
+import { makeTask } from './core/utils';
+import { CallbackToken } from './callback-token';
+
+export interface ILvCallbackToken extends IDisposable {
+  /**
+   * 更新优先级
+   */
+  updatePriorityLevel: (priorityLevel: PriorityLevel) => void;
+}
+
+export function lvSchedulerCallback(callback: IScheduledCallback, options: IOptions = {}): ILvCallbackToken {
+  const newTask = makeTask(callback, options);
+  getScheduler().addTask(newTask);
+
+  return new CallbackToken(newTask);
+}

package/src/scheduler/lv-scheduler-config.ts

@@ -0,0 +1,17 @@
+import { getScheduler } from './core/scheduler';
+import type { IConfig } from './type';
+
+export function lvSchedulerConfig(config: IConfig) {
+  if (config.fps !== undefined) {
+    getScheduler().executor.setFrameRate(config.fps);
+  }
+
+  if (config.enableInputPending !== undefined) {
+    getScheduler().setEnableInputPending(config.enableInputPending);
+  }
+}
+
+export function lvSchedulerResetConfig() {
+  getScheduler().executor.resetFrameRate();
+  getScheduler().setEnableInputPending(true);
+}

package/src/scheduler/type.ts

@@ -0,0 +1,48 @@
+// 任务调度的优先级，从高到低
+export enum PriorityLevel {
+  /** 立即执行任务的优先级 */
+  ImmediatePriority,
+  /** 用户阻塞的优先级 */
+  UserBlockingPriority,
+  /** 普通优先级 */
+  NormalPriority,
+  /** 低优先级 */
+  LowPriority,
+  /** 闲置优先级 */
+  IdlePriority,
+}
+
+export interface IOptions {
+  delay?: number;
+  priorityLevel?: PriorityLevel;
+}
+
+export interface IConfig {
+  fps?: number;
+  enableInputPending?: boolean;
+}
+
+export interface IScheduledCallback {
+  /**
+   * @param chunkScheduler 分片调度器
+   * @param didUserCallbackTimeout 该callback执行时，是否已经超过了注册时设置的过期时间
+   * @param remainingTime 该callback执行时，当前调度loop中剩余的可用时间
+   */
+  (chunkScheduler: IChunkScheduler, didUserCallbackTimeout: boolean, remainingTime: number): void;
+}
+
+/**
+ * 分片调度器
+ * 支持将某个大的宏任务，拆成小的粒度执行
+ */
+export interface IChunkScheduler {
+  /**
+   * 在分片结束状态下，启动一个新的任务进入调度器
+   */
+  execute: (callback: IScheduledCallback, options?: IOptions) => void;
+
+  /**
+   * 在分片结束状态下，延续当前任务（本质上是立即执行任务）
+   */
+  continueExecute: (callback: IScheduledCallback) => void;
+}

package/src/sprintf/index.ts

@@ -0,0 +1,2 @@
+// 格式化字符串
+export { sprintf } from './sprintf';