rockbed 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# rockbed
+
+`rockbed` is a small TypeScript utility package extracted from `template-commander/src/bedrock`.
+It keeps only the core primitives that are useful across projects.
+
+The package is designed for subpath imports:
+
+```ts
+import { ILvErrorOr, makeOkWith, makeError } from 'rockbed/error';
+import { Emitter } from 'rockbed/event';
+```
+
+## Module Map
+
+| Import path | Main exports | Use it for |
+| --- | --- | --- |
+| `rockbed/assert` | `lvAssert`, `lvAssertNotNil`, `lvAssertNever`, `lvAssertNotHere` | Runtime invariants and TypeScript narrowing. |
+| `rockbed/async` | `wait`, `Barrier`, `makeBarrierByPromise`, `defer`, `makeCancelablePromise`, `parallelPromise`, `makePromiseWithTimeout`, `CancellationTokenSource` | Timers, promise coordination, cancellation-aware promise helpers. |
+| `rockbed/dispose` | `IDisposable`, `Disposable`, `DisposableStore`, `MutableDisposable`, `SafeDisposable`, `makeSafeDisposable`, `disposeWithLog` | Ownership and cleanup of resources or subscriptions. |
+| `rockbed/error` | `ILvErrorOr<T>`, `ILvErrorRef`, `makeOk`, `makeOkWith`, `makeError`, `makeErrorBy`, `lvErrorConst`, `isLvErrorRef`, `GenericError` | Typed result objects instead of throwing for expected failures. |
+| `rockbed/event` | `Emitter`, `Event`, `listenOnce`, listener error handlers | Lightweight typed event emitters that return disposables. |
+| `rockbed/json` | `safeJsonParse`, `safeJsonStringify` | JSON helpers that never throw. |
+| `rockbed/lock` | `SharedMutex` | Async read/write locking with writer priority. |
+| `rockbed/response` | `IResponse<T>`, `makeSuccessResponse`, `makeErrorResponse` | Simple `{ code, msg, data }` API response objects. |
+
+## Error Result Pattern
+
+`ILvErrorOr<T>` is the central result type.
+
+```ts
+import { ILvErrorOr, makeError, makeOkWith } from 'rockbed/error';
+
+function parsePort(value: string): ILvErrorOr<number> {
+  const port = Number(value);
+  if (!Number.isInteger(port)) {
+    return makeError(400, 'port must be an integer');
+  }
+  return makeOkWith(port);
+}
+
+const result = parsePort('8080');
+if (result.ok) {
+  console.log(result.value);
+} else {
+  console.error(result.code, result.msg);
+}
+```
+
+Every result also has `pair()` for tuple-style control flow:
+
+```ts
+const [err, value] = parsePort('8080').pair();
+if (err) {
+  throw new Error(err.toString());
+}
+console.log(value);
+```
+
+## Event Pattern
+
+`Emitter<TArgs>` produces an `Event<TArgs>`. Subscribing returns `IDisposable`.
+
+```ts
+import { Emitter, listenOnce } from 'rockbed/event';
+
+const emitter = new Emitter<[message: string]>();
+const subscription = emitter.event((message) => console.log(message));
+
+emitter.fire('ready');
+subscription.dispose();
+
+listenOnce(emitter.event)((message) => console.log('only once', message));
+```
+
+## Dispose Pattern
+
+Use `DisposableStore` when one owner needs to clean up multiple resources.
+Use `Disposable` as a base class when a class owns a store.
+
+```ts
+import { Disposable, makeSafeDisposable } from 'rockbed/dispose';
+
+class Session extends Disposable {
+  start() {
+    this._register(makeSafeDisposable(() => console.log('cleanup')));
+  }
+}
+```
+
+## Async Pattern
+
+```ts
+import { Barrier, makePromiseWithTimeout, wait } from 'rockbed/async';
+
+await wait(100);
+
+const barrier = new Barrier();
+queueMicrotask(() => barrier.open());
+await barrier.wait();
+
+const result = await makePromiseWithTimeout(async (token) => {
+  if (token.isCancellationRequested) {
+    return 'cancelled';
+  }
+  return 'done';
+}, 1000);
+```
+
+## Lock Pattern
+
+`SharedMutex` supports exclusive writes and shared reads.
+
+```ts
+import { SharedMutex } from 'rockbed/lock';
+
+const mutex = new SharedMutex();
+
+await mutex.lock();
+try {
+  // write
+} finally {
+  mutex.unlock();
+}
+
+await mutex.lockShared();
+try {
+  // read
+} finally {
+  mutex.unlockShared();
+}
+```
+
+## Publishing
+
+```sh
+npm install
+npm run typecheck
+npm run build
+npm publish --registry=https://registry.npmjs.org
+```
+
+The npm package includes `dist`, `src`, and this README. Keeping source files in the published
+package makes the available primitives easier for humans and AI coding agents to inspect.

