clever-queue 0.3.0 → 0.4.1

package/test/issues/00008-error-contract.mjs

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import * as cleverQueue from "../../dist/index.js";
+
+const engineOptions = {
+  bestEffortRunners: 1,
+};
+
+async function runFailingTask(thrownValue) {
+  const engine = cleverQueue.createEngine(engineOptions);
+  const queue = engine.createQueue({
+    priority: cleverQueue.queues.Priorities.Absolute,
+    weight: 50,
+  });
+
+  try {
+    await queue.enqueue(
+      engine.createTask(async () => {
+        throw thrownValue;
+      }, {}),
+    );
+    throw new Error("task was expected to reject");
+  } finally {
+    engine.stop();
+  }
+}
+
+describe("Issue #8 - task error propagation contract", () => {
+  it("rejects with the original Error instance when a task throws an Error", async () => {
+    const originalError = new Error("original error");
+
+    await assert.rejects(() => runFailingTask(originalError), (error) => {
+      assert.equal(error, originalError);
+      return true;
+    });
+  });
+
+  it("wraps thrown strings in the documented CQError fallback", async () => {
+    await assert.rejects(() => runFailingTask("boom"), {
+      name: cleverQueue.tasks.ErrorsList.FunctionRaisedAnHundledException.name,
+      message: cleverQueue.tasks.ErrorsList.FunctionRaisedAnHundledException.message,
+    });
+  });
+
+  it("wraps thrown objects in the documented CQError fallback", async () => {
+    await assert.rejects(() => runFailingTask({ code: "E_OBJECT" }), {
+      name: cleverQueue.tasks.ErrorsList.FunctionRaisedAnHundledException.name,
+      message: cleverQueue.tasks.ErrorsList.FunctionRaisedAnHundledException.message,
+    });
+  });
+});

package/test/issues/00009-weight-semantics.mjs

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import * as cleverQueue from "../../dist/index.js";
+
+async function dequeueIds(engine, count) {
+  const ids = [];
+  for (let index = 0; index < count; index += 1) {
+    const task = await engine.getNextTask(cleverQueue.queues.Priorities.BestEffort);
+    assert.ok(task);
+    ids.push(task.options.id);
+  }
+
+  return ids;
+}
+
+describe("Issue #9 - queue weight semantics", () => {
+  it("exposes 1 as the lowest valid queue weight", () => {
+    assert.equal(cleverQueue.queues.Weights.Lowest, 1);
+  });
+
+  it("rejects weight 0 because active queues must have a positive scheduling weight", () => {
+    const engine = cleverQueue.createEngine({ bestEffortRunners: 1 });
+
+    assert.throws(
+      () =>
+        engine.createQueue({
+          priority: cleverQueue.queues.Priorities.Standard,
+          weight: 0,
+        }),
+      {
+        name: cleverQueue.queues.ErrorsList.NoWeightOptionsOnQueueInitialization.name,
+        message: cleverQueue.queues.ErrorsList.NoWeightOptionsOnQueueInitialization.message,
+      },
+    );
+
+    engine.stop();
+  });
+
+  it("uses larger weights to receive proportionally more scheduling turns over time", async () => {
+    const engine = cleverQueue.createEngine({ autostart: false, bestEffortRunners: 1 });
+    const heavyQueue = engine.createQueue({ priority: cleverQueue.queues.Priorities.Standard, weight: 2 });
+    const lightQueue = engine.createQueue({ priority: cleverQueue.queues.Priorities.Standard, weight: 1 });
+
+    for (let index = 0; index < 4; index += 1) heavyQueue.enqueue(engine.createTask(() => undefined, { id: `heavy-${index}` }));
+    for (let index = 0; index < 2; index += 1) lightQueue.enqueue(engine.createTask(() => undefined, { id: `light-${index}` }));
+
+    engine.start();
+    const ids = await dequeueIds(engine, 6);
+
+    assert.deepEqual(ids, ["heavy-0", "heavy-1", "light-0", "heavy-2", "heavy-3", "light-1"]);
+    engine.stop();
+  });
+});

