@actuallab/core 12.3.14 → 12.3.31

package/dist/index.cjs

@@ -25,14 +25,20 @@ __export(index_exports, {
   AsyncLock: () => AsyncLock,
   DisposableBag: () => DisposableBag,
   EventHandlerSet: () => EventHandlerSet,
+  Log: () => Log,
+  LogLevel: () => LogLevel,
+  LogLevelController: () => LogLevelController,
   PromiseSource: () => PromiseSource,
   Result: () => Result,
   RetryDelayLimitExceeded: () => RetryDelayLimitExceeded,
   RetryDelayNone: () => RetryDelayNone,
   RetryDelaySeq: () => RetryDelaySeq,
   RetryDelayer: () => RetryDelayer,
+  RingBuffer: () => RingBuffer,
   abortSignalKey: () => abortSignalKey,
+  createLogProvider: () => createLogProvider,
   errorResult: () => errorResult,
+  initLogging: () => initLogging,
   resolvedVoidPromise: () => resolvedVoidPromise,
   result: () => result,
   resultFrom: () => resultFrom,
@@ -43,6 +49,340 @@ module.exports = __toCommonJS(index_exports);
 // src/polyfills.ts
 Symbol.metadata ??= /* @__PURE__ */ Symbol("Symbol.metadata");
 
+// src/disposable.ts
+var DisposableBag = class {
+  _items = [];
+  _disposed = false;
+  get isDisposed() {
+    return this._disposed;
+  }
+  add(item) {
+    if (this._disposed)
+      throw new Error("DisposableBag is already disposed.");
+    this._items.push(item);
+  }
+  dispose() {
+    if (this._disposed) return;
+    this._disposed = true;
+    const items = this._items;
+    this._items = [];
+    for (let i = items.length - 1; i >= 0; i--) {
+      const item = items[i];
+      if ("dispose" in item) item.dispose();
+    }
+  }
+  async disposeAsync() {
+    if (this._disposed) return;
+    this._disposed = true;
+    const items = this._items;
+    this._items = [];
+    for (let i = items.length - 1; i >= 0; i--) {
+      const item = items[i];
+      if ("disposeAsync" in item) await item.disposeAsync();
+      else if ("dispose" in item) item.dispose();
+    }
+  }
+};
+
+// src/logging-init.ts
+var GlobalThisKey = "logLevels";
+var StorageKey = "logLevels";
+var DateStorageKey = `${StorageKey}.date`;
+var MaxStorageAge = 864e5 * 3;
+var sessionStorage = typeof globalThis !== "undefined" && "sessionStorage" in globalThis ? globalThis.sessionStorage : null;
+function initLogging() {
+  Log.defaultMinLevel = 3 /* Warn */;
+  const minLevels = Log.minLevels;
+  if (typeof globalThis !== "undefined")
+    globalThis[GlobalThisKey] = new LogLevelController(minLevels);
+  const wasRestored = restore(minLevels);
+  if (wasRestored)
+    console.log("Logging: logLevels are restored");
+  else {
+    console.log("Logging: logLevels are reset");
+    reset(minLevels);
+  }
+}
+var LogLevelController = class {
+  constructor(minLevels) {
+    this.minLevels = minLevels;
+  }
+  /** List the current set of overrides. */
+  list() {
+    return Object.fromEntries(this.minLevels);
+  }
+  /** Print every known scope's effective level to the console as a table.
+   *  Shows: scope, effective level, the source ('override' / 'default-key' /
+   *  'package-default' / 'baseline'), and the package default for reference.
+   *  Use this from the dev console to discover what to pass to override(). */
+  dump() {
+    const baseline = Log.defaultMinLevel;
+    const globalOverride = this.minLevels.get("default");
+    const allScopes = /* @__PURE__ */ new Set([
+      ...Log.knownScopes,
+      ...Log.scopeDefaults.keys(),
+      ...this.minLevels.keys()
+    ]);
+    allScopes.delete("default");
+    const rows = {};
+    const sorted = [...allScopes].sort();
+    for (const scope of sorted) {
+      const override = this.minLevels.get(scope);
+      const pkgDefault = Log.scopeDefaults.get(scope);
+      let level;
+      let source;
+      if (override !== void 0) {
+        level = override;
+        source = "override";
+      } else if (globalOverride !== void 0) {
+        level = globalOverride;
+        source = "minLevels.get('default')";
+      } else if (pkgDefault !== void 0) {
+        level = pkgDefault;
+        source = "package-default";
+      } else {
+        level = baseline;
+        source = "baseline";
+      }
+      rows[scope] = {
+        level: LogLevel[level],
+        source,
+        packageDefault: pkgDefault === void 0 ? "-" : LogLevel[pkgDefault]
+      };
+    }
+    console.table(rows);
+    console.log(
+      `Baseline: ${LogLevel[baseline]}` + (globalOverride === void 0 ? "" : `, default override: ${LogLevel[globalOverride]}`)
+    );
+  }
+  /** Override the level for a single scope.  Persisted to sessionStorage. */
+  override(scope, newLevel) {
+    this.minLevels.set(scope, newLevel);
+    persist(this.minLevels);
+  }
+  /** Override the level for every scope whose name starts with scopePrefix
+   *  (e.g. 'rpc.' to enable verbose RPC logging).  Persisted. */
+  overrideAll(scopePrefix, newLevel) {
+    const matched = /* @__PURE__ */ new Set();
+    for (const [scope] of this.minLevels)
+      if (scope.startsWith(scopePrefix)) matched.add(scope);
+    for (const [scope] of Log.scopeDefaults)
+      if (scope.startsWith(scopePrefix)) matched.add(scope);
+    for (const scope of matched)
+      this.minLevels.set(scope, newLevel);
+    persist(this.minLevels);
+  }
+  /** Reset all overrides; package defaults take effect again.  Persisted. */
+  reset() {
+    reset(this.minLevels);
+    persist(this.minLevels);
+  }
+  /** Clear all overrides (no global default unless `defaultLevel` is given). */
+  clear(defaultLevel) {
+    this.minLevels.clear();
+    if (defaultLevel !== void 0)
+      this.minLevels.set("default", defaultLevel);
+    persist(this.minLevels);
+  }
+};
+function restore(minLevels) {
+  if (!sessionStorage)
+    return false;
+  const dateJson = sessionStorage.getItem(DateStorageKey);
+  if (!dateJson)
+    return false;
+  if (Date.now() - JSON.parse(dateJson) > MaxStorageAge)
+    return false;
+  const readJson = sessionStorage.getItem(StorageKey);
+  if (!readJson)
+    return false;
+  const readMinLevels = new Map(JSON.parse(readJson));
+  if (typeof readMinLevels.size !== "number")
+    return false;
+  minLevels.clear();
+  readMinLevels.forEach((value, key) => minLevels.set(key, value));
+  return true;
+}
+function persist(minLevels) {
+  if (!sessionStorage)
+    return false;
+  sessionStorage.setItem(DateStorageKey, JSON.stringify(Date.now()));
+  sessionStorage.setItem(StorageKey, JSON.stringify(Array.from(minLevels.entries())));
+  return true;
+}
+function reset(minLevels) {
+  minLevels.clear();
+  persist(minLevels);
+}
+
+// src/logging.ts
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["Debug"] = 1] = "Debug";
+  LogLevel2[LogLevel2["Info"] = 2] = "Info";
+  LogLevel2[LogLevel2["Warn"] = 3] = "Warn";
+  LogLevel2[LogLevel2["Error"] = 4] = "Error";
+  LogLevel2[LogLevel2["None"] = 1e3] = "None";
+  return LogLevel2;
+})(LogLevel || {});
+var LogRefSet = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+  }
+  items = [];
+  idSeed = 0;
+  ref(data) {
+    const itemIndex = this.items.findIndex((el) => el.ref.target === data);
+    if (itemIndex >= 0) {
+      const existing = this.items[itemIndex];
+      existing.touchedAt = Date.now();
+      return existing.ref;
+    }
+    const id = data.__logRefId ?? this.idSeed++;
+    const newRef = { target: data, id };
+    data.__logRefId = id;
+    if (this.items.length >= this.capacity)
+      this.removeOldest();
+    this.items.push({ ref: newRef, touchedAt: Date.now() });
+    return newRef;
+  }
+  removeOldest() {
+    let indexToEvict = 0;
+    let itemToEvict = this.items[0];
+    for (let i = 1; i < this.items.length; i++) {
+      const item = this.items[i];
+      if (item.touchedAt < itemToEvict.touchedAt) {
+        itemToEvict = item;
+        indexToEvict = i;
+      }
+    }
+    this.items.splice(indexToEvict, 1);
+    const ref = itemToEvict.ref;
+    ref.target = ref.target?.toString();
+  }
+};
+var Log = class _Log {
+  constructor(scope, level) {
+    this.scope = scope;
+    this.level = level;
+    const prefix = `[${scope}]`;
+    switch (level) {
+      case 1 /* Debug */:
+        this.log = (...data) => console.debug(prefix, ...data);
+        break;
+      case 2 /* Info */:
+        this.log = (...data) => console.log(prefix, ...data);
+        break;
+      case 3 /* Warn */:
+        this.log = (...data) => console.warn(prefix, ...data);
+        break;
+      case 4 /* Error */:
+        this.log = (...data) => console.error(prefix, ...data);
+        break;
+      case 1e3 /* None */:
+        throw new Error("LogLevel.None cannot be used here");
+    }
+    this.trace = (...data) => console.trace(prefix, ...data);
+  }
+  static isInitialized = false;
+  static logRefs = new LogRefSet(10);
+  /** User-set overrides (persisted to sessionStorage). Empty by default. */
+  static minLevels = /* @__PURE__ */ new Map();
+  /** Per-scope defaults registered by packages via createLogProvider(). */
+  static scopeDefaults = /* @__PURE__ */ new Map();
+  /** Every scope ever requested via Log.get().  Used by logLevels.dump()
+   *  so devs can discover what's available to override at runtime. */
+  static knownScopes = /* @__PURE__ */ new Set();
+  /** Global baseline for any scope without a default or override. */
+  static defaultMinLevel = 3 /* Warn */;
+  static loggerFactory = (scope, level) => new _Log(scope, level);
+  log;
+  trace;
+  static get(scope) {
+    if (!this.isInitialized) {
+      this.isInitialized = true;
+      initLogging();
+    }
+    this.knownScopes.add(scope);
+    const minLevels = this.minLevels;
+    const minLevel = minLevels.get(scope) ?? minLevels.get("default") ?? this.scopeDefaults.get(scope) ?? this.defaultMinLevel;
+    const getLogger = (level) => level >= minLevel ? this.loggerFactory(scope, level) : null;
+    return {
+      logScope: scope,
+      debugLog: getLogger(1 /* Debug */),
+      infoLog: getLogger(2 /* Info */),
+      warnLog: getLogger(3 /* Warn */),
+      errorLog: getLogger(4 /* Error */)
+    };
+  }
+  static ref(data) {
+    if (!data)
+      return data;
+    return this.logRefs.ref(data);
+  }
+  assert(predicate, ...data) {
+    if (!predicate)
+      this.log(...data);
+  }
+};
+function createLogProvider(prefix, defaults) {
+  for (const [scope, level] of Object.entries(defaults)) {
+    const fullName = prefix + scope;
+    Log.scopeDefaults.set(fullName, level);
+    Log.knownScopes.add(fullName);
+  }
+  return (scope) => Log.get(prefix + scope);
+}
+
+// src/result.ts
+var Result = class _Result {
+  hasValue;
+  hasError;
+  _value;
+  _error;
+  constructor(value, error) {
+    this.hasValue = error === void 0;
+    this.hasError = !this.hasValue;
+    this._value = value;
+    this._error = error;
+  }
+  get value() {
+    if (this.hasError) throw this._error;
+    return this._value;
+  }
+  get error() {
+    return this._error;
+  }
+  get valueOrUndefined() {
+    return this.hasValue ? this._value : void 0;
+  }
+  static ok(value) {
+    return new _Result(value);
+  }
+  static error(error) {
+    return new _Result(void 0, error);
+  }
+};
+function result(value, error) {
+  return new Result(value, error);
+}
+function errorResult(error) {
+  return Result.error(error);
+}
+function resultFrom(fn) {
+  try {
+    return result(fn());
+  } catch (e) {
+    return errorResult(e);
+  }
+}
+async function resultFromAsync(fn) {
+  try {
+    return result(await fn());
+  } catch (e) {
+    return errorResult(e);
+  }
+}
+
 // src/async-context.ts
 var AsyncContextKey = class {
   id;
@@ -150,41 +490,6 @@ var AsyncLock = class {
   }
 };
 
