navi-hey 1.1.0 → 1.2.1

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 (109) hide show
  1. package/README.md +38 -4
  2. package/lib/common/utils/EnvResolver.js +26 -0
  3. package/lib/common/utils/env_resolver/EnvStringResolver.js +52 -0
  4. package/lib/common/utils/logging/BaseLogger.js +98 -0
  5. package/lib/common/utils/logging/BufferedLogger.js +100 -0
  6. package/lib/common/utils/logging/ConsoleLogger.js +20 -0
  7. package/lib/common/utils/logging/Log.js +82 -0
  8. package/lib/common/utils/logging/LogBuffer.js +122 -0
  9. package/lib/common/utils/logging/LogBufferCollection.js +56 -0
  10. package/lib/common/utils/logging/LogContext.js +51 -0
  11. package/lib/common/utils/logging/LogFactory.js +33 -0
  12. package/lib/common/utils/logging/LogFilter.js +34 -0
  13. package/lib/common/utils/logging/Logger.js +138 -0
  14. package/lib/common/utils/logging/LoggerGroup.js +104 -0
  15. package/lib/enqueuers/ActionEnqueuer.js +18 -2
  16. package/lib/enqueuers/ActionsEnqueuer.js +6 -3
  17. package/lib/enqueuers/PaginatedActionEnqueuer.js +53 -0
  18. package/lib/enqueuers/PaginatedActionsEnqueuer.js +47 -0
  19. package/lib/exceptions/{ConfigurationFileNotFound.js → config/ConfigurationFileNotFound.js} +1 -1
  20. package/lib/exceptions/{ConfigurationFileNotProvided.js → config/ConfigurationFileNotProvided.js} +1 -1
  21. package/lib/exceptions/{MissingTopLevelConfgKey.js → config/MissingTopLevelConfgKey.js} +1 -1
  22. package/lib/exceptions/{ConflictError.js → http/ConflictError.js} +1 -1
  23. package/lib/exceptions/{ForbiddenError.js → http/ForbiddenError.js} +1 -1
  24. package/lib/exceptions/{NotFoundError.js → http/NotFoundError.js} +1 -1
  25. package/lib/exceptions/{ItemNotFound.js → registry/ItemNotFound.js} +1 -1
  26. package/lib/exceptions/{MissingActionResource.js → registry/MissingActionResource.js} +1 -1
  27. package/lib/exceptions/{MissingMappingVariable.js → registry/MissingMappingVariable.js} +1 -1
  28. package/lib/exceptions/{InvalidHtmlResponseBody.js → request/InvalidHtmlResponseBody.js} +1 -1
  29. package/lib/exceptions/{InvalidResponseBody.js → request/InvalidResponseBody.js} +1 -1
  30. package/lib/exceptions/{NullResponse.js → request/NullResponse.js} +1 -1
  31. package/lib/exceptions/{RequestFailed.js → request/RequestFailed.js} +1 -1
  32. package/lib/jobs/ActionProcessingJob.js +17 -3
  33. package/lib/jobs/HtmlParseJob.js +17 -4
  34. package/lib/jobs/PaginatedActionProcessingJob.js +77 -0
  35. package/lib/jobs/ResourceRequestJob.js +8 -5
  36. package/lib/models/{Config.js → configs/Config.js} +3 -3
  37. package/lib/models/configs/Link.js +36 -0
  38. package/lib/models/configs/PaginationConfig.js +63 -0
  39. package/lib/models/{WebConfig.js → configs/WebConfig.js} +5 -1
  40. package/lib/models/{ResourceRequest.js → request/ResourceRequest.js} +30 -8
  41. package/lib/models/{ResourceRequestAction.js → request/ResourceRequestAction.js} +6 -6
  42. package/lib/models/request/ResourceRequestPaginatedAction.js +81 -0
  43. package/lib/models/{PathSegmentTraverser.js → response/PathSegmentTraverser.js} +1 -1
  44. package/lib/models/{ResponseParser.js → response/ResponseParser.js} +1 -1
  45. package/lib/registry/ClientRegistry.js +1 -1
  46. package/lib/registry/LogRegistry.js +13 -13
  47. package/lib/registry/LogRegistryInstance.js +16 -16
  48. package/lib/registry/NamedRegistry.js +1 -1
  49. package/lib/registry/ResourceRegistry.js +1 -1
  50. package/lib/serializers/JobIndexSerializer.js +3 -0
  51. package/lib/serializers/LogSerializer.js +1 -1
  52. package/lib/server/PathValidator.js +1 -1
  53. package/lib/server/RouteRegister.js +3 -3
  54. package/lib/server/Router.js +20 -18
  55. package/lib/server/{AssetsRequestHandler.js → handlers/AssetsRequestHandler.js} +3 -3
  56. package/lib/server/{BaseUrlsRequestHandler.js → handlers/BaseUrlsRequestHandler.js} +3 -3
  57. package/lib/server/{IndexRequestHandler.js → handlers/IndexRequestHandler.js} +2 -2
  58. package/lib/server/{JobsFilter.js → handlers/JobsFilter.js} +1 -1
  59. package/lib/server/handlers/LinksRequestHandler.js +32 -0
  60. package/lib/server/{LogsRequestHandler.js → handlers/LogsRequestHandler.js} +4 -4
  61. package/lib/server/{SettingsRequestHandler.js → handlers/SettingsRequestHandler.js} +4 -3
  62. package/lib/server/{StatsRequestHandler.js → handlers/StatsRequestHandler.js} +3 -3
  63. package/lib/server/{EngineContinueRequestHandler.js → handlers/engine/EngineContinueRequestHandler.js} +3 -3
  64. package/lib/server/{EnginePauseRequestHandler.js → handlers/engine/EnginePauseRequestHandler.js} +3 -3
  65. package/lib/server/{EngineRestartRequestHandler.js → handlers/engine/EngineRestartRequestHandler.js} +3 -3
  66. package/lib/server/{EngineShutdownRequestHandler.js → handlers/engine/EngineShutdownRequestHandler.js} +2 -2
  67. package/lib/server/{EngineStartRequestHandler.js → handlers/engine/EngineStartRequestHandler.js} +3 -3
  68. package/lib/server/{EngineStatusRequestHandler.js → handlers/engine/EngineStatusRequestHandler.js} +2 -2
  69. package/lib/server/{EngineStopRequestHandler.js → handlers/engine/EngineStopRequestHandler.js} +3 -3
  70. package/lib/server/{JobLogsRequestHandler.js → handlers/jobs/JobLogsRequestHandler.js} +4 -4
  71. package/lib/server/{JobRequestHandler.js → handlers/jobs/JobRequestHandler.js} +4 -4
  72. package/lib/server/{JobRetryRequestHandler.js → handlers/jobs/JobRetryRequestHandler.js} +4 -4
  73. package/lib/server/{JobsRequestHandler.js → handlers/jobs/JobsRequestHandler.js} +4 -4
  74. package/lib/services/ApplicationInstance.js +4 -2
  75. package/lib/services/Client.js +1 -1
  76. package/lib/services/ConfigLoader.js +4 -4
  77. package/lib/services/ConfigParser.js +7 -7
  78. package/lib/services/Engine.js +1 -1
  79. package/lib/utils/HtmlParser.js +1 -1
  80. package/lib/utils/logging/BaseLogger.js +1 -98
  81. package/lib/utils/logging/BufferedLogger.js +1 -100
  82. package/lib/utils/logging/ConsoleLogger.js +1 -20
  83. package/lib/utils/logging/Log.js +1 -82
  84. package/lib/utils/logging/LogBuffer.js +1 -122
  85. package/lib/utils/logging/LogBufferCollection.js +1 -56
  86. package/lib/utils/logging/LogContext.js +1 -51
  87. package/lib/utils/logging/LogFactory.js +1 -33
  88. package/lib/utils/logging/LogFilter.js +1 -34
  89. package/lib/utils/logging/Logger.js +1 -138
  90. package/lib/utils/logging/LoggerGroup.js +1 -104
  91. package/package.json +1 -1
  92. package/static/assets/index-CX_uXu4Q.js +11 -0
  93. package/static/favicon.png +0 -0
  94. package/static/index.html +2 -1
  95. package/lib/exceptions/LockedByOtherWorker.js +0 -14
  96. package/lib/utils/EnvResolver.js +0 -75
  97. package/static/assets/index-BfggoMvd.js +0 -11
  98. /package/lib/exceptions/{MissingClientsConfig.js → config/MissingClientsConfig.js} +0 -0
  99. /package/lib/exceptions/{MissingResourceConfig.js → config/MissingResourceConfig.js} +0 -0
  100. /package/lib/exceptions/{ClientNotFound.js → registry/ClientNotFound.js} +0 -0
  101. /package/lib/exceptions/{ResourceNotFound.js → registry/ResourceNotFound.js} +0 -0
  102. /package/lib/models/{FailureConfig.js → configs/FailureConfig.js} +0 -0
  103. /package/lib/models/{LogConfig.js → configs/LogConfig.js} +0 -0
  104. /package/lib/models/{WorkersConfig.js → configs/WorkersConfig.js} +0 -0
  105. /package/lib/models/{AssetRequest.js → request/AssetRequest.js} +0 -0
  106. /package/lib/models/{Resource.js → request/Resource.js} +0 -0
  107. /package/lib/models/{ParametersMapper.js → response/ParametersMapper.js} +0 -0
  108. /package/lib/models/{PathResolver.js → response/PathResolver.js} +0 -0
  109. /package/lib/models/{ResponseWrapper.js → response/ResponseWrapper.js} +0 -0
