@xylabs/base 5.0.84 → 5.0.86

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +117 -200
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -15,6 +15,8 @@
15
15
 
16
16
  Base functionality used throughout XY Labs TypeScript/JavaScript libraries
17
17
 
18
+
19
+
18
20
  ## Reference
19
21
 
20
22
  **@xylabs/base**
@@ -23,19 +25,25 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
23
25
 
24
26
  ## Classes
25
27
 
26
- - [Base](#classes/Base)
27
- - [UniqueBase](#classes/UniqueBase)
28
+ | Class | Description |
29
+ | ------ | ------ |
30
+ | [Base](#classes/Base) | Abstract base class providing logging, telemetry, and global instance tracking with WeakRef-based GC. |
31
+ | [UniqueBase](#classes/UniqueBase) | Base class that registers itself as globally unique, preventing duplicate module instances. |
28
32
 
29
33
  ## Type Aliases
30
34
 
31
- - [BaseClassName](#type-aliases/BaseClassName)
32
- - [BaseParamsFields](#type-aliases/BaseParamsFields)
33
- - [BaseParams](#type-aliases/BaseParams)
35
+ | Type Alias | Description |
36
+ | ------ | ------ |
37
+ | [BaseClassName](#type-aliases/BaseClassName) | Branded string type representing a class name used for global instance tracking. |
38
+ | [BaseParamsFields](#type-aliases/BaseParamsFields) | Common parameter fields available to all Base instances (logger, meter, tracer). |
39
+ | [BaseParams](#type-aliases/BaseParams) | Parameters for constructing a Base instance, combining BaseParamsFields with optional additional params. |
34
40
 
35
41
  ## Functions
36
42
 
37
- - [disableGloballyUnique](#functions/disableGloballyUnique)
38
- - [globallyUnique](#functions/globallyUnique)
43
+ | Function | Description |
44
+ | ------ | ------ |
45
+ | [disableGloballyUnique](#functions/disableGloballyUnique) | Disables global uniqueness checks, allowing duplicate registrations without throwing. |
46
+ | [globallyUnique](#functions/globallyUnique) | Registers a value as globally unique under the given name and domain. Throws if a different value is already registered under the same key. |
39
47
 
40
48
  ### classes
41
49
 
@@ -53,25 +61,23 @@ Abstract base class providing logging, telemetry, and global instance tracking w
53
61
 
54
62
  ## Type Parameters
55
63
 
56
- ### TParams
57
-
58
- `TParams` *extends* [`BaseParams`](#../type-aliases/BaseParams) = [`BaseParams`](#../type-aliases/BaseParams)
59
-
60
- The parameter type, extending BaseParams
64
+ | Type Parameter | Default type | Description |
65
+ | ------ | ------ | ------ |
66
+ | `TParams` *extends* [`BaseParams`](#../type-aliases/BaseParams) | [`BaseParams`](#../type-aliases/BaseParams) | The parameter type, extending BaseParams |
61
67
 
62
68
  ## Constructors
63
69
 
64
70
  ### Constructor
65
71
 
66
72
  ```ts
67
- new Base<TParams>(params): Base<TParams>;
73
+ new Base<TParams>(params: BaseParams<TParams>): Base<TParams>;
68
74
  ```
69
75
 
70
76
  ### Parameters
71
77
 
72
- #### params
73
-
74
- [`BaseParams`](#../type-aliases/BaseParams)\<`TParams`\>
78
+ | Parameter | Type |
79
+ | ------ | ------ |
80
+ | `params` | [`BaseParams`](#../type-aliases/BaseParams)\<`TParams`\> |
75
81
 
76
82
  ### Returns
77
83
 
@@ -79,27 +85,11 @@ new Base<TParams>(params): Base<TParams>;
79
85
 
80
86
  ## Properties
81
87
 
82
- ### defaultLogger?
83
-
84
- ```ts
85
- static optional defaultLogger: Logger;
86
- ```
87
-
88
- ***
89
-
90
- ### globalInstances
91
-
92
- ```ts
93
- readonly static globalInstances: Record<BaseClassName, WeakRef<Base>[]> = {};
94
- ```
95
-
96
- ***
97
-
98
- ### globalInstancesCountHistory
99
-
100
- ```ts
101
- readonly static globalInstancesCountHistory: Record<BaseClassName, number[]> = {};
102
- ```
88
+ | Property | Modifier | Type | Default value |
89
+ | ------ | ------ | ------ | ------ |
90
+ | <a id="defaultlogger"></a> `defaultLogger?` | `static` | `Logger` | `undefined` |
91
+ | <a id="globalinstances"></a> `globalInstances` | `readonly` | `Record`\<[`BaseClassName`](#../type-aliases/BaseClassName), `WeakRef`\<`Base`\>[]\> | `{}` |
92
+ | <a id="globalinstancescounthistory"></a> `globalInstancesCountHistory` | `readonly` | `Record`\<[`BaseClassName`](#../type-aliases/BaseClassName), `number`[]\> | `{}` |
103
93
 
104
94
  ## Accessors
105
95
 
@@ -118,14 +108,14 @@ get static historyInterval(): number;
118
108
  ### Set Signature
119
109
 
120
110
  ```ts
121
- set static historyInterval(value): void;
111
+ set static historyInterval(value: number): void;
122
112
  ```
123
113
 
124
114
  #### Parameters
125
115
 
126
- ##### value
127
-
128
- `number`
116
+ | Parameter | Type |
117
+ | ------ | ------ |
118
+ | `value` | `number` |
129
119
 
130
120
  #### Returns
131
121
 
@@ -148,14 +138,14 @@ get static historyTime(): number;
148
138
  ### Set Signature
149
139
 
150
140
  ```ts
151
- set static historyTime(value): void;
141
+ set static historyTime(value: number): void;
152
142
  ```
153
143
 
154
144
  #### Parameters
155
145
 
156
- ##### value
157
-
158
- `number`
146
+ | Parameter | Type |
147
+ | ------ | ------ |
148
+ | `value` | `number` |
159
149
 
160
150
  #### Returns
161
151
 
@@ -178,14 +168,14 @@ get static maxGcFrequency(): number;
178
168
  ### Set Signature
179
169
 
180
170
  ```ts
181
- set static maxGcFrequency(value): void;
171
+ set static maxGcFrequency(value: number): void;
182
172
  ```
183
173
 
184
174
  #### Parameters
185
175
 
186
- ##### value
187
-
188
- `number`
176
+ | Parameter | Type |
177
+ | ------ | ------ |
178
+ | `value` | `number` |
189
179
 
190
180
  #### Returns
191
181
 
@@ -268,14 +258,14 @@ get tracer(): Tracer | undefined;
268
258
  ### Call Signature
269
259
 
270
260
  ```ts
271
- static gc(force?): void;
261
+ static gc(force?: boolean): void;
272
262
  ```
273
263
 
274
264
  #### Parameters
275
265
 
276
- ##### force?
277
-
278
- `boolean`
266
+ | Parameter | Type |
267
+ | ------ | ------ |
268
+ | `force?` | `boolean` |
279
269
 
280
270
  #### Returns
281
271
 
@@ -284,14 +274,14 @@ static gc(force?): void;
284
274
  ### Call Signature
285
275
 
286
276
  ```ts
287
- static gc(className): void;
277
+ static gc(className: BaseClassName): void;
288
278
  ```
289
279
 
290
280
  #### Parameters
291
281
 
292
- ##### className
293
-
294
- [`BaseClassName`](#../type-aliases/BaseClassName)
282
+ | Parameter | Type |
283
+ | ------ | ------ |
284
+ | `className` | [`BaseClassName`](#../type-aliases/BaseClassName) |
295
285
 
296
286
  #### Returns
297
287
 
@@ -302,14 +292,14 @@ static gc(className): void;
302
292
  ### instanceCount()
303
293
 
304
294
  ```ts
305
- static instanceCount(className): number;
295
+ static instanceCount(className: BaseClassName): number;
306
296
  ```
307
297
 
308
298
  ### Parameters
309
299
 
310
- #### className
311
-
312
- [`BaseClassName`](#../type-aliases/BaseClassName)
300
+ | Parameter | Type |
301
+ | ------ | ------ |
302
+ | `className` | [`BaseClassName`](#../type-aliases/BaseClassName) |
313
303
 
314
304
  ### Returns
315
305
 
@@ -365,23 +355,23 @@ Base class that registers itself as globally unique, preventing duplicate module
365
355
 
366
356
  ## Type Parameters
367
357
 
368
- ### TParams
369
-
370
- `TParams` *extends* [`BaseParams`](#../type-aliases/BaseParams) = [`BaseParams`](#../type-aliases/BaseParams)
358
+ | Type Parameter | Default type |
359
+ | ------ | ------ |
360
+ | `TParams` *extends* [`BaseParams`](#../type-aliases/BaseParams) | [`BaseParams`](#../type-aliases/BaseParams) |
371
361
 
372
362
  ## Constructors
373
363
 
374
364
  ### Constructor
375
365
 
376
366
  ```ts
377
- new UniqueBase<TParams>(params): UniqueBase<TParams>;
367
+ new UniqueBase<TParams>(params: BaseParams<TParams>): UniqueBase<TParams>;
378
368
  ```
379
369
 
380
370
  ### Parameters
381
371
 
382
- #### params
383
-
384
- [`BaseParams`](#../type-aliases/BaseParams)\<`TParams`\>
372
+ | Parameter | Type |
373
+ | ------ | ------ |
374
+ | `params` | [`BaseParams`](#../type-aliases/BaseParams)\<`TParams`\> |
385
375
 
386
376
  ### Returns
387
377
 
@@ -393,63 +383,14 @@ new UniqueBase<TParams>(params): UniqueBase<TParams>;
393
383
 
394
384
  ## Properties
395
385
 
396
- ### defaultLogger?
397
-
398
- ```ts
399
- static optional defaultLogger: Logger;
400
- ```
401
-
402
- ### Inherited from
403
-
404
- [`Base`](#Base).[`defaultLogger`](Base.md#defaultlogger)
405
-
406
- ***
407
-
408
- ### globalInstances
409
-
410
- ```ts
411
- readonly static globalInstances: Record<BaseClassName, WeakRef<Base>[]> = {};
412
- ```
413
-
414
- ### Inherited from
415
-
416
- [`Base`](#Base).[`globalInstances`](Base.md#globalinstances)
417
-
418
- ***
419
-
420
- ### globalInstancesCountHistory
421
-
422
- ```ts
423
- readonly static globalInstancesCountHistory: Record<BaseClassName, number[]> = {};
424
- ```
425
-
426
- ### Inherited from
427
-
428
- [`Base`](#Base).[`globalInstancesCountHistory`](Base.md#globalinstancescounthistory)
429
-
430
- ***
431
-
432
- ### uniqueDomain
433
-
434
- ```ts
435
- readonly static uniqueDomain: "xy" = 'xy';
436
- ```
437
-
438
- ***
439
-
440
- ### uniqueName
441
-
442
- ```ts
443
- readonly static uniqueName: string;
444
- ```
445
-
446
- ***
447
-
448
- ### uniqueNameXyo
449
-
450
- ```ts
451
- readonly static uniqueNameXyo: string;
452
- ```
386
+ | Property | Modifier | Type | Default value | Inherited from |
387
+ | ------ | ------ | ------ | ------ | ------ |
388
+ | <a id="defaultlogger"></a> `defaultLogger?` | `static` | `Logger` | `undefined` | [`Base`](#Base).[`defaultLogger`](Base.md#defaultlogger) |
389
+ | <a id="globalinstances"></a> `globalInstances` | `readonly` | `Record`\<[`BaseClassName`](#../type-aliases/BaseClassName), `WeakRef`\<[`Base`](#Base)\>[]\> | `{}` | [`Base`](#Base).[`globalInstances`](Base.md#globalinstances) |
390
+ | <a id="globalinstancescounthistory"></a> `globalInstancesCountHistory` | `readonly` | `Record`\<[`BaseClassName`](#../type-aliases/BaseClassName), `number`[]\> | `{}` | [`Base`](#Base).[`globalInstancesCountHistory`](Base.md#globalinstancescounthistory) |
391
+ | <a id="uniquedomain"></a> `uniqueDomain` | `readonly` | `"xy"` | `'xy'` | - |
392
+ | <a id="uniquename"></a> `uniqueName` | `readonly` | `string` | `undefined` | - |
393
+ | <a id="uniquenamexyo"></a> `uniqueNameXyo` | `readonly` | `string` | `undefined` | - |
453
394
 
454
395
  ## Accessors
455
396
 
@@ -468,14 +409,14 @@ get static historyInterval(): number;
468
409
  ### Set Signature
469
410
 
470
411
  ```ts
471
- set static historyInterval(value): void;
412
+ set static historyInterval(value: number): void;
472
413
  ```
473
414
 
474
415
  #### Parameters
475
416
 
476
- ##### value
477
-
478
- `number`
417
+ | Parameter | Type |
418
+ | ------ | ------ |
419
+ | `value` | `number` |
479
420
 
480
421
  #### Returns
481
422
 
@@ -502,14 +443,14 @@ get static historyTime(): number;
502
443
  ### Set Signature
503
444
 
504
445
  ```ts
505
- set static historyTime(value): void;
446
+ set static historyTime(value: number): void;
506
447
  ```
507
448
 
508
449
  #### Parameters
509
450
 
510
- ##### value
511
-
512
- `number`
451
+ | Parameter | Type |
452
+ | ------ | ------ |
453
+ | `value` | `number` |
513
454
 
514
455
  #### Returns
515
456
 
@@ -536,14 +477,14 @@ get static maxGcFrequency(): number;
536
477
  ### Set Signature
537
478
 
538
479
  ```ts
539
- set static maxGcFrequency(value): void;
480
+ set static maxGcFrequency(value: number): void;
540
481
  ```
541
482
 
542
483
  #### Parameters
543
484
 
544
- ##### value
545
-
546
- `number`
485
+ | Parameter | Type |
486
+ | ------ | ------ |
487
+ | `value` | `number` |
547
488
 
548
489
  #### Returns
549
490
 
@@ -650,14 +591,14 @@ get tracer(): Tracer | undefined;
650
591
  ### Call Signature
651
592
 
652
593
  ```ts
653
- static gc(force?): void;
594
+ static gc(force?: boolean): void;
654
595
  ```
655
596
 
656
597
  #### Parameters
657
598
 
658
- ##### force?
659
-
660
- `boolean`
599
+ | Parameter | Type |
600
+ | ------ | ------ |
601
+ | `force?` | `boolean` |
661
602
 
662
603
  #### Returns
663
604
 
@@ -670,14 +611,14 @@ static gc(force?): void;
670
611
  ### Call Signature
671
612
 
672
613
  ```ts
673
- static gc(className): void;
614
+ static gc(className: BaseClassName): void;
674
615
  ```
675
616
 
676
617
  #### Parameters
677
618
 
678
- ##### className
679
-
680
- [`BaseClassName`](#../type-aliases/BaseClassName)
619
+ | Parameter | Type |
620
+ | ------ | ------ |
621
+ | `className` | [`BaseClassName`](#../type-aliases/BaseClassName) |
681
622
 
682
623
  #### Returns
683
624
 
@@ -692,14 +633,14 @@ static gc(className): void;
692
633
  ### instanceCount()
693
634
 
694
635
  ```ts
695
- static instanceCount(className): number;
636
+ static instanceCount(className: BaseClassName): number;
696
637
  ```
697
638
 
698
639
  ### Parameters
699
640
 
700
- #### className
701
-
702
- [`BaseClassName`](#../type-aliases/BaseClassName)
641
+ | Parameter | Type |
642
+ | ------ | ------ |
643
+ | `className` | [`BaseClassName`](#../type-aliases/BaseClassName) |
703
644
 
704
645
  ### Returns
705
646
 
@@ -783,9 +724,9 @@ Disables global uniqueness checks, allowing duplicate registrations without thro
783
724
 
784
725
  ```ts
785
726
  function globallyUnique(
786
- name,
787
- value,
788
- domain?): string;
727
+ name: string | symbol,
728
+ value: unknown,
729
+ domain?: string): string;
789
730
  ```
790
731
 
791
732
  Registers a value as globally unique under the given name and domain.
@@ -793,23 +734,11 @@ Throws if a different value is already registered under the same key.
793
734
 
794
735
  ## Parameters
795
736
 
796
- ### name
797
-
798
- The unique name or symbol
799
-
800
- `string` | `symbol`
801
-
802
- ### value
803
-
804
- `unknown`
805
-
806
- The value to register
807
-
808
- ### domain?
809
-
810
- `string` = `'global'`
811
-
812
- The namespace domain (default 'global')
737
+ | Parameter | Type | Default value | Description |
738
+ | ------ | ------ | ------ | ------ |
739
+ | `name` | `string` \| `symbol` | `undefined` | The unique name or symbol |
740
+ | `value` | `unknown` | `undefined` | The value to register |
741
+ | `domain` | `string` | `'global'` | The namespace domain (default 'global') |
813
742
 
814
743
  ## Returns
815
744
 
@@ -826,18 +755,18 @@ The fully qualified unique name
826
755
  ***
827
756
 
828
757
  ```ts
829
- type BaseClassName = string & object;
758
+ type BaseClassName = string & {
759
+ __baseClassName: true;
760
+ };
830
761
  ```
831
762
 
832
763
  Branded string type representing a class name used for global instance tracking.
833
764
 
834
765
  ## Type Declaration
835
766
 
836
- ### \_\_baseClassName
837
-
838
- ```ts
839
- __baseClassName: true;
840
- ```
767
+ | Name | Type |
768
+ | ------ | ------ |
769
+ | `__baseClassName` | `true` |
841
770
 
842
771
  ### <a id="BaseParams"></a>BaseParams
843
772
 
@@ -853,9 +782,9 @@ Parameters for constructing a Base instance, combining BaseParamsFields with opt
853
782
 
854
783
  ## Type Parameters
855
784
 
856
- ### TAdditionalParams
857
-
858
- `TAdditionalParams` *extends* `EmptyObject` = `EmptyObject`
785
+ | Type Parameter | Default type |
786
+ | ------ | ------ |
787
+ | `TAdditionalParams` *extends* `EmptyObject` | `EmptyObject` |
859
788
 
860
789
  ### <a id="BaseParamsFields"></a>BaseParamsFields
861
790
 
@@ -864,34 +793,22 @@ Parameters for constructing a Base instance, combining BaseParamsFields with opt
864
793
  ***
865
794
 
866
795
  ```ts
867
- type BaseParamsFields = object;
796
+ type BaseParamsFields = {
797
+ logger?: Logger;
798
+ meterProvider?: MeterProvider;
799
+ traceProvider?: TracerProvider;
800
+ };
868
801
  ```
869
802
 
870
803
  Common parameter fields available to all Base instances (logger, meter, tracer).
871
804
 
872
805
  ## Properties
873
806
 
874
- ### logger?
875
-
876
- ```ts
877
- optional logger: Logger;
878
- ```
879
-
880
- ***
881
-
882
- ### meterProvider?
883
-
884
- ```ts
885
- optional meterProvider: MeterProvider;
886
- ```
887
-
888
- ***
889
-
890
- ### traceProvider?
891
-
892
- ```ts
893
- optional traceProvider: TracerProvider;
894
- ```
807
+ | Property | Type |
808
+ | ------ | ------ |
809
+ | <a id="logger"></a> `logger?` | `Logger` |
810
+ | <a id="meterprovider"></a> `meterProvider?` | `MeterProvider` |
811
+ | <a id="traceprovider"></a> `traceProvider?` | `TracerProvider` |
895
812
 
896
813
 
897
814
  Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xylabs/base",
3
- "version": "5.0.84",
3
+ "version": "5.0.86",
4
4
  "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
5
5
  "homepage": "https://xyo.network",
6
6
  "bugs": {
@@ -36,13 +36,13 @@
36
36
  ],
37
37
  "dependencies": {
38
38
  "@opentelemetry/api": "^1.9.0",
39
- "@xylabs/assert": "~5.0.84",
40
- "@xylabs/logger": "~5.0.84",
41
- "@xylabs/object": "~5.0.84"
39
+ "@xylabs/assert": "~5.0.86",
40
+ "@xylabs/logger": "~5.0.86",
41
+ "@xylabs/object": "~5.0.86"
42
42
  },
43
43
  "devDependencies": {
44
- "@xylabs/ts-scripts-yarn3": "~7.4.13",
45
- "@xylabs/tsconfig": "~7.4.13",
44
+ "@xylabs/ts-scripts-yarn3": "~7.4.16",
45
+ "@xylabs/tsconfig": "~7.4.16",
46
46
  "typescript": "~5.9.3",
47
47
  "vitest": "~4.0.18"
48
48
  },