@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/controls/log.md

@@ -0,0 +1,50 @@
+# :log
+
+```
+({:log: any, :level: string}): void
+```
+
+The `:log` control outputs messages to the server console at specified log levels (debug, info, warn, error).
+
+#### Keys
+
+- `:log: any`: __Required__ - The value to be log to the console.
+- `:level: string`: Level of log. One of debug, info, warn, error. The default is info.
+
+#### Examples
+
+###### String Message
+```yaml
+:log: 'New Log Message'
+```
+
+###### Log a JSON Object
+```yaml
+:log:
+  message: Log Message
+  user_id:
+    _user: id
+  timestamp:
+    _date: now
+```
+
+###### Set log levels
+```yaml
+- :log:
+    payload:
+      _payload: true
+  :level: debug
+- :log: 'Processing started'
+  :level: 'info'
+- :log:
+    message: Multiple failed attempts
+    attempts:
+      _payload: attempt_count
+    user:
+      _user: id
+  :level: warn
+- :log:
+    message: An error occurred.
+
+  :level: error
+```

package/content/controls/parallel.md

@@ -0,0 +1,71 @@
+# :parallel
+
+```
+({:parallel: routine[]}): void
+```
+
+The `:parallel` control executes multiple independent routines simultaneously. All routines within the `:parallel` array are started at the same time and the control waits for all of them to complete before continuing. If any routine returns with an error, rejection, or explicit return, the parallel control will exit early with that status (prioritizing errors first, then rejections, then returns).
+
+#### Keys
+
+- `:parallel: routine[]`: __Required__ - An array of routines that will be executed in parallel.
+
+#### Examples
+
+###### Fetch from multiple sources in parallel
+
+```yaml
+routine:
+  - :parallel:
+      - id: fetch_user_stats
+        type: MongoDBAggregation
+        connectionId: users
+        properties:
+          pipeline:
+            - $match:
+                account_id:
+                  _payload: account_id
+            - $group:
+                _id: null
+                total_users:
+                  $sum: 1
+                active_users:
+                  $sum:
+                    $cond:
+                      - $eq: ['$status', 'active']
+                      - 1
+                      - 0
+
+      - id: fetch_revenue
+        type: KnexRaw
+        connectionId: analytics_db
+        properties:
+          query: |
+            SELECT
+              SUM(amount) as total_revenue,
+              COUNT(*) as transaction_count
+            FROM transactions
+            WHERE account_id = :account_id
+              AND created_at >= NOW() - INTERVAL '30 days'
+          parameters:
+            account_id:
+              _payload: account_id
+
+      - id: fetch_tickets
+        type: AxiosHttp
+        connectionId: tickets-api
+        properties:
+          url: '/tickets'
+          method: get
+          params:
+            organization_id:
+              _payload: account_id
+            status: 'open'
+  - :return:
+      user_stats:
+        _step: fetch_user_stats
+      revenue:
+        _step: revenue
+      tickets:
+        _step: fetch_tickets
+```

package/content/controls/parallel_for.md

@@ -0,0 +1,36 @@
+# :parallel_for
+
+```
+({:parallel_for: string, :in: any[], :do: routine}): void
+```
+
+The `:parallel_for` control executes a routine for each item in an array simultaneously. Each iteration has access to its array item through the [`_item`](/_item) operator using the key specified in `:parallel_for`.
+Unlike sequential [`:for`](/:for), all iterations start at the same time, making it ideal for processing independent items where order doesn't matter.
+The control waits for all iterations to complete before continuing, unless an error, rejection, or return occurs.
+
+#### Keys
+
+- `:parallel_for: string`: __Required__ - Used to define the key that can be used to access the value of the array item of the executing iteration.
+- `:in: any`: __Required__ - Used to define the array of data to iterate over.
+- `:do: routine`: __Required__ - Used to define the routine that will be executed for each array item in parallel.
+
+#### Examples
+
+###### Update Multiple Users
+```yaml
+- :parallel_for: user_id
+  :in:
+    _payload: user_ids
+  :do:
+    id: update_last_seen
+    type: MongoDBUpdateOne
+    connectionId: users
+    properties:
+      filter:
+        _id:
+          _item: user_id
+      update:
+        $set:
+          last_seen:
+            _date: now
+```

