@zk-tech/bedrock 0.0.1

package/src/cache/lru-with-timeout.ts

@@ -0,0 +1,85 @@
+import { ignoreDispose } from '@/dispose';
+import { LRUCache } from './lru';
+
+export class LRUCacheWithTimeout<T, K = string> {
+  private readonly _updateTime: Map<K, number> = new Map();
+  private _timer?: NodeJS.Timeout;
+  private readonly _lru: LRUCache<T, K>;
+
+  constructor(
+    capacity: number,
+    private readonly _timeout: number,
+  ) {
+    this._lru = new LRUCache(capacity);
+
+    ignoreDispose(
+      this._lru.onEvicted((key: K) => {
+        this._updateTime.delete(key);
+      }),
+    );
+  }
+
+  get(key: K): T | undefined {
+    const result = this._lru.get(key);
+    if (result) {
+      this._updateTime.set(key, Date.now() + this._timeout);
+    }
+    return result;
+  }
+
+  put(key: K, value: T): void {
+    this._startTimer();
+    this._updateTime.set(key, Date.now() + this._timeout);
+    return this._lru.put(key, value);
+  }
+
+  remove(key: K): void {
+    this._updateTime.delete(key);
+    return this._lru.remove(key);
+  }
+
+  size(): number {
+    return this._lru.size();
+  }
+
+  clear(): void {
+    this._updateTime.clear();
+    return this._lru.clear();
+  }
+
+  dispose(): void {
+    this.clear();
+    clearTimeout(this._timer);
+  }
+
+  private _startTimer() {
+    if (this._timer) {
+      return;
+    }
+    this._timer = setTimeout(this._tick, this._timeout);
+  }
+
+  private _check() {
+    const now = Date.now();
+    const shouldRemove: K[] = [];
+    for (const [key, time] of this._updateTime) {
+      if (time <= now) {
+        shouldRemove.push(key);
+      }
+    }
+    for (const key of shouldRemove) {
+      this._updateTime.delete(key);
+      this._lru.remove(key);
+    }
+  }
+
+  private readonly _tick = () => {
+    this._check();
+    if (this._lru.size() === 0) {
+      // 不再轮询
+      this._timer = undefined;
+      return;
+    }
+    this._timer = setTimeout(this._tick, this._timeout);
+  };
+}

package/src/cache/lru.test.ts

@@ -0,0 +1,56 @@
+import { LRUCache } from './lru';
+
+class Foo {
+  constructor(public readonly value: string) {}
+}
+
+describe('LRUCache', () => {
+  let cache: LRUCache<Foo>;
+
+  beforeEach(() => {
+    // 创建一个容量为5的缓存实例
+    cache = new LRUCache<Foo>(5);
+
+    // 向缓存中添加一些初始数据供测试使用
+    cache.put('1', new Foo('apple'));
+    cache.put('2', new Foo('banana'));
+    cache.put('3', new Foo('orange'));
+  });
+
+  it('should return the value when getting an existing key', () => {
+    const result = cache.get('2');
+    expect(result).not.toBeUndefined();
+    expect(result!.value).toBe('banana');
+  });
+
+  it('should return undefined when getting a non-existing key', () => {
+    const result = cache.get('4');
+    expect(result).toBeUndefined();
+  });
+
+  it('should update the value when putting an existing key', () => {
+    cache.put('2', new Foo('grapefruit'));
+    const result = cache.get('2');
+    expect(result).not.toBeUndefined();
+    expect(result!.value).toBe('grapefruit');
+  });
+
+  it('should add the key-value pair to the cache when putting a new key', () => {
+    cache.put('4', new Foo('kiwi'));
+    const result = cache.get('4');
+    expect(result).not.toBeUndefined();
+    expect(result!.value).toBe('kiwi');
+  });
+
+  it('should remove the least recently used item when the cache is full and a new item is added', () => {
+    cache.put('4', new Foo('kiwi'));
+    cache.put('5', new Foo('pear'));
+    cache.put('6', new Foo('mango'));
+    // 检查最早添加的项是否被移除
+    const result1 = cache.get('1');
+    const result2 = cache.get('2');
+    expect(result1).toBeUndefined();
+    expect(result2).not.toBeUndefined();
+    expect(result2!.value).toBe('banana');
+  });
+});

package/src/cache/lru.ts

