@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/operators/_input.md

@@ -0,0 +1,86 @@
+# _input
+
+```
+(key: string): any
+(all: boolean): any
+(arguments: {
+  all?: boolean,
+  key?: string,
+  default?: any,
+}): any
+```
+
+The `_input` operator gets a value from the [`input`](/page-and-app-state) object. The `input` is a data object that can be set when linking to a new page using the [`Link`](/link) action, and can be used to set data like a `id` when switching to a new page. Unlike `urlQuery`, the `input` is not visible, and cannot be changed by the user, but if the page is reloaded, the `input` is lost.
+
+#### Arguments
+
+###### string
+If the `_input` operator is called with a string argument, the value of the key in the `input` object is returned. If the value is not found, `null` is returned. Dot notation and [block list indexes](/lists) are supported.
+
+###### boolean
+If the `_input` operator is called with boolean argument `true`, the entire `input` object is returned.
+
+###### object
+  - `all: boolean`: If `all` is set to `true`, the entire `input` object is returned. One of `all` or `key` are required.
+  - `key: string`: The value of the key in the `input` 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 `input`. By default, `null` is returned if a value is not found.
+
+#### Examples
+
+###### Get the value of `my_key` from `input`:
+```yaml
+_input: my_key
+```
+```yaml
+_input:
+  key: my_key
+```
+Returns: The value of `my_key` in `input`.
+
+###### Get the entire `input` object:
+```yaml
+_input: true
+```
+```yaml
+_input:
+  all: true
+```
+Returns: The entire `input` object.
+
+###### Dot notation:
+Assuming input:
+```yaml
+my_object:
+  subfield: 'Value'
+```
+then:
+```yaml
+_input: my_object.subfield
+```
+```yaml
+_input:
+  key: my_object.subfield
+```
+Returns: `"Value"`.
+
+###### Return a default value if the value is not found:
+```yaml
+_input:
+  key: might_not_exist
+  default: Default value
+```
+Returns: The value of `might_not_exist`, or `"Default value"`.
+
+###### Block list indices:
+Assuming `input`:
+```yaml
+my_array:
+  - value: 0
+  - value: 1
+  - value: 2
+```
+then:
+```yaml
+_input: my_array.$.value
+```
+Returns: `0` when used from the first block (0th index) in a list.

package/content/operators/_intl.md

@@ -0,0 +1,135 @@
+# _intl
+
+The `_intl` operator converts date objects to strings, using a specified format.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+# Operator methods:
+
+## _intl.dateTimeFormat
+
+```
+(arguments: {
+  on: date,
+  locale?: string,
+  options?: object
+})
+```
+
+The `_intl.dateTimeFormat` provides language-sensitive date and time formatting, based on [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat). If no locale is provide, the users default locale will be used.
+
+#### Arguments
+
+###### object
+  - `on: date`: The date object to format.
+  - `locale: string`: A string with a BCP 47 language tag, or an array of such strings.
+  - `options: object`: [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) options.
+
+#### Examples
+
+###### Format a date:
+```yaml
+_intl.dateTimeFormat:
+  on:
+    _date: 2019-06-13
+  locale: en
+  options:
+    weekday: long
+    year: numeric
+    month: long
+    day: numeric
+```
+Returns: `"Thursday, June 13, 2019"`.
+
+## _intl.listFormat
+
+```
+(arguments: {
+  on: any[],
+  locale?: string,
+  options?: object
+})
+```
+
+The `_intl.listFormat` provides language-sensitive list formatting, based on [`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat). If no locale is provide, the users default locale will be used.
+
+#### Arguments
+
+###### object
+  - `on: any[]`: The array to format.
+  - `locale: string`: A string with a BCP 47 language tag, or an array of such strings.
+  - `options: object`: [`Intl.ListFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/ListFormat/ListFormat) options.
+
+#### Examples
+
+###### Format a list:
+```yaml
+_intl.listFormat:
+  on:
+    - Motorcycle
+    - Bus
+    - Car
+  locale: fr
+```
+Returns: `"Motorcycle, Bus et Car"`.
+
+## _intl.numberFormat
+
+```
+(arguments: {
+  on: number,
+  locale?: string,
+  options?: object
+})
+```
+
+The `_intl.numberFormat` provides language-sensitive number formatting, based on [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat). If no locale is provide, the users default locale will be used.
+
+#### Arguments
+
+###### object
+  - `on: number`: The number to format.
+  - `locale: string`: A string with a BCP 47 language tag, or an array of such strings.
+  - `options: object`: [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) options.
+
+#### Examples
+
+###### Format a number:
+```yaml
+_intl.numberFormat:
+  on: 13182375813.47422
+  locale: de
+```
+Returns: `"13.182.375.813,474"`.
+
+## _intl.relativeTimeFormat
+
+```
+(arguments: {
+  on: any,
+  locale?: string,
+  unit: enum,
+  options?: object
+})
+```
+
+The `_intl.relativeTimeFormat` provides language-sensitive relative time  formatting, based on [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat). If no locale is provide, the users default locale will be used.
+
+#### Arguments
+
+###### object
+  - `on: number`: The number to format.
+  - `locale: string`: A string with a BCP 47 language tag, or an array of such strings.
+  - `unit: enum`: Unit to use in the relative time internationalized message. Possible values are: `year`, `quarter`, `month`, `week`, `day`, `hour`, `minute`, `second`. Plural forms are also permitted.
+  - `options: object`: [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat) options.
+
+#### Examples
+
+###### Format a number:
+```yaml
+_intl.relativeTimeFormat:
+  on: 4
+  unit: 'days'
+  locale: fr
+```
+Returns: `"dans 4 jours"`.

