Merge branch 'release/4.0.6'

CONTRIBUTING.md

@@ -2,14 +2,32 @@
 
 * [Issues](#issues)
 * [Pull Requests](#pull-requests)
+* [Setup development environmment](#setup-development-environment)
 
 ## Issues
 
 * State version of node/camaro/OS.
-* Include the script which can reproduce the issue.
+* Include a minimal script which can reproduce the issue.
 
 ## Pull Requests
 
 * Make sure all tests pass.
 * If new feature(s) is included, write test(s) for them as well.
 * Check the benchmark script to see if there's any performance regression.
+
+## Setup development environment
+
+It's easier to have Docker installed for development.
+
+```sh
+npm install
+
+# for fetching c++ dependencies using napa
+npm run install-deps
+
+# use docker to build. if you don't have Docker installed, you can use build.sh script
+npm run build
+
+# tests
+npm run test
+```

README.md

@@ -35,12 +35,12 @@
 ## 🔥 Benchmark
 
 ```
-camaro x 287 ops/sec ±0.74% (79 runs sampled)
-rapidx2j x 233 ops/sec ±0.49% (87 runs sampled)
-xml2json x 50.36 ops/sec ±1.08% (65 runs sampled)
-xml2js x 40.71 ops/sec ±8.94% (56 runs sampled)
-fast-xml-parser x 227 ops/sec ±1.07% (88 runs sampled)
-xml-js x 38.52 ops/sec ±7.82% (53 runs sampled)
+camaro x 362 ops/sec ±0.31% (87 runs sampled)
+rapidx2j x 226 ops/sec ±0.27% (88 runs sampled)
+xml2json x 46.32 ops/sec ±1.39% (61 runs sampled)
+xml2js x 50.51 ops/sec ±7.22% (68 runs sampled)
+fast-xml-parser x 256 ops/sec ±0.63% (86 runs sampled)
+xml-js x 45.05 ops/sec ±6.19% (61 runs sampled)
 ```
 
 * Please note that **this is an unfair game for camaro** because it only transform those fields specified in template.

benchmark/index.md

@@ -1,24 +1,28 @@
 # Benchmark
 
+Never mind about the actual number. You can check the percentage differences between package for reference.
+
+Benchmark ran on AMZ Ryzen 3800X.
+
 ## transform()
 
 `node benchmark/transform`
 
 ```
-camaro x 287 ops/sec ±0.74% (79 runs sampled)
-rapidx2j x 233 ops/sec ±0.49% (87 runs sampled)
-xml2json x 50.36 ops/sec ±1.08% (65 runs sampled)
-xml2js x 40.71 ops/sec ±8.94% (56 runs sampled)
-fast-xml-parser x 227 ops/sec ±1.07% (88 runs sampled)
-xml-js x 38.52 ops/sec ±7.82% (53 runs sampled)
+camaro x 362 ops/sec ±0.31% (87 runs sampled)
+rapidx2j x 226 ops/sec ±0.27% (88 runs sampled)
+xml2json x 46.32 ops/sec ±1.39% (61 runs sampled)
+xml2js x 50.51 ops/sec ±7.22% (68 runs sampled)
+fast-xml-parser x 256 ops/sec ±0.63% (86 runs sampled)
+xml-js x 45.05 ops/sec ±6.19% (61 runs sampled)
 ```
 
 ## prettyPrint()
 
 `node benchmark/pretty-print`
 
 ```
-camaro x 201,493 ops/sec ±1.25% (77 runs sampled)
-pretty-data x 132,456 ops/sec ±3.72% (85 runs sampled)
-prettify-xml x 199,420 ops/sec ±1.45% (91 runs sampled)
+camaro x 274,438 ops/sec ±0.56% (87 runs sampled)
+pretty-data x 155,168 ops/sec ±0.82% (94 runs sampled)
+prettify-xml x 244,450 ops/sec ±0.28% (94 runs sampled)
 ```

examples/array.md

@@ -0,0 +1,96 @@
+## Transform to array
+
+```xml
+<root>
+    <items>
+        <item>
+            <name>item 1</name>
+            <value>value 1</value>
+        </item>
+        <item>
+            <name>item 2</name>
+            <value>value 2</value>
+        </item>
+        <item>
+            <name>item 3</name>
+            <value>value 3</value>
+        </item>
+        <item>
+            <name>item 4</name>
+            <value>value 4</value>
+        </item>
+    </items>
+</root>
+```
+
+### Example 1
+
+```js
+const { transform } = require('camaro')
+
+;(async function() {
+    const template = {
+        items: ['/root/items/item', {
+            name: 'name',
+            value: 'value'
+        }]
+    }
+
+    const result = await transform(xml, template)
+    console.log(JSON.stringify(result, null, 2))
+})()
+```
+
+Output: 
+```
+{
+  "items": [
+    {
+      "name": "item 1",
+      "value": "value 1"
+    },
+    {
+      "name": "item 2",
+      "value": "value 2"
+    },
+    {
+      "name": "item 3",
+      "value": "value 3"
+    },
+    {
+      "name": "item 4",
+      "value": "value 4"
+    }
+  ]
+}
+```
+
+
+### Example 2
+
+Getting just names only as array of name string
+
+```js
+const { transform } = require('camaro')
+
+;(async function() {
+    const template = {
+        names: ['/root/items/item', 'name']
+    }
+
+    const result = await transform(xml, template)
+    console.log(JSON.stringify(result, null, 2))
+})()
+```
+
+Output: 
+```
+{
+  "names": [
+    "item 1",
+    "item 2",
+    "item 3",
+    "item 4"
+  ]
+}
+```

examples/default-value.md

@@ -0,0 +1,43 @@
+## Default value if a path value is empty
+
+Related issue: [#78](https://github.com/tuananh/camaro/issues/78)
+
+```js
+const { transform } = require('camaro')
+
+const xml = `
+    <items>
+        <item>hello</item>
+        <item />
+        <item>world</item>
+    </items>
+`
+const textOrDefault = (defaultValue) => `concat(
+    text(),
+    substring(
+        "${defaultValue}",
+        1,
+        number(not(text())) * string-length("${defaultValue}")
+    )
+)`
+const template = {
+    items: ['//items/item', textOrDefault('my default val')]
+}
+
+;(async function main() {
+    const output = await transform(xml, template)
+    console.log(JSON.stringify(output, null, 4))
+})();
+```
+
+Output
+
+```json
+{
+    "items": [
+        "hello",
+        "my default val",
+        "world"
+    ]
+}
+```

index.d.ts

@@ -1,5 +1,5 @@
 type transform = <T = any>(xml: string, template: object) => T;
 type toJson = <T = any>(xml: string) => T;
 type prettyPrint = <T = any>(xml: string) => T;
-declare const camaro: { transform, toJson, prettyPrint };
-export = camaro;
+declare const camaro: { transform: transform, toJson: toJson, prettyPrint: prettyPrint };
+export = camaro;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "camaro",
-  "version": "4.0.5",
+  "version": "4.0.6",
   "description": "Transforming XML to JSON using Node.js binding to native pugixml parser library",
   "homepage": "https://github.com/tuananh/camaro",
   "bugs": "https://github.com/tuananh/camaro/issues",