@guanghechen/task 2.0.0 → 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present guanghechen (https://github.com/guanghechen)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -49,7 +49,8 @@
 </header>
 <br/>
 
-Atomic and resumable tasks implementation with observable status tracking.
+Atomic and resumable tasks implementation with observable status tracking. Provides two task types:
+`AtomicTask` for one-shot operations and `ResumableTask` for pausable/resumable operations.
 
 ## Install
 
@@ -67,5 +68,124 @@ Atomic and resumable tasks implementation with observable status tracking.
 
 ## Usage
 
+### AtomicTask
+
+For tasks that run to completion without pause/resume support:
+
+```typescript
+import { AtomicTask, TaskStatusEnum, TaskStrategyEnum } from '@guanghechen/task'
+import { Subscriber } from '@guanghechen/subscriber'
+
+class DownloadTask extends AtomicTask {
+  private readonly url: string
+
+  constructor(url: string) {
+    super('download-task', TaskStrategyEnum.ABORT_ON_ERROR)
+    this.url = url
+  }
+
+  protected async run(): Promise<void> {
+    // Perform the download operation
+    console.log(`Downloading from ${this.url}`)
+    await fetch(this.url)
+    console.log('Download complete')
+  }
+}
+
+const task = new DownloadTask('https://example.com/file')
+
+// Subscribe to status changes
+const subscriber = new Subscriber({
+  onNext: (status) => {
+    console.log('Status:', TaskStatusEnum[status])
+  }
+})
+task.status.subscribe(subscriber)
+
+// Start the task
+await task.start()
+
+// Or run to completion
+await task.complete()
+
+// Check for errors
+if (task.errors.length > 0) {
+  console.error('Task failed:', task.errors)
+}
+```
+
+### ResumableTask
+
+For tasks that can be paused and resumed:
+
+```typescript
+import { ResumableTask, TaskStatusEnum, TaskStrategyEnum } from '@guanghechen/task'
+
+class BatchProcessTask extends ResumableTask {
+  private readonly items: string[]
+
+  constructor(items: string[]) {
+    super('batch-process', TaskStrategyEnum.CONTINUE_ON_ERROR, 100) // 100ms poll interval
+    this.items = items
+  }
+
+  protected *run(): IterableIterator<Promise<void>> {
+    for (const item of this.items) {
+      yield this.processItem(item)
+    }
+  }
+
+  private async processItem(item: string): Promise<void> {
+    console.log(`Processing: ${item}`)
+    await new Promise(resolve => setTimeout(resolve, 500))
+  }
+}
+
+const task = new BatchProcessTask(['item1', 'item2', 'item3'])
+
+// Start the task
+await task.start()
+
+// Pause after some time
+setTimeout(async () => {
+  await task.pause()
+  console.log('Task paused')
+
+  // Resume later
+  setTimeout(async () => {
+    await task.resume()
+    console.log('Task resumed')
+  }, 2000)
+}, 1000)
+```
+
+### Task Status
+
+Tasks have observable status with the following states:
+
+| Status               | Description                          |
+| :------------------: | :----------------------------------: |
+| `PENDING`            | Task not started                     |
+| `RUNNING`            | Task is running                      |
+| `SUSPENDED`          | Task is paused (ResumableTask only)  |
+| `CANCELLED`          | Task was cancelled                   |
+| `FAILED`             | Task failed with errors              |
+| `COMPLETED`          | Task completed successfully          |
+| `ATTEMPT_SUSPENDING` | Attempting to pause                  |
+| `ATTEMPT_RESUMING`   | Attempting to resume                 |
+| `ATTEMPT_CANCELING`  | Attempting to cancel                 |
+| `ATTEMPT_COMPLETING` | Attempting to complete               |
+
+### Task Strategy
+
+| Strategy            | Description                                    |
+| :-----------------: | :--------------------------------------------: |
+| `ABORT_ON_ERROR`    | Stop task execution when an error occurs       |
+| `CONTINUE_ON_ERROR` | Continue execution despite errors              |
+
+## Reference
+
+- [homepage][homepage]
+
 [homepage]:
-  https://github.com/guanghechen/sora/tree/@guanghechen/task@2.0.0/packages/task#readme
+  https://github.com/guanghechen/sora/tree/@guanghechen/task@2.0.0/packages/task#readme

package/lib/cjs/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var observable = require('@guanghechen/observable');
-var error_types = require('@guanghechen/error.types');
+var types = require('@guanghechen/types');
 
 exports.TaskStrategyEnum = void 0;
 (function (TaskStrategyEnum) {
@@ -128,7 +128,7 @@ class AtomicTask {
                 .catch(error => {
                 const soraError = {
                     from: this.name,
-                    level: error_types.ErrorLevelEnum.ERROR,
+                    level: types.ErrorLevelEnum.ERROR,
                     details: error,
                 };
                 this._errors.push(soraError);
@@ -235,7 +235,7 @@ class ResumableTask {
             catch (error) {
                 const soraError = {
                     from: this.name,
-                    level: error_types.ErrorLevelEnum.ERROR,
+                    level: types.ErrorLevelEnum.ERROR,
                     details: error,
                 };
                 this._errors.push(soraError);
@@ -253,7 +253,7 @@ class ResumableTask {
         if (status.alive) {
             const soraError = {
                 from: this.name,
-                level: error_types.ErrorLevelEnum.ERROR,
+                level: types.ErrorLevelEnum.ERROR,
                 details: new RangeError('The task is not terminated.'),
             };
             this._errors.push(soraError);
@@ -284,7 +284,7 @@ class ResumableTask {
             this._step = undefined;
             const soraError = {
                 from: this.name,
-                level: error_types.ErrorLevelEnum.ERROR,
+                level: types.ErrorLevelEnum.ERROR,
                 details: error,
             };
             this._errors.push(soraError);
@@ -299,8 +299,21 @@ class ResumableTask {
         }
     }
     async _queueStep() {
-        await new Promise(resolve => setTimeout(resolve, this._pollInterval));
-        await this._launchStep();
+        try {
+            await new Promise(resolve => setTimeout(resolve, this._pollInterval));
+            await this._launchStep();
+        }
+        catch (error) {
+            if (this.status.terminated)
+                return;
+            const soraError = {
+                from: this.name,
+                level: types.ErrorLevelEnum.ERROR,
+                details: error,
+            };
+            this._errors.push(soraError);
+            this.status.next(exports.TaskStatusEnum.FAILED, { strict: false });
+        }
     }
 }
 

package/lib/esm/index.mjs

@@ -1,5 +1,5 @@
 import { Observable } from '@guanghechen/observable';
-import { ErrorLevelEnum } from '@guanghechen/error.types';
+import { ErrorLevelEnum } from '@guanghechen/types';
 
 var TaskStrategyEnum;
 (function (TaskStrategyEnum) {
@@ -297,8 +297,21 @@ class ResumableTask {
         }
     }
     async _queueStep() {
-        await new Promise(resolve => setTimeout(resolve, this._pollInterval));
-        await this._launchStep();
+        try {
+            await new Promise(resolve => setTimeout(resolve, this._pollInterval));
+            await this._launchStep();
+        }
+        catch (error) {
+            if (this.status.terminated)
+                return;
+            const soraError = {
+                from: this.name,
+                level: ErrorLevelEnum.ERROR,
+                details: error,
+            };
+            this._errors.push(soraError);
+            this.status.next(TaskStatusEnum.FAILED, { strict: false });
+        }
     }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/task",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Atomic and resumable tasks",
   "author": {
     "name": "guanghechen",
@@ -8,17 +8,17 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/task@1.0.6",
+    "url": "https://github.com/guanghechen/sora/tree/@guanghechen/task@2.0.0",
     "directory": "packages/task"
   },
-  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/task@1.0.6/packages/task#readme",
+  "homepage": "https://github.com/guanghechen/sora/tree/@guanghechen/task@2.0.0/packages/task#readme",
   "type": "module",
   "exports": {
     ".": {
+      "types": "./lib/types/index.d.ts",
       "source": "./src/index.ts",
       "import": "./lib/esm/index.mjs",
-      "require": "./lib/cjs/index.cjs",
-      "types": "./lib/types/index.d.ts"
+      "require": "./lib/cjs/index.cjs"
     }
   },
   "source": "./src/index.ts",
@@ -26,13 +26,6 @@
   "module": "./lib/esm/index.mjs",
   "types": "./lib/types/index.d.ts",
   "license": "MIT",
-  "scripts": {
-    "build": "rollup -c ../../rollup.config.mjs",
-    "clean": "rimraf lib",
-    "test": "vitest run --config ../../vitest.config.ts",
-    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
-    "test:update": "vitest run --config ../../vitest.config.ts -u"
-  },
   "files": [
     "lib/",
     "!lib/**/*.map",
@@ -42,8 +35,14 @@
     "README.md"
   ],
   "dependencies": {
-    "@guanghechen/error.types": "^2.0.0",
-    "@guanghechen/observable": "^7.0.0"
+    "@guanghechen/observable": "^7.0.1",
+    "@guanghechen/types": "^2.0.1"
   },
-  "gitHead": "12990a720b31d50d217e2e17a6191256dc94eda6"
-}
+  "scripts": {
+    "build": "rollup -c ../../rollup.config.mjs",
+    "clean": "rimraf lib",
+    "test": "vitest run --config ../../vitest.config.ts",
+    "test:coverage": "vitest run --config ../../vitest.config.ts --coverage",
+    "test:update": "vitest run --config ../../vitest.config.ts -u"
+  }
+}