package/README.md CHANGED
@@ -16,6 +16,7 @@ Key features:
16
16
  - Concurrent HTTP request execution via a worker pool.
17
17
  - URL templates with placeholder parameters (e.g. `{:id}`).
18
18
  - Response-driven actions: after each successful request, configurable actions extract variables from the response and trigger follow-up processing.
19
+ - Paginated resource support: `paginated_actions` fan out one request per page based on a page-count expression evaluated against the response.
19
20
  - Automatic retry of failed requests after the main queue is exhausted.
20
21
 
21
22
  ---
@@ -92,8 +93,13 @@ resources:
92
93
  - resource: category_information
93
94
  - resource: products
94
95
  parameters:
95
- category_id: parsed_body.id
96
- page: headers['x-next-page']
96
+ category_id: parsedBody.id
97
+ paginated_actions:
98
+ - resource: products_page
99
+ pagination:
100
+ - pages: parsedBody.pagination.pages
101
+ - page_key: page
102
+ - zero_indexed: false
97
103
  - url: /categories
98
104
  status: 302
99
105
  - url: /#/categories
@@ -134,7 +140,13 @@ When the web server is enabled, the following screens are available:
134
140
  | `client` | Name of the client to use for this request. Defaults to `default`. |
135
141
  | `actions` | Optional list of actions to execute after a successful response. |
