navi-hey 0.4.0
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.
- package/bin/navi.js +9 -0
- package/lib/exceptions/AppError.js +13 -0
- package/lib/exceptions/ClientNotFound.js +16 -0
- package/lib/exceptions/ConfigurationFileNotFound.js +10 -0
- package/lib/exceptions/ConfigurationFileNotProvided.js +10 -0
- package/lib/exceptions/InvalidResponseBody.js +19 -0
- package/lib/exceptions/ItemNotFound.js +16 -0
- package/lib/exceptions/LockedByOtherWorker.js +14 -0
- package/lib/exceptions/MissingActionResource.js +13 -0
- package/lib/exceptions/MissingClientsConfig.js +14 -0
- package/lib/exceptions/MissingMappingVariable.js +17 -0
- package/lib/exceptions/MissingResourceConfig.js +14 -0
- package/lib/exceptions/MissingTopLevelConfgKey.js +15 -0
- package/lib/exceptions/NullResponse.js +13 -0
- package/lib/exceptions/RequestFailed.js +16 -0
- package/lib/exceptions/ResourceNotFound.js +16 -0
- package/lib/factories/Factory.js +79 -0
- package/lib/factories/JobFactory.js +82 -0
- package/lib/factories/WorkerFactory.js +35 -0
- package/lib/models/ActionEnqueuer.js +34 -0
- package/lib/models/ActionProcessingJob.js +51 -0
- package/lib/models/ActionsEnqueuer.js +42 -0
- package/lib/models/Config.js +68 -0
- package/lib/models/Job.js +87 -0
- package/lib/models/ParametersMapper.js +43 -0
- package/lib/models/PathResolver.js +77 -0
- package/lib/models/PathSegmentTraverser.js +82 -0
- package/lib/models/Resource.js +47 -0
- package/lib/models/ResourceRequest.js +80 -0
- package/lib/models/ResourceRequestAction.js +73 -0
- package/lib/models/ResourceRequestJob.js +61 -0
- package/lib/models/ResponseParser.js +36 -0
- package/lib/models/ResponseWrapper.js +86 -0
- package/lib/models/WebConfig.js +15 -0
- package/lib/models/Worker.js +57 -0
- package/lib/models/WorkersConfig.js +18 -0
- package/lib/registry/ClientRegistry.js +92 -0
- package/lib/registry/JobRegistry.js +125 -0
- package/lib/registry/JobRegistryInstance.js +149 -0
- package/lib/registry/NamedRegistry.js +73 -0
- package/lib/registry/ResourceRegistry.js +91 -0
- package/lib/registry/WorkersRegistry.js +106 -0
- package/lib/registry/WorkersRegistryInstance.js +139 -0
- package/lib/server/RequestHandler.js +15 -0
- package/lib/server/RouteRegister.js +27 -0
- package/lib/server/Router.js +44 -0
- package/lib/server/StatsRequestHandler.js +31 -0
- package/lib/server/WebServer.js +45 -0
- package/lib/services/Application.js +113 -0
- package/lib/services/ArgumentsParser.js +36 -0
- package/lib/services/Client.js +108 -0
- package/lib/services/ConfigLoader.js +75 -0
- package/lib/services/ConfigParser.js +131 -0
- package/lib/services/Engine.js +67 -0
- package/lib/services/WorkersAllocator.js +74 -0
- package/lib/utils/EnvResolver.js +53 -0
- package/lib/utils/PromiseAggregator.js +37 -0
- package/lib/utils/ResourceRequestCollector.js +35 -0
- package/lib/utils/collections/Collection.js +17 -0
- package/lib/utils/collections/IdentifyableCollection.js +86 -0
- package/lib/utils/collections/Queue.js +45 -0
- package/lib/utils/collections/SortedArrayMerger.js +84 -0
- package/lib/utils/collections/SortedArraySearcher.js +101 -0
- package/lib/utils/collections/SortedCollection.js +169 -0
- package/lib/utils/generators/IdGenerator.js +79 -0
- package/lib/utils/generators/IncrementalIdGenerator.js +25 -0
- package/lib/utils/generators/UUidGenerator.js +49 -0
- package/lib/utils/index.js +2 -0
- package/lib/utils/logging/BaseLogger.js +93 -0
- package/lib/utils/logging/BufferedLogger.js +91 -0
- package/lib/utils/logging/ConsoleLogger.js +19 -0
- package/lib/utils/logging/Log.js +70 -0
- package/lib/utils/logging/LogBuffer.js +101 -0
- package/lib/utils/logging/LogFactory.js +32 -0
- package/lib/utils/logging/Logger.js +134 -0
- package/lib/utils/logging/LoggerGroup.js +100 -0
- package/package.json +78 -0
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Merges two already-sorted arrays into a single sorted array using
|
|
3
|
+
* a two-pointer algorithm — O(n + m).
|
|
4
|
+
*
|
|
5
|
+
* The relative order of elements with equal sort values preserves the
|
|
6
|
+
* order of the first array before the second.
|
|
7
|
+
*/
|
|
8
|
+
class SortedArrayMerger {
|
|
9
|
+
#first;
|
|
10
|
+
#second;
|
|
11
|
+
#sortBy;
|
|
12
|
+
#result = [];
|
|
13
|
+
#i = 0;
|
|
14
|
+
#j = 0;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* @param {Array} first - The first sorted array.
|
|
18
|
+
* @param {Array} second - The second sorted array.
|
|
19
|
+
* @param {Function} sortBy - Function that extracts a comparable value from an element.
|
|
20
|
+
*/
|
|
21
|
+
constructor(first, second, sortBy) {
|
|
22
|
+
this.#first = first;
|
|
23
|
+
this.#second = second;
|
|
24
|
+
this.#sortBy = sortBy;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Merges two sorted arrays into a single sorted array.
|
|
29
|
+
* @param {Array} first - The first sorted array.
|
|
30
|
+
* @param {Array} second - The second sorted array.
|
|
31
|
+
* @param {Function} sortBy - Function that extracts a comparable value from an element.
|
|
32
|
+
* @returns {Array} A new sorted array containing all elements from both arrays.
|
|
33
|
+
*/
|
|
34
|
+
static merge(first, second, sortBy) {
|
|
35
|
+
return new SortedArrayMerger(first, second, sortBy).merge();
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Returns a new sorted array containing all elements from both arrays.
|
|
40
|
+
* @returns {Array} The merged sorted array.
|
|
41
|
+
*/
|
|
42
|
+
merge() {
|
|
43
|
+
this.#result = [];
|
|
44
|
+
this.#i = 0;
|
|
45
|
+
this.#j = 0;
|
|
46
|
+
|
|
47
|
+
while (this.#bothHaveMore()) {
|
|
48
|
+
this.#pickNext();
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
return this.#result.concat(this.#first.slice(this.#i), this.#second.slice(this.#j));
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Picks the next element from the first or second array based on sort order.
|
|
56
|
+
* @returns {void}
|
|
57
|
+
*/
|
|
58
|
+
#pickNext() {
|
|
59
|
+
if (this.#firstComesFirst()) {
|
|
60
|
+
this.#result.push(this.#first[this.#i++]);
|
|
61
|
+
} else {
|
|
62
|
+
this.#result.push(this.#second[this.#j++]);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Checks whether both arrays still have unprocessed elements.
|
|
68
|
+
* @returns {boolean} True if both pointers are within bounds.
|
|
69
|
+
*/
|
|
70
|
+
#bothHaveMore() {
|
|
71
|
+
return this.#i < this.#first.length && this.#j < this.#second.length;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Determines whether the current element of the first array should come before
|
|
76
|
+
* the current element of the second array.
|
|
77
|
+
* @returns {boolean} True if the first element comes first.
|
|
78
|
+
*/
|
|
79
|
+
#firstComesFirst() {
|
|
80
|
+
return this.#sortBy(this.#first[this.#i]) <= this.#sortBy(this.#second[this.#j]);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export { SortedArrayMerger };
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Performs binary search on a sorted array to find boundary indices
|
|
3
|
+
* for range queries — O(log n).
|
|
4
|
+
*
|
|
5
|
+
* Supports four modes that correspond to the four range methods of
|
|
6
|
+
* `SortedCollection`:
|
|
7
|
+
*
|
|
8
|
+
* | Mode | Finds first index where… |
|
|
9
|
+
* |----------|--------------------------|
|
|
10
|
+
* | `after` | `sortBy(el) > value` |
|
|
11
|
+
* | `from` | `sortBy(el) >= value` |
|
|
12
|
+
* | `before` | `sortBy(el) >= value` |
|
|
13
|
+
* | `upTo` | `sortBy(el) > value` |
|
|
14
|
+
*
|
|
15
|
+
* `after` and `upTo` share the same condition; `from` and `before` share
|
|
16
|
+
* the other. The caller decides which side of the boundary to slice.
|
|
17
|
+
*/
|
|
18
|
+
class SortedArraySearcher {
|
|
19
|
+
#array;
|
|
20
|
+
#sortBy;
|
|
21
|
+
#value;
|
|
22
|
+
#mode;
|
|
23
|
+
#lo = 0;
|
|
24
|
+
#hi;
|
|
25
|
+
#mid;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* @param {Array} array - The sorted array to search.
|
|
29
|
+
* @param {Function} sortBy - Function that extracts a comparable value from an element.
|
|
30
|
+
* @param {*} value - The boundary value to search for.
|
|
31
|
+
* @param {'after'|'from'|'before'|'upTo'} mode - The range mode.
|
|
32
|
+
*/
|
|
33
|
+
constructor(array, sortBy, value, mode) {
|
|
34
|
+
this.#array = array;
|
|
35
|
+
this.#sortBy = sortBy;
|
|
36
|
+
this.#value = value;
|
|
37
|
+
this.#mode = mode;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Returns the boundary index for slicing based on the range mode.
|
|
42
|
+
* @param {Array} array - The sorted array to search.
|
|
43
|
+
* @param {Function} sortBy - Function that extracts a comparable value from an element.
|
|
44
|
+
* @param {*} value - The boundary value to search for.
|
|
45
|
+
* @param {'after'|'from'|'before'|'upTo'} mode - The range mode.
|
|
46
|
+
* @returns {number} The boundary index.
|
|
47
|
+
*/
|
|
48
|
+
static search(array, sortBy, value, mode) {
|
|
49
|
+
return new SortedArraySearcher(array, sortBy, value, mode).search();
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Returns the boundary index for slicing based on the range mode.
|
|
54
|
+
* @returns {number} The boundary index.
|
|
55
|
+
*/
|
|
56
|
+
search() {
|
|
57
|
+
this.#lo = 0;
|
|
58
|
+
this.#hi = this.#array.length;
|
|
59
|
+
|
|
60
|
+
while (this.#lo < this.#hi) {
|
|
61
|
+
this.#mid = (this.#lo + this.#hi) >> 1;
|
|
62
|
+
this.#step();
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
return this.#lo;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Performs one binary search step, narrowing the search range.
|
|
70
|
+
* @returns {void}
|
|
71
|
+
*/
|
|
72
|
+
#step() {
|
|
73
|
+
if (this.#shouldAdvanceLo()) {
|
|
74
|
+
this.#lo = this.#mid + 1;
|
|
75
|
+
} else {
|
|
76
|
+
this.#hi = this.#mid;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Determines whether the lower bound should advance past the midpoint.
|
|
82
|
+
* @returns {boolean} True if the lower bound should be moved forward.
|
|
83
|
+
*/
|
|
84
|
+
#shouldAdvanceLo() {
|
|
85
|
+
const item = this.#array[this.#mid];
|
|
86
|
+
const sortedValue = this.#sortBy(item);
|
|
87
|
+
if (sortedValue < this.#value) return true;
|
|
88
|
+
if (sortedValue > this.#value) return false;
|
|
89
|
+
return this.#isExclusiveMode();
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Checks whether the current mode is exclusive ('after' or 'upTo').
|
|
94
|
+
* @returns {boolean} True if the mode is exclusive.
|
|
95
|
+
*/
|
|
96
|
+
#isExclusiveMode() {
|
|
97
|
+
return this.#mode === 'after' || this.#mode === 'upTo';
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export { SortedArraySearcher };
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
import { Collection } from './Collection.js';
|
|
2
|
+
import { SortedArrayMerger } from './SortedArrayMerger.js';
|
|
3
|
+
import { SortedArraySearcher } from './SortedArraySearcher.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* A collection that maintains elements in sorted order.
|
|
7
|
+
*
|
|
8
|
+
* New elements are buffered in a non-sorted list and merged into the sorted
|
|
9
|
+
* list only when iteration is needed (deferred / lazy flush strategy).
|
|
10
|
+
*
|
|
11
|
+
* The merge strategy is:
|
|
12
|
+
* 1. Sort `#nonSorted` using `sortBy` — O(m log m)
|
|
13
|
+
* 2. Merge two sorted arrays via two-pointer algorithm — O(n + m)
|
|
14
|
+
*
|
|
15
|
+
* Range methods (`after`, `from`, `before`, `upTo`) use binary search to
|
|
16
|
+
* find the cut-off index — O(log n) — avoiding a full scan.
|
|
17
|
+
*/
|
|
18
|
+
class SortedCollection extends Collection {
|
|
19
|
+
#sorted = [];
|
|
20
|
+
#nonSorted = [];
|
|
21
|
+
#sortBy;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* @param {Array} initialSet - Optional initial elements (default `[]`).
|
|
25
|
+
* @param {object} options - Configuration options.
|
|
26
|
+
* @param {Function} options.sortBy - Function that extracts a comparable value from an element.
|
|
27
|
+
* @throws {Error} If `sortBy` is not a function.
|
|
28
|
+
* @returns {SortedCollection} A new SortedCollection instance.
|
|
29
|
+
*/
|
|
30
|
+
constructor(initialSet = [], { sortBy } = {}) {
|
|
31
|
+
super();
|
|
32
|
+
if (typeof sortBy !== 'function') throw new Error('sortBy must be a function');
|
|
33
|
+
this.#sortBy = sortBy;
|
|
34
|
+
this.#nonSorted = [...initialSet];
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Adds an element to the pending (non-sorted) list.
|
|
39
|
+
* @param {*} item - The element to add.
|
|
40
|
+
* @returns {void}
|
|
41
|
+
*/
|
|
42
|
+
push(item) {
|
|
43
|
+
this.#nonSorted.push(item);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Returns a copy of all elements in sorted order.
|
|
48
|
+
* Triggers a flush of pending elements first.
|
|
49
|
+
* @returns {Array} Sorted shallow copy.
|
|
50
|
+
*/
|
|
51
|
+
list() {
|
|
52
|
+
return [...this.#flushedSorted()];
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Returns the total number of elements (sorted + pending).
|
|
57
|
+
* @returns {number} The total size of the collection.
|
|
58
|
+
*/
|
|
59
|
+
size() {
|
|
60
|
+
return this.#sorted.length + this.#nonSorted.length;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Returns elements for which `fn(element)` is truthy.
|
|
65
|
+
* Triggers a flush first.
|
|
66
|
+
* @param {Function} fn - Predicate function.
|
|
67
|
+
* @returns {Array} Elements that satisfy the predicate.
|
|
68
|
+
*/
|
|
69
|
+
select(fn) {
|
|
70
|
+
return this.#flushedSorted().filter(fn);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Returns elements whose sort field is strictly greater than `value`.
|
|
75
|
+
* Uses binary search for O(log n) cut-off detection.
|
|
76
|
+
* @param {*} value - The exclusive lower bound.
|
|
77
|
+
* @returns {Array} Elements with sort field greater than `value`.
|
|
78
|
+
*/
|
|
79
|
+
after(value) {
|
|
80
|
+
const i = this.#binarySearch(value, 'after');
|
|
81
|
+
return this.#sorted.slice(i);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Returns elements whose sort field is greater than or equal to `value`.
|
|
86
|
+
* Uses binary search for O(log n) cut-off detection.
|
|
87
|
+
* @param {*} value - The inclusive lower bound.
|
|
88
|
+
* @returns {Array} Elements with sort field greater than or equal to `value`.
|
|
89
|
+
*/
|
|
90
|
+
from(value) {
|
|
91
|
+
const i = this.#binarySearch(value, 'from');
|
|
92
|
+
return this.#sorted.slice(i);
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/**
|
|
96
|
+
* Returns elements whose sort field is strictly less than `value`.
|
|
97
|
+
* Uses binary search for O(log n) cut-off detection.
|
|
98
|
+
* @param {*} value - The exclusive upper bound.
|
|
99
|
+
* @returns {Array} Elements with sort field less than `value`.
|
|
100
|
+
*/
|
|
101
|
+
before(value) {
|
|
102
|
+
const i = this.#binarySearch(value, 'before');
|
|
103
|
+
return this.#sorted.slice(0, i);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* Returns elements whose sort field is less than or equal to `value`.
|
|
108
|
+
* Uses binary search for O(log n) cut-off detection.
|
|
109
|
+
* @param {*} value - The inclusive upper bound.
|
|
110
|
+
* @returns {Array} Elements with sort field less than or equal to `value`.
|
|
111
|
+
*/
|
|
112
|
+
upTo(value) {
|
|
113
|
+
const i = this.#binarySearch(value, 'upTo');
|
|
114
|
+
return this.#sorted.slice(0, i);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Flushes pending elements and returns the sorted array.
|
|
119
|
+
* @returns {Array} The internal sorted array.
|
|
120
|
+
*/
|
|
121
|
+
#flushedSorted() {
|
|
122
|
+
this.#flush();
|
|
123
|
+
return this.#sorted;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/**
|
|
127
|
+
* Merges pending elements into the sorted array if any are buffered.
|
|
128
|
+
* @returns {void}
|
|
129
|
+
*/
|
|
130
|
+
#flush() {
|
|
131
|
+
if (this.#nonSorted.length === 0) return;
|
|
132
|
+
|
|
133
|
+
this.#sortNonSorted();
|
|
134
|
+
this.#sorted = this.#merge();
|
|
135
|
+
this.#nonSorted = [];
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* Sorts the pending non-sorted array in place using the sortBy function.
|
|
140
|
+
* @returns {void}
|
|
141
|
+
*/
|
|
142
|
+
#sortNonSorted() {
|
|
143
|
+
this.#nonSorted.sort((a, b) => {
|
|
144
|
+
const va = this.#sortBy(a);
|
|
145
|
+
const vb = this.#sortBy(b);
|
|
146
|
+
return va < vb ? -1 : va > vb ? 1 : 0;
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Merges the sorted and non-sorted arrays using a two-pointer algorithm.
|
|
152
|
+
* @returns {Array} The merged sorted array.
|
|
153
|
+
*/
|
|
154
|
+
#merge() {
|
|
155
|
+
return SortedArrayMerger.merge(this.#sorted, this.#nonSorted, this.#sortBy);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Performs a binary search on the flushed sorted array.
|
|
160
|
+
* @param {*} value - The boundary value to search for.
|
|
161
|
+
* @param {'after'|'from'|'before'|'upTo'} mode - The range mode.
|
|
162
|
+
* @returns {number} The boundary index.
|
|
163
|
+
*/
|
|
164
|
+
#binarySearch(value, mode) {
|
|
165
|
+
return SortedArraySearcher.search(this.#flushedSorted(), this.#sortBy, value, mode);
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
export { SortedCollection };
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { UUidGenerator } from './UUidGenerator.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* IdGenerator generates unique identifiers for objects, ensuring no duplicates
|
|
5
|
+
* are produced across multiple invocations.
|
|
6
|
+
*
|
|
7
|
+
* It delegates UUID generation to a {@link UUidGenerator} instance, and exposes
|
|
8
|
+
* a generator function suitable for use as an attributes generator in a {@link Factory}.
|
|
9
|
+
* @author darthjee
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* A function returned by {@link IdGenerator#generator} that enriches an attributes
|
|
14
|
+
* object with a unique `id` field.
|
|
15
|
+
* @callback IdGeneratorFunction
|
|
16
|
+
* @param {object} [attributes={}] - The attributes object to enrich with a unique identifier.
|
|
17
|
+
* @param {*} [attributes.id] - An optional existing identifier. If provided, it is kept and registered to avoid future collisions.
|
|
18
|
+
* @returns {object} The attributes object with a guaranteed unique `id` field.
|
|
19
|
+
* @example
|
|
20
|
+
* const idGenerator = new IdGenerator();
|
|
21
|
+
* const generate = idGenerator.generator();
|
|
22
|
+
* generate({ name: 'foo' }); // => { id: '<uuid>', name: 'foo' }
|
|
23
|
+
* generate({ id: 42, name: 'bar' }); // => { id: 42, name: 'bar' }
|
|
24
|
+
*/
|
|
25
|
+
class IdGenerator {
|
|
26
|
+
#uuidGenerator = null;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Creates a new IdGenerator instance.
|
|
30
|
+
* @param {object} params - The parameters for creating an IdGenerator instance.
|
|
31
|
+
* @param {UUidGenerator} params.uuidGenerator - The UUID generator used to produce unique identifiers.
|
|
32
|
+
*/
|
|
33
|
+
constructor({ uuidGenerator = new UUidGenerator() } = {}) {
|
|
34
|
+
this.#uuidGenerator = uuidGenerator;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Returns a function that generates attributes with a unique `id` field.
|
|
39
|
+
*
|
|
40
|
+
* The returned function accepts an optional attributes object and delegates
|
|
41
|
+
* to {@link IdGenerator#generate}.
|
|
42
|
+
* @returns {IdGeneratorFunction} A function that accepts an attributes object and returns it enriched with a unique `id`.
|
|
43
|
+
*/
|
|
44
|
+
generator() {
|
|
45
|
+
return (attributes = {}) => this.generate(attributes);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/**
|
|
49
|
+
* Generates a unique `id` for the given attributes object and returns the enriched attributes.
|
|
50
|
+
*
|
|
51
|
+
* If the attributes already contain an `id`, that value is registered to avoid future collisions.
|
|
52
|
+
* @param {object} attributes - The attributes object to enrich with a unique identifier.
|
|
53
|
+
* @param {*} [attributes.id] - An optional existing identifier. If provided, it is kept and registered.
|
|
54
|
+
* @returns {object} The attributes object with a guaranteed unique `id` field.
|
|
55
|
+
*/
|
|
56
|
+
generate(attributes = {}) {
|
|
57
|
+
const id = this.#generateId(attributes.id);
|
|
58
|
+
|
|
59
|
+
attributes = { id, ...attributes };
|
|
60
|
+
|
|
61
|
+
return attributes;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Resolves the identifier to use, either by registering an existing one or generating a new unique one.
|
|
66
|
+
* @param {*} id - The existing identifier, if any.
|
|
67
|
+
* @returns {*} The resolved unique identifier.
|
|
68
|
+
*/
|
|
69
|
+
#generateId(id) {
|
|
70
|
+
if (id) {
|
|
71
|
+
this.#uuidGenerator.push(id);
|
|
72
|
+
return id;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
return this.#uuidGenerator.generate();
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export { IdGenerator };
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* IncrementalIdGenerator generates sequential integer identifiers starting from 1.
|
|
3
|
+
* @author darthjee
|
|
4
|
+
*/
|
|
5
|
+
class IncrementalIdGenerator {
|
|
6
|
+
#nextId;
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Creates a new IncrementalIdGenerator instance.
|
|
10
|
+
* @param {number} [start=1] - The first id to generate.
|
|
11
|
+
*/
|
|
12
|
+
constructor(start = 1) {
|
|
13
|
+
this.#nextId = start;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Generates the next sequential integer identifier.
|
|
18
|
+
* @returns {number} The next integer id.
|
|
19
|
+
*/
|
|
20
|
+
generate() {
|
|
21
|
+
return this.#nextId++;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export { IncrementalIdGenerator };
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
|
|
2
|
+
import { randomUUID } from 'crypto';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* UUidGenerator generates unique identifiers, ensuring no duplicates are produced
|
|
6
|
+
* across multiple calls.
|
|
7
|
+
*
|
|
8
|
+
* It tracks previously generated or registered identifiers and retries generation
|
|
9
|
+
* whenever a collision is detected.
|
|
10
|
+
* @author darthjee
|
|
11
|
+
*/
|
|
12
|
+
class UUidGenerator {
|
|
13
|
+
#generated = new Set();
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* Creates a new UUidGenerator instance.
|
|
17
|
+
* @param {object} params - The parameters for creating a UUidGenerator instance.
|
|
18
|
+
* @param {Function} params.generator - A function used to produce identifier values. Defaults to {@link randomUUID}.
|
|
19
|
+
*/
|
|
20
|
+
constructor({ generator = randomUUID } = {}) {
|
|
21
|
+
this.generator = generator;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Registers an existing identifier to prevent it from being generated in the future.
|
|
26
|
+
* @param {*} id - The identifier to register as already in use.
|
|
27
|
+
* @returns {void}
|
|
28
|
+
*/
|
|
29
|
+
push(id) {
|
|
30
|
+
this.#generated.add(id);
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Generates a new unique identifier that has not been previously generated or registered.
|
|
35
|
+
* @returns {*} A unique identifier.
|
|
36
|
+
*/
|
|
37
|
+
generate() {
|
|
38
|
+
let id;
|
|
39
|
+
|
|
40
|
+
do {
|
|
41
|
+
id = this.generator();
|
|
42
|
+
} while (this.#generated.has(id));
|
|
43
|
+
|
|
44
|
+
this.#generated.add(id);
|
|
45
|
+
return id;
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export { UUidGenerator };
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Base logger that filters log output based on a configurable level threshold.
|
|
3
|
+
* Subclasses must implement _output(level, message) to handle the actual output.
|
|
4
|
+
* @author darthjee
|
|
5
|
+
*/
|
|
6
|
+
class BaseLogger {
|
|
7
|
+
#level;
|
|
8
|
+
#suppressed = false;
|
|
9
|
+
#levels = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Creates a new BaseLogger instance.
|
|
13
|
+
* @param {string} [level] - The log level threshold. Defaults to the LOG_LEVEL env var or 'info'.
|
|
14
|
+
*/
|
|
15
|
+
constructor(level) {
|
|
16
|
+
this.#level = level ?? process.env.LOG_LEVEL ?? 'info';
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Outputs a message at the given level. Override in subclasses.
|
|
21
|
+
* @param {string} _level - The log level.
|
|
22
|
+
* @param {string} _message - The message to output.
|
|
23
|
+
* @returns {void}
|
|
24
|
+
*/
|
|
25
|
+
_output(_level, _message) {}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Logs a debug message if the configured level allows it.
|
|
29
|
+
* @param {string} message - The message to log.
|
|
30
|
+
* @returns {void}
|
|
31
|
+
*/
|
|
32
|
+
debug(message) {
|
|
33
|
+
if (this.#shouldLog('debug')) this._output('debug', message);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Logs an info message if the configured level allows it.
|
|
38
|
+
* @param {string} message - The message to log.
|
|
39
|
+
* @returns {void}
|
|
40
|
+
*/
|
|
41
|
+
info(message) {
|
|
42
|
+
if (this.#shouldLog('info')) this._output('info', message);
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Logs a warn message if the configured level allows it.
|
|
47
|
+
* @param {string} message - The message to log.
|
|
48
|
+
* @returns {void}
|
|
49
|
+
*/
|
|
50
|
+
warn(message) {
|
|
51
|
+
if (this.#shouldLog('warn')) this._output('warn', message);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Logs an error message if the configured level allows it.
|
|
56
|
+
* @param {string} message - The message to log.
|
|
57
|
+
* @returns {void}
|
|
58
|
+
*/
|
|
59
|
+
error(message) {
|
|
60
|
+
if (this.#shouldLog('error')) this._output('error', message);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Suppresses or restores log output for this instance.
|
|
65
|
+
* @param {boolean} [value=true] - When true, all log output is suppressed.
|
|
66
|
+
* @returns {void}
|
|
67
|
+
*/
|
|
68
|
+
suppress(value = true) {
|
|
69
|
+
this.#suppressed = value;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Sets the log level threshold for this instance.
|
|
74
|
+
* @param {string} level - The new log level ('debug', 'info', 'warn', 'error', 'silent').
|
|
75
|
+
* @returns {void}
|
|
76
|
+
*/
|
|
77
|
+
setLevel(level) {
|
|
78
|
+
if (!(level in this.#levels)) {
|
|
79
|
+
throw new Error(`Invalid log level: "${level}". Must be one of: ${Object.keys(this.#levels).join(', ')}.`);
|
|
80
|
+
}
|
|
81
|
+
this.#level = level;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* @param {string} level - The log level to check.
|
|
86
|
+
* @returns {boolean} True if the message should be logged at the given level.
|
|
87
|
+
*/
|
|
88
|
+
#shouldLog(level) {
|
|
89
|
+
return !this.#suppressed && this.#levels[level] >= this.#levels[this.#level];
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
export { BaseLogger };
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { BaseLogger } from './BaseLogger.js';
|
|
2
|
+
import { LogBuffer } from './LogBuffer.js';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* BufferedLogger extends BaseLogger by maintaining a history of log messages.
|
|
6
|
+
* Useful for displaying logs in a web interface or debugging.
|
|
7
|
+
* @author darthjee
|
|
8
|
+
*/
|
|
9
|
+
class BufferedLogger extends BaseLogger {
|
|
10
|
+
#buffer;
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Creates a new BufferedLogger instance.
|
|
14
|
+
* @param {string} [level] - The log level threshold.
|
|
15
|
+
* @param {number} [retention=100] - Maximum number of logs to retain in buffer.
|
|
16
|
+
*/
|
|
17
|
+
constructor(level, retention = 100) {
|
|
18
|
+
super(level);
|
|
19
|
+
this.#buffer = new LogBuffer(retention);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Stores the message in the buffer.
|
|
24
|
+
* @param {string} level - The log level ('debug', 'info', 'warn', 'error').
|
|
25
|
+
* @param {string} message - The message to output.
|
|
26
|
+
* @returns {void}
|
|
27
|
+
*/
|
|
28
|
+
_output(level, message) {
|
|
29
|
+
this.#buffer.add(level, message);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Gets all logs from the buffer.
|
|
34
|
+
* @returns {Array<import('./Log.js').Log>} Array of log entries.
|
|
35
|
+
*/
|
|
36
|
+
getLogs() {
|
|
37
|
+
return this.#buffer.getLogs();
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Gets a specific log by ID.
|
|
42
|
+
* @param {number} id - The log ID to find.
|
|
43
|
+
* @returns {import('./Log.js').Log|undefined} The log entry or undefined if not found.
|
|
44
|
+
*/
|
|
45
|
+
getLogById(id) {
|
|
46
|
+
return this.#buffer.getLogById(id);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Gets logs filtered by level.
|
|
51
|
+
* @param {string} level - The log level to filter by.
|
|
52
|
+
* @returns {Array<import('./Log.js').Log>} Array of log entries matching the level.
|
|
53
|
+
*/
|
|
54
|
+
getLogsByLevel(level) {
|
|
55
|
+
return this.#buffer.getLogsByLevel(level);
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Clears all logs from the buffer.
|
|
60
|
+
* @returns {void}
|
|
61
|
+
*/
|
|
62
|
+
clearLogs() {
|
|
63
|
+
this.#buffer.clear();
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Gets the current number of logs in the buffer.
|
|
68
|
+
* @returns {number} The number of logs.
|
|
69
|
+
*/
|
|
70
|
+
get bufferSize() {
|
|
71
|
+
return this.#buffer.size;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Gets the retention limit.
|
|
76
|
+
* @returns {number} The maximum number of logs to retain.
|
|
77
|
+
*/
|
|
78
|
+
get retention() {
|
|
79
|
+
return this.#buffer.retention;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Converts all logs to JSON array.
|
|
84
|
+
* @returns {Array<object>} Array of log objects.
|
|
85
|
+
*/
|
|
86
|
+
getLogsJSON() {
|
|
87
|
+
return this.#buffer.toJSON();
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
export { BufferedLogger };
|