@dxos/debug 0.10.0 → 0.11.0

package/dist/lib/index.mjs

@@ -0,0 +1,398 @@
+import { inspect } from "@dxos/node-std/util";
+//#region src/assert.ts
+/**
+* A simple syntax sugar to write `value as T` as a statement.
+*
+* NOTE: This does not provide any type safety.
+* It's just for convenience so that autocomplete works for value.
+* It's recommended to check the type URL manually beforehand or use `assertAnyType` instead.
+* @param value
+*/
+var checkType = (value) => value;
+//#endregion
+//#region src/error-stream.ts
+/**
+* Represents a stream of errors that entities can expose.
+*/
+var ErrorStream = class {
+	_handler;
+	_unhandledErrors = 0;
+	assertNoUnhandledErrors() {
+		if (this._unhandledErrors > 0) throw new Error(`Assertion failed: expected no unhandled errors to be thrown, but ${this._unhandledErrors} were thrown.`);
+	}
+	raise(error) {
+		if (this._handler) this._handler(error);
+		else this._unhandledError(error);
+	}
+	handle(handler) {
+		this._handler = handler;
+	}
+	pipeTo(receiver) {
+		this.handle((error) => receiver.raise(error));
+	}
+	_unhandledError(error) {
+		this._unhandledErrors++;
+		setTimeout(() => {
+			throw error;
+		});
+	}
+};
+//#endregion
+//#region src/fail.ts
+/**
+* Should be used in expressions where values are cheked not to be null or undefined.
+*
+* Example:
+*
+* ```
+* const value: string | undefined;
+*
+* callMethod(value ?? failUndefined());
+* ```
+*/
+var failUndefined = () => {
+	throw new Error("Required value was null or undefined.");
+};
+//#endregion
+//#region src/inspect.ts
+/**
+* Utility to automatically log debug info.
+*
+* ```
+*   // Called via `console.log`.
+*   [inspect.custom] () {
+*     return inspectObject(this);
+*   }
+*
+*   // Called via `JSON.stringify`.
+*   toJSON () {
+*     return { ... };
+*   }
+* ```
+*/
+var inspectObject = (obj) => {
+	const name = Object.getPrototypeOf(obj).constructor.name;
+	return obj.toJSON ? `${name}(${inspect(obj.toJSON())})` : String(obj);
+};
+//#endregion
+//#region src/log-method.ts
+function logMethod(target, propertyName, descriptor) {
+	const method = descriptor.value;
+	descriptor.value = function(...args) {
+		console.log(`Called ${target.constructor.name}.${propertyName} ${args}`);
+		try {
+			const result = method.apply(this, args);
+			if (typeof result.catch === "function") result.catch((err) => {
+				console.log(`Rejected ${target.constructor.name}.${propertyName}`, err);
+			});
+			return result;
+		} catch (err) {
+			console.log(`Thrown ${target.constructor.name}.${propertyName}`, err);
+			throw err;
+		}
+	};
+}
+//#endregion
+//#region src/raise.ts
+/**
+* Immediatelly throws an error passed as an argument.
+*
+* Usefull for throwing errors from inside expressions.
+* For example:
+* ```
+* const item = model.getById(someId) ?? raise(new Error('Not found'));
+* ```
+* @param error
+*/
+var raise = (error) => {
+	throw error;
+};
+//#endregion
+//#region src/snoop.ts
+var SnoopLevel = /* @__PURE__ */ function(SnoopLevel) {
+	SnoopLevel[SnoopLevel["DEFAULT"] = 0] = "DEFAULT";
+	SnoopLevel[SnoopLevel["VERBOSE"] = 1] = "VERBOSE";
+	SnoopLevel[SnoopLevel["BOLD"] = 2] = "BOLD";
+	return SnoopLevel;
+}({});
+/**
+* Utils for debug logging of functions.
+*/
+var Snoop = class Snoop {
+	_context;
+	static stackFunction(err) {
+		const match = err.stack.split("\n")[2].match(/.+\((.+)\).*/);
+		if (match) {
+			const [file, line] = match[1].split(":");
+			return `[${file.substring(file.lastIndexOf("/") + 1)}:${line}]`;
+		}
+	}
+	constructor(_context) {
+		this._context = _context;
+	}
+	get verbose() {
+		return 1;
+	}
+	get bold() {
+		return 2;
+	}
+	format(prefix, name, args, level) {
+		const pre = prefix.repeat(level === 2 ? 8 : 2);
+		const line = `${pre} ${this._context ? `${this._context}.${name}` : name}${args}`;
+		return level === 2 ? [
+			pre,
+			line,
+			pre
+		].join("\n") : line;
+	}
+	in(label, level, ...args) {
+		return this.format("<", label, level === 0 ? "" : `(${String(...args)})`, level);
+	}
+	out(label, level, result) {
+		return this.format(">", label, level === 0 ? "" : ` = ${String(result)}`, level);
+	}
+	sync(f, label, level = 1) {
+		label = label ?? Snoop.stackFunction(/* @__PURE__ */ new Error());
+		return (...args) => {
+			console.log(this.in(label ?? "", level, ...args));
+			const r = f(...args);
+			console.log(this.out(label ?? "", level, r));
+			return r;
+		};
+	}
+	async(f, label, level = 1) {
+		label = label ?? Snoop.stackFunction(/* @__PURE__ */ new Error());
+		return async (...args) => {
+			console.log(this.in(label ?? "", level, ...args));
+			const r = await f(...args);
+			console.log(this.out(label ?? "", level, r));
+			return r;
+		};
+	}
+};
+var snoop = new Snoop();
+//#endregion
+//#region src/stack-trace.ts
+/**
+* Will capture the stack trace at the point where the class is created.
+* Stack traces are formatted lazily only when `getStack` is called.
+* Formatting is significantly more expensive than capture so only call getStack when you need them.
+*
+* IMPORTANT: a trace that has never been formatted keeps its entire capture site reachable. V8 holds
+* the captured frames structurally until `Error.prototype.stack` is read, and every frame holds a
+* strong reference to that frame's receiver — so retaining an unformatted `StackTrace` retains the
+* `this` of each function that was on the stack at capture time. Records that outlive their capture
+* site (diagnostics, registries, caches) must therefore store the formatted string rather than the
+* `StackTrace` itself. Keeping one in a never-pruned module-level container leaked an entire ECHO
+* client graph per query on Cloudflare Workers, where nothing ever reads the diagnostics (DX-1140).
+*/
+var StackTrace = class {
+	_error;
+	_frames;
+	constructor() {
+		this._error = /* @__PURE__ */ new Error();
+	}
+	/**
+	* Formats on first use, then releases the captured frames — and with them the capture site.
+	*
+	* The `Error` is dropped before formatting, not after: releasing the capture site is the whole
+	* point, so it must not be contingent on `stack` being present or `split` succeeding.
+	*/
+	_format() {
+		if (!this._frames) {
+			const error = this._error;
+			this._error = void 0;
+			this._frames = error?.stack?.split("\n") ?? [];
+		}
+		return this._frames;
+	}
+	/**
+	* Get stack formatted as string.
+	* @param skipFrames Number of frames to skip. By default, the first frame would be the invocation of the StackTrace constructor.
+	* @returns
+	*/
+	getStack(skipFrames = 0) {
+		return this.getStackArray(skipFrames).join("\n");
+	}
+	getStackArray(skipFrames = 0) {
+		return this._format().slice(skipFrames + 2);
+	}
+};
+//#endregion
+//#region src/strings.ts
+var truncate = (str = "", length = 8, pad = false) => {
+	if (str.length >= length - 1) return str.substring(0, length - 1) + "…";
+	else return pad ? str.padEnd(length, typeof pad === "boolean" ? " " : pad[0]) : str;
+};
+var truncateKey = (key, length = 8) => {
+	const str = String(key);
+	if (str.length <= length) return str;
+	return str.slice(0, length);
+};
+//#endregion
+//#region src/throw.ts
+/**
+* Wrapper for async tests.
+* @param {Function} test - Async test
+* @param errType
+* @return {Promise<void>}
+*
+* @deprecated Use vitests `expect(() => ...).toThrowError();` instead.
+*/
+var expectToThrow = async (test, errType = Error) => {
+	let thrown;
+	try {
+		await test();
+	} catch (err) {
+		thrown = err;
+	}
+	if (thrown === void 0 || !(thrown instanceof errType)) throw new Error(`Expected function to throw instance of ${errType.prototype.name}`);
+};
+//#endregion
+//#region src/timeout-warning.ts
+/**
+* Prints a warning to console if the action takes longer then specified timeout. No errors are thrown.
+*
+* @param timeout Timeout in milliseconds after which warning is printed.
+* @param context Context description that would be included in the printed message.
+* @param body Action which is timed.
+*/
+var warnAfterTimeout = async (timeout, context, body) => {
+	const stack = new StackTrace();
+	const timeoutId = setTimeout(() => {
+		console.warn(`Action \`${context}\` is taking more then ${timeout.toLocaleString()}ms to complete. This might be a bug.\n${stack.getStack()}`);
+	}, timeout);
+	try {
+		return await body();
+	} finally {
+		clearTimeout(timeoutId);
+	}
+};
+/**
+* A decorator that prints a warning to console if method execution time exceeds specified timeout.
+*
+* ```typescript
+* class Foo {
+*   @timed(5_000)
+*   async doStuff() {
+*     // long task
+*   }
+* }
+* ```
+*
+* This is useful for debugging code that might deadlock.
+*
+* @param timeout Timeout in milliseconds after which the warning is printed.
+*/
+function timed(timeout) {
+	return (target, propertyName, descriptor) => {
+		const method = descriptor.value;
+		descriptor.value = function(...args) {
+			return warnAfterTimeout(timeout, `${target.constructor.name}.${propertyName}`, () => method.apply(this, args));
+		};
+	};
+}
+//#endregion
+//#region src/todo.ts
+/**
+* Throws an error. Can be used in an expression instead of a value
+*/
+var todo = (message) => {
+	throw new Error(message ?? "Not implemented.");
+};
+//#endregion
+//#region src/devtools-formatter.ts
+/**
+* Lets types provide custom formatters for the Chrome Devtools.
+*
+* https://www.mattzeunert.com/2016/02/19/custom-chrome-devtools-object-formatters.html
+* NOTE: Must be enabled in chrome devtools preferences.
+*
+* @example
+* ```typescript
+* class MyType {
+*  get [devtoolsFormatter] (): DevtoolsFormatter {
+*    ...
+*  }
+* ```
+*/
+var devtoolsFormatter = Symbol.for("devtoolsFormatter");
+var register = () => {
+	if (typeof window !== "undefined") (window.devtoolsFormatters ??= []).push({
+		header: (value, config) => {
+			const formatter = value[devtoolsFormatter];
+			if (formatter === void 0) return null;
+			if (typeof formatter !== "object" || formatter === null || typeof formatter.header !== "function") throw new Error(`Invalid devtools formatter for ${value.constructor.name}`);
+			return formatter.header(config);
+		},
+		hasBody: (value, config) => {
+			const formatter = value[devtoolsFormatter];
+			if (!formatter || !formatter.hasBody) return false;
+			return formatter.hasBody(config);
+		},
+		body: (value, config) => {
+			const formatter = value[devtoolsFormatter];
+			if (!formatter || !formatter.body) return null;
+			return formatter.body(config);
+		}
+	});
+};
+register();
+//#endregion
+//#region src/equality.ts
+var equalsSymbol = Symbol.for("dxos.common.equals");
+var isEquatable = (value) => {
+	return typeof value === "object" && value !== null && typeof value[equalsSymbol] === "function";
+};
+var isEqual = (value, other) => {
+	return value[equalsSymbol](other);
+};
+/**
+* Feed this as a third argument to `_.isEqualWith` to compare objects with `Equatable` interface.
+*/
+var loadashEqualityFn = (value, other) => {
+	if (!isEquatable(value)) return;
+	return isEqual(value, other);
+};
+//#endregion
+//#region src/exposed-modules.ts
+/**
+* Allows to register a module to be used later during debugging.
+*
+* ```ts
+* import * as keys from '@dxos/keys';
+* exposeModule('@dxos/keys', keys);
+*
+* ...
+*
+* const { PublicKey } = importModule('@dxos/keys');
+* ```
+*
+* Overwrites the module if it already exists.
+*/
+var exposeModule = (name, module) => {
+	EXPOSED_MODULES[name] = module;
+};
+/**
+* Imports a previously exposed module by its name.
+* Throws an error if the module is not found.
+*
+* @param {string} name - The name of the module to import.
+* @returns {any} The imported module.
+* @throws {Error} If the module is not exposed.
+*/
+var importModule = (name) => {
+	if (EXPOSED_MODULES[name]) return EXPOSED_MODULES[name];
+	else throw new Error(`Module ${name} is not exposed.`);
+};
+var EXPOSED_MODULES = {};
+//#endregion
+//#region src/inspect-custom.ts
+/**
+* Using this allows code to be written in a portable fashion, so that the custom inspect function is used in an Node.js environment and ignored in the browser.
+*/
+var inspectCustom = Symbol.for("nodejs.util.inspect.custom");
+//#endregion
+export { ErrorStream, Snoop, SnoopLevel, StackTrace, checkType, devtoolsFormatter, equalsSymbol, expectToThrow, exposeModule, failUndefined, importModule, inspectCustom, inspectObject, isEqual, isEquatable, loadashEqualityFn, logMethod, raise, snoop, timed, todo, truncate, truncateKey, warnAfterTimeout };
+
+//# sourceMappingURL=index.mjs.map

