@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/operators/_regex.md

@@ -0,0 +1,69 @@
+# _regex
+
+```
+(pattern: string): boolean
+(arguments: {
+  pattern: string,
+  on?: string,
+  key?: string,
+  flags?: string
+}): boolean
+```
+
+The `_regex` operator performs a regex test on a string, and returns `true` if there is a match.
+
+The regex operator has shorthand argument definitions that can be used on web client.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### object
+  - `pattern: string`: __Required__ - The regular expression pattern to test.
+  - `on: string`: The string to test the value on. One of `on` or `key` must be specified unless the operator is used in an input block.
+  - `key: string`: The key of a value in `state` to test. One of `on` or `key` must be specified unless the operator is used in an input block.
+  - `flags: string`: The regex flags to use. The default value is `"gm"`.
+
+###### string
+The regular expression pattern to test. The string shorthand can only be used in an input block, and the tested value will be the block's value.
+
+#### Examples
+
+###### Check if a username is valid (Alphanumeric string that may include _ and – having a length of 3 to 16 characters):
+```yaml
+_regex:
+  pattern: ^[a-z0-9_-]{3,16}$
+  on:
+    _state: username_input
+```
+Returns: `true` if matched else `false`.
+
+###### Using the key of the value in `state`:
+```yaml
+_regex:
+  pattern: ^[a-z0-9_-]{3,16}$
+  key: username_input
+```
+Returns: `true` if matched else `false`.
+
+###### Using the value of the block in which the operator is evaluated:
+```yaml
+id: username_input
+type: TextInput
+validate:
+  - message: Invalid username.
+    status: error
+    pass:
+      _regex: ^[a-z0-9_-]{3,16}$
+```
+Returns: `true` if matched else `false`.
+
+###### Case insensitive match:
+```yaml
+_regex:
+  pattern: ^[a-z0-9_-]{3,16}$
+  on:
+    _state: username_input
+  flags: 'gmi'
+```
+Returns: `true` if matched else `false`.

package/content/operators/_request.md

@@ -0,0 +1,35 @@
+# _request
+
+```
+(requestId: string): any
+```
+
+The `_request` operator returns the response value of a request. If the request has not yet been called, or is still executing, the returned value is `null`. Dot notation and [block list indexes](/lists) are supported. For more detailed information about a request, the [_request_details](/_request_details) operator can be used.
+
+If the request was called via the [`Request`](/Request) action with `holdValue: true`, `_request` returns the previous response while the new request is loading instead of returning `null`. Use `_request_details: <id>.loading` to detect that a new call is still in-flight, and `_request_details: <id>.error` to detect a failure.
+
+#### Arguments
+
+###### string
+The id of the request.
+
+#### Examples
+
+###### Using a request response:
+```yaml
+_request: my_request
+```
+Returns: The response returned by the request.
+
+###### Using dot notation to get the data object from the response:
+```yaml
+_request: my_request.data
+```
+###### Using dot notation to get the first element of an array response:
+```yaml
+_request: array_request.0
+```
+###### Using dot notation and block list indexes to get the name field from the element corresponding to the block index of an array response:
+```yaml
+_request: array_request.$.name
+```

package/content/operators/_request_details.md

@@ -0,0 +1,29 @@
+# _request_details
+
+```
+(requestId: string): any
+```
+
+The `_request_details` operator returns detailed information of a request. If the request has not yet been called, the returned value is `null`.
+
+The response includes the following fields:
+
+- `blockId: string`: The id of the block from which the request was initiated.
+- `loading: boolean`: When `true`, the request is awaiting a response.
+- `payload: object`: The payload sent with the request.
+- `requestId: string`: The id of the request.
+- `response: object`: The response returned by the request. `null` while `loading` is true.
+- `responseTime: number`: The time taken to get the response in milliseconds.
+
+#### Arguments
+
+###### string
+The id of the request.
+
+#### Examples
+
+###### Using a request id:
+```yaml
+_request_details: my_request
+```
+Returns: The details of the specified request.

package/content/operators/_secret.md

@@ -0,0 +1,56 @@
+# _secret
+
+```
+(key: string): any
+(all: boolean): any
+(arguments: {
+  all?: boolean,
+  key?: string,
+  default?: any
+}): any
+```
+
+The `_secret` operator gets a value from the [`secret`](/context-and-secret) object. The `secrets` is a data object that contains sensitive information like passwords or API keys. The `_secret` operator can only be used in `connections` and `requests`. Secrets are read from environment variables on the server that start with `LOWDEFY_SECRET_`, (i.e. `LOWDEFY_SECRET_SECRET_NAME`). The name of the secret is the part after `LOWDEFY_SECRET_`. Since environment variables can only be strings, secrets can be JSON encoded, and parsed using the [`_json.parse`](/_json) method.
+
+#### Arguments
+
+###### string
+If the `_secret` operator is called with a string argument, the value of the key in the `secrets` object is returned. If the value is not found, `null` is returned.
+
+###### boolean
+If the `_secret` operator is called with boolean argument `true`, the entire `secrets` object is returned.
+
+###### object
+  - `all: boolean`: If `all` is set to `true`, the entire `secrets` object is returned. One of `all` or `key` are required.
+  - `key: string`: The value of the key in the `secrets` object is returned. If the value is not found, `null`, or the specified default value is returned. One of `all` or `key` are required.
+  - `default: any`: A value to return if the `key` is not found in `secrets`. By default, `null` is returned if a value is not found.
+
+#### Examples
+
+###### Get the value of `MY_SECRET` from `secrets`:
+```yaml
+_secret: MY_SECRET
+```
+```yaml
+_secret:
+  key: MY_SECRET
+```
+Returns: The value of `MY_SECRET` in `secrets`.
+
+###### Get the entire `secret` object:
+```yaml
+_secret: true
+```
+```yaml
+_secret:
+  all: true
+```
+Returns: The entire `secrets` object.
+
+###### Return a default value if the value is not found:
+```yaml
+_secret:
+  key: MY_SECRET
+  default: Not so secret
+```
+Returns: The value of `MY_SECRET`, or `"Not so secret"`.

