@cadenza.io/service 1.24.5 → 1.24.7

package/dist/index.d.mts

@@ -21814,6 +21814,13 @@ declare class CadenzaService {
      * @param {string} signal - The name of the event or signal to emit.
      * @param {AnyObject} [data={}] - The data to be emitted along with the signal.
      * @return {void} No return value.
+     *
+     * @example
+     * This is meant to be used as a global event emitter.
+     * If you want to emit an event from within a task, you can use the `emit` method provided to the task function. See {@link TaskFunction}.
+     * ```ts
+     * Cadenza.emit('main.my_event', { foo: 'bar' });
+     * ```
      */
     static emit(signal: string, data?: AnyObject): void;
     /**
@@ -21822,10 +21829,24 @@ declare class CadenzaService {
      * @param {Task | GraphRoutine} task - The task or graph routine to be executed.
      * @param {AnyObject} context - The context within which the task will be executed.
      * @return {void}
+     *
+     * @example
+     * ```ts
+     * const task = Cadenza.createTask('My task', (ctx) => {
+     *   console.log('My task executed with context:', ctx);
+     * });
+     *
+     * Cadenza.run(task, { foo: 'bar' });
+     *
+     * const routine = Cadenza.createRoutine('My routine', [task], 'My routine description');
+     *
+     * Cadenza.run(routine, { foo: 'bar' });
+     * ```
      */
     static run(task: Task | GraphRoutine, context: AnyObject): void;
     /**
      * Logs a message with a specified log level and additional contextual data.
+     * Records in the CadenzaDB when available.
      *
      * @param {string} message - The main message to be logged.
      * @param {any} [data={}] - Additional data or metadata to include with the log.
@@ -21844,11 +21865,57 @@ declare class CadenzaService {
      * @param {string|undefined} [serviceName] - The name of the service that the routine belongs to. This is optional and defaults to undefined.
      * @param {TaskOptions} [options={}] - A configuration object for the task, allowing various properties such as concurrency, timeout, and retry settings to be customized.
      * @return {DeputyTask} - A new DeputyTask instance initialized with the specified parameters.
+     *
+     * @example
+     * Let's say we are writing the code for a Service called "Service1".
+     * We also have an additional service called "Service2" with a routine called "My Routine".
+     * A flow on Service1 depends on the result of "My Routine" on Service2.
+     * We can create a deputy task for the routine using the following code:
+     * ```ts
+     * Cadenza.createDeputyTask("My Routine", "Service2").then(
+     *   Cadenza.createTask("Handle result", (ctx) => {
+     *     console.log("'Handle result' executed with context:", ctx);
+     *   }),
+     * );
+     * ```
+     * Internally, this will send a request to an available "Service2" instance to execute the "My Routine" routine.
+     * The deputy task will wait for the response and then execute the next task(s) in the chain.
+     *
+     * You can visualize the execution of the deputy task as follows:
+     * ```
+     * Service1 flow = [Deputy tasks for "My Routine"] -> ["Handle result"]
+     *                       ||       A
+     *                       V       ||
+     * Service2 flow =    [[My Routine]]
+     * ```
+     *
+     * Deputy tasks are useful for delegating flows to other services, allowing for parallel execution and load balancing.
+     * But it creates tight coupling between the services, which may not be desirable in some cases.
+     * In cases where an event on one service should simply trigger a flow on another service, without the need for a result,
+     * it is recommended to use signals instead. Like this:
+     *
+     * Service1
+     * ```ts
+     * Cadenza.createTask("Generate event", (ctx, emit) => {
+     *   // Do something
+     *   emit("some.event");
+     * });
+     * ```
+     *
+     * Service2
+     * ```ts
+     * Cadenza.createTask("Handle event", (ctx) => {
+     *   console.log("Handle event executed with context:", ctx);
+     * }).doOn("Service1.some.event");
+     * ```
+     *
+     * Every time the "Generate event" task is executed, it will emit a signal "Service1.some.event" to one Service2 instance and trigger the "Handle event" task.
      */
     static createDeputyTask(routineName: string, serviceName?: string | undefined, options?: TaskOptions): DeputyTask;
     /**
      * Creates a meta deputy task by setting the `isMeta` property in the options to true,
      * and delegating task creation to the `createDeputyTask` method.
+     * See {@link createDeputyTask} and {@link createMetaTask} for more information.
      *
      * @param {string} routineName - The name of the routine associated with the task.
      * @param {string | undefined} [serviceName] - The optional name of the service associated with the task.
@@ -21856,39 +21923,20 @@ declare class CadenzaService {
      * @return {DeputyTask} - The created meta deputy task.
      */
     static createMetaDeputyTask(routineName: string, serviceName?: string | undefined, options?: TaskOptions): DeputyTask;
-    /**
-     * Creates a unique deputy task with the specified routine name, service name,
-     * and optional task options. The uniqueness is ensured by setting the
-     * `isUnique` property in the task options.
-     *
-     * @param {string} routineName - The name of the routine associated with the task.
-     * @param {string | undefined} [serviceName] - The name of the service associated with the task. If undefined, no service name is used.
-     * @param {TaskOptions} [options={}] - Additional configuration options for the task.
-     * @return {*} - Returns the result of creating a deputy task with the provided parameters and unique configuration.
-     */
-    static createUniqueDeputyTask(routineName: string, serviceName?: string | undefined, options?: TaskOptions): DeputyTask;
-    /**
-     * Creates a unique meta deputy task based on the provided routine name, service name, and options.
-     * This method sets the task as a meta task and delegates the creation to the `createUniqueDeputyTask` method.
-     *
-     * @param {string} routineName - The routine name to associate with the meta deputy task.
-     * @param {string | undefined} [serviceName] - The optional service name associated with the task.
-     * @param {TaskOptions} [options] - Additional options to configure the task. Defaults to an empty options object.
-     * @return {*} A unique meta deputy task created based on the given parameters.
-     */
-    static createUniqueMetaDeputyTask(routineName: string, serviceName?: string | undefined, options?: TaskOptions): DeputyTask;
     /**
      * Creates a throttled deputy task with the specified parameters.
+     * See {@link createThrottledTask} and {@link createDeputyTask} for more information.
      *
      * @param {string} routineName - The name of the routine to be executed.
      * @param {string | undefined} [serviceName=undefined] - The name of the service, if applicable.
      * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] - A function to get the throttled tag for the task.
      * @param {TaskOptions} [options={}] - The options for task configuration, including concurrency and callbacks.
-     * @return {any} The created throttled deputy task.
+     * @return {DeputyTask} The created throttled deputy task.
      */
     static createThrottledDeputyTask(routineName: string, serviceName?: string | undefined, throttledIdGetter?: ThrottleTagGetter, options?: TaskOptions): DeputyTask;
     /**
      * Creates a throttled deputy task with meta-task settings enabled.
+     * See {@link createThrottledTask},{@link createDeputyTask} and {@link createMetaTask} for more information.
      *
      * @param {string} routineName - The name of the routine for which the task is being created.
      * @param {string|undefined} [serviceName=undefined] - The name of the service associated with the task, or undefined if not applicable.
@@ -21900,6 +21948,7 @@ declare class CadenzaService {
     /**
      * Creates and configures a signal transmission task that handles the transmission
      * of a specified signal to a target service with a set of customizable options.
+     * This is only used for internal purposes and is not exposed to the business logic layer.
      *
      * @param {string} signalName - The name of the signal to be transmitted.
      * @param {string} serviceName - The name of the target service to transmit the signal to.
@@ -22013,114 +22062,339 @@ declare class CadenzaService {
      * @param {string} [description] - An optional description of what the task does.
      * @param {TaskOptions} [options={}] - An optional configuration object specifying additional task options.
      * @return {Task} - The created task instance.
+     *
+     * @example
+     * You can use arrow functions to create tasks.
+     * ```ts
+     * const task = Cadenza.createTask('My task', (ctx) => {
+     *   console.log('My task executed with context:', ctx);
+     * }, 'My task description');
+     * ```
+     *
+     * You can also use named functions to create tasks.
+     * This is the preferred way to create tasks since it allows for code inspection in the CadenzaUI.
+     * ```ts
+     * function myTask(ctx) {
+     *   console.log('My task executed with context:', ctx);
+     * }
+     *
+     * const task = Cadenza.createTask('My task', myTask);
+     * ```
+     *
+     * ** Use the TaskOptions object to configure the task. **
+     *
+     * With concurrency limit, timeout limit and retry settings.
+     * ```ts
+     * Cadenza.createTask('My task', (ctx) => {
+     *   console.log('My task executed with context:', ctx);
+     * }, 'My task description', {
+     *   concurrency: 10,
+     *   timeout: 10000,
+     *   retryCount: 3,
+     *   retryDelay: 1000,
+     *   retryDelayFactor: 1.5,
+     * });
+     * ```
+     *
+     * You can specify the input and output context schemas for the task.
+     * ```ts
+     * Cadenza.createTask('My task', (ctx) => {
+     *   return { bar: 'foo' + ctx.foo };
+     * }, 'My task description', {
+     *   inputContextSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       foo: {
+     *         type: 'string',
+     *       },
+     *     },
+     *   required: ['foo'],
+     *   },
+     *   validateInputContext: true, // default is false
+     *   outputContextSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       bar: {
+     *         type: 'string',
+     *       },
+     *     },
+     *     required: ['bar'],
+     *   },
+     *   validateOutputContext: true, // default is false
+     * });
+     * ```
      */
     static createTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
-     * Creates a new meta task with the specified name, function, description, and options.
+     * Creates a meta task with the specified name, functionality, description, and options.
+     * This is used for creating tasks that lives on the meta layer.
+     * The meta layer is a special layer that is executed separately from the business logic layer and is used for extending Cadenzas core functionality.
+     * See {@link Task} or {@link createTask} for more information.
      *
      * @param {string} name - The name of the meta task.
      * @param {TaskFunction} func - The function to be executed by the meta task.
      * @param {string} [description] - An optional description of the meta task.
-     * @param {TaskOptions} [options={}] - Additional options to configure the meta task.
-     * @return {Task} The created meta task instance.
+     * @param {TaskOptions} [options={}] - Additional optional task configuration. Automatically sets `isMeta` to true.
+     * @return {Task} A task instance configured as a meta task.
      */
     static createMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
-     * Creates a UniqueTask (executes once per execution ID, merging parents) and registers it.
-     * Use for fan-in/joins after parallel branches.
+     * Creates a unique task by wrapping the provided task function with a uniqueness constraint.
+     * Unique tasks are designed to execute once per execution ID, merging parents. This is useful for
+     * tasks that require fan-in/joins after parallel branches.
+     * See {@link Task} for more information.
      * @param {string} name Unique identifier.
      * @param {TaskFunction} func Function receiving joinedContexts as a list (context.joinedContexts).
      * @param {string} [description] Optional description.
      * @param {TaskOptions} [options={}] Optional task options.
      * @returns {Task} The created UniqueTask.
+     *
+     * @example
+     * ```ts
+     * const splitTask = Cadenza.createTask('Split foos', function* (ctx) {
+     *   for (const foo of ctx.foos) {
+     *     yield { foo };
+     *   }
+     * }, 'Splits a list of foos into multiple sub-branches');
+     *
+     * const processTask = Cadenza.createTask('Process foo', (ctx) => {
+     *  return { bar: 'foo' + ctx.foo };
+     * }, 'Process a foo');
+     *
+     * const uniqueTask = Cadenza.createUniqueTask('Gather processed foos', (ctx) => {
+     *   // A unique task will always be provided with a list of contexts (ctx.joinedContexts) from its predecessors.
+     *   const processedFoos = ctx.joinedContexts.map((c) => c.bar);
+     *   return { foos: processedFoos };
+     * }, 'Gathers together the processed foos.');
+     *
+     * splitTask.then(
+     *   processTask.then(
+     *     uniqueTask,
+     *   ),
+     * );
+     *
+     * // Give the flow a name using a routine
+     * Cadenza.createRoutine(
+     *   'Process foos',
+     *   [splitTask],
+     *   'Processes a list of foos'
+     * ).doOn('main.received_foos'); // Subscribe to a signal
+     *
+     * // Trigger the flow from anywhere
+     * Cadenza.emit('main.received_foos', { foos: ['foo1', 'foo2', 'foo3'] });
+     * ```
      */
     static createUniqueTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
-     * Creates a unique meta task with the provided name, function, description, and options.
+     * Creates a unique meta task with the specified name, function, description, and options.
+     * See {@link createUniqueTask} and {@link createMetaTask} for more information.
      *
-     * @param {string} name - The unique name for the meta task.
-     * @param {TaskFunction} func - The function to be executed by the task.
-     * @param {string} [description] - An optional description of the task's purpose.
-     * @param {TaskOptions} [options={}] - Additional optional configuration settings for the task.
-     * @return {Task} Returns the created unique meta task.
+     * @param {string} name - The name of the task to create.
+     * @param {TaskFunction} func - The function to execute when the task is run.
+     * @param {string} [description] - An optional description of the task.
+     * @param {TaskOptions} [options={}] - Optional settings for the task. Defaults to an empty object. Automatically sets `isMeta` and `isUnique` to true.
+     * @return {Task} The created unique meta task.
      */
     static createUniqueMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions): Task;
     /**
-     * Creates a ThrottledTask (rate-limited by concurrency or custom groups) and registers it.
-     * @param {string} name Unique identifier.
-     * @param {TaskFunction} func Function.
-     * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] Optional getter for dynamic grouping (e.g., per-user).
-     * @param {string} [description] Optional.
-     * @param {TaskOptions} [options={}] Optional task options.
-     * @returns {Task} The created ThrottledTask.
+     * Creates a throttled task with a concurrency limit of 1, ensuring that only one instance of the task can run at a time for a specific throttle tag.
+     * This is useful for ensuring execution order and preventing race conditions.
+     * See {@link Task} for more information.
+     *
+     * @param {string} name - The name of the task.
+     * @param {TaskFunction} func - The function to be executed when the task runs.
+     * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] - A function that generates a throttle tag identifier to group tasks for throttling.
+     * @param {string} [description] - An optional description of the task.
+     * @param {TaskOptions} [options={}] - Additional options to customize the task behavior.
+     * @return {Task} The created throttled task.
+     *
+     * @example
+     * ```ts
+     * const task = Cadenza.createThrottledTask(
+     *   'My task',
+     *   async (ctx) => {
+     *      await new Promise((resolve) => setTimeout(resolve, 1000));
+     *      console.log('My task executed with context:', ctx);
+     *   },
+     *   // Will throttle by the value of ctx.foo to make sure tasks with the same value are executed sequentially
+     *   (ctx) => ctx.foo,
+     * );
+     *
+     * Cadenza.run(task, { foo: 'bar' }); // (First execution)
+     * Cadenza.run(task, { foo: 'bar' }); // This will be executed after the first execution is finished
+     * Cadenza.run(task, { foo: 'baz' }); // This will be executed in parallel with the first execution
+     * ```
      */
     static createThrottledTask(name: string, func: TaskFunction, throttledIdGetter?: ThrottleTagGetter, description?: string, options?: TaskOptions): Task;
     /**
-     * Creates and returns a throttled meta task with the specified name, function,
-     * and additional options. Throttling is determined based on the throttled ID getter.
+     * Creates a throttled meta task with the specified configuration.
+     * See {@link createThrottledTask} and {@link createMetaTask} for more information.
      *
-     * @param {string} name - The unique name for the meta task.
-     * @param {TaskFunction} func - The function to be executed as the task.
-     * @param {ThrottleTagGetter} [throttledIdGetter=() => "default"] - A function that determines the throttle ID for the task.
+     * @param {string} name - The name of the throttled meta task.
+     * @param {TaskFunction} func - The task function to be executed.
+     * @param {ThrottleTagGetter} throttledIdGetter - A function to retrieve the throttling identifier.
      * @param {string} [description] - An optional description of the task.
-     * @param {TaskOptions} [options={}] - Additional configuration options for the task.
+     * @param {TaskOptions} [options={}] - Additional options for configuring the task.
      * @return {Task} The created throttled meta task.
      */
     static createThrottledMetaTask(name: string, func: TaskFunction, throttledIdGetter?: ThrottleTagGetter, description?: string, options?: TaskOptions): Task;
     /**
-     * Creates a DebounceTask (delays exec until quiet period) and registers it.
-     * @param {string} name Identifier.
-     * @param {TaskFunction} func Function.
-     * @param {string} [description] Optional.
-     * @param {number} [debounceTime=1000] Delay in ms.
-     * @param {TaskOptions & DebounceOptions} [options={}] Optional task options plus optional debounce config (e.g., leading/trailing).
-     * @returns {Task} The created DebounceTask.
+     * Creates and returns a new debounced task with the specified parameters.
+     * This is useful to prevent rapid execution of tasks that may be triggered by multiple events within a certain time frame.
+     * See {@link DebounceTask} for more information.
+     *
+     * @param {string} name - The unique name of the task to be created.
+     * @param {TaskFunction} func - The function to be executed by the task.
+     * @param {string} [description] - An optional description of the task.
+     * @param {number} [debounceTime=1000] - The debounce time in milliseconds to delay the execution of the task.
+     * @param {TaskOptions & DebounceOptions} [options={}] - Additional configuration options for the task, including debounce behavior and other task properties.
+     * @return {DebounceTask} A new instance of the DebounceTask with the specified configuration.
+     *
+     * @example
+     * ```ts
+     * const task = Cadenza.createDebounceTask(
+     *   'My debounced task',
+     *   (ctx) => {
+     *      console.log('My task executed with context:', ctx);
+     *   },
+     *   'My debounced task description',
+     *   100, // Debounce time in milliseconds. Default is 1000
+     *   {
+     *     leading: false, // Should the first execution of a burst be executed immediately? Default is false
+     *     trailing: true, // Should the last execution of a burst be executed? Default is true
+     *     maxWait: 1000, // Maximum time in milliseconds to wait for the next execution. Default is 0
+     *   },
+     * );
+     *
+     * Cadenza.run(task, { foo: 'bar' }); // This will not be executed
+     * Cadenza.run(task, { foo: 'bar' }); // This will not be executed
+     * Cadenza.run(task, { foo: 'baz' }); // This execution will be delayed by 100ms
+     * ```
      */
     static createDebounceTask(name: string, func: TaskFunction, description?: string, debounceTime?: number, options?: TaskOptions & DebounceOptions): DebounceTask;
     /**
-     * Creates a DebounceTask for the meta layer (delays exec until quiet period) and registers it.
-     * @param {string} name Identifier.
-     * @param {TaskFunction} func Function.
-     * @param {string} [description] Optional.
-     * @param {number} [debounceTime=1000] Delay in ms.
-     * @param {TaskOptions & DebounceOptions} [options={}] Optional task options plus optional debounce config (e.g., leading/trailing).
-     * @returns {Task} The created DebounceMetaTask.
+     * Creates a debounced meta task with the specified parameters.
+     * See {@link createDebounceTask} and {@link createMetaTask} for more information.
+     *
+     * @param {string} name - The name of the task.
+     * @param {TaskFunction} func - The function to be executed by the task.
+     * @param {string} [description] - Optional description of the task.
+     * @param {number} [debounceTime=1000] - The debounce delay in milliseconds.
+     * @param {TaskOptions & DebounceOptions} [options={}] - Additional configuration options for the task.
+     * @return {DebounceTask} Returns an instance of the debounced meta task.
      */
     static createDebounceMetaTask(name: string, func: TaskFunction, description?: string, debounceTime?: number, options?: TaskOptions & DebounceOptions): DebounceTask;
     /**
-     * Creates an EphemeralTask (self-destructs after exec or condition) without default registration.
-     * Useful for transients; optionally register if needed.
-     * @param {string} name Identifier (may not be unique if not registered).
-     * @param {TaskFunction} func Function.
-     * @param {string} [description] Optional.
-     * @param {TaskOptions & EphemeralTaskOptions} [options={}] Optional task options.
-     * @returns {Task} The created EphemeralTask.
+     * Creates an ephemeral task with the specified configuration.
+     * Ephemeral tasks are designed to self-destruct after execution or a certain condition is met.
+     * This is useful for transient tasks such as resolving promises or performing cleanup operations.
+     * They are not registered by default.
+     * See {@link EphemeralTask} for more information.
+     *
+     * @param {string} name - The name of the task to be created.
+     * @param {TaskFunction} func - The function that defines the logic of the task.
+     * @param {string} [description] - An optional description of the task.
+     * @param {TaskOptions & EphemeralTaskOptions} [options={}] - The configuration options for the task, including concurrency, timeouts, and retry policies.
+     * @return {EphemeralTask} The created ephemeral task instance.
+     *
+     * @example
+     * By default, ephemeral tasks are executed once and destroyed after execution.
+     * ```ts
+     * const task = Cadenza.createEphemeralTask('My ephemeral task', (ctx) => {
+     *   console.log('My task executed with context:', ctx);
+     * });
+     *
+     * Cadenza.run(task); // Executes the task once and destroys it after execution
+     * Cadenza.run(task); // Does nothing, since the task is destroyed
+     * ```
+     *
+     * Use destroy condition to conditionally destroy the task
+     * ```ts
+     * const task = Cadenza.createEphemeralTask(
+     *   'My ephemeral task',
+     *   (ctx) => {
+     *      console.log('My task executed with context:', ctx);
+     *   },
+     *   'My ephemeral task description',
+     *   {
+     *     once: false, // Should the task be executed only once? Default is true
+     *     destroyCondition: (ctx) => ctx.foo > 10, // Should the task be destroyed after execution? Default is undefined
+     *   },
+     * );
+     *
+     * Cadenza.run(task, { foo: 5 }); // The task will not be destroyed and can still be executed
+     * Cadenza.run(task, { foo: 10 }); // The task will not be destroyed and can still be executed
+     * Cadenza.run(task, { foo: 20 }); // The task will be destroyed after execution and cannot be executed anymore
+     * Cadenza.run(task, { foo: 30 }); // This will not be executed
+     * ```
+     *
+     * A practical use case for ephemeral tasks is to resolve a promise upon some external event.
+     * ```ts
+     * const task = Cadenza.createTask('Confirm something', (ctx, emit) => {
+     *   return new Promise((resolve) => {
+     *     ctx.foo = uuid();
+     *
+     *     Cadenza.createEphemeralTask(`Resolve promise of ${ctx.foo}`, (c) => {
+     *       console.log('My task executed with context:', ctx);
+     *       resolve(c);
+     *     }).doOn(`socket.confirmation_received:${ctx.foo}`);
+     *
+     *     emit('this_domain.confirmation_requested', ctx);
+     *   });
+     * });
+     * ```
      */
     static createEphemeralTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
