feat: sort_by function

Author: dreamorosi

Diff for: packages/jmespath/src/functions/Functions.ts

@@ -1,6 +1,7 @@
 import { Expression, getType, isNumber, isRecord } from '../visitor/utils';
 import type { JSONArray, JSONObject, JSONValue } from '../types';
 import { typeCheck, arityCheck } from './typeChecking';
+import { JMESPathTypeError } from '../errors';
 
 /**
  * TODO: validate SignatureDecorator type and extract to a separate file
@@ -261,6 +262,54 @@ class Functions {
     return arg.sort();
   }
 
+  /**
+   * Sort the provided array by the provided expression.
+   *
+   * @param arg The array to sort
+   * @param expression The expression to sort by
+   * @returns The sorted array
+   */
+  @Functions.signature({
+    argumentsSpecs: [['array'], ['expression']],
+  })
+  public funcSortBy(
+    args: Array<JSONValue>,
+    expression: Expression
+  ): Array<unknown> {
+    return args
+      .map((value, index) => {
+        const visited = expression.visit(value);
+        const type = getType(visited);
+        if (type !== 'string' && type !== 'number') {
+          throw new JMESPathTypeError({
+            currentValue: visited,
+            expectedTypes: ['string'],
+            actualType: getType(visited),
+          });
+        }
+
+        return {
+          value,
+          index,
+          visited: visited ? visited : null,
+        };
+      })
+      .sort((a, b) => {
+        if (a.visited === null && b.visited === null) {
+          return 0;
+        } else if (a.visited === null) {
+          return -1;
+        } else if (b.visited === null) {
+          return 1;
+        } else if (a.visited === b.visited) {
+          return a.index - b.index; // Make the sort stable
+        } else {
+          return a.visited > b.visited ? 1 : -1;
+        }
+      })
+      .map(({ value }) => value); // Extract the original values
+  }
+
   /**
    * Determines if the provided string starts with the provided suffix.
    *

Diff for: packages/jmespath/src/functions/typeChecking.ts

@@ -1,4 +1,4 @@
-import { getType, isRecord } from '../visitor/utils';
+import { Expression, getType, isRecord } from '../visitor/utils';
 import { JMESPathTypeError, ArityError, VariadicArityError } from '../errors';
 
 /**
@@ -97,7 +97,19 @@ const typeCheckArgument = (arg: unknown, argumentSpec: Array<string>): void => {
       }
       break;
     } else {
-      if (type === 'string' || type === 'number' || type === 'boolean') {
+      if (type === 'expression') {
+        if (!(arg instanceof Expression)) {
+          if (!hasMoreTypesToCheck) {
+            throw new JMESPathTypeError({
+              currentValue: arg,
+              expectedTypes: argumentSpec,
+              actualType: getType(arg),
+            });
+          }
+          continue;
+        }
+        break;
+      } else if (type === 'string' || type === 'number' || type === 'boolean') {
         if (typeof arg !== type) {
           if (!hasMoreTypesToCheck) {
             throw new JMESPathTypeError({

Diff for: packages/jmespath/tests/unit/functions.test.ts

@@ -1606,7 +1606,7 @@ describe('Functions tests', () => {
     }
   );
 
-  /* it.each([
+  it.each([
     {
       description: 'sort by field expression',
       expression: 'sort_by(people, &age)',
@@ -1734,6 +1734,16 @@ describe('Functions tests', () => {
       expression: 'sort_by(`[]`, &age)',
       expected: [],
     },
+    {
+      expression: 'sort_by(people, &name)',
+      expected: [
+        { age: 10, age_str: '10', bool: true, name: 3 },
+        { age: 20, age_str: '20', bool: true, name: 'a', extra: 'foo' },
+        { age: 40, age_str: '40', bool: false, name: 'b', extra: 'bar' },
+        { age: 30, age_str: '30', bool: true, name: 'c' },
+        { age: 50, age_str: '50', bool: false, name: 'd' },
+      ],
+    },
   ])('should support sorty_by() special cases', ({ expression, expected }) => {
     // Prepare
     const data = {
@@ -1778,27 +1788,25 @@ describe('Functions tests', () => {
 
     // Assess
     expect(result).toStrictEqual(expected);
-  }); */
-  /* it.each([
+  });
+
+  it.each([
     {
       expression: 'sort_by(people, &extra)',
-      error: 'TypeError: expected (string), received null',
+      error:
+        'Invalid argument type for function sort_by(), expected "string" but found "null" in expression: sort_by(people, &extra)',
     },
     {
       expression: 'sort_by(people, &bool)',
-      error: 'TypeError: unexpected type (boolean)',
-    },
-    {
-      expression: 'sort_by(people, &name)',
-      error: 'TypeError: expected (string), received number',
+      error:
+        'Invalid argument type for function sort_by(), expected "string" but found "boolean" in expression: sort_by(people, &bool)',
     },
     {
       expression: 'sort_by(people, name)',
       error:
-        'TypeError: sort_by() expected argument 2 to be type (expression) but received type null instead.',
+        'Invalid argument type for function sort_by(), expected "expression" but found "null" in expression: sort_by(people, name)',
     },
   ])('sort_by() function special cases errors', ({ expression, error }) => {
-    // TODO: see if we can assert the error type as well in sort_by() function special cases errors tests
     // Prepare
     const data = {
       people: [
@@ -1839,7 +1847,8 @@ describe('Functions tests', () => {
 
     // Act & Assess
     expect(() => search(expression, data)).toThrow(error);
-  }); */
+  });
+
   /* it.each([
     {
       expression: 'max_by(people, &age)',
@@ -2091,7 +2100,7 @@ describe('Functions tests', () => {
     expect(() => search(expression, data)).toThrow(error);
   });
  */
-  /* it.each([
+  it.each([
     {
       description: 'stable sort order',
       expression: 'sort_by(people, &age)',
@@ -2198,7 +2207,7 @@ describe('Functions tests', () => {
 
     // Assess
     expect(result).toStrictEqual(expected);
-  }); */
+  });
 
   it.each([
     {