navi-hey 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/bin/navi.js +3 -3
  2. package/lib/{factories → background}/JobFactory.js +2 -2
  3. package/lib/{registry → background}/JobRegistry.js +17 -0
  4. package/lib/{registry → background}/JobRegistryInstance.js +42 -1
  5. package/lib/{models → background}/Worker.js +5 -3
  6. package/lib/{factories → background}/WorkerFactory.js +2 -2
  7. package/lib/{registry → background}/WorkersRegistryInstance.js +1 -1
  8. package/lib/{models → enqueuers}/ActionEnqueuer.js +4 -1
  9. package/lib/{models → enqueuers}/AssetRequestEnqueuer.js +6 -2
  10. package/lib/exceptions/ConflictError.js +14 -0
  11. package/lib/{models → jobs}/ActionProcessingJob.js +4 -4
  12. package/lib/{models → jobs}/AssetDownloadJob.js +6 -6
  13. package/lib/{models → jobs}/HtmlParseJob.js +6 -6
  14. package/lib/{models → jobs}/ResourceRequestJob.js +11 -11
  15. package/lib/models/ResourceRequest.js +5 -2
  16. package/lib/models/ResourceRequestAction.js +6 -3
  17. package/lib/models/WebConfig.js +5 -1
  18. package/lib/registry/LogRegistry.js +146 -0
  19. package/lib/registry/LogRegistryInstance.js +156 -0
  20. package/lib/serializers/JobIndexSerializer.js +10 -3
  21. package/lib/serializers/LogSerializer.js +26 -0
  22. package/lib/server/EngineContinueRequestHandler.js +34 -0
  23. package/lib/server/EnginePauseRequestHandler.js +34 -0
  24. package/lib/server/EngineRestartRequestHandler.js +34 -0
  25. package/lib/server/EngineShutdownRequestHandler.js +29 -0
  26. package/lib/server/EngineStartRequestHandler.js +34 -0
  27. package/lib/server/EngineStatusRequestHandler.js +27 -0
  28. package/lib/server/EngineStopRequestHandler.js +34 -0
  29. package/lib/server/JobLogsRequestHandler.js +39 -0
  30. package/lib/server/JobRequestHandler.js +1 -1
  31. package/lib/server/JobRetryRequestHandler.js +40 -0
  32. package/lib/server/JobsFilter.js +55 -0
  33. package/lib/server/JobsRequestHandler.js +5 -2
  34. package/lib/server/LogsRequestHandler.js +55 -0
  35. package/lib/server/RouteRegister.js +40 -7
  36. package/lib/server/Router.js +43 -25
  37. package/lib/server/SettingsRequestHandler.js +34 -0
  38. package/lib/server/StatsRequestHandler.js +2 -2
  39. package/lib/server/WebServer.js +28 -8
  40. package/lib/services/Application.js +138 -84
  41. package/lib/services/ApplicationInstance.js +272 -0
  42. package/lib/services/Client.js +22 -18
  43. package/lib/services/Engine.js +51 -6
  44. package/lib/services/EngineEvents.js +42 -0
  45. package/lib/services/FailureChecker.js +4 -4
  46. package/lib/services/WorkersAllocator.js +2 -2
  47. package/lib/utils/HtmlElementParser.js +5 -4
  48. package/lib/utils/HtmlParser.js +4 -4
  49. package/lib/utils/PromiseAggregator.js +11 -5
  50. package/lib/utils/logging/BufferedLogger.js +8 -0
  51. package/lib/utils/logging/LogBuffer.js +25 -5
  52. package/lib/utils/logging/LogBufferCollection.js +56 -0
  53. package/lib/utils/logging/LogContext.js +51 -0
  54. package/lib/utils/logging/LogFilter.js +34 -0
  55. package/package.json +1 -1
  56. package/static/assets/index-BfggoMvd.js +11 -0
  57. package/static/assets/{index-DBkz-poX.css → index-CuWjW0sT.css} +1 -1
  58. package/static/index.html +2 -2
  59. /package/lib/{models → background}/Job.js +0 -0
  60. /package/lib/{registry → background}/WorkersRegistry.js +0 -0
  61. /package/lib/{models → enqueuers}/ActionsEnqueuer.js +0 -0
  62. /package/lib/{factories → factory}/Factory.js +0 -0