package/dist/lib/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/assert.ts","../../src/error-stream.ts","../../src/fail.ts","../../src/inspect.ts","../../src/log-method.ts","../../src/raise.ts","../../src/snoop.ts","../../src/stack-trace.ts","../../src/strings.ts","../../src/throw.ts","../../src/timeout-warning.ts","../../src/todo.ts","../../src/devtools-formatter.ts","../../src/equality.ts","../../src/exposed-modules.ts","../../src/inspect-custom.ts"],"sourcesContent":["//\n// Copyright 2020 DXOS.org\n//\n\n/**\n * A simple syntax sugar to write `value as T` as a statement.\n *\n * NOTE: This does not provide any type safety.\n * It's just for convenience so that autocomplete works for value.\n * It's recommended to check the type URL manually beforehand or use `assertAnyType` instead.\n * @param value\n */\nexport const checkType = <T>(value: T): T => value;\n","//\n// Copyright 2021 DXOS.org\n//\n\nexport type ErrorHandlerCallback = (error: Error) => void;\n\n/**\n * Represents a stream of errors that entities can expose.\n */\nexport class ErrorStream {\n  private _handler: ErrorHandlerCallback | undefined;\n\n  private _unhandledErrors = 0;\n\n  assertNoUnhandledErrors(): void {\n    if (this._unhandledErrors > 0) {\n      throw new Error(\n        `Assertion failed: expected no unhandled errors to be thrown, but ${this._unhandledErrors} were thrown.`,\n      );\n    }\n  }\n\n  raise(error: Error): void {\n    if (this._handler) {\n      this._handler(error);\n    } else {\n      this._unhandledError(error);\n    }\n  }\n\n  handle(handler: ErrorHandlerCallback): void {\n    this._handler = handler;\n  }\n\n  pipeTo(receiver: ErrorStream): void {\n    this.handle((error) => receiver.raise(error));\n  }\n\n  private _unhandledError(error: Error): void {\n    this._unhandledErrors++;\n\n    setTimeout(() => {\n      throw error;\n    });\n  }\n}\n","//\n// Copyright 2021 DXOS.org\n//\n\n/**\n * Should be used in expressions where values are cheked not to be null or undefined.\n *\n * Example:\n *\n * ```\n * const value: string | undefined;\n *\n * callMethod(value ?? failUndefined());\n * ```\n */\n// TODO(burdon): Rename failIfUndefined().\nexport const failUndefined = () => {\n  throw new Error('Required value was null or undefined.');\n};\n","//\n// Copyright 2022 DXOS.org\n//\n\nimport { inspect } from 'node:util';\n\n/**\n * Utility to automatically log debug info.\n *\n * ```\n *   // Called via `console.log`.\n *   [inspect.custom] () {\n *     return inspectObject(this);\n *   }\n *\n *   // Called via `JSON.stringify`.\n *   toJSON () {\n *     return { ... };\n *   }\n * ```\n */\nexport const inspectObject = (obj: any) => {\n  const name = Object.getPrototypeOf(obj).constructor.name;\n  return obj.toJSON ? `${name}(${inspect(obj.toJSON())})` : String(obj);\n};\n","//\n// Copyright 2021 DXOS.org\n//\n\n/* eslint-disable no-console */\n\nexport function logMethod(\n  target: any,\n  propertyName: string,\n  descriptor: TypedPropertyDescriptor<(...args: any) => any>,\n): void {\n  const method = descriptor.value!;\n  descriptor.value = function (this: any, ...args: any) {\n    console.log(`Called ${target.constructor.name}.${propertyName} ${args}`);\n    try {\n      const result = method.apply(this, args);\n      if (typeof result.catch === 'function') {\n        result.catch((err: any) => {\n          console.log(`Rejected ${target.constructor.name}.${propertyName}`, err);\n        });\n      }\n      return result;\n    } catch (err: any) {\n      console.log(`Thrown ${target.constructor.name}.${propertyName}`, err);\n      throw err;\n    }\n  };\n}\n","//\n// Copyright 2020 DXOS.org\n//\n\n/**\n * Immediatelly throws an error passed as an argument.\n *\n * Usefull for throwing errors from inside expressions.\n * For example:\n * ```\n * const item = model.getById(someId) ?? raise(new Error('Not found'));\n * ```\n * @param error\n */\nexport const raise = (error: Error): never => {\n  throw error;\n};\n","//\n// Copyright 2022 DXOS.org\n//\n\n/* eslint-disable no-console */\n\nexport enum SnoopLevel {\n  DEFAULT = 0,\n  VERBOSE = 1,\n  BOLD = 2,\n}\n\n/**\n * Utils for debug logging of functions.\n */\n// TODO(burdon): Integrate with log/spyglass.\nexport class Snoop {\n  static stackFunction(err: Error): string | undefined {\n    const stack = err.stack!.split('\\n');\n    const match = stack[2].match(/.+\\((.+)\\).*/);\n    if (match) {\n      const [file, line] = match[1].split(':');\n      return `[${file.substring(file.lastIndexOf('/') + 1)}:${line}]`;\n    }\n  }\n\n  constructor(private readonly _context?: string) {}\n\n  get verbose() {\n    return SnoopLevel.VERBOSE;\n  }\n\n  get bold() {\n    return SnoopLevel.BOLD;\n  }\n\n  format(prefix: string, name: string, args: string, level: SnoopLevel): string {\n    const pre = prefix.repeat(level === SnoopLevel.BOLD ? 8 : 2);\n    const label = this._context ? `${this._context}.${name}` : name;\n    const line = `${pre} ${label}${args}`;\n    return level === SnoopLevel.BOLD ? [pre, line, pre].join('\\n') : line;\n  }\n\n  in(label: string, level: SnoopLevel, ...args: any[]): string {\n    return this.format('<', label, level === SnoopLevel.DEFAULT ? '' : `(${String(...args)})`, level);\n  }\n\n  out(label: string, level: SnoopLevel, result: any): string {\n    return this.format('>', label, level === SnoopLevel.DEFAULT ? '' : ` = ${String(result)}`, level);\n  }\n\n  sync(f: any, label?: string, level: SnoopLevel = SnoopLevel.VERBOSE) {\n    label = label ?? Snoop.stackFunction(new Error());\n    return (...args: any[]) => {\n      console.log(this.in(label ?? '', level, ...args));\n      const r = f(...args);\n      console.log(this.out(label ?? '', level, r));\n      return r;\n    };\n  }\n\n  async(f: any, label?: string, level: SnoopLevel = SnoopLevel.VERBOSE) {\n    label = label ?? Snoop.stackFunction(new Error());\n    return async (...args: any[]) => {\n      console.log(this.in(label ?? '', level, ...args));\n      const r = await f(...args);\n      console.log(this.out(label ?? '', level, r));\n      return r;\n    };\n  }\n}\n\nexport const snoop = new Snoop();\n","//\n// Copyright 2021 DXOS.org\n//\n\n/**\n * Will capture the stack trace at the point where the class is created.\n * Stack traces are formatted lazily only when `getStack` is called.\n * Formatting is significantly more expensive than capture so only call getStack when you need them.\n *\n * IMPORTANT: a trace that has never been formatted keeps its entire capture site reachable. V8 holds\n * the captured frames structurally until `Error.prototype.stack` is read, and every frame holds a\n * strong reference to that frame's receiver — so retaining an unformatted `StackTrace` retains the\n * `this` of each function that was on the stack at capture time. Records that outlive their capture\n * site (diagnostics, registries, caches) must therefore store the formatted string rather than the\n * `StackTrace` itself. Keeping one in a never-pruned module-level container leaked an entire ECHO\n * client graph per query on Cloudflare Workers, where nothing ever reads the diagnostics (DX-1140).\n */\nexport class StackTrace {\n  private _error: Error | undefined;\n  private _frames: string[] | undefined;\n\n  // NOTE: Captured in the constructor body, not a field initializer — an initializer adds its own\n  // frame, which would shift the `skipFrames` offsets every caller passes.\n  constructor() {\n    this._error = new Error();\n  }\n\n  /**\n   * Formats on first use, then releases the captured frames — and with them the capture site.\n   *\n   * The `Error` is dropped before formatting, not after: releasing the capture site is the whole\n   * point, so it must not be contingent on `stack` being present or `split` succeeding.\n   */\n  private _format(): string[] {\n    if (!this._frames) {\n      const error = this._error;\n      this._error = undefined;\n      this._frames = error?.stack?.split('\\n') ?? [];\n    }\n    return this._frames;\n  }\n\n  /**\n   * Get stack formatted as string.\n   * @param skipFrames Number of frames to skip. By default, the first frame would be the invocation of the StackTrace constructor.\n   * @returns\n   */\n  getStack(skipFrames = 0): string {\n    return this.getStackArray(skipFrames).join('\\n');\n  }\n\n  getStackArray(skipFrames = 0): string[] {\n    return this._format().slice(skipFrames + 2);\n  }\n}\n","//\n// Copyright 2020 DXOS.org\n//\n\nexport const truncate = (str = '', length = 8, pad: boolean | string = false) => {\n  if (str.length >= length - 1) {\n    return str.substring(0, length - 1) + '…';\n  } else {\n    return pad ? str.padEnd(length, typeof pad === 'boolean' ? ' ' : pad[0]) : str;\n  }\n};\n\nexport const truncateKey = (key: any, length = 8) => {\n  const str = String(key);\n  if (str.length <= length) {\n    return str;\n  }\n\n  return str.slice(0, length);\n\n  // return start\n  //   ? `${str.slice(0, length)}...`\n  //   : `${str.substring(0, length / 2)}...${str.substring(str.length - length / 2)}`;\n};\n","//\n// Copyright 2020 DXOS.org\n//\n\n/**\n * Wrapper for async tests.\n * @param {Function} test - Async test\n * @param errType\n * @return {Promise<void>}\n *\n * @deprecated Use vitests `expect(() => ...).toThrowError();` instead.\n */\nexport const expectToThrow = async (test: () => void, errType = Error) => {\n  let thrown;\n  try {\n    await test();\n  } catch (err) {\n    thrown = err;\n  }\n\n  if (thrown === undefined || !(thrown instanceof errType)) {\n    throw new Error(`Expected function to throw instance of ${errType.prototype.name}`);\n  }\n};\n","//\n// Copyright 2020 DXOS.org\n//\n\nimport { StackTrace } from './stack-trace';\n\n/**\n * Prints a warning to console if the action takes longer then specified timeout. No errors are thrown.\n *\n * @param timeout Timeout in milliseconds after which warning is printed.\n * @param context Context description that would be included in the printed message.\n * @param body Action which is timed.\n */\nexport const warnAfterTimeout = async <T>(timeout: number, context: string, body: () => Promise<T>): Promise<T> => {\n  const stack = new StackTrace();\n  const timeoutId = setTimeout(() => {\n    // eslint-disable-next-line no-console\n    console.warn(\n      `Action \\`${context}\\` is taking more then ${timeout.toLocaleString()}ms to complete. This might be a bug.\\n${stack.getStack()}`,\n    );\n  }, timeout);\n  try {\n    return await body();\n  } finally {\n    clearTimeout(timeoutId);\n  }\n};\n\n/**\n * A decorator that prints a warning to console if method execution time exceeds specified timeout.\n *\n * ```typescript\n * class Foo {\n *   @timed(5_000)\n *   async doStuff() {\n *     // long task\n *   }\n * }\n * ```\n *\n * This is useful for debugging code that might deadlock.\n *\n * @param timeout Timeout in milliseconds after which the warning is printed.\n */\nexport function timed(timeout: number) {\n  return (target: any, propertyName: string, descriptor: TypedPropertyDescriptor<(...args: any) => any>) => {\n    const method = descriptor.value!;\n    descriptor.value = function (this: any, ...args: any) {\n      return warnAfterTimeout(timeout, `${target.constructor.name}.${propertyName}`, () => method.apply(this, args));\n    };\n  };\n}\n","//\n// Copyright 2020 DXOS.org\n//\n\n/**\n * Throws an error. Can be used in an expression instead of a value\n */\nexport const todo = (message?: string): never => {\n  throw new Error(message ?? 'Not implemented.');\n};\n","//\n// Copyright 2023 DXOS.org\n//\n\n/**\n * Lets types provide custom formatters for the Chrome Devtools.\n *\n * https://www.mattzeunert.com/2016/02/19/custom-chrome-devtools-object-formatters.html\n * NOTE: Must be enabled in chrome devtools preferences.\n *\n * @example\n * ```typescript\n * class MyType {\n *  get [devtoolsFormatter] (): DevtoolsFormatter {\n *    ...\n *  }\n * ```\n */\n\nexport const devtoolsFormatter = Symbol.for('devtoolsFormatter');\n\nexport type JsonML = [string, Record<string, any>?, ...(JsonML | string)[]];\n\nexport interface DevtoolsFormatter {\n  /**\n   * NOTE: Make sure to do an instance check and return null if the object is not of the correct type.\n   */\n  header: (config?: any) => JsonML | null;\n  hasBody?: (config?: any) => boolean;\n  body?: (config?: any) => JsonML | null;\n}\n\n/**\n * Types that implement this interface can provide custom formatters for the Chrome Devtools.\n *\n * https://firefox-source-docs.mozilla.org/devtools-user/custom_formatters/index.html\n */\nexport interface CustomDevtoolsFormattable {\n  get [devtoolsFormatter](): DevtoolsFormatter;\n}\n\nconst register = () => {\n  if (typeof window !== 'undefined') {\n    ((window as any).devtoolsFormatters ??= []).push({\n      header: (value: any, config: any) => {\n        const formatter = value[devtoolsFormatter];\n        if (formatter === undefined) {\n          return null;\n        }\n        if (typeof formatter !== 'object' || formatter === null || typeof formatter.header !== 'function') {\n          throw new Error(`Invalid devtools formatter for ${value.constructor.name}`);\n        }\n\n        return formatter.header(config);\n      },\n      hasBody: (value: any, config: any) => {\n        const formatter = value[devtoolsFormatter];\n        if (!formatter || !formatter.hasBody) {\n          return false;\n        }\n\n        return formatter.hasBody(config);\n      },\n      body: (value: any, config: any) => {\n        const formatter = value[devtoolsFormatter];\n        if (!formatter || !formatter.body) {\n          return null;\n        }\n\n        return formatter.body(config);\n      },\n    });\n  }\n};\n\nregister();\n","//\n// Copyright 2023 DXOS.org\n//\n\nexport const equalsSymbol = Symbol.for('dxos.common.equals');\n\nexport interface Equatable {\n  [equalsSymbol]: (other: any) => boolean;\n}\n\n// TODO(dmaretskyi): export to @dxos/traits.\n// TODO(dmaretskyi): Hash trait for maps?\n\nexport const isEquatable = (value: any): value is Equatable => {\n  return typeof value === 'object' && value !== null && typeof value[equalsSymbol] === 'function';\n};\n\nexport const isEqual = (value: Equatable, other: any) => {\n  return value[equalsSymbol](other);\n};\n\n/**\n * Feed this as a third argument to `_.isEqualWith` to compare objects with `Equatable` interface.\n */\nexport const loadashEqualityFn = (value: any, other: any): boolean | undefined => {\n  if (!isEquatable(value)) {\n    return undefined;\n  }\n  return isEqual(value, other);\n};\n","//\n// Copyright 2024 DXOS.org\n//\n\n/**\n * Allows to register a module to be used later during debugging.\n *\n * ```ts\n * import * as keys from '@dxos/keys';\n * exposeModule('@dxos/keys', keys);\n *\n * ...\n *\n * const { PublicKey } = importModule('@dxos/keys');\n * ```\n *\n * Overwrites the module if it already exists.\n */\nexport const exposeModule = (name: string, module: any) => {\n  EXPOSED_MODULES[name] = module;\n};\n\n/**\n * Imports a previously exposed module by its name.\n * Throws an error if the module is not found.\n *\n * @param {string} name - The name of the module to import.\n * @returns {any} The imported module.\n * @throws {Error} If the module is not exposed.\n */\nexport const importModule = (name: string) => {\n  if (EXPOSED_MODULES[name]) {\n    return EXPOSED_MODULES[name];\n  } else {\n    throw new Error(`Module ${name} is not exposed.`);\n  }\n};\n\nconst EXPOSED_MODULES: Record<string, any> = {};\n","//\n// Copyright 2024 DXOS.org\n//\n\nimport type { InspectOptionsStylized, inspect as inspectFn } from 'node:util';\n\n/**\n * Using this allows code to be written in a portable fashion, so that the custom inspect function is used in an Node.js environment and ignored in the browser.\n */\nexport const inspectCustom = Symbol.for('nodejs.util.inspect.custom');\n\nexport type CustomInspectFunction<T = any> = (\n  this: T,\n  depth: number,\n  options: InspectOptionsStylized,\n  inspect: typeof inspectFn,\n) => any; // TODO: , inspect: inspect\n\nexport interface CustomInspectable {\n  [inspectCustom]: CustomInspectFunction;\n}\n"],"mappings":"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"}

