chore: added TSDoc for workflow utility functions (#5674)

* feat(translation): Init plugin * Create migration and entity * Start service implementation * fix typo * typings * config * lang -> locale * chnge config * link * update link * update export * workflow composer (wip) * workflow step/workflow * simplify api * Add structured tests * Add step name onto the step function for future usage * new abstraction level of exported workflow * cleanup * rm step 4 * Add parallelize support to workflow composition * add Symbols and support primitive types as input * rem .only * eslint * cleanup + test * resultFrom * prevent undefined from crashing * finalise tests * chore: transform * chore: tests and transform type * move translation to my dummy * chore: copy before transform * yarn.lock * chore: shortcut to property access * Add type safety * WIP typesafety * WIP * finalise typings * remove extends unknown * WIP * finalise transform typings * finalise transform typings * workflow typs * More typings in invoke and compensate * rm comment * Context as the last args * fix step function type * types * fixes * fixes compose * chore: transform * chore: fix tests and transform Proxy * chore: args length * uncomment * chore: array fill * WIP fix filler * WIP fix filler * chore: remove only * apply gap filler to create step invoke * context first * fixes * wofkrlow ts documentation * wofkrlow ts documentation * wofkrlow ts documentation * wofkrlow ts documentation * wofkrlow ts documentation * chore: hook * hook types * update types * don't loose previous iteration * update implementation * fix some tests part 1 * finalise typings * rm new lines * fixes * wip * fixes * fix tests * simplify types * simplify types * update export * improve types exclusion compensateInput * allow a workflow to return plain object composed of stepReturn properties * only allow one handler for the hook registration * only allow one handler for the hook registration * workflow loading * lint * lint * lint * finalise tests * try to fix ci * try to fix ci * remove corepack step * cleanup * cleanup * cleanup * chore: context as 2nd argumentq * added tsdoc for some workflow functions * Add support for StepResponse and re work the typings * changeset * chore: invoke output as default compensate input * copy data * copy data * fix createWorkflow result * added tsdoc to remaining utility functions * rm test file * proxify input and transformer as well * transformer should re run + type update * rework step response * allow void return from steps * updates to the TSDocs * address comments * address PR feedback * add await for API Route examples * ignore documenting hooks --------- Co-authored-by: adrien2p <adrien.deperetti@gmail.com> Co-authored-by: Carlos R. L. Rodrigues <rodrigolr@gmail.com> Co-authored-by: Carlos R. L. Rodrigues <37986729+carlos-r-l-rodrigues@users.noreply.github.com>
2023-11-23 16:38:43 +00:00
parent 1e39a95f8a
commit f3e20379b0
28 changed files with 687 additions and 175 deletions
--- a/packages/workflows/src/utils/composer/transform.ts
+++ b/packages/workflows/src/utils/composer/transform.ts
@@ -13,14 +13,67 @@ type Func1<T extends object | WorkflowData, U> = (

 type Func<T, U> = (input: T, context: StepExecutionContext) => U | Promise<U>

+/**
+ *
+ * This function transforms the output of other utility functions.
+ *
+ * For example, if you're using the value(s) of some step(s) as an input to a later step. As you can't directly manipulate data in the  workflow constructor function passed to {@link createWorkflow},
+ * the `transform` function provides access to the runtime value of the step(s) output so that you can manipulate them.
+ *
+ * Another example is if you're using the runtime value of some step(s) as the output of a workflow.
+ *
+ * If you're also retrieving the output of a hook and want to check if its value is set, you must use a workflow to get the runtime value of that hook.
+ *
+ * @returns There's no expected value to be returned by the `transform` function.
+ *
+ * @example
+ * import {
+ *   createWorkflow,
+ *   transform
+ * } from "@medusajs/workflows"
+ * import { step1, step2 } from "./steps"
+ *
+ * type WorkflowInput = {
+ *   name: string
+ * }
+ *
+ * type WorkflowOutput = {
+ *   message: string
+ * }
+ *
+ * const myWorkflow = createWorkflow<
+ *     WorkflowInput,
+ *     WorkflowOutput
+ *   >
+ *   ("hello-world", (input) => {
+ *     const str1 = step1(input)
+ *     const str2 = step2(input)
+ *
+ *     return transform({
+ *       str1,
+ *       str2
+ *     }, (input) => ({
+ *       message: `${input.str1}${input.str2}`
+ *     }))
+ * })
+ */
 // prettier-ignore
 // eslint-disable-next-line max-len
 export function transform<T extends object | WorkflowData, RFinal>(
+  /**
+   * The output(s) of other step functions.
+   */
  values: T,
+  /**
+   * The transform function used to perform action on the runtime values of the provided `values`.
+   */
  ...func:
    | [Func1<T, RFinal>]
 ): WorkflowData<RFinal>

+/**
+ * @internal
+ */
 // prettier-ignore
 // eslint-disable-next-line max-len
 export function transform<T extends object | WorkflowData, RA, RFinal>(
@@ -30,6 +83,9 @@ export function transform<T extends object | WorkflowData, RA, RFinal>(
    | [Func1<T, RA>, Func<RA, RFinal>]
 ): WorkflowData<RFinal>

+/**
+ * @internal
+ */
 // prettier-ignore
 // eslint-disable-next-line max-len
 export function transform<T extends object | WorkflowData, RA, RB, RFinal>(
@@ -40,6 +96,9 @@ export function transform<T extends object | WorkflowData, RA, RB, RFinal>(
    | [Func1<T, RA>, Func<RA, RB>, Func<RB, RFinal>]
 ): WorkflowData<RFinal>

+/**
+ * @internal
+ */
 // prettier-ignore
 // eslint-disable-next-line max-len
 export function transform<T extends object | WorkflowData, RA, RB, RC, RFinal>(
@@ -51,6 +110,9 @@ export function transform<T extends object | WorkflowData, RA, RB, RC, RFinal>(
    | [Func1<T, RA>, Func<RA, RB>, Func<RB, RC>, Func<RC, RFinal>]
 ): WorkflowData<RFinal>

+/**
+ * @internal
+ */
 // prettier-ignore
 // eslint-disable-next-line max-len
 export function transform<T extends object | WorkflowData, RA, RB, RC, RD, RFinal>(
@@ -63,6 +125,9 @@ export function transform<T extends object | WorkflowData, RA, RB, RC, RD, RFina
    | [Func1<T, RA>, Func<RA, RB>, Func<RB, RC>, Func<RC, RD>, Func<RD, RFinal>]
 ): WorkflowData<RFinal>

+/**
+ * @internal
+ */
 // prettier-ignore
 // eslint-disable-next-line max-len
 export function transform<T extends object | WorkflowData, RA, RB, RC, RD, RE, RFinal>(
@@ -76,6 +141,9 @@ export function transform<T extends object | WorkflowData, RA, RB, RC, RD, RE, R
    | [Func1<T, RA>, Func<RA, RB>, Func<RB, RC>, Func<RC, RD>, Func<RD, RE>, Func<RE, RFinal>]
 ): WorkflowData<RFinal>

+/**
+ * @internal
+ */
 // prettier-ignore
 // eslint-disable-next-line max-len
 export function transform<T extends object | WorkflowData, RA, RB, RC, RD, RE, RF, RFinal>(
@@ -90,14 +158,6 @@ export function transform<T extends object | WorkflowData, RA, RB, RC, RD, RE, R
    | [Func1<T, RA>, Func<RA, RB>, Func<RB, RC>, Func<RC, RD>, Func<RD, RE>, Func<RE, RF>, Func<RF, RFinal>]
 ): WorkflowData<RFinal>

-/**
- * Transforms the input value(s) using the provided functions.
- * Allow to perform transformation on the future result of the step(s) to be passed
- * to other steps later on at run time.
- *
- * @param values
- * @param functions
- */
 export function transform(
  values: any | any[],
  ...functions: Function[]