Steps

As the codebase expands, the internal logic within APIs may become increasingly intricate. By using Steps, we can break down complex logic into several simple steps, which can enhance code readability and make the code structure clearer.

Usage

In the context, use the step method to break down the logic into multiple steps. Each step can return an object, and the properties of this object will be mixed into stages and serve as parameters for the next step.

Note

You can use the VS Code extension’s code snippets by typing .step!

async action(
  params: { /* ... */ },
  context,
) {
  const result = await context
    /**
     * Step 1
     */
    .step(async (stages) => {
      const value1 = 5;

      return { value1 };
    })
    /**
     * Step 2
     */
    .step(async (stage) => {
      const value2 = stage.value1 + 5;

      return { value2 };
    })
    .run();

  return result;
},

Running

After declaring multiple steps in your code, you need to execute the run() method to run the entire sequence of steps.

Once all steps have completed, the final stage will be returned by the run() method. For example, in the code snippet above, the content of the result variable will be:

{ value1: 5, value2: 10 }

Protected

In the object returned by each step, if a property starts with $, it will be protected and only visible within the step, not included in the return value of the run() method.

You can utilize this feature to keep certain variables private within the steps and not expose them in the final results.

async action(
  params: { /* ... */ },
  context,
) {
  const result = await context
    /**
     * Step 1
     */
    .step(async (stages) => {
      const $value1 = 5;

      return { $value1 };
    })
    /**
     * Step 2
     */
    .step(async (stage) => {
      const value2 = stage.$value1 + 5;

      return { value2 };
    })
    .run();

  return result;
},

In this case, the content of the result variable will be as follows, where $value1 does not appear in the results.

{ value2: 10 }

VS Code Structure

Milkio’s VS Code extension can display the structure of your API. In the sidebar of your VS Code, there is a collapsible panel at the bottom named MILKIO STRUCTURE, which includes the structure of your API.

↓ Meta
↓ Action
  step: Step 1
  step: Step 2
  step: Step 3
↓ Tests
  test: Basic

This feature is very useful when reading lengthy API documents. By clicking on an item, you can quickly navigate to the relevant code location.

For steps, multiline comments at the top will be displayed as the step’s name (single-line comments are not supported).