package/test/issues/00010-lifecycle-semantics.mjs

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import * as cleverQueue from "../../dist/index.js";
+
+function createDeferred() {
+  /** @type {(value?: unknown) => void} */
+  let resolve;
+  const promise = new Promise((resolver) => {
+    resolve = resolver;
+  });
+
+  return { promise, resolve };
+}
+
+describe("Issue #10 - lifecycle semantics", () => {
+  it("rejects queued tasks when the engine is stopped, while letting the in-flight task finish", async () => {
+    const blocker = createDeferred();
+    const engine = cleverQueue.createEngine({ bestEffortRunners: 1 });
+    const queue = engine.createQueue({ priority: cleverQueue.queues.Priorities.Standard, weight: 1 });
+
+    const firstTask = queue.enqueue(
+      engine.createTask(async () => {
+        await blocker.promise;
+        return "first";
+      }, {}),
+    );
+    const secondTask = queue.enqueue(engine.createTask(() => "second", {}));
+
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    engine.stop();
+    blocker.resolve();
+
+    assert.equal(await firstTask, "first");
+    await assert.rejects(secondTask, {
+      name: cleverQueue.queues.ErrorsList.QueueIsStopping.name,
+    });
+  });
+
+  it("rejects pending tasks immediately when a queue is stopped", async () => {
+    const engine = cleverQueue.createEngine({ bestEffortRunners: 1 });
+    const queue = engine.createQueue({ priority: cleverQueue.queues.Priorities.Standard, weight: 1 });
+    const pendingTask = queue.enqueue(engine.createTask(() => "never runs", {}));
+
+    queue.stop();
+
+    await assert.rejects(pendingTask, {
+      name: cleverQueue.queues.ErrorsList.QueueIsStopping.name,
+    });
+    engine.stop();
+  });
+
+  it("lets a runner finish its current task before stopping without starting the next one", async () => {
+    const blocker = createDeferred();
+    const engine = cleverQueue.createEngine({ autostart: false, bestEffortRunners: 1 });
+    const queue = engine.createQueue({ priority: cleverQueue.queues.Priorities.Standard, weight: 1 });
+    const runner = engine.runners[0];
+
+    const firstTask = queue.enqueue(
+      engine.createTask(async () => {
+        await blocker.promise;
+        return "first";
+      }, {}),
+    );
+    const secondTask = queue.enqueue(engine.createTask(() => "second", {}));
+
+    engine.start();
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    runner.stop();
+    blocker.resolve();
+
+    assert.equal(await firstTask, "first");
+    assert.equal(runner.statistics().status, "stopping");
+
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    assert.equal(queue.statistics().tasks, 1);
+
+    queue.stop();
+    await assert.rejects(secondTask, {
+      name: cleverQueue.queues.ErrorsList.QueueIsStopping.name,
+    });
+    engine.stop();
+  });
+
+  it("rejects new tasks after a queue has been stopped", async () => {
+    const engine = cleverQueue.createEngine({ bestEffortRunners: 1 });
+    const queue = engine.createQueue({ priority: cleverQueue.queues.Priorities.Standard, weight: 1 });
+
+    queue.stop();
+
+    await assert.rejects(
+      queue.enqueue(engine.createTask(() => "late", {})),
+      {
+        name: cleverQueue.queues.ErrorsList.QueueIsStopping.name,
+        message: cleverQueue.queues.ErrorsList.QueueIsStopping.message,
+      },
+    );
+
+    engine.stop();
+  });
+});

package/test/issues/00012-wording-cleanup.mjs

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import * as cleverQueue from "../../dist/index.js";
+
+describe("Issue #12 - wording and status cleanup", () => {
+  it("uses the normalized initializing status wording across runtime objects", () => {
+    const task = new cleverQueue.tasks.Task(() => undefined, { autostart: false });
+    assert.equal(task.statistics().status, "initializing");
+
+    const engine = cleverQueue.createEngine({ autostart: false, bestEffortRunners: 1 });
+    const queue = engine.createQueue({ autostart: false, priority: cleverQueue.queues.Priorities.Standard, weight: 1 });
+    const runner = engine.createRunner({ autostart: false, priority: cleverQueue.queues.Priorities.BestEffort });
+
+    assert.equal(engine.statistics().engine.status, "initializing");
+    assert.equal(queue.statistics().status, "initializing");
+    assert.equal(runner.statistics().status, "initializing");
+    engine.stop();
+  });
+
+  it("reports completed instead of runned after successful task execution", async () => {
+    const task = new cleverQueue.tasks.Task(() => "done", {});
+    task.resolver = () => {};
+    task.rejecter = () => {};
+
+    await task.run();
+
+    assert.equal(task.statistics().status, "completed");
+  });
+});

