@axi-engine/utils 0.1.6 → 0.1.8
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/README.md +1 -4
- package/dist/index.cjs +380 -0
- package/dist/{index.d.ts → index.d.cts} +94 -43
- package/dist/index.d.cts.map +1 -0
- package/dist/index.d.mts +94 -43
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +298 -130
- package/dist/index.mjs.map +1 -0
- package/package.json +38 -33
- package/dist/index.js +0 -239
package/README.md
CHANGED
|
@@ -32,11 +32,8 @@ const isSame = haveSameElements(['a', 'b'], ['b', 'a']); // Returns true
|
|
|
32
32
|
|
|
33
33
|
## API Reference
|
|
34
34
|
|
|
35
|
-
|
|
35
|
+
[**Browse the API Documentation here**](https://github.com/axijs/engine/tree/main/packages/utils/docs/api)
|
|
36
36
|
|
|
37
|
-
<!--
|
|
38
|
-
[**Full API Documentation**](https://github.com/.../blob/main/packages/utils/docs/api/README.md)
|
|
39
|
-
-->
|
|
40
37
|
|
|
41
38
|
|
|
42
39
|
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,380 @@
|
|
|
1
|
+
let uuid = require("uuid");
|
|
2
|
+
|
|
3
|
+
//#region src/arrays.ts
|
|
4
|
+
/**
|
|
5
|
+
* Generates an array of numbers from 0 to length-1.
|
|
6
|
+
* @param length The desired length of the array.
|
|
7
|
+
* @returns An array of sequential numbers.
|
|
8
|
+
* @example genArray(3); // returns [0, 1, 2]
|
|
9
|
+
*/
|
|
10
|
+
function genArray(length) {
|
|
11
|
+
return Array.from({ length }, (_v, i) => i);
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Creates a new array with its elements shuffled in a random order.
|
|
15
|
+
* This function does not mutate the original array.
|
|
16
|
+
* @template T The type of elements in the array.
|
|
17
|
+
* @param array The array to shuffle.
|
|
18
|
+
* @returns A new, shuffled array.
|
|
19
|
+
*/
|
|
20
|
+
function shuffleArray(array) {
|
|
21
|
+
const result = [...array];
|
|
22
|
+
for (let i = result.length - 1; i > 0; i--) {
|
|
23
|
+
const j = Math.floor(Math.random() * (i + 1));
|
|
24
|
+
[result[i], result[j]] = [result[j], result[i]];
|
|
25
|
+
}
|
|
26
|
+
return result;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Checks if the first array is a sequential starting subset of the second array.
|
|
30
|
+
* @param arr1 The potential subset array.
|
|
31
|
+
* @param arr2 The array to check against.
|
|
32
|
+
* @returns `true` if arr1 is a sequential start of arr2, otherwise `false`.
|
|
33
|
+
* @example
|
|
34
|
+
* isSequentialStart([1, 2], [1, 2, 3]); // true
|
|
35
|
+
* isSequentialStart([1, 3], [1, 2, 3]); // false
|
|
36
|
+
*/
|
|
37
|
+
function isSequentialStart(arr1, arr2) {
|
|
38
|
+
if (arr1.length > arr2.length) return false;
|
|
39
|
+
return arr1.every((element, index) => element === arr2[index]);
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Checks if two arrays contain the same elements, ignoring order.
|
|
43
|
+
* Works for arrays of primitives like strings or numbers.
|
|
44
|
+
* @template T The type of elements in the array.
|
|
45
|
+
* @param arr1 The first array.
|
|
46
|
+
* @param arr2 The second array.
|
|
47
|
+
* @returns `true` if both arrays contain the same elements, otherwise `false`.
|
|
48
|
+
* @example
|
|
49
|
+
* haveSameElements(['a', 'b'], ['b', 'a']); // true
|
|
50
|
+
* haveSameElements([1, 2, 3], [3, 1, 2]); // true
|
|
51
|
+
* haveSameElements(['a', 'b'], ['a', 'c']); // false
|
|
52
|
+
*/
|
|
53
|
+
function haveSameElements(arr1, arr2) {
|
|
54
|
+
if (!arr1 && !arr2) return true;
|
|
55
|
+
if (!arr1 || !arr2) return false;
|
|
56
|
+
if (arr1.length !== arr2.length) return false;
|
|
57
|
+
const sortedArr1 = [...arr1].sort();
|
|
58
|
+
const sortedArr2 = [...arr2].sort();
|
|
59
|
+
return sortedArr1.every((value, index) => value === sortedArr2[index]);
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Checks if two arrays are strictly equal (same elements in the same order).
|
|
63
|
+
* @template T The type of elements in the array.
|
|
64
|
+
* @param arr1 The first array.
|
|
65
|
+
* @param arr2 The second array.
|
|
66
|
+
* @returns `true` if the arrays are strictly equal, otherwise `false`.
|
|
67
|
+
* @example
|
|
68
|
+
* areArraysEqual(['a', 'b'], ['a', 'b']); // true
|
|
69
|
+
* areArraysEqual(['a', 'b'], ['b', 'a']); // false
|
|
70
|
+
* areArraysEqual([1, 2], [1, 2, 3]); // false
|
|
71
|
+
*/
|
|
72
|
+
function areArraysEqual(arr1, arr2) {
|
|
73
|
+
if (!arr1 && !arr2) return true;
|
|
74
|
+
if (!arr1 || !arr2) return false;
|
|
75
|
+
if (arr1.length !== arr2.length) return false;
|
|
76
|
+
return arr1.every((value, index) => value === arr2[index]);
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Gets the last element of an array.
|
|
80
|
+
* @template T The type of elements in the array.
|
|
81
|
+
* @param array The array to query.
|
|
82
|
+
* @returns The last element of the array, or `undefined` if the array is empty.
|
|
83
|
+
*/
|
|
84
|
+
function last(array) {
|
|
85
|
+
return array[array.length - 1];
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Creates a duplicate-free version of an array.
|
|
89
|
+
* @template T The type of elements in the array.
|
|
90
|
+
* @param array The array to process.
|
|
91
|
+
* @returns A new array with only unique elements.
|
|
92
|
+
*/
|
|
93
|
+
function unique(array) {
|
|
94
|
+
return [...new Set(array)];
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Gets a random element from an array.
|
|
98
|
+
* @template T The type of elements in the array.
|
|
99
|
+
* @param array The array to choose from.
|
|
100
|
+
* @returns A random element from the array, or `undefined` if the array is empty.
|
|
101
|
+
*/
|
|
102
|
+
function getRandomElement(array) {
|
|
103
|
+
if (array.length === 0) return;
|
|
104
|
+
return array[Math.floor(Math.random() * array.length)];
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
//#endregion
|
|
108
|
+
//#region src/guards.ts
|
|
109
|
+
function isNullOrUndefined(val) {
|
|
110
|
+
return val === void 0 || val === null;
|
|
111
|
+
}
|
|
112
|
+
function isUndefined(val) {
|
|
113
|
+
return typeof val === "undefined";
|
|
114
|
+
}
|
|
115
|
+
function isNumber(val) {
|
|
116
|
+
return typeof val === "number";
|
|
117
|
+
}
|
|
118
|
+
function isBoolean(val) {
|
|
119
|
+
return typeof val === "boolean";
|
|
120
|
+
}
|
|
121
|
+
function isString(val) {
|
|
122
|
+
return typeof val === "string";
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Type guard to check if a value is a string that ends with '%'.
|
|
126
|
+
* @param val The value to check.
|
|
127
|
+
* @returns `true` if the value is a percentage string.
|
|
128
|
+
*/
|
|
129
|
+
function isPercentageString(val) {
|
|
130
|
+
return typeof val === "string" && val.endsWith("%");
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
//#endregion
|
|
134
|
+
//#region src/assertion.ts
|
|
135
|
+
/**
|
|
136
|
+
* Throws an error if the condition is true.
|
|
137
|
+
* @param conditionForThrow - If true, an error will be thrown.
|
|
138
|
+
* @param exceptionMessage - The message for the error.
|
|
139
|
+
* @throws {Error} if the value is true
|
|
140
|
+
*/
|
|
141
|
+
function throwIf(conditionForThrow, exceptionMessage) {
|
|
142
|
+
if (conditionForThrow) throw new Error(exceptionMessage);
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* Throws an error if the value is null, undefined, or an empty array.
|
|
146
|
+
*
|
|
147
|
+
* @template T The type of the value being checked.
|
|
148
|
+
* @param value The value to check.
|
|
149
|
+
* @param exceptionMessage The message for the error.
|
|
150
|
+
* @throws {Error} if the value is null, undefined, or an empty array.
|
|
151
|
+
*
|
|
152
|
+
* @example
|
|
153
|
+
* // Example with a potentially undefined variable
|
|
154
|
+
* const user: { name: string } | undefined = findUser();
|
|
155
|
+
* throwIfEmpty(user, 'User not found');
|
|
156
|
+
* // From here, TypeScript knows `user` is not undefined.
|
|
157
|
+
* console.log(user.name);
|
|
158
|
+
*
|
|
159
|
+
* @example
|
|
160
|
+
* // Example with an array
|
|
161
|
+
* const items: string[] = getItems();
|
|
162
|
+
* throwIfEmpty(items, 'Items array cannot be empty');
|
|
163
|
+
* // From here, you can safely access items[0] without checking for an empty array again.
|
|
164
|
+
* console.log('First item:', items[0]);
|
|
165
|
+
*/
|
|
166
|
+
function throwIfEmpty(value, exceptionMessage) {
|
|
167
|
+
const isArrayAndEmpty = Array.isArray(value) && value.length === 0;
|
|
168
|
+
if (isNullOrUndefined(value) || isArrayAndEmpty) throw new Error(exceptionMessage);
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
//#endregion
|
|
172
|
+
//#region src/config.ts
|
|
173
|
+
const defaultConfig = { pathSeparator: "/" };
|
|
174
|
+
const axiSettings = { ...defaultConfig };
|
|
175
|
+
/**
|
|
176
|
+
* set up global configuration for axi-engine.
|
|
177
|
+
* @param newConfig - configuration object
|
|
178
|
+
*/
|
|
179
|
+
function configure(newConfig) {
|
|
180
|
+
Object.assign(axiSettings, newConfig);
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
//#endregion
|
|
184
|
+
//#region src/constructor-registry.ts
|
|
185
|
+
/**
|
|
186
|
+
* A generic registry for mapping string identifiers to class constructors.
|
|
187
|
+
*
|
|
188
|
+
* This utility is fundamental for building extensible systems like dependency injection containers,
|
|
189
|
+
* factories, and serialization engines where types need to be dynamically resolved.
|
|
190
|
+
*
|
|
191
|
+
* @template T - A base type that all registered constructors must produce an instance of.
|
|
192
|
+
*/
|
|
193
|
+
var ConstructorRegistry = class {
|
|
194
|
+
items = /* @__PURE__ */ new Map();
|
|
195
|
+
/**
|
|
196
|
+
* Registers a constructor with a unique string identifier.
|
|
197
|
+
*
|
|
198
|
+
* @param typeId - The unique identifier for the constructor (e.g., a static `typeName` property from a class).
|
|
199
|
+
* @param ctor - The class constructor to register.
|
|
200
|
+
* @returns The registry instance for chainable calls.
|
|
201
|
+
* @throws If a constructor with the same `typeId` is already registered.
|
|
202
|
+
*/
|
|
203
|
+
register(typeId, ctor) {
|
|
204
|
+
throwIf(this.items.has(typeId), `A constructor with typeId '${typeId}' is already registered.`);
|
|
205
|
+
this.items.set(typeId, ctor);
|
|
206
|
+
return this;
|
|
207
|
+
}
|
|
208
|
+
/**
|
|
209
|
+
* Retrieves a constructor by its identifier.
|
|
210
|
+
*
|
|
211
|
+
* @param typeId - The identifier of the constructor to retrieve.
|
|
212
|
+
* @returns The found class constructor.
|
|
213
|
+
* @throws If no constructor is found for the given `typeId`.
|
|
214
|
+
*/
|
|
215
|
+
get(typeId) {
|
|
216
|
+
const Ctor = this.items.get(typeId);
|
|
217
|
+
throwIfEmpty(Ctor, `No constructor found for typeId '${typeId}'`);
|
|
218
|
+
return Ctor;
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* Checks if a constructor for a given identifier is registered.
|
|
222
|
+
* @param typeId - The identifier to check.
|
|
223
|
+
* @returns `true` if a constructor is registered, otherwise `false`.
|
|
224
|
+
*/
|
|
225
|
+
has(typeId) {
|
|
226
|
+
return this.items.has(typeId);
|
|
227
|
+
}
|
|
228
|
+
/**
|
|
229
|
+
* Clears all registered constructors from the registry.
|
|
230
|
+
*/
|
|
231
|
+
clear() {
|
|
232
|
+
this.items.clear();
|
|
233
|
+
}
|
|
234
|
+
};
|
|
235
|
+
|
|
236
|
+
//#endregion
|
|
237
|
+
//#region src/emitter.ts
|
|
238
|
+
/**
|
|
239
|
+
* A minimal, type-safe event emitter for a single event.
|
|
240
|
+
* It does not manage state, it only manages subscribers and event dispatching.
|
|
241
|
+
* @template T A tuple representing the types of the event arguments.
|
|
242
|
+
*/
|
|
243
|
+
var Emitter = class {
|
|
244
|
+
listeners = /* @__PURE__ */ new Set();
|
|
245
|
+
/**
|
|
246
|
+
* Returns the number of listeners.
|
|
247
|
+
*/
|
|
248
|
+
get listenerCount() {
|
|
249
|
+
return this.listeners.size;
|
|
250
|
+
}
|
|
251
|
+
/**
|
|
252
|
+
* Subscribes a listener to this event.
|
|
253
|
+
* @returns A function to unsubscribe the listener.
|
|
254
|
+
*/
|
|
255
|
+
subscribe(listener) {
|
|
256
|
+
this.listeners.add(listener);
|
|
257
|
+
return () => this.listeners.delete(listener);
|
|
258
|
+
}
|
|
259
|
+
/**
|
|
260
|
+
* Manually unsubscribe by listener
|
|
261
|
+
* @returns returns true if an listener has been removed, or false if the listener does not exist.
|
|
262
|
+
*/
|
|
263
|
+
unsubscribe(listener) {
|
|
264
|
+
return this.listeners.delete(listener);
|
|
265
|
+
}
|
|
266
|
+
/**
|
|
267
|
+
* Dispatches the event to all subscribed listeners.
|
|
268
|
+
*/
|
|
269
|
+
emit(...args) {
|
|
270
|
+
this.listeners.forEach((listener) => listener(...args));
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* Clears all listeners.
|
|
274
|
+
*/
|
|
275
|
+
clear() {
|
|
276
|
+
this.listeners.clear();
|
|
277
|
+
}
|
|
278
|
+
};
|
|
279
|
+
|
|
280
|
+
//#endregion
|
|
281
|
+
//#region src/math.ts
|
|
282
|
+
/**
|
|
283
|
+
* Clamps a number between an optional minimum and maximum value.
|
|
284
|
+
* @param val The number to clamp.
|
|
285
|
+
* @param min The minimum value. If null or undefined, it's ignored.
|
|
286
|
+
* @param max The maximum value. If null or undefined, it's ignored.
|
|
287
|
+
* @returns The clamped number.
|
|
288
|
+
*/
|
|
289
|
+
function clampNumber(val, min, max) {
|
|
290
|
+
if (!isNullOrUndefined(min)) val = Math.max(val, min);
|
|
291
|
+
if (!isNullOrUndefined(max)) val = Math.min(val, max);
|
|
292
|
+
return val;
|
|
293
|
+
}
|
|
294
|
+
/**
|
|
295
|
+
* Calculates a percentage of a given value.
|
|
296
|
+
* @param val The base value.
|
|
297
|
+
* @param percents The percentage to get.
|
|
298
|
+
* @returns The calculated percentage of the value.
|
|
299
|
+
* @example getPercentOf(200, 10); // returns 20
|
|
300
|
+
*/
|
|
301
|
+
function getPercentOf(val, percents) {
|
|
302
|
+
return percents / 100 * val;
|
|
303
|
+
}
|
|
304
|
+
|
|
305
|
+
//#endregion
|
|
306
|
+
//#region src/misc.ts
|
|
307
|
+
/**
|
|
308
|
+
* Returns the first key of an object.
|
|
309
|
+
* @param obj The object from which to get the key.
|
|
310
|
+
* @returns The first key of the object as a string.
|
|
311
|
+
*/
|
|
312
|
+
function firstKeyOf(obj) {
|
|
313
|
+
return Object.keys(obj)[0];
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
//#endregion
|
|
317
|
+
//#region src/path.ts
|
|
318
|
+
/**
|
|
319
|
+
* Ensures that the given path is returned as an array of segments.
|
|
320
|
+
*/
|
|
321
|
+
function ensurePathArray(path, separator = axiSettings.pathSeparator) {
|
|
322
|
+
return Array.isArray(path) ? [...path] : path.split(separator);
|
|
323
|
+
}
|
|
324
|
+
/**
|
|
325
|
+
* Ensures that the given path is returned as a single string.
|
|
326
|
+
*/
|
|
327
|
+
function ensurePathString(path, separator = axiSettings.pathSeparator) {
|
|
328
|
+
return !Array.isArray(path) ? path : path.join(separator);
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
//#endregion
|
|
332
|
+
//#region src/random.ts
|
|
333
|
+
/**
|
|
334
|
+
* Returns a random integer between min (inclusive) and max (exclusive).
|
|
335
|
+
* @param min The minimum integer (inclusive).
|
|
336
|
+
* @param max The maximum integer (exclusive).
|
|
337
|
+
* @returns A random integer.
|
|
338
|
+
* @example randInt(1, 5); // returns 1, 2, 3, or 4
|
|
339
|
+
*/
|
|
340
|
+
function randInt(min, max) {
|
|
341
|
+
min = Math.ceil(min);
|
|
342
|
+
max = Math.floor(max);
|
|
343
|
+
return Math.floor(Math.random() * (max - min) + min);
|
|
344
|
+
}
|
|
345
|
+
/**
|
|
346
|
+
* Generates a unique identifier using uuidv4.
|
|
347
|
+
* @returns A unique string ID.
|
|
348
|
+
*/
|
|
349
|
+
function randId() {
|
|
350
|
+
return (0, uuid.v4)();
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
//#endregion
|
|
354
|
+
exports.ConstructorRegistry = ConstructorRegistry;
|
|
355
|
+
exports.Emitter = Emitter;
|
|
356
|
+
exports.areArraysEqual = areArraysEqual;
|
|
357
|
+
exports.axiSettings = axiSettings;
|
|
358
|
+
exports.clampNumber = clampNumber;
|
|
359
|
+
exports.configure = configure;
|
|
360
|
+
exports.ensurePathArray = ensurePathArray;
|
|
361
|
+
exports.ensurePathString = ensurePathString;
|
|
362
|
+
exports.firstKeyOf = firstKeyOf;
|
|
363
|
+
exports.genArray = genArray;
|
|
364
|
+
exports.getPercentOf = getPercentOf;
|
|
365
|
+
exports.getRandomElement = getRandomElement;
|
|
366
|
+
exports.haveSameElements = haveSameElements;
|
|
367
|
+
exports.isBoolean = isBoolean;
|
|
368
|
+
exports.isNullOrUndefined = isNullOrUndefined;
|
|
369
|
+
exports.isNumber = isNumber;
|
|
370
|
+
exports.isPercentageString = isPercentageString;
|
|
371
|
+
exports.isSequentialStart = isSequentialStart;
|
|
372
|
+
exports.isString = isString;
|
|
373
|
+
exports.isUndefined = isUndefined;
|
|
374
|
+
exports.last = last;
|
|
375
|
+
exports.randId = randId;
|
|
376
|
+
exports.randInt = randInt;
|
|
377
|
+
exports.shuffleArray = shuffleArray;
|
|
378
|
+
exports.throwIf = throwIf;
|
|
379
|
+
exports.throwIfEmpty = throwIfEmpty;
|
|
380
|
+
exports.unique = unique;
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
//#region src/types.d.ts
|
|
1
2
|
/**
|
|
2
3
|
* Represents a path that can be provided as a single string
|
|
3
4
|
* or an array of segments.
|
|
@@ -38,16 +39,17 @@ type Constructor<T = {}> = new (...args: any[]) => T;
|
|
|
38
39
|
* @template T A tuple representing the types of the event arguments.
|
|
39
40
|
*/
|
|
40
41
|
type Subscribable<T extends any[]> = {
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
42
|
+
readonly listenerCount: number;
|
|
43
|
+
/**
|
|
44
|
+
* Subscribes a listener to this event.
|
|
45
|
+
* @returns A function to unsubscribe the listener.
|
|
46
|
+
*/
|
|
47
|
+
subscribe(listener: (...args: T) => void): () => void;
|
|
48
|
+
unsubscribe(listener: (...args: T) => void): boolean;
|
|
49
|
+
clear(): void;
|
|
49
50
|
};
|
|
50
|
-
|
|
51
|
+
//#endregion
|
|
52
|
+
//#region src/arrays.d.ts
|
|
51
53
|
/**
|
|
52
54
|
* Generates an array of numbers from 0 to length-1.
|
|
53
55
|
* @param length The desired length of the array.
|
|
@@ -119,7 +121,8 @@ declare function unique<T>(array: T[]): T[];
|
|
|
119
121
|
* @returns A random element from the array, or `undefined` if the array is empty.
|
|
120
122
|
*/
|
|
121
123
|
declare function getRandomElement<T>(array: T[]): T | undefined;
|
|
122
|
-
|
|
124
|
+
//#endregion
|
|
125
|
+
//#region src/assertion.d.ts
|
|
123
126
|
/**
|
|
124
127
|
* Throws an error if the condition is true.
|
|
125
128
|
* @param conditionForThrow - If true, an error will be thrown.
|
|
@@ -150,9 +153,10 @@ declare function throwIf(conditionForThrow: boolean, exceptionMessage: string):
|
|
|
150
153
|
* console.log('First item:', items[0]);
|
|
151
154
|
*/
|
|
152
155
|
declare function throwIfEmpty<T>(value: T, exceptionMessage: string): asserts value is NonNullable<T>;
|
|
153
|
-
|
|
156
|
+
//#endregion
|
|
157
|
+
//#region src/config.d.ts
|
|
154
158
|
interface AxiEngineConfig {
|
|
155
|
-
|
|
159
|
+
pathSeparator: string;
|
|
156
160
|
}
|
|
157
161
|
declare const axiSettings: AxiEngineConfig;
|
|
158
162
|
/**
|
|
@@ -160,38 +164,80 @@ declare const axiSettings: AxiEngineConfig;
|
|
|
160
164
|
* @param newConfig - configuration object
|
|
161
165
|
*/
|
|
162
166
|
declare function configure(newConfig: Partial<AxiEngineConfig>): void;
|
|
163
|
-
|
|
167
|
+
//#endregion
|
|
168
|
+
//#region src/constructor-registry.d.ts
|
|
169
|
+
/**
|
|
170
|
+
* A generic registry for mapping string identifiers to class constructors.
|
|
171
|
+
*
|
|
172
|
+
* This utility is fundamental for building extensible systems like dependency injection containers,
|
|
173
|
+
* factories, and serialization engines where types need to be dynamically resolved.
|
|
174
|
+
*
|
|
175
|
+
* @template T - A base type that all registered constructors must produce an instance of.
|
|
176
|
+
*/
|
|
177
|
+
declare class ConstructorRegistry<T> {
|
|
178
|
+
private readonly items;
|
|
179
|
+
/**
|
|
180
|
+
* Registers a constructor with a unique string identifier.
|
|
181
|
+
*
|
|
182
|
+
* @param typeId - The unique identifier for the constructor (e.g., a static `typeName` property from a class).
|
|
183
|
+
* @param ctor - The class constructor to register.
|
|
184
|
+
* @returns The registry instance for chainable calls.
|
|
185
|
+
* @throws If a constructor with the same `typeId` is already registered.
|
|
186
|
+
*/
|
|
187
|
+
register(typeId: string, ctor: Constructor<T>): this;
|
|
188
|
+
/**
|
|
189
|
+
* Retrieves a constructor by its identifier.
|
|
190
|
+
*
|
|
191
|
+
* @param typeId - The identifier of the constructor to retrieve.
|
|
192
|
+
* @returns The found class constructor.
|
|
193
|
+
* @throws If no constructor is found for the given `typeId`.
|
|
194
|
+
*/
|
|
195
|
+
get(typeId: string): Constructor<T>;
|
|
196
|
+
/**
|
|
197
|
+
* Checks if a constructor for a given identifier is registered.
|
|
198
|
+
* @param typeId - The identifier to check.
|
|
199
|
+
* @returns `true` if a constructor is registered, otherwise `false`.
|
|
200
|
+
*/
|
|
201
|
+
has(typeId: string): boolean;
|
|
202
|
+
/**
|
|
203
|
+
* Clears all registered constructors from the registry.
|
|
204
|
+
*/
|
|
205
|
+
clear(): void;
|
|
206
|
+
}
|
|
207
|
+
//#endregion
|
|
208
|
+
//#region src/emitter.d.ts
|
|
164
209
|
/**
|
|
165
210
|
* A minimal, type-safe event emitter for a single event.
|
|
166
211
|
* It does not manage state, it only manages subscribers and event dispatching.
|
|
167
212
|
* @template T A tuple representing the types of the event arguments.
|
|
168
213
|
*/
|
|
169
214
|
declare class Emitter<T extends any[]> implements Subscribable<T> {
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
215
|
+
private listeners;
|
|
216
|
+
/**
|
|
217
|
+
* Returns the number of listeners.
|
|
218
|
+
*/
|
|
219
|
+
get listenerCount(): number;
|
|
220
|
+
/**
|
|
221
|
+
* Subscribes a listener to this event.
|
|
222
|
+
* @returns A function to unsubscribe the listener.
|
|
223
|
+
*/
|
|
224
|
+
subscribe(listener: (...args: T) => void): () => void;
|
|
225
|
+
/**
|
|
226
|
+
* Manually unsubscribe by listener
|
|
227
|
+
* @returns returns true if an listener has been removed, or false if the listener does not exist.
|
|
228
|
+
*/
|
|
229
|
+
unsubscribe(listener: (...args: T) => void): boolean;
|
|
230
|
+
/**
|
|
231
|
+
* Dispatches the event to all subscribed listeners.
|
|
232
|
+
*/
|
|
233
|
+
emit(...args: T): void;
|
|
234
|
+
/**
|
|
235
|
+
* Clears all listeners.
|
|
236
|
+
*/
|
|
237
|
+
clear(): void;
|
|
193
238
|
}
|
|
194
|
-
|
|
239
|
+
//#endregion
|
|
240
|
+
//#region src/guards.d.ts
|
|
195
241
|
declare function isNullOrUndefined(val: unknown): val is null | undefined;
|
|
196
242
|
declare function isUndefined(val: unknown): val is undefined;
|
|
197
243
|
declare function isNumber(val: unknown): val is number;
|
|
@@ -203,7 +249,8 @@ declare function isString(val: unknown): val is string;
|
|
|
203
249
|
* @returns `true` if the value is a percentage string.
|
|
204
250
|
*/
|
|
205
251
|
declare function isPercentageString(val: unknown): val is string;
|
|
206
|
-
|
|
252
|
+
//#endregion
|
|
253
|
+
//#region src/math.d.ts
|
|
207
254
|
/**
|
|
208
255
|
* Clamps a number between an optional minimum and maximum value.
|
|
209
256
|
* @param val The number to clamp.
|
|
@@ -220,14 +267,16 @@ declare function clampNumber(val: number, min?: number | null, max?: number | nu
|
|
|
220
267
|
* @example getPercentOf(200, 10); // returns 20
|
|
221
268
|
*/
|
|
222
269
|
declare function getPercentOf(val: number, percents: number): number;
|
|
223
|
-
|
|
270
|
+
//#endregion
|
|
271
|
+
//#region src/misc.d.ts
|
|
224
272
|
/**
|
|
225
273
|
* Returns the first key of an object.
|
|
226
274
|
* @param obj The object from which to get the key.
|
|
227
275
|
* @returns The first key of the object as a string.
|
|
228
276
|
*/
|
|
229
277
|
declare function firstKeyOf(obj: any): string;
|
|
230
|
-
|
|
278
|
+
//#endregion
|
|
279
|
+
//#region src/path.d.ts
|
|
231
280
|
/**
|
|
232
281
|
* Ensures that the given path is returned as an array of segments.
|
|
233
282
|
*/
|
|
@@ -236,7 +285,8 @@ declare function ensurePathArray(path: PathType, separator?: string): string[];
|
|
|
236
285
|
* Ensures that the given path is returned as a single string.
|
|
237
286
|
*/
|
|
238
287
|
declare function ensurePathString(path: PathType, separator?: string): string;
|
|
239
|
-
|
|
288
|
+
//#endregion
|
|
289
|
+
//#region src/random.d.ts
|
|
240
290
|
/**
|
|
241
291
|
* Returns a random integer between min (inclusive) and max (exclusive).
|
|
242
292
|
* @param min The minimum integer (inclusive).
|
|
@@ -250,5 +300,6 @@ declare function randInt(min: number, max: number): number;
|
|
|
250
300
|
* @returns A unique string ID.
|
|
251
301
|
*/
|
|
252
302
|
declare function randId(): string;
|
|
253
|
-
|
|
254
|
-
export {
|
|
303
|
+
//#endregion
|
|
304
|
+
export { AxiEngineConfig, Constructor, ConstructorRegistry, Emitter, PathType, Subscribable, areArraysEqual, axiSettings, clampNumber, configure, ensurePathArray, ensurePathString, firstKeyOf, genArray, getPercentOf, getRandomElement, haveSameElements, isBoolean, isNullOrUndefined, isNumber, isPercentageString, isSequentialStart, isString, isUndefined, last, randId, randInt, shuffleArray, throwIf, throwIfEmpty, unique };
|
|
305
|
+
//# sourceMappingURL=index.d.cts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/arrays.ts","../src/assertion.ts","../src/config.ts","../src/constructor-registry.ts","../src/emitter.ts","../src/guards.ts","../src/math.ts","../src/misc.ts","../src/path.ts","../src/random.ts"],"mappings":"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"}
|