@xylabs/base 5.0.80 → 5.0.82

package/README.md

@@ -24,6 +24,7 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 ## Classes
 
 - [Base](#classes/Base)
+- [UniqueBase](#classes/UniqueBase)
 
 ## Type Aliases
 
@@ -44,6 +45,10 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ***
 
+## Extended by
+
+- [`UniqueBase`](#UniqueBase)
+
 ## Type Parameters
 
 ### TParams
@@ -92,6 +97,338 @@ readonly static globalInstances: Record<BaseClassName, WeakRef<Base>[]> = {};
 readonly static globalInstancesCountHistory: Record<BaseClassName, number[]> = {};
 ```
 
+## Accessors
+
+### historyInterval
+
+### Get Signature
+
+```ts
+get static historyInterval(): number;
+```
+
+#### Returns
+
+`number`
+
+### Set Signature
+
+```ts
+set static historyInterval(value): void;
+```
+
+#### Parameters
+
+##### value
+
+`number`
+
+#### Returns
+
+`void`
+
+***
+
+### historyTime
+
+### Get Signature
+
+```ts
+get static historyTime(): number;
+```
+
+#### Returns
+
+`number`
+
+### Set Signature
+
+```ts
+set static historyTime(value): void;
+```
+
+#### Parameters
+
+##### value
+
+`number`
+
+#### Returns
+
+`void`
+
+***
+
+### maxGcFrequency
+
+### Get Signature
+
+```ts
+get static maxGcFrequency(): number;
+```
+
+#### Returns
+
+`number`
+
+### Set Signature
+
+```ts
+set static maxGcFrequency(value): void;
+```
+
+#### Parameters
+
+##### value
+
+`number`
+
+#### Returns
+
+`void`
+
+***
+
+### maxHistoryDepth
+
+### Get Signature
+
+```ts
+get static maxHistoryDepth(): number;
+```
+
+#### Returns
+
+`number`
+
+***
+
+### logger
+
+### Get Signature
+
+```ts
+get logger(): Logger | undefined;
+```
+
+#### Returns
+
+`Logger` \| `undefined`
+
+***
+
+### meter
+
+### Get Signature
+
+```ts
+get meter(): Meter | undefined;
+```
+
+#### Returns
+
+`Meter` \| `undefined`
+
+***
+
+### params
+
+### Get Signature
+
+```ts
+get params(): BaseParams<TParams>;
+```
+
+#### Returns
+
+[`BaseParams`](#../type-aliases/BaseParams)\<`TParams`\>
+
+***
+
+### tracer
+
+### Get Signature
+
+```ts
+get tracer(): Tracer | undefined;
+```
+
+#### Returns
+
+`Tracer` \| `undefined`
+
+## Methods
+
+### gc()
+
+### Call Signature
+
+```ts
+static gc(force?): void;
+```
+
+#### Parameters
+
+##### force?
+
+`boolean`
+
+#### Returns
+
+`void`
+
+### Call Signature
+
+```ts
+static gc(className): void;
+```
+
+#### Parameters
+
+##### className
+
+[`BaseClassName`](#../type-aliases/BaseClassName)
+
+#### Returns
+
+`void`
+
+***
+
+### instanceCount()
+
+```ts
+static instanceCount(className): number;
+```
+
+### Parameters
+
+#### className
+
+[`BaseClassName`](#../type-aliases/BaseClassName)
+
+### Returns
+
+`number`
+
+***
+
+### instanceCounts()
+
+```ts
+static instanceCounts(): Record<BaseClassName, number>;
+```
+
+### Returns
+
+`Record`\<[`BaseClassName`](#../type-aliases/BaseClassName), `number`\>
+
+***
+
+### startHistory()
+
+```ts
+static startHistory(): void;
+```
+
+### Returns
+
+`void`
+
+***
+
+### stopHistory()
+
+```ts
+static stopHistory(): void;
+```
+
+### Returns
+
+`void`
+
+  ### <a id="UniqueBase"></a>UniqueBase
+
+[**@xylabs/base**](#../README)
+
+***
+
+## Extends
+
+- [`Base`](#Base)\<`TParams`\>
+
+## Type Parameters
+
+### TParams
+
+`TParams` *extends* [`BaseParams`](#../type-aliases/BaseParams) = [`BaseParams`](#../type-aliases/BaseParams)
+
+## Constructors
+
+### Constructor
+
+```ts
+new UniqueBase<TParams>(params): UniqueBase<TParams>;
+```
+
+### Parameters
+
+#### params
+
+[`BaseParams`](#../type-aliases/BaseParams)\<`TParams`\>
+
+### Returns
+
+`UniqueBase`\<`TParams`\>
+
+### Overrides
+
+[`Base`](#Base).[`constructor`](Base.md#constructor)
+
+## Properties
+
+### defaultLogger?
+
+```ts
+static optional defaultLogger: Logger;
+```
+
+### Inherited from
+
+[`Base`](#Base).[`defaultLogger`](Base.md#defaultlogger)
+
+***
+
+### globalInstances
+
+```ts
+readonly static globalInstances: Record<BaseClassName, WeakRef<Base>[]> = {};
+```
+
+### Inherited from
+
+[`Base`](#Base).[`globalInstances`](Base.md#globalinstances)
+
+***
+
+### globalInstancesCountHistory
+
+```ts
+readonly static globalInstancesCountHistory: Record<BaseClassName, number[]> = {};
+```
+
+### Inherited from
+
+[`Base`](#Base).[`globalInstancesCountHistory`](Base.md#globalinstancescounthistory)
+
+***
+
+### uniqueDomain
+
+```ts
+readonly static uniqueDomain: "xy" = 'xy';
+```
+
 ***
 
 ### uniqueName
@@ -100,6 +437,14 @@ readonly static globalInstancesCountHistory: Record<BaseClassName, number[]> = {
 readonly static uniqueName: string;
 ```
 
+***
+
+### uniqueNameXyo
+
+```ts
+readonly static uniqueNameXyo: string;
+```
+
 ## Accessors
 
 ### historyInterval
@@ -130,6 +475,10 @@ set static historyInterval(value): void;
 
 `void`
 
+### Inherited from
+
+[`Base`](#Base).[`historyInterval`](Base.md#historyinterval)
+
 ***
 
 ### historyTime
@@ -160,6 +509,10 @@ set static historyTime(value): void;
 
 `void`
 
+### Inherited from
+
+[`Base`](#Base).[`historyTime`](Base.md#historytime)
+
 ***
 
 ### maxGcFrequency
@@ -190,6 +543,10 @@ set static maxGcFrequency(value): void;
 
 `void`
 
+### Inherited from
+
+[`Base`](#Base).[`maxGcFrequency`](Base.md#maxgcfrequency)
+
 ***
 
 ### maxHistoryDepth
@@ -204,6 +561,10 @@ get static maxHistoryDepth(): number;
 
 `number`
 
+### Inherited from
+
+[`Base`](#Base).[`maxHistoryDepth`](Base.md#maxhistorydepth)
+
 ***
 
 ### logger
@@ -211,12 +572,16 @@ get static maxHistoryDepth(): number;
 ### Get Signature
 
 ```ts
-get logger(): undefined | Logger;
+get logger(): Logger | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Logger`
+`Logger` \| `undefined`
+
+### Inherited from
+
+[`Base`](#Base).[`logger`](Base.md#logger)
 
 ***
 
@@ -225,12 +590,16 @@ get logger(): undefined | Logger;
 ### Get Signature
 
 ```ts
-get meter(): undefined | Meter;
+get meter(): Meter | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Meter`
+`Meter` \| `undefined`
+
+### Inherited from
+
+[`Base`](#Base).[`meter`](Base.md#meter)
 
 ***
 
@@ -246,6 +615,10 @@ get params(): BaseParams<TParams>;
 
 [`BaseParams`](#../type-aliases/BaseParams)\<`TParams`\>
 
+### Inherited from
+
+[`Base`](#Base).[`params`](Base.md#params)
+
 ***
 
 ### tracer
@@ -253,12 +626,16 @@ get params(): BaseParams<TParams>;
 ### Get Signature
 
 ```ts
-get tracer(): undefined | Tracer;
+get tracer(): Tracer | undefined;
 ```
 
 #### Returns
 
-`undefined` \| `Tracer`
+`Tracer` \| `undefined`
+
+### Inherited from
+
+[`Base`](#Base).[`tracer`](Base.md#tracer)
 
 ## Methods
 
@@ -280,6 +657,10 @@ static gc(force?): void;
 
 `void`
 
+#### Inherited from
+
+[`Base`](#Base).[`gc`](Base.md#gc)
+
 ### Call Signature
 
 ```ts
@@ -290,12 +671,16 @@ static gc(className): void;
 
 ##### className
 
-`string`
+[`BaseClassName`](#../type-aliases/BaseClassName)
 
 #### Returns
 
 `void`
 
+#### Inherited from
+
+[`Base`](#Base).[`gc`](Base.md#gc)
+
 ***
 
 ### instanceCount()
@@ -308,12 +693,16 @@ static instanceCount(className): number;
 
 #### className
 
-`string`
+[`BaseClassName`](#../type-aliases/BaseClassName)
 
 ### Returns
 
 `number`
 
+### Inherited from
+
+[`Base`](#Base).[`instanceCount`](Base.md#instancecount)
+
 ***
 
 ### instanceCounts()
@@ -326,6 +715,10 @@ static instanceCounts(): Record<BaseClassName, number>;
 
 `Record`\<[`BaseClassName`](#../type-aliases/BaseClassName), `number`\>
 
+### Inherited from
+
+[`Base`](#Base).[`instanceCounts`](Base.md#instancecounts)
+
 ***
 
 ### startHistory()
@@ -338,6 +731,10 @@ static startHistory(): void;
 
 `void`
 
+### Inherited from
+
+[`Base`](#Base).[`startHistory`](Base.md#starthistory)
+
 ***
 
 ### stopHistory()
@@ -350,6 +747,10 @@ static stopHistory(): void;
 
 `void`
 
+### Inherited from
+
+[`Base`](#Base).[`stopHistory`](Base.md#stophistory)
+
 ### functions
 
   ### <a id="disableGloballyUnique"></a>disableGloballyUnique
@@ -376,20 +777,20 @@ function disableGloballyUnique(): void;
 function globallyUnique(
    name, 
    value, 
-   domain): string;
+   domain?): string;
 ```
 
 ## Parameters
 
 ### name
 
-`string`
+`string` | `symbol`
 
 ### value
 
 `unknown`
 
-### domain
+### domain?
 
 `string` = `'global'`
 
@@ -406,7 +807,15 @@ function globallyUnique(
 ***
 
 ```ts
-type BaseClassName = Exclude<string, "base-class-name-reserved-32546239486">;
+type BaseClassName = string & object;
+```
+
+## Type Declaration
+
+### \_\_baseClassName
+
+```ts
+__baseClassName: true;
 ```
 
   ### <a id="BaseParams"></a>BaseParams

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/base",
-  "version": "5.0.80",
+  "version": "5.0.82",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "homepage": "https://xyo.network",
   "bugs": {
@@ -22,32 +22,29 @@
   "exports": {
     ".": {
       "types": "./dist/neutral/index.d.ts",
-      "source": "./src/index.ts",
       "default": "./dist/neutral/index.mjs"
     },
     "./package.json": "./package.json"
   },
   "module": "./dist/neutral/index.mjs",
-  "source": "./src/index.ts",
   "types": "./dist/neutral/index.d.ts",
   "files": [
     "dist",
-    "src",
     "!**/*.bench.*",
     "!**/*.spec.*",
     "!**/*.test.*"
   ],
   "dependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@xylabs/assert": "~5.0.80",
-    "@xylabs/logger": "~5.0.80",
-    "@xylabs/object": "~5.0.80"
+    "@xylabs/assert": "~5.0.82",
+    "@xylabs/logger": "~5.0.82",
+    "@xylabs/object": "~5.0.82"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "~7.3.2",
-    "@xylabs/tsconfig": "~7.3.2",
-    "tslib": "~2.8.1",
-    "typescript": "~5.9.3"
+    "@xylabs/ts-scripts-yarn3": "~7.4.11",
+    "@xylabs/tsconfig": "~7.4.11",
+    "typescript": "~5.9.3",
+    "vitest": "~4.0.18"
   },
   "publishConfig": {
     "access": "public"

package/src/Base.ts

@@ -1,158 +0,0 @@
-import type {
-  Meter,
-  MeterProvider, Tracer, TracerProvider,
-} from '@opentelemetry/api'
-import { assertEx } from '@xylabs/assert'
-import type { Logger } from '@xylabs/logger'
-import type { EmptyObject } from '@xylabs/object'
-
-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 = string & { __baseClassName: true }
-
-export type BaseParamsFields = {
-  logger?: Logger
-  meterProvider?: MeterProvider
-  traceProvider?: TracerProvider
-}
-
-export type BaseParams<TAdditionalParams extends EmptyObject = EmptyObject> = TAdditionalParams & BaseParamsFields
-
-export abstract class Base<TParams extends BaseParams = BaseParams> {
-  static defaultLogger?: Logger
-  static readonly globalInstances: Record<BaseClassName, WeakRef<Base>[]> = {}
-  static readonly globalInstancesCountHistory: Record<BaseClassName, number[]> = {}
-  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: BaseParams<TParams>
-
-  constructor(params: BaseParams<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 meter(): Meter | undefined {
-    return this.params?.meterProvider?.getMeter(this.constructor.name)
-  }
-
-  get params() {
-    return this._params
-  }
-
-  get tracer(): Tracer | undefined {
-    return this.params?.traceProvider?.getTracer(this.constructor.name)
-  }
-
-  static gc(force?: boolean): void
-  static gc(className: BaseClassName): void
-  static gc(classNameOrForce: BaseClassName | boolean = false): void {
-    if (typeof classNameOrForce === 'string') {
-      this.gcClass(classNameOrForce)
-    } else {
-      if (classNameOrForce || Date.now() - this._lastGC > this._maxGcFrequency) {
-        this.gcAll()
-      }
-    }
-  }
-
-  static instanceCount(className: BaseClassName): 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 as BaseClassName] = 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) as BaseClassName[]) {
-      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) as BaseClassName[]) {
-      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 baseClassName = this.constructor.name as BaseClassName
-    const instanceArray = Base.globalInstances[baseClassName] ?? []
-    instanceArray.push(new WeakRef(this))
-    Base.globalInstances[baseClassName] = instanceArray
-  }
-}

package/src/UniqueBase.ts

@@ -1,13 +0,0 @@
-import type { BaseParams } from './Base.ts'
-import { Base } from './Base.ts'
-import { globallyUnique } from './globallyUnique.ts'
-
-export abstract class UniqueBase<TParams extends BaseParams = BaseParams> extends Base<TParams> {
-  static readonly uniqueDomain = 'xy'
-  static readonly uniqueName = globallyUnique(this.name, this, this.uniqueDomain)
-  // TODO: Remove xyo domain version when old xyo versions are no longer needed
-  static readonly uniqueNameXyo = globallyUnique(this.name, this, 'xyo')
-  constructor(params: BaseParams<TParams>) {
-    super(params)
-  }
-}

package/src/globallyUnique.ts

@@ -1,33 +0,0 @@
-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 | symbol, value: unknown, domain = 'global') => {
-  const uniqueName = domain === 'bundle' ? [domain, name].join(':') : [domain, import.meta.url, 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

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