rockbed 0.1.0

package/src/dispose/disposable-t.ts

@@ -0,0 +1,85 @@
+import { DisposableStore } from './disposable-store';
+import type { IDisposable } from './dispose-base';
+import { BRANCH_DISPOSE } from './logger';
+
+//
+// Disposable基类
+//
+// 自动添加DisposableStore，提供默认的dispose和register方法
+//
+export abstract class Disposable implements IDisposable {
+  protected readonly _store = new DisposableStore();
+
+  // 销毁该节点和所有的子节点
+  dispose(): void {
+    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);
+  }
+}
+
+export class MutableDisposable<T extends IDisposable> implements IDisposable {
+  private _value?: T;
+  private _isDisposed = false;
+
+  constructor(value?: T) {
+    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();
+    this._value = value;
+  }
+
+  clear(): void {
+    this.value = undefined;
+  }
+
+  dispose(): void {
+    this._isDisposed = true;
+    this._value?.dispose();
+    this._value = undefined;
+  }
+
+  release(): T | undefined {
+    const oldValue = this._value;
+    this._value = undefined;
+    return oldValue;
+  }
+}
+
+export class SafeDisposable<T extends IDisposable> implements IDisposable {
+  private _value: T | null = null;
+
+  constructor(value: T) {
+    this._value = value;
+  }
+
+  isEmpty() {
+    return this._value === null;
+  }
+
+  dispose() {
+    if (!this._value) {
+      return;
+    }
+    this._value.dispose();
+    this._value = null;
+  }
+}

package/src/dispose/disposable-utils.ts

@@ -0,0 +1,13 @@
+import { SafeDisposable } from './disposable-t';
+import { EmptyDispose } from './dispose-base';
+
+export function makeSafeDisposable(fn: (...args: any) => any) {
+  const disposable = new SafeDisposable({
+    dispose: fn,
+  });
+  return disposable;
+}
+
+export function makeEmptyDisposable() {
+  return EmptyDispose;
+}

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,8 @@
+export type { IDisposable } from './dispose-base';
+export { EmptyDispose } from './dispose-base';
+export { DisposableStore } from './disposable-store';
+export { Disposable, MutableDisposable, SafeDisposable } from './disposable-t';
+export { makeSafeDisposable } from './disposable-utils';
+export { makeEmptyDisposable } from './disposable-utils';
+export { disposeWithLog } from './logger';
+export type { IDisposableLogger } from './logger';

package/src/dispose/logger.ts