@@ -0,0 +1,59 @@
+import { Emitter, type Event } from '@/event';
+
+/**
+ * LRUCache
+ * T 是值类型
+ * K 是索引类型，默认string
+ */
+export class LRUCache<T, K = string> {
+  protected readonly _cache: Map<K, T> = new Map();
+  private _onEvicted?: Emitter<[K, T]>;
+
+  constructor(private readonly _capacity: number) {}
+
+  get onEvicted(): Event<[K, T]> {
+    if (!this._onEvicted) {
+      this._onEvicted = new Emitter();
+    }
+    return this._onEvicted.event;
+  }
+
+  get(key: K): T | undefined {
+    const value = this._cache.get(key);
+    if (value) {
+      // 将访问过的 key 移到最近使用的位置
+      this._cache.delete(key);
+      this._cache.set(key, value);
+    }
+    return value;
+  }
+
+  put(key: K, value: T): void {
+    if (this._cache.has(key)) {
+      // 如果已存在该 key，则将其移动到最近使用的位置
+      this._cache.delete(key);
+    } else if (this._cache.size >= this._capacity) {
+      // 如果已达到容量上限，则删除最久未使用的键值对
+      const oldestKey = this._cache.keys().next().value as K;
+      const oldestVal = this._onEvicted ? this._cache.get(oldestKey)! : null;
+      this._cache.delete(oldestKey);
+      this._onEvicted?.fire(oldestKey, oldestVal!);
+    }
+    this._cache.set(key, value);
+  }
+
+  remove(key: K): void {
+    const obj = this._cache.get(key);
+    if (obj) {
+      this._cache.delete(key);
+    }
+  }
+
+  size(): number {
+    return this._cache.size;
+  }
+
+  clear(): void {
+    this._cache.clear();
+  }
+}

package/src/context/context.test.ts

@@ -0,0 +1,17 @@
+import { makeEntryContext, makeUserInputContext } from './context';
+
+describe('context', () => {
+  it('bind', () => {
+    const context = makeEntryContext();
+    expect(context.getValue('lvweb')).toBeUndefined();
+    context.setValue('lvweb', true);
+    expect(context.getValue('lvweb')).toBeTruthy();
+  });
+
+  it('background', () => {
+    const context = makeUserInputContext();
+    context.setValue('lvweb', true);
+    const newContext = context.background();
+    expect(newContext.getValue('lvweb')).toBeUndefined();
+  });
+});

package/src/context/context.ts

@@ -0,0 +1,60 @@
+/**
+ * Context类型
+ */
+export enum ContextType {
+  // 入口
+  Entry,
+  // 事件
+  Event,
+  // 用户
+  UserInput,
+  // 自定义任务
+  Task,
+}
+
+export class Context {
+  private readonly _store = new Map<string, any>();
+
+  constructor(public readonly type: ContextType = ContextType.Task) {}
+
+  /**
+   * 获取一个纯粹的上下文
+   */
+  background() {
+    return new Context(this.type);
+  }
+
+  /**
+   * 绑定信息
+   */
+  setValue<T>(key: string, value: T) {
+    this._store.set(key, value);
+  }
+
+  /**
+   * 获取信息
+   */
+  getValue<T>(key: string) {
+    return this._store.get(key) as T | undefined;
+  }
+}
+
+export function makeEntryContext() {
+  return new Context(ContextType.Entry);
+}
+
+export function makeEventContext() {
+  return new Context(ContextType.Event);
+}
+
+export function makeUserInputContext() {
+  return new Context(ContextType.UserInput);
+}
+
+export function makeTaskContext() {
+  return new Context(ContextType.Task);
+}
+
+export function makeContext() {
+  return new Context();
+}

package/src/context/index.ts

@@ -0,0 +1,8 @@
+export { Context, ContextType } from './context';
+export {
+  makeEntryContext,
+  makeEventContext,
+  makeUserInputContext,
+  makeTaskContext,
+  makeContext,
+} from './context';

package/src/di/base.ts