package/test/miscellaneous/test.mjs

@@ -8,27 +8,32 @@ const engineOptions = {
   logFunction: undefined,
 };
 
+function trackEnqueue(promises, queue, task) {
+  promises.push(queue.enqueue(task).catch(() => undefined));
+}
+
 describe("Scheduler Unit Tests", () => {
   it("Priority Test", () => {
+    const pending = [];
     const engine = cleverQueue.createEngine(engineOptions);
     const queue1 = engine.createQueue({
       name: "A",
       priority: cleverQueue.queues.Priorities.Absolute,
       weight: 50,
     });
-    for (let index = 0; index < 100; index++) queue1.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue1, engine.createTask(() => {}, {}));
     const queue2 = engine.createQueue({
       name: "B",
       priority: cleverQueue.queues.Priorities.Standard,
       weight: 50,
     });
-    for (let index = 0; index < 100; index++) queue2.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue2, engine.createTask(() => {}, {}));
     const queue3 = engine.createQueue({
       name: "C",
       priority: cleverQueue.queues.Priorities.BestEffort,
       weight: 50,
     });
-    for (let index = 0; index < 100; index++) queue3.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue3, engine.createTask(() => {}, {}));
 
     const engineStatistics = engine.statistics();
     assert.equal(engineStatistics.engine.queues, 3);
@@ -36,25 +41,26 @@ describe("Scheduler Unit Tests", () => {
   });
 
   it("Weighted Test", () => {
+    const pending = [];
     const engine = cleverQueue.createEngine(engineOptions);
     const queue1 = engine.createQueue({
       name: "A",
       priority: cleverQueue.queues.Priorities.Absolute,
       weight: 80,
     });
-    for (let index = 0; index < 100; index++) queue1.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue1, engine.createTask(() => {}, {}));
     const queue2 = engine.createQueue({
       name: "B",
       priority: cleverQueue.queues.Priorities.Absolute,
       weight: 50,
     });
-    for (let index = 0; index < 100; index++) queue2.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue2, engine.createTask(() => {}, {}));
     const queue3 = engine.createQueue({
       name: "C",
       priority: cleverQueue.queues.Priorities.Absolute,
       weight: 20,
     });
-    for (let index = 0; index < 100; index++) queue3.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue3, engine.createTask(() => {}, {}));
 
     const engineStatistics = engine.statistics();
     assert.equal(engineStatistics.engine.queues, 3);
