Add $assert() function. (#375)

* Add $assert() function.

* Apply boolean check in the correct way.

Author: jhorbulyk

docs/object-functions.md

@@ -57,3 +57,8 @@ __Examples__
 __Signature:__`$error(message)`
 
 Deliberately throws an error with an optional `message`
+
+ ## `$assert()`
+__Signature:__`$assert(condition, message)`
+
+If condition is true, the function returns undefined. If the condition is false, an exception is thrown with the message as the message of the exception.

src/functions.js

@@ -1822,6 +1822,25 @@ const functions = (() => {
         };
     }
 
+    /**
+     *
+     * @param {boolean} condition - the condition to evaluate
+     * @param {string} [message] - the message to attach to the error
+     * @throws custom error with code 'D3137'
+     * @returns {undefined}
+     */
+    function assert(condition, message) {
+        if(!condition) {
+            throw {
+                code: "D3141",
+                stack: (new Error()).stack,
+                message: message || "$assert() statement failed"
+            };
+        }
+
+        return undefined;
+    }
+
     /**
      * Implements the merge sort (stable) with optional comparator function
      *
@@ -1995,7 +2014,7 @@ const functions = (() => {
         formatNumber, formatBase, number, floor, ceil, round, abs, sqrt, power, random,
         boolean, not,
         map, zip, filter, single, foldLeft, sift,
-        keys, lookup, append, exists, spread, merge, reverse, each, error, sort, shuffle, distinct,
+        keys, lookup, append, exists, spread, merge, reverse, each, error, assert, sort, shuffle, distinct,
         base64encode, base64decode,  encodeUrlComponent, encodeUrl, decodeUrlComponent, decodeUrl
     };
 })();

src/jsonata.js

@@ -1858,6 +1858,7 @@ var jsonata = (function() {
     staticFrame.bind('reverse', defineFunction(fn.reverse, '<a:a>'));
     staticFrame.bind('each', defineFunction(fn.each, '<o-f:a>'));
     staticFrame.bind('error', defineFunction(fn.error, '<s?:x>'));
+    staticFrame.bind('assert', defineFunction(fn.assert, '<bs?:x>'));
     staticFrame.bind('sort', defineFunction(fn.sort, '<af?:a>'));
     staticFrame.bind('shuffle', defineFunction(fn.shuffle, '<a:a>'));
     staticFrame.bind('distinct', defineFunction(fn.distinct, '<x:x>'));
@@ -1980,7 +1981,8 @@ var jsonata = (function() {
         "D3137": "{{{message}}}",
         "D3138": "The $single() function expected exactly 1 matching result.  Instead it matched more.",
         "D3139": "The $single() function expected exactly 1 matching result.  Instead it matched 0.",
-        "D3140": "Malformed URL passed to ${{{functionName}}}(): {{value}}"
+        "D3140": "Malformed URL passed to ${{{functionName}}}(): {{value}}",
+        "D3141": "{{{message}}}"
     };
 
     /**

test/test-suite/datasets/dataset5.json

@@ -70,4 +70,4 @@
             }
         ]
     }
-}
+}

test/test-suite/groups/function-assert/case000.json

@@ -0,0 +1,9 @@
+{
+    "expr": "$assert(Account.Order[0].Product[0].Price < 34, 'Too Expensive')",
+    "dataset": "dataset5",
+    "bindings": {},
+    "error": {
+        "code": "D3141",
+        "message": "Too Expensive"
+    }    
+}

test/test-suite/groups/function-assert/case001.json

@@ -0,0 +1,6 @@
+{
+    "expr": "$assert(Account.Order[0].Product[0].Price < 35, 'Too Expensive')",
+    "dataset": "dataset5",
+    "bindings": {},
+    "undefinedResult": true
+}

test/test-suite/groups/function-assert/case002.json

@@ -0,0 +1,6 @@
+{
+    "expr": "($assert(Account.Order[0].Product[0].Price < 35, 'Too Expensive'); Account.Order[0].Product[0].Price)",
+    "dataset": "dataset5",
+    "bindings": {},
+    "result": 34.45
+}

test/test-suite/groups/function-assert/case003.json

@@ -0,0 +1,9 @@
+{
+    "expr": "($assert(Account.Order[0].Product[0].Price < 34, 'Too Expensive'); Account.Order[0].Product[0].Price)",
+    "dataset": "dataset5",
+    "bindings": {},
+    "error": {
+        "code": "D3141",
+        "message": "Too Expensive"
+    }
+}

test/test-suite/groups/function-assert/case004.json

@@ -0,0 +1,6 @@
+{
+    "expr": "$assert(null)",
+    "dataset": "dataset5",
+    "bindings": {},
+    "code": "T0410"
+}

test/test-suite/groups/function-assert/case005.json

@@ -0,0 +1,6 @@
+{
+    "expr": "$assert(5)",
+    "dataset": "dataset5",
+    "bindings": {},
+    "code": "T0410"
+}