@@ -0,0 +1,41 @@
+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 {
+      // console.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/error/error-base.ts

@@ -0,0 +1,39 @@
+//
+// lv项目中使用的错误类型
+//
+
+export const ILvErrorRef = Symbol.for('rockbed.ILvErrorRef');
+export type ILvErrorRef = ILvErrorOr<never>;
+
+export const ILvRealErrorRef = Symbol.for('rockbed.ILvRealErrorRef');
+export interface ILvRealErrorRef {
+  readonly ok: false;
+  readonly code: number;
+  readonly msg: string;
+  readonly cause?: ILvErrorRef | Error;
+  readonly toString: () => string;
+  readonly pair: () => [ILvRealErrorRef, null];
+  readonly errorInfo?: unknown;
+}
+
+//
+// 没有错误时，可以直接使用 value 字段
+//
+export const ILvValueRef = Symbol.for('rockbed.ILvValueRef');
+export interface ILvValueRef<T> {
+  readonly ok: true;
+  readonly code: 0;
+  readonly msg: '';
+  readonly cause?: undefined;
+  readonly value: T;
+  readonly toString: () => string;
+  readonly pair: () => [null, T];
+}
+
+//
+// lv项目中使用的携带值可能错误类型
+//
+export const ILvErrorOr = Symbol.for('rockbed.ILvErrorOr');
+export type ILvErrorOr<T> = (ILvRealErrorRef | ILvValueRef<T>) & {
+  readonly pair: () => [null, T] | [ILvRealErrorRef, null];
+};

package/src/error/error-code.ts

@@ -0,0 +1,48 @@
+import { lvErrorConst } from './error-const';
+
+/**
+ * 提供了通用的错误码(+1至+256)
+ *
+ * 注意：这里只是提供了通用的错误码，方便服务使用，但并不是要求服务一定使用如下的错误码来表明某种错误
+ */
+export enum GenericError {
+  Ok = 0,
+  Cancelled = 1, // 操作被取消
+  TimedOut = 2, // 操作超时
+  PermissionDenied = 3, // 无权限
+  AlreadyExists = 4, // 已经存在(文件/记录等)
+  NotSupported = 5, // 操作不支持
+  ResourceUnavailable = 6, // 资源不可用
+  OutOfRange = 7, // (参数/结果等)发生越界
+  InvalidArgument = 8, // 无效参数
+  NetworkFailed = 9, // 网络失败
+  Interrupted = 10, // 操作被中断(捕获异常转为错误)
+  ResultNil = 11, // 结果不存在(null or undefined转为错误)
+}
+
+/**
+ * 通用错误码所对应的编译时常量对象(ErrorConst)
+ */
+export const cancelledError = lvErrorConst(GenericError.Cancelled, 'operation(s) cancelled.');
+export const timeoutError = lvErrorConst(GenericError.TimedOut, 'operation(s) timed out.');
+export const permissionDeniedError = lvErrorConst(
+  GenericError.PermissionDenied,
+  'permission denied.',
+);
+export const alreadyExistsError = lvErrorConst(GenericError.AlreadyExists, 'already exists.');
+export const notSupportedError = lvErrorConst(
+  GenericError.NotSupported,
+  'operation(s) not supported.',
+);
+export const resourceUnavailableError = lvErrorConst(
+  GenericError.ResourceUnavailable,
+  'resource is unavailable.',
+);
+export const outOfRangeError = lvErrorConst(GenericError.OutOfRange, 'out of range.');
+export const invalidArgumentError = lvErrorConst(
+  GenericError.InvalidArgument,
+  'invalid arguments.',
+);
+export const networkFailedError = lvErrorConst(GenericError.NetworkFailed, 'network failed.');
+export const interruptedError = lvErrorConst(GenericError.Interrupted, 'interrupted.');
+export const resultNilError = lvErrorConst(GenericError.ResultNil, 'result is nil.');

package/src/error/error-const.ts

@@ -0,0 +1,16 @@
+import { makeError, makeErrorBy } from './error-t';
+
+//
+// Error编译时错误对象
+//
+export function lvErrorConst(code: number, msg: string) {
+  return (rewrite?: string | Error) => {
+    if (!rewrite) {
+      return makeError(code, msg);
+    }
+    if (typeof rewrite === 'string') {
+      return makeError(code, rewrite);
+    }
+    return makeErrorBy(code, rewrite.message, rewrite);
+  };
+}

package/src/error/error-or.ts

@@ -0,0 +1,2 @@
+// makeOkWith 依赖内部 lvErrorRefSymbol，先放到 error-t 里面实现，有需要再拆分
+export { makeOkWith } from './error-t';

package/src/error/error-t.ts

@@ -0,0 +1,93 @@
+import type { ILvErrorRef, ILvErrorOr, ILvRealErrorRef } from './error-base';
+
+//
+// Error类
+//
+// 用户给函数签名明确错误
+// function foo(): ILvErrorRef
+//   return makeOk();  // 如果没有错误
+//   return makeError(code, msg);  // 指定错误码和携带消息
+//
+//   const SomeError = LvErrorConst(code, msg);  // 更推荐用LvErrorConst生成
+//   return SomeError();
+//
+
+const lvErrorRefSymbol = Symbol('lvErrorRef');
+
+export function makeOk(): ILvErrorOr<never> {
+  return {
+    ok: true,
+    value: null!,
+    pair() {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return [null, null!] as any;
+    },
+    code: 0,
+    msg: '',
+    ...{ [lvErrorRefSymbol]: true }, // 跳过类型检测
+  };
+}
+
+export function makeOkWith<T>(value: T): ILvErrorOr<T> {
+  return {
+    ok: true,
+    value,
+    pair() {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+      return [null, value] as any;
+    },
+    code: 0,
+    msg: '',
+    ...{ [lvErrorRefSymbol]: true }, // 跳过类型检测
+  };
+}
+
+function printCause(cause: ILvErrorRef | Error | undefined): string {
+  if (cause === undefined) {
+    return '';
+  } else if (cause instanceof Error) {
+    return `\ncaused by [jsError]${cause.name}-${cause.message}`;
+  } else {
+    return `\ncaused by [${cause.code}]${cause.msg}${cause.ok ? '' : printCause(cause.cause)}`;
+  }
+}
+
+function internalMakeError(
+  code: number,
+  msg: string,
+  cause?: ILvErrorRef | Error,
+  errorInfo?: unknown,
+) {
+  const errorRef: ILvRealErrorRef = {
+    ok: false,
+    code,
+    msg,
+    cause,
+    errorInfo,
+    toString() {
+      return `[${code}]${msg}.${cause ? printCause(cause) : ''}`;
+    },
+    pair() {
+      return [errorRef, null];
+    },
+    ...{ [lvErrorRefSymbol]: true }, // 跳过类型检测
+  };
+  return errorRef;
+}
+
+export function makeError(code: number, msg: string, errorInfo?: unknown): ILvRealErrorRef {
+  return internalMakeError(code, msg, undefined, errorInfo);
+}
+
+export function makeErrorBy(
+  code: number,
+  msg: string,
+  cause: ILvErrorRef | Error,
+  errorInfo?: unknown,
+): ILvRealErrorRef {
+  return internalMakeError(code, msg, cause, errorInfo);
+}
+
+export function isLvErrorRef(val: unknown): val is ILvErrorRef {
+  return typeof val === 'object' && val !== null && lvErrorRefSymbol in val;
+}

package/src/error/index.ts

@@ -0,0 +1,5 @@
+export * from './error-base';
+export * from './error-const';
+export * from './error-or';
+export * from './error-t';
+export * from './error-code';

package/src/event/emitter.ts

@@ -0,0 +1,193 @@
+/* eslint-disable @typescript-eslint/no-redundant-type-constituents */
+import { makeSafeDisposable } from '../dispose';
+import type { IDisposable } from '../dispose';
+
+export interface EmitterOptions {
+  onAddListener?: (...args: any) => any;
+  onRemoveListener?: (...args: any) => any;
+  onListenerError?: (e: any) => void;
+}
+
+/**
+ * 默认错误处理：异步抛出监听器错误，避免阻塞当前事件分发。
+ */
+export function asyncUnexpectedErrorHandler(e: unknown): undefined {
+  setTimeout(() => {
+    throw e;
+  }, 0);
+}
+
+/**
+ * 同步抛出监听器错误，适合测试或需要立即失败的场景。
+ */
+export function syncUnexpectedError(e: unknown): undefined {
+  throw e;
+}
+
+/**
+ * 忽略监听器错误，适合明确允许 best-effort 通知的场景。
+ */
+export function ignoreUnexpectedError(_e: unknown): undefined {}
+
+//
+// 事件监听中的回调实体
+//
+class Listener<TArgs extends any[]> {
+  private readonly _callback: (...args: TArgs) => void;
+  private readonly _callbackThis: any | undefined;
+
+  constructor(callback: (...args: TArgs) => void, callbackThis: any | undefined) {
+    this._callback = callback;
+    this._callbackThis = callbackThis;
+  }
+
+  invoke(...args: TArgs): void {
+    this._callback.call(this._callbackThis, ...args);
+  }
+}
+
+//
+// 存放在EventDeliveryQueue中的元素
+//
+class EventDeliveryQueueElement<TArgs extends any[]> {
+  readonly emitter: Emitter<TArgs>;
+  readonly listener: Listener<TArgs>;
+  readonly event: TArgs;
+  constructor(emitter: Emitter<TArgs>, listener: Listener<TArgs>, event: TArgs) {
+    this.emitter = emitter;
+    this.listener = listener;
+    this.event = event;
+  }
+}
+
+export class EventDeliveryQueue {
+  protected _queue: EventDeliveryQueueElement<any>[] = [];
+
+  constructor(
+    private readonly _onListenerError: (e: unknown) => void = asyncUnexpectedErrorHandler,
+  ) {}
+
+  get size(): number {
+    return this._queue.length;
+  }
+
+  push<TArgs extends any[]>(
+    emitter: Emitter<TArgs>,
+    listener: Listener<TArgs>,
+    event: TArgs,
+  ): void {
+    this._queue.push(new EventDeliveryQueueElement(emitter, listener, event));
+  }
+
+  clear<TArgs extends any[]>(emitter: Emitter<TArgs>): void {
+    this._queue = this._queue.filter((element) => element.emitter !== emitter);
+  }
+
+  deliver(): void {
+    while (this._queue.length > 0) {
+      const element = this._queue.shift()!;
+      try {
+        element.listener.invoke(...element.event);
+      } catch (e) {
+        this._onListenerError(e);
+      }
+    }
+  }
+}
+
+export interface Event<T extends any[]> {
+  (listener: (...args: T) => any, thisArgs?: any): IDisposable;
+}
+
+export class Emitter<TArgs extends any[]> {
+  protected _listeners?: Set<Listener<TArgs>>;
+  private readonly _options?: EmitterOptions;
+  private _disposed = false;
+  private _event?: Event<TArgs>;
+  private _deliveryQueue?: EventDeliveryQueue;
+
+  constructor(options?: EmitterOptions) {
+    this._options = options;
+  }
+
+  get event(): Event<TArgs> {
+    if (this._event) {
+      return this._event;
+    }
+
+    this._event = (callback: (...args: TArgs) => any, thisArgs?: any): IDisposable => {
+      if (!this._listeners) {
+        this._listeners = new Set();
+      }
+
+      const listener = new Listener(callback, thisArgs);
+      this._listeners.add(listener);
+
+      if (this._options?.onAddListener) {
+        this._options.onAddListener(this, callback, thisArgs);
+      }
+
+      // 生成可销毁函数返回
+      const result = () => {
+        if (!this._disposed) {
+          this._listeners?.delete(listener);
+          if (this._options?.onRemoveListener) {
+            this._options.onRemoveListener(this, callback, thisArgs);
+          }
+        }
+      };
+
+      return makeSafeDisposable(result);
+    };
+
+    return this._event;
+  }
+
+  dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+    this._disposed = true;
+    this._listeners?.clear();
+    this._deliveryQueue?.clear(this);
+  }
+
+  fire(...event: TArgs): void {
+    if (!this._listeners) {
+      return;
+    }
+    this._deliveryQueue ??= new EventDeliveryQueue(this._options?.onListenerError);
+
+    for (const listener of this._listeners) {
+      this._deliveryQueue.push(this, listener, event);
+    }
+    this._deliveryQueue.deliver();
+  }
+}
+
+// 辅助能力：只监听某个事件一次
+export function listenOnce<TArgs extends any[]>(event: Event<TArgs>): Event<TArgs> {
+  return (listener, thisArgs = null) => {
+    let didFire = false;
+    let result: IDisposable | undefined = undefined;
+
+    result = event((...args) => {
+      if (didFire) {
+        return;
+      }
+      if (result) {
+        result.dispose();
+      } else {
+        didFire = true;
+      }
+
+      return listener.call(thisArgs, ...args);
+    }, null);
+
+    if (didFire) {
+      result.dispose();
+    }
+
+    return result;
+  };
+}

