feat(task): add start, success & failure methods (#8061)

* feat(task): add start, success & failure methods

Allow managing the task manually instead of using `.run()` and `.runInside()`.

@vates/task/.USAGE.md

@@ -49,6 +49,15 @@ const result = await task.runInside(fn)
 // if fn rejects, the task will be marked as failed
 // if fn resolves, the task will be marked as succeeded
 const result = await task.run(fn)
+
+// manually starts the task
+task.start()
+
+// manually finishes the task in success state
+task.success(result)
+
+// manually finishes the task in failure state
+task.failure(error)
 ```
 
 Inside a task:

@vates/task/README.md

@@ -65,6 +65,15 @@ const result = await task.runInside(fn)
 // if fn rejects, the task will be marked as failed
 // if fn resolves, the task will be marked as succeeded
 const result = await task.run(fn)
+
+// manually starts the task
+task.start()
+
+// manually finishes the task in success state
+task.success(result)
+
+// manually finishes the task in failure state
+task.failure(error)
 ```
 
 Inside a task:

@vates/task/index.js

@@ -132,9 +132,13 @@ class Task {
   #end(status, result) {
     assert.equal(this.#status, PENDING)
 
-    this.#status = status
     this.#emit('end', { status, result })
     this.#onProgress = alreadyEnded
+    this.#status = status
+  }
+
+  failure(error) {
+    this.#end(FAILURE, error)
   }
 
   info(message, data) {
@@ -142,10 +146,8 @@ class Task {
   }
 
   #maybeStart() {
-    const startData = this.#startData
-    if (startData !== undefined) {
-      this.#startData = undefined
-      this.#emit('start', startData)
+    if (this.#startData !== undefined) {
+      this.start()
     }
   }
 
@@ -181,6 +183,18 @@ class Task {
     this.#emit('property', { name, value })
   }
 
+  start() {
+    const startData = this.#startData
+    assert.notEqual(startData, undefined, 'task has already started')
+
+    this.#startData = undefined
+    this.#emit('start', startData)
+  }
+
+  success(result) {
+    this.#end(SUCCESS, result)
+  }
+
   warning(message, data) {
     assert.equal(this.status, PENDING)
 

@vates/task/index.test.js

@@ -145,6 +145,36 @@ describe('Task', function () {
     })
   })
 
+  describe('#failure()', function () {
+    const error = new Error()
+
+    it('throws if the task has not started yet', function () {
+      const task = createTask()
+
+      assert.throws(() => task.failure(error), { message: 'task has not started yet' })
+    })
+
+    it('throws if the task has already finished', function () {
+      const task = createTask()
+      task.start()
+      task.success()
+
+      assert.throws(() => task.failure(error), { code: 'ERR_ASSERTION' })
+    })
+
+    it('finishes the task and mark it as failed', function () {
+      const task = createTask()
+      task.start()
+      task.failure(error)
+
+      assertEvent(task, {
+        status: 'failure',
+        result: error,
+        type: 'end',
+      })
+    })
+  })
+
   describe('.info()', function () {
     it('does nothing when run outside a task', function () {
       Task.info('foo')
@@ -244,6 +274,52 @@ describe('Task', function () {
     })
   })
 
+  describe('#start', function () {
+    it('starts the task', function () {
+      const task = createTask()
+      task.start()
+
+      assertEvent(task, { type: 'start' })
+    })
+
+    it('throws when the task has already started', function () {
+      const task = createTask()
+      task.start()
+
+      assert.throws(() => task.start(), { message: 'task has already started' })
+    })
+  })
+
+  describe('#success()', function () {
+    const result = {}
+
+    it('throws if the task has not started yet', function () {
+      const task = createTask()
+
+      assert.throws(() => task.success(result), { message: 'task has not started yet' })
+    })
+
+    it('throws if the task has already finished', function () {
+      const task = createTask()
+      task.start()
+      task.success()
+
+      assert.throws(() => task.success(result), { code: 'ERR_ASSERTION' })
+    })
+
+    it('finishes the task and mark it as successful', function () {
+      const task = createTask()
+      task.start()
+      task.success(result)
+
+      assertEvent(task, {
+        status: 'success',
+        result,
+        type: 'end',
+      })
+    })
+  })
+
   describe('.warning()', function () {
     it('does nothing when run outside a task', function () {
       Task.warning('foo')

CHANGELOG.unreleased.md

@@ -43,6 +43,8 @@
 
 <!--packages-start-->
 
+
+- @vates/task minor
 - @xen-orchestra/backups patch
 - @xen-orchestra/fs minor
 - @xen-orchestra/log minor