package/dist/assert/index.d.ts

@@ -0,0 +1,6 @@
+declare function lvAssert(expr: unknown, reason?: string): asserts expr;
+declare function lvAssertNotHere(reason?: string): never;
+declare function lvAssertNever(member: never, message?: string): never;
+declare function lvAssertNotNil<T>(val: T, reason?: string): asserts val is NonNullable<T>;
+
+export { lvAssert, lvAssertNever, lvAssertNotHere, lvAssertNotNil };

package/dist/assert/index.js

@@ -0,0 +1,27 @@
+// src/assert/assert.ts
+function abort(reason) {
+  throw new Error(`lvAssert(${reason})`);
+}
+function lvAssert(expr, reason) {
+  if (!expr) {
+    abort(reason ?? "#expr is false");
+  }
+}
+function lvAssertNotHere(reason) {
+  abort(reason ?? "unreachable code flow");
+}
+function lvAssertNever(member, message = "Illegal value:") {
+  abort(`${message}: ${member}`);
+}
+function lvAssertNotNil(val, reason) {
+  if (val === null || val === void 0) {
+    abort(reason ?? "#val is nil");
+  }
+}
+export {
+  lvAssert,
+  lvAssertNever,
+  lvAssertNotHere,
+  lvAssertNotNil
+};
+//# sourceMappingURL=index.js.map