package/content/operators/_item.md

@@ -0,0 +1,166 @@
+# _item
+
+```
+(key: string): any
+```
+
+The `_item` operator returns the current item value during iteration in [`:for`](/:for) and [`:parallel_for`](/:parallel_for) loop control structures within API routines.
+The key used with `_item` must match the key defined in the relevant loop control declaration because it also supports nested loops.
+Dot notation is supported for accessing nested properties.
+
+#### Arguments
+
+###### string
+The key name defined in the relevant loop control structure.
+
+#### Examples
+
+###### Using in a :for loop:
+```yaml
+routine:
+  - :for: user_id
+    :in:
+      _payload: user_ids
+    :do:
+      - id: update_user
+        type: MongoDBUpdateOne
+        connectionId: users
+        properties:
+          filter:
+            _id:
+              _item: user_id  # Access the current user_id
+          update:
+            $set:
+              last_seen:
+                _date: now
+```
+Returns: The current value from the array being iterated over.
+
+###### Using dot notation to access nested properties:
+```yaml
+routine:
+  - :for: product
+    :in:
+      _payload: products  # Array of product objects
+    :do:
+      - id: update_product
+        type: MongoDBUpdateOne
+        connectionId: products
+        properties:
+          filter:
+            _id:
+              _item: product._id  # Access the _id field of current product
+          update:
+            $set:
+              name:
+                _item: product.name
+              price:
+                _item: product.price
+              category:
+                _item: product.category
+              last_updated:
+                _date: now
+
+      - :log:
+          message: 'Processing product'
+          product_name:
+            _item: product.name
+          product_sku:
+            _item: product.sku
+```
+
+###### Using in :parallel_for loop for concurrent processing:
+```yaml
+routine:
+  - id: get_orders
+    type: MongoDBFind
+    connectionId: orders
+    properties:
+      query:
+        status: 'pending'
+
+  - :parallel_for: order
+    :in:
+      _step: get_orders
+    :do:
+      - id: send_notification
+        type: SendGridMail
+        connectionId: email-service
+        properties:
+          to:
+            _item: order.customer_email
+          template_id: 'order_confirmation'
+          dynamic_template_data:
+            order_id:
+              _item: order._id
+            total:
+              _item: order.total
+            items:
+              _item: order.items
+```
+
+###### Nested loops with multiple _item references:
+```yaml
+routine:
+  - :for: category
+    :in:
+      _payload: categories
+    :do:
+      - :for: product
+        :in:
+          _item: category.products  # Access products array from outer loop item
+        :do:
+          - id: update_product
+            type: MongoDBUpdateOne
+            connectionId: products
+            properties:
+              filter:
+                _id:
+                  _item: product._id
+              update:
+                $set:
+                  category_name:
+                    _item: category.name  # Access outer loop item
+                  category_id:
+                    _item: category._id
+                  product_rank:
+                    _item: product.rank  # Access inner loop item
+```
+
+###### Accumulating values with _item:
+```yaml
+routine:
+  - :set_state:
+      total: 0
+      processed_count: 0
+
+  - :for: item
+    :in:
+      _payload: order_items
+    :do:
+      - :set_state:
+          total:
+            _sum:
+              - _state: total
+              - _product:
+                  - _item: item.price
+                  - _item: item.quantity
+          processed_count:
+            _sum:
+              - _state: processed_count
+              - 1
+
+      - :log:
+          processing_item:
+            _item: item.name
+          item_total:
+            _product:
+              - _item: item.price
+              - _item: item.quantity
+
+  - :return:
+      total:
+        _state: total
+      items_processed:
+        _state: processed_count
+```

