Merge pull request #36 from sontx/task-icon

Task and task group icon

Author: sontx

docs/task/task-handler.md

@@ -54,6 +54,7 @@ A task handler should have the following structure:
 - `name`: The name of the task, we'll use the file name or package name as the task name if not defined. This is optional.
 - `description`: A brief description of the task, this is optional.
 - `version`: The version of the task, we'll use the package version if not defined. This is optional.
+- `icon`: The icon url of the task, this is optional.
 - `parameters`: An object that describes the input parameters of the task for showing help, set null if the task doesn't have parameters. This is optional.
 - `output`: An object that describes the output of the task for showing help, set null if the task doesn't have output. This is optional.
 - `handle`: The function that executes the task. This is required.
@@ -63,6 +64,7 @@ There are alternative ways to define those fields by using these corresponding d
 - `@Name`: The name of the task.
 - `@Description`: A brief description of the task.
 - `@Version`: The version of the task.
+- `@Icon`: The icon url of the task.
 - `@Parameters`: An object that describes the input parameters of the task for showing help. No value or null means the task doesn't have parameters.
 - `@Output`: An object that describes the output of the task for showing help. No value or null means the task doesn't have output.
 
@@ -219,9 +221,10 @@ For example, the handler for `Task1Handler` will be `package:my-group:task1`.
 
 The group information will be obtained from the package.json:
 
-- `name`: The name of the task group.
-- `description`: A brief description of the task group.
-- `version`: The version of the task group.
-- `author`: The author of the task group.
+- `name`: The name of the task group. Corresponds to the package name.
+- `description`: A brief description of the task group. Corresponds to the package description.
+- `version`: The version of the task group. Corresponds to the package version.
+- `icon`: The icon url of the task group. Corresponds to the package.json `letrun.icon` field.
+- `author`: The author of the task group. Corresponds to the package author.
 
 > We recommend you use scoped package and name the package with `@letrun-task-` prefix.

icons/catch.svg

