> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devset.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Built-In DSL Functions: Complete Reference Guide
> Complete reference for every built-in function in Devset DSL. Covers random generation, timestamps, choice, math, and comparison functions with examples.
Devset's built-in functions let you generate dynamic values, perform calculations, and evaluate conditions directly inside your workflow and stage definitions. You call a function by wrapping it in a `{ "$fn": "..." }` expression — anywhere a `DslValue` is accepted, such as a `set` field, a `state` mutation, the `emit` condition, or a `repeat` guard. Functions evaluate fresh on every stage execution, so each run produces independent results.
## How to Use Functions
Wrap any function call in a `$fn` expression object:
```json theme={null}
{ "$fn": "uuid()" }
{ "$fn": "int(10, 500)" }
{ "$fn": "choice(PENDING,ACTIVE,CLOSED)" }
```
Assign the result to a payload field inside a stage's `set` block:
```json theme={null}
"set": {
"id": { "$fn": "uuid()" },
"amount": { "$fn": "int(1, 1000)" },
"status": { "$fn": "choice(PENDING,ACTIVE)" },
"createdAt": { "$fn": "now()" }
}
```
Or use a function as a condition in `emit`, `repeatWhile`, or `repeatUntil`:
```json theme={null}
"emit": { "$fn": "lt(state.order.count, 100)" }
```
## Referencing Values in Arguments
Function arguments can be more than literals. You have two ways to pass live values into a function call:
**Payload path reference** — prefix a field name with `.` to read from the current stage's resolved payload:
```json theme={null}
{ "$fn": "add(state.order.total, .amount)" }
```
Here `.amount` reads the `amount` field that was assigned earlier in the same stage's `set` block.
**State reference** — use `state.` followed by a dot-notation path to read from workflow state:
```json theme={null}
{ "$fn": "add(state.order.count, 1)" }
```
You can nest function calls freely. The inner call is evaluated first and its result is passed as an argument to the outer call:
```json theme={null}
{ "$fn": "add(state.count, int(1, 5))" }
```
This adds a random integer between 1 and 5 to the current count on every execution.
***
## Generation Functions
Use these functions to produce random values for payload fields.
### `uuid()`
**Signature:** `uuid()`
Generates a random UUID v4 string. Use this for unique identifiers such as message IDs, order IDs, or correlation IDs.
```json theme={null}
{ "$fn": "uuid()" }
```
**Example output:** `"a3f4c1d2-7e8b-4f09-b1c3-0e2a5d6f8901"`
***
### `string()`
**Signature:** `string()`
Generates a random alphanumeric string. Useful when you need a short opaque token or reference code.
```json theme={null}
{ "$fn": "string()" }
```
***
### `bit()`
**Signature:** `bit()`
Returns a random integer of either `0` or `1`. Useful for binary flags or simple on/off fields.
```json theme={null}
{ "$fn": "bit()" }
```
***
### `bool()` / `boolean()`
**Signature:** `bool()` or `boolean()`
Returns a random `true` or `false` boolean value. Both names are equivalent.
```json theme={null}
{ "$fn": "bool()" }
```
***
### `int(min, max)`
**Signature:** `int(min, max)`
Returns a random integer in the inclusive range `[min, max]`. Both arguments must be integer literals or path references that resolve to integers.
| Argument | Description |
| -------- | ----------------------- |
| `min` | Lower bound (inclusive) |
| `max` | Upper bound (inclusive) |
```json theme={null}
{ "$fn": "int(10, 500)" }
```
**Example:** Generate a price between 10 and 500.
***
### `long(min, max)`
**Signature:** `long(min, max)`
Returns a random long integer in the inclusive range `[min, max]`. Use this instead of `int` when you need values outside the 32-bit integer range — for example large Unix timestamps or database record IDs.
| Argument | Description |
| -------- | ----------------------- |
| `min` | Lower bound (inclusive) |
| `max` | Upper bound (inclusive) |
```json theme={null}
{ "$fn": "long(1000000000000, 9999999999999)" }
```
***
## Timestamp Functions
Use these functions to capture the current time in various formats.
### `now()`
**Signature:** `now()`
Returns the current wall-clock time as an ISO-8601 string.
```json theme={null}
{ "$fn": "now()" }
```
**Example output:** `"2024-06-15T10:23:44.512Z"`
***
### `nows()`
**Signature:** `nows()`
Returns the current time as a Unix timestamp in **seconds** (integer).
```json theme={null}
{ "$fn": "nows()" }
```
**Example output:** `1718447024`
***
### `nowms()`
**Signature:** `nowms()`
Returns the current time as a Unix timestamp in **milliseconds** (integer). Useful for high-resolution timing fields or when your consumers expect millisecond-precision epoch values.
```json theme={null}
{ "$fn": "nowms()" }
```
**Example output:** `1718447024512`
***
## Choice Functions
Use these functions to pick values from a predefined set, either uniformly or with weighted probabilities.
### `choice(v1, v2, ...)`
**Signature:** `choice(v1, v2, ...)`
Picks one value from the list with equal probability. Pass any number of comma-separated values. Values do not need to be quoted.
```json theme={null}
{ "$fn": "choice(PENDING,ACTIVE,CLOSED)" }
```
Each call returns one of `"PENDING"`, `"ACTIVE"`, or `"CLOSED"` with roughly equal frequency.
***
### `choiceWeighted(v1:w1, v2:w2, ...)`
**Signature:** `choiceWeighted(v1:w1, v2:w2, ...)`
Picks one value from the list using the specified weights. Each entry is written as `value:weight` where weight is a positive integer. Higher weights make a value more likely to be chosen. Weights do not need to sum to 100 — they are relative to each other.
```json theme={null}
{ "$fn": "choiceWeighted(ACTIVE:70,CLOSED:20,PENDING:10)" }
```
In this example, `"ACTIVE"` is returned 70% of the time, `"CLOSED"` 20%, and `"PENDING"` 10%.
Use `choiceWeighted` when you want to model realistic distributions — for example, most orders being active rather than pending or closed.
***
## Math Functions
Use these functions to compute derived numeric values, typically for maintaining running totals or calculating metrics in workflow state.
### `add(a, b)`
**Signature:** `add(a, b)`
Returns `a + b`. Both arguments can be literals, path references, state references, or nested function calls.
```json theme={null}
{ "$fn": "add(state.order.total, .amount)" }
```
Adds the current stage's `amount` to the running `order.total` in state.
***
### `sub(a, b)`
**Signature:** `sub(a, b)`
Returns `a - b`.
```json theme={null}
{ "$fn": "sub(state.budget, .cost)" }
```
***
### `percent(value, total)`
**Signature:** `percent(value, total)`
Returns `(value / total) * 100`. Use this to compute percentage metrics — for example the proportion of high-value orders in a run.
| Argument | Description |
| -------- | --------------- |
| `value` | The numerator |
| `total` | The denominator |
```json theme={null}
{ "$fn": "percent(state.highValue.count, state.order.count)" }
```
***
## Comparison Functions
Comparison functions return a boolean (`true` or `false`) and are designed for use in `emit`, `repeatWhile`, and `repeatUntil` expressions. You can also use them anywhere else a `DslValue` is accepted.
### `lt(a, b)` — Less Than
Returns `true` if `a < b`.
```json theme={null}
"emit": { "$fn": "lt(state.order.count, 100)" }
```
Emit only while the order count is below 100.
***
### `lte(a, b)` — Less Than or Equal
Returns `true` if `a ≤ b`.
```json theme={null}
"repeatWhile": { "$fn": "lte(state.retries, 5)" }
```
***
### `gt(a, b)` — Greater Than
Returns `true` if `a > b`.
```json theme={null}
{ "$fn": "gt(.amount, 200)" }
```
***
### `gte(a, b)` — Greater Than or Equal
Returns `true` if `a ≥ b`.
```json theme={null}
"repeatUntil": { "$fn": "gte(state.retries, 3)" }
```
***
### `eq(a, b)` — Equal
Returns `true` if `a == b`.
```json theme={null}
"emit": { "$fn": "eq(.status, ACTIVE)" }
```
***
### `neq(a, b)` — Not Equal
Returns `true` if `a != b`.
```json theme={null}
"emit": { "$fn": "neq(.status, CANCELLED)" }
```
***
## Related Pages
* [Stage Fields](/reference/stage-fields) — how to use `$fn` expressions in `set`, `state`, `emit`, `repeatWhile`, and `repeatUntil`.
* [Workflow DSL](/reference/workflow-dsl) — top-level workflow structure including the `state` object that function arguments reference.