package/content/operators/_js.md

@@ -0,0 +1,113 @@
+# _js
+
+> This operator is experimental and may change in future versions.
+
+```
+(function: string): any
+(function: { fn: string, args?: object }): any
+```
+
+The `_js` operator enables the use of custom JavaScript logic within Lowdefy configuration where operators are evaluated. The purpose of this operator is to facilitate quick implementation of fast, synchronous functions. Like other operators, these functions are evaluated during page render, thus slow functions can impact app performance.
+For more advanced logic, or when the use of external dependencies is necessary, instead develop a [custom plugin](/plugins-introduction).
+
+#### Using Lowdefy operators in JavaScript
+Certain Lowdefy operators can be used inside of the JavaScript function block. These operators are available as functions and will take their standard arguments.
+
+###### Client JavaScript function prototype:
+_Function parameters passed to the operator method._
+```js
+function ({ actions, args, event, input, location, lowdefyApp, lowdefyGlobal, request, state, urlQuery, user }) {
+  // Your JavaScript code here
+};
+```
+
+The function arguments available to the JavaScript function are:
+  - `actions: function`: Implements the [_actions](/_actions) operator.
+  - `args: object`: Pre-resolved values passed via the object form of `_js` (see below). `undefined` when the string form is used.
+  - `event: function`: Implements the [_event](/_event) operator.
+  - `input: function`: Implements the [_input](/_input) operator.
+  - `location: function`: Implements the [_location](/_location) operator.
+  - `lowdefyApp: function`: Implements the [_app](/_app) operator.
+  - `lowdefyGlobal: function`: Implements the [_global](/_global) operator.
+  - `request: function`: Implements the [_request](/_request) operator.
+  - `state: function`: Implements the [_state](/_state) operator.
+  - `urlQuery: function`: Implements the [_url_query](/_url_query) operator.
+  - `user: function`: Implements the [_user](/_user) operator.
+
+###### Server JavaScript function prototype:
+_Function parameters passed to the operator method._
+```js
+function ({ args, item, lowdefyApp, payload, secret, state, step, user }) {
+  // Your JavaScript code here
+};
+```
+
+The function arguments available to the JavaScript function are
+  - `args: object`: Pre-resolved values passed via the object form of `_js` (see below). `undefined` when the string form is used.
+  - `item: function`: Implements the [_item](/_item) operator.
+  - `lowdefyApp: function`: Implements the [_app](/_app) operator.
+  - `payload: function`: Implements the [_payload](/_payload) operator.
+  - `secret: function`: Implements the [_secret](/_secret) operator.
+  - `state: function`: Implements the [_state](/_state) operator.
+  - `step: function`: Implements the [_step](/_step) operator.
+  - `user: function`: Implements the [_user](/_user) operator.
+
+#### Passing pre-computed values with `args`
+The object form of `_js` accepts an `args` object whose values are resolved by the parser **before** the JavaScript function runs. This lets you compute values using any Lowdefy operator (`_state`, `_request`, `_user`, etc.) and consume them inside the function without calling operator methods from JavaScript.
+
+#### Arguments
+
+###### string
+The JavaScript function body, including the function return statement, excluding the function prototype.
+
+###### object
+An object with the following properties:
+  - `fn: string`: The JavaScript function body (same as the string form).
+  - `args: object`: (optional) Values to inject into the function. Each value is evaluated as a normal Lowdefy expression and made available inside `fn` on the `args` object.
+
+#### Examples
+
+###### Perform a calculation:
+```js
+_js: |
+  let x = state('input_1');
+  let y = state('input_2');
+  return x + y;
+```
+
+###### Create custom logic based on data from a request:
+```js
+_js: |
+  const products = request('get_products').data?.products ?? [];
+  const laptopsWithRatingGreaterThan4 = products.filter(product =>
+      product.category === "laptops" && product.rating > 4
+  );
+  if (laptopsWithRatingGreaterThan4.length > 3) {
+      return true;
+  }
+  return false;
+```
+
+###### Chain array methods on request data:
+```js
+_js: |
+  const products = request('get_products').data?.products ?? [];
+  const totalPriceOfPhones = products
+      .filter(product => product.category === "smartphones")
+      .reduce((acc, product) => acc + product.price, 0);
+  return totalPriceOfPhones;
+```
+
+###### Pass pre-computed values with `args`:
+```yaml
+_js:
+  fn: |
+    const { products, target } = args;
+    return products
+        .filter(p => p.category === target)
+        .reduce((a, p) => a + p.price, 0);
+  args:
+    products:
+      _request: get_products.data.products
+    target: smartphones
+```