package/content/controls/reject.md

@@ -0,0 +1,56 @@
+# :reject
+
+```
+({:reject: string, :cause: any}): void
+```
+
+The `:reject` control is used to return a user-friendly error to the client when validation fails or business rules are violated.
+Unlike [`:throw`](/:throw), which indicates a system error, `:reject` represents an expected failure condition that should be communicated to the user.
+The control immediately stops routine execution and returns with a `"reject"` status.
+Importantly, `:reject` does not trigger `:catch` blocks in [`:try`](/:try) statements, making it ideal for handling validation and business logic errors separately from system errors.
+
+#### Keys
+
+- `:reject: string`: __Required__ - The error message that will be returned in the response object of the API call result.
+- `:cause: any`: Additional metadata that will be returned with the error message.
+
+#### Examples
+
+###### Example
+
+```yaml
+- id: check_inventory
+  type: MongoDBFindOne
+  connectionId: products
+  properties:
+    query:
+      product_id:
+        _payload: product_id
+- :if:
+    _lt:
+      - _step: check_inventory.quantity
+      - _payload: requested_quantity
+  :then:
+    :reject:
+      _string.concat:
+        - "Insufficient inventory. Only "
+        - _step: check_inventory.quantity
+        - " items available"
+```
+
+###### Reject with Additional Context
+
+```yaml
+- :if:
+    _not:
+      _step: get_user.email_verified
+  :then:
+    :reject: "Please verify your email before proceeding"
+    :cause:
+      user_id:
+        _step: get_user._id
+      email:
+        _step: get_user.email
+      account_created_at:
+        _step: get_user.created_at
+```

package/content/controls/return.md

@@ -0,0 +1,66 @@
+# :return
+
+```
+({:return: any}): void
+```
+
+The `:return` control immediately ends the execution of an API endpoint routine and returns a successful response with the specified data.
+Any routine steps after a `:return` are not executed. The control accepts any value type (objects, arrays, strings, numbers, null) and marks the API call as successful.
+When used within conditional controls like [`:if`](/:if) or [`:switch`](/:switch), it provides a way to exit early with a success status and return data to the client.
+
+The `:return` control also works in client [event action lists](/events-and-actions) — it ends the whole event successfully, the event's `catch` actions do not run, and any actions after it are recorded as skipped. Inside a `catch` action list, `:return` ends the remaining catch actions the same way, but the event keeps its error result — `success` stays `false`.
+
+#### Keys
+
+- `:return: any`: __Required__ - The value that will be returned in the response object of the API call result.
+
+#### Examples
+
+###### Return Step Result
+
+```yaml
+- id: get_company
+  type: MongoDBInsertOne
+  connectionId: companies
+  properties:
+    doc:
+      _id:
+        _payload: company_id
+- :return:
+    _step: get_company
+```
+
+###### Switch with multiple returns
+
+```yaml
+- id: get_user_subscription
+  type: MongoDBFindOne
+  connectionId: subscriptions
+  properties:
+    query:
+      user_id:
+        _user: id
+- :switch:
+    - :case:
+        _not:
+          _step: get_user_subscription
+      :then:
+        :return:
+          plan: "free"
+          features: ["basic_access"]
+          limit: 10
+    - :case:
+        _eq:
+          - _step: get_user_subscription.type
+          - "premium"
+      :then:
+        :return:
+          plan: "premium"
+          features: ["full_access", "priority_support", "api_access"]
+          limit: -1
+  :default:
+    :return:
+      plan: "standard"
+      features: ["standard_access", "email_support"]
+      limit: 100
+```

package/content/controls/set_state.md