@@ -0,0 +1,73 @@
+// service特征标识
+export type BrandedService = { _serviceBrand: undefined };
+
+//
+// 服务唯一标识符（编译时生成）
+// 需要DI进行注入的服务必须拥有该标识符
+// 本质上是一个参数装饰器
+//
+export interface ServiceIdentifier<T> {
+  (...args: any[]): void;
+  type: T;
+}
+
+// 获取服务的视图接口
+export interface ServicesAccessor {
+  get: <T>(id: ServiceIdentifier<T>) => T;
+}
+
+// 服务唯一标识符存储
+const serviceIds = new Map<string, ServiceIdentifier<any>>();
+
+export const DI_TARGET = '$di$target';
+export const DI_DEPENDENCIES = '$di$dependencies';
+
+// 获取某个服务的依赖
+// 因为服务依赖关系会存放在构造函数的属性上
+export function getServiceDependencies(ctor: any): { id: ServiceIdentifier<any>; index: number }[] {
+  return ctor[DI_DEPENDENCIES] || [];
+}
+
+// 更新服务依赖依赖关系
+function setServiceDependency(id: ServiceIdentifier<any>, ctor: any, index: number): void {
+  if (ctor[DI_TARGET] === ctor) {
+    ctor[DI_DEPENDENCIES].push({ id, index });
+  } else {
+    ctor[DI_DEPENDENCIES] = [{ id, index }];
+    ctor[DI_TARGET] = ctor;
+  }
+}
+
+//
+// 创建服务唯一标识符
+// 传入服务ID，返回一个参数装饰器
+// 参数装饰器会记录A需要
+//   const IFooServiceId = createDecorator<FooService>('FooService');
+//
+//   class Bar
+//     constructor(@IFooServiceId a: IFooService)  // IFooService是接口声明
+//
+export function createDecorator<T>(serviceId: string): ServiceIdentifier<T> {
+  if (serviceIds.has(serviceId)) {
+    return serviceIds.get(serviceId)!;
+  }
+
+  const id = function (target: any, key: string, index: number): any {
+    if (arguments.length !== 3) {
+      throw new Error('@IServiceName-decorator can only be used to decorate a parameter');
+    }
+    setServiceDependency(id, target, index);
+  } as any;
+
+  id.toString = () => serviceId;
+
+  serviceIds.set(serviceId, id);
+  return id;
+}
+
+// TODO(niurouwan): 补一下注释和例子
+export function refineServiceDecorator<T1, T extends T1>(
+  serviceIdentifier: ServiceIdentifier<T1>,
+): ServiceIdentifier<T> {
+  return serviceIdentifier as ServiceIdentifier<T>;
+}

package/src/di/container-service.test.ts

