@venizia/ignis-helpers 0.4.8-13 → 0.4.8-14

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 (120) hide show
  1. package/dist/esm/common/redact.js.map +1 -1
  2. package/dist/esm/common/types/class.d.ts +14 -12
  3. package/dist/esm/common/types/class.js.map +1 -1
  4. package/dist/esm/common/types/const-value.d.ts +3 -3
  5. package/dist/esm/common/types/const-value.js.map +1 -1
  6. package/dist/esm/common/types/injection.d.ts +1 -1
  7. package/dist/esm/common/types/injection.js.map +1 -1
  8. package/dist/esm/common/types/utility.d.ts +0 -4
  9. package/dist/esm/common/types/utility.js.map +1 -1
  10. package/dist/esm/modules/env/app-env.d.ts +17 -8
  11. package/dist/esm/modules/env/app-env.js +18 -15
  12. package/dist/esm/modules/env/app-env.js.map +1 -1
  13. package/dist/esm/modules/env/common/types.d.ts +22 -6
  14. package/dist/esm/modules/env/common/types.js.map +1 -1
  15. package/dist/esm/modules/logger/base/abstract.d.ts +6 -7
  16. package/dist/esm/modules/logger/base/abstract.js.map +1 -1
  17. package/dist/esm/modules/logger/base/base.d.ts +7 -8
  18. package/dist/esm/modules/logger/base/base.js.map +1 -1
  19. package/dist/esm/modules/logger/base/console.d.ts +6 -7
  20. package/dist/esm/modules/logger/base/console.js.map +1 -1
  21. package/dist/esm/modules/logger/common/types.d.ts +7 -7
  22. package/dist/esm/modules/logger/common/types.js.map +1 -1
  23. package/dist/esm/modules/logger/factory.js.map +1 -1
  24. package/dist/esm/modules/logger/hf/flusher.js.map +1 -1
  25. package/dist/esm/modules/logger/hf/logger.d.ts +6 -7
  26. package/dist/esm/modules/logger/hf/logger.js.map +1 -1
  27. package/dist/esm/modules/logger/pino/backing.js.map +1 -1
  28. package/dist/esm/modules/logger/pino/destination.d.ts +1 -1
  29. package/dist/esm/modules/logger/pino/destination.js.map +1 -1
  30. package/dist/esm/modules/logger/pino/logger.d.ts +1 -2
  31. package/dist/esm/modules/logger/pino/logger.js.map +1 -1
  32. package/dist/esm/modules/logger/winston/formats.js +2 -2
  33. package/dist/esm/modules/logger/winston/formats.js.map +1 -1
  34. package/dist/esm/modules/logger/winston/logger.d.ts +1 -2
  35. package/dist/esm/modules/logger/winston/logger.js.map +1 -1
  36. package/dist/esm/modules/logger/winston/transports/dgram.transport.d.ts +1 -1
  37. package/dist/esm/modules/logger/winston/transports/dgram.transport.js +1 -1
  38. package/dist/esm/modules/logger/winston/transports/dgram.transport.js.map +1 -1
  39. package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.d.ts +5 -5
  40. package/dist/esm/modules/network/http-request/fetcher/axios-fetcher.js.map +1 -1
  41. package/dist/esm/modules/network/http-request/fetcher/base-fetcher.d.ts +1 -2
  42. package/dist/esm/modules/network/http-request/fetcher/base-fetcher.js.map +1 -1
  43. package/dist/esm/modules/network/http-request/fetcher/common/types.d.ts +1 -1
  44. package/dist/esm/modules/network/http-request/fetcher/common/types.js.map +1 -1
  45. package/dist/esm/modules/network/http-request/fetcher/node-fetcher.d.ts +1 -2
  46. package/dist/esm/modules/network/http-request/fetcher/node-fetcher.js +5 -6
  47. package/dist/esm/modules/network/http-request/fetcher/node-fetcher.js.map +1 -1
  48. package/dist/esm/modules/network/utilities/query-string.d.ts +2 -2
  49. package/dist/esm/modules/network/utilities/query-string.js.map +1 -1
  50. package/dist/esm/modules/network/utilities/url-safety/ingest.js.map +1 -1
  51. package/dist/esm/modules/queue/kafka/base.d.ts +1 -1
  52. package/dist/esm/modules/queue/kafka/base.js +13 -2
  53. package/dist/esm/modules/queue/kafka/base.js.map +1 -1
  54. package/dist/esm/modules/redis/cluster/cluster.helper.d.ts +1 -1
  55. package/dist/esm/modules/redis/cluster/cluster.helper.js +10 -3
  56. package/dist/esm/modules/redis/cluster/cluster.helper.js.map +1 -1
  57. package/dist/esm/modules/redis/cluster/index.d.ts +1 -0
  58. package/dist/esm/modules/redis/cluster/index.js +1 -0
  59. package/dist/esm/modules/redis/cluster/index.js.map +1 -1
  60. package/dist/esm/modules/redis/cluster/types.d.ts +20 -0
  61. package/dist/esm/modules/redis/cluster/types.js +2 -0
  62. package/dist/esm/modules/redis/cluster/types.js.map +1 -0
  63. package/dist/esm/modules/redis/common/constants.d.ts +2 -8
  64. package/dist/esm/modules/redis/common/constants.js +2 -5
  65. package/dist/esm/modules/redis/common/constants.js.map +1 -1
  66. package/dist/esm/modules/redis/common/types.d.ts +9 -62
  67. package/dist/esm/modules/redis/common/types.js.map +1 -1
  68. package/dist/esm/modules/redis/factory.d.ts +3 -4
  69. package/dist/esm/modules/redis/factory.js.map +1 -1
  70. package/dist/esm/modules/redis/sentinel/constants.d.ts +14 -0
  71. package/dist/esm/modules/redis/sentinel/constants.js +11 -0
  72. package/dist/esm/modules/redis/sentinel/constants.js.map +1 -0
  73. package/dist/esm/modules/redis/sentinel/index.d.ts +2 -0
  74. package/dist/esm/modules/redis/sentinel/index.js +2 -0
  75. package/dist/esm/modules/redis/sentinel/index.js.map +1 -1
  76. package/dist/esm/modules/redis/sentinel/sentinel.helper.d.ts +1 -1
  77. package/dist/esm/modules/redis/sentinel/sentinel.helper.js +18 -9
  78. package/dist/esm/modules/redis/sentinel/sentinel.helper.js.map +1 -1
  79. package/dist/esm/modules/redis/sentinel/types.d.ts +26 -0
  80. package/dist/esm/modules/redis/sentinel/types.js +2 -0
  81. package/dist/esm/modules/redis/sentinel/types.js.map +1 -0
  82. package/dist/esm/modules/redis/single/index.d.ts +1 -0
  83. package/dist/esm/modules/redis/single/index.js +1 -0
  84. package/dist/esm/modules/redis/single/index.js.map +1 -1
  85. package/dist/esm/modules/redis/single/single.helper.d.ts +1 -1
  86. package/dist/esm/modules/redis/single/single.helper.js +1 -1
  87. package/dist/esm/modules/redis/single/single.helper.js.map +1 -1
  88. package/dist/esm/modules/redis/single/types.d.ts +15 -0
  89. package/dist/esm/modules/redis/single/types.js +2 -0
  90. package/dist/esm/modules/redis/single/types.js.map +1 -0
  91. package/dist/esm/modules/secrets/base/abstract.helper.js +6 -1
  92. package/dist/esm/modules/secrets/base/abstract.helper.js.map +1 -1
  93. package/dist/esm/modules/secrets/common/types/registration.d.ts +25 -6
  94. package/dist/esm/modules/secrets/common/types/registration.js.map +1 -1
  95. package/dist/esm/modules/secrets/dotenv/dotenv.helper.js +1 -1
  96. package/dist/esm/modules/secrets/dotenv/dotenv.helper.js.map +1 -1
  97. package/dist/esm/modules/secrets/factory.js +7 -6
  98. package/dist/esm/modules/secrets/factory.js.map +1 -1
  99. package/dist/esm/modules/secrets/hashicorp/hashicorp.helper.d.ts +12 -10
  100. package/dist/esm/modules/secrets/hashicorp/hashicorp.helper.js +50 -25
  101. package/dist/esm/modules/secrets/hashicorp/hashicorp.helper.js.map +1 -1
  102. package/dist/esm/modules/storage/in-memory/helper.d.ts +2 -3
  103. package/dist/esm/modules/storage/in-memory/helper.js.map +1 -1
  104. package/dist/esm/modules/worker-thread/common/types.d.ts +2 -2
  105. package/dist/esm/modules/worker-thread/common/types.js.map +1 -1
  106. package/dist/esm/modules/worker-thread/thread/abstract.d.ts +2 -2
  107. package/dist/esm/modules/worker-thread/thread/abstract.js.map +1 -1
  108. package/dist/esm/modules/worker-thread/worker-pool.d.ts +1 -1
  109. package/dist/esm/modules/worker-thread/worker-pool.js.map +1 -1
  110. package/dist/esm/utilities/module.utility.d.ts +8 -5
  111. package/dist/esm/utilities/module.utility.js +5 -1
  112. package/dist/esm/utilities/module.utility.js.map +1 -1
  113. package/dist/esm/utilities/parse.utility.d.ts +34 -6
  114. package/dist/esm/utilities/parse.utility.js +82 -15
  115. package/dist/esm/utilities/parse.utility.js.map +1 -1
  116. package/dist/esm/utilities/performance.utility.d.ts +3 -3
  117. package/dist/esm/utilities/performance.utility.js.map +1 -1
  118. package/dist/esm/utilities/promise.utility.d.ts +1 -1
  119. package/dist/esm/utilities/promise.utility.js.map +1 -1
  120. package/package.json +3 -3
