# @actions/expressions

> `@actions/expressions` is a library to parse and evaluate GitHub Actions [expressions](https://docs.github.com/actions/learn-github-actions/expressions).

Latest version **0.3.61** (published 2026-08-04) · MIT license · 0 weekly downloads

## Install

```sh
npm install @actions/expressions
pnpm add @actions/expressions
yarn add @actions/expressions
bun add @actions/expressions
```

## Health

**Score 65/100 (B)** — status: active.

Positive: esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.61 |
| Published | 2026-08-04 |
| First published | 2023-03-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Node | >= 20 |
| Dependencies | 0 |
| Unpacked size | 162.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 192 |
| Maintainers | thboop, ericsciple, bdehamer |

## Links

- npm: https://www.npmjs.com/package/@actions/expressions
- Repository: https://github.com/actions/languageservices
- Homepage: https://github.com/actions/languageservices#readme
- Issues: https://github.com/actions/languageservices/issues
- npm.io page: https://npm.io/package/@actions/expressions

## Recent versions

- 0.3.61 (latest) — 2026-08-04
- 0.3.60 — 2026-07-15
- 0.3.59 — 2026-07-13
- 0.3.58 — 2026-06-11
- 0.3.57 — 2026-05-12
- 0.3.56 — 2026-05-08
- 0.3.55 — 2026-04-28
- 0.3.54 — 2026-04-21
- 0.3.53 — 2026-04-15
- 0.3.52 — 2026-04-14
- 0.3.51 — 2026-04-03
- 0.3.50 — 2026-04-01
- 0.3.49 — 2026-03-20
- 0.3.48 — 2026-03-18
- 0.3.47 — 2026-03-10
- … 48 more at https://npm.io/package/@actions/expressions/versions

## README

# actions/expressions

`@actions/expressions` is a library to parse and evaluate GitHub Actions [expressions](https://docs.github.com/actions/learn-github-actions/expressions).

## Installation

The [package](https://www.npmjs.com/package/@actions/expressions) contains TypeScript types and compiled ECMAScript modules.

```bash
npm install @actions/expressions
```

## Usage

### Simple example

```ts
import { Parser, Lexer, Evaluator, data } from '@actions/expressions';

const lexer = new Lexer("1 == 2");
const lr = lexer.lex();

const parser = new Parser(lr.tokens, [], []);
const expr = parser.parse();

const evaluator = new Evaluator(expr, new data.Dictionary());
const result = evaluator.evaluate();

console.log(result.coerceString()) // false
```

### With context data

```ts
import { Parser, Lexer, Evaluator, data } from '@actions/expressions';

const lexer = new Lexer("'monalisa' == context.name");
const lr = lexer.lex();

const parser = new Parser(lr.tokens, ["context"], []);
const expr = parser.parse();

const evaluator = new Evaluator(expr, new data.Dictionary([{
  key: "context"
  value: new data.Dictionary([{
    key: "name"
    value: new data.StringData("monalisa")
  }])
}]));
const result = evaluator.evaluate();

console.log(result.coerceString()) // true
```

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) at the root of the repository for general guidelines and recommendations.

This project is just one of multiple implementations of the GitHub Actions Expressions language. We therefore cannot accept contributions that add new language features or significantly change the behavior of existing language features. If you would like to propose a change to the language itself, please use our [Community Forum](https://github.com/community/community/discussions/categories/actions-and-packages).

If you do want to contribute, please run [prettier](https://prettier.io/) to format your code and add unit tests as appropriate before submitting your PR. [./testdata](./testdata) contains test cases that all implementations should pass, please also make sure those tests are still passing.

### Build

```bash
npm run build
```

or to watch for changes

```bash
npm run watch
```

### Test

```bash
npm test
```

or to watch for changes and run tests:

```bash
npm run test-watch
```

### Lint

```bash
npm run format-check
```

## License

This project is licensed under the terms of the MIT open source license. Please refer to [MIT](../LICENSE) for the full terms.

---
_Source: https://npm.io/package/@actions/expressions · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._