package/bin/navi.js CHANGED
@@ -4,6 +4,6 @@ import { Application } from '../lib/services/Application.js';
4
4
  import { ArgumentsParser } from '../lib/services/ArgumentsParser.js';
5
5
 
6
6
  const { config } = ArgumentsParser.parse(process.argv.slice(2));
7
- const app = new Application();
8
- app.loadConfig(config);
9
- app.run();
7
+ Application.build();
8
+ Application.loadConfig(config);
9
+ Application.run();
@@ -1,5 +1,5 @@
1
- import { Factory } from './Factory.js';
2
- import { ResourceRequestJob } from '../models/ResourceRequestJob.js';
1
+ import { Factory } from '../factory/Factory.js';
2
+ import { ResourceRequestJob } from '../jobs/ResourceRequestJob.js';
3
3
  import { IdGenerator } from '../utils/generators/IdGenerator.js';
4
4
 
5
5
  /**
@@ -32,6 +32,14 @@ class JobRegistry {
32
32
  JobRegistry.#instance = null;
33
33
  }
34
34
 
35
+ /**
36
+ * Clears all pending queues (enqueued, retryQueue, and failed).
37
+ * @returns {void}
38
+ */
39
+ static clearQueues() {
40
+ return JobRegistry.#getInstance().clearQueues();
41
+ }
42
+
35
43
  /**
36
44
  * Enqueues a new job using the factory registered under the given key.
37
45
  * @param {string} factoryKey - The factory key to use.
@@ -77,6 +85,15 @@ class JobRegistry {
77
85
  return JobRegistry.#getInstance().requeue(job);
78
86
  }
79
87
 
88
+ /**
89
+ * Moves a job directly to the retry queue, removing it from the failed or dead collection.
90
+ * @param {string} id - The ID of the job to retry.
91
+ * @returns {Job|null} The job if found and moved, or null if not in a retryable state.
92
+ */
93
+ static retryJob(id) {
94
+ return JobRegistry.#getInstance().retryJob(id);
95
+ }
96
+
80
97
  /**
81
98
  * Promotes cooling-down failed jobs that are ready to retry.
82
99
  * @returns {void}
@@ -1,4 +1,4 @@
1
- import { JobFactory } from '../factories/JobFactory.js';
1
+ import { JobFactory } from './JobFactory.js';
2
2
  import { IdentifyableCollection } from '../utils/collections/IdentifyableCollection.js';
3
3
  import { Queue } from '../utils/collections/Queue.js';
4
4
  import { SortedCollection } from '../utils/collections/SortedCollection.js';
@@ -104,6 +104,34 @@ class JobRegistryInstance {
104
104
  this.#enqueued.push(job);
105
105
  }
106
106
 
107
+ /**
108
+ * Moves a job directly to the retry queue, removing it from the failed or dead collection.
109
+ * Returns the job if found and moved, or null if the job is not in a retryable state.
110
+ * @param {string} id - The ID of the job to retry.
111
+ * @returns {Job|null} The job instance, or null if not found in failed or dead.
112
+ */
113
+ retryJob(id) {
114
+ const allFailed = this.#failed.list();
115
+ const failedJob = allFailed.find(j => j.id === id);
116
+ if (failedJob) {
117
+ this.#failed = new SortedCollection(
118
+ allFailed.filter(j => j.id !== id),
119
+ { sortBy: FAILED_SORT_BY }
120
+ );
121
+ this.#retryQueue.push(failedJob);
122
+ return failedJob;
123
+ }
124
+
125
+ const deadJob = this.#dead.get(id);
126
+ if (deadJob) {
127
+ this.#dead.remove(id);
128
+ this.#retryQueue.push(deadJob);
129
+ return deadJob;
130
+ }
131
+
132
+ return null;
133
+ }
134
+
107
135
  /**
108
136
  * Promotes jobs from the failed queue to the retryQueue once their cooldown has elapsed.
109
137
  * @returns {void}
@@ -117,6 +145,19 @@ class JobRegistryInstance {
117
145
  ready.forEach(job => this.#retryQueue.push(job));
118
146
  }
119
147
 
148
+ /**
149
+ * Clears all queues (enqueued, retryQueue, failed, finished, and dead), leaving
150
+ * only the processing collection intact.
151
+ * @returns {void}
152
+ */
153
+ clearQueues() {
154
+ this.#enqueued = new Queue();
155
+ this.#retryQueue = new Queue();
156
+ this.#failed = new SortedCollection([], { sortBy: FAILED_SORT_BY });
157
+ this.#finished = new IdentifyableCollection();
158
+ this.#dead = new IdentifyableCollection();
159
+ }
160
+
120
161
  /**
121
162
  * Returns whether the registry has any jobs pending (including those in cooldown).
122
163
  * @returns {boolean} True if any of enqueued, failed, or retryQueue is non-empty.
@@ -1,4 +1,4 @@
1
- import { Logger } from '../utils/logging/Logger.js';
1
+ import { LogContext } from '../utils/logging/LogContext.js';
2
2
 
3
3
  /**
4
4
  * Worker processes jobs pulled from a JobRegistry.
@@ -41,11 +41,13 @@ class Worker {
41
41
  throw new Error('No job assigned to worker');
42
42
  }
43
43
 
44
+ const logContext = new LogContext({ workerId: this.id, jobId: this.job.id });
45
+
44
46
  try {
45
- await this.job.perform();
47
+ await this.job.perform(logContext);
46
48
  this.#jobRegistry.finish(this.job);
47
49
  } catch (error) {
48
- Logger.error(`Error occurred while performing job: #${this.job.id} - ${error}`);
50
+ logContext.error(`Error occurred while performing job: #${this.job.id} - ${error}`);
49
51
  this.#jobRegistry.fail(this.job);
50
52
  } finally {
51
53
  this.job = undefined;
@@ -1,5 +1,5 @@
1
- import { Factory } from './Factory.js';
2
- import { Worker } from '../models/Worker.js';
1
+ import { Worker } from './Worker.js';
2
+ import { Factory } from '../factory/Factory.js';
3
3
  import { IdGenerator } from '../utils/generators/IdGenerator.js';
4
4
 
5
5
  /**
@@ -1,4 +1,4 @@
1
- import { WorkerFactory } from '../factories/WorkerFactory.js';
1
+ import { WorkerFactory } from './WorkerFactory.js';
2
2
  import { IdentifyableCollection } from '../utils/collections/IdentifyableCollection.js';
3
3
 
4
4
  /**
@@ -1,4 +1,5 @@
1
- import { JobRegistry as DefaultJobRegistry } from '../registry/JobRegistry.js';
1
+ import { JobRegistry as DefaultJobRegistry } from '../background/JobRegistry.js';
2
+ import { Application } from '../services/Application.js';
2
3
 
3
4
  /**
4
5
  * ActionEnqueuer enqueues one ActionProcessingJob per item for a single Action.
@@ -22,9 +23,11 @@ class ActionEnqueuer {
22
23
 
23
24
  /**
24
25
  * Enqueues one ActionProcessingJob per item for the configured action.
26
+ * Does nothing if the application is in 'stopped' status.
25
27
  * @returns {void}
26
28
  */
