@xylabs/base 4.8.0

package/README.md

@@ -0,0 +1,69 @@
+[![logo][]](https://xylabs.com)
+
+# @xylabs/base
+
+[![npm-badge][]][npm-link]
+[![npm-downloads-badge][]][npm-link]
+[![jsdelivr-badge][]][jsdelivr-link]
+[![npm-license-badge][]](LICENSE)
+[![socket-badge][]][socket-link]
+
+> XY Labs generalized Javascript library 
+
+## Table of Contents
+
+-   [Description](#description)
+-   [Install](#install)
+-   [Maintainers](#maintainers)
+-   [License](#license)
+-   [Credits](#credits)
+
+## Description
+
+Common Javascript code that is used throughout XYO projects that use React.
+
+## Install
+
+Using npm:
+
+```sh
+npm i --save @xylabs/base
+```
+
+Using yarn:
+
+```sh
+yarn add @xylabs/base
+```
+
+## Documentation
+[Developer Reference](https://xylabs.github.io/sdk-js)
+
+## Maintainers
+
+-   [Arie Trouw](https://github.com/arietrouw) ([arietrouw.com](https://arietrouw.com))
+-   [Joel Carter](https://github.com/JoelBCarter)
+-   [Matt Jones](https://github.com/jonesmac)
+-   [Jordan Trouw](https://github.com/jordantrouw)
+
+## License
+
+See the [LICENSE](LICENSE) file for license details
+
+## Credits
+
+[Made with 🔥and ❄️ by XY Labs](https://xylabs.com)
+
+[logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg
+
+[npm-badge]: https://img.shields.io/npm/v/@xylabs/base.svg
+[npm-link]: https://www.npmjs.com/package/@xylabs/base
+
+[npm-downloads-badge]: https://img.shields.io/npm/dw/@xylabs/base
+[npm-license-badge]: https://img.shields.io/npm/l/@xylabs/base
+
+[jsdelivr-badge]: https://data.jsdelivr.com/v1/package/npm/@xylabs/base/badge
+[jsdelivr-link]: https://www.jsdelivr.com/package/npm/@xylabs/base
+
+[socket-badge]: https://socket.dev/api/badge/npm/package/@xylabs/base
+[socket-link]: https://socket.dev/npm/package/@xylabs/base

package/dist/neutral/index.mjs

@@ -0,0 +1,143 @@
+// src/Base.ts
+import { assertEx } from "@xylabs/assert";
+
+// src/globallyUnique.ts
+var xyoGlobal = () => {
+  globalThis.xylabs = globalThis.xylabs ?? {};
+  return globalThis.xylabs;
+};
+var disableGloballyUnique = () => {
+  xyoGlobal().uniqueDisabled = true;
+};
+var globallyUnique = (name, value, domain = "global") => {
+  const uniqueName = [domain, name].join(":");
+  if (!xyoGlobal().uniqueDisabled) {
+    const xylabs = globalThis.xylabs = globalThis.xylabs ?? {};
+    const unique = xylabs.unique = xylabs.unique ?? {};
+    if (unique[uniqueName] === void 0) {
+      unique[uniqueName] = value;
+    } else {
+      if (unique[uniqueName] !== value) {
+        throw new Error(
+          `Global unique item ${uniqueName} already defined.  Make sure you are not importing two versions of the package that contains this item`
+        );
+      }
+    }
+  }
+  return uniqueName;
+};
+
+// src/Base.ts
+var DEFAULT_HISTORY_INTERVAL = 1e3 * 5;
+var DEFAULT_HISTORY_TIME = 60 * 60 * 1e3;
+var MAX_GC_FREQUENCY = 1e3 * 60;
+var MIN_GC_FREQUENCY = 1e3;
+var MIN_HISTORY_INTERVAL = 1e3;
+var Base = class _Base {
+  static defaultLogger;
+  static globalInstances = {};
+  static globalInstancesCountHistory = {};
+  static uniqueName = globallyUnique(this.name, this, "xyo");
+  static _historyInterval = DEFAULT_HISTORY_INTERVAL;
+  static _historyTime = DEFAULT_HISTORY_TIME;
+  static _historyTimeout;
+  static _lastGC = 0;
+  static _maxGcFrequency = MAX_GC_FREQUENCY;
+  _params;
+  constructor(params) {
+    this._params = params;
+    params?.logger?.debug(`Base constructed [${Object(this).name}]`);
+    this.recordInstance();
+  }
+  static get historyInterval() {
+    return this._historyInterval;
+  }
+  static set historyInterval(value) {
+    assertEx(value <= this.historyTime, () => `historyInterval [${value}] must be less than or equal to historyTime [${this.historyTime}]`);
+    this._historyInterval = Math.max(value, MIN_HISTORY_INTERVAL);
+  }
+  static get historyTime() {
+    return this._historyTime;
+  }
+  static set historyTime(value) {
+    assertEx(value >= this.historyInterval, () => `historyTime [${value}] must be greater than or equal to historyInterval [${this.historyInterval}]`);
+    this._historyInterval = value;
+  }
+  static get maxGcFrequency() {
+    return this._maxGcFrequency;
+  }
+  static set maxGcFrequency(value) {
+    this._maxGcFrequency = Math.max(value, MIN_GC_FREQUENCY);
+  }
+  static get maxHistoryDepth() {
+    return Math.floor(this.historyTime / this.historyInterval);
+  }
+  get logger() {
+    return this.params?.logger ?? _Base.defaultLogger;
+  }
+  get params() {
+    return this._params;
+  }
+  static gc(classNameOrForce = false) {
+    if (typeof classNameOrForce === "string") {
+      this.gcClass(classNameOrForce);
+    } else {
+      if (classNameOrForce || Date.now() - this._lastGC > this._maxGcFrequency) {
+        this.gcAll();
+      }
+    }
+  }
+  static instanceCount(className) {
+    return this.globalInstances[className]?.length ?? 0;
+  }
+  static instanceCounts() {
+    this.gc();
+    const result = {};
+    for (const [className, instances] of Object.entries(this.globalInstances)) result[className] = instances.length;
+    return result;
+  }
+  static startHistory() {
+    if (this._historyTimeout) {
+      this.stopHistory();
+    }
+    const timeoutHandler = () => {
+      if (this._historyTimeout) {
+        this.addToHistory();
+        this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval);
+      }
+    };
+    this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval);
+  }
+  static stopHistory() {
+    if (this._historyTimeout) {
+      clearTimeout(this._historyTimeout);
+      this._historyTimeout = void 0;
+    }
+  }
+  static addToHistory() {
+    const counts = this.instanceCounts();
+    for (const className of Object.keys(this.globalInstances)) {
+      this.globalInstancesCountHistory[className] = this.globalInstancesCountHistory[className]?.slice(-this.maxHistoryDepth) ?? [];
+      this.globalInstancesCountHistory[className].push(counts[className]);
+    }
+  }
+  static gcAll() {
+    for (const className of Object.keys(this.globalInstances)) {
+      this.gcClass(className);
+    }
+  }
+  static gcClass(className) {
+    this.globalInstances[className] = this.globalInstances[className]?.filter((ref) => ref.deref() !== null) ?? [];
+  }
+  recordInstance() {
+    const instanceArray = _Base.globalInstances[this.constructor.name] ?? [];
+    instanceArray.push(new WeakRef(this));
+    _Base.globalInstances[this.constructor.name] = instanceArray;
+  }
+};
+export {
+  Base,
+  disableGloballyUnique,
+  globallyUnique
+};
+//# sourceMappingURL=index.mjs.map

package/dist/neutral/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/Base.ts","../../src/globallyUnique.ts"],"sourcesContent":["import { assertEx } from '@xylabs/assert'\nimport type { Logger } from '@xylabs/logger'\nimport type { EmptyObject } from '@xylabs/object'\n\nimport { globallyUnique } from './globallyUnique.ts'\n\nconst DEFAULT_HISTORY_INTERVAL = 1000 * 5\nconst DEFAULT_HISTORY_TIME = 60 * 60 * 1000\nconst MAX_GC_FREQUENCY = 1000 * 60\nconst MIN_GC_FREQUENCY = 1000\nconst MIN_HISTORY_INTERVAL = 1000\n\nexport type BaseClassName = Exclude<string, 'base-class-name-reserved-32546239486'>\n\nexport type BaseParamsFields = {\n  logger?: Logger\n}\n\nexport type BaseParams<TAdditionalParams extends EmptyObject | void = void> =\n  TAdditionalParams extends EmptyObject ? BaseParamsFields & TAdditionalParams : BaseParamsFields\n\nexport abstract class Base<TParams extends BaseParams | undefined = BaseParams> {\n  static defaultLogger?: Logger\n  static readonly globalInstances: Record<BaseClassName, WeakRef<Base<BaseParams | undefined>>[]> = {}\n  static readonly globalInstancesCountHistory: Record<BaseClassName, number[]> = {}\n  static readonly uniqueName = globallyUnique(this.name, this, 'xyo')\n  private static _historyInterval = DEFAULT_HISTORY_INTERVAL\n  private static _historyTime = DEFAULT_HISTORY_TIME\n  private static _historyTimeout?: ReturnType<typeof setTimeout>\n  private static _lastGC = 0\n  private static _maxGcFrequency = MAX_GC_FREQUENCY\n  private _params: TParams\n\n  constructor(params: TParams) {\n    this._params = params\n    params?.logger?.debug(`Base constructed [${Object(this).name}]`)\n    this.recordInstance()\n  }\n\n  static get historyInterval() {\n    return this._historyInterval\n  }\n\n  static set historyInterval(value: number) {\n    assertEx(value <= this.historyTime, () => `historyInterval [${value}] must be less than or equal to historyTime [${this.historyTime}]`)\n    this._historyInterval = Math.max(value, MIN_HISTORY_INTERVAL)\n  }\n\n  static get historyTime() {\n    return this._historyTime\n  }\n\n  static set historyTime(value: number) {\n    assertEx(value >= this.historyInterval, () => `historyTime [${value}] must be greater than or equal to historyInterval [${this.historyInterval}]`)\n    this._historyInterval = value\n  }\n\n  static get maxGcFrequency() {\n    return this._maxGcFrequency\n  }\n\n  static set maxGcFrequency(value: number) {\n    this._maxGcFrequency = Math.max(value, MIN_GC_FREQUENCY)\n  }\n\n  static get maxHistoryDepth() {\n    return Math.floor(this.historyTime / this.historyInterval)\n  }\n\n  get logger() {\n    return this.params?.logger ?? Base.defaultLogger\n  }\n\n  get params() {\n    return this._params\n  }\n\n  static gc(force?: boolean): void\n  static gc(className: string): void\n  static gc(classNameOrForce: string | boolean = false): void {\n    if (typeof classNameOrForce === 'string') {\n      this.gcClass(classNameOrForce)\n    } else {\n      if (classNameOrForce || Date.now() - this._lastGC > this._maxGcFrequency) {\n        this.gcAll()\n      }\n    }\n  }\n\n  static instanceCount(className: string): number {\n    return this.globalInstances[className]?.length ?? 0\n  }\n\n  static instanceCounts(): Record<BaseClassName, number> {\n    this.gc()\n    const result: Record<BaseClassName, number> = {}\n    for (const [className, instances] of Object.entries(this.globalInstances)) result[className] = instances.length\n    return result\n  }\n\n  static startHistory(): void {\n    if (this._historyTimeout) {\n      this.stopHistory()\n    }\n\n    const timeoutHandler = () => {\n      if (this._historyTimeout) {\n        this.addToHistory()\n        this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval)\n      }\n    }\n\n    this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval)\n  }\n\n  static stopHistory(): void {\n    if (this._historyTimeout) {\n      clearTimeout(this._historyTimeout)\n      this._historyTimeout = undefined\n    }\n  }\n\n  private static addToHistory() {\n    const counts = this.instanceCounts()\n    for (const className of Object.keys(this.globalInstances)) {\n      this.globalInstancesCountHistory[className] = this.globalInstancesCountHistory[className]?.slice(-this.maxHistoryDepth) ?? []\n      this.globalInstancesCountHistory[className].push(counts[className])\n    }\n  }\n\n  private static gcAll() {\n    for (const className of Object.keys(this.globalInstances)) {\n      this.gcClass(className)\n    }\n  }\n\n  private static gcClass(className: BaseClassName) {\n    // remove all the weak refs that are now empty\n    this.globalInstances[className] = this.globalInstances[className]?.filter(ref => ref.deref() !== null) ?? []\n  }\n\n  private recordInstance() {\n    const instanceArray = Base.globalInstances[this.constructor.name] ?? []\n    instanceArray.push(new WeakRef(this))\n    Base.globalInstances[this.constructor.name] = instanceArray\n  }\n}\n","declare global {\n  var xylabs: {\n    unique: Record<string, unknown>\n    uniqueDisabled?: boolean\n  }\n}\n\nconst xyoGlobal = () => {\n  globalThis.xylabs = globalThis.xylabs ?? {}\n  return globalThis.xylabs\n}\n\nexport const disableGloballyUnique = () => {\n  xyoGlobal().uniqueDisabled = true\n}\n\nexport const globallyUnique = (name: string, value: unknown, domain = 'global') => {\n  const uniqueName = [domain, name].join(':')\n  if (!xyoGlobal().uniqueDisabled) {\n    const xylabs = globalThis.xylabs = globalThis.xylabs ?? {}\n    const unique = (xylabs.unique = xylabs.unique ?? {})\n    if (unique[uniqueName] === undefined) {\n      unique[uniqueName] = value\n    } else {\n      if (unique[uniqueName] !== value) {\n        throw new Error(\n          `Global unique item ${uniqueName} already defined.  Make sure you are not importing two versions of the package that contains this item`,\n        )\n      }\n    }\n  }\n  return uniqueName\n}\n"],"mappings":"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","names":[]}

package/dist/types/Base.d.ts

@@ -0,0 +1,40 @@
+import type { Logger } from '@xylabs/logger';
+import type { EmptyObject } from '@xylabs/object';
+export type BaseClassName = Exclude<string, 'base-class-name-reserved-32546239486'>;
+export type BaseParamsFields = {
+    logger?: Logger;
+};
+export type BaseParams<TAdditionalParams extends EmptyObject | void = void> = TAdditionalParams extends EmptyObject ? BaseParamsFields & TAdditionalParams : BaseParamsFields;
+export declare abstract class Base<TParams extends BaseParams | undefined = BaseParams> {
+    static defaultLogger?: Logger;
+    static readonly globalInstances: Record<BaseClassName, WeakRef<Base<BaseParams | undefined>>[]>;
+    static readonly globalInstancesCountHistory: Record<BaseClassName, number[]>;
+    static readonly uniqueName: string;
+    private static _historyInterval;
+    private static _historyTime;
+    private static _historyTimeout?;
+    private static _lastGC;
+    private static _maxGcFrequency;
+    private _params;
+    constructor(params: TParams);
+    static get historyInterval(): number;
+    static set historyInterval(value: number);
+    static get historyTime(): number;
+    static set historyTime(value: number);
+    static get maxGcFrequency(): number;
+    static set maxGcFrequency(value: number);
+    static get maxHistoryDepth(): number;
+    get logger(): Logger | undefined;
+    get params(): TParams;
+    static gc(force?: boolean): void;
+    static gc(className: string): void;
+    static instanceCount(className: string): number;
+    static instanceCounts(): Record<BaseClassName, number>;
+    static startHistory(): void;
+    static stopHistory(): void;
+    private static addToHistory;
+    private static gcAll;
+    private static gcClass;
+    private recordInstance;
+}
+//# sourceMappingURL=Base.d.ts.map

package/dist/types/Base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Base.d.ts","sourceRoot":"","sources":["../../src/Base.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAUjD,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,sCAAsC,CAAC,CAAA;AAEnF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,UAAU,CAAC,iBAAiB,SAAS,WAAW,GAAG,IAAI,GAAG,IAAI,IACxE,iBAAiB,SAAS,WAAW,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,gBAAgB,CAAA;AAEjG,8BAAsB,IAAI,CAAC,OAAO,SAAS,UAAU,GAAG,SAAS,GAAG,UAAU;IAC5E,MAAM,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC7B,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC,CAAK;IACpG,MAAM,CAAC,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC,CAAK;IACjF,MAAM,CAAC,QAAQ,CAAC,UAAU,SAAyC;IACnE,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAA2B;IAC1D,OAAO,CAAC,MAAM,CAAC,YAAY,CAAuB;IAClD,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAA+B;IAC9D,OAAO,CAAC,MAAM,CAAC,OAAO,CAAI;IAC1B,OAAO,CAAC,MAAM,CAAC,eAAe,CAAmB;IACjD,OAAO,CAAC,OAAO,CAAS;gBAEZ,MAAM,EAAE,OAAO;IAM3B,MAAM,KAAK,eAAe,IAIQ,MAAM,CAFvC;IAED,MAAM,KAAK,eAAe,CAAC,KAAK,EAAE,MAAM,EAGvC;IAED,MAAM,KAAK,WAAW,IAIQ,MAAM,CAFnC;IAED,MAAM,KAAK,WAAW,CAAC,KAAK,EAAE,MAAM,EAGnC;IAED,MAAM,KAAK,cAAc,IAIQ,MAAM,CAFtC;IAED,MAAM,KAAK,cAAc,CAAC,KAAK,EAAE,MAAM,EAEtC;IAED,MAAM,KAAK,eAAe,WAEzB;IAED,IAAI,MAAM,uBAET;IAED,IAAI,MAAM,YAET;IAED,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI;IAChC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAWlC,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAI/C,MAAM,CAAC,cAAc,IAAI,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC;IAOtD,MAAM,CAAC,YAAY,IAAI,IAAI;IAe3B,MAAM,CAAC,WAAW,IAAI,IAAI;IAO1B,OAAO,CAAC,MAAM,CAAC,YAAY;IAQ3B,OAAO,CAAC,MAAM,CAAC,KAAK;IAMpB,OAAO,CAAC,MAAM,CAAC,OAAO;IAKtB,OAAO,CAAC,cAAc;CAKvB"}

package/dist/types/globallyUnique.d.ts

@@ -0,0 +1,9 @@
+declare global {
+    var xylabs: {
+        unique: Record<string, unknown>;
+        uniqueDisabled?: boolean;
+    };
+}
+export declare const disableGloballyUnique: () => void;
+export declare const globallyUnique: (name: string, value: unknown, domain?: string) => string;
+//# sourceMappingURL=globallyUnique.d.ts.map

package/dist/types/globallyUnique.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globallyUnique.d.ts","sourceRoot":"","sources":["../../src/globallyUnique.ts"],"names":[],"mappings":"AAAA,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,MAAM,EAAE;QACV,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QAC/B,cAAc,CAAC,EAAE,OAAO,CAAA;KACzB,CAAA;CACF;AAOD,eAAO,MAAM,qBAAqB,YAEjC,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,OAAO,OAAO,EAAE,eAAiB,WAgB7E,CAAA"}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './Base.ts';
+export * from './globallyUnique.ts';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,qBAAqB,CAAA"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@xylabs/base",
+  "version": "4.8.0",
+  "description": "Primary SDK for using XYO Protocol 2.0",
+  "homepage": "https://xyo.network",
+  "bugs": {
+    "url": "git+https://github.com/XYOracleNetwork/sdk-xyo-client-js/issues",
+    "email": "support@xyo.network"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XYOracleNetwork/sdk-xyo-client-js.git"
+  },
+  "license": "LGPL-3.0-or-later",
+  "author": {
+    "name": "XYO Development Team",
+    "email": "support@xyo.network",
+    "url": "https://xyo.network"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/neutral/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "module": "dist/neutral/index.mjs",
+  "types": "dist/types/index.d.ts",
+  "dependencies": {
+    "@xylabs/assert": "^4.8.0",
+    "@xylabs/logger": "^4.8.0",
+    "@xylabs/object": "^4.8.0"
+  },
+  "devDependencies": {
+    "@xylabs/ts-scripts-yarn3": "^6.2.1",
+    "@xylabs/tsconfig": "^6.2.1",
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Base.ts

@@ -0,0 +1,147 @@
+import { assertEx } from '@xylabs/assert'
+import type { Logger } from '@xylabs/logger'
+import type { EmptyObject } from '@xylabs/object'
+
+import { globallyUnique } from './globallyUnique.ts'
+
+const DEFAULT_HISTORY_INTERVAL = 1000 * 5
+const DEFAULT_HISTORY_TIME = 60 * 60 * 1000
+const MAX_GC_FREQUENCY = 1000 * 60
+const MIN_GC_FREQUENCY = 1000
+const MIN_HISTORY_INTERVAL = 1000
+
+export type BaseClassName = Exclude<string, 'base-class-name-reserved-32546239486'>
+
+export type BaseParamsFields = {
+  logger?: Logger
+}
+
+export type BaseParams<TAdditionalParams extends EmptyObject | void = void> =
+  TAdditionalParams extends EmptyObject ? BaseParamsFields & TAdditionalParams : BaseParamsFields
+
+export abstract class Base<TParams extends BaseParams | undefined = BaseParams> {
+  static defaultLogger?: Logger
+  static readonly globalInstances: Record<BaseClassName, WeakRef<Base<BaseParams | undefined>>[]> = {}
+  static readonly globalInstancesCountHistory: Record<BaseClassName, number[]> = {}
+  static readonly uniqueName = globallyUnique(this.name, this, 'xyo')
+  private static _historyInterval = DEFAULT_HISTORY_INTERVAL
+  private static _historyTime = DEFAULT_HISTORY_TIME
+  private static _historyTimeout?: ReturnType<typeof setTimeout>
+  private static _lastGC = 0
+  private static _maxGcFrequency = MAX_GC_FREQUENCY
+  private _params: TParams
+
+  constructor(params: TParams) {
+    this._params = params
+    params?.logger?.debug(`Base constructed [${Object(this).name}]`)
+    this.recordInstance()
+  }
+
+  static get historyInterval() {
+    return this._historyInterval
+  }
+
+  static set historyInterval(value: number) {
+    assertEx(value <= this.historyTime, () => `historyInterval [${value}] must be less than or equal to historyTime [${this.historyTime}]`)
+    this._historyInterval = Math.max(value, MIN_HISTORY_INTERVAL)
+  }
+
+  static get historyTime() {
+    return this._historyTime
+  }
+
+  static set historyTime(value: number) {
+    assertEx(value >= this.historyInterval, () => `historyTime [${value}] must be greater than or equal to historyInterval [${this.historyInterval}]`)
+    this._historyInterval = value
+  }
+
+  static get maxGcFrequency() {
+    return this._maxGcFrequency
+  }
+
+  static set maxGcFrequency(value: number) {
+    this._maxGcFrequency = Math.max(value, MIN_GC_FREQUENCY)
+  }
+
+  static get maxHistoryDepth() {
+    return Math.floor(this.historyTime / this.historyInterval)
+  }
+
+  get logger() {
+    return this.params?.logger ?? Base.defaultLogger
+  }
+
+  get params() {
+    return this._params
+  }
+
+  static gc(force?: boolean): void
+  static gc(className: string): void
+  static gc(classNameOrForce: string | boolean = false): void {
+    if (typeof classNameOrForce === 'string') {
+      this.gcClass(classNameOrForce)
+    } else {
+      if (classNameOrForce || Date.now() - this._lastGC > this._maxGcFrequency) {
+        this.gcAll()
+      }
+    }
+  }
+
+  static instanceCount(className: string): number {
+    return this.globalInstances[className]?.length ?? 0
+  }
+
+  static instanceCounts(): Record<BaseClassName, number> {
+    this.gc()
+    const result: Record<BaseClassName, number> = {}
+    for (const [className, instances] of Object.entries(this.globalInstances)) result[className] = instances.length
+    return result
+  }
+
+  static startHistory(): void {
+    if (this._historyTimeout) {
+      this.stopHistory()
+    }
+
+    const timeoutHandler = () => {
+      if (this._historyTimeout) {
+        this.addToHistory()
+        this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval)
+      }
+    }
+
+    this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval)
+  }
+
+  static stopHistory(): void {
+    if (this._historyTimeout) {
+      clearTimeout(this._historyTimeout)
+      this._historyTimeout = undefined
+    }
+  }
+
+  private static addToHistory() {
+    const counts = this.instanceCounts()
+    for (const className of Object.keys(this.globalInstances)) {
+      this.globalInstancesCountHistory[className] = this.globalInstancesCountHistory[className]?.slice(-this.maxHistoryDepth) ?? []
+      this.globalInstancesCountHistory[className].push(counts[className])
+    }
+  }
+
+  private static gcAll() {
+    for (const className of Object.keys(this.globalInstances)) {
+      this.gcClass(className)
+    }
+  }
+
+  private static gcClass(className: BaseClassName) {
+    // remove all the weak refs that are now empty
+    this.globalInstances[className] = this.globalInstances[className]?.filter(ref => ref.deref() !== null) ?? []
+  }
+
+  private recordInstance() {
+    const instanceArray = Base.globalInstances[this.constructor.name] ?? []
+    instanceArray.push(new WeakRef(this))
+    Base.globalInstances[this.constructor.name] = instanceArray
+  }
+}

package/src/globallyUnique.ts

@@ -0,0 +1,33 @@
+declare global {
+  var xylabs: {
+    unique: Record<string, unknown>
+    uniqueDisabled?: boolean
+  }
+}
+
+const xyoGlobal = () => {
+  globalThis.xylabs = globalThis.xylabs ?? {}
+  return globalThis.xylabs
+}
+
+export const disableGloballyUnique = () => {
+  xyoGlobal().uniqueDisabled = true
+}
+
+export const globallyUnique = (name: string, value: unknown, domain = 'global') => {
+  const uniqueName = [domain, name].join(':')
+  if (!xyoGlobal().uniqueDisabled) {
+    const xylabs = globalThis.xylabs = globalThis.xylabs ?? {}
+    const unique = (xylabs.unique = xylabs.unique ?? {})
+    if (unique[uniqueName] === undefined) {
+      unique[uniqueName] = value
+    } else {
+      if (unique[uniqueName] !== value) {
+        throw new Error(
+          `Global unique item ${uniqueName} already defined.  Make sure you are not importing two versions of the package that contains this item`,
+        )
+      }
+    }
+  }
+  return uniqueName
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './Base.ts'
+export * from './globallyUnique.ts'

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts"],
+  "tsconfig": "./tsconfig.typedoc.json"
+}

package/xy.config.ts

@@ -0,0 +1,10 @@
+import type { XyTsupConfig } from '@xylabs/ts-scripts-yarn3'
+const config: XyTsupConfig = {
+  compile: {
+    browser: {},
+    neutral: { src: true },
+    node: {},
+  },
+}
+
+export default config