[ES|QL] AST node synthesizer

[vadimkibana]

Summary

Closes #191812

Adds ability to create ES|QL AST nodes from plain strings and compose them.

Create an integer literal:

const node = expr `42`;

Create any expression:

const node = expr `nested.field = fn(123)`;

Compose AST nodes:

const value = expr `123`;
const node = expr `nested.field = fn(${value})`;

Usage

You can create an assignment expression AST node as simle as:

import { synth } from '@kbn/esql-ast';

const node = synth.expr `my.field = max(10, ?my_param)`;
// { type: 'function', name: '=', args: [ ... ]}

To construct an equivalent AST node using the Builder class, you would need to
write the following code:

import { Builder } from '@kbn/esql-ast';

const node = Builder.expression.func.binary('=', [
  Builder.expression.column({
    args: [Builder.identifier({ name: 'my' }), Builder.identifier({ name: 'field' })],
  }),
  Builder.expression.func.call('max', [
    Builder.expression.literal.integer(10),
    Builder.param.named({ value: 'my_param' }),
  ]),
]);
// { type: 'function', name: '=', args: [ ... ]}

You can nest template strings to create more complex AST nodes:

const field = synth.expr `my.field`;
const value = synth.expr `max(10, 20)`;

const assignment = synth.expr`${field} = ${value}`;
// { type: 'function', name: '=', args: [ 
//     { type: 'column', args: [ ... ] },
//     { type: 'function', name: 'max', args: [ ... ] }
// ]}

Use the synth.cmd method to create command nodes:

const command = synth.cmd `WHERE my.field == 10`;
// { type: 'command', name: 'WHERE', args: [ ... ]}

AST nodes created by the synthesizer are pretty-printed when you coerce them to
a string or call the toString method:

const command = synth.cmd ` WHERE my.field == 10 `; // { type: 'command', ... }
String(command); // "WHERE my.field == 10"

Reference

synth.expr

The synth.expr synthesizes an expression AST nodes. (Expressions are
basically any thing that can go into a WHERE command, like boolean expression,
function call, literal, params, etc.)

Use it as a function:

const node = synth.expr('my.field = max(10, 20)');

Specify parser options:

const node = synth.expr('my.field = max(10, 20)', { withFormatting: false });

Use it as a template string tag:

const node = synth.expr `my.field = max(10, 20)`;

Specify parser options, when using as a template string tag:

const node = synth.expr({ withFormatting: false }) `my.field = max(10, 20)`;

Combine nodes using template strings:

const field = synth.expr `my.field`;
const node = synth.expr `${field} = max(10, 20)`;

Print the node as a string:

const node = synth.expr `my.field = max(10, 20)`;
String(node); // 'my.field = max(10, 20)'

synth.cmd

The synth.cmd synthesizes a command AST node (such as SELECT, WHERE,
etc.). You use it the same as the synth.expr function or template string tag.
The only difference is that the synth.cmd function or tag creates a command
AST node.

const node = synth.cmd `WHERE my.field == 10`;
// { type: 'command', name: 'where', args: [ ... ]}

Checklist

Delete any items that are not applicable to this PR.

• Unit or functional tests were updated or added to match the most common scenarios

For maintainers

• This was checked for breaking API changes and was labeled appropriately

[elasticmachine]

Pinging @elastic/kibana-esql (Team:ESQL)

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: 1fd324f

Metrics [docs]

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
kbnUiSharedDeps-srcJs	3.5MB	3.5MB	+1008.0B

History

• 💚 Build #255315 succeeded 8e24d21
• 💔 Build #255275 failed 27d7457
• 💔 Build #255248 failed 9362218
• 💔 Build #255234 failed a234190

[stratoula]

This is lovely! LGTM

[kibanamachine]

Starting backport for target branches: 8.x

https://github.com/elastic/kibana/actions/runs/12116127168

[kibanamachine]

💚 All backports created successfully

Status	Branch	Result
✅	8.x

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation