# @atlassianlabs/jql-autocomplete

> JQL autocomplete engine

Latest version **1.1.1** (published 2023-07-12) · 0 weekly downloads

## Install

```sh
npm install @atlassianlabs/jql-autocomplete
pnpm add @atlassianlabs/jql-autocomplete
yarn add @atlassianlabs/jql-autocomplete
bun add @atlassianlabs/jql-autocomplete
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.1 |
| Published | 2023-07-12 |
| First published | 2021-12-10 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 6 |
| Unpacked size | 220.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Atlassian Pty Ltd |
| Maintainers | doklovic, prkb, crumley, nrundquist, dkolbly-atlassian, kpainter-atl, soneymathew |

## Links

- npm: https://www.npmjs.com/package/@atlassianlabs/jql-autocomplete
- Repository: https://bitbucket.org/atlassian/atlassian-frontend
- Homepage: https://bitbucket.org/atlassian/atlassian-frontend#readme
- Issues: https://bitbucket.org/atlassian/atlassian-frontend/issues
- npm.io page: https://npm.io/package/@atlassianlabs/jql-autocomplete

## Dependencies (6)

- [util](https://npm.io/package/util.md) ^0.12.4
- [assert](https://npm.io/package/assert.md) ^2.0.0
- [antlr4ts](https://npm.io/package/antlr4ts.md) 0.5.0-alpha.4
- [antlr4-c3](https://npm.io/package/antlr4-c3.md) 3.0.1
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.0.0
- [@atlassianlabs/jql-parser](https://npm.io/package/@atlassianlabs/jql-parser.md) ^1.0.0

## Recent versions

- 1.1.1 (latest) — 2023-07-12
- 1.1.0 — 2023-06-02
- 1.0.1 — 2022-09-26
- 1.0.0 — 2022-02-21
- 0.0.1 — 2021-12-10

## README

# JQL Autocomplete

[![Atlassian license](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)

This package allows consumers to retrieve autocomplete suggestions for a given JQL query. JQL
Autocomplete leverages the [antlr4-c3](https://github.com/mike-lischke/antlr4-c3) library to provide
code completion candidates using the ANTLR4 generated `@atlassianlabs/jql-parser`. Refer to
[antlr4-c3](https://github.com/mike-lischke/antlr4-c3) for a more in-depth introduction into code
completion with ANTLR4 grammars.

## Usage

For a simple use case you'll want to construct a new `JQLAutocomplete` object for a given source
query.

```typescript
import { JQLAutocomplete } from '@atlassianlabs/jql-autocomplete';

const autocomplete = JQLAutocomplete.fromText("assignee = currentUser()");
```

You can then specify the (zero-indexed) caret position to retrieve suggestions for, e.g.:
```typescript
// Caret positioned at "assignee = "
const selectionStart = 11;
const selectionStop = 11;
const suggestions = autocomplete.getJQLSuggestionsForCaretPosition([
  selectionStart,
  selectionStop,
]);

console.log(suggestions);
```
Will output the following response:
```json
{
  "tokens": {
    "matchedText": "",
    "replacePosition": [11,11],
    "values": ["EMPTY"]
  },
  "rules": {
    "function": {
      "matchedText": "",
      "replacePosition": [11,11],
      "context": {
        "field": "assignee",
        "operator": "="
      }
    },
    "value": {
      "matchedText": "",
      "replacePosition": [11,11],
      "context": {
        "field": "assignee",
        "operator": "="
      }
    }
  }
}
```

This includes a collection of [tokens](https://github.com/antlr/antlr4/blob/master/doc/lexer-rules.md#lexer-rules)
and [rules](https://github.com/antlr/antlr4/blob/master/doc/parser-rules.md) that are valid for the
given caret position. Rules are essential for deriving more than just keywords from your
autocomplete.

As you can see in the above example a valid query could be produced using:
- An `EMPTY` token, e.g. `assignee = EMPTY`
- A `function` rule, e.g. `assignee = currentUser()`
- A `value` rule, e.g. `assignee = xxxxxxxxx`

Typically, when encountering rules you'll want to enrich this information with Jira data. To do so
you can leverage [Jira Cloud REST API's](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-jql/).

## Installation

```sh
yarn add @atlassianlabs/jql-autocomplete
```

## Documentation
### Fine tuning

When constructing an autocomplete object you can specify a collection of `ignoredTokens` and
`preferredRules`. When not provided, the autocomplete engine specified default arguments which are
suitable for most autocomplete use cases. You can read more about these options in the
[antlr4-c3 documentation](https://github.com/mike-lischke/antlr4-c3#fine-tuning).

We also extend the `antlr4-c3` configuration options with a new argument, `delimiterTokens`. By
default `JQLAutocomplete` will provide suggestions for the token immediately preceding the caret.
When the caret is positioned at a delimiter token then we'll look for suggestions **after** the
current token.

For example:

```typescript
import { JQLLexer, JQLParser } from '@atlassianlabs/jql-parser';
import { JQLAutocomplete } from '@atlassianlabs/jql-autocomplete';

const ignoredTokens = new Set([JQLLexer.NOT_EQUALS]); // Exclude != tokens from suggestions
const preferredRules = new Set([JQLParser.RULE_jqlField]) // Only show rule suggestions for fields
const delimiterTokens = new Set([JQLLexer.COMMA]) // Give suggestions for tokens AFTER commas

const autocomplete = JQLAutocomplete.fromText("assignee = currentUser()", ignoredTokens, preferredRules, delimiterTokens);
```

## Support

For developers outside of Atlassian looking for help, or to report issues, [please make a post on the community forum](https://community.developer.atlassian.com/c/atlassian-ecosystem-design).
We will monitor the forums and redirect topics to the appropriate maintainers.

## License
Copyright (c) 2021 - 2022 Atlassian and others. Apache 2.0 licensed, see [LICENSE](LICENSE) file.

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