package/content/operators/_json.md

@@ -0,0 +1,120 @@
+# _json
+
+The `_json` parses and writes JSON strings.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+# Operator methods:
+
+## _json.parse
+
+```
+(value: string): any
+```
+
+The `_json.parse` method parses a JSON string into an object.
+
+#### Arguments
+
+###### string
+The string to parse.
+
+#### Examples
+
+###### Parse a JSON string:
+```yaml
+_json.parse: '{"key": "Value", "boolean": true, "array": [1, 2]}'
+```
+Returns:
+```
+key: Value
+boolean: true
+array:
+  - 1
+  - 2
+```
+
+## _json.stringify
+
+```
+({on: any, options?: object}): string
+([on: any, options?: object]): string
+```
+
+The `_json.stringify` method creates a JSON string from an object.
+
+#### Arguments
+
+###### object
+  - `on: any`: The object to stringify.
+  - `options: object`: Optional settings.
+    - `stable: boolean`: If set to true, equal objects will be stringified to the same string. Object keys are sorted.
+    - `space: number | string`: Used to insert whitespace to increase legibility. If a number, it is the number of space character to use. If a string, the string is used as whitespace. The default is `2`.
+
+#### Examples
+
+###### Stringify an object as JSON:
+```yaml
+_json.stringify:
+  on:
+    key: Value
+    boolean: true
+    array:
+      - 1
+      - 2
+```
+```yaml
+_json.stringify:
+  - key: Value
+    boolean: true
+    array:
+      - 1
+      - 2
+```
+Returns (as a string):
+```text
+'{
+  "key": "Value",
+  "boolean": true,
+  "array": [
+    1,
+    2
+  ]
+}'
+```
+###### Stable option:
+```yaml
+_json.stringify:
+  on:
+    key: Value
+    boolean: true
+    array:
+      - 1
+      - 2
+  options:
+    stable: true
+```
+Returns (as a string):
+```text
+'{
+  "array": [
+    1,
+    2
+  ],
+  "boolean": true,
+  "key": "Value"
+}''
+```
+###### Space option:
+```yaml
+_json.stringify:
+  on:
+    key: Value
+    boolean: true
+    array:
+      - 1
+      - 2
+  options:
+    space: 0
+```
+Returns `'{"key":"Value","boolean":true,"array":[1,2]}'`