package/src/event/index.ts

@@ -0,0 +1,10 @@
+// 事件相关能力
+export {
+  Emitter,
+  EventDeliveryQueue,
+  asyncUnexpectedErrorHandler,
+  ignoreUnexpectedError,
+  listenOnce,
+  syncUnexpectedError,
+} from './emitter';
+export type { EmitterOptions, Event } from './emitter';

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './assert';
+export * from './async';
+export * from './dispose';
+export * from './error';
+export * from './event';
+export * from './json';
+export * from './lock';
+export * from './response';

package/src/json/index.ts

@@ -0,0 +1 @@
+export * from './json';

package/src/json/json.ts

@@ -0,0 +1,15 @@
+export function safeJsonParse<T>(value: string): T {
+  try {
+    return JSON.parse(value);
+  } catch (error) {
+    return {} as T;
+  }
+}
+
+export function safeJsonStringify<T>(value: T): string {
+  try {
+    return JSON.stringify(value);
+  } catch (error) {
+    return '{}';
+  }
+}

package/src/lock/README.md

@@ -0,0 +1,11 @@
+# 读写锁
+TODO(niurouwan): 补上
+
+## 核心
+- 写写互斥、读写互斥，读读可重入  
+- 写者优先于读者  
+- 写者唤醒顺序按调用顺序来  
+
+## 实现原理
+
+## 使用举例