@@ -0,0 +1,179 @@
+import { createDecorator } from './base';
+import { InstantiationService as ContainerService, InstantiationService } from './instantiation-service';
+import { ServiceOwnership } from './service-ownership-collection';
+import { ServiceRegistry } from './service-registry';
+
+/**
+ * 存在dispose的service1
+ */
+class MockService1 {
+  readonly _serviceBrand: undefined;
+
+  constructor(private readonly _fn: () => void) {}
+
+  dispose() {
+    this._fn();
+  }
+}
+const IMockService1 = createDecorator<MockService1>('MockService1');
+
+/**
+ * 存在dispose的service2
+ */
+class MockService2 {
+  readonly _serviceBrand: undefined;
+
+  constructor(private readonly _fn: () => void) {}
+
+  dispose() {
+    this._fn();
+  }
+}
+const IMockService2 = createDecorator<MockService2>('MockService2');
+
+/**
+ * 不存在dispose的service
+ */
+class MockService3 {
+  readonly _serviceBrand: undefined;
+
+  constructor(private readonly _fn: () => void) {}
+}
+const IMockService3 = createDecorator<MockService3>('MockService3');
+
+/**
+ * reference service
+ */
+class MockService4 {
+  readonly _serviceBrand: undefined;
+
+  constructor(private readonly _fn: () => void) {}
+
+  dispose() {
+    this._fn();
+  }
+}
+const IMockService4 = createDecorator<MockService4>('MockService4');
+
+describe('ContainerService', () => {
+  // 单层的dispose
+  it('dispose1', () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    const fn3 = vi.fn();
+
+    const registry = new ServiceRegistry();
+    registry.registerInstance(IMockService1, new MockService1(fn1));
+    registry.registerInstance(IMockService2, new MockService2(fn2));
+    registry.registerInstance(IMockService3, new MockService3(fn3));
+    const containerService = new ContainerService(registry.makeCollection());
+    containerService.dispose();
+
+    expect(fn1).toBeCalled();
+    expect(fn2).toBeCalled();
+    expect(fn3).not.toBeCalled();
+  });
+
+  // 双层的dispose，一起销毁
+  it('dispose2', () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    const fn3 = vi.fn();
+
+    const registry1 = new ServiceRegistry();
+    registry1.registerInstance(IMockService1, new MockService1(fn1));
+    const containerService = new ContainerService(registry1.makeCollection());
+
+    const registry2 = new ServiceRegistry();
+    registry2.registerInstance(IMockService2, new MockService2(fn2));
+    registry2.registerInstance(IMockService3, new MockService3(fn3));
+    const childContainerService = new ContainerService(registry2.makeCollection(), containerService);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(containerService['_childs'].has(childContainerService)).toBeTruthy();
+
+    containerService.dispose();
+
+    expect(fn1).toBeCalled();
+    expect(fn2).toBeCalled();
+    expect(fn3).not.toBeCalled();
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(containerService['_childs'].has(childContainerService)).toBeFalsy();
+  });
+
+  // 双层的dispose，只销毁下一层
+  it('dispose3', () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    const fn3 = vi.fn();
+
+    const registry1 = new ServiceRegistry();
+    registry1.registerInstance(IMockService1, new MockService1(fn1));
+    const containerService = new ContainerService(registry1.makeCollection());
+
+    const registry2 = new ServiceRegistry();
+    registry2.registerInstance(IMockService2, new MockService2(fn2));
+    registry2.registerInstance(IMockService3, new MockService3(fn3));
+    const childContainerService = new ContainerService(registry2.makeCollection(), containerService);
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(containerService['_childs'].has(childContainerService)).toBeTruthy();
+
+    childContainerService.dispose();
+
+    expect(fn1).not.toBeCalled();
+    expect(fn2).toBeCalled();
+    expect(fn3).not.toBeCalled();
+    // eslint-disable-next-line dot-notation, @typescript-eslint/dot-notation
+    expect(containerService['_childs'].has(childContainerService)).toBeFalsy();
+  });
+
+  // parent是instantiationService，正常dispose
+  it('dispose4', () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    const fn3 = vi.fn();
+
+    const registry1 = new ServiceRegistry();
+    registry1.registerInstance(IMockService1, new MockService1(fn1));
+    const instantiationService = new InstantiationService(registry1.makeCollection());
+
+    const registry2 = new ServiceRegistry();
+    registry2.registerInstance(IMockService2, new MockService2(fn2));
+    registry2.registerInstance(IMockService3, new MockService3(fn3));
+    const containerService = new ContainerService(registry2.makeCollection(), instantiationService);
+
+    containerService.dispose();
+
+    expect(fn1).not.toBeCalled();
+    expect(fn2).toBeCalled();
+    expect(fn3).not.toBeCalled();
+  });
+
+  // reference dispose
+  it('reference dispose', () => {
+    const fn1 = vi.fn();
+    const fn2 = vi.fn();
+    const fn4 = vi.fn();
+
+    const mock4Instance = new MockService4(fn4);
+    const registry1 = new ServiceRegistry();
+    registry1.registerInstance(IMockService1, new MockService1(fn1));
+    registry1.registerInstance(IMockService4, mock4Instance);
+    const containerService = new ContainerService(registry1.makeCollection());
+
+    const registry2 = new ServiceRegistry();
+    registry2.registerInstance(IMockService2, new MockService2(fn2));
+    registry2.registerInstance(IMockService4, mock4Instance, {
+      ownership: ServiceOwnership.Reference,
+    });
+    const childContainerService = new ContainerService(registry2.makeCollection(), containerService);
+    childContainerService.dispose();
+
+    expect(fn1).not.toBeCalled();
+    expect(fn2).toBeCalled();
+    expect(fn4).not.toBeCalled();
+
+    containerService.dispose();
+    expect(fn1).toBeCalled();
+    expect(fn4).toBeCalled();
+  });
+});

package/src/di/context.web.tsx