@@ -0,0 +1,98 @@
+# :set_state
+
+```
+({:set_state: object}): void
+```
+
+The `:set_state` control sets values in the server-side state object during API endpoint execution.
+It accepts an object where each key-value pair is saved to the state, making data available throughout the routine via the `_state` operator.
+This server state is isolated to the current API call and does not persist between calls or affect client state. The control supports nested paths using dot notation and can store any data type.
+Values are evaluated before being set, allowing dynamic state updates based on previous operations.
+
+#### Keys
+
+- `:set_state: object`: __Required__ - Object to be saved to server state.
+
+#### Examples
+
+###### Accumulating Values
+```yaml
+- :set_state:
+    total: 0
+    count: 0
+- :for: product
+  :in:
+    _payload: products
+  :do:
+    - :set_state:
+        total:
+          _sum:
+            - _state: total
+            - _item: product.price
+        count:
+          _sum:
+            - _state: processed_count
+            - 1
+- :return:
+    total:
+      _state: total
+    count:
+      _state: count
+```
+
+###### Dot Notation
+```yaml
+- :set_state:
+    user:
+      _step: get_user
+- :set_state:
+    user.profile.name:
+      _string.concat:
+        - _state: user.profile.first_name
+        - ' '
+        - _state: user.profile.last_name
+```
+
+###### Shared Value
+```yaml
+- :set_state:
+    product_id:
+      _uuid: true
+- id: insert_product
+  type: MongoDBInsertOne
+  connectionId: tickets
+  properties:
+    doc:
+      _id:
+        _state: product_id
+      name:
+        _payload: product_name
+      created_at:
+        _date: now
+
+- id: insert_new_product_event
+  type: MongoDBInsertOne
+  connectionId: events
+  properties:
+    doc:
+      _id:
+        _uuid: true
+      type: new-product
+      description:
+        _nunjucks:
+          template: New product {{ product_name }} created by {{ user_name }}.
+          on:
+            product_name:
+              _payload: product_name
+            user_name:
+              _user: name
+      product_id:
+        _state: product_id
+      user:
+        id:
+          _user: id
+        name:
+          _user: name
+      timestamp:
+        _date: now
+```

package/content/controls/switch.md

@@ -0,0 +1,90 @@
+# :switch
+
+```
+({:switch: [{:case: boolean, :then: routine], :default: routine}): void
+```
+
+The `:switch` control evaluates multiple conditions sequentially and executes the routine for the first matching case.
+Each case in the `:switch` array contains a `:case` condition and a `:then` routine.
+The control evaluates conditions from top to bottom, executing only the first matching case's `:then` block.
+If no cases match, the optional `:default` routine is executed.
+This control is ideal for handling multiple mutually exclusive conditions more elegantly than nested [`:if`](/:if) statements.
+
+The `:switch` control also works in client [event action lists](/events-and-actions) — there each `:then` and `:default` is a list of actions, and the same syntax and semantics apply.
+
+#### Keys
+
+- `:switch: array`: __Required__
+    - `:case: boolean`: __Required__ - The boolean result of a test.
+    - `:then: routine`: __Required__ - The routine to execute if the test is `true`.
+- `:default: routine`:  The routine to execute if all the `:case` tests are `false`.
+
+#### Examples
+
+###### Validation
+```yaml
+- :switch:
+    - :case:
+        _not:
+          _payload: email
+      :then:
+        :reject: "Email is required"
+    - :case:
+        _not:
+          _regex:
+            on:
+              _payload: email
+            pattern: ^[^@]+@[^@]+\\.[^@]+$
+      :then:
+        :reject: "Invalid email format"
+    - :case:
+        _lt:
+          - _string.length:
+              _payload: password
+          - 8
+      :then:
+        :reject: "Password must be at least 8 characters"
+    - :case:
+        _not:
+          _eq:
+            - _payload: password
+            - _payload: confirm_password
+      :then:
+        :reject: "Passwords do not match"
+  :default: []
+```
+
+###### Switch with multiple returns
+
+```yaml
+- id: get_user_subscription
+  type: MongoDBFindOne
+  connectionId: subscriptions
+  properties:
+    filter:
+      user_id:
+        _user: id
+- :switch:
+    - :case:
+        _not:
+          _step: get_user_subscription
+      :then:
+        :return:
+          plan: "free"
+          features: ["basic_access"]
+          limit: 10
+    - :case:
+        _eq:
+          - _step: get_user_subscription.type
+          - "premium"
+      :then:
+        :return:
+          plan: "premium"
+          features: ["full_access", "priority_support", "api_access"]
+          limit: -1
+  :default:
+    :return:
+      plan: "standard"
+      features: ["standard_access", "email_support"]
+      limit: 100
+```

