feat: Add mutation functions for SETtings

[sddonne]

Part of elastic/kibana#250172

Summary

This PR adds mutation helpers to safely add or modify query settings.

Details

The following methods were added:

• .set
  • .list() — List all SET header commands.
  • .findBySettingName() — Find a SET command by its setting name.
  • .set() — Modify the value of an existing SET setting.
  • .upsert() — Modify a SET setting value, or add a new SET command if it does not exist.

The one needed for this task is .upsert() but as it needs the rest to be built they were also exposed.
This is a similar implementation to LIMIT and FROM commands.

Checklist

• Unit tests have been added or updated.
• The proper documentation has been added or updated.
• If this PR contains breaking changes, you have explained them using the BREAKING CHANGE: change syntax.
• The PR title has the correct conventional commit label in the title, this is crucial for the correct versioning of this package. Check the following cheat shit.

  Title Label	Release
  breaking: true (!)	major
  feat	minor
  fix	patch
  refactor	patch
  perf	patch
  build	patch
  docs	patch
  chore	patch
  revert	patch

(Built with the help of Cursor)

[stratoula]

Looks nice Seb, added some comments from the code review

[stratoula]

commands.set.set(root, 'unmapped_fields', 'LOAD') reads awkwardly

I know we are trying to keep consistent but honestly this seems very weird. Why dont we rename to update instead?

[sddonne]

Mm true, renamed.

[stratoula]

What about boolean values? Like SET approximation = TRUE?? Same for the upsert

[sddonne]

Good call, modified it so the value is taken as an expression query, in this way you can also set maps as values.
3bc75e8
Using Synth to transform it into the correct AST node.
Synth added a circular dependency so just parsing the value now.

[stratoula]

ok cool but type wise this value being string seems wrong no? As it can also be boolean or number

[sddonne]

We can implement this in two ways, as it is now, it expects the value to be written as you want it to appear in the query.
commands.set.update(root, 'unmapped_fields', 'true'); -> SET unmapped_fields = true;
commands.set.update(root, 'unmapped_fields', '"LOAD"'); -> SET unmapped_fields = "LOAD";
commands.set.update(root, 'unmapped_fields', '{"key" : "value"}'); -> SET unmapped_fields = {"key": "value"};

The other would be to expect a ESQLNode, delegating the responsibility to client to build it.

Mm there is also a third way that would be to set the value type as string | number | boolean | object (I think this is what you meant) and we should have some logic to transform them into ESQLNodes, but seems complex for this use case..

I think the current one is like in a middle ground between offering functionality and keeping it simple.

[stratoula]

I see, as long as it works prperly is ok but it is confusing that we are typing all the values as string. At least add a JSDoc comment on the value parameter explaining that it's parsed as an ES|QL expression (so 'true' → boolean, '"LOAD"' → string literal, etc.). That way future callers don't have to guess.

[sddonne]

9feaba4

[stratoula]

Approving with a comment, please at least add a comment on the value:string functions to explain what is going on as it is confusing 🙏