From 7634145286cdb8483bbcd151343bbcb6d5a0a65f Mon Sep 17 00:00:00 2001
From: SamTolmay <sam@lowdefy.com>
Date: Mon, 16 Aug 2021 14:09:27 +0200
Subject: [PATCH] feat(engine): Document Lowdefy action functions in JsAction.

---
 packages/docs/actions/JsAction.yaml     | 55 +++++++++++++++++++++++--
 packages/engine/src/actions/JsAction.js |  4 +-
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/packages/docs/actions/JsAction.yaml b/packages/docs/actions/JsAction.yaml
index 3c054e5f0..336d9b1dd 100644
--- a/packages/docs/actions/JsAction.yaml
+++ b/packages/docs/actions/JsAction.yaml
@@ -30,19 +30,31 @@ _ref:
     description: |
       The `JsAction` action is used to call a custom JavaScript function which was loaded onto the page using the `window.lowdefy.registerJsAction()` method. This JavaScript function can be asynchronous. See [Custom Code](/custom-code) for more details on how to register a new JavaScript action.
 
-      The returned result of the JavaScript function is accessible through the [`_actions`](/_actions) operator for subsequent action in the event action list.
+      The returned result of the JavaScript function is accessible through the [`_actions`](/_actions) operator for subsequent actions in the event action list.
+
+      #### JsAction function parameters
+
+      A `JsAction` function is called with a context object which includes all [`context` data objects](/context-and-state) as well as the list of `args` passed to the action.
 
-      A `JsAction` is called with a context object which includes all [`context` data objects](/context-and-state) as well as the list of `args` passed to the action.
       ```text
       (context: {
-        user: object,
+        actions: object,
+        contextId: string,
         global: object,
+        input: object,
+        pageId: string,
+        requests: object,
         state: object,
         urlQuery: object,
-        input: object,
+        user: object,
       },
       ...args?: any[]): any
       ```
+
+      #### Using Lowdefy actions in a JsAction
+
+      The context passed to the custom JsAction function contains an object called `actions`. This object contains all the Lowdefy action functions like `SetState`, `Request`, and `CallMethod`. The functions can be called using the same parameters as when they are used directly in the Lowdefy configuration. Operators in these parameters are not evaluated.
+
     params: |
       ###### object
         - `name: string`: __Required__ - The registered name of the JavaScript function to call when the action is triggered.
@@ -232,3 +244,38 @@ _ref:
         }
       }
       ```
+
+      ##### Use Lowdefy SetState action:
+
+      ```js
+      // file: /public/theAnswer.js
+      function theAnswer({actions}) {
+        // Think for a while...
+        return actions.SetState({ answer: 42 })
+      }
+      export default theAnswer;
+      ```
+
+      ##### Use Lowdefy Request action to loop over a list of requests:
+      ```js
+      // file: /public/loopRequests.js
+      function loopRequests({ actions }, ...requestIds) {
+        return Promise.all(requestIds.map((id) => actions.Request(id)));
+      }
+      export default loopRequests;
+      ```
+
+      ```yaml
+      id: call_all_requests
+      type: Button
+      events:
+        onClick:
+          - id: loop_requests
+            type: JsAction
+            params:
+              name: loopRequests
+              args:
+                - request_1
+                - request_2
+                - request_3
+      ```
diff --git a/packages/engine/src/actions/JsAction.js b/packages/engine/src/actions/JsAction.js
index 015bcafab..2a51f4360 100644
--- a/packages/engine/src/actions/JsAction.js
+++ b/packages/engine/src/actions/JsAction.js
@@ -43,11 +43,11 @@ async function JsAction({ context, event, params, arrayIndices, blockId }) {
   return context.lowdefy.imports.jsActions[params.name](
     {
       ...serializer.copy({
-        user: context.lowdefy.user,
         global: context.lowdefy.lowdefyGlobal,
+        input: context.lowdefy.inputs[context.id],
         state: context.state,
         urlQuery: context.lowdefy.urlQuery,
-        input: context.lowdefy.inputs[context.id],
+        user: context.lowdefy.user,
       }),
       actions,
       contextId: context.id,