From f7837a7820dda3001650f8b6c912d7bcda3efb81 Mon Sep 17 00:00:00 2001 From: devside Date: Wed, 7 Mar 2018 13:39:07 +0100 Subject: [PATCH 01/13] draft doc --- README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++--- package.json | 2 +- 2 files changed, 125 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 1098981..af7ac2c 100644 --- a/README.md +++ b/README.md @@ -3,25 +3,143 @@

- Declarative task sequencer for Javascript platforms + Declarative task sequencer for Javascript

- + Build Status - + Coverage Status - + NPM Version

- -## Installation +### Installation ```shell yarn add tasko npm install tasko ``` + +### Terminology + +Tasko is inspired by Behavior tree' control flow. It doesn't rely on a time-based execution (tick). + +### Task + +A **task** is an **object** created with a create-task function. + +#### Properties + +| Properties | Type | Détails | +| ---------- | -------- | ------------------------------------------------------------------------- | +| **name** | string | Task name | +| **run** | function | Called by the parent to run the task with optional spread params | +| **cancel** | function | Called by the parent to cancel the task, before or after running the task | + +#### Usage + +```js +/** + * Create a successful task + * + * @param {function} success - The callback to succeed with an optional param + * @param {function} fail - The callback to fail with an optional param + * @param {function} message - Send a message to the parent + * + * @returns {object} - A task + */ +const createSuccessfulTask = (success, fail, message) => ({ + name: 'success', + run(...params) { + message(`the task is running with params: ${JSON.stringify(params)}`) + success('success') + }, + cancel: () => { + // noop + }, +}) +``` + +### Decorator + +A **decorator** is a function which enhance the original task behavior. + +#### Usage + +```js +/** + * Makes a task always succeeds + * + * @param {function} createTask - original create-task + * + * @returns {function} - Enhance create-task + */ +const alwaysSucceed = createTask => (succeed, _, message) => { + const task = createTask(succeed, succeed, message) + + return { + ...task, + name: decorateName('alwaysSucceed', task.name), // @alwaysSucceed(task-name) + } +} +``` + +### Composition + +A **composite, or branch, task** runs other tasks + +#### Exit condition + +It determined how a composite task will succeeded or failed based on its children. + +* **selector**: this task immediately succeeds if a child has succeeded, fails if all its children have failed +* **sequence**: this task immediately fails if a child has failed, succeeds if all its children have succeeded +* **all**: this task runs all its children, it fails if a child has failed, succeeds otherwise. + +#### Execution mode + +It determined how a composite task should run its children. + +* **serie** +* **parallel** + +#### Usage + +```js +import { serieSequence, parallelAll } from 'tasko/composite' +import { noop } from 'tasko/util' + +const think = (success, fail, message) => ({ + name: 'think', + run() { + message(`I'm thinking`) + success('Done') + }, + cancel: noop, +}) + +const thinkings = serieSequence(think, think) + +thinkings( + () => console.log('Process succeeded !'), + () => console.log('Process failed !'), + (message, taskName) => console.log(taskName + ':', message), +) +``` + +Logs + +``` +think: I'm thinking +think: Done +think: I'm thinking +think: Done +Process succeeded ! +``` + +### More examples diff --git a/package.json b/package.json index 12f9401..61a742e 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,7 @@ "build:es": "rimraf es && BABEL_ENV=es babel src --ignore=__ --out-dir es", "check:repository": "test -z \"$(git status --porcelain)\"", "ci": "npm-run-all -p format test:coverage build -s check:repository", - "format": "prettier --config .prettierrc --write 'src/**/*.js'", + "format": "prettier --config .prettierrc --write 'src/**/*.js' '**/*.md'", "test": "BABEL_ENV=test jest", "test:coverage": "yarn test --coverage" } From 1e54536e7ed83e240b72cc79924842545ee30d62 Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 19 Mar 2018 17:35:21 +0100 Subject: [PATCH 02/13] Update README.md --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index af7ac2c..5cccaa7 100644 --- a/README.md +++ b/README.md @@ -95,18 +95,18 @@ A **composite, or branch, task** runs other tasks #### Exit condition -It determined how a composite task will succeeded or failed based on its children. +It determined how a composite task will succeed or fail based on its children. * **selector**: this task immediately succeeds if a child has succeeded, fails if all its children have failed * **sequence**: this task immediately fails if a child has failed, succeeds if all its children have succeeded -* **all**: this task runs all its children, it fails if a child has failed, succeeds otherwise. +* **all**: this task runs all its children, it fails if a child has failed, succeeds otherwise #### Execution mode It determined how a composite task should run its children. -* **serie** -* **parallel** +* **serie**: one task after another +* **parallel**: only works if the tasks run in a microtask, serie otherwise #### Usage From 0c62d71d91ea97a5e998e444e71b6e20d602c8f8 Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 19 Mar 2018 17:36:48 +0100 Subject: [PATCH 03/13] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5cccaa7..e157cd4 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ It determined how a composite task will succeed or fail based on its children. It determined how a composite task should run its children. * **serie**: one task after another -* **parallel**: only works if the tasks run in a microtask, serie otherwise +* **parallel**: only works if the tasks run asynchronously (microtasks), serie otherwise #### Usage From c6cfe03b6234e93cb00f6f18ea4d385486319a9e Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 19 Mar 2018 17:46:10 +0100 Subject: [PATCH 04/13] Update README.md --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index e157cd4..f69610a 100644 --- a/README.md +++ b/README.md @@ -108,6 +108,24 @@ It determined how a composite task should run its children. * **serie**: one task after another * **parallel**: only works if the tasks run asynchronously (microtasks), serie otherwise +#### Api + +```js +import { + serieSequence, + serieSelector, + serieAll, + parallelSequence, + parallelSelector, + parallelAll +} from 'tasko/composite' +``` + +composite(...createTasks) + +**createTasks**: spread list of createTasks to compose +**Returns**: a createTask + #### Usage ```js From 4813e72d60b9d00e78bea3fd136dfb724bb1ec81 Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 19 Mar 2018 17:46:34 +0100 Subject: [PATCH 05/13] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f69610a..3cb2163 100644 --- a/README.md +++ b/README.md @@ -123,7 +123,7 @@ import { composite(...createTasks) -**createTasks**: spread list of createTasks to compose +**createTasks**: spread list of createTasks to compose
**Returns**: a createTask #### Usage From 3a498648a2bc3b7d140c592159f3e150916c0fd2 Mon Sep 17 00:00:00 2001 From: DevSide Date: Sun, 24 Mar 2019 23:57:08 +0100 Subject: [PATCH 06/13] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3cb2163..8c73a90 100644 --- a/README.md +++ b/README.md @@ -89,9 +89,9 @@ const alwaysSucceed = createTask => (succeed, _, message) => { } ``` -### Composition +### Composite -A **composite, or branch, task** runs other tasks +A **composite (or branch)** is a task which orchestrates other tasks #### Exit condition From 9a5eeafb743c4595b3e01f4a0f824846e4fc962d Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 25 Mar 2019 00:23:50 +0100 Subject: [PATCH 07/13] Update README.md --- README.md | 62 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8c73a90..3fd38db 100644 --- a/README.md +++ b/README.md @@ -29,9 +29,25 @@ npm install tasko Tasko is inspired by Behavior tree' control flow. It doesn't rely on a time-based execution (tick). -### Task +### Task creators -A **task** is an **object** created with a create-task function. +A task creator is a function that creates a task. + +#### Parameters + +| Properties | Type | Détails | +| ---------- | -------- | ------------------------------------------------------------------------- | +| **success** | function | | +| **fail** | function | | +| **send** | function | | + +#### Returns + +A Task. + +### Tasks + +A task is an object which can be run a process and/or be cancelled. #### Properties @@ -53,10 +69,10 @@ A **task** is an **object** created with a create-task function. * * @returns {object} - A task */ -const createSuccessfulTask = (success, fail, message) => ({ +const createSuccessfulTask = (success, fail, send) => ({ name: 'success', run(...params) { - message(`the task is running with params: ${JSON.stringify(params)}`) + send(`the task is running with params: ${JSON.stringify(params)}`) success('success') }, cancel: () => { @@ -65,10 +81,18 @@ const createSuccessfulTask = (success, fail, message) => ({ }) ``` -### Decorator +### Decorators A **decorator** is a function which enhance the original task behavior. +#### Parameter + +A task creator to enhance. + +#### Returns + +A task creator enhanced. + #### Usage ```js @@ -79,8 +103,8 @@ A **decorator** is a function which enhance the original task behavior. * * @returns {function} - Enhance create-task */ -const alwaysSucceed = createTask => (succeed, _, message) => { - const task = createTask(succeed, succeed, message) +const alwaysSucceed = taskCreator => (succeed, _, send) => { + const task = taskCreator(succeed, succeed, send) return { ...task, @@ -89,7 +113,9 @@ const alwaysSucceed = createTask => (succeed, _, message) => { } ``` -### Composite +See existing decoractors that you can use import https://github.com/DevSide/tasko/blob/master/src/decorator.js + +### Composites A **composite (or branch)** is a task which orchestrates other tasks @@ -106,7 +132,15 @@ It determined how a composite task will succeed or fail based on its children. It determined how a composite task should run its children. * **serie**: one task after another -* **parallel**: only works if the tasks run asynchronously (microtasks), serie otherwise +* **parallel**: only works if the tasks run asynchronously, serie otherwise + +#### Parameters + +A (spread) list of task creators to execute. + +#### Returns + +A task creators. #### Api @@ -121,21 +155,16 @@ import { } from 'tasko/composite' ``` -composite(...createTasks) - -**createTasks**: spread list of createTasks to compose
-**Returns**: a createTask - #### Usage ```js import { serieSequence, parallelAll } from 'tasko/composite' import { noop } from 'tasko/util' -const think = (success, fail, message) => ({ +const think = (success, fail, send) => ({ name: 'think', run() { - message(`I'm thinking`) + send(`I'm thinking`) success('Done') }, cancel: noop, @@ -148,6 +177,7 @@ thinkings( () => console.log('Process failed !'), (message, taskName) => console.log(taskName + ':', message), ) + ``` Logs From a7ce679ff655c63e224073213021923090842bfd Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 25 Mar 2019 00:29:45 +0100 Subject: [PATCH 08/13] Update README.md --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 3fd38db..9d8847f 100644 --- a/README.md +++ b/README.md @@ -18,14 +18,14 @@

