@lowdefy/docs-content 0.0.0-experimental-20260710073520

package/content/operators/_array.md

@@ -0,0 +1,331 @@
+# _array
+
+The `_array` operator can be used to run javascript [`Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) methods.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+# Operator methods:
+
+## _array.concat
+
+```
+(arrays: any[][]): any[]
+```
+
+The `_array.concat` method [concatenates](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) arrays.
+
+## _array.copyWithin
+
+```
+(arguments: {
+  on: any[],
+  target: number,
+  start?: number,
+  end?: number
+}): any[]
+(arguments: [
+  on: any[],
+  target: number,
+  start?: number,
+  end?: number
+]): any[]
+```
+
+The `_array.copyWithin` method [copies part of an array to another location in the same array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/copyWithin) without modifying its length.
+
+## _array.every
+
+```
+(arguments: {
+  on: any[],
+  callback: function,
+}): boolean
+(arguments: [
+  on: any[],
+  callback: function,
+]): boolean
+```
+
+The `_array.every` method  tests whether [all elements in the array pass](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/every) the test implemented by the provided function. It returns a Boolean value.
+
+## _array.fill
+
+```
+(arguments: {
+  on: any[],
+  value: any,
+  start?: number,
+  end?: number
+}): any[]
+(arguments: [
+  on: any[],
+  value: number,
+  start?: number,
+  end?: number
+]): any[]
+```
+
+The `_array.fill` method [changes all elements in an array to a static value](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/fill), from a `start` index to an `end` index.
+
+## _array.filter
+
+```
+(arguments: {
+  on: any[],
+  callback: function,
+}): any[]
+(arguments: [
+  on: any[],
+  callback: function,
+]): any[]
+```
+
+The `_array.filter` method returns [an array with all elements that pass the test](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter) implemented by the provided function.
+
+## _array.find
+
+```
+(arguments: {
+  on: any[],
+  callback: function,
+}): any
+(arguments: [
+  on: any[],
+  callback: function,
+]): any
+```
+
+The `_array.find` method returns the value of the [first element in the provided array that satisfies the provided testing function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find). If no values satisfies the testing function, undefined is returned.
+
+## _array.findIndex
+
+```
+(arguments: {
+  on: any[],
+  callback: function,
+}): number
+(arguments: [
+  on: any[],
+  callback: function,
+]): number
+```
+
+The `_array.findIndex` method returns [the index of the first element in the array that satisfies the provided testing function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex). Otherwise, it returns -1, indicating that no element passed the test.
+
+## _array.flat
+
+```
+(arguments: {on: any[], depth?: number}): any[]
+(arguments: [on: any[], depth?: number]): any[]
+```
+
+The `_array.flat` method returns a array with all [sub-array elements concatenated into it recursively](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) up to the specified `depth`.
+
+## _array.includes
+
+```
+(arguments: {on: any[], value: any}): boolean
+(arguments: [on: any[], value: any]): boolean
+```
+
+The `_array.includes` method determines whether an array [includes a certain value among its entries](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes), returning `true` or `false` as appropriate.
+
+## _array.indexOf
+
+```
+(arguments: {on: any[], value: any}): number
+(arguments: [on: any[], value: any]): number
+```
+
+The `_array.indexOf` method returns the [first index at which a given element can be found](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf) in the array, or `-1` if it is not present.
+
+## _array.join
+
+```
+(arguments: {on: any[], separator?: string}): string
+(arguments: [on: any[], separator?: string]): string
+```
+
+The `_array.join` method returns [a string by concatenating all of the elements in an array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join), separated by commas or a specified `separator` string. If the array has only one item, then that item will be returned without using the separator.
+
+## _array.lastIndexOf
+
+```
+(arguments: {on: any[], value: any}): number
+(arguments: [on: any[], value: any]): number
+```
+
+The `_array.lastIndexOf` method returns the [last index at which a given element can be found](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/lastIndexOf) in the array, or -1 if it is not present.
+
+## _array.length
+
+```
+(array: any[]}): number
+```
+
+The `_array.length` method returns the [number of elements](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) in the array.
+
+## _array.map
+
+```
+(arguments: {
+  on: any[],
+  callback: function,
+}): any[]
+(arguments: [
+  on: any[],
+  callback: function,
+]): any[]
+```
+
+The `_array.map` method returns an array populated with the results of [calling a provided function on every element](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) in the provided array.
+
+## _array.reduce
+
+```
+(arguments: {
+  on: any[],
+  callback: function,
+  initialValue?: any
+}): any
+(arguments: [
+  on: any[],
+  callback: function,
+  initialValue?: any
+]): any
+```
+
+The `_array.reduce` method [executes a reducer function on each element of the array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/Reduce), resulting in single output value.
+
+#### Examples
+
+The simplest example would probably be adding all the elements in an array:
+```yaml
+sum:
+  _array.reduce:
+    on: [1, 2, 3, 4]
+    callback:
+      _function:
+        __sum:
+          - __args: 0
+          - __args: 1
+```
+This will return `sum: 10`
+
+You can start off by counting from 10 by specifying an `initialValue` for the reducer:
+```yaml
+sum:
+  _array.reduce:
+    on: [1, 2, 3, 4]
+    callback:
+      _function:
+        __sum:
+          - __args: 0
+          - __args: 1
+    initialValue: 10
+```
+This will return `sum: 20`
+
+You can use the index of the array element to add some logic to your `callback`. For instance, when you reach index 2 of your array (the 3rd entry), add 100 instead of the current element value:
+```yaml
+sum:
+  _array.reduce:
+    on: [1, 2, 3, 4]
+    callback:
+      _function:
+        __sum:
+          - __args: 0
+          - __if:
+              test:
+                __eq:
+                  - __args: 2
+                  - 2
+              then: 100
+              else:
+                __args: 1
+```
+This will return `sum: 107`
+
+## _array.reduceRight
+
+```
+(arguments: {
+  on: any[],
+  callback: function,
+  initialValue?: any
+}): any
+(arguments: [
+  on: any[],
+  callback: function,
+  initialValue?: any
+]): any
+```
+
+The `_array.reduceRight` method [applies a function against an accumulator and each value of the array (from right-to-left)](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/ReduceRight) to reduce it to a single value.
+
+## _array.reverse
+
+```
+(array: any[]}): any[]
+```
+
+The `_array.reverse` method [reverses](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) an array.
+
+## _array.slice
+
+```
+(arguments: {
+  on: any[],
+  start?: number,
+  end?: number
+}): number
+(arguments: [
+  on: any[],
+  start?: number,
+  end?: number
+]): number
+```
+
+The `_array.slice` method returns [a portion of an array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice) selected from `start` to `end` (end not included) where `start` and `end` represent the index of items in that array.
+
+## _array.some
+
+```
+(arguments: {
+  on: any[],
+  callback: function,
+}): boolean
+(arguments: [
+  on: any[],
+  callback: function,
+]): boolean
+```
+
+The `_array.some` method tests whether [at least one element in the array passes the test](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some) implemented by the provided function. It returns a Boolean value.
+
+## _array.sort
+
+```
+(arguments: {on: any[]}): number
+```
+
+The `_array.sort` method [sorts](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) the elements of an array. The sort order is ascending, built upon converting the elements into strings, then comparing their sequences of UTF-16 code units values.
+
+## _array.splice
+
+```
+(arguments: {
+  on: any[],
+  start: number,
+  deleteCount?: number
+  insert: any[]
+}): number
+(arguments: {
+  on: any[],
+  start: number,
+  deleteCount?: number,
+  insert: any[]
+}): number
+```
+
+The `_array.slice` method [changes the contents of an array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) by removing or replacing existing elements and/or adding new elements.

package/content/operators/_base64.md

@@ -0,0 +1,49 @@
+# _base64
+
+The `_base64` operator converts strings to and from [base64](https://en.wikipedia.org/wiki/Base64) format.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+# Operator methods:
+
+## _base64.decode
+
+```
+(value: string): string
+```
+
+The `_base64.decode` method decodes base64 encoded content into an ASCII string.
+
+#### Arguments
+
+###### string
+The string to decode.
+
+#### Examples
+
+###### Decode a base64 string:
+```yaml
+_base64.decode: SGVsbG8=
+```
+Returns: `"Hello"`.
+
+## _base64.encode
+
+```
+(value: string): string
+```
+
+The `_base64.encode` method base64 encodes a ASCII string.
+
+#### Arguments
+
+###### string
+The string to encode.
+
+#### Examples
+
+###### Encode a string as base64:
+```yaml
+_base64.encode: Hello
+```
+Returns: `"SGVsbG8="`.

package/content/operators/_boolean.md

@@ -0,0 +1,33 @@
+# _boolean
+
+```
+(value: any): boolean
+```
+
+The `_boolean` operator coerces the input to a boolean using javascript [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) and [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) rules. It is equivalent to a double negation (`_not` of `_not`), or the javascript `!!value` expression.
+
+> This operator can be used as a [`_build`](/_build) operator method.
+
+#### Arguments
+
+###### any
+
+#### Examples
+
+###### Coerce a truthy value to `true`:
+```yaml
+_boolean: 100
+```
+Returns: `true`
+
+###### Coerce a falsy value to `false`:
+```yaml
+_boolean: null
+```
+Returns: `false`
+
+###### Coerce an empty string to `false`:
+```yaml
+_boolean: ''
+```
+Returns: `false`

package/content/operators/_build.md

@@ -0,0 +1,166 @@
+# _build
+
+The `_build` operator evaluates at build time. This allows looping over a list in a JSON file generated by another application to calculate a value at build time, or to read environment variables.
+
+# Operator methods:
+
+## _build.env
+
+```
+(key: string): any
+(all: boolean): any
+```
+
+The `_build.env` method reads from your environment variables. The return value of `_build.env` will form part of the build output, so the [`_secret`](/_secret) operator should rather be used for reading any secrets.
+
+#### Examples
+
+###### Read environment from environment variables:
+With the following development and production environment variables, we can use the `_build.env` method to determine which environment we are in.
+
+`Development environment .env`
+```
+MY_ENVIRONMENT="development"
+```
+`Production environment`
+```
+MY_ENVIRONMENT="production"
+```
+
+```yaml
+_build.env: MY_ENVIRONMENT
+```
+
+This will return "development" in the development environment and "production" in the production environment.
+
+## _build.[operator]
+
+The `_build` operator can be used to evaluate normal operators at build time. Note that when using an operator as a method, the `_` gets left out of the original operator. For example, when using `_and` as a method, we write `_build.and`. When using an operator which has methods itself, we can just chain the methods: `_array.map` as a method becomes `_build.array.map`.
+
+The following operators can be used during the build:
+- [_and](/_and)
+- [_app](/_app)
+- [_args](/_args)
+- [_array](/_array)
+- [_base64](/_base64)
+- [_date](/_date)
+- [_divide](/_divide)
+- [_eq](/_eq)
+- [_function](/_function)
+- [_get](/_get)
+- [_gt](/_gt)
+- [_gte](/_gte)
+- [_hash](/_hash)
+- [_if](/_if)
+- [_if_none](/_if_none)
+- [_intl](/_intl)
+- [_json](/_json)
+- [_log](/_log)
+- [_lt](/_lt)
+- [_lte](/_lte)
+- [_math](/_math)
+- [_ne](/_ne)
+- [_not](/_not)
+- [_number](/_number)
+- [_object](/_object)
+- [_operator](/_operator)
+- [_or](/_or)
+- [_product](/_product)
+- [_random](/_random)
+- [_regex](/_regex)
+- [_string](/_string)
+- [_subtract](/_subtract)
+- [_sum](/_sum)
+- [_switch](/_switch)
+- [_type](/_type)
+- [_uri](/_uri)
+
+#### Examples
+
+###### Use the app slug as a map key at build time:
+The [`_app`](/_app) operator also resolves at build time, so `_build.app: slug` can supply a key for a build-time map. Because the key must be a string when `_build.object.fromEntries` runs, the runtime `_app` form would arrive too late here.
+
+```yaml
+_build.object.fromEntries:
+  - - _build.app: slug
+    - enabled: true
+```
+Returns (when `slug` is `my-app`):
+```yaml
+my-app:
+  enabled: true
+```
+
+###### Check environment variables to determine which url to link to:
+Use the `Link` action to link to a production url if the build is a production build in Vercel (the `VERCEL_ENV` variable will be set to "production"), otherwise link to a preview url.
+
+```yaml
+id: link_to_website
+type: Link
+params:
+  url:
+    _build.if:
+      test:
+        _build.eq:
+          - _build.env: VERCEL_ENV
+          - production
+      then: "https://www.productionsite.com"
+      else: "https://productionsite-git-develop-org.vercel.app"
+```
+
+###### Loop over a static list at build time:
+Let's say we have a static list of fruit and their sales in a file called `fruit_sales.json` which is generated by another application. We can map over this list at build time to return a list of the fruit and their total sales.
+
+`fruit_sales.json`
+```json
+[
+  {
+    "name": "Apples",
+    "sales": [
+      15,
+      20,
+      10,
+      25
+    ]
+  },
+  {
+    "name": "Bananas",
+    "sales": [
+      20,
+      5,
+      25,
+      17
+    ]
+  },
+  {
+    "name": "Oranges",
+    "sales": [
+      21,
+      12,
+      31,
+      40
+    ]
+  }
+]
+```
+```yaml
+_build.array.map:
+  on:
+    _ref: fruit_sales.json
+  callback:
+    _build.function:
+      name:
+        __build.args: 0.name
+      total_sales:
+        __build.sum:
+          __build.args: 0.sales
+```
+Returns:
+```
+- name: Apples
+  total_sales: 70
+- name: Bananas
+  total_sales: 67
+- name: Oranges
+  total_sales: 104
+```