package/content/controls/throw.md

@@ -0,0 +1,79 @@
+# :throw
+
+```
+({:throw: string, :cause: any}): void
+```
+
+The `:throw` control creates a system error that immediately stops routine execution and returns with an "error" status.
+Unlike [`:reject`](/:reject), which handles expected user errors, `:throw` is designed for unexpected system failures, programming errors, or critical issues that require attention.
+The key difference is that `:throw` can be caught and handled by [`:try`](/:try)/`:catch` blocks, while [`:reject`](/:reject) cannot.
+This makes `:throw` ideal for recoverable system errors where you might want to implement fallback logic.
+
+#### Keys
+
+- `:throw: string`: __Required__ - The error message that will be returned in the response object of the API call result.
+- `:cause: any`: Additional metadata that will be returned with the error message.
+
+#### Examples
+
+###### Throw on invalid status
+```yaml
+- :switch:
+    - :case:
+        _eq:
+          - _payload: status
+          - accept
+      :then:
+        - :return:
+            message: Accepted
+    - :case:
+        _eq:
+          - _payload: status
+          - deny
+      :then:
+        - :return:
+            message: Denied
+    - :case:
+        _eq:
+          - _payload: status
+          - more_info_required
+      :then:
+        - :return:
+            message: More info required
+  :default:
+    - :throw: 'Invalid status type'
+      :cause:
+        status:
+          _payload: status
+```
+
+###### Throw on invalid configuration
+```yaml
+- id: get_system_config
+  type: MongoDBFindOne
+  connectionId: config
+  properties:
+    query:
+      name: 'max_file_size'
+
+- :if:
+    _not:
+      _step: get_system_config
+  :then:
+    :throw: 'System configuration missing: max_file_size not found'
+
+- :if:
+    _gt:
+      - _payload: file_size
+      - _step: get_system_config.value
+  :then:
+    :throw: 'File size exceeds system limit'
+    :cause:
+      maxAllowed:
+        _step: get_system_config.value
+      received:
+        _payload: file_size
+
+- :return:
+    message: 'File upload validated'
+```

package/content/controls/try.md

@@ -0,0 +1,88 @@
+# :try
+
+```
+({:try: routine, :catch: routine, :finally: routine}): void
+```
+
+If one control in the routine chain defined in the `:try` key fails by throwing an error, the steps in the list following the failed control will not be executed.
+To handle any errors thrown by a routine element, a routine can be provided using `catch` key.
+The routine defined using the `:finally` key will be run regardless of whether or not the routine throws an error.
+
+#### Keys
+
+- `:try: routine`: __Required__ - The routine to be run.
+- `:catch: routine`: The routine to execute if any step in the routine defined errors.
+- `:finally: routine`: The routine to be run regardless of the out come of the initial routine.
+
+#### Examples
+
+###### Try external API with fallback
+```yaml
+- :try:
+    - id: get_weather
+      type: AxiosHttp
+      connectionId: weather-api
+      properties:
+        url: /current
+        params:
+          city:
+            _payload: city
+  :catch:
+    - id: get_default_weather
+      type: MongoDBFindOne
+      connectionId: weather-cache
+      properties:
+        query:
+          city:
+            _payload: city
+- :return:
+    weather:
+      _if:
+        test:
+          _step: get_weather
+        then:
+          _step: get_weather.data
+        else:
+          _step: get_default_weather
+```
+
+###### Try database operation with fallback
+```yaml
+- :try:
+    - id: update_user
+      type: MongoDBUpdateOne
+      connectionId: database
+      properties:
+        filter:
+          _id:
+            _payload: user._id
+        update:
+          $set:
+            last_login:
+              _date: now
+  :catch:
+    - :log:
+        message: 'Database update failed, creating new user record'
+        user_id:
+          _payload: user._id
+      :level: warn
+    - id: create_user
+      type: MongoDBInsertOne
+      connectionId: database
+      properties:
+        doc:
+          _id:
+            _payload: user._id
+          last_login:
+            _date: now
+          created_at:
+            _date: now
+  :finally:
+    - :log:
+        message: 'User login process completed'
+      :level: info
+- :return:
+    success: true
+    user_id:
+      _payload: user._id
+```