136
142
  | `actions[].resource` | Name of the resource to act upon. Required. |
137
- | `actions[].parameters` | Optional key-value map. Each key is the destination variable name and each value is a path expression resolved against the response (e.g. `parsed_body.id`, `headers['page']`). When absent, the parsed body item is passed through unchanged. |
143
+ | `actions[].parameters` | Optional key-value map. Each key is the destination variable name and each value is a path expression resolved against the response (e.g. `parsedBody.id`, `headers['page']`). When absent, the parsed body item is passed through unchanged. |
144
+ | `paginated_actions` | Optional list of paginated actions. Each entry fans out one `ResourceRequestJob` per page. |
145
+ | `paginated_actions[].resource` | Name of the resource to enqueue per page. Required. |
146
+ | `paginated_actions[].pagination` | List of pagination config entries. Required. |
147
+ | `paginated_actions[].pagination[].pages` | Path expression (e.g. `parsedBody.pagination.pages`) resolving to the total page count. |
148
+ | `paginated_actions[].pagination[].page_key` | Parameter name injected as the current page number into each downstream request. |
149
+ | `paginated_actions[].pagination[].zero_indexed` | Boolean. Pages start at `0` when `true`, at `1` when `false` (default). |
138
150
  | `assets` | Optional list of asset extraction rules. When present on an HTML resource, Navi parses the response body and enqueues a download job for each matched URL. |
139
151
  | `assets[].selector` | CSS selector used to find asset elements in the HTML response (e.g. `script[src]`, `link[rel="stylesheet"]`). |
140
152
  | `assets[].attribute` | Attribute on the matched element that holds the asset URL (e.g. `src`, `href`). |
@@ -147,7 +159,29 @@ When the web server is enabled, the following screens are available:
147
159
 