package/dist/assert/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/assert/assert.ts"],"sourcesContent":["function abort(reason: string): never {\n  throw new Error(`lvAssert(${reason})`);\n}\n\nexport function lvAssert(expr: unknown, reason?: string): asserts expr {\n  if (!expr) {\n    abort(reason ?? '#expr is false');\n  }\n}\n\nexport function lvAssertNotHere(reason?: string): never {\n  abort(reason ?? 'unreachable code flow');\n}\n\nexport function lvAssertNever(member: never, message = 'Illegal value:'): never {\n  // eslint-disable-next-line @typescript-eslint/restrict-template-expressions\n  abort(`${message}: ${member}`);\n}\n\nexport function lvAssertNotNil<T>(val: T, reason?: string): asserts val is NonNullable<T> {\n  if (val === null || val === undefined) {\n    abort(reason ?? '#val is nil');\n  }\n}\n"],"mappings":";AAAA,SAAS,MAAM,QAAuB;AACpC,QAAM,IAAI,MAAM,YAAY,MAAM,GAAG;AACvC;AAEO,SAAS,SAAS,MAAe,QAA+B;AACrE,MAAI,CAAC,MAAM;AACT,UAAM,UAAU,gBAAgB;AAAA,EAClC;AACF;AAEO,SAAS,gBAAgB,QAAwB;AACtD,QAAM,UAAU,uBAAuB;AACzC;AAEO,SAAS,cAAc,QAAe,UAAU,kBAAyB;AAE9E,QAAM,GAAG,OAAO,KAAK,MAAM,EAAE;AAC/B;AAEO,SAAS,eAAkB,KAAQ,QAAgD;AACxF,MAAI,QAAQ,QAAQ,QAAQ,QAAW;AACrC,UAAM,UAAU,aAAa;AAAA,EAC/B;AACF;","names":[]}

package/dist/async/index.d.ts

@@ -0,0 +1,105 @@
+import { I as ILvErrorOr, a as ILvErrorRef } from '../error-base-BWuBlS2k.js';
+import { I as IDisposable } from '../dispose-base-CAeXDpjg.js';
+
+interface ICancellationToken {
+    readonly isCancellationRequested: boolean;
+    readonly reason?: string;
+    readonly onCancellationRequested: (listener: () => any, thisArgs?: any) => IDisposable;
+}
+declare class CancellationToken {
+    static None: Readonly<ICancellationToken>;
+    static Cancelled: Readonly<ICancellationToken>;
+    static Make(reason: string): ICancellationToken;
+}
+declare class CancellationTokenSource implements IDisposable {
+    private _token?;
+    private _abortController?;
+    get token(): ICancellationToken;
+    get signal(): AbortSignal;
+    cancel(reason?: string): void;
+    dispose(cancel?: boolean): void;
+}
+/**
+ * 一般来说Promise常用的场景有：
+ * 1. 单次异步调用（new Promise）
+ * 2. 批量promise调用（Promise.all）
+ * 3. promise竞速调用（Promise.race）
+ *
+ * 但是原生能力有如下的缺陷
+ * 1. 不支持取消某一次promise调用
+ * 2. 不支持错误语义，promise.catch的重视程度比try catch还低
+ * 3. 超时行为需要基于race封装
+ *
+ * 针对这三点，基建侧提供了高阶的promise能力
+ * 1. makeCancelablePromise 返回一个可取消的promise
+ * const promise = makeCancelablePromise(() => { ... });
+ * promise.then((res) => {
+ *   // res是一个ILvErrorRef对象
+ * });
+ * // 可以直接取消promise
+ * promise.cancel();
+ *
+ * 2. parallelPromise 并发执行promise，会自动观测ILvErrorRef语义
+ * 当单个promise出现错误返回时，promise执行失败，尽可能调用所有cancelablePromise
+ * 当单个promise出现reject时，promise执行失败，尽可能调用所有cancelablePromise，并且将reject继续上抛
+ *
+ * 3. makePromiseWithTimeout 让promise支持超时，可以提供默认值
+ *
+ * ——————————————————
+ * Promise.allSettled和Promise.any在实际使用中场景较少，暂不提供错误语义包装
+ */
+interface CancelablePromise<T> extends Promise<T> {
+    cancel: () => void;
+}
+/**
+ * 快速生成一个CancelablePromise对象
+ */
+declare function makeCancelablePromise<T>(callback: (token: ICancellationToken) => Promise<T | ILvErrorOr<T>>): CancelablePromise<ILvErrorOr<T>>;
+/**
+ * 并行执行promise，当某一个失败，本次调用失败
+ * 本质上和Promise.all差不多，相比较之下
+ * 1. 包装了错误语义判断
+ * 2. 当失败时，会尽可能尝试cancel其他promise
+ *
+ * 注意：某一个promise失败时，会尽可能尝试调用其他promise的cancel，但不保证一定有效
+ * （有可能promiseA已经成功，但是primiseB在之后失败了）
+ */
+declare function parallelPromise(promiseList: Promise<any>[]): Promise<ILvErrorRef>;
+/**
+ * 包装一个promise，提供超时能力
+ */
+declare function makePromiseWithTimeout<T>(callback: (token: ICancellationToken) => Promise<T | ILvErrorOr<T>>, timeout: number, defaultValue?: T): Promise<ILvErrorOr<T>>;
+interface Deferred<T> {
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason: unknown) => void;
+    promise: Promise<T>;
+}
+declare function defer<T = void>(): Deferred<T>;
+
+/**
+ * 等待一段时间
+ * @param ms 单位毫秒
+ */
+declare function wait(ms: number): Promise<void>;
+
+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
+ */
+declare class Barrier {
+    private _isOpen;
+    private readonly _promise;
+    private _completePromise;
+    constructor();
+    isOpen(): boolean;
+    open(): void;
+    wait(): Promise<boolean>;
+}
+declare function makeBarrierByPromise(promise: Promise<any>, openWhenReject?: boolean): Barrier;
+
+export { Barrier, type CancelablePromise, CancellationToken, CancellationTokenSource, type Deferred, type IBarrier, type ICancellationToken, defer, makeBarrierByPromise, makeCancelablePromise, makePromiseWithTimeout, parallelPromise, wait };

package/dist/async/index.js

