Add undocumented API to hook into when a new frame is created.

This is helpful in scenarios where you wish to debug the environment
behavior, or modify the env for advanced scenarios.

As the callback is set via a Symbol, it can not be manipulated
or read inside a query. See jsonata-js/jsonata/jsonata-js#700.

Author: adamscybot

src/jsonata.js

@@ -1837,7 +1837,7 @@ var jsonata = (function() {
      */
     function createFrame(enclosingEnvironment) {
         var bindings = {};
-        return {
+        const newFrame = {
             bind: function (name, value) {
                 bindings[name] = value;
             },
@@ -1857,6 +1857,16 @@ var jsonata = (function() {
                 ancestry: [ null ]
             }
         };
+
+        if (enclosingEnvironment) {
+            var framePushCallback = enclosingEnvironment.lookup(Symbol.for('jsonata.__createFrame_push'));
+            if(framePushCallback) {
+                framePushCallback(enclosingEnvironment, newFrame);
+            }
+        }
+       
+
+        return newFrame
     }
 
     // Function registration

test/implementation-tests.js

@@ -1024,6 +1024,21 @@ describe("Tests that include infinite recursion", () => {
     });
 });
 
+describe("Tests that use internal frame push callbacks", () => {
+    describe("frame push callback bound to expression", function()  {
+        it("calls callback when new frame created", function(done) {
+            var expr = jsonata("( )");
+            expr.assign(Symbol.for('jsonata.__createFrame_push'), function(parentEnv, newEnv) {
+                expect(parentEnv).to.not.equal(newEnv);
+                expect(parentEnv).to.include.keys(['lookup', 'bind']);
+                expect(newEnv).to.include.keys(['lookup', 'bind']);
+                done();
+            });
+            expr.evaluate();
+        });
+    });
+});
+
 /**
  * Protect the process/browser from a runnaway expression
  * i.e. Infinite loop (tail recursion), or excessive stack growth