148
160
  Navi supports multi-level resource chaining. After a successful response, each configured action uses `parameters` path expressions to extract variables from the response body or headers and enqueues new jobs for the target resource. The extracted variables resolve `{:placeholder}` tokens in the target URL templates.
149
161
 
150
- For example, requesting `/categories.json` might return `[{ "id": 1 }, { "id": 2 }]`. With an action targeting `category_information` and `parameters: { id: parsed_body.id }`, Navi automatically enqueues requests for `/categories/1.json` and `/categories/2.json`.
162
+ For example, requesting `/categories.json` might return `[{ "id": 1 }, { "id": 2 }]`. With an action targeting `category_information` and `parameters: { id: parsedBody.id }`, Navi automatically enqueues requests for `/categories/1.json` and `/categories/2.json`. Header values can also be extracted, e.g. `page: headers['x-next-page']`.
163
+
164
+ > **Note:** HTTP response header names are always lowercase after Node.js normalization. Use lowercase keys in path expressions (e.g. `headers['x-total-pages']`), regardless of how the server set them.
165
+
166
+ ## Paginated Actions
167
+
168
+ `paginated_actions` complement `actions` when the response indicates multiple pages. Instead of iterating over array items, Navi evaluates a `pages` expression against the whole response, then enqueues one `ResourceRequestJob` per page, injecting the page number under the configured `page_key`.
169
+
170
+ ```yaml
171
+ resources:
172
+ categories:
173
+ - url: /categories.json
174
+ status: 200
175
+ paginated_actions:
176
+ - resource: products_page
177
+ pagination:
178
+ - pages: parsedBody.pagination.pages
179
+ - page_key: page
180
+ - zero_indexed: false
181
+ products_page:
182
+ - url: /products/{:page}.json
183
+ status: 200
184
+ ```
151
185
 
152
186
  ---
153
187
 
