Targetprocess DSL suggestions

This package provides expression parser and analysis instruments to build client-side typing suggestions, which can be integrated into various UI DSL editors.

For example, it can infer that when user types Feature., the editor should display suggestion list of fields available on Feature type: Name, Epic, PlannedStartDate, etc.

Usage example

import type { Entity } from '@targetprocess/suggestion-context'
import { buildSuggestions, getDefaultFunctions, getDefaultPrimitiveEntities, getDefaultVariables } from '@targetprocess/dsl-suggestions'

it('example', () => {
  // Describe entities which are avaible in the current context
  const entities: Entity[] = [
    // This library has some built-in entities for primitive types: String, Integer, Date, etc.
    ...getDefaultPrimitiveEntities(),
    // Add domain entities
    // In real code you will most likely get them from Targetprocess API like `/api/meta/v2`
    {
      name: 'UserStory',
      fields: [
        { name: 'Name', type: { kind: 'domain', typeName: 'String' } },
        { name: 'Feature', type: { kind: 'domain', typeName: 'Feature' } }
      ]
    },
    {
      name: 'Feature',
      fields: [{ name: 'Name', type: { kind: 'domain', typeName: 'string' } }]
    }
  ]

  // Specify functions, like IIF, Select, Where, which are available in the current context
  // This library already includes most used API functions.
  const functions = getDefaultFunctions()

  // Given the previously collected meta, DSL text, and caret position in that text,
  // build a list of suggestions to be displayed to the user.
  const result = buildSuggestions({
    rootType: { kind: 'domain', typeName: 'UserStory' },
    getScopeVariables: getDefaultVariables,
    suggestionMeta: {
      entities: new Map<string, Entity>(entities.map(e => [e.name.toLowerCase(), e])),
      functions
    },
    text: 'It.',
    caretPosition: 3
  })

  // If the input can't be parsed, the result will be `undefined`
  expect(result).toBeDefined()
  const actual = result!.suggestions.map(x => x.label)
  expect(actual).toEqual(['Name', 'Feature', 'ToString'])
})

By default, all parsing and analysis errors are logged to console. You can override the library's logger in defaultLoggerFactory, for example to disable all logging:

import { defaultLoggerFactory } from '@targetprocess/suggestion-context'

defaultLoggerFactory.logger = {
  error() {
    // do nothing
  }
}

Local development

npm ci

Changing grammar

If you make changes to ANTLR G4 grammar files:

npm run grammar-antlr4ts

Publishing

Use npm version to update "version" in package-lock.json and create a tag, e.g.:

npm version 1.0.0
git push origin 1.0.0

Wait for Gitlab pipeline to finish, and run manual publish step there.