@@ -62,6 +68,7 @@ describe("Scheduler Unit Tests", () => {
   });
 
   it("Combine Test", () => {
+    const pending = [];
     const engine = cleverQueue.createEngine(engineOptions);
 
     const queue1 = engine.createQueue({
@@ -69,21 +76,21 @@ describe("Scheduler Unit Tests", () => {
       priority: cleverQueue.queues.Priorities.Absolute,
       weight: 80,
     });
-    for (let index = 0; index < 100; index++) queue1.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue1, engine.createTask(() => {}, {}));
 
     const queue2 = engine.createQueue({
       name: "B - Standard - 50",
       priority: cleverQueue.queues.Priorities.Standard,
       weight: 50,
     });
-    for (let index = 0; index < 100; index++) queue2.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue2, engine.createTask(() => {}, {}));
 
     const queue3 = engine.createQueue({
       name: "C- Standard - 20",
       priority: cleverQueue.queues.Priorities.Standard,
       weight: 20,
     });
-    for (let index = 0; index < 100; index++) queue3.enqueue(engine.createTask(() => {}, {}));
+    for (let index = 0; index < 100; index++) trackEnqueue(pending, queue3, engine.createTask(() => {}, {}));
 
     const engineStatistics = engine.statistics();
     assert.equal(engineStatistics.engine.queues, 3);

package/test/units/engine.mjs

@@ -4,7 +4,7 @@ import { describe, it } from "node:test";
 import * as cleverQueue from "../../dist/index.js";
 
 describe("Engine Class Unit Tests", () => {
-  it("Successfull Initialisation without any option (use hardcoded default options)", () => {
+  it("Successful Initialisation without any option (use hardcoded default options)", () => {
     const engine = cleverQueue.createEngine();
     const statistics = engine.statistics();
     assert.equal(statistics.engine.runners, 1);
@@ -22,7 +22,7 @@ describe("Engine Class Unit Tests", () => {
     );
   });
 
-  it("Successfull Initialisation with 3 Runners", () => {
+  it("Successful Initialisation with 3 Runners", () => {
     const engineOptions = {
       bestEffortRunners: 3,
     };

package/test/units/queue.mjs

@@ -9,7 +9,7 @@ const engineOptions = {
 };
 
 describe("Queue Class Unit Tests", () => {
-  it("Successfull Initialisation without any option (use hardcoded default options)", () => {
+  it("Successful Initialisation without any option (use hardcoded default options)", () => {
     const engine = cleverQueue.createEngine();
     const statistics = engine.statistics();
     assert.equal(statistics.engine.runners, 1);
@@ -17,7 +17,7 @@ describe("Queue Class Unit Tests", () => {
     engine.stop();
   });
 
-  it("Successfull Initialisation", () => {
+  it("Successful Initialisation", () => {
     const engine = cleverQueue.createEngine(engineOptions);
     const queueOptions = {
       priority: cleverQueue.queues.Priorities.Standard,
@@ -45,7 +45,7 @@ describe("Queue Class Unit Tests", () => {
     engine.stop();
   });
 
-  it("Keeps the exported lowest weight constant at zero", () => {
-    assert.equal(cleverQueue.queues.Weights.Lowest, 0);
+  it("Keeps the exported lowest weight constant at one", () => {
+    assert.equal(cleverQueue.queues.Weights.Lowest, 1);
   });
 });

package/test/units/task.mjs

@@ -9,28 +9,29 @@ const engineOptions = {
 };
 
 const task = async (string_) => {
-  //  console.log(string_, "Start", new Date());
   await new Promise((resolve) => setTimeout(resolve, 2000));
-  //  console.log(string_, "End", new Date());
   return string_;
 };
 
 describe("Scheduler Unit Tests", () => {
-  it("Exception if function passed is not a function (but a result of an executed function)", () => {
+  it("Exception if function passed is not a function (but a result of an executed function)", async () => {
     const engine = cleverQueue.createEngine(engineOptions);
     const queue1 = engine.createQueue({
       name: "A",
       priority: cleverQueue.queues.Priorities.Absolute,
       weight: 50,
     });
-    assert.rejects(
-      async () => {
-        const myTask = engine.createTask(task("myTask"), {});
-        await queue1.enqueue(myTask);
-      },
-      { name: cleverQueue.tasks.ErrorsList.FunctionIsNotAFunction.name },
-    );
-    engine.stop();
+    try {
+      await assert.rejects(
+        async () => {
+          const myTask = engine.createTask(task("myTask"), {});
+          await queue1.enqueue(myTask);
+        },
+        { name: cleverQueue.tasks.ErrorsList.FunctionIsNotAFunction.name },
+      );
+    } finally {
+      engine.stop();
+    }
   });
 
   it("Priority Test", () => {
@@ -41,7 +42,7 @@ describe("Scheduler Unit Tests", () => {
       weight: 50,
     });
 
-    for (let index = 0; index < 8; index++) queue1.enqueue(engine.createTask(() => task("Task " + index), {}));
+    for (let index = 0; index < 8; index++) queue1.enqueue(engine.createTask(() => task(`Task ${index}`), {})).catch(() => undefined);
 
     const engineStatistics = engine.statistics();
     assert.equal(engineStatistics.engine.queues, 1);