feat(jmespath): add built in functions

[dreamorosi]

Description of your changes

This PR adds a new Functions class to the JMESPath utility. This class holds the implementation for all the built-in functions listed in the JMESPath specification as well as a class method decorator to validate function arguments.

Customers are not expected to use this class directly, instead the logic in it will allow them to use function expressions in their JMESPath expressions, for example:

const payload = {
  grades: [1, 5, 2, 10],
};

const maxGrade = search('max(grades)', payload); // 10
const minGrade = search('min(grades)', payload); // 1
const avgGrade = search('avg(grades)', payload); // 4.5
const roundedUpAvgGrade = search('ceil(avg(grades))', payload); // 5
const roundedDownAvgGrade = search('floor(avg(grades))', payload); // 4

This part of the code has been implemented as a class purposefully so that we, as well as customers, can extend the class and add new functions to the utility.

To facilitate this, the Functions class provides also a class method decorator defined as static method. Using this decorator a method implementing a JMESPath function can have its arguments validated at runtime for types, number, and whether or not the function is variadic.

For example:

class CustomFunctions extends PowertoolsFunctions {
  @PowertoolsFunctions.signature({ // (1)!
    argumentsSpecs: [['string']],
    variadic: false,
  })
  public funcDecodeBrotliCompression(value: string): string { // (2)!
    const encoded = fromBase64(value, 'base64');
    const uncompressed = brotliDecompressSync(encoded);

    return uncompressed.toString();
  }
}

To keep the PR focused I am adding only the base functions, however the next PR will add some Powertools functions that are equivalent to the ones found in Python.

Related issues, RFCs

Issue number: #2206

Checklist

• My changes meet the tenets criteria
• I have performed a self-review of my own code
• I have commented my code where necessary, particularly in areas that should be flagged with a TODO, or hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my change is effective and works
• The PR title follows the conventional commit semantics

Breaking change checklist

Is it a breaking change?: NO

• I have documented the migration process
• I have added, implemented necessary warnings (if it can live side by side)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[am29d]

What happens when the argumentSpecs do not match with the signature?

[dreamorosi]

What happens when the argumentSpecs do not match with the signature?

It will throw a runtime JMESPathTypeError, all the logic for that is implemented from this line onwards.