@@ -22,20 +22,73 @@ export const SYSTEM_TASK_GROUP: TaskGroup = {
 export interface TaskGroup {
   /**
    * The name of the task group.
+   * This name should be unique across all task groups.
+   * You can define group's name in the name field of package.json.
+   *
+   * @example
+   * ```json
+   * {
+   *   "name": "my-task-group"
+   *   ...
+   * }
+   * ```
    */
   name: string;
   /**
    * A brief description of the task group.
+   * This description will be shown in the help output.
+   * You can define group's description in the description field of package.json.
+   *
+   * @example
+   * ```json
+   * {
+   *   "description": "This is an awesome task group"
+   *   ...
+   * }
+   * ```
    */
   description?: string;
   /**
    * The version of the task group.
+   * You can define group's version in the version field of package.json.
+   *
+   * @example
+   * ```json
+   * {
+   *    "version": "1.0.0"
+   *    ...
+   * }
+   * ```
    */
   version?: string;
   /**
    * The author of the task group.
+   * You can define group's author in the author field of package.json.
+   *
+   * @example
+   * ```json
+   * {
+   *   "author": "John Doe"
+   *   ...
+   * }
+   * ```
    */
   author?: string;
+  /**
+   * The icon url of the task group.
+   * You can define group's icon in the letrun.icon field of package.json.
+   *
+   * @example
+   * ```json
+   * {
+   *   "letrun": {
+   *     "icon": "https://example.com/icon.png"
+   *   }
+   *   ...
+   * }
+   * ```
+   */
+  icon?: string;
   /**
    * The tasks that belong to this group. This map contains the name of the task as the key and the task handler as the value.
    */
@@ -57,6 +110,7 @@ export interface TaskGroupMetadata {
   description?: string;
   version?: string;
   author?: string;
+  icon?: string;
   type?: 'package' | 'script';
   tasks: TaskMetadata[];
 }

icons/delay.svg

@@ -22,12 +22,19 @@ export interface TaskHandlerInput {
  * Keeps the logic stateless because it will be recalled multiple times with different task data.
  */
 export interface TaskHandler<T = any> {
-  /** The name of the task handler. */
+  /**
+   * The name of the task handler.
+   * This name should be unique across all task handlers of the same {@link TaskGroup}.
+   */
   name?: string;
   /** The version of the task handler. */
   version?: string;
   /** Optional description of the task handler. */
   description?: string;
+  /**
+   * The icon url of the task handler.
+   */
+  icon?: string;
   /**
    *  An object that describes the input parameters of the task for showing help.
    *  If the task does not require any input, set this to null.
@@ -58,6 +65,7 @@ export interface TaskMetadata {
   name: string;
   version?: string;
   description?: string;
+  icon?: string;
   parameters?: Joi.Description | null;
   output?: Joi.Description | null;
 }

icons/for.svg

@@ -50,6 +50,22 @@ export function Description(value: string) {
   return injectFieldDecorator('description', value);
 }
 
+/**
+ * A decorator that injects the icon field to a {@link TaskHandler}. See {@link TaskHandler.icon}.
+ * @param value
+ * @constructor
+ *
+ * @example
+ * ```ts
+ * @Icon('https://example.com/icon.png')
+ * class MyTaskHandler implements TaskHandler {
+ * }
+ * ```
+ */
+export function Icon(value: string) {
+  return injectFieldDecorator('icon', value);
+}
+
 /**
  * A decorator that injects the parameters field to a {@link TaskHandler}. See {@link TaskHandler.parameters}.
  * @param value - task handler parameters. If value is not provided, the parameters field will be set to null (no parameters are required).

icons/http.svg

@@ -1,4 +1,4 @@
-import { Description, Name, Output, Parameters, Version } from '@src/decorator/task-handler';
+import { Description, Icon, Name, Output, Parameters, Version } from '@src/decorator/task-handler';
 import Joi from 'joi';
 
 describe('TaskHandler Decorators', () => {
@@ -100,6 +100,7 @@ describe('TaskHandler Decorators', () => {
     @Name('my-task-handler')
     @Version('1.0.0')
     @Description('This is a task handler')
+    @Icon('https://example.com/icon.png')
     @Parameters(Joi.object({ name: Joi.string().required() }))
     @Output(Joi.object({ value: Joi.string().required() }))
     class MyTaskHandler extends BaseClass {}
@@ -121,13 +122,23 @@ describe('TaskHandler Decorators', () => {
     @Description('This is a task handler')
     @Parameters(schema)
     @Output(outputSchema)
+    @Icon('https://example.com/icon.png')
     class MyTaskHandler {}
 
     const instance = new MyTaskHandler();
     expect((instance as any).name).toBe('my-task-handler');
     expect((instance as any).version).toBe('1.0.0');
     expect((instance as any).description).toBe('This is a task handler');
+    expect((instance as any).icon).toBe('https://example.com/icon.png');
     expect((instance as any).parameters).toEqual(schema.describe());
     expect((instance as any).output).toEqual(outputSchema.describe());
   });
+
+  it('should inject icon field into TaskHandler', () => {
+    @Icon('https://example.com/icon.png')
+    class MyTaskHandler {}
+
+    const instance = new MyTaskHandler();
+    expect((instance as any).icon).toBe('https://example.com/icon.png');
+  });
 });

icons/if.svg

@@ -2,6 +2,7 @@ import {
   countTasks,
   Description,
   getTasksByStatus,
+  Icon,
   isWorkflowTaskDefsEmpty,
   Name,
   Output,
@@ -49,6 +50,7 @@ const OutputSchema = Joi.object({
 
 @Name('catch')
 @Description('Handles errors during task execution')
+@Icon('https://raw.githubusercontent.com/sontx/letrun/main/icons/catch.svg')
 @Parameters(Schema)
 @Output(OutputSchema)
 export class CatchTaskHandler implements TaskHandler {

icons/iterate.svg

@@ -1,4 +1,4 @@
-import { delayMs, Description, Name, Output, Parameters, validateParameters } from '@letrun/core';
+import { delayMs, Description, Icon, Name, Output, Parameters, validateParameters } from '@letrun/core';
 import { TaskHandler, TaskHandlerInput } from '@letrun/common';
 import Joi from 'joi';
 import ms from 'ms';
@@ -19,6 +19,7 @@ const OutputSchema = Joi.any().description('The "data" field from the input para
 
 @Name('delay')
 @Description('Delays the execution of the workflow for a specified amount of time')
+@Icon('https://raw.githubusercontent.com/sontx/letrun/main/icons/delay.svg')
 @Parameters(Schema)
 @Output(OutputSchema)
 export class DelayTaskHandler implements TaskHandler {

icons/lambda.svg

@@ -1,4 +1,4 @@
-import { Description, Name, Output, Parameters, validateParameters } from '@letrun/core';
+import { Description, Icon, Name, Output, Parameters, validateParameters } from '@letrun/core';
 import { RerunError, TaskDef, TaskHandler, TaskHandlerInput } from '@letrun/common';
 import Joi from 'joi';
 import { initNewIteration, validateLoopTask } from './loop-task';
@@ -42,6 +42,7 @@ const OutputSchema = Joi.object({
 
 @Name('for')
 @Description('Loops through a specified range and performs tasks')
+@Icon('https://raw.githubusercontent.com/sontx/letrun/main/icons/for.svg')
 @Parameters(Schema)
 @Output(OutputSchema)
 export class ForTaskHandler implements TaskHandler {

icons/log.svg

@@ -1,4 +1,4 @@
-import { Description, Name, Output, Parameters, validateParameters } from '@letrun/core';
+import { Description, Icon, Name, Output, Parameters, validateParameters } from '@letrun/core';
 import { TaskHandler, TaskHandlerInput } from '@letrun/common';
 import Joi from 'joi';
 
@@ -72,6 +72,7 @@ const OutputSchema = Joi.any().description('The response data from the HTTP requ
 
 @Name('http')
 @Description('Sends HTTP requests and processes responses')
+@Icon('https://raw.githubusercontent.com/sontx/letrun/main/icons/http.svg')
 @Parameters(Schema)
 @Output(OutputSchema)
 export class HttpTaskHandler implements TaskHandler {

icons/switch.svg

@@ -1,6 +1,7 @@
 import {
   countTasks,
   Description,
+  Icon,
   isWorkflowTaskDefsEmpty,
   Name,
   Output,
@@ -81,6 +82,7 @@ const OutputSchema = Joi.boolean().description('The result of the expression');
 
 @Name('if')
 @Description('Executes tasks based on conditions')
+@Icon('https://raw.githubusercontent.com/sontx/letrun/main/icons/if.svg')
 @Parameters(Schema)
 @Output(OutputSchema)
 export class IfTaskHandler implements TaskHandler {

icons/while.svg

@@ -1,4 +1,4 @@
-import { Description, Name, Output, Parameters, validateParameters } from '@letrun/core';
+import { Description, Icon, Name, Output, Parameters, validateParameters } from '@letrun/core';
 import { RerunError, TaskDef, TaskHandler, TaskHandlerInput } from '@letrun/common';
 import Joi from 'joi';
 import { initNewIteration, validateLoopTask } from './loop-task';
@@ -26,6 +26,7 @@ const OutputSchema = Joi.object({
 
 @Name('iterate')
 @Description('Loops through a list of items and performs tasks')
+@Icon('https://raw.githubusercontent.com/sontx/letrun/main/icons/iterate.svg')
 @Parameters(Schema)
 @Output(OutputSchema)
 export class IterateTaskHandler implements TaskHandler {

icons/workflow.svg

@@ -1,6 +1,6 @@
 import Joi from 'joi';
 import {
-  Description,
+  Description, Icon,
   Name,
   Output,
   Parameters,
@@ -33,6 +33,7 @@ const OutputSchema = Joi.any().description('The result of the lambda expression.
 
 @Name('lambda')
 @Description('Evaluates a lambda expression.')
+@Icon('https://raw.githubusercontent.com/sontx/letrun/main/icons/lambda.svg')
 @Parameters(Schema)
 @Output(OutputSchema)
 export class LambdaTaskHandler implements TaskHandler {