@@ -0,0 +1,41 @@
+import { createContext, createElement, useContext, useMemo, type ReactElement } from 'react';
+import { lvAssertNotNil } from '@/assert';
+import type { IInstantiationService } from './instantiation-service.interface';
+import type { ServiceIdentifier, ServicesAccessor } from './base';
+
+interface IProps {
+  instantiationService: IInstantiationService;
+  children?: React.ReactNode;
+}
+
+const Context = createContext<IInstantiationService | null>(null);
+
+/**
+ * 组件支持依赖注入上下文
+ */
+export const InstantiationContext = (props: IProps) => {
+  return createElement(
+    Context.Provider,
+    { value: props.instantiationService },
+    props.children,
+  ) as ReactElement<any, any>;
+};
+
+/**
+ * 获取服务的hook
+ * @param identifier 服务标识符
+ * @returns 对应服务
+ */
+export function useService<T>(identifier: ServiceIdentifier<T>): T {
+  const instantiationService = useContext(Context);
+  lvAssertNotNil(instantiationService, 'react components need service context.');
+  const service = useMemo(
+    () =>
+      instantiationService.invokeFunction((servicesAccessor: ServicesAccessor) =>
+        servicesAccessor.get(identifier),
+      ),
+    [instantiationService, identifier],
+  );
+
+  return service;
+}

package/src/di/descriptor.ts

@@ -0,0 +1,31 @@
+//
+// DI中服务描述符，本质上是构造函数的包装
+//
+// 必须提供服务构造函数
+// 支持静态参数
+// 支持配置是否延迟初始化
+//
+export class SyncDescriptor<T> {
+  readonly ctor: new (...args: any[]) => T;
+  readonly staticArguments: any[];
+  readonly supportsDelayedInstantiation: boolean;
+
+  constructor(
+    ctor: new (...args: any[]) => T,
+    staticArguments: any[] = [],
+    supportsDelayedInstantiation = false,
+  ) {
+    this.ctor = ctor;
+    this.staticArguments = staticArguments;
+    this.supportsDelayedInstantiation = supportsDelayedInstantiation;
+  }
+}
+
+//
+// 特化描述符
+// 1. 没有静态参数，没有动态参数，只存在注入参数
+// 2. 默认延迟初始化
+//
+export interface SyncDescriptor0<T> {
+  readonly ctor: new () => T;
+}

package/src/di/idle-value.test.ts

@@ -0,0 +1,73 @@
+import { sleep } from '@/async';
+import { IdleValue } from './idle-value';
+
+class Foo {
+  value = 'public value.';
+
+  private _data = 100;
+  private readonly _mockFn: () => void;
+
+  constructor(mockFn: () => void) {
+    this._mockFn = mockFn;
+  }
+
+  get data() {
+    return this._data;
+  }
+
+  set data(value: number) {
+    this._data = value;
+  }
+
+  test() {
+    this._mockFn();
+  }
+}
+
+describe('idle value', () => {
+  it('initializes during idle time', async () => {
+    const fn = vi.fn();
+    const wrapper = new IdleValue<Foo>(() => new Foo(fn));
+    // Not initialized immediately
+    expect(wrapper.isInitialized).toBe(false);
+
+    expect(fn).not.toBeCalled();
+    expect(wrapper.isInitialized).toBe(false);
+
+    await sleep(500);
+
+    // Must have been initialized asynchronously
+    expect(wrapper.isInitialized).toBe(true);
+
+    // Properties work normally
+    expect(wrapper.value.value).toBe('public value.');
+    // Setters/getters work normally
+    expect(wrapper.value.data).toBe(100);
+    wrapper.value.data = 200;
+    expect(wrapper.value.data).toBe(200);
+    // Method calls work normally
+    wrapper.value.test();
+    expect(fn).toBeCalled();
+  });
+
+  it('initializes immediately due to usage', () => {
+    const fn = vi.fn();
+    const wrapper = new IdleValue<Foo>(() => new Foo(fn));
+    // Not initialized immediately
+    expect(wrapper.isInitialized).toBe(false);
+
+    // Properties work normally
+    expect(wrapper.value.value).toBe('public value.');
+    // Setters/getters work normally
+    expect(wrapper.value.data).toBe(100);
+    wrapper.value.data = 200;
+    expect(wrapper.value.data).toBe(200);
+    // Method calls work normally
+    wrapper.value.test();
+    expect(fn).toBeCalled();
+
+    // Initialized because value was accessed
+    expect(wrapper.isInitialized).toBe(true);
+    // await sleep(500);
+  });
+});