cborg 1.6.1 → 1.8.0

package/README.md

@@ -10,9 +10,18 @@
 
 * [Example](#example)
 * [CLI](#cli)
-  * [`cborg json2hex '<json string>'`](#cborg-json2hex-json-string)
-  * [`cborg hex2json [--pretty] <hex string>`](#cborg-hex2json---pretty-hex-string)
-  * [`cborg hex2diag <hex string>`](#cborg-hex2diag-hex-string)
+  * [`cborg bin2diag [binary input]`](#cborg-bin2diag-binary-input)
+  * [`cborg bin2hex [binary string]`](#cborg-bin2hex-binary-string)
+  * [`cborg bin2json [--pretty] [binary input]`](#cborg-bin2json---pretty-binary-input)
+  * [`cborg diag2bin [diagnostic string]`](#cborg-diag2bin-diagnostic-string)
+  * [`cborg diag2hex [diagnostic string]`](#cborg-diag2hex-diagnostic-string)
+  * [`cborg diag2json [--pretty] [diagnostic string]`](#cborg-diag2json---pretty-diagnostic-string)
+  * [`cborg hex2bin [hex string]`](#cborg-hex2bin-hex-string)
+  * [`cborg hex2diag [hex string]`](#cborg-hex2diag-hex-string)
+  * [`cborg hex2json [--pretty] [hex string]`](#cborg-hex2json---pretty-hex-string)
+  * [`cborg json2bin [json string]`](#cborg-json2bin-json-string)
+  * [`cborg json2diag [json string]`](#cborg-json2diag-json-string)
+  * [`cborg json2hex '[json string]'`](#cborg-json2hex-json-string)
 * [API](#api)
   * [`encode(object[, options])`](#encodeobject-options)
     * [Options](#options)
@@ -50,18 +59,87 @@ encoded: Uint8Array(21) [
 
 When installed globally via `npm` (with `npm install cborg --global`), the `cborg` command will be available that provides some handy CBOR CLI utilities. Run with `cborg help` for additional details.
 
-### `cborg json2hex '<json string>'`
+The following commands take either input from the command line, or if no input is supplied will read from stdin. Output is printed to stdout. So you can `cat foo | cborg <command>`.
 
-Convert a JSON object into CBOR bytes in hexadecimal format.
+### `cborg bin2diag [binary input]`
+
+Convert CBOR from binary input to a CBOR diagnostic output format which explains the byte contents.
 
 ```
-$ cborg json2hex '["a", "b", 1, "😀"]'
+$ cborg hex2bin 84616161620164f09f9880 | cborg bin2diag
+84                                                # array(4)
+  61                                              #   string(1)
+    61                                            #     "a"
+  61                                              #   string(1)
+    62                                            #     "b"
+  01                                              #   uint(1)
+  64 f09f                                         #   string(2)
+    f09f9880                                      #     "😀"
+```
+
+### `cborg bin2hex [binary string]`
+
+A utility method to convert a binary input (stdin only) to hexadecimal output (does not involve CBOR).
+
+### `cborg bin2json [--pretty] [binary input]`
+
+Convert CBOR from binary input to JSON format.
+
+```
+$ cborg hex2bin 84616161620164f09f9880 | cborg bin2json
+["a","b",1,"😀"]
+```
+
+### `cborg diag2bin [diagnostic string]`
+
+Convert a CBOR diagnostic string to a binary data form of the CBOR.
+
+```
+$ cborg json2diag '["a","b",1,"😀"]' | cborg diag2bin | cborg bin2hex
 84616161620164f09f9880
 ```
 
-### `cborg hex2json [--pretty] <hex string>`
+### `cborg diag2hex [diagnostic string]`
 
-Convert a hexadecimal string to a JSON format.
+Convert a CBOR diagnostic string to the CBOR bytes in hexadecimal format.
+
+```
+$ cborg json2diag '["a","b",1,"😀"]' | cborg diag2hex
+84616161620164f09f9880
+```
+
+### `cborg diag2json [--pretty] [diagnostic string]`
+
+Convert a CBOR diagnostic string to JSON format.
+
+```
+$ cborg json2diag '["a","b",1,"😀"]' | cborg diag2json
+["a","b",1,"😀"]
+```
+
+### `cborg hex2bin [hex string]`
+
+A utility method to convert a hex string to binary output (does not involve CBOR).
+
+### `cborg hex2diag [hex string]`
+
+Convert CBOR from a hexadecimal string to a CBOR diagnostic output format which explains the byte contents.
+
+```
+$ cborg hex2diag 84616161620164f09f9880
+84                                                # array(4)
+  61                                              #   string(1)
+    61                                            #     "a"
+  61                                              #   string(1)
+    62                                            #     "b"
+  01                                              #   uint(1)
+  64 f09f                                         #   string(2)
+    f09f9880                                      #     "😀"
+```
+
+### `cborg hex2json [--pretty] [hex string]`
+
+Convert CBOR from a hexadecimal string to JSON format.
 
 ```
 $ cborg hex2json 84616161620164f09f9880
@@ -75,12 +153,21 @@ $ cborg hex2json --pretty 84616161620164f09f9880
 ]
 ```
 
-### `cborg hex2diag <hex string>`
+### `cborg json2bin [json string]`
 
-Convert a hexadecimal string to a CBOR diagnostic output format which explains the byte contents.
+Convert a JSON object into a binary data form of the CBOR.
 
 ```
-$ cborg hex2diag 84616161620164f09f9880
+$ cborg json2bin '["a","b",1,"😀"]' | cborg bin2hex
+84616161620164f09f9880
+```
+
+### `cborg json2diag [json string]`
+
+Convert a JSON object into a CBOR diagnostic output format which explains the contents of the CBOR form of the input object.
+
+```
+$ cborg json2diag '["a", "b", 1, "😀"]'
 84                                                # array(4)
   61                                              #   string(1)
     61                                            #     "a"
@@ -91,6 +178,15 @@ $ cborg hex2diag 84616161620164f09f9880
     f09f9880                                      #     "😀"
 ```
 
+### `cborg json2hex '[json string]'`
+
+Convert a JSON object into CBOR bytes in hexadecimal format.
+
+```
+$ cborg json2hex '["a", "b", 1, "😀"]'
+84616161620164f09f9880
+```
+
 ## API
 
 ### `encode(object[, options])`
@@ -150,6 +246,7 @@ Decode valid CBOR bytes from a `Uint8Array` (or `Buffer`) and return a JavaScrip
 * `strict` (boolean, default `false`): when decoding integers, including for lengths (arrays, maps, strings, bytes), values will be checked to see whether they were encoded in their smallest possible form. If not, an error will be thrown.
   * Currently, this form of deterministic strictness cannot be enforced for float representations, or map key ordering (pull requests _very_ welcome).
 * `useMaps` (boolean, default `false`): when decoding major 5 (map) entries, use a `Map` rather than a plain `Object`. This will nest for any encountered map. During encode, a `Map` will be interpreted as an `Object` and will round-trip as such unless `useMaps` is supplied, in which case, all `Map`s and `Object`s will round-trip as `Map`s. There is no way to retain the distinction during round-trip without using a custom tag.
+* `retainStringBytes` (boolean, default `false`): when decoding strings, retain the original bytes on the `Token` object as `byteValue`. Since it is possible to encode non-UTF-8 characters in strings in CBOR, and JavaScript doesn't properly handle non-UTF-8 in its conversion from bytes (`TextEncoder` or `Buffer`), this can result in a loss of data (and an inability to round-trip). Where this is important, a token stream should be consumed instead of a plain `decode()` and the `byteValue` property on string tokens can be inspected (see [lib/diagnostic.js](lib/diagnostic.js) for an example of its use.)
 * `tags` (array): a mapping of tag number to tag decoder function. By default no tags are supported. See [Tag decoders](#tag-decoders).
 * `tokenizer` (object): an object with two methods, `next()` which returns a `Token` and `done()` which returns a `boolean`. Can be used to implement custom input decoding. See the source code for examples.
 

package/cjs/browser-test/node-test-bin.js

@@ -4,6 +4,7 @@ var chai = require('chai');
 var child_process = require('child_process');
 var process = require('process');
 var path = require('path');
+var os = require('os');
 var url = require('url');
 require('../lib/bin.js');
 
@@ -14,6 +15,52 @@ var process__default = /*#__PURE__*/_interopDefaultLegacy(process);
 var path__default = /*#__PURE__*/_interopDefaultLegacy(path);
 
 const {assert} = chai__default["default"];
+const fixture1JsonString = '{"a":1,"b":[2,3],"smile":"\uD83D\uDE00"}';
+const fixture1JsonPrettyString = `{
+  "a": 1,
+  "b": [
+    2,
+    3
+  ],
+  "smile": "😀"
+}
+`;
+const fixture1HexString = 'a3616101616282020365736d696c6564f09f9880';
+const fixture1Bin = fromHex(fixture1HexString);
+const fixture1BinString = new TextDecoder().decode(fixture1Bin);
+const fixture1DiagnosticString = `a3                                                # map(3)
+  61                                              #   string(1)
+    61                                            #     "a"
+  01                                              #   uint(1)
+  61                                              #   string(1)
+    62                                            #     "b"
+  82                                              #   array(2)
+    02                                            #     uint(2)
+    03                                            #     uint(3)
+  65                                              #   string(5)
+    736d696c65                                    #     "smile"
+  64                                              #   string(2)
+    f09f9880                                      #     "😀"
+`;
+const fixture2HexString = 'a4616101616282020363627566440102036165736d696c6564f09f9880';
+const fixture2DiagnosticString = `a4                                                # map(4)
+  61                                              #   string(1)
+    61                                            #     "a"
+  01                                              #   uint(1)
+  61                                              #   string(1)
+    62                                            #     "b"
+  82                                              #   array(2)
+    02                                            #     uint(2)
+    03                                            #     uint(3)
+  63                                              #   string(3)
+    627566                                        #     "buf"
+  44                                              #   bytes(4)
+    01020361                                      #     "\\x01\\x02\\x03a"
+  65                                              #   string(5)
+    736d696c65                                    #     "smile"
+  64                                              #   string(2)
+    f09f9880                                      #     "😀"
+`;
 const binPath = path__default["default"].join(path__default["default"].dirname(url.fileURLToPath((typeof document === 'undefined' ? new (require('u' + 'rl').URL)('file:' + __filename).href : (document.currentScript && document.currentScript.src || new URL('browser-test/node-test-bin.js', document.baseURI).href)))), '../lib/bin.js');
 function fromHex(hex) {
   return new Uint8Array(hex.split('').map((c, i, d) => i % 2 === 0 ? `0x${ c }${ d[i + 1] }` : '').filter(Boolean).map(e => parseInt(e, 16)));
@@ -48,15 +95,18 @@ describe('Bin', () => {
       assert.strictEqual(e.stdout, '');
       assert.strictEqual(e.stderr, `Usage: cborg <command> <args>
 Valid commands:
-\thex2diag [hex input]
-\thex2bin [hex input]
-\thex2json [--pretty] [hex input]
-\tbin2hex [binary input]
 \tbin2diag [binary input]
+\tbin2hex [binary input]
 \tbin2json [--pretty] [binary input]
-\tjson2hex '[json input]'
-\tjson2diag '[json input]'
+\tdiag2bin [diagnostic input]
+\tdiag2hex [diagnostic input]
+\tdiag2json [--pretty] [diagnostic input]
+\thex2bin [hex input]
+\thex2diag [hex input]
+\thex2json [--pretty] [hex input]
 \tjson2bin '[json input]'
+\tjson2diag '[json input]'
+\tjson2hex '[json input]'
 Input may either be supplied as an argument or piped via stdin
 `);
     }
@@ -70,15 +120,18 @@ Input may either be supplied as an argument or piped via stdin
       assert.strictEqual(e.stderr, `Unknown command: 'blip'
 Usage: cborg <command> <args>
 Valid commands:
-\thex2diag [hex input]
-\thex2bin [hex input]
-\thex2json [--pretty] [hex input]
-\tbin2hex [binary input]
 \tbin2diag [binary input]
+\tbin2hex [binary input]
 \tbin2json [--pretty] [binary input]
-\tjson2hex '[json input]'
-\tjson2diag '[json input]'
+\tdiag2bin [diagnostic input]
+\tdiag2hex [diagnostic input]
+\tdiag2json [--pretty] [diagnostic input]
+\thex2bin [hex input]
+\thex2diag [hex input]
+\thex2json [--pretty] [hex input]
 \tjson2bin '[json input]'
+\tjson2diag '[json input]'
+\tjson2hex '[json input]'
 Input may either be supplied as an argument or piped via stdin
 `);
     }
@@ -88,135 +141,209 @@ Input may either be supplied as an argument or piped via stdin
     assert.strictEqual(stdout, '');
     assert.strictEqual(stderr, `Usage: cborg <command> <args>
 Valid commands:
-\thex2diag [hex input]
-\thex2bin [hex input]
-\thex2json [--pretty] [hex input]
-\tbin2hex [binary input]
 \tbin2diag [binary input]
+\tbin2hex [binary input]
 \tbin2json [--pretty] [binary input]
-\tjson2hex '[json input]'
-\tjson2diag '[json input]'
+\tdiag2bin [diagnostic input]
+\tdiag2hex [diagnostic input]
+\tdiag2json [--pretty] [diagnostic input]
+\thex2bin [hex input]
+\thex2diag [hex input]
+\thex2json [--pretty] [hex input]
 \tjson2bin '[json input]'
+\tjson2diag '[json input]'
+\tjson2hex '[json input]'
 Input may either be supplied as an argument or piped via stdin
 `);
   });
+  it('bin2diag (stdin)', async () => {
+    const {stdout, stderr} = await execBin('bin2diag', fixture1Bin);
+    assert.strictEqual(stderr, '');
+    assert.strictEqual(stdout, fixture1DiagnosticString);
+  });
+  it('bin2hex (stdin)', async () => {
+    const {stdout, stderr} = await execBin('bin2hex', fixture1Bin);
+    assert.strictEqual(stderr, '');
+    assert.strictEqual(stdout, `${ fixture1HexString }\n`);
+  });
+  it('bin2json (stdin)', async () => {
+    const {stdout, stderr} = await execBin('bin2json', fixture1Bin);
+    assert.strictEqual(stderr, '');
+    assert.strictEqual(stdout, `${ fixture1JsonString }\n`);
+  });
+  it('bin2json pretty (stdin)', async () => {
+    const {stdout, stderr} = await execBin('bin2json --pretty', fixture1Bin);
+    assert.strictEqual(stderr, '');
+    assert.strictEqual(stdout, fixture1JsonPrettyString);
+  });
   for (const stdin of [
       true,
       false
     ]) {
-    it(`hex2json${ stdin ? ' (stdin)' : '' }`, async () => {
-      const {stdout, stderr} = stdin ? await execBin('hex2json a3616101616282020365736d696c6564f09f9880') : await execBin('hex2json', 'a3616101616282020365736d696c6564f09f9880');
-      assert.strictEqual(stderr, '');
-      assert.strictEqual(stdout, '{"a":1,"b":[2,3],"smile":"\uD83D\uDE00"}\n');
-    });
-    it(`hex2json pretty${ stdin ? ' (stdin)' : '' }`, async () => {
-      const {stdout, stderr} = stdin ? await execBin('hex2json --pretty a3616101616282020365736d696c6564f09f9880') : await execBin('hex2json --pretty', 'a3616101616282020365736d696c6564f09f9880');
+    if (os.platform() !== 'win32' || stdin) {
+      it(`diag2bin${ stdin ? ' (stdin)' : '' }`, async () => {
+        const {stdout, stderr} = !stdin ? await execBin(`diag2bin '${ fixture1DiagnosticString }'`) : await execBin('diag2bin', fixture1DiagnosticString);
+        assert.strictEqual(stderr, '');
+        assert.strictEqual(stdout, fixture1BinString);
+      });
+      it(`diag2hex${ stdin ? ' (stdin)' : '' }`, async () => {
+        const {stdout, stderr} = !stdin ? await execBin(`diag2hex '${ fixture1DiagnosticString }'`) : await execBin('diag2hex', fixture1DiagnosticString);
+        assert.strictEqual(stderr, '');
+        assert.strictEqual(stdout, `${ fixture1HexString }\n`);
+      });
+      it(`diag2json${ stdin ? ' (stdin)' : '' }`, async () => {
+        const {stdout, stderr} = !stdin ? await execBin(`diag2json '${ fixture1DiagnosticString }'`) : await execBin('diag2json', fixture1DiagnosticString);
+        assert.strictEqual(stderr, '');
+        assert.strictEqual(stdout, `${ fixture1JsonString }\n`);
+      });
+      it(`diag2json pretty${ stdin ? ' (stdin)' : '' }`, async () => {
+        const {stdout, stderr} = !stdin ? await execBin(`diag2json --pretty '${ fixture1DiagnosticString }'`) : await execBin('diag2json --pretty', fixture1DiagnosticString);
+        assert.strictEqual(stderr, '');
+        assert.strictEqual(stdout, fixture1JsonPrettyString);
+      });
+    }
+    it(`hex2bin${ stdin ? ' (stdin)' : '' }`, async () => {
+      const {stdout, stderr} = !stdin ? await execBin(`hex2bin ${ fixture1HexString }`) : await execBin('hex2bin', fixture1HexString);
       assert.strictEqual(stderr, '');
-      assert.strictEqual(stdout, `{
-  "a": 1,
-  "b": [
-    2,
-    3
-  ],
-  "smile": "😀"
-}
-`);
+      assert.strictEqual(stdout, fixture1BinString);
     });
     it(`hex2diag${ stdin ? ' (stdin)' : '' }`, async () => {
-      const {stdout, stderr} = stdin ? await execBin('hex2diag a4616101616282020363627566440102036165736d696c6564f09f9880') : await execBin('hex2diag', 'a4616101616282020363627566440102036165736d696c6564f09f9880');
+      const {stdout, stderr} = !stdin ? await execBin(`hex2diag ${ fixture2HexString }`) : await execBin('hex2diag', fixture2HexString);
       assert.strictEqual(stderr, '');
-      assert.strictEqual(stdout, `a4                                                # map(4)
-  61                                              #   string(1)
-    61                                            #     "a"
-  01                                              #   uint(1)
-  61                                              #   string(1)
-    62                                            #     "b"
-  82                                              #   array(2)
-    02                                            #     uint(2)
-    03                                            #     uint(3)
-  63                                              #   string(3)
-    627566                                        #     "buf"
-  44                                              #   bytes(4)
-    01020361                                      #     "\\x01\\x02\\x03a"
-  65                                              #   string(5)
-    736d696c65                                    #     "smile"
-  64 f09f                                         #   string(2)
-    f09f9880                                      #     "😀"
-`);
+      assert.strictEqual(stdout, fixture2DiagnosticString);
     });
-    it(`hex2bin${ stdin ? ' (stdin)' : '' }`, async () => {
-      const {stdout, stderr} = stdin ? await execBin('hex2bin a3616101616282020365736d696c6564f09f9880') : await execBin('hex2bin', 'a3616101616282020365736d696c6564f09f9880');
+    it(`hex2json${ stdin ? ' (stdin)' : '' }`, async () => {
+      const {stdout, stderr} = !stdin ? await execBin(`hex2json ${ fixture1HexString }`) : await execBin('hex2json', fixture1HexString);
       assert.strictEqual(stderr, '');
-      assert.strictEqual(stdout, new TextDecoder().decode(fromHex('a3616101616282020365736d696c6564f09f9880')));
+      assert.strictEqual(stdout, `${ fixture1JsonString }\n`);
     });
-    it(`json2hex${ stdin ? ' (stdin)' : '' }`, async () => {
-      const {stdout, stderr} = stdin ? await execBin('json2hex "{\\"a\\":1,\\"b\\":[2,3],\\"smile\\":\\"\uD83D\uDE00\\"}"') : await execBin('json2hex', '{"a":1,"b":[2,3],"smile":"\uD83D\uDE00"}');
+    it(`hex2json pretty${ stdin ? ' (stdin)' : '' }`, async () => {
+      const {stdout, stderr} = !stdin ? await execBin(`hex2json --pretty ${ fixture1HexString }`) : await execBin('hex2json --pretty', fixture1HexString);
       assert.strictEqual(stderr, '');
-      assert.strictEqual(stdout, 'a3616101616282020365736d696c6564f09f9880\n');
+      assert.strictEqual(stdout, fixture1JsonPrettyString);
     });
     it(`json2bin${ stdin ? ' (stdin)' : '' }`, async () => {
-      const {stdout, stderr} = stdin ? await execBin('json2bin "{\\"a\\":1,\\"b\\":[2,3],\\"smile\\":\\"\uD83D\uDE00\\"}"') : await execBin('json2bin', '{"a":1,"b":[2,3],"smile":"\uD83D\uDE00"}');
+      const {stdout, stderr} = !stdin ? await execBin('json2bin "{\\"a\\":1,\\"b\\":[2,3],\\"smile\\":\\"\uD83D\uDE00\\"}"') : await execBin('json2bin', fixture1JsonString);
       assert.strictEqual(stderr, '');
-      assert.strictEqual(stdout, new TextDecoder().decode(fromHex('a3616101616282020365736d696c6564f09f9880')));
+      assert.strictEqual(stdout, fixture1BinString);
     });
     it(`json2diag${ stdin ? ' (stdin)' : '' }`, async () => {
-      const {stdout, stderr} = stdin ? await execBin('json2diag "{\\"a\\":1,\\"b\\":[2,3],\\"smile\\":\\"\uD83D\uDE00\\"}"') : await execBin('json2diag', '{"a":1,"b":[2,3],"smile":"\uD83D\uDE00"}');
+      const {stdout, stderr} = !stdin ? await execBin('json2diag "{\\"a\\":1,\\"b\\":[2,3],\\"smile\\":\\"\uD83D\uDE00\\"}"') : await execBin('json2diag', fixture1JsonString);
       assert.strictEqual(stderr, '');
-      assert.strictEqual(stdout, `a3                                                # map(3)
-  61                                              #   string(1)
-    61                                            #     "a"
-  01                                              #   uint(1)
-  61                                              #   string(1)
-    62                                            #     "b"
-  82                                              #   array(2)
-    02                                            #     uint(2)
-    03                                            #     uint(3)
-  65                                              #   string(5)
-    736d696c65                                    #     "smile"
-  64 f09f                                         #   string(2)
-    f09f9880                                      #     "😀"
-`);
+      assert.strictEqual(stdout, fixture1DiagnosticString);
+    });
+    it(`json2hex${ stdin ? ' (stdin)' : '' }`, async () => {
+      const {stdout, stderr} = !stdin ? await execBin(`json2hex "${ fixture1JsonString.replace(/"/g, '\\"') }"`) : await execBin('json2hex', fixture1JsonString);
+      assert.strictEqual(stderr, '');
+      assert.strictEqual(stdout, `${ fixture1HexString }\n`);
     });
   }
-  it('bin2diag (stdin)', async () => {
-    const {stdout, stderr} = await execBin('bin2diag', fromHex('a3616101616282020365736d696c6564f09f9880'));
+  it('diag indenting', async () => {
+    const {stdout, stderr} = await execBin('json2diag', '{"a":[],"b":{},"c":{"a":1,"b":{"a":{"a":{}}}},"d":{"a":{"a":{"a":1},"b":2,"c":[]}},"e":[[[[{"a":{}}]]]],"f":1}');
     assert.strictEqual(stderr, '');
-    assert.strictEqual(stdout, `a3                                                # map(3)
+    assert.strictEqual(stdout, `a6                                                # map(6)
   61                                              #   string(1)
     61                                            #     "a"
-  01                                              #   uint(1)
+  80                                              #   array(0)
   61                                              #   string(1)
     62                                            #     "b"
-  82                                              #   array(2)
-    02                                            #     uint(2)
-    03                                            #     uint(3)
-  65                                              #   string(5)
-    736d696c65                                    #     "smile"
-  64 f09f                                         #   string(2)
-    f09f9880                                      #     "😀"
+  a0                                              #   map(0)
+  61                                              #   string(1)
+    63                                            #     "c"
+  a2                                              #   map(2)
+    61                                            #     string(1)
+      61                                          #       "a"
+    01                                            #     uint(1)
+    61                                            #     string(1)
+      62                                          #       "b"
+    a1                                            #     map(1)
+      61                                          #       string(1)
+        61                                        #         "a"
+      a1                                          #       map(1)
+        61                                        #         string(1)
+          61                                      #           "a"
+        a0                                        #         map(0)
+  61                                              #   string(1)
+    64                                            #     "d"
+  a1                                              #   map(1)
+    61                                            #     string(1)
+      61                                          #       "a"
+    a3                                            #     map(3)
+      61                                          #       string(1)
+        61                                        #         "a"
+      a1                                          #       map(1)
+        61                                        #         string(1)
+          61                                      #           "a"
+        01                                        #         uint(1)
+      61                                          #       string(1)
+        62                                        #         "b"
+      02                                          #       uint(2)
+      61                                          #       string(1)
+        63                                        #         "c"
+      80                                          #       array(0)
+  61                                              #   string(1)
+    65                                            #     "e"
+  81                                              #   array(1)
+    81                                            #     array(1)
+      81                                          #       array(1)
+        81                                        #         array(1)
+          a1                                      #           map(1)
+            61                                    #             string(1)
+              61                                  #               "a"
+            a0                                    #             map(0)
+  61                                              #   string(1)
+    66                                            #     "f"
+  01                                              #   uint(1)
 `);
   });
-  it('bin2json (stdin)', async () => {
-    const {stdout, stderr} = await execBin('bin2json', fromHex('a3616101616282020365736d696c6564f09f9880'));
-    assert.strictEqual(stderr, '');
-    assert.strictEqual(stdout, '{"a":1,"b":[2,3],"smile":"\uD83D\uDE00"}\n');
+  describe('diag length bytes', () => {
+    it('compact', async () => {
+      const {stdout, stderr} = await execBin('json2diag', '"aaaaaaaaaaaaaaaaaaaaaaa"');
+      assert.strictEqual(stderr, '');
+      assert.strictEqual(stdout, `77                                                # string(23)
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+`);
+    });
+    it('1-byte', async () => {
+      const {stdout, stderr} = await execBin('json2diag', '"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"');
+      assert.strictEqual(stderr, '');
+      assert.strictEqual(stdout, `78 23                                             # string(35)
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  616161616161616161616161                        #   "aaaaaaaaaaaa"
+`);
+    });
+    it('2-byte', async () => {
+      const {stdout, stderr} = await execBin('json2diag', '"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"');
+      assert.strictEqual(stderr, '');
+      assert.strictEqual(stdout, `79 0100                                           # string(256)
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  6161616161616161616161616161616161616161616161  #   "aaaaaaaaaaaaaaaaaaaaaaa"
+  616161                                          #   "aaa"
+`);
+    });
   });
-  it('bin2json pretty (stdin)', async () => {
-    const {stdout, stderr} = await execBin('bin2json --pretty', fromHex('a3616101616282020365736d696c6564f09f9880'));
+  it('diag non-utf8 and non-printable ascii', async () => {
+    const input = '7864f55ff8f12508b63ef2bfeca7557ae90df6311a5ec1631b4a1fa843310bd9c3a710eaace5a1bdd72ad0bfe049771c11e756338bd93865e645f1adec9b9c99ef407fbd4fc6859e7904c5ad7dc9bd10a5cc16973d5b28ec1a6dd43d9f82f9f18c3d03418e35';
+    let {stdout, stderr} = await execBin(`hex2diag ${ input }`);
     assert.strictEqual(stderr, '');
-    assert.strictEqual(stdout, `{
-  "a": 1,
-  "b": [
-    2,
-    3
-  ],
-  "smile": "😀"
-}
+    assert.strictEqual(stdout, `78 64                                             # string(86)
+  f55ff8f12508b63ef2bfeca7557ae90df6311a5ec1631b  #   "õ_øñ%\\x08¶>ò¿ì§Uzé\\x0dö1\\x1a^Ác\\x1b"
+  4a1fa843310bd9c3a710eaace5a1bdd72ad0bfe049771c  #   "J\\x1f¨C1\\x0bÙç\\x10ê¬å¡½×*пàIw\\x1c"
+  11e756338bd93865e645f1adec9b9c99ef407fbd4fc685  #   "\\x11çV3\\x8bÙ8eæEñ\\xadì\\x9b\\x9c\\x99ï@\\x7f½OÆ\\x85"
+  9e7904c5ad7dc9bd10a5cc16973d5b28ec1a6dd43d9f82  #   "\\x9ey\\x04Å\\xad}ɽ\\x10¥Ì\\x16\\x97=[(ì\\x1amÔ=\\x9f\\x82"
+  f9f18c3d03418e35                                #   "ùñ\\x8c=\\x03A\\x8e5"
 `);
-  });
-  it('bin2hex (stdin)', async () => {
-    const {stdout, stderr} = await execBin('bin2hex', fromHex('a3616101616282020365736d696c6564f09f9880'));
+    ({stdout, stderr} = await execBin('diag2hex', stdout));
     assert.strictEqual(stderr, '');
-    assert.strictEqual(stdout, 'a3616101616282020365736d696c6564f09f9880\n');
+    assert.strictEqual(stdout, `${ input }\n`);
   });
 });

package/cjs/lib/3string.js

@@ -8,29 +8,33 @@ var _0uint = require('./0uint.js');
 var _2bytes = require('./2bytes.js');
 var byteUtils = require('./byte-utils.js');
 
-function toToken(data, pos, prefix, length) {
+function toToken(data, pos, prefix, length, options) {
   const totLength = prefix + length;
   common.assertEnoughData(data, pos, totLength);
-  return new token.Token(token.Type.string, byteUtils.toString(data, pos + prefix, pos + totLength), totLength);
+  const tok = new token.Token(token.Type.string, byteUtils.toString(data, pos + prefix, pos + totLength), totLength);
+  if (options.retainStringBytes === true) {
+    tok.byteValue = byteUtils.slice(data, pos + prefix, pos + totLength);
+  }
+  return tok;
 }
-function decodeStringCompact(data, pos, minor, _options) {
-  return toToken(data, pos, 1, minor);
+function decodeStringCompact(data, pos, minor, options) {
+  return toToken(data, pos, 1, minor, options);
 }
 function decodeString8(data, pos, _minor, options) {
-  return toToken(data, pos, 2, _0uint.readUint8(data, pos + 1, options));
+  return toToken(data, pos, 2, _0uint.readUint8(data, pos + 1, options), options);
 }
 function decodeString16(data, pos, _minor, options) {
-  return toToken(data, pos, 3, _0uint.readUint16(data, pos + 1, options));
+  return toToken(data, pos, 3, _0uint.readUint16(data, pos + 1, options), options);
 }
 function decodeString32(data, pos, _minor, options) {
-  return toToken(data, pos, 5, _0uint.readUint32(data, pos + 1, options));
+  return toToken(data, pos, 5, _0uint.readUint32(data, pos + 1, options), options);
 }
 function decodeString64(data, pos, _minor, options) {
   const l = _0uint.readUint64(data, pos + 1, options);
   if (typeof l === 'bigint') {
     throw new Error(`${ common.decodeErrPrefix } 64-bit integer string lengths not supported`);
   }
-  return toToken(data, pos, 9, l);
+  return toToken(data, pos, 9, l, options);
 }
 const encodeString = _2bytes.encodeBytes;