27
29
  enqueue() {
30
+ if (Application.isStopped()) return;
28
31
  for (const item of this.#items) {
29
32
  this.#jobRegistry.enqueue('Action', { action: this.#action, item });
30
33
  }
@@ -1,3 +1,4 @@
1
+ import { Application } from '../services/Application.js';
1
2
  import { HtmlParser } from '../utils/HtmlParser.js';
2
3
 
3
4
  /**
@@ -28,10 +29,13 @@ class AssetRequestEnqueuer {
28
29
  /**
29
30
  * Parses the HTML body for URLs matching the asset request rule, resolves each URL
30
31
  * to absolute form, and enqueues one AssetDownloadJob per URL.
32
+ * Does nothing if the application is in 'stopped' status.
33
+ * @param {LogContext} logContext Context carrying workerId/jobId for log entries.
31
34
  * @returns {void}
32
35
  */
33
- enqueue() {
34
- const urls = HtmlParser.parse(this.#rawHtml, this.#assetRequest.selector, this.#assetRequest.attribute);
36
+ enqueue(logContext) {
37
+ if (Application.isStopped()) return;
38
+ const urls = HtmlParser.parse(this.#rawHtml, this.#assetRequest.selector, this.#assetRequest.attribute, logContext);
35
39
  for (const url of urls) {
36
40
  this.#jobRegistry.enqueue('AssetDownload', {
37
41
  url: this.#resolveUrl(url),
@@ -0,0 +1,14 @@
1
+ import { AppError } from './AppError.js';
2
+
3
+ /**
4
+ * ConflictError is thrown when a requested state transition is not valid
5
+ * given the current application state (e.g. pausing an already-paused engine).
6
+ * @author darthjee
7
+ */
8
+ class ConflictError extends AppError {
9
+ constructor() {
10
+ super('Conflict');
11
+ }
12
+ }
13
+
14
+ export { ConflictError };
@@ -1,5 +1,4 @@
1
- import { Job } from './Job.js';
2
- import { Logger } from '../utils/logging/Logger.js';
1
+ import { Job } from '../background/Job.js';
3
2
 
4
3
  /**
5
4
  * ActionProcessingJob is a Job that processes a single Action for a given item.
@@ -44,10 +43,11 @@ class ActionProcessingJob extends Job {
44
43
 
45
44
  /**
46
45
  * Performs the action for the given item.
46
+ * @param {LogContext} logContext - Context carrying workerId/jobId for log entries.
47
47
  * @returns {Promise<void>}
48
48
  */
49
- async perform() {
50
- Logger.debug(`ActionProcessingJob #${this.id} performing`);
49
+ async perform(logContext) {
50
+ logContext.debug(`ActionProcessingJob #${this.id} performing`);
51
51
  try {
52
52
  this.lastError = undefined;
53
53
  await this.#action.execute(this.#item);
@@ -1,5 +1,4 @@
1
- import { Job } from './Job.js';
2
- import { Logger } from '../utils/logging/Logger.js';
1
+ import { Job } from '../background/Job.js';
3
2
 
4
3
  /**
5
4
  * AssetDownloadJob is a Job that fetches a single fully-resolved asset URL and validates
@@ -40,16 +39,17 @@ class AssetDownloadJob extends Job {
40
39
 
41
40
  /**
42
41
  * Fetches the asset URL using the named client and validates the HTTP status.
42
+ * @param {LogContext} logContext - Context carrying workerId/jobId for log entries.
43
43
  * @returns {Promise<object>} The HTTP response.
44
44
  */
45
- async perform() {
46
- Logger.debug(`AssetDownloadJob #${this.id} performing`);
45
+ async perform(logContext) {
46
+ logContext.debug(`AssetDownloadJob #${this.id} performing`);
47
47
  try {
48
48
  this.lastError = undefined;
49
49
  const client = this.#clientRegistry.getClient(this.#clientName);
50
- return await client.performUrl(this.#url, this.#status);
50
+ return await client.performUrl(this.#url, this.#status, logContext);
51
51
  } catch (error) {
52
- Logger.error(`AssetDownloadJob #${this.id} failed: ${error}`);
52
+ logContext.error(`AssetDownloadJob #${this.id} failed: ${error}`);
53
53
  this._fail(error);
54
54
  }
55
55
  }
@@ -1,6 +1,5 @@
1
- import { AssetRequestEnqueuer } from './AssetRequestEnqueuer.js';
2
- import { Job } from './Job.js';
3
- import { Logger } from '../utils/logging/Logger.js';
1
+ import { Job } from '../background/Job.js';
2
+ import { AssetRequestEnqueuer } from '../enqueuers/AssetRequestEnqueuer.js';
4
3
 
5
4
  /**
6
5
  * HtmlParseJob is a Job that parses an HTML response body, extracts asset URLs using
@@ -53,14 +52,15 @@ class HtmlParseJob extends Job {
53
52
 
54
53
  /**
55
54
  * Parses the HTML body, resolves asset URLs, and enqueues one AssetDownloadJob per URL.
55
+ * @param {LogContext} logContext - Context carrying workerId/jobId for log entries.
56
56
  * @returns {Promise<void>}
57
57
  */
58
- async perform() {
59
- Logger.debug(`HtmlParseJob #${this.id} performing`);
58
+ async perform(logContext) {
59
+ logContext.debug(`HtmlParseJob #${this.id} performing`);
60
60
  try {
61
61
  this.lastError = undefined;
62
62
  for (const assetRequest of this.#assetRequests) {
63
- new AssetRequestEnqueuer(this.#rawHtml, assetRequest, this.#jobRegistry, this.#clientRegistry).enqueue();
63
+ new AssetRequestEnqueuer(this.#rawHtml, assetRequest, this.#jobRegistry, this.#clientRegistry).enqueue(logContext);
64
64
  }
65
65
  } catch (error) {
66
66
  this._fail(error);
@@ -1,7 +1,6 @@
1
- import { Job } from './Job.js';
2
- import { ResponseWrapper } from './ResponseWrapper.js';
3
- import { JobRegistry } from '../registry/JobRegistry.js';
4
- import { Logger } from '../utils/logging/Logger.js';
1
+ import { Job } from '../background/Job.js';
2
+ import { JobRegistry } from '../background/JobRegistry.js';
3
+ import { ResponseWrapper } from '../models/ResponseWrapper.js';
5
4
 
6
5
  /**
7
6
  * ResourceRequestJob is a Job that performs an HTTP request for a ResourceRequest.
@@ -30,24 +29,26 @@ class ResourceRequestJob extends Job {
30
29
 
31
30
  /**
32
31
  * Returns the job-specific arguments for serialization.
33
- * @returns {{ url: string, parameters: object }} The job arguments.
32
+ * The URL is fully resolved with all parameter placeholders substituted.
33
+ * @returns {{ url: string }} The job arguments.
34
34
  */
35
35
  get arguments() {
36
- return { url: this.#resourceRequest.url, parameters: this.#parameters };
36
+ return { url: this.#resourceRequest.resolveUrl(this.#parameters) };
37
37
  }
38
38
 
39
39
  /**
40
40
  * Performs the HTTP request for the resource request.
41
+ * @param {LogContext} logContext - Context carrying workerId/jobId for log entries.
41
42
  * @returns {Promise} A promise that resolves with the HTTP response.
42
43
  */
43
- async perform() {
44
- Logger.debug(`ResourceRequestJob #${this.id} performing`);
44
+ async perform(logContext) {
45
+ logContext.debug(`ResourceRequestJob #${this.id} performing`);
45
46
  try {
46
47
  this.lastError = undefined;
47
- const response = await this.#getClient().perform(this.#resourceRequest, this.#parameters);
48
+ const response = await this.#getClient().perform(this.#resourceRequest, this.#parameters, logContext);
48
49
  return this.#handleResponse(response);
49
50
  } catch (error) {
50
- Logger.error(`Job #${this.id} failed: ${error}`);
51
+ logContext.error(`Job #${this.id} failed: ${error}`);
51
52
  this._fail(error);
52
53
  }
53
54
  }
@@ -90,4 +91,3 @@ class ResourceRequestJob extends Job {
90
91
  }
91
92
 
92
93
  export { ResourceRequestJob };
93
-
@@ -1,7 +1,8 @@
1
- import { ActionsEnqueuer } from './ActionsEnqueuer.js';
2
1
  import { AssetRequest } from './AssetRequest.js';
3
2
  import { ResourceRequestAction } from './ResourceRequestAction.js';
4
- import { JobRegistry as DefaultJobRegistry } from '../registry/JobRegistry.js';
3
+ import { JobRegistry as DefaultJobRegistry } from '../background/JobRegistry.js';
4
+ import { ActionsEnqueuer } from '../enqueuers/ActionsEnqueuer.js';
5
+ import { Application } from '../services/Application.js';
5
6
 
6
7
  /**
7
8
  * ResourceRequest represents a request to a specific URL with an expected status code.
@@ -50,12 +51,14 @@ class ResourceRequest {
50
51
 
51
52
  /**
52
53
  * Enqueues one HtmlParseJob for this resource request's asset extraction rules.
54
+ * Does nothing if the application is in 'stopped' status.
53
55
  * @param {string} rawHtml The raw HTML response body string.
54
56
  * @param {object} [jobRegistry=JobRegistry] The job registry used to enqueue the HtmlParseJob.
55
57
  * @param {object} clientRegistry The client registry for URL resolution inside HtmlParseJob.
56
58
  * @returns {void}
57
59
  */
58
60
  enqueueAssets(rawHtml, jobRegistry = DefaultJobRegistry, clientRegistry) {
61
+ if (Application.isStopped()) return;
59
62
  jobRegistry.enqueue('HtmlParse', { rawHtml, assetRequests: this.assets, clientRegistry });
60
63
  }
61
64
 
@@ -1,8 +1,9 @@
1
1
  import { ParametersMapper } from './ParametersMapper.js';
2
+ import { JobRegistry as DefaultJobRegistry } from '../background/JobRegistry.js';
2
3
  import { MissingActionResource } from '../exceptions/MissingActionResource.js';
3
- import { JobRegistry as DefaultJobRegistry } from '../registry/JobRegistry.js';
4
+ import { LogRegistry } from '../registry/LogRegistry.js';
4
5
  import { ResourceRegistry as DefaultResourceRegistry } from '../registry/ResourceRegistry.js';
5
- import { Logger } from '../utils/logging/Logger.js';
6
+ import { Application } from '../services/Application.js';
6
7
 
7
8
  /**
8
9
  * Represents a single action to execute after a successful resource request response.
@@ -39,11 +40,13 @@ class ResourceRequestAction {
39
40
  /**
40
41
  * Maps the response wrapper to variables, looks up the target resource, and
41
42
  * enqueues one ResourceRequestJob per ResourceRequest in that resource.
43
+ * Does nothing if the application is in 'stopped' status.
42
44
  * @param {ResponseWrapper} responseWrapper A ResponseWrapper instance exposing
43
45
  * parsedBody and headers.
44
46
  * @returns {void}
45
47
  */
46
48
  execute(responseWrapper) {
49
+ if (Application.isStopped()) return;
47
50
  const vars = this.#mapper.map(responseWrapper);
48
51
  const resource = this.#resourceRegistry.getItem(this.resource);
49
52
 
@@ -63,7 +66,7 @@ class ResourceRequestAction {
63
66
  try {
64
67
  return [new ResourceRequestAction(attrs)];
65
68
  } catch (error) {
66
- Logger.error(`Skipping action: ${error}`);
69
+ LogRegistry.error(`Skipping action: ${error}`);
67
70
  return [];
68
71
  }
69
72
  });
@@ -6,9 +6,13 @@ class WebConfig {
6
6
  /**
7
7
  * @param {object} config - Configuration object.
8
8
  * @param {number} config.port - The port number to listen on.
9
+ * @param {number} [config.logs_page_size=20] - Maximum number of log entries per page.
10
+ * @param {boolean} [config.enable_shutdown=true] - Whether the shutdown button is enabled.
9
11
  */
10
- constructor({ port }) {
12
+ constructor({ port, logs_page_size: logsPageSize = 20, enable_shutdown: enableShutdown = true }) {
11
13
  this.port = port;
14
+ this.logsPageSize = logsPageSize;
15
+ this.enableShutdown = enableShutdown;
12
16
  }
13
17
  }
14
18
 
@@ -0,0 +1,146 @@
1
+ import { LogRegistryInstance } from './LogRegistryInstance.js';
2
+
3
+ /**
4
+ * LogRegistry is a static singleton facade for the application's buffered log publisher.
5
+ *
6
+ * Call `LogRegistry.build(options)` once during application bootstrap.
7
+ * Use `LogRegistry.reset()` in tests to restore a clean state between examples.
8
+ * @author darthjee
9
+ */
10
+ class LogRegistry {
11
+ static #instance = null;
12
+
13
+ /**
14
+ * Creates and stores the singleton instance.
15
+ * @param {object} [options={}] - Forwarded to LogRegistryInstance constructor.
16
+ * @returns {LogRegistryInstance} The created instance.
17
+ * @throws {Error} If build() has already been called without a preceding reset().
18
+ */
19
+ static build(options = {}) {
20
+ if (LogRegistry.#instance) {
21
+ throw new Error('LogRegistry.build() has already been called. Call reset() first.');
22
+ }
23
+ LogRegistry.#instance = new LogRegistryInstance(options);
24
+ return LogRegistry.#instance;
25
+ }
26
+
27
+ /**
28
+ * Destroys the singleton instance. Intended for test teardown.
29
+ * @returns {void}
30
+ */
31
+ static reset() {
32
+ LogRegistry.#instance = null;
33
+ }
34
+
35
+ /**
36
+ * Logs a debug message to both the console and the API buffer.
37
+ * @param {string} message - The message to log.
38
+ * @param {object} [attributes={}] - Optional structured metadata.
39
+ * @returns {void}
40
+ */
41
+ static debug(message, attributes = {}) {
42
+ LogRegistry.#getInstance().debug(message, attributes);
43
+ }
44
+
45
+ /**
46
+ * Logs an error message to both the console and the API buffer.
47
+ * @param {string} message - The message to log.
48
+ * @param {object} [attributes={}] - Optional structured metadata.
49
+ * @returns {void}
50
+ */
51
+ static error(message, attributes = {}) {
52
+ LogRegistry.#getInstance().error(message, attributes);
53
+ }
54
+
55
+ /**
56
+ * Gets a specific log by ID.
57
+ * @param {number} id
58
+ * @returns {import('../utils/logging/Log.js').Log|undefined}
59
+ */
60
+ static getLogById(id) {
61
+ return LogRegistry.#getInstance().getLogById(id);
62
+ }
63
+
64
+ /**
65
+ * Gets logs in chronological order (oldest first), optionally filtered to entries newer than lastId.
66
+ * @param {object} [options={}]
67
+ * @param {number|string} [options.lastId] - When provided, returns only logs newer than this ID.
68
+ * Returns an empty array if the ID is not found.
69
+ * @returns {Array<import('../utils/logging/Log.js').Log>}
70
+ */
71
+ static getLogs({ lastId } = {}) {
72
+ return LogRegistry.#getInstance().getLogs({ lastId });
73
+ }
74
+
75
+ /**
76
+ * Gets logs stored in the per-job buffer for the given job ID,
77
+ * optionally filtered to entries newer than lastId.
78
+ * @param {string|number} jobId
79
+ * @param {object} [options={}]
80
+ * @param {number|string} [options.lastId] - When provided, returns only logs newer than this ID.
81
+ * @returns {Array<import('../utils/logging/Log.js').Log>}
82
+ */
83
+ static getLogsByJobId(jobId, { lastId } = {}) {
84
+ return LogRegistry.#getInstance().getLogsByJobId(jobId, { lastId });
85
+ }
86
+
87
+ /**
88
+ * Gets logs stored in the per-worker buffer for the given worker ID.
89
+ * @param {string|number} workerId
90
+ * @returns {Array<import('../utils/logging/Log.js').Log>}
91
+ */
92
+ static getLogsByWorkerId(workerId) {
93
+ return LogRegistry.#getInstance().getLogsByWorkerId(workerId);
94
+ }
95
+
96
+ /**
97
+ * Gets logs filtered by level.
98
+ * @param {string} level
99
+ * @returns {Array<import('../utils/logging/Log.js').Log>}
100
+ */
101
+ static getLogsByLevel(level) {
102
+ return LogRegistry.#getInstance().getLogsByLevel(level);
103
+ }
104
+
105
+ /**
106
+ * Returns all logs as plain JSON objects.
107
+ * @returns {Array<object>}
108
+ */
109
+ static getLogsJSON() {
110
+ return LogRegistry.#getInstance().getLogsJSON();
111
+ }
112
+
113
+ /**
114
+ * Logs an info message to both the console and the API buffer.
115
+ * @param {string} message - The message to log.
116
+ * @param {object} [attributes={}] - Optional structured metadata.
117
+ * @returns {void}
118
+ */
119
+ static info(message, attributes = {}) {
120
+ LogRegistry.#getInstance().info(message, attributes);
121
+ }
122
+
123
+ /**
124
+ * Logs a warn message to both the console and the API buffer.
125
+ * @param {string} message - The message to log.
126
+ * @param {object} [attributes={}] - Optional structured metadata.
127
+ * @returns {void}
128
+ */
129
+ static warn(message, attributes = {}) {
130
+ LogRegistry.#getInstance().warn(message, attributes);
131
+ }
132
+
133
+ /**
134
+ * Returns the singleton instance, throwing if not yet built.
135
+ * @returns {LogRegistryInstance}
136
+ * @throws {Error} If build() has not been called.
137
+ */
138
+ static #getInstance() {
139
+ if (!LogRegistry.#instance) {
140
+ throw new Error('LogRegistry has not been built. Call LogRegistry.build() first.');
141
+ }
142
+ return LogRegistry.#instance;
143
+ }
144
+ }
145
+
146
+ export { LogRegistry };