@@ -0,0 +1,26 @@
1
+ import { EnvStringResolver } from './env_resolver/EnvStringResolver.js';
2
+
3
+ /**
4
+ * Resolves environment variable references in string values.
5
+ *
6
+ * Supports `$VAR_NAME` and `${VAR_NAME}` syntax, resolved from
7
+ * `process.env` at call time. Logs a warning when a referenced
8
+ * variable is not defined and replaces it with an empty string.
9
+ *
10
+ * @author darthjee
11
+ */
12
+ class EnvResolver {
13
+ /**
14
+ * Resolves environment variable references in all values of an object.
15
+ *
16
+ * @param {object} object Map of keys to raw string values.
17
+ * @returns {object} A new object with env var references resolved in values.
18
+ */
19
+ static resolveObject(object) {
20
+ return Object.fromEntries(
21
+ Object.entries(object).map(([key, value]) => [key, EnvStringResolver.resolve(value)])
22
+ );
23
+ }
24
+ }
25
+
26
+ export { EnvResolver };
@@ -0,0 +1,52 @@
1
+ import { Logger } from '../logging/Logger.js';
2
+
3
+ /**
4
+ * Pattern matching environment variable references in strings.
5
+ * Supports `$VAR_NAME` and `${VAR_NAME}` syntax.
6
+ * @type {RegExp}
7
+ */
8
+ const ENV_VAR_PATTERN = /\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
9
+
10
+ class EnvStringResolver {
11
+ /**
12
+ * @param {string} string Raw string content.
13
+ */
14
+ constructor(string) {
15
+ this.string = string;
16
+ }
17
+
18
+ /**
19
+ * Resolves environment variable references in a raw string (e.g. YAML file content).
20
+ *
21
+ * Replaces all `$VAR` and `${VAR}` occurrences with their environment values.
22
+ *
23
+ * @param {string} string Raw string content.
24
+ * @returns {string} Resolved string with env var references replaced.
25
+ */
26
+ static resolve(string) {
27
+ return new EnvStringResolver(string).resolve();
28
+ }
29
+
30
+ /**
31
+ * Resolves environment variable references in a raw string (e.g. YAML file content).
32
+ *
33
+ * Replaces all `$VAR` and `${VAR}` occurrences with their environment values.
34
+ *
35
+ * @returns {string} Resolved string with env var references replaced.
36
+ */
37
+ resolve() {
38
+ return String(this.string).replace(ENV_VAR_PATTERN, (_match, braced, bare) => {
39
+ const varName = braced || bare;
40
+ const resolved = process.env[varName];
41
+
42
+ if (resolved === undefined) {
43
+ Logger.warn(`Environment variable not defined: ${varName}`);
44
+ return '';
45
+ }
46
+
47
+ return resolved;
48
+ });
49
+ }
50
+ }
51
+
52
+ export { EnvStringResolver };
@@ -0,0 +1,98 @@
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
+ * @param {object} _attributes - The structured metadata for the log entry.
24
+ * @returns {void}
25
+ */
26
+ _output(_level, _message, _attributes) {}
27
+
28
+ /**
29
+ * Logs a debug message if the configured level allows it.
30
+ * @param {string} message - The message to log.
31
+ * @param {object} [attributes={}] - Optional structured metadata.
32
+ * @returns {void}
33
+ */
34
+ debug(message, attributes = {}) {
35
+ if (this.#shouldLog('debug')) this._output('debug', message, attributes);
36
+ }
37
+
38
+ /**
39
+ * Logs an info message if the configured level allows it.
40
+ * @param {string} message - The message to log.
41
+ * @param {object} [attributes={}] - Optional structured metadata.
42
+ * @returns {void}
43
+ */
44
+ info(message, attributes = {}) {
45
+ if (this.#shouldLog('info')) this._output('info', message, attributes);
46
+ }
47
+
48
+ /**
49
+ * Logs a warn message if the configured level allows it.
50
+ * @param {string} message - The message to log.
51
+ * @param {object} [attributes={}] - Optional structured metadata.
52
+ * @returns {void}
53
+ */
54
+ warn(message, attributes = {}) {
55
+ if (this.#shouldLog('warn')) this._output('warn', message, attributes);
56
+ }
57
+
58
+ /**
59
+ * Logs an error message if the configured level allows it.
60
+ * @param {string} message - The message to log.
61
+ * @param {object} [attributes={}] - Optional structured metadata.
62
+ * @returns {void}
63
+ */
64
+ error(message, attributes = {}) {
65
+ if (this.#shouldLog('error')) this._output('error', message, attributes);
66
+ }
67
+
68
+ /**
69
+ * Suppresses or restores log output for this instance.
70
+ * @param {boolean} [value=true] - When true, all log output is suppressed.
71
+ * @returns {void}
72
+ */
73
+ suppress(value = true) {
74
+ this.#suppressed = value;
75
+ }
76
+
77
+ /**
78
+ * Sets the log level threshold for this instance.
79
+ * @param {string} level - The new log level ('debug', 'info', 'warn', 'error', 'silent').
80
+ * @returns {void}
81
+ */
82
+ setLevel(level) {
83
+ if (!(level in this.#levels)) {
84
+ throw new Error(`Invalid log level: "${level}". Must be one of: ${Object.keys(this.#levels).join(', ')}.`);
85
+ }
86
+ this.#level = level;
87
+ }
88
+
89
+ /**
90
+ * @param {string} level - The log level to check.
91
+ * @returns {boolean} True if the message should be logged at the given level.
92
+ */
93
+ #shouldLog(level) {
94
+ return !this.#suppressed && this.#levels[level] >= this.#levels[this.#level];
95
+ }
96
+ }
97
+
98
+ export { BaseLogger };
@@ -0,0 +1,100 @@
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
+ * @param {object} [attributes={}] - Optional structured metadata for the log entry.
27
+ * @returns {void}
28
+ */
29
+ _output(level, message, attributes = {}) {
30
+ this.#buffer.add(level, message, attributes);
31
+ }
32
+
33
+ /**
34
+ * Returns the most recently added log, or undefined if the buffer is empty.
35
+ * @returns {import('./Log.js').Log|undefined} The most recently added log entry, or undefined.
36
+ */
37
+ get latestLog() {
38
+ return this.#buffer.latestLog;
39
+ }
40
+
41
+ /**
42
+ * Gets all logs from the buffer.
43
+ * @returns {Array<import('./Log.js').Log>} Array of log entries.
44
+ */
45
+ getLogs() {
46
+ return this.#buffer.getLogs();
47
+ }
48
+
49
+ /**
50
+ * Gets a specific log by ID.
51
+ * @param {number} id - The log ID to find.
52
+ * @returns {import('./Log.js').Log|undefined} The log entry or undefined if not found.
53
+ */
54
+ getLogById(id) {
55
+ return this.#buffer.getLogById(id);
56
+ }
57
+
58
+ /**
59
+ * Gets logs filtered by level.
60
+ * @param {string} level - The log level to filter by.
61
+ * @returns {Array<import('./Log.js').Log>} Array of log entries matching the level.
62
+ */
63
+ getLogsByLevel(level) {
64
+ return this.#buffer.getLogsByLevel(level);
65
+ }
66
+
67
+ /**
68
+ * Clears all logs from the buffer.
69
+ * @returns {void}
70
+ */
71
+ clearLogs() {
72
+ this.#buffer.clear();
73
+ }
74
+
75
+ /**
76
+ * Gets the current number of logs in the buffer.
77
+ * @returns {number} The number of logs.
78
+ */
79
+ get bufferSize() {
80
+ return this.#buffer.size;
81
+ }
82
+
83
+ /**
84
+ * Gets the retention limit.
85
+ * @returns {number} The maximum number of logs to retain.
86
+ */
87
+ get retention() {
88
+ return this.#buffer.retention;
89
+ }
90
+
91
+ /**
92
+ * Converts all logs to JSON array.
93
+ * @returns {Array<object>} Array of log objects.
94
+ */
95
+ getLogsJSON() {
96
+ return this.#buffer.toJSON();
97
+ }
98
+ }
99
+
100
+ export { BufferedLogger };
@@ -0,0 +1,20 @@
1
+ import { BaseLogger } from './BaseLogger.js';
2
+
3
+ /**
4
+ * Logger that writes output to the browser/Node.js console.
5
+ * @author darthjee
6
+ */
7
+ class ConsoleLogger extends BaseLogger {
8
+ /**
9
+ * Writes a message to the console at the given level.
10
+ * @param {string} level - One of 'debug', 'info', 'warn', 'error'.
11
+ * @param {string} message - The message to output.
12
+ * @param {object} [attributes={}] - Optional structured metadata to output alongside the message.
13
+ * @returns {void}
14
+ */
15
+ _output(level, message, attributes = {}) {
16
+ console[level](message, attributes); // eslint-disable-line no-console
17
+ }
18
+ }
19
+
20
+ export { ConsoleLogger };
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Represents a single log entry with id, level, message, attributes and timestamp.
3
+ * @author darthjee
4
+ */
5
+ class Log {
6
+ #id;
7
+ #level;
8
+ #message;
9
+ #attributes;
10
+ #timestamp;
11
+
12
+ /**
13
+ * Creates a new Log instance.
14
+ * @param {number} id - Unique incremental identifier for this log.
15
+ * @param {string} level - The log level (debug, info, warn, error).
16
+ * @param {string} message - The log message.
17
+ * @param {object} [attributes={}] - Optional structured metadata for the log entry.
18
+ */
19
+ constructor(id, level, message, attributes = {}) {
20
+ this.#id = id;
21
+ this.#level = level;
22
+ this.#message = message;
23
+ this.#attributes = attributes;
24
+ this.#timestamp = new Date();
25
+ }
26
+
27
+ /**
28
+ * Gets the log ID.
29
+ * @returns {number} The log ID.
30
+ */
31
+ get id() {
32
+ return this.#id;
33
+ }
34
+
35
+ /**
36
+ * Gets the log level.
37
+ * @returns {string} The log level.
38
+ */
39
+ get level() {
40
+ return this.#level;
41
+ }
42
+
43
+ /**
44
+ * Gets the log message.
45
+ * @returns {string} The log message.
46
+ */
47
+ get message() {
48
+ return this.#message;
49
+ }
50
+
51
+ /**
52
+ * Gets the log attributes.
53
+ * @returns {object} The structured metadata attached to this log entry.
54
+ */
55
+ get attributes() {
56
+ return this.#attributes;
57
+ }
58
+
59
+ /**
60
+ * Gets the log timestamp.
61
+ * @returns {Date} The timestamp when the log was created.
62
+ */
63
+ get timestamp() {
64
+ return this.#timestamp;
65
+ }
66
+
67
+ /**
68
+ * Converts the log to a plain object.
69
+ * @returns {object} Plain object representation of the log.
70
+ */
71
+ toJSON() {
72
+ return {
73
+ id: this.#id,
74
+ level: this.#level,
75
+ message: this.#message,
76
+ attributes: this.#attributes,
77
+ timestamp: this.#timestamp.toISOString()
78
+ };
79
+ }
80
+ }
81
+
82
+ export { Log };
@@ -0,0 +1,122 @@
1
+ import { LogFactory } from './LogFactory.js';
2
+
3
+ /**
4
+ * LogBuffer manages a limited collection of log entries with automatic retention.
5
+ * When the retention limit is reached, the oldest logs are automatically discarded.
6
+ * @author darthjee
7
+ */
8
+ class LogBuffer {
9
+ #logs;
10
+ #retention;
11
+ #factory;
12
+
13
+ /**
14
+ * Creates a new LogBuffer instance.
15
+ * @param {number} [retention=100] - Maximum number of logs to retain.
16
+ */
17
+ constructor(retention = 100) {
18
+ this.#logs = [];
19
+ this.#retention = retention;
20
+ this.#factory = new LogFactory();
21
+ }
22
+
23
+ /**
24
+ * Adds a new log entry to the buffer.
25
+ * If retention limit is reached, removes the oldest log.
26
+ * @param {string} level - The log level.
27
+ * @param {string} message - The log message.
28
+ * @param {object} [attributes={}] - Optional structured metadata for the log entry.
29
+ * @returns {import('./Log.js').Log} The created log entry.
30
+ */
31
+ add(level, message, attributes = {}) {
32
+ const log = this.#factory.build(level, message, attributes);
33
+
34
+ this.#logs.unshift(log);
35
+
36
+ if (this.#logs.length > this.#retention) {
37
+ this.#logs.pop();
38
+ }
39
+
40
+ return log;
41
+ }
42
+
43
+ /**
44
+ * Gets all logs in the buffer.
45
+ * @returns {Array<Log>} Array of log entries.
46
+ */
47
+ getLogs() {
48
+ return [...this.#logs].reverse();
49
+ }
50
+
51
+ /**
52
+ * Gets a specific log by ID.
53
+ * @param {number} id - The log ID to find.
54
+ * @returns {Log|undefined} The log entry or undefined if not found.
55
+ */
56
+ getLogById(id) {
57
+ return this.#logs.find(log => log.id === id);
58
+ }
59
+
60
+ /**
61
+ * Gets logs filtered by level.
62
+ * @param {string} level - The log level to filter by.
63
+ * @returns {Array<Log>} Array of log entries matching the level.
64
+ */
65
+ getLogsByLevel(level) {
66
+ return this.#logs.filter(log => log.level === level).reverse();
67
+ }
68
+
69
+ /**
70
+ * Appends an existing Log instance to the buffer, respecting the retention limit.
71
+ * @param {import('./Log.js').Log} log - The Log instance to append.
72
+ * @returns {void}
73
+ */
74
+ push(log) {
75
+ this.#logs.unshift(log);
76
+ if (this.#logs.length > this.#retention) {
77
+ this.#logs.pop();
78
+ }
79
+ }
80
+
81
+ /**
82
+ * Returns the most recently added log, or undefined if the buffer is empty.
83
+ * @returns {import('./Log.js').Log|undefined} The most recently added log entry, or undefined.
84
+ */
85
+ get latestLog() {
86
+ return this.#logs[0];
87
+ }
88
+
89
+ /**
90
+ * Clears all logs from the buffer.
91
+ * @returns {void}
92
+ */
93
+ clear() {
94
+ this.#logs = [];
95
+ }
96
+
97
+ /**
98
+ * Gets the current number of logs in the buffer.
99
+ * @returns {number} The number of logs.
100
+ */
101
+ get size() {
102
+ return this.#logs.length;
103
+ }
104
+
105
+ /**
106
+ * Gets the retention limit.
107
+ * @returns {number} The maximum number of logs to retain.
108
+ */
109
+ get retention() {
110
+ return this.#retention;
111
+ }
112
+
113
+ /**
114
+ * Converts all logs to JSON array.
115
+ * @returns {Array<object>} Array of log objects.
116
+ */
117
+ toJSON() {
118
+ return [...this.#logs].reverse().map(log => log.toJSON());
119
+ }
120
+ }
121
+
122
+ export { LogBuffer };
@@ -0,0 +1,56 @@
1
+ import { LogBuffer } from './LogBuffer.js';
2
+ import { EngineEvents } from '../../../services/EngineEvents.js';
3
+
4
+ /**
5
+ * LogBufferCollection manages a keyed map of LogBuffer instances.
6
+ * Buffers are created on first use and cleared automatically when the engine stops.
7
+ * @author darthjee
8
+ */
9
+ class LogBufferCollection {
10
+ #buffers;
11
+ #retention;
12
+
13
+ /**
14
+ * @param {number} [retention=100] - Maximum number of logs to retain per buffer.
15
+ */
16
+ constructor(retention = 100) {
17
+ this.#buffers = new Map();
18
+ this.#retention = retention;
19
+ EngineEvents.on('stop', () => this.clear());
20
+ }
21
+
22
+ /**
23
+ * Appends an existing Log instance to the buffer for the given key.
24
+ * Lazily creates the buffer on first use.
25
+ * @param {string|number} key - The key identifying the buffer (e.g. jobId or workerId).
26
+ * @param {import('./Log.js').Log} log - The Log instance to append.
27
+ * @returns {void}
28
+ */
29
+ push(key, log) {
30
+ if (!this.#buffers.has(key)) {
31
+ this.#buffers.set(key, new LogBuffer(this.#retention));
32
+ }
33
+ this.#buffers.get(key).push(log);
34
+ }
35
+
36
+ /**
37
+ * Returns all logs for the given key in chronological order (oldest first).
38
+ * Returns an empty array if no buffer exists for that key.
39
+ * @param {string|number} key - The key to look up.
40
+ * @returns {Array<import('./Log.js').Log>} Array of log entries for the given key, oldest first.
41
+ */
42
+ getLogs(key) {
43
+ if (!this.#buffers.has(key)) return [];
44
+ return this.#buffers.get(key).getLogs();
45
+ }
46
+
47
+ /**
48
+ * Removes all per-key buffers.
49
+ * @returns {void}
50
+ */
51
+ clear() {
52
+ this.#buffers = new Map();
53
+ }
54
+ }
55
+
56
+ export { LogBufferCollection };
@@ -0,0 +1,51 @@
1
+ import { LogRegistry } from '../../../registry/LogRegistry.js';
2
+
3
+ /**
4
+ * LogContext wraps a fixed set of attributes and forwards log calls to LogRegistry
5
+ * with those attributes merged into every entry.
6
+ * @author darthjee
7
+ */
8
+ class LogContext {
9
+ #attributes;
10
+
11
+ /**
12
+ * @param {object} attributes Fixed attributes to include on every log entry (e.g. workerId, jobId).
13
+ */
14
+ constructor(attributes) {
15
+ this.#attributes = attributes;
16
+ }
17
+
18
+ /**
19
+ * @param {string} message The log message.
20
+ * @param {object} [attrs={}] Additional per-call attributes merged with context attributes.
21
+ */
22
+ debug(message, attrs = {}) {
23
+ LogRegistry.debug(message, { ...this.#attributes, ...attrs });
24
+ }
25
+
26
+ /**
27
+ * @param {string} message The log message.
28
+ * @param {object} [attrs={}] Additional per-call attributes merged with context attributes.
29
+ */
30
+ info(message, attrs = {}) {
31
+ LogRegistry.info(message, { ...this.#attributes, ...attrs });
32
+ }
33
+
34
+ /**
35
+ * @param {string} message The log message.
36
+ * @param {object} [attrs={}] Additional per-call attributes merged with context attributes.
37
+ */
38
+ warn(message, attrs = {}) {
39
+ LogRegistry.warn(message, { ...this.#attributes, ...attrs });
40
+ }
41
+
42
+ /**
43
+ * @param {string} message The log message.
44
+ * @param {object} [attrs={}] Additional per-call attributes merged with context attributes.
45
+ */
46
+ error(message, attrs = {}) {
47
+ LogRegistry.error(message, { ...this.#attributes, ...attrs });
48
+ }
49
+ }
50
+
51
+ export { LogContext };