package/dist/types/src/index.d.ts

@@ -1,5 +1,4 @@
 export * from './assert';
-export * from './error-handler';
 export * from './error-stream';
 export * from './fail';
 export * from './inspect';

package/dist/types/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,QAAQ,CAAC;AACvB,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,QAAQ,CAAC;AACvB,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC"}

package/dist/types/src/stack-trace.d.ts

@@ -2,10 +2,26 @@
  * Will capture the stack trace at the point where the class is created.
  * Stack traces are formatted lazily only when `getStack` is called.
  * Formatting is significantly more expensive than capture so only call getStack when you need them.
+ *
+ * IMPORTANT: a trace that has never been formatted keeps its entire capture site reachable. V8 holds
+ * the captured frames structurally until `Error.prototype.stack` is read, and every frame holds a
+ * strong reference to that frame's receiver — so retaining an unformatted `StackTrace` retains the
+ * `this` of each function that was on the stack at capture time. Records that outlive their capture
+ * site (diagnostics, registries, caches) must therefore store the formatted string rather than the
+ * `StackTrace` itself. Keeping one in a never-pruned module-level container leaked an entire ECHO
+ * client graph per query on Cloudflare Workers, where nothing ever reads the diagnostics (DX-1140).
  */
 export declare class StackTrace {
-    private _stack;
+    private _error;
+    private _frames;
     constructor();
+    /**
+     * Formats on first use, then releases the captured frames — and with them the capture site.
+     *
+     * The `Error` is dropped before formatting, not after: releasing the capture site is the whole
+     * point, so it must not be contingent on `stack` being present or `split` succeeding.
+     */
+    private _format;
     /**
      * Get stack formatted as string.
      * @param skipFrames Number of frames to skip. By default, the first frame would be the invocation of the StackTrace constructor.

package/dist/types/src/stack-trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stack-trace.d.ts","sourceRoot":"","sources":["../../../src/stack-trace.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAQ;IAEtB,cAEC;IAED;;;;OAIG;IACH,QAAQ,CAAC,UAAU,SAAI,GAAG,MAAM,CAG/B;IAED,aAAa,CAAC,UAAU,SAAI,GAAG,MAAM,EAAE,CAGtC;CACF"}
+{"version":3,"file":"stack-trace.d.ts","sourceRoot":"","sources":["../../../src/stack-trace.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,OAAO,CAAuB;IAItC,cAEC;IAED;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IASf;;;;OAIG;IACH,QAAQ,CAAC,UAAU,SAAI,GAAG,MAAM,CAE/B;IAED,aAAa,CAAC,UAAU,SAAI,GAAG,MAAM,EAAE,CAEtC;CACF"}

package/dist/types/src/stack-trace.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stack-trace.test.d.ts.map

package/dist/types/src/stack-trace.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-trace.test.d.ts","sourceRoot":"","sources":["../../../src/stack-trace.test.ts"],"names":[],"mappings":""}