# Expressions

Learn about the expression syntax available in templates.

Templates support dynamic values using the `${expression}` syntax. Expressions use a subset of JavaScript and can appear in both keys and values throughout a template.

You can find the full list of available variables and functions in the [variables](/reference/cli/templates/variables) and [functions](/reference/cli/templates/functions) references.

## Resolution

When a value consists entirely of a single expression, the result preserves the original type. If the expression evaluates to a number, the result is a number, not a string. This lets you pass non-string values like numbers, booleans, objects, and arrays through expressions.

If the value contains anything outside the expression, even a leading space, it is treated as string interpolation and the result is always a string.

For example, consider these two templates where the outer passes a value to the inner:

**inner.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Inner",
  "description": "Expects a number option.",
  "options": {
    "count": {
      "type": "number",
      "description": "The item count."
    }
  },
  "actions": [
    {
      "name": "print",
      "message": "You have ${options.count} items."
    }
  ]
}
```

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Outer",
  "description": "Passes a number to another template.",
  "actions": [
    {
      "name": "import",
      "template": "./inner.json5",
      "options": {
        // Resolves to the number 42, not the string "42"
        "count": "${40 + 2}"
      }
    }
  ]
}
```

Running this template prints `You have 42 items.` because `"${40 + 2}"` resolves to the number `42`. Writing `"Total: ${40 + 2}"` instead would produce the string `"Total: 42"`, and the CLI would report the error:

```
Expected value of type number for option count, but got string.
```

## Operators

Expressions support the following operators:

| Category           | Operators                                      |
| ------------------ | ---------------------------------------------- |
| Arithmetic         | `+`, `-`, `*`, `/`, `%`, `**`                  |
| Comparison         | `==`, `!=`, `===`, `!==`, `<`, `>`, `<=`, `>=` |
| Logical            | `&&`, `\|\|`, `!`                              |
| Nullish coalescing | `??`                                           |
| Conditional        | `condition ? then : else`                      |

## Literals

The following literal types are supported:

| Type     | Syntax               |
| -------- | -------------------- |
| Strings  | `'hello'`, `"world"` |
| Numbers  | `42`, `3.14`         |
| Booleans | `true`, `false`      |
| Null     | `null`               |
| Arrays   | `[1, 2, 3]`          |
| Objects  | `{key: 'value'}`     |
| Regex    | `/pattern/flags`     |

## Property access

You can use dot or bracket notation to access properties:

```json5
"source": "${project.path.source}",
"name": "${options['name']}"
```

## Built-in API

Expressions support a subset of JavaScript methods and properties. See below for the full list available for each value type.

### Strings

| Name                                                                                                               | Description                                           |
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| [length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length)           | The number of characters in the string.               |
| [slice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice)             | Extracts a section of the string.                     |
| [indexOf](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf)         | Returns the index of the first occurrence of a value. |
| [match](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/match)             | Matches the string against a regular expression.      |
| [matchAll](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll)       | Returns all matches of a regular expression.          |
| [replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace)         | Replaces the first match of a pattern.                |
| [replaceAll](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll)   | Replaces all matches of a pattern.                    |
| [includes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes)       | Checks whether the string contains a value.           |
| [startsWith](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith)   | Checks whether the string starts with a value.        |
| [endsWith](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith)       | Checks whether the string ends with a value.          |
| [toLowerCase](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toLowerCase) | Converts the string to lowercase.                     |
| [toUpperCase](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/toUpperCase) | Converts the string to uppercase.                     |
| [repeat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/repeat)           | Repeats the string a given number of times.           |
| [split](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/split)             | Splits the string into an array of substrings.        |

### Arrays

| Name                                                                                                        | Description                                           |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [length](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length)     | The number of elements in the array.                  |
| [slice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice)       | Returns a shallow copy of a portion of the array.     |
| [join](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/join)         | Joins all elements into a string.                     |
| [includes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes) | Checks whether the array contains a value.            |
| [indexOf](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/indexOf)   | Returns the index of the first occurrence of a value. |

### Regular expressions

| Name                                                                                                     | Description                                 |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| [source](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/source) | The pattern text of the regular expression. |
| [test](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/test)     | Tests whether the pattern matches a string. |

## Explore

- [Variables](/reference/cli/templates/variables): Explore the built-in template variables.
- [Functions](/reference/cli/templates/functions): Explore the built-in template functions.