@@ -10,6 +10,12 @@ export declare class ParseUtility {
10
10
  * the sign of zero was the only disagreement.
11
11
  */
12
12
  private static round;
13
+ /**
14
+ * A rejected value for an error message: a number as `String` writes it (`NaN`, `Infinity`; JSON would write
15
+ * `null`), a string quoted and escaped, anything else as `EchoUtility.toSafeEcho` writes it. Longer than
16
+ * `ECHO_LIMIT` characters, it is cut and ends with an ellipsis, so a long value cannot flood a log line.
17
+ */
18
+ private static echoRejected;
13
19
  /** Arrays stay arrays - mapping one through the object branch would turn it into an index-keyed object - but their object elements still need their keys camelized. Dates are opaque values. */
14
20
  private static camelizeValue;
15
21
  /**
@@ -23,12 +29,12 @@ export declare class ParseUtility {
23
29
  }): string;
24
30
  static keysToCamel(opts: {
25
31
  source: object;
26
- }): any;
32
+ }): Record<string, unknown>;
27
33
  static isInt(opts: {
28
- input: any;
34
+ input: unknown;
29
35
  }): boolean;
30
36
  static isFloat(opts: {
31
- input: any;
37
+ input: unknown;
32
38
  }): boolean;
33
39
  /**
34
40
  * Parses an integer, TOTAL by design: it always answers a number, and answers `0` for anything it
@@ -47,14 +53,36 @@ export declare class ParseUtility {
47
53
  * through `AbstractRedisHelper.buildRetryStrategy` means "give up after the first failure".
48
54
  */
49
55
  static toInt(opts: {
50
- input: any;
56
+ input: unknown;
51
57
  }): number;
52
58
  static toFloat(opts: {
53
- input: any;
59
+ input: unknown;
54
60
  digit?: number;
55
61
  }): number;
62
+ /**
63
+ * Reads a number from a value that should hold one, and refuses anything else: the read of an environment
64
+ * variable, where `ParseUtility.toInt` answers `0` for garbage and `Number` answers `NaN`.
65
+ *
66
+ * - `undefined`, `null` and a blank string answer `undefined`: nothing was set, so a `defaultValue` applies.
67
+ * - A decimal number as text answers its value. Surrounding whitespace is allowed (`' 12 '` is `12`), so is
68
+ * an exponent (`'1e3'` is `1000`), a sign (`'-5'`) and a fraction (`'.5'`, `'5.'`).
69
+ * - Anything else throws: `'abc'`, `'12px'`, `'0x10'`, `'1,000'`, `'Infinity'`, `'NaN'`, a boolean or an object.
70
+ * A number that is not finite throws too; a finite number answers itself.
71
+ *
72
+ * @throws ApplicationError `[toNumber] <the value> is not a number`; the value is echoed escaped and cut at 40 characters.
73
+ * @example
74
+ * ```ts
75
+ * applicationEnvironment.get(KEY, {
76
+ * transform: (raw) => ParseUtility.toNumber({ input: raw }),
77
+ * defaultValue: 6379,
78
+ * });
79
+ * ```
80
+ */
81
+ static toNumber(opts: {
82
+ input: unknown;
83
+ }): number | undefined;
56
84
  static toBoolean(opts: {
57
- input: any;
85
+ input: unknown;
58
86
  }): boolean;
59
87
  /** Converts an array to a Map keyed by `key`. Last element wins on duplicate keys. */
60
88
  static parseArrayToMapWithKey<T extends Record<K, PropertyKey>, K extends keyof T>(opts: {
@@ -1,7 +1,13 @@
1
1
  import { getError } from '../modules/error/index.js';
2
2
  import { UidRandom } from '../modules/uid/common/random.js';
3
+ import { EchoUtility } from './echo.utility.js';
3
4
  const UID_BASE = 36;
4
5
  const UID_HALF_LENGTH = 5;
6
+ /** A decimal number as text: optional sign, digits with an optional fraction (`5.`, `.5`), an optional exponent. The fraction is one optional group, so a long run of digits that ends in a letter fails in linear time. Hex, octal, separators, `Infinity` and `NaN` are not numbers here. */
7
+ const DECIMAL_NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
8
+ /** The longest piece of a rejected value an error message echoes: a long value would flood a log line. */
9
+ const ECHO_LIMIT = 40;
10
+ const ECHO_ELLIPSIS = '...';
5
11
  /** Number, string and key conversions that tolerate bad input; no node import, so it ships on `/core`. */
6
12
  export class ParseUtility {
7
13
  /**
@@ -23,6 +29,28 @@ export class ParseUtility {
23
29
  const [shiftedMantissa, shiftedExponent] = `${shifted}e`.split('e');
24
30
  return Number(`${shiftedMantissa}e${Number(shiftedExponent) - precision}`) + 0;
25
31
  }
32
+ /**
33
+ * A rejected value for an error message: a number as `String` writes it (`NaN`, `Infinity`; JSON would write
34
+ * `null`), a string quoted and escaped, anything else as `EchoUtility.toSafeEcho` writes it. Longer than
35
+ * `ECHO_LIMIT` characters, it is cut and ends with an ellipsis, so a long value cannot flood a log line.
36
+ */
37
+ static echoRejected(opts) {
38
+ const { value } = opts;
39
+ if (typeof value === 'string') {
40
+ let kept = '';
41
+ let count = 0;
42
+ for (const character of value) {
43
+ if (count === ECHO_LIMIT) {
44
+ return `${EchoUtility.toSafeEcho({ value: kept }).slice(0, -1)}${ECHO_ELLIPSIS}"`;
45
+ }
46
+ kept += character;
47
+ count += 1;
48
+ }
49
+ return EchoUtility.toSafeEcho({ value: kept });
50
+ }
51
+ const echoed = typeof value === 'number' ? String(value) : EchoUtility.toSafeEcho({ value });
52
+ return echoed.length > ECHO_LIMIT ? `${echoed.slice(0, ECHO_LIMIT)}${ECHO_ELLIPSIS}` : echoed;
53
+ }
26
54
  /** Arrays stay arrays - mapping one through the object branch would turn it into an index-keyed object - but their object elements still need their keys camelized. Dates are opaque values. */
27
55
  static camelizeValue(opts) {
28
56
  const { value } = opts;
@@ -33,10 +61,9 @@ export class ParseUtility {
33
61
  return value;
34
62
  }
35
63
  const camelized = {};
36
- const valueKeys = Object.keys(value);
37
- for (const key of valueKeys) {
64
+ for (const [key, entry] of Object.entries(value)) {
38
65
  camelized[ParseUtility.toCamel({ input: key })] = ParseUtility.camelizeValue({
39
- value: value[key],
66
+ value: entry,
40
67
  });
41
68
  }
42
69
  return camelized;
@@ -65,24 +92,21 @@ export class ParseUtility {
65
92
  static keysToCamel(opts) {
66
93
  const { source } = opts;
67
94
  const n = {};
68
- const keys = Object.keys(source);
69
- for (const key of keys) {
70
- n[ParseUtility.toCamel({ input: key })] = ParseUtility.camelizeValue({
71
- value: source[key],
72
- });
95
+ for (const [key, entry] of Object.entries(source)) {
96
+ n[ParseUtility.toCamel({ input: key })] = ParseUtility.camelizeValue({ value: entry });
73
97
  }
74
98
  return n;
75
99
  }
76
100
  static isInt(opts) {
77
101
  const { input } = opts;
78
- if (isNaN(input)) {
102
+ if (Number.isNaN(Number(input))) {
79
103
  return false;
80
104
  }
81
105
  return (Number.isInteger(input) || Math.floor(Number(input)) === input || Number(input) % 1 === 0);
82
106
  }
83
107
  static isFloat(opts) {
84
108
  const { input } = opts;
85
- if (isNaN(input)) {
109
+ if (Number.isNaN(Number(input))) {
86
110
  return false;
87
111
  }
88
112
  return Number(input) === input || Number(input) % 1 !== 0;
@@ -108,8 +132,8 @@ export class ParseUtility {
108
132
  if (!input) {
109
133
  return 0;
110
134
  }
111
- const normalized = input?.toString()?.replace(/,/g, '');
112
- if (isNaN(normalized)) {
135
+ const normalized = String(input).replace(/,/g, '');
136
+ if (Number.isNaN(Number(normalized))) {
113
137
  return 0;
114
138
  }
115
139
  const parsed = Number.parseInt(normalized, 10);
@@ -120,13 +144,56 @@ export class ParseUtility {
120
144
  if (!input) {
121
145
  return 0;
122
146
  }
123
- const normalized = input?.toString()?.replace(/,/g, '');
124
- if (isNaN(normalized)) {
147
+ const normalized = String(input).replace(/,/g, '');
148
+ if (Number.isNaN(Number(normalized))) {
125
149
  return 0;
126
150
  }
127
151
  const parsed = ParseUtility.round({ value: Number.parseFloat(normalized), precision: digit });
128
152
  return Number.isNaN(parsed) ? 0 : parsed;
129
153
  }
154
+ /**
155
+ * Reads a number from a value that should hold one, and refuses anything else: the read of an environment
156
+ * variable, where `ParseUtility.toInt` answers `0` for garbage and `Number` answers `NaN`.
157
+ *
158
+ * - `undefined`, `null` and a blank string answer `undefined`: nothing was set, so a `defaultValue` applies.
159
+ * - A decimal number as text answers its value. Surrounding whitespace is allowed (`' 12 '` is `12`), so is
160
+ * an exponent (`'1e3'` is `1000`), a sign (`'-5'`) and a fraction (`'.5'`, `'5.'`).
161
+ * - Anything else throws: `'abc'`, `'12px'`, `'0x10'`, `'1,000'`, `'Infinity'`, `'NaN'`, a boolean or an object.
162
+ * A number that is not finite throws too; a finite number answers itself.
163
+ *
164
+ * @throws ApplicationError `[toNumber] <the value> is not a number`; the value is echoed escaped and cut at 40 characters.
165
+ * @example
166
+ * ```ts
167
+ * applicationEnvironment.get(KEY, {
168
+ * transform: (raw) => ParseUtility.toNumber({ input: raw }),
169
+ * defaultValue: 6379,
170
+ * });
171
+ * ```
172
+ */
173
+ static toNumber(opts) {
174
+ const { input } = opts;
175
+ if (input === undefined || input === null) {
176
+ return undefined;
177
+ }
178
+ if (typeof input === 'number' && Number.isFinite(input)) {
179
+ return input;
180
+ }
181
+ if (typeof input === 'string') {
182
+ const trimmed = input.trim();
183
+ if (trimmed === '') {
184
+ return undefined;
185
+ }
186
+ if (DECIMAL_NUMBER.test(trimmed)) {
187
+ const parsed = Number(trimmed);
188
+ if (Number.isFinite(parsed)) {
189
+ return parsed;
190
+ }
191
+ }
192
+ }
193
+ throw getError({
194
+ message: `[toNumber] ${ParseUtility.echoRejected({ value: input })} is not a number`,
195
+ });
196
+ }
130
197
  static toBoolean(opts) {
131
198
  const { input } = opts;
132
199
  return (input !== '' &&
@@ -198,7 +265,7 @@ export class ParseUtility {
198
265
  if (result == null) {
199
266
  throw getError({ message: `Cannot read property '${key}' of ${result}` });
200
267
  }
201
- result = result[key];
268
+ result = Reflect.get(Object(result), key);
202
269
  }
203
270
  return result;
204
271
  }
@@ -1 +1 @@
1
- {"version":3,"file":"parse.utility.js","sourceRoot":"","sources":["../../../src/utilities/parse.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { getError } from '@/modules/error';\nimport { UidRandom } from '@/modules/uid/common/random';\n\nconst UID_BASE = 36;\nconst UID_HALF_LENGTH = 5;\n\n/** Number, string and key conversions that tolerate bad input; no node import, so it ships on `/core`. */\nexport class ParseUtility {\n /**\n * Rounds at a decimal precision, shifting the exponent rather than multiplying: `1.005` at 2 is\n * `1.01` here, where `Math.round(1.005 * 100) / 100` gives `1`.\n *\n * Hand-written to keep lodash out of a browser bundle. One deliberate difference from `lodash/round`:\n * a result of negative zero is normalised to `0`. They compare equal, stringify the same and\n * serialise the same, so nothing downstream can tell - checked across 114 value/precision pairs, and\n * the sign of zero was the only disagreement.\n */\n private static round(opts: { value: number; precision?: number }): number {\n const { value, precision = 0 } = opts;\n\n if (!Number.isFinite(value) || precision === 0) {\n return Math.round(value) + 0;\n }\n\n const [mantissa, exponent] = `${value}e`.split('e');\n const shifted = Math.round(Number(`${mantissa}e${Number(exponent) + precision}`));\n const [shiftedMantissa, shiftedExponent] = `${shifted}e`.split('e');\n\n return Number(`${shiftedMantissa}e${Number(shiftedExponent) - precision}`) + 0;\n }\n\n /** Arrays stay arrays - mapping one through the object branch would turn it into an index-keyed object - but their object elements still need their keys camelized. Dates are opaque values. */\n private static camelizeValue(opts: { value: unknown }): unknown {\n const { value } = opts;\n\n if (Array.isArray(value)) {\n return value.map((element) => ParseUtility.camelizeValue({ value: element }));\n }\n\n if (!value || typeof value !== 'object' || value instanceof Date) {\n return value;\n }\n\n const camelized: any = {};\n const valueKeys = Object.keys(value);\n\n for (const key of valueKeys) {\n camelized[ParseUtility.toCamel({ input: key })] = ParseUtility.camelizeValue({\n value: (value as Record<string, unknown>)[key],\n });\n }\n\n return camelized;\n }\n\n /**\n * Ten uppercase base36 characters (`0-9A-Z`) from the platform CSPRNG, about 51 bits. Two draws of\n * five characters, because one draw covers at most `2 ** 48` and ten base36 characters need more.\n * A throwaway key for a test or a label, not a secret: use `TokenUidHelper` for a secret.\n */\n static getUID() {\n const half = Math.pow(UID_BASE, UID_HALF_LENGTH);\n let uid = '';\n\n for (let draw = 0; draw < 2; draw++) {\n uid += UidRandom.below({ max: half })\n .toString(UID_BASE)\n .padStart(UID_HALF_LENGTH, '0')\n .toUpperCase();\n }\n\n return uid;\n }\n\n static toCamel(opts: { input: string }) {\n return opts.input.replace(/([-_][a-z])/gi, (sub: string) => {\n return sub.toUpperCase().replace('-', '').replace('_', '');\n });\n }\n\n static keysToCamel(opts: { source: object }) {\n const { source } = opts;\n const n: any = {};\n const keys = Object.keys(source);\n\n for (const key of keys) {\n n[ParseUtility.toCamel({ input: key })] = ParseUtility.camelizeValue({\n value: (source as Record<string, unknown>)[key],\n });\n }\n\n return n;\n }\n\n static isInt(opts: { input: any }) {\n const { input } = opts;\n\n if (isNaN(input)) {\n return false;\n }\n\n return (\n Number.isInteger(input) || Math.floor(Number(input)) === input || Number(input) % 1 === 0\n );\n }\n\n static isFloat(opts: { input: any }) {\n const { input } = opts;\n\n if (isNaN(input)) {\n return false;\n }\n\n return Number(input) === input || Number(input) % 1 !== 0;\n }\n\n /**\n * Parses an integer, TOTAL by design: it always answers a number, and answers `0` for anything it\n * cannot parse - `undefined`, `''`, `'abc'`.\n *\n * That makes `ParseUtility.toInt({ input }) ?? fallback` dead code, because the left side is never\n * nullish. The fallback belongs INSIDE the call, and for an environment read it belongs in the read\n * itself:\n *\n * ```ts\n * ParseUtility.toInt({ input: applicationEnvironment.get(KEY, { defaultValue: '6379' }) }) // correct\n * ParseUtility.toInt({ input: applicationEnvironment.get(KEY) }) ?? 6379 // always 0 when KEY is unset\n * ```\n *\n * The second form is silent: a missing port reads `0` and a missing retry budget reads `0`, which\n * through `AbstractRedisHelper.buildRetryStrategy` means \"give up after the first failure\".\n */\n static toInt(opts: { input: any }) {\n const { input } = opts;\n\n if (!input) {\n return 0;\n }\n\n const normalized = input?.toString()?.replace(/,/g, '');\n\n if (isNaN(normalized)) {\n return 0;\n }\n\n const parsed = Number.parseInt(normalized, 10);\n\n return Number.isNaN(parsed) ? 0 : parsed;\n }\n\n static toFloat(opts: { input: any; digit?: number }) {\n const { input, digit = 2 } = opts;\n\n if (!input) {\n return 0;\n }\n\n const normalized = input?.toString()?.replace(/,/g, '');\n\n if (isNaN(normalized)) {\n return 0;\n }\n\n const parsed = ParseUtility.round({ value: Number.parseFloat(normalized), precision: digit });\n\n return Number.isNaN(parsed) ? 0 : parsed;\n }\n\n static toBoolean(opts: { input: any }): boolean {\n const { input } = opts;\n\n return (\n input !== '' &&\n input !== 'false' &&\n input !== '0' &&\n input !== false &&\n input !== 0 &&\n input !== null &&\n input !== undefined\n );\n }\n\n /** Converts an array to a Map keyed by `key`. Last element wins on duplicate keys. */\n static parseArrayToMapWithKey<T extends Record<K, PropertyKey>, K extends keyof T>(opts: {\n items: T[];\n key: K;\n }): Map<T[K], T> {\n const { items, key } = opts;\n const resultMap = new Map<T[K], T>();\n\n if (!items.length) {\n return resultMap;\n }\n\n items.forEach((element) => {\n if (!(key in element)) {\n throw getError({\n message: 'Invalid keyMap',\n });\n }\n\n resultMap.set(element[key], element);\n });\n\n return resultMap;\n }\n\n /** Splits a delimited string into trimmed, non-empty entries - the transform for list-shaped env values (e.g. `applicationEnvironment.get(KEY, { transform: (input) => ParseUtility.toDelimitedArray({ input }) })`). */\n static toDelimitedArray(opts: { input: unknown; separator?: string }): string[] {\n const { input, separator = ',' } = opts;\n\n if (input == null) {\n return [];\n }\n\n return String(input)\n .split(separator)\n .map((entry) => entry.trim())\n .filter((entry) => entry.length > 0);\n }\n\n /**\n * A trimmed value, or `undefined` when the input is absent or carries nothing but whitespace.\n *\n * Written for environment reads. `KEY=` in a deployment file is a pipeline that forgot to export the\n * value, but `process.env.KEY` answers `''` for it, and `''` walks straight past `??`:\n *\n * ```ts\n * process.env.APP_ENV_LOGGER_FORMAT ?? 'text' // '' when the line is blank\n * ParseUtility.blankToUndefined({ input: process.env.APP_ENV_LOGGER_FORMAT }) ?? 'text' // 'text'\n * ```\n *\n * Reach for this rather than `||`, which reads `'0'` as blank as well.\n */\n static blankToUndefined(opts: { input: string | undefined }): string | undefined {\n const trimmed = opts.input?.trim();\n\n return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;\n }\n\n /** Trims a possibly-undefined env value to a clean string ('' when absent). */\n static toTrimmed(opts: { input: unknown }): string {\n const { input } = opts;\n\n if (input == null) {\n return '';\n }\n\n return String(input).trim();\n }\n\n /** Traverse a dotted property path on an object. */\n static getDeepProperty<T, V>(opts: { source: T; path: string }): V {\n const keys = opts.path.split('.');\n let result: any = opts.source;\n\n for (const key of keys) {\n if (result == null) {\n throw getError({ message: `Cannot read property '${key}' of ${result}` });\n }\n\n result = result[key];\n }\n\n return result as V;\n }\n}\n"]}
1
+ {"version":3,"file":"parse.utility.js","sourceRoot":"","sources":["../../../src/utilities/parse.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { getError } from '@/modules/error';\nimport { UidRandom } from '@/modules/uid/common/random';\nimport { EchoUtility } from './echo.utility';\n\nconst UID_BASE = 36;\nconst UID_HALF_LENGTH = 5;\n\n/** A decimal number as text: optional sign, digits with an optional fraction (`5.`, `.5`), an optional exponent. The fraction is one optional group, so a long run of digits that ends in a letter fails in linear time. Hex, octal, separators, `Infinity` and `NaN` are not numbers here. */\nconst DECIMAL_NUMBER = /^[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?$/;\n\n/** The longest piece of a rejected value an error message echoes: a long value would flood a log line. */\nconst ECHO_LIMIT = 40;\nconst ECHO_ELLIPSIS = '...';\n\n/** Number, string and key conversions that tolerate bad input; no node import, so it ships on `/core`. */\nexport class ParseUtility {\n /**\n * Rounds at a decimal precision, shifting the exponent rather than multiplying: `1.005` at 2 is\n * `1.01` here, where `Math.round(1.005 * 100) / 100` gives `1`.\n *\n * Hand-written to keep lodash out of a browser bundle. One deliberate difference from `lodash/round`:\n * a result of negative zero is normalised to `0`. They compare equal, stringify the same and\n * serialise the same, so nothing downstream can tell - checked across 114 value/precision pairs, and\n * the sign of zero was the only disagreement.\n */\n private static round(opts: { value: number; precision?: number }): number {\n const { value, precision = 0 } = opts;\n\n if (!Number.isFinite(value) || precision === 0) {\n return Math.round(value) + 0;\n }\n\n const [mantissa, exponent] = `${value}e`.split('e');\n const shifted = Math.round(Number(`${mantissa}e${Number(exponent) + precision}`));\n const [shiftedMantissa, shiftedExponent] = `${shifted}e`.split('e');\n\n return Number(`${shiftedMantissa}e${Number(shiftedExponent) - precision}`) + 0;\n }\n\n /**\n * A rejected value for an error message: a number as `String` writes it (`NaN`, `Infinity`; JSON would write\n * `null`), a string quoted and escaped, anything else as `EchoUtility.toSafeEcho` writes it. Longer than\n * `ECHO_LIMIT` characters, it is cut and ends with an ellipsis, so a long value cannot flood a log line.\n */\n private static echoRejected(opts: { value: unknown }): string {\n const { value } = opts;\n\n if (typeof value === 'string') {\n let kept = '';\n let count = 0;\n\n for (const character of value) {\n if (count === ECHO_LIMIT) {\n return `${EchoUtility.toSafeEcho({ value: kept }).slice(0, -1)}${ECHO_ELLIPSIS}\"`;\n }\n\n kept += character;\n count += 1;\n }\n\n return EchoUtility.toSafeEcho({ value: kept });\n }\n\n const echoed = typeof value === 'number' ? String(value) : EchoUtility.toSafeEcho({ value });\n\n return echoed.length > ECHO_LIMIT ? `${echoed.slice(0, ECHO_LIMIT)}${ECHO_ELLIPSIS}` : echoed;\n }\n\n /** Arrays stay arrays - mapping one through the object branch would turn it into an index-keyed object - but their object elements still need their keys camelized. Dates are opaque values. */\n private static camelizeValue(opts: { value: unknown }): unknown {\n const { value } = opts;\n\n if (Array.isArray(value)) {\n return value.map((element) => ParseUtility.camelizeValue({ value: element }));\n }\n\n if (!value || typeof value !== 'object' || value instanceof Date) {\n return value;\n }\n\n const camelized: Record<string, unknown> = {};\n\n for (const [key, entry] of Object.entries(value)) {\n camelized[ParseUtility.toCamel({ input: key })] = ParseUtility.camelizeValue({\n value: entry,\n });\n }\n\n return camelized;\n }\n\n /**\n * Ten uppercase base36 characters (`0-9A-Z`) from the platform CSPRNG, about 51 bits. Two draws of\n * five characters, because one draw covers at most `2 ** 48` and ten base36 characters need more.\n * A throwaway key for a test or a label, not a secret: use `TokenUidHelper` for a secret.\n */\n static getUID() {\n const half = Math.pow(UID_BASE, UID_HALF_LENGTH);\n let uid = '';\n\n for (let draw = 0; draw < 2; draw++) {\n uid += UidRandom.below({ max: half })\n .toString(UID_BASE)\n .padStart(UID_HALF_LENGTH, '0')\n .toUpperCase();\n }\n\n return uid;\n }\n\n static toCamel(opts: { input: string }) {\n return opts.input.replace(/([-_][a-z])/gi, (sub: string) => {\n return sub.toUpperCase().replace('-', '').replace('_', '');\n });\n }\n\n static keysToCamel(opts: { source: object }) {\n const { source } = opts;\n const n: Record<string, unknown> = {};\n\n for (const [key, entry] of Object.entries(source)) {\n n[ParseUtility.toCamel({ input: key })] = ParseUtility.camelizeValue({ value: entry });\n }\n\n return n;\n }\n\n static isInt(opts: { input: unknown }) {\n const { input } = opts;\n\n if (Number.isNaN(Number(input))) {\n return false;\n }\n\n return (\n Number.isInteger(input) || Math.floor(Number(input)) === input || Number(input) % 1 === 0\n );\n }\n\n static isFloat(opts: { input: unknown }) {\n const { input } = opts;\n\n if (Number.isNaN(Number(input))) {\n return false;\n }\n\n return Number(input) === input || Number(input) % 1 !== 0;\n }\n\n /**\n * Parses an integer, TOTAL by design: it always answers a number, and answers `0` for anything it\n * cannot parse - `undefined`, `''`, `'abc'`.\n *\n * That makes `ParseUtility.toInt({ input }) ?? fallback` dead code, because the left side is never\n * nullish. The fallback belongs INSIDE the call, and for an environment read it belongs in the read\n * itself:\n *\n * ```ts\n * ParseUtility.toInt({ input: applicationEnvironment.get(KEY, { defaultValue: '6379' }) }) // correct\n * ParseUtility.toInt({ input: applicationEnvironment.get(KEY) }) ?? 6379 // always 0 when KEY is unset\n * ```\n *\n * The second form is silent: a missing port reads `0` and a missing retry budget reads `0`, which\n * through `AbstractRedisHelper.buildRetryStrategy` means \"give up after the first failure\".\n */\n static toInt(opts: { input: unknown }) {\n const { input } = opts;\n\n if (!input) {\n return 0;\n }\n\n const normalized = String(input).replace(/,/g, '');\n\n if (Number.isNaN(Number(normalized))) {\n return 0;\n }\n\n const parsed = Number.parseInt(normalized, 10);\n\n return Number.isNaN(parsed) ? 0 : parsed;\n }\n\n static toFloat(opts: { input: unknown; digit?: number }) {\n const { input, digit = 2 } = opts;\n\n if (!input) {\n return 0;\n }\n\n const normalized = String(input).replace(/,/g, '');\n\n if (Number.isNaN(Number(normalized))) {\n return 0;\n }\n\n const parsed = ParseUtility.round({ value: Number.parseFloat(normalized), precision: digit });\n\n return Number.isNaN(parsed) ? 0 : parsed;\n }\n\n /**\n * Reads a number from a value that should hold one, and refuses anything else: the read of an environment\n * variable, where `ParseUtility.toInt` answers `0` for garbage and `Number` answers `NaN`.\n *\n * - `undefined`, `null` and a blank string answer `undefined`: nothing was set, so a `defaultValue` applies.\n * - A decimal number as text answers its value. Surrounding whitespace is allowed (`' 12 '` is `12`), so is\n * an exponent (`'1e3'` is `1000`), a sign (`'-5'`) and a fraction (`'.5'`, `'5.'`).\n * - Anything else throws: `'abc'`, `'12px'`, `'0x10'`, `'1,000'`, `'Infinity'`, `'NaN'`, a boolean or an object.\n * A number that is not finite throws too; a finite number answers itself.\n *\n * @throws ApplicationError `[toNumber] <the value> is not a number`; the value is echoed escaped and cut at 40 characters.\n * @example\n * ```ts\n * applicationEnvironment.get(KEY, {\n * transform: (raw) => ParseUtility.toNumber({ input: raw }),\n * defaultValue: 6379,\n * });\n * ```\n */\n static toNumber(opts: { input: unknown }): number | undefined {\n const { input } = opts;\n\n if (input === undefined || input === null) {\n return undefined;\n }\n\n if (typeof input === 'number' && Number.isFinite(input)) {\n return input;\n }\n\n if (typeof input === 'string') {\n const trimmed = input.trim();\n\n if (trimmed === '') {\n return undefined;\n }\n\n if (DECIMAL_NUMBER.test(trimmed)) {\n const parsed = Number(trimmed);\n\n if (Number.isFinite(parsed)) {\n return parsed;\n }\n }\n }\n\n throw getError({\n message: `[toNumber] ${ParseUtility.echoRejected({ value: input })} is not a number`,\n });\n }\n\n static toBoolean(opts: { input: unknown }): boolean {\n const { input } = opts;\n\n return (\n input !== '' &&\n input !== 'false' &&\n input !== '0' &&\n input !== false &&\n input !== 0 &&\n input !== null &&\n input !== undefined\n );\n }\n\n /** Converts an array to a Map keyed by `key`. Last element wins on duplicate keys. */\n static parseArrayToMapWithKey<T extends Record<K, PropertyKey>, K extends keyof T>(opts: {\n items: T[];\n key: K;\n }): Map<T[K], T> {\n const { items, key } = opts;\n const resultMap = new Map<T[K], T>();\n\n if (!items.length) {\n return resultMap;\n }\n\n items.forEach((element) => {\n if (!(key in element)) {\n throw getError({\n message: 'Invalid keyMap',\n });\n }\n\n resultMap.set(element[key], element);\n });\n\n return resultMap;\n }\n\n /** Splits a delimited string into trimmed, non-empty entries - the transform for list-shaped env values (e.g. `applicationEnvironment.get(KEY, { transform: (input) => ParseUtility.toDelimitedArray({ input }) })`). */\n static toDelimitedArray(opts: { input: unknown; separator?: string }): string[] {\n const { input, separator = ',' } = opts;\n\n if (input == null) {\n return [];\n }\n\n return String(input)\n .split(separator)\n .map((entry) => entry.trim())\n .filter((entry) => entry.length > 0);\n }\n\n /**\n * A trimmed value, or `undefined` when the input is absent or carries nothing but whitespace.\n *\n * Written for environment reads. `KEY=` in a deployment file is a pipeline that forgot to export the\n * value, but `process.env.KEY` answers `''` for it, and `''` walks straight past `??`:\n *\n * ```ts\n * process.env.APP_ENV_LOGGER_FORMAT ?? 'text' // '' when the line is blank\n * ParseUtility.blankToUndefined({ input: process.env.APP_ENV_LOGGER_FORMAT }) ?? 'text' // 'text'\n * ```\n *\n * Reach for this rather than `||`, which reads `'0'` as blank as well.\n */\n static blankToUndefined(opts: { input: string | undefined }): string | undefined {\n const trimmed = opts.input?.trim();\n\n return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;\n }\n\n /** Trims a possibly-undefined env value to a clean string ('' when absent). */\n static toTrimmed(opts: { input: unknown }): string {\n const { input } = opts;\n\n if (input == null) {\n return '';\n }\n\n return String(input).trim();\n }\n\n /** Traverse a dotted property path on an object. */\n static getDeepProperty<T, V>(opts: { source: T; path: string }): V {\n const keys = opts.path.split('.');\n let result: unknown = opts.source;\n\n for (const key of keys) {\n if (result == null) {\n throw getError({ message: `Cannot read property '${key}' of ${result}` });\n }\n\n result = Reflect.get(Object(result), key);\n }\n\n return result as V;\n }\n}\n"]}
@@ -6,13 +6,13 @@ export declare class PerformanceUtility {
6
6
  from: number;
7
7
  digit?: number;
8
8
  }): number;
9
- static executeWithMeasure<R = any>(opts: {
9
+ static executeWithMeasure<R>(opts: {
10
10
  logger?: ILogger;
11
11
  level?: string;
12
12
  description?: string;
13
- args?: any;
13
+ args?: unknown;
14
14
  scope: string;
15
- task: Function;
15
+ task: () => R | Promise<R>;
16
16
  }): Promise<R>;
17
17
  }
18
18
  //# sourceMappingURL=performance.utility.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"performance.utility.js","sourceRoot":"","sources":["../../../src/utilities/performance.utility.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAItC,2GAA2G;AAC3G,MAAM,OAAO,kBAAkB;IAC7B,MAAM,CAAC,aAAa;QAClB,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,IAAsC;QACvD,OAAO,YAAY,CAAC,OAAO,CAAC;YAC1B,KAAK,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI;YACpC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,2BAA2B;SACjD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,kBAAkB,CAAU,IAOlC;QACC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAC5B,MAAM,EACJ,MAAM,GAAG,OAAO,EAChB,KAAK,GAAG,OAAO,EACf,KAAK,EACL,WAAW,GAAG,WAAW,EACzB,IAAI,EACJ,IAAI,GACL,GAAG,IAAI,CAAC;YAET,sIAAsI;YACtI,MAAM,MAAM,GAAe,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YACtD,MAAM,GAAG,GAAG,CAAC,OAAe,EAAE,GAAG,MAAsB,EAAE,EAAE,CACzD,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC;YAE1C,IAAI,IAAI,EAAE,CAAC;gBACT,GAAG,CAAC,+BAA+B,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;YACjE,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,qBAAqB,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YACjD,CAAC;YAED,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;iBACpB,IAAI,CAAC,OAAO,CAAC;iBACb,KAAK,CAAC,MAAM,CAAC;iBACb,OAAO,CAAC,GAAG,EAAE;gBACZ,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAEnC,IAAI,IAAI,EAAE,CAAC;oBACT,GAAG,CAAC,2CAA2C,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBACnF,CAAC;qBAAM,CAAC;oBACN,GAAG,CAAC,gCAAgC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;gBAClE,CAAC;YACH,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import { type AnyType } from '@/common/types';\nimport { type ILogger } from '@/modules/logger';\nimport { ParseUtility } from './parse.utility';\n\nconst DEFAULT_PERFORMANCE_DECIMAL = 6;\n\ntype TLogMethod = (message: string, ...args: Array<AnyType>) => void;\n\n/** Timing helpers on `performance.now()`: checkpoints, elapsed milliseconds and a measured task runner. */\nexport class PerformanceUtility {\n static getCheckpoint() {\n return performance.now();\n }\n\n static getExecuted(opts: { from: number; digit?: number }) {\n return ParseUtility.toFloat({\n input: performance.now() - opts.from,\n digit: opts.digit ?? DEFAULT_PERFORMANCE_DECIMAL,\n });\n }\n\n static executeWithMeasure<R = any>(opts: {\n logger?: ILogger;\n level?: string;\n description?: string;\n args?: any;\n scope: string;\n task: Function;\n }) {\n return new Promise<R>((resolve, reject) => {\n const t = performance.now();\n const {\n logger = console,\n level = 'debug',\n scope,\n description = 'Executing',\n args,\n task,\n } = opts;\n\n // `level` names a method on whichever logger was passed, so it is looked up, not indexed; the call keeps `this` bound to that logger.\n const method: TLogMethod = Reflect.get(logger, level);\n const log = (message: string, ...params: Array<AnyType>) =>\n method.call(logger, message, ...params);\n\n if (args) {\n log('[%s] START | %s... | Args: %j', scope, description, args);\n } else {\n log('[%s] START | %s ...', scope, description);\n }\n\n Promise.resolve(task())\n .then(resolve)\n .catch(reject)\n .finally(() => {\n const took = performance.now() - t;\n\n if (args) {\n log('[%s] DONE | %s | Args: %j | Took: %s (ms)', scope, description, args, took);\n } else {\n log('[%s] DONE | %s | Took: %s (ms)', scope, description, took);\n }\n });\n });\n }\n}\n"]}
1
+ {"version":3,"file":"performance.utility.js","sourceRoot":"","sources":["../../../src/utilities/performance.utility.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAItC,2GAA2G;AAC3G,MAAM,OAAO,kBAAkB;IAC7B,MAAM,CAAC,aAAa;QAClB,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC;IAC3B,CAAC;IAED,MAAM,CAAC,WAAW,CAAC,IAAsC;QACvD,OAAO,YAAY,CAAC,OAAO,CAAC;YAC1B,KAAK,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI;YACpC,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,2BAA2B;SACjD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,CAAC,kBAAkB,CAAI,IAO5B;QACC,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACxC,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAC5B,MAAM,EACJ,MAAM,GAAG,OAAO,EAChB,KAAK,GAAG,OAAO,EACf,KAAK,EACL,WAAW,GAAG,WAAW,EACzB,IAAI,EACJ,IAAI,GACL,GAAG,IAAI,CAAC;YAET,sIAAsI;YACtI,MAAM,MAAM,GAAe,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YACtD,MAAM,GAAG,GAAG,CAAC,OAAe,EAAE,GAAG,MAAiB,EAAE,EAAE,CACpD,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC;YAE1C,IAAI,IAAI,EAAE,CAAC;gBACT,GAAG,CAAC,+BAA+B,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;YACjE,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,qBAAqB,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;YACjD,CAAC;YAED,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;iBACpB,IAAI,CAAC,OAAO,CAAC;iBACb,KAAK,CAAC,MAAM,CAAC;iBACb,OAAO,CAAC,GAAG,EAAE;gBACZ,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAEnC,IAAI,IAAI,EAAE,CAAC;oBACT,GAAG,CAAC,2CAA2C,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;gBACnF,CAAC;qBAAM,CAAC;oBACN,GAAG,CAAC,gCAAgC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC;gBAClE,CAAC;YACH,CAAC,CAAC,CAAC;QACP,CAAC,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import { type ILogger } from '@/modules/logger';\nimport { ParseUtility } from './parse.utility';\n\nconst DEFAULT_PERFORMANCE_DECIMAL = 6;\n\ntype TLogMethod = (message: string, ...args: unknown[]) => void;\n\n/** Timing helpers on `performance.now()`: checkpoints, elapsed milliseconds and a measured task runner. */\nexport class PerformanceUtility {\n static getCheckpoint() {\n return performance.now();\n }\n\n static getExecuted(opts: { from: number; digit?: number }) {\n return ParseUtility.toFloat({\n input: performance.now() - opts.from,\n digit: opts.digit ?? DEFAULT_PERFORMANCE_DECIMAL,\n });\n }\n\n static executeWithMeasure<R>(opts: {\n logger?: ILogger;\n level?: string;\n description?: string;\n args?: unknown;\n scope: string;\n task: () => R | Promise<R>;\n }) {\n return new Promise<R>((resolve, reject) => {\n const t = performance.now();\n const {\n logger = console,\n level = 'debug',\n scope,\n description = 'Executing',\n args,\n task,\n } = opts;\n\n // `level` names a method on whichever logger was passed, so it is looked up, not indexed; the call keeps `this` bound to that logger.\n const method: TLogMethod = Reflect.get(logger, level);\n const log = (message: string, ...params: unknown[]) =>\n method.call(logger, message, ...params);\n\n if (args) {\n log('[%s] START | %s... | Args: %j', scope, description, args);\n } else {\n log('[%s] START | %s ...', scope, description);\n }\n\n Promise.resolve(task())\n .then(resolve)\n .catch(reject)\n .finally(() => {\n const took = performance.now() - t;\n\n if (args) {\n log('[%s] DONE | %s | Args: %j | Took: %s (ms)', scope, description, args, took);\n } else {\n log('[%s] DONE | %s | Took: %s (ms)', scope, description, took);\n }\n });\n });\n }\n}\n"]}
@@ -1,7 +1,7 @@
1
1
  import { type ValueOrPromise } from '../common/index.js';
2
2
  import type { ILogger } from '../modules/logger/index.js';
3
3
  /** An async task as `executeWithLimit` takes it. */
4
- export type TTask<T> = (...args: any[]) => Promise<T>;
4
+ export type TTask<T> = (...args: never[]) => Promise<T>;
5
5
  /** Check if a value is a promise. */
6
6
  export declare const isPromiseLike: <T>(value: T | PromiseLike<T>) => value is PromiseLike<T>;
7
7
  /** Waiting, bounded concurrency and fire-and-forget. `voidExecution` is not a `BaseHelper` member: TS cannot emit protected members on an exported ANONYMOUS class (TS4094), which is what factory-built controllers return; a static on a separate class has no such limit. */
@@ -1 +1 @@
1
- {"version":3,"file":"promise.utility.js","sourceRoot":"","sources":["../../../src/utilities/promise.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ValueOrPromise } from '@/common';\nimport { HTTP } from '@/common/constants/http';\nimport { getError } from '@/modules/error';\nimport type { ILogger } from '@/modules/logger';\n\n/** An async task as `executeWithLimit` takes it. */\nexport type TTask<T> = (...args: any[]) => Promise<T>;\n\n/** Check if a value is a promise. */\nexport const isPromiseLike = <T>(value: T | PromiseLike<T>): value is PromiseLike<T> => {\n return (\n !!value &&\n (typeof value === 'object' || typeof value === 'function') &&\n typeof (value as PromiseLike<T>).then === 'function'\n );\n};\n\n/** Waiting, bounded concurrency and fire-and-forget. `voidExecution` is not a `BaseHelper` member: TS cannot emit protected members on an exported ANONYMOUS class (TS4094), which is what factory-built controllers return; a static on a separate class has no such limit. */\nexport class PromiseUtility {\n /** The longest delay a timer takes (a signed 32-bit integer of milliseconds); a larger one fires after 1 ms. */\n private static readonly MAX_TIMER_MS = 2_147_483_647;\n\n static sleep(opts: { ms: number }): Promise<void> {\n return new Promise((resolve) => setTimeout(resolve, opts.ms));\n }\n\n /**\n * Runs `call` and resolves with its result, or rejects with an `ApplicationError` when `timeoutMs` passes first\n * (`message` is the error text; the default names the limit). The timer is cleared on every path - the call wins,\n * the timeout wins, the call throws - so none is left behind. The call's own rejection passes through unchanged.\n * The losing call keeps running: a promise cannot be cancelled. The timeout error carries status 504 (Gateway\n * Timeout). `timeoutMs` must be a positive number no larger than `2_147_483_647` (the most a timer takes: a larger\n * one fires at once), else this rejects without running `call`.\n */\n static async withTimeout<T>(opts: {\n call: () => ValueOrPromise<T>;\n timeoutMs: number;\n message?: string;\n }): Promise<T> {\n const { call, timeoutMs, message } = opts;\n\n if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > PromiseUtility.MAX_TIMER_MS) {\n throw getError({\n message: `[withTimeout] timeoutMs must be positive and at most ${PromiseUtility.MAX_TIMER_MS} | received: ${timeoutMs}`,\n });\n }\n\n let timer: ReturnType<typeof setTimeout> | undefined;\n const timeout = new Promise<never>((_resolve, reject) => {\n timer = setTimeout(() => {\n reject(\n getError({\n statusCode: HTTP.ResultCodes.RS_5.GatewayTimeout,\n message: message ?? `[withTimeout] Timed out after ${timeoutMs}ms`,\n }),\n );\n }, timeoutMs);\n });\n\n try {\n const result = await Promise.race([new Promise<T>((resolve) => resolve(call())), timeout]);\n\n return result;\n } finally {\n clearTimeout(timer);\n }\n }\n\n /** Execute async tasks with bounded concurrency. */\n static async executeWithLimit<T>(opts: {\n tasks: Array<TTask<T>>;\n limit: number;\n onTaskDone?: <R>(opts: { result: R }) => ValueOrPromise<void>;\n }) {\n const { tasks, limit, onTaskDone } = opts;\n\n if (!Number.isInteger(limit) || limit < 1) {\n throw getError({\n message: `[executePromiseWithLimit] limit must be a positive integer | received: ${limit}`,\n });\n }\n\n const results: Promise<T>[] = [];\n const executing = new Set();\n\n for (const task of tasks) {\n const promise = task().then((result) => {\n executing.delete(promise);\n\n return result;\n });\n\n executing.add(promise);\n results.push(promise);\n\n if (executing.size >= limit) {\n const done = await Promise.race(executing);\n await onTaskDone?.({ result: done });\n }\n }\n\n await Promise.all(executing);\n\n return Promise.all(results);\n }\n\n /** Fire-and-forget: routes rejection to `logger` (or console.error), passes sync results through untouched. */\n static voidExecution(opts: {\n logger?: ILogger;\n scope: string;\n execution: ValueOrPromise<unknown>;\n }): void {\n const { logger, scope, execution } = opts;\n\n if (!isPromiseLike(execution)) {\n return;\n }\n\n Promise.resolve(execution).catch((error: unknown) => {\n if (logger) {\n logger.for(scope).error('Unhandled error in fire-and-forget execution | Error: %s', error);\n\n return;\n }\n\n console.error('[%s] Unhandled error in fire-and-forget execution', scope, error);\n });\n }\n}\n"]}
1
+ {"version":3,"file":"promise.utility.js","sourceRoot":"","sources":["../../../src/utilities/promise.utility.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ValueOrPromise } from '@/common';\nimport { HTTP } from '@/common/constants/http';\nimport { getError } from '@/modules/error';\nimport type { ILogger } from '@/modules/logger';\n\n/** An async task as `executeWithLimit` takes it. */\nexport type TTask<T> = (...args: never[]) => Promise<T>;\n\n/** Check if a value is a promise. */\nexport const isPromiseLike = <T>(value: T | PromiseLike<T>): value is PromiseLike<T> => {\n return (\n !!value &&\n (typeof value === 'object' || typeof value === 'function') &&\n typeof (value as PromiseLike<T>).then === 'function'\n );\n};\n\n/** Waiting, bounded concurrency and fire-and-forget. `voidExecution` is not a `BaseHelper` member: TS cannot emit protected members on an exported ANONYMOUS class (TS4094), which is what factory-built controllers return; a static on a separate class has no such limit. */\nexport class PromiseUtility {\n /** The longest delay a timer takes (a signed 32-bit integer of milliseconds); a larger one fires after 1 ms. */\n private static readonly MAX_TIMER_MS = 2_147_483_647;\n\n static sleep(opts: { ms: number }): Promise<void> {\n return new Promise((resolve) => setTimeout(resolve, opts.ms));\n }\n\n /**\n * Runs `call` and resolves with its result, or rejects with an `ApplicationError` when `timeoutMs` passes first\n * (`message` is the error text; the default names the limit). The timer is cleared on every path - the call wins,\n * the timeout wins, the call throws - so none is left behind. The call's own rejection passes through unchanged.\n * The losing call keeps running: a promise cannot be cancelled. The timeout error carries status 504 (Gateway\n * Timeout). `timeoutMs` must be a positive number no larger than `2_147_483_647` (the most a timer takes: a larger\n * one fires at once), else this rejects without running `call`.\n */\n static async withTimeout<T>(opts: {\n call: () => ValueOrPromise<T>;\n timeoutMs: number;\n message?: string;\n }): Promise<T> {\n const { call, timeoutMs, message } = opts;\n\n if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > PromiseUtility.MAX_TIMER_MS) {\n throw getError({\n message: `[withTimeout] timeoutMs must be positive and at most ${PromiseUtility.MAX_TIMER_MS} | received: ${timeoutMs}`,\n });\n }\n\n let timer: ReturnType<typeof setTimeout> | undefined;\n const timeout = new Promise<never>((_resolve, reject) => {\n timer = setTimeout(() => {\n reject(\n getError({\n statusCode: HTTP.ResultCodes.RS_5.GatewayTimeout,\n message: message ?? `[withTimeout] Timed out after ${timeoutMs}ms`,\n }),\n );\n }, timeoutMs);\n });\n\n try {\n const result = await Promise.race([new Promise<T>((resolve) => resolve(call())), timeout]);\n\n return result;\n } finally {\n clearTimeout(timer);\n }\n }\n\n /** Execute async tasks with bounded concurrency. */\n static async executeWithLimit<T>(opts: {\n tasks: Array<TTask<T>>;\n limit: number;\n onTaskDone?: <R>(opts: { result: R }) => ValueOrPromise<void>;\n }) {\n const { tasks, limit, onTaskDone } = opts;\n\n if (!Number.isInteger(limit) || limit < 1) {\n throw getError({\n message: `[executePromiseWithLimit] limit must be a positive integer | received: ${limit}`,\n });\n }\n\n const results: Promise<T>[] = [];\n const executing = new Set();\n\n for (const task of tasks) {\n const promise = task().then((result) => {\n executing.delete(promise);\n\n return result;\n });\n\n executing.add(promise);\n results.push(promise);\n\n if (executing.size >= limit) {\n const done = await Promise.race(executing);\n await onTaskDone?.({ result: done });\n }\n }\n\n await Promise.all(executing);\n\n return Promise.all(results);\n }\n\n /** Fire-and-forget: routes rejection to `logger` (or console.error), passes sync results through untouched. */\n static voidExecution(opts: {\n logger?: ILogger;\n scope: string;\n execution: ValueOrPromise<unknown>;\n }): void {\n const { logger, scope, execution } = opts;\n\n if (!isPromiseLike(execution)) {\n return;\n }\n\n Promise.resolve(execution).catch((error: unknown) => {\n if (logger) {\n logger.for(scope).error('Unhandled error in fire-and-forget execution | Error: %s', error);\n\n return;\n }\n\n console.error('[%s] Unhandled error in fire-and-forget execution', scope, error);\n });\n }\n}\n"]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/ignis-helpers",
3
- "version": "0.4.8-13",
3
+ "version": "0.4.8-14",
4
4
  "description": "Production-ready TypeScript utility library: pluggable logging (winston or pino behind one ILogger contract), Redis single/cluster/sentinel with pub/sub, BullMQ/MQTT/Kafka message queues, MinIO/Disk/Bun-S3 object storage, AES-256/RSA/ECDH cryptography, Snowflake UID generation, cron scheduling, Socket.IO/WebSocket, TCP/TLS/UDP networking, HTTP clients, secrets/Vault, worker thread pools, and environment management. Sub-path imports isolate optional peer dependencies so the root barrel never forces a peer into your bundle.",
5
5
  "keywords": [
6
6
  "aes",
@@ -176,7 +176,7 @@
176
176
  "force-update": "sh ../../scripts/build/force-update.sh"
177
177
  },
178
178
  "dependencies": {
179
- "@venizia/ignis-inversion": "0.4.7-4",
179
+ "@venizia/ignis-inversion": "0.4.7-5",
180
180
  "reflect-metadata": "^0.2.2",
181
181
  "zod": "^4.6.7"
182
182
  },
@@ -188,7 +188,7 @@
188
188
  "@socket.io/redis-emitter": "^5.1.0",
189
189
  "@types/bun": "^1.4.3",
190
190
  "@types/luxon": "^3.7.6",
191
- "@venizia/dev-configs": "0.4.8-9",
191
+ "@venizia/dev-configs": "0.4.8-10",
192
192
  "axios": "^1.20.0",
193
193
  "bullmq": "^6.4.0",
194
194
  "cron": "^4.4.0",