-### Installation +## Installation ```shell yarn add tasko npm install tasko ``` -### Terminology +## Terminology Tasko is inspired by Behavior tree' control flow. It doesn't rely on a time-based execution (tick). @@ -83,7 +83,7 @@ const createSuccessfulTask = (success, fail, send) => ({ ### Decorators -A **decorator** is a function which enhance the original task behavior. +A **decorator** is a function which enhances the original task behavior. #### Parameter @@ -99,9 +99,9 @@ A task creator enhanced. /** * Makes a task always succeeds * - * @param {function} createTask - original create-task + * @param {function} taskCreator - task creator to enhance * - * @returns {function} - Enhance create-task + * @returns {function} - Enhanced task creator */ const alwaysSucceed = taskCreator => (succeed, _, send) => { const task = taskCreator(succeed, succeed, send) @@ -117,7 +117,7 @@ See existing decoractors that you can use import https://github.com/DevSide/task ### Composites -A **composite (or branch)** is a task which orchestrates other tasks +A **composite (or branch)** is a task which orchestrates other tasks with an execution mode and an exit condition. #### Exit condition @@ -142,7 +142,7 @@ A (spread) list of task creators to execute. A task creators. -#### Api +#### Available composites ```js import { From faf76749e7c17fe3d4d96de207511f04c4a15536 Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 25 Mar 2019 00:39:36 +0100 Subject: [PATCH 09/13] Update README.md --- README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9d8847f..da646b1 100644 --- a/README.md +++ b/README.md @@ -35,11 +35,15 @@ A task creator is a function that creates a task. #### Parameters -| Properties | Type | Détails | -| ---------- | -------- | ------------------------------------------------------------------------- | -| **success** | function | | -| **fail** | function | | -| **send** | function | | +All those functions notify +| Properties | Type | Details | +| ------------- | -------- | ------------------------------------------------------------------------- | +| **success** | function | A callback function to notify the parent the task succeeded. | +| | | It takes an optional paramater to be propagated. | +| **fail** | function | A callback function to notify the parent the task failed. | +| | | It takes an optional paramater to be propagated. | +| **send** | function | A function to send something to the parent. | +| | | It takes an required paramater to be propagated. | #### Returns @@ -51,7 +55,7 @@ A task is an object which can be run a process and/or be cancelled. #### Properties -| Properties | Type | Détails | +| Properties | Type | Details | | ---------- | -------- | ------------------------------------------------------------------------- | | **name** | string | Task name | | **run** | function | Called by the parent to run the task with optional spread params | From 0289429a9ef20cdf5598f7e04eb5a3d2bd7c2ed1 Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 25 Mar 2019 00:40:42 +0100 Subject: [PATCH 10/13] Update README.md --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index da646b1..a405067 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,6 @@ A task creator is a function that creates a task. #### Parameters -All those functions notify | Properties | Type | Details | | ------------- | -------- | ------------------------------------------------------------------------- | | **success** | function | A callback function to notify the parent the task succeeded. | From f319c71c245ff08ccff5514b6e70a7a4b522e027 Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 25 Mar 2019 00:43:12 +0100 Subject: [PATCH 11/13] Update README.md --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a405067..21194fb 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,14 @@ See existing decoractors that you can use import https://github.com/DevSide/task A **composite (or branch)** is a task which orchestrates other tasks with an execution mode and an exit condition. -#### Exit condition +#### Execution modes + +It determined how a composite task should run its children. + +* **serie**: one task after another +* **parallel**: only works if the tasks run asynchronously, serie otherwise + +#### Exit conditions It determined how a composite task will succeed or fail based on its children. @@ -130,14 +137,7 @@ It determined how a composite task will succeed or fail based on its children. * **sequence**: this task immediately fails if a child has failed, succeeds if all its children have succeeded * **all**: this task runs all its children, it fails if a child has failed, succeeds otherwise -#### Execution mode - -It determined how a composite task should run its children. - -* **serie**: one task after another -* **parallel**: only works if the tasks run asynchronously, serie otherwise - -#### Parameters +#### Parameter A (spread) list of task creators to execute. From 5c2ff6328801252700cb1656359cf3debe029211 Mon Sep 17 00:00:00 2001 From: DevSide Date: Mon, 25 Mar 2019 00:50:46 +0100 Subject: [PATCH 12/13] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 21194fb..fc6e3b0 100644 --- a/README.md +++ b/README.md @@ -161,7 +161,7 @@ import { #### Usage ```js -import { serieSequence, parallelAll } from 'tasko/composite' +import { serieSequence } from 'tasko/composite' import { noop } from 'tasko/util' const think = (success, fail, send) => ({ From 87fbcc2076f2e2730bbf4868b661cb25496cfc5e Mon Sep 17 00:00:00 2001 From: Thomas Triau Date: Mon, 25 Mar 2019 00:54:25 +0100 Subject: [PATCH 13/13] format --- README.md | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index fc6e3b0..cf55be1 100644 --- a/README.md +++ b/README.md @@ -35,14 +35,14 @@ A task creator is a function that creates a task. #### Parameters -| Properties | Type | Details | -| ------------- | -------- | ------------------------------------------------------------------------- | -| **success** | function | A callback function to notify the parent the task succeeded. | -| | | It takes an optional paramater to be propagated. | -| **fail** | function | A callback function to notify the parent the task failed. | -| | | It takes an optional paramater to be propagated. | -| **send** | function | A function to send something to the parent. | -| | | It takes an required paramater to be propagated. | +| Properties | Type | Details | +| ----------- | -------- | ------------------------------------------------------------ | +| **success** | function | A callback function to notify the parent the task succeeded. | +| | | It takes an optional paramater to be propagated. | +| **fail** | function | A callback function to notify the parent the task failed. | +| | | It takes an optional paramater to be propagated. | +| **send** | function | A function to send something to the parent. | +| | | It takes an required paramater to be propagated. | #### Returns @@ -148,13 +148,13 @@ A task creators. #### Available composites ```js -import { - serieSequence, - serieSelector, - serieAll, - parallelSequence, - parallelSelector, - parallelAll +import { + serieSequence, + serieSelector, + serieAll, + parallelSequence, + parallelSelector, + parallelAll, } from 'tasko/composite' ``` @@ -180,7 +180,6 @@ thinkings( () => console.log('Process failed !'), (message, taskName) => console.log(taskName + ':', message), ) - ``` Logs