From f02bfd2172be1efc4f6e4c195a8499dc60319497 Mon Sep 17 00:00:00 2001
From: rafearnold <rafe.arnold@gmail.com>
Date: Fri, 22 Nov 2024 10:13:56 +0000
Subject: [PATCH 1/6] document formatJson handlebars helper.

---
 _docs/response-templating.md | 59 ++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/_docs/response-templating.md b/_docs/response-templating.md
index ba2be195..8b5e858b 100644
--- a/_docs/response-templating.md
+++ b/_docs/response-templating.md
@@ -546,6 +546,65 @@ Without assigning to a variable:
 
 {% endraw %}
 
+## Format JSON helper
+
+The `formatJson` helper will rewrite the input JSON into a format of your choice.
+
+{% raw %}
+
+```handlebars
+{{#formatJson}}{"foo":true,"bar":{"baz":false}}{{/formatJson}}
+```
+
+{% endraw %}
+
+By default, the input will be rewritten to a "pretty" format (new lines and indentation):
+
+{% raw %}
+
+```json
+{
+  "foo" : true,
+  "bar" : {
+    "baz" : false
+  }
+}
+```
+
+{% endraw %}
+
+The format can be controlled by supplying a `format` option:
+
+{% raw %}
+
+```handlebars
+{{#formatJson format='compact'}}
+{
+    "foo" : true,
+    "bar" : {
+        "baz" : false
+    }
+}
+{{/formatJson}}
+```
+
+{% endraw %}
+
+The available `format` options are `compact` (all whitespace removed) and `pretty`.
+
+The input JSON can alternatively be supplied inline, or as a variable:
+
+{% raw %}
+
+```handlebars
+{{formatJson '{"foo":true,"bar":{"baz":false}}'}}
+
+{{#assign 'someJson'}} { "foo": true, "bar": { "baz": false } } {{/assign}}
+{{formatJson someJson format='compact'}}
+```
+
+{% endraw %}
+
 ## Date and time helpers
 
 A helper is present to render the current date/time, with the ability to specify the format ([via Java's SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html)) and offset.

From 8099ab56d69176f3d4238dd11a97ee6662b9e96a Mon Sep 17 00:00:00 2001
From: rafearnold <rafe.arnold@gmail.com>
Date: Fri, 22 Nov 2024 10:24:33 +0000
Subject: [PATCH 2/6] document formatXml handlebars helper.

---
 _docs/response-templating.md | 59 +++++++++++++++++++++++++++++++++++-
 1 file changed, 58 insertions(+), 1 deletion(-)

diff --git a/_docs/response-templating.md b/_docs/response-templating.md
index 8b5e858b..a37f32c2 100644
--- a/_docs/response-templating.md
+++ b/_docs/response-templating.md
@@ -461,9 +461,66 @@ A common use case for returned node objects is to iterate over the collection wi
 
 {% endraw %}
 
+## Format XML helper
+
+The `formatXml` helper will rewrite the input XML into a format of your choice.
+
+{% raw %}
+
+```handlebars
+{{#formatXml}}
+<foo><bar
+>wh</bar></foo
+>
+{{/formatXml}}
+```
+
+{% endraw %}
+
+By default, the input will be rewritten to a "pretty" format (new lines and indentation):
+
+{% raw %}
+
+```xml
+<foo>
+    <bar>wh</bar>
+</foo>
+```
+
+{% endraw %}
+
+The format can be controlled by supplying a `format` option:
+
+{% raw %}
+
+```handlebars
+{{#formatXml format='compact'}}
+<foo><bar
+>wh</bar></foo
+>
+{{/formatXml}}
+```
+
+{% endraw %}
+
+The available `format` options are `compact` (all whitespace removed) and `pretty`.
+
+The input XML can alternatively be supplied inline, or as a variable:
+
+{% raw %}
+
+```handlebars
+{{formatXml '{"foo":true,"bar":{"baz":false}}'}}
+
+{{#assign 'someXml'}} <foo>  <bar>wh</bar>  </foo> {{/assign}}
+{{formatXml someXml format='compact'}}
+```
+
+{% endraw %}
+
 ## JSONPath helper
 
-It is similarly possible to extract JSON values or sub documents via JSONPath using the `jsonPath` helper. Given the JSON
+Like the `xPath` helper, it is similarly possible to extract JSON values or sub documents via JSONPath using the `jsonPath` helper. Given the JSON
 
 ```json
 {

From ccf5cad864b4709ec803590463c691fb2f57f0a1 Mon Sep 17 00:00:00 2001
From: rafearnold <rafe.arnold@gmail.com>
Date: Fri, 22 Nov 2024 10:32:48 +0000
Subject: [PATCH 3/6] document toJson handlebars helper.

---
 _docs/response-templating.md | 54 ++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/_docs/response-templating.md b/_docs/response-templating.md
index a37f32c2..74b29c26 100644
--- a/_docs/response-templating.md
+++ b/_docs/response-templating.md
@@ -603,6 +603,60 @@ Without assigning to a variable:
 
 {% endraw %}
 
+## Write as JSON helper
+
+The `toJson` helper will convert any object into a JSON string.
+
+{% raw %}
+
+```handlebars
+{{toJson (array 1 2 3)}}
+```
+
+{% endraw %}
+
+emits
+
+{% raw %}
+
+```json
+[ 1, 2, 3 ]
+```
+
+{% endraw %}
+
+Given a request with the following headers:
+
+{% raw %}
+
+```
+Authorization: whatever
+Content-Type: text/plain
+```
+
+{% endraw %}
+
+{% raw %}
+
+```handlebars
+{{toJson request.headers}}
+```
+
+{% endraw %}
+
+will produce
+
+{% raw %}
+
+```json
+{
+  "Authorization" : "whatever",
+  "Content-Type" : "text/plain"
+}
+```
+
+{% endraw %}
+
 ## Format JSON helper
 
 The `formatJson` helper will rewrite the input JSON into a format of your choice.

From 77345610dc65fb6df9fbbced32009fbabc27c8b3 Mon Sep 17 00:00:00 2001
From: rafearnold <rafe.arnold@gmail.com>
Date: Fri, 22 Nov 2024 10:40:35 +0000
Subject: [PATCH 4/6] document jsonArrayAdd handlebars helper.

---
 _docs/response-templating.md | 79 ++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)

diff --git a/_docs/response-templating.md b/_docs/response-templating.md
index 74b29c26..dbdf559b 100644
--- a/_docs/response-templating.md
+++ b/_docs/response-templating.md
@@ -716,6 +716,85 @@ The input JSON can alternatively be supplied inline, or as a variable:
 
 {% endraw %}
 
+## Adding to a JSON Array
+
+The `jsonArrayAdd` helper allows you to append an element to an existing json array.
+
+Its simplest form just takes two parameters, the JSON array to append to and the JSON item to be added:
+
+{% raw %}
+
+```handlebars
+{{#assign 'existingArray'}}
+[
+    {
+        "id": 123,
+        "name": "alice"
+    }
+]
+{{/assign}}
+
+{{#assign 'newItem'}}
+{
+    "id": 321,
+    "name": "sam"
+}
+{{/assign}}
+
+{{jsonArrayAdd existingArray newItem}}
+```
+
+{% endraw %}
+
+The above template will produce the following JSON:
+
+{% raw %}
+
+```json
+[
+    {
+        "id": 123,
+        "name": "alice"
+    },
+    {
+        "id": 321,
+        "name": "sam"
+    }
+]
+```
+
+{% endraw %}
+
+You can also use it in block form to parse the contents of the block as the new item to add:
+
+{% raw %}
+
+```handlebars
+{{#jsonArrayAdd existingArray}}
+{
+    "id": 321,
+    "name": "sam"
+}
+{{/jsonArrayAdd}}
+```
+
+{% endraw %}
+
+It may be convenient to default the array to an empty array if it does not exist:
+
+{% raw %}
+
+```handlebars
+{{#jsonArrayAdd (val existingArray or='[]')}}
+{
+    "id": 321,
+    "name": "sam"
+}
+{{/jsonArrayAdd}}
+```
+
+{% endraw %}
+
 ## Date and time helpers
 
 A helper is present to render the current date/time, with the ability to specify the format ([via Java's SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html)) and offset.

From 7d1f69552f5d0bd3991c0c64c42608c92878a93d Mon Sep 17 00:00:00 2001
From: rafearnold <rafe.arnold@gmail.com>
Date: Fri, 22 Nov 2024 10:45:05 +0000
Subject: [PATCH 5/6] document jsonMerge handlebars helper.

---
 _docs/response-templating.md | 83 ++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/_docs/response-templating.md b/_docs/response-templating.md
index dbdf559b..ee96c06a 100644
--- a/_docs/response-templating.md
+++ b/_docs/response-templating.md
@@ -795,6 +795,89 @@ It may be convenient to default the array to an empty array if it does not exist
 
 {% endraw %}
 
+## Merging JSON objects
+
+The `jsonMerge` helper allows you to merge two json objects.
+Merging will recurse into any common keys where the values are both objects, but not into any array values,
+where the value in the second object will overwrite that in the first.
+
+Given these two objects:
+
+{% raw %}
+
+```handlebars
+{{#assign 'object1'}}
+    {
+    "id": 456,
+    "forename": "Robert",
+    "surname": "Smith",
+    "address": {
+    "number": "12"
+    },
+    "hobbies": [ "chess", "football" ]
+    }
+{{/assign}}
+{{#assign 'object2'}}
+    {
+    "forename": "Robert",
+    "nickname": "Bob",
+    "address": {
+    "street": "High Street"
+    },
+    "hobbies": [ "rugby" ]
+    }
+{{/assign}}
+```
+
+{% endraw %}
+
+{% raw %}
+
+```handlebars
+{{jsonMerge object1 object2}}
+```
+
+{% endraw %}
+
+will return this object:
+
+{% raw %}
+
+```json
+{
+    "id": 456,
+    "forename": "Robert",
+    "surname": "Smith",
+    "nickname": "Bob",
+    "address": {
+        "number": "12",
+        "street": "High Street"
+    },
+    "hobbies": [ "rugby" ]
+}
+```
+
+{% endraw %}
+
+Like the `jsonArrayAdd` helper, the second object can be provided as a block:
+
+{% raw %}
+
+```handlebars
+{{#jsonMerge object1}}
+{
+    "forename": "Robert",
+    "nickname": "Bob",
+    "address": {
+        "street": "High Street"
+    },
+    "hobbies": [ "rugby" ]
+}
+{{/jsonMerge}}
+```
+
+{% endraw %}
+
 ## Date and time helpers
 
 A helper is present to render the current date/time, with the ability to specify the format ([via Java's SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html)) and offset.

From ff44bedb1c1639c971b9c2c28e5d7ea5f529625a Mon Sep 17 00:00:00 2001
From: rafearnold <rafe.arnold@gmail.com>
Date: Fri, 22 Nov 2024 10:48:26 +0000
Subject: [PATCH 6/6] document jsonRemove handlebars helper.

---
 _docs/response-templating.md | 76 ++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

diff --git a/_docs/response-templating.md b/_docs/response-templating.md
index ee96c06a..3203d793 100644
--- a/_docs/response-templating.md
+++ b/_docs/response-templating.md
@@ -878,6 +878,82 @@ Like the `jsonArrayAdd` helper, the second object can be provided as a block:
 
 {% endraw %}
 
+## Removing from a JSON Array or Object
+
+The `jsonRemove` helper allows you to remove an element from an existing json array, or remove a key from an existing
+json object, by identifying it using a [json path](https://datatracker.ietf.org/doc/rfc9535/) expression.
+
+For instance, given an existing array like this:
+
+{% raw %}
+
+```handlebars
+{{#assign 'existingArray'}}
+[
+    { "id": 456, "name": "bob"},
+    { "id": 123, "name": "alice"},
+    { "id": 321, "name": "sam"}
+]
+{{/assign}}
+```
+
+{% endraw %}
+
+application of this helper, which selects the object with id `123`:
+
+{% raw %}
+
+```handlebars
+{{jsonRemove existingArray '$.[?(@.id == 123)]'}}
+```
+
+{% endraw %}
+
+will return this array:
+
+{% raw %}
+
+```json
+[
+    { "id": 456, "name": "bob"},
+    { "id": 321, "name": "sam"}
+]
+```
+
+{% endraw %}
+
+Given an object like this:
+
+{% raw %}
+
+```handlebars
+{{#assign 'existingObject'}}
+    { "id": 456, "name": "bob"}
+{{/assign}}
+```
+
+{% endraw %}
+
+application of this helper, which selects the key name:
+
+{% raw %}
+
+```handlebars
+{{jsonRemove existingObject '$.name'}}
+```
+
+{% endraw %}
+
+will return this object:
+
+{% raw %}
+
+```json
+{ "id": 456 }
+```
+
+{% endraw %}
+
 ## Date and time helpers
 
 A helper is present to render the current date/time, with the ability to specify the format ([via Java's SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html)) and offset.