package/content/operators/_state.md

@@ -0,0 +1,134 @@
+# _state
+
+```
+(key: string): any
+(all: boolean): any
+(arguments: {
+  all?: boolean,
+  key?: string,
+  default?: any,
+}): any
+```
+
+If used in a block, the `_state` operator gets a value from the [`state`](/page-and-app-state) object. The `state` is a data object specific to the page it is in. The value of `input` blocks are available in `state`, with their `blockId` as key.
+
+If used in an API endpoint, the `_state` operator gets a value from the API endpoints state. The `state` is a data object specific to that execution of the API endpoint.
+
+#### Arguments
+
+###### string
+If the `_state` operator is called with a string argument, the value of the key in the `state` object is returned. If the value is not found, `null` is returned. Dot notation and [block list indexes](/lists) are supported.
+
+###### boolean
+If the `_state` operator is called with boolean argument `true`, the entire `state` object is returned.
+
+###### object
+  - `all: boolean`: If `all` is set to `true`, the entire `state` object is returned. One of `all` or `key` are required.
+  - `key: string`: The value of the key in the `state` object is returned. If the value is not found, `null`, or the specified default value is returned. Dot notation and [block list indexes](/lists) are supported. One of `all` or `key` are required.
+  - `default: any`: A value to return if the `key` is not found in `state`. By default, `null` is returned if a value is not found.
+
+#### Examples
+
+###### Get the value of `my_key` from `state`:
+```yaml
+_state: my_key
+```
+```yaml
+_state:
+  key: my_key
+```
+Returns: The value of `my_key` in `state`.
+
+###### Get the entire `state` object:
+```yaml
+_state: true
+```
+```yaml
+_state:
+  all: true
+```
+Returns: The entire `state` object.
+
+###### Dot notation:
+Assuming state:
+```yaml
+my_object:
+  subfield: 'Value'
+```
+then:
+```yaml
+_state: my_object.subfield
+```
+```yaml
+_state:
+  key: my_object.subfield
+```
+Returns: `"Value"`.
+
+###### Return a default value if the value is not found:
+```yaml
+_state:
+  key: might_not_exist
+  default: Default value
+```
+Returns: The value of `might_not_exist`, or `"Default value"`.
+
+###### Block list indices:
+Assuming `state`:
+```yaml
+my_array:
+  - value: 0
+  - value: 1
+  - value: 2
+```
+then:
+```yaml
+_state: my_array.$.value
+```
+Returns: `0` when used from the first block (0th index) in a list.
+
+###### Using `_state` with `:set_state` in an API endpoint
+
+```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/operators/_step.md

@@ -0,0 +1,98 @@
+# _step
+
+```
+(stepId: string): any
+```
+
+The `_step` operator returns the response value from a previously executed step in an API routine. This operator is only available within API routines and allows later steps to access data from earlier steps. If the step has not yet been executed or is still executing, the returned value is `null`. Dot notation and array indexes are supported for accessing nested properties.
+
+#### Arguments
+
+###### string
+The id of a step that has already been executed in the current API routine.
+
+#### Examples
+
+###### Using a step response:
+```yaml
+routine:
+  - id: get_user
+    type: MongoDBFindOne
+    connectionId: users
+    properties:
+      query:
+        email:
+          _payload: email
+
+  - :return:
+      _step: get_user
+```
+Returns: The complete response object returned by the `get_user` step.
+
+###### Using dot notation to access nested properties:
+```yaml
+routine:
+  - id: get_user
+    type: MongoDBFindOne
+    connectionId: users
+    properties:
+      query:
+        email:
+          _payload: email
+
+  - id: get_orders
+    type: MongoDBFind
+    connectionId: orders
+    properties:
+      query:
+        userId:
+          _step: get_user._id  # Access the _id field from get_user
+```
+
+###### Using array indexes:
+```yaml
+routine:
+  - id: get_products
+    type: MongoDBFind
+    connectionId: products
+    properties:
+      query:
+        category: 'electronics'
+
+  - :return:
+      first_product:
+        _step: get_products.0  # Access the first element of the array
+      first_product_name:
+        _step: get_products.0.name  # Access a property of the first element
+```
+
+###### Chaining multiple steps:
+```yaml
+routine:
+  - id: create_order
+    type: MongoDBInsertOne
+    connectionId: orders
+    properties:
+      doc:
+        items:
+          _payload: items
+        total:
+          _payload: total
+
+  - id: send_confirmation
+    type: SendGridMail
+    connectionId: email-service
+    properties:
+      to:
+        _payload: customer_email
+      template_data:
+        order_id:
+          _step: create_order.insertedId  # Use the inserted document's ID
+
+  - :return:
+      success: true
+      order_id:
+        _step: create_order.insertedId
+      email_sent:
+        _step: send_confirmation.success
+```