-// src/disposable.ts
-var DisposableBag = class {
-  _items = [];
-  _disposed = false;
-  get isDisposed() {
-    return this._disposed;
-  }
-  add(item) {
-    if (this._disposed)
-      throw new Error("DisposableBag is already disposed.");
-    this._items.push(item);
-  }
-  dispose() {
-    if (this._disposed) return;
-    this._disposed = true;
-    const items = this._items;
-    this._items = [];
-    for (let i = items.length - 1; i >= 0; i--) {
-      const item = items[i];
-      if ("dispose" in item) item.dispose();
-    }
-  }
-  async disposeAsync() {
-    if (this._disposed) return;
-    this._disposed = true;
-    const items = this._items;
-    this._items = [];
-    for (let i = items.length - 1; i >= 0; i--) {
-      const item = items[i];
-      if ("disposeAsync" in item) await item.disposeAsync();
-      else if ("dispose" in item) item.dispose();
-    }
-  }
-};
-
 // src/promise-source.ts
 var PromiseSource = class {
   promise;
@@ -244,55 +549,97 @@ var EventHandlerSet = class {
   }
 };
 
-// src/result.ts
-var Result = class _Result {
-  hasValue;
-  hasError;
-  _value;
-  _error;
-  constructor(value, error) {
-    this.hasValue = error === void 0;
-    this.hasError = !this.hasValue;
-    this._value = value;
-    this._error = error;
-  }
-  get value() {
-    if (this.hasError) throw this._error;
-    return this._value;
-  }
-  get error() {
-    return this._error;
-  }
-  get valueOrUndefined() {
-    return this.hasValue ? this._value : void 0;
-  }
-  static ok(value) {
-    return new _Result(value);
+// src/ring-buffer.ts
+var RingBuffer = class {
+  _buffer;
+  _start = 0;
+  _end = 0;
+  _count = 0;
+  capacity;
+  get count() {
+    return this._count;
+  }
+  get isEmpty() {
+    return this._count === 0;
+  }
+  get isFull() {
+    return this._count === this.capacity;
+  }
+  get remainingCapacity() {
+    return this.capacity - this._count;
+  }
+  get hasRemainingCapacity() {
+    return this._count < this.capacity;
+  }
+  constructor(capacity) {
+    if (capacity < 1)
+      throw new RangeError(`RingBuffer capacity must be >= 1 (was ${capacity}).`);
+    this.capacity = capacity;
+    this._buffer = new Array(capacity);
+  }
+  /** Read the item at `index` (0-indexed, from head). */
+  get(index) {
+    if (index < 0 || index >= this._count)
+      throw new RangeError(`Index ${index} out of range [0, ${this._count}).`);
+    return this._buffer[(this._start + index) % this.capacity];
+  }
+  /** Add an item at the tail. Throws if the buffer is full. */
+  pushTail(item) {
+    if (this._count >= this.capacity)
+      throw new Error("RingBuffer is full.");
+    this._buffer[this._end] = item;
+    this._end = (this._end + 1) % this.capacity;
+    this._count++;
+  }
+  /** Add an item at the tail, evicting the head item if the buffer is full. */
+  pushTailAndMoveHeadIfFull(item) {
+    if (this._count >= this.capacity) {
+      this._buffer[this._start] = void 0;
+      this._start = (this._start + 1) % this.capacity;
+      this._count--;
+    }
+    this.pushTail(item);
+  }
+  /** Remove the head item. Throws if the buffer is empty. */
+  pullHead() {
+    if (this._count === 0)
+      throw new Error("RingBuffer is empty.");
+    const head = this._buffer[this._start];
+    this._buffer[this._start] = void 0;
+    this._start = (this._start + 1) % this.capacity;
+    this._count--;
+    return head;
+  }
+  /**
+   * Advance the head by `skipCount` slots, releasing references to skipped
+   * items so they can be garbage-collected.
+   */
+  moveHead(skipCount) {
+    if (skipCount === 0) return;
+    if (skipCount < 0 || skipCount > this._count)
+      throw new RangeError(`skipCount ${skipCount} out of range [0, ${this._count}].`);
+    for (let k = 0; k < skipCount; k++) {
+      this._buffer[(this._start + k) % this.capacity] = void 0;
+    }
+    this._start = (this._start + skipCount) % this.capacity;
+    this._count -= skipCount;
   }
-  static error(error) {
-    return new _Result(void 0, error);
+  /** Remove all items. */
+  clear() {
+    for (let i = 0; i < this.capacity; i++) this._buffer[i] = void 0;
+    this._start = 0;
+    this._end = 0;
+    this._count = 0;
+  }
+  /** Copy the buffer's contents to a new array, head-first. */
+  toArray() {
+    const out = new Array(this._count);
+    for (let i = 0; i < this._count; i++) {
+      out[i] = this._buffer[(this._start + i) % this.capacity];
+    }
+    return out;
   }
 };
-function result(value, error) {
-  return new Result(value, error);
-}
-function errorResult(error) {
-  return Result.error(error);
-}
-function resultFrom(fn) {
-  try {
-    return result(fn());
-  } catch (e) {
-    return errorResult(e);
-  }
-}
-async function resultFromAsync(fn) {
-  try {
-    return result(await fn());
-  } catch (e) {
-    return errorResult(e);
-  }
-}
 
 // src/retry-delay-seq.ts
 var DefaultSpread = 0.1;
@@ -399,14 +746,20 @@ var RetryDelayer = class {
   AsyncLock,
   DisposableBag,
   EventHandlerSet,
+  Log,
+  LogLevel,
+  LogLevelController,
   PromiseSource,
   Result,
   RetryDelayLimitExceeded,
   RetryDelayNone,
   RetryDelaySeq,
   RetryDelayer,
+  RingBuffer,
   abortSignalKey,
+  createLogProvider,
   errorResult,
+  initLogging,
   resolvedVoidPromise,
   result,
   resultFrom,