-     * Creates an EphemeralTask for the meta layer (self-destructs after exec or condition) without default registration.
-     * Useful for transients; optionally register if needed.
-     * @param {string} name Identifier (may not be unique if not registered).
-     * @param {TaskFunction} func Function.
-     * @param {string} [description] Optional.
-     * @param {TaskOptions & EphemeralTaskOptions} [options={}] Optional task options.
-     * @returns {Task} The created EphemeralMetaTask.
+     * Creates an ephemeral meta task with the specified name, function, description, and options.
+     * See {@link createEphemeralTask} and {@link createMetaTask} for more details.
+     *
+     * @param {string} name - The name of the task to be created.
+     * @param {TaskFunction} func - The function to be executed as part of the task.
+     * @param {string} [description] - An optional description of the task.
+     * @param {TaskOptions & EphemeralTaskOptions} [options={}] - Additional options for configuring the task.
+     * @return {EphemeralTask} The created ephemeral meta task.
      */
     static createEphemeralMetaTask(name: string, func: TaskFunction, description?: string, options?: TaskOptions & EphemeralTaskOptions): EphemeralTask;
     /**
-     * Creates a GraphRoutine (named entry to starting tasks) and registers it.
-     * @param {string} name Unique identifier.
-     * @param {Task[]} tasks Starting tasks.
-     * @param {string} [description] Optional.
-     * @returns {GraphRoutine} The created GraphRoutine.
+     * Creates a new routine with the specified name, tasks, and an optional description.
+     * Routines are named entry points to starting tasks and are registered in the GraphRegistry.
+     * They are used to group tasks together and provide a high-level structure for organizing and managing the execution of a set of tasks.
+     * See {@link GraphRoutine} for more information.
+     *
+     * @param {string} name - The name of the routine to create.
+     * @param {Task[]} tasks - A list of tasks to include in the routine.
+     * @param {string} [description=""] - An optional description for the routine.
+     * @return {GraphRoutine} A new instance of the GraphRoutine containing the specified tasks and description.
+     *
+     * @example
+     * ```ts
+     * const task1 = Cadenza.createTask("Task 1", () => {});
+     * const task2 = Cadenza.createTask("Task 2", () => {});
+     *
+     * task1.then(task2);
+     *
+     * const routine = Cadenza.createRoutine("Some routine", [task1]);
+     *
+     * Cadenza.run(routine);
+     *
+     * // Or, routines can be triggered by signals
+     * routine.doOn("some.signal");
+     *
+     * Cadenza.emit("some.signal", {});
+     * ```
      */
     static createRoutine(name: string, tasks: Task[], description?: string): GraphRoutine;
     /**
-     * Creates a GraphRoutine for the meta layer (named entry to starting tasks) and registers it.
-     * @param {string} name Unique identifier.
-     * @param {Task[]} tasks Starting tasks.
-     * @param {string} [description] Optional.
-     * @returns {GraphRoutine} The created GraphMetaRoutine.
+     * Creates a meta routine with a given name, tasks, and optional description.
+     * Routines are named entry points to starting tasks and are registered in the GraphRegistry.
+     * They are used to group tasks together and provide a high-level structure for organizing and managing the execution of a set of tasks.
+     * See {@link GraphRoutine} and {@link createRoutine} for more information.
+     *
+     * @param {string} name - The name of the routine to be created.
+     * @param {Task[]} tasks - An array of tasks that the routine will consist of.
+     * @param {string} [description=""] - An optional description for the routine.
+     * @return {GraphRoutine} A new instance of the `GraphRoutine` representing the created routine.
      */
     static createMetaRoutine(name: string, tasks: Task[], description?: string): GraphRoutine;
     static reset(): void;