@@ -0,0 +1,380 @@
+// src/error/error-t.ts
+var lvErrorRefSymbol = /* @__PURE__ */ Symbol("lvErrorRef");
+function makeOk() {
+  return {
+    ok: true,
+    value: null,
+    pair() {
+      return [null, null];
+    },
+    code: 0,
+    msg: "",
+    ...{ [lvErrorRefSymbol]: true }
+    // 跳过类型检测
+  };
+}
+function makeOkWith(value) {
+  return {
+    ok: true,
+    value,
+    pair() {
+      return [null, value];
+    },
+    code: 0,
+    msg: "",
+    ...{ [lvErrorRefSymbol]: true }
+    // 跳过类型检测
+  };
+}
+function printCause(cause) {
+  if (cause === void 0) {
+    return "";
+  } else if (cause instanceof Error) {
+    return `
+caused by [jsError]${cause.name}-${cause.message}`;
+  } else {
+    return `
+caused by [${cause.code}]${cause.msg}${cause.ok ? "" : printCause(cause.cause)}`;
+  }
+}
+function internalMakeError(code, msg, cause, errorInfo) {
+  const errorRef = {
+    ok: false,
+    code,
+    msg,
+    cause,
+    errorInfo,
+    toString() {
+      return `[${code}]${msg}.${cause ? printCause(cause) : ""}`;
+    },
+    pair() {
+      return [errorRef, null];
+    },
+    ...{ [lvErrorRefSymbol]: true }
+    // 跳过类型检测
+  };
+  return errorRef;
+}
+function makeError(code, msg, errorInfo) {
+  return internalMakeError(code, msg, void 0, errorInfo);
+}
+function makeErrorBy(code, msg, cause, errorInfo) {
+  return internalMakeError(code, msg, cause, errorInfo);
+}
+function isLvErrorRef(val) {
+  return typeof val === "object" && val !== null && lvErrorRefSymbol in val;
+}
+
+// src/error/error-const.ts
+function lvErrorConst(code, msg) {
+  return (rewrite) => {
+    if (!rewrite) {
+      return makeError(code, msg);
+    }
+    if (typeof rewrite === "string") {
+      return makeError(code, rewrite);
+    }
+    return makeErrorBy(code, rewrite.message, rewrite);
+  };
+}
+
+// src/error/error-code.ts
+var cancelledError = lvErrorConst(1 /* Cancelled */, "operation(s) cancelled.");
+var timeoutError = lvErrorConst(2 /* TimedOut */, "operation(s) timed out.");
+var permissionDeniedError = lvErrorConst(
+  3 /* PermissionDenied */,
+  "permission denied."
+);
+var alreadyExistsError = lvErrorConst(4 /* AlreadyExists */, "already exists.");
+var notSupportedError = lvErrorConst(
+  5 /* NotSupported */,
+  "operation(s) not supported."
+);
+var resourceUnavailableError = lvErrorConst(
+  6 /* ResourceUnavailable */,
+  "resource is unavailable."
+);
+var outOfRangeError = lvErrorConst(7 /* OutOfRange */, "out of range.");
+var invalidArgumentError = lvErrorConst(
+  8 /* InvalidArgument */,
+  "invalid arguments."
+);
+var networkFailedError = lvErrorConst(9 /* NetworkFailed */, "network failed.");
+var interruptedError = lvErrorConst(10 /* Interrupted */, "interrupted.");
+var resultNilError = lvErrorConst(11 /* ResultNil */, "result is nil.");
+
+// src/dispose/dispose-base.ts
+var EmptyDispose = Object.freeze({ dispose() {
+} });
+
+// src/dispose/disposable-t.ts
+var SafeDisposable = class {
+  _value = null;
+  constructor(value) {
+    this._value = value;
+  }
+  isEmpty() {
+    return this._value === null;
+  }
+  dispose() {
+    if (!this._value) {
+      return;
+    }
+    this._value.dispose();
+    this._value = null;
+  }
+};
+
+// src/dispose/disposable-utils.ts
+function makeSafeDisposable(fn) {
+  const disposable = new SafeDisposable({
+    dispose: fn
+  });
+  return disposable;
+}
+
+// src/async/promise.ts
+var shortcutCancellationEvent = (callback, context) => {
+  const handle = setTimeout(callback.bind(context), 0);
+  return makeSafeDisposable(() => clearTimeout(handle));
+};
+var MutableToken = class {
+  _isCancelled = false;
+  _reason;
+  _listeners = /* @__PURE__ */ new Set();
+  get isCancellationRequested() {
+    return this._isCancelled;
+  }
+  get reason() {
+    return this._reason;
+  }
+  onCancellationRequested(listener, thisArgs) {
+    if (this._isCancelled) {
+      return shortcutCancellationEvent(listener, thisArgs);
+    }
+    const wrappedListener = listener.bind(thisArgs);
+    this._listeners.add(wrappedListener);
+    return makeSafeDisposable(() => {
+      this._listeners.delete(wrappedListener);
+    });
+  }
+  cancel(reason) {
+    if (this._isCancelled) {
+      return;
+    }
+    this._reason = reason;
+    this._isCancelled = true;
+    for (const listener of this._listeners) {
+      listener();
+    }
+    this._listeners.clear();
+  }
+  dispose() {
+    this._listeners.clear();
+  }
+};
+var CancellationToken = class {
+  static None = Object.freeze({
+    isCancellationRequested: false,
+    onCancellationRequested: () => EmptyDispose
+  });
+  static Cancelled = Object.freeze({
+    isCancellationRequested: true,
+    onCancellationRequested: shortcutCancellationEvent
+  });
+  static Make(reason) {
+    return Object.freeze({
+      isCancellationRequested: true,
+      onCancellationRequested: shortcutCancellationEvent,
+      reason
+    });
+  }
+};
+var CancellationTokenSource = class {
+  _token;
+  _abortController;
+  get token() {
+    if (!this._token) {
+      this._token = new MutableToken();
+    }
+    return this._token;
+  }
+  get signal() {
+    if (!this._abortController) {
+      this._abortController = new AbortController();
+    }
+    if (this._token?.isCancellationRequested) {
+      this._abortController.abort(this._token.reason);
+    }
+    return this._abortController.signal;
+  }
+  cancel(reason) {
+    if (!this._token) {
+      this._token = reason === void 0 ? CancellationToken.Cancelled : CancellationToken.Make(reason);
+    } else if (this._token instanceof MutableToken) {
+      this._token.cancel(reason);
+    }
+    this._abortController?.abort(reason);
+  }
+  dispose(cancel = false) {
+    if (cancel) {
+      this.cancel();
+    }
+    if (!this._token) {
+      this._token = CancellationToken.None;
+    } else if (this._token instanceof MutableToken) {
+      this._token.dispose();
+    }
+  }
+};
+function makeCancelablePromise(callback) {
+  const source = new CancellationTokenSource();
+  const thenable = callback(source.token);
+  const promise = new Promise((resolve, reject) => {
+    const subscription = source.token.onCancellationRequested(() => {
+      subscription.dispose();
+      source.dispose();
+      resolve(cancelledError());
+    });
+    Promise.resolve(thenable).then(
+      (value) => {
+        subscription.dispose();
+        source.dispose();
+        if (isLvErrorRef(value)) {
+          resolve(value);
+        } else {
+          resolve(makeOkWith(value));
+        }
+      },
+      (err) => {
+        subscription.dispose();
+        source.dispose();
+        reject(err);
+      }
+    );
+  });
+  return new class {
+    cancel() {
+      source.cancel();
+    }
+    then(resolve, reject) {
+      return promise.then(resolve, reject);
+    }
+    catch(reject) {
+      return this.then(void 0, reject);
+    }
+    finally(onfinally) {
+      return promise.finally(onfinally);
+    }
+  }();
+}
+function parallelPromise(promiseList) {
+  if (promiseList.length === 0) {
+    return Promise.resolve(makeOk());
+  }
+  let todo = promiseList.length;
+  const finish = () => {
+    todo = -1;
+    for (const promise of promiseList) {
+      promise.cancel?.();
+    }
+  };
+  return new Promise((resolve, reject) => {
+    for (const promise of promiseList) {
+      promise.then((res) => {
+        if (isLvErrorRef(res) && !res.ok) {
+          finish();
+          resolve(res);
+          return;
+        }
+        todo--;
+        if (todo === 0) {
+          resolve(makeOk());
+        }
+      }).catch((err) => {
+        finish();
+        reject(err);
+      });
+    }
+  });
+}
+function makePromiseWithTimeout(callback, timeout, defaultValue) {
+  const cancellable = makeCancelablePromise(callback);
+  const timer = setTimeout(() => {
+    cancellable.cancel();
+  }, timeout);
+  return cancellable.then((res) => {
+    clearTimeout(timer);
+    if (res.ok) {
+      return res;
+    }
+    if (res.code === 1 /* Cancelled */) {
+      if (defaultValue !== void 0) {
+        return makeOkWith(defaultValue);
+      }
+      return timeoutError();
+    } else {
+      return res;
+    }
+  });
+}
+function defer() {
+  let resolve;
+  let reject;
+  const promise = new Promise((_resolve, _reject) => {
+    resolve = _resolve;
+    reject = _reject;
+  });
+  return { resolve, reject, promise };
+}
+
+// src/async/wait.ts
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/async/barrier.ts
+var Barrier = class {
+  _isOpen;
+  _promise;
+  _completePromise;
+  constructor() {
+    this._isOpen = false;
+    this._promise = new Promise((c, e) => {
+      this._completePromise = c;
+    });
+  }
+  isOpen() {
+    return this._isOpen;
+  }
+  open() {
+    this._isOpen = true;
+    this._completePromise(true);
+  }
+  wait() {
+    return this._promise;
+  }
+};
+function makeBarrierByPromise(promise, openWhenReject = false) {
+  const barrier = new Barrier();
+  promise.then(() => barrier.open());
+  if (openWhenReject) {
+    promise.catch((err) => {
+      barrier.open();
+      throw err;
+    });
+  }
+  return barrier;
+}
+export {
+  Barrier,
+  CancellationToken,
+  CancellationTokenSource,
+  defer,
+  makeBarrierByPromise,
+  makeCancelablePromise,
+  makePromiseWithTimeout,
+  parallelPromise,
+  wait
+};
+//# sourceMappingURL=index.js.map