navi-hey 1.6.1 → 1.6.3

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 (39) hide show
  1. package/lib/enqueuers/ActionEnqueuer.js +1 -1
  2. package/lib/enqueuers/PaginatedActionEnqueuer.js +1 -1
  3. package/lib/jobs/ActionProcessingJob.js +1 -1
  4. package/lib/jobs/AssetDownloadJob.js +1 -1
  5. package/lib/jobs/HtmlParseJob.js +1 -1
  6. package/lib/jobs/PaginatedActionProcessingJob.js +1 -1
  7. package/lib/jobs/ResourceRequestJob.js +1 -2
  8. package/lib/models/configs/PageRange.js +37 -0
  9. package/lib/models/configs/PaginationConfig.js +7 -11
  10. package/lib/models/request/ResourceRequest.js +31 -1
  11. package/lib/models/request/ResourceRequestAction.js +1 -1
  12. package/lib/models/request/ResourceRequestPaginatedAction.js +15 -11
  13. package/lib/server/handlers/StatsHandler.js +1 -2
  14. package/lib/server/handlers/jobs/JobHandler.js +1 -1
  15. package/lib/server/handlers/jobs/JobRetryHandler.js +1 -1
  16. package/lib/server/handlers/jobs/JobsHandler.js +1 -1
  17. package/lib/services/ApplicationInstance.js +9 -7
  18. package/lib/services/FailureChecker.js +1 -1
  19. package/lib/utils/ResourceEnqueuer.js +1 -1
  20. package/package.json +2 -1
  21. package/lib/background/Job.js +0 -97
  22. package/lib/background/JobFactory.js +0 -82
  23. package/lib/background/JobRegistry.js +0 -160
  24. package/lib/background/JobRegistryInstance.js +0 -247
  25. package/lib/background/Worker.js +0 -59
  26. package/lib/background/WorkerFactory.js +0 -35
  27. package/lib/background/WorkersRegistry.js +0 -106
  28. package/lib/background/WorkersRegistryInstance.js +0 -139
  29. package/lib/factory/Factory.js +0 -79
  30. package/lib/services/Engine.js +0 -153
  31. package/lib/services/WorkersAllocator.js +0 -74
  32. package/lib/utils/collections/Collection.js +0 -26
  33. package/lib/utils/collections/IdentifyableCollection.js +0 -95
  34. package/lib/utils/collections/Queue.js +0 -53
  35. package/lib/utils/collections/SortedArrayMerger.js +0 -84
  36. package/lib/utils/collections/SortedArraySearcher.js +0 -101
  37. package/lib/utils/collections/SortedCollection.js +0 -169
  38. package/lib/utils/generators/IdGenerator.js +0 -79
  39. package/lib/utils/generators/UUidGenerator.js +0 -49
@@ -1,160 +0,0 @@
1
- import { JobRegistryInstance } from './JobRegistryInstance.js';
2
-
3
- /**
4
- * JobRegistry is a static singleton facade for managing the application's job queues.
5
- *
6
- * Call `JobRegistry.build(options)` once during application bootstrap.
7
- * Use `JobRegistry.reset()` in tests to restore a clean state between examples.
8
- * @author darthjee
9
- */
10
- class JobRegistry {
11
- static #instance = null;
12
-
13
- /**
14
- * Creates and stores the singleton instance.
15
- * @param {object} [options={}] - Forwarded to `JobRegistryInstance` constructor.
16
- * @returns {JobRegistryInstance} The created instance.
17
- * @throws {Error} If `build()` has already been called without a preceding `reset()`.
18
- */
19
- static build(options = {}) {
20
- if (JobRegistry.#instance) {
21
- throw new Error('JobRegistry.build() has already been called. Call reset() first.');
22
- }
23
- JobRegistry.#instance = new JobRegistryInstance(options);
24
- return JobRegistry.#instance;
25
- }
26
-
27
- /**
28
- * Destroys the singleton instance. Intended for test teardown.
29
- * @returns {void}
30
- */
31
- static reset() {
32
- JobRegistry.#instance = null;
33
- }
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
-
43
- /**
44
- * Enqueues a new job using the factory registered under the given key.
45
- * @param {string} factoryKey - The factory key to use.
46
- * @param {object} [params={}] - Build params forwarded to the factory.
47
- * @returns {Job} The created and enqueued Job instance.
48
- */
49
- static enqueue(factoryKey, params = {}) {
50
- return JobRegistry.#getInstance().enqueue(factoryKey, params);
51
- }
52
-
53
- /**
54
- * Marks a job as failed.
55
- * @param {Job} job - The job to mark as failed.
56
- * @returns {void}
57
- */
58
- static fail(job) {
59
- return JobRegistry.#getInstance().fail(job);
60
- }
61
-
62
- /**
63
- * Marks a job as finished.
64
- * @param {Job} job - The job to mark as finished.
65
- * @returns {void}
66
- */
67
- static finish(job) {
68
- return JobRegistry.#getInstance().finish(job);
69
- }
70
-
71
- /**
72
- * Picks the next ready job and moves it to processing.
73
- * @returns {Job|undefined} The next ready job, or undefined if none are ready.
74
- */
75
- static pick() {
76
- return JobRegistry.#getInstance().pick();
77
- }
78
-
79
- /**
80
- * Moves a job from processing back to the enqueued queue.
81
- * @param {Job} job - The job to re-enqueue.
82
- * @returns {void}
83
- */
84
- static requeue(job) {
85
- return JobRegistry.#getInstance().requeue(job);
86
- }
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
-
97
- /**
98
- * Promotes cooling-down failed jobs that are ready to retry.
99
- * @returns {void}
100
- */
101
- static promoteReadyJobs() {
102
- return JobRegistry.#getInstance().promoteReadyJobs();
103
- }
104
-
105
- /**
106
- * Returns whether any jobs exist (including those in cooldown).
107
- * @returns {boolean} True if any jobs exist.
108
- */
109
- static hasJob() {
110
- return JobRegistry.#getInstance().hasJob();
111
- }
112
-
113
- /**
114
- * Returns whether any jobs are immediately ready to be picked.
115
- * @returns {boolean} True if any jobs are ready.
116
- */
117
- static hasReadyJob() {
118
- return JobRegistry.#getInstance().hasReadyJob();
119
- }
120
-
121
- /**
122
- * Returns all jobs in the given status collection.
123
- * @param {string} status - The status name to filter by.
124
- * @returns {object[]} Array of raw job instances, or an empty array for unknown status.
125
- */
126
- static jobsByStatus(status) {
127
- return JobRegistry.#getInstance().jobsByStatus(status);
128
- }
129
-
130
- /**
131
- * Searches all collections and returns the job and its status for the given ID.
132
- * @param {string} id - The ID of the job to look up.
133
- * @returns {{ job: object, status: string } | null} The raw job and its status, or null if not found.
134
- */
135
- static jobById(id) {
136
- return JobRegistry.#getInstance().jobById(id);
137
- }
138
-
139
- /**
140
- * Returns counts of jobs in each state.
141
- * @returns {{ enqueued: number, processing: number, failed: number, retryQueue: number, finished: number, dead: number, total: number }} Job counts per state, plus total (dead + finished).
142
- */
143
- static stats() {
144
- return JobRegistry.#getInstance().stats();
145
- }
146
-
147
- /**
148
- * Returns the singleton instance, throwing if not yet built.
149
- * @returns {JobRegistryInstance} The singleton instance.
150
- * @throws {Error} If `build()` has not been called.
151
- */
152
- static #getInstance() {
153
- if (!JobRegistry.#instance) {
154
- throw new Error('JobRegistry has not been built. Call JobRegistry.build() first.');
155
- }
156
- return JobRegistry.#instance;
157
- }
158
- }
159
-
160
- export { JobRegistry };
@@ -1,247 +0,0 @@
1
- import { JobFactory } from './JobFactory.js';
2
- import { IdentifyableCollection } from '../utils/collections/IdentifyableCollection.js';
3
- import { Queue } from '../utils/collections/Queue.js';
4
- import { SortedCollection } from '../utils/collections/SortedCollection.js';
5
-
6
- const FAILED_SORT_BY = job => job.readyBy;
7
-
8
- /**
9
- * Holds the actual job queues for the JobRegistry singleton.
10
- * Not exported — use the static `JobRegistry` facade instead.
11
- * @author darthjee
12
- */
13
- class JobRegistryInstance {
14
- #enqueued;
15
- #failed;
16
- #retryQueue;
17
- #finished;
18
- #dead;
19
- #processing;
20
- #cooldown;
21
- #maxRetries;
22
-
23
- /**
24
- * @param {object} [options={}] - Construction options.
25
- * @param {Queue} [options.queue] - Initial enqueued jobs queue.
26
- * @param {SortedCollection} [options.failed] - Initial failed jobs collection.
27
- * @param {Queue} [options.retryQueue] - Initial retry queue.
28
- * @param {IdentifyableCollection} [options.finished] - Initial finished jobs collection.
29
- * @param {IdentifyableCollection} [options.dead] - Initial dead jobs collection.
30
- * @param {IdentifyableCollection} [options.processing] - Initial processing jobs collection.
31
- * @param {number} [options.cooldown=5000] - Cooldown in milliseconds before a failed job is retried.
32
- * @param {number} [options.maxRetries=3] - Maximum number of retries before a job is marked dead.
33
- */
34
- constructor({ queue, failed, retryQueue, finished, dead, processing, cooldown = 5000, maxRetries = 3 } = {}) {
35
- this.#enqueued = queue || new Queue();
36
- this.#failed = failed || new SortedCollection([], { sortBy: FAILED_SORT_BY });
37
- this.#retryQueue = retryQueue || new Queue();
38
- this.#finished = finished || new IdentifyableCollection();
39
- this.#dead = dead || new IdentifyableCollection();
40
- this.#processing = processing || new IdentifyableCollection();
41
- this.#cooldown = cooldown;
42
- this.#maxRetries = maxRetries;
43
- }
44
-
45
- /**
46
- * Enqueues a new job using the factory registered under the given key.
47
- * @param {string} factoryKey - The factory key to use.
48
- * @param {object} [params={}] - Build params forwarded to the factory.
49
- * @returns {Job} The created and enqueued Job instance.
50
- */
51
- enqueue(factoryKey, params = {}) {
52
- const job = JobFactory.get(factoryKey).build(params);
53
- this.#enqueued.push(job);
54
- return job;
55
- }
56
-
57
- /**
58
- * Marks a job as failed.
59
- * @param {Job} job - The job to mark as failed.
60
- * @returns {void}
61
- */
62
- fail(job) {
63
- if (!job) return;
64
- this.#processing.remove(job.id);
65
- if (job.exhausted(this.#maxRetries)) {
66
- this.#dead.push(job);
67
- } else {
68
- job.applyCooldown(this.#cooldown);
69
- this.#failed.push(job);
70
- }
71
- }
72
-
73
- /**
74
- * Marks a job as finished.
75
- * @param {Job} job - The job to mark as finished.
76
- * @returns {void}
77
- */
78
- finish(job) {
79
- if (!job) return;
80
- this.#processing.remove(job.id);
81
- this.#finished.push(job);
82
- }
83
-
84
- /**
85
- * Picks (removes and returns) the first ready job and adds it to processing.
86
- * @returns {Job|undefined} The first available job, or undefined if none are ready.
87
- */
88
- pick() {
89
- const job = this.#enqueued.pick() || this.#retryQueue.pick();
90
- if (job) {
91
- this.#processing.push(job);
92
- }
93
- return job;
94
- }
95
-
96
- /**
97
- * Moves a job from processing back to the enqueued queue.
98
- * @param {Job} job - The job to re-enqueue.
99
- * @returns {void}
100
- */
101
- requeue(job) {
102
- if (!job) return;
103
- this.#processing.remove(job.id);
104
- this.#enqueued.push(job);
105
- }
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
-
135
- /**
136
- * Promotes jobs from the failed queue to the retryQueue once their cooldown has elapsed.
137
- * @returns {void}
138
- */
139
- promoteReadyJobs() {
140
- const now = Date.now();
141
- const ready = this.#failed.upTo(now);
142
- const waiting = this.#failed.after(now);
143
-
144
- this.#failed = new SortedCollection(waiting, { sortBy: FAILED_SORT_BY });
145
- ready.forEach(job => this.#retryQueue.push(job));
146
- }
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
-
161
- /**
162
- * Returns whether the registry has any jobs pending (including those in cooldown).
163
- * @returns {boolean} True if any of enqueued, failed, or retryQueue is non-empty.
164
- */
165
- hasJob() {
166
- return this.#enqueued.hasAny() || this.#failed.hasAny() || this.#retryQueue.hasAny();
167
- }
168
-
169
- /**
170
- * Returns whether there is a job ready to be picked by a worker right now.
171
- * @returns {boolean} True if enqueued or retryQueue is non-empty.
172
- */
173
- hasReadyJob() {
174
- return this.#enqueued.hasAny() || this.#retryQueue.hasAny();
175
- }
176
-
177
- /**
178
- * Returns all jobs in the collection that corresponds to the given status.
179
- * @param {string} status - The status name ('enqueued', 'processing', 'failed', 'retryQueue', 'finished', 'dead').
180
- * @returns {object[]} Array of raw job instances, or an empty array for unknown status.
181
- */
182
- jobsByStatus(status) {
183
- const collection = this.#collectionByStatus(status);
184
- if (!collection) return [];
185
- return collection.list();
186
- }
187
-
188
- /**
189
- * Searches all collections and returns the job and its status for the given ID.
190
- * @param {string} id - The ID of the job to look up.
191
- * @returns {{ job: object, status: string } | null} The raw job and its status, or null if not found.
192
- */
193
- jobById(id) {
194
- for (const status of Object.keys(this.#collectionsByStatus())) {
195
- const job = this.#collectionByStatus(status).findById(id);
196
- if (job) {
197
- return { job, status };
198
- }
199
- }
200
- return null;
201
- }
202
-
203
- /**
204
- * Returns counts of jobs in each state.
205
- * @returns {{ enqueued: number, processing: number, failed: number, retryQueue: number, finished: number, dead: number, total: number }} Counts of jobs in each state, plus total (dead + finished).
206
- */
207
- stats() {
208
- const dead = this.#dead.size();
209
- const finished = this.#finished.size();
210
-
211
- return {
212
- enqueued: this.#enqueued.size(),
213
- processing: this.#processing.size(),
214
- failed: this.#failed.size(),
215
- retryQueue: this.#retryQueue.size(),
216
- finished,
217
- dead,
218
- total: dead + finished,
219
- };
220
- }
221
-
222
- /**
223
- * Returns the collection corresponding to the given status, or undefined.
224
- * @param {string} status - The status name.
225
- * @returns {object|undefined} The collection for the given status, or undefined if unknown.
226
- */
227
- #collectionByStatus(status) {
228
- return this.#collectionsByStatus()[status];
229
- }
230
-
231
- /**
232
- * Returns an object mapping each status name to its corresponding collection.
233
- * @returns {object} A map of status names to collection instances.
234
- */
235
- #collectionsByStatus() {
236
- return {
237
- enqueued: this.#enqueued,
238
- processing: this.#processing,
239
- failed: this.#failed,
240
- retryQueue: this.#retryQueue,
241
- finished: this.#finished,
242
- dead: this.#dead,
243
- };
244
- }
245
- }
246
-
247
- export { JobRegistryInstance };
@@ -1,59 +0,0 @@
1
- import { LogContext } from '../utils/logging/LogContext.js';
2
-
3
- /**
4
- * Worker processes jobs pulled from a JobRegistry.
5
- * @author darthjee
6
- */
7
- class Worker {
8
- #jobRegistry;
9
- #workersRegistry;
10
-
11
- /**
12
- * Creates a new Worker instance.
13
- * @param {object} params - The parameters for creating a Worker instance.
14
- * @param {string|number} params.id - The unique identifier for this worker.
15
- * @param {JobRegistry} params.jobRegistry - The job registry to report job outcomes to.
16
- * @param {WorkersRegistry} params.workersRegistry - The workers registry to report idle status to.
17
- */
18
- constructor({ id, jobRegistry, workersRegistry }) {
19
- this.id = id;
20
- this.#jobRegistry = jobRegistry;
21
- this.#workersRegistry = workersRegistry;
22
- }
23
-
24
- /**
25
- * Assigns a job to this worker.
26
- * @param {Job} job - The job to assign.
27
- * @returns {void}
28
- */
29
- assign(job) {
30
- this.job = job;
31
- }
32
-
33
- /**
34
- * Performs the assigned job. If no job is assigned, an error is thrown.
35
- * Any errors that occur during job execution are caught and logged.
36
- * @returns {Promise<void>}
37
- * @see Job.perform() for the actual job execution logic.
38
- */
39
- async perform() {
40
- if (!this.job) {
41
- throw new Error('No job assigned to worker');
42
- }
43
-
44
- const logContext = new LogContext({ workerId: this.id, jobId: this.job.id });
45
-
46
- try {
47
- await this.job.perform(logContext);
48
- this.#jobRegistry.finish(this.job);
49
- } catch (error) {
50
- logContext.error(`Error occurred while performing job: #${this.job.id} - ${error}`);
51
- this.#jobRegistry.fail(this.job);
52
- } finally {
53
- this.job = undefined;
54
- this.#workersRegistry.setIdle(this.id);
55
- }
56
- }
57
- }
58
-
59
- export { Worker };
@@ -1,35 +0,0 @@
1
- import { Worker } from './Worker.js';
2
- import { Factory } from '../factory/Factory.js';
3
- import { IdGenerator } from '../utils/generators/IdGenerator.js';
4
-
5
- /**
6
- * WorkerFactory is responsible for creating Worker instances with unique identifiers.
7
- * It uses the Factory base class to generate Worker instances with specified attributes.
8
- * @author darthjee
9
- */
10
- class WorkerFactory extends Factory {
11
- #registries;
12
-
13
- /**
14
- * Creates a new WorkerFactory instance.
15
- * @param {object} options - Configuration options for the factory.
16
- * @param {class} options.klass - The class to instantiate (default is Worker).
17
- * @param {object} options.attributesGenerator - The generator for unique attributes (default is IdGenerator).
18
- * @param {object} [options.jobRegistry] - The job registry to inject into each Worker.
19
- * @param {object} [options.workersRegistry] - The workers registry to inject into each Worker.
20
- */
21
- constructor({ klass = Worker, attributesGenerator = new IdGenerator(), jobRegistry, workersRegistry } = {}) {
22
- super({ klass, attributesGenerator });
23
- this.#registries = { jobRegistry, workersRegistry };
24
- }
25
-
26
- /**
27
- * Builds a new Worker instance.
28
- * @returns {Worker} The created Worker instance.
29
- */
30
- build() {
31
- return super.build({ ...this.#registries });
32
- }
33
- }
34
-
35
- export { WorkerFactory };
@@ -1,106 +0,0 @@
1
- import { WorkersRegistryInstance } from './WorkersRegistryInstance.js';
2
-
3
- /**
4
- * WorkersRegistry is a static singleton facade for managing the application's worker pool.
5
- *
6
- * Call `WorkersRegistry.build(options)` once during application bootstrap.
7
- * Use `WorkersRegistry.reset()` in tests to restore a clean state between examples.
8
- * @author darthjee
9
- */
10
- class WorkersRegistry {
11
- static #instance = null;
12
-
13
- /**
14
- * Creates and stores the singleton instance.
15
- * @param {object} [options={}] - Forwarded to `WorkersRegistryInstance` constructor.
16
- * @returns {WorkersRegistryInstance} The created instance.
17
- * @throws {Error} If `build()` has already been called without a preceding `reset()`.
18
- */
19
- static build(options = {}) {
20
- if (WorkersRegistry.#instance) {
21
- throw new Error('WorkersRegistry.build() has already been called. Call reset() first.');
22
- }
23
- WorkersRegistry.#instance = new WorkersRegistryInstance(options);
24
- return WorkersRegistry.#instance;
25
- }
26
-
27
- /**
28
- * Destroys the singleton instance. Intended for test teardown.
29
- * @returns {void}
30
- */
31
- static reset() {
32
- WorkersRegistry.#instance = null;
33
- }
34
-
35
- /**
36
- * Initializes the specified number of workers.
37
- * @returns {void}
38
- */
39
- static initWorkers() {
40
- return WorkersRegistry.#getInstance().initWorkers();
41
- }
42
-
43
- /**
44
- * Sets a worker as busy.
45
- * @param {string} id - The ID of the worker to set as busy.
46
- * @returns {void}
47
- */
48
- static setBusy(id) {
49
- return WorkersRegistry.#getInstance().setBusy(id);
50
- }
51
-
52
- /**
53
- * Sets a worker as idle.
54
- * @param {string} id - The ID of the worker to set as idle.
55
- * @returns {void}
56
- */
57
- static setIdle(id) {
58
- return WorkersRegistry.#getInstance().setIdle(id);
59
- }
60
-
61
- /**
62
- * Checks if there is at least one busy worker.
63
- * @returns {boolean} True if there is at least one busy worker, false otherwise.
64
- */
65
- static hasBusyWorker() {
66
- return WorkersRegistry.#getInstance().hasBusyWorker();
67
- }
68
-
69
- /**
70
- * Checks if there is at least one idle worker.
71
- * @returns {boolean} True if there is at least one idle worker, false otherwise.
72
- */
73
- static hasIdleWorker() {
74
- return WorkersRegistry.#getInstance().hasIdleWorker();
75
- }
76
-
77
- /**
78
- * Gets an idle worker if available.
79
- * @returns {Worker|null} An idle worker if available, or null if no idle workers are present.
80
- */
81
- static getIdleWorker() {
82
- return WorkersRegistry.#getInstance().getIdleWorker();
83
- }
84
-
85
- /**
86
- * Returns counts of workers in each state.
87
- * @returns {{ idle: number, busy: number }} Counts of workers in each state.
88
- */
89
- static stats() {
90
- return WorkersRegistry.#getInstance().stats();
91
- }
92
-
93
- /**
94
- * Returns the singleton instance, throwing if not yet built.
95
- * @returns {WorkersRegistryInstance} The singleton instance.
96
- * @throws {Error} If `build()` has not been called.
97
- */
98
- static #getInstance() {
99
- if (!WorkersRegistry.#instance) {
100
- throw new Error('WorkersRegistry has not been built. Call WorkersRegistry.build() first.');
101
- }
102
- return WorkersRegistry.#instance;
103
- }
104
- }
105
-
106
- export { WorkersRegistry };