1============ 2CBOR binding 3============ 4 5Overview 6======== 7 8C functions to encode/decode values in CBOR format, and a simple command 9line utility to convert between JSON and CBOR. 10 11To integrate CBOR into your application: 12 13* Call ``duk_cbor_encode()`` and ``duk_cbor_decode()`` directly if a C API 14 is enough. 15 16* Call ``duk_cbor_init()`` to register a global ``CBOR`` object with 17 ECMAScript bindings ``CBOR.encode()`` and ``CBOR.decode()``, roughly 18 matching https://github.com/paroga/cbor-js. 19 20Basic usage of the ``jsoncbor`` conversion tool:: 21 22 $ make jsoncbor 23 [...] 24 $ cat test.json | ./jsoncbor -e # writes CBOR to stdout 25 $ cat test.cbor | ./jsoncbor -d # writes JSON to stdout 26 27CBOR objects are decoded into ECMAScript objects, with non-string keys 28coerced into strings. 29 30Direct support for CBOR is likely to be included in the Duktape API in the 31future. This extra will then become unnecessary. 32 33CBOR 34==== 35 36CBOR is a standard format for JSON-like binary interchange. It is 37faster and smaller, and can encode more data types than JSON. In particular, 38binary data can be serialized without encoding e.g. in base-64. These 39properties make it useful for storing state files, IPC, etc. 40 41Some CBOR shortcomings for preserving information: 42 43* No property attribute or inheritance support. 44 45* No DAGs or looped graphs. 46 47* Array objects with properties lose their non-index properties. 48 49* Array objects with gaps lose their gaps as they read back as undefined. 50 51* Buffer objects and views lose much of their detail besides the raw data. 52 53* ECMAScript strings cannot be fully represented; strings must be UTF-8. 54 55* Functions and native objects lose most of their detail. 56 57* CBOR tags are useful to provide soft decoding information, but the tags 58 are just integers from an IANA controlled space with no space for custom 59 tags. So tags cannot be easily used for private, application specific tags. 60 IANA allows reserving custom tags with little effort however, see 61 https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml. 62 63Future work 64=========== 65 66General: 67 68* Add flags to control encode/decode behavior. 69 70* Allow decoding with a trailer so that stream parsing is easier. 71 Similar change would be useful for JSON decoding. 72 73* Reserve CBOR tag for missing value. 74 75* Reserve other necessary CBOR tags. 76 77* Explicit support for encoding with and without side effects (e.g. 78 skipping Proxy traps and getters). 79 80* JSON encoding supports .toJSON(), maybe something like .toCBOR()? 81 82* Optimize encoding and decoding more. 83 84Encoding: 85 86* Tagging of typed arrays: 87 https://datatracker.ietf.org/doc/draft-ietf-cbor-array-tags/. 88 Mixed endian encode must convert to e.g. little endian because 89 no mixed endian tag exists. 90 91* Encoding typed arrays as integer arrays instead? 92 93* Float16Array encoding support (once/if supported by main engine). 94 95* Tagging of array gaps, once IANA reservation is complete: 96 https://github.com/svaarala/duktape/blob/master/doc/cbor-missing-tag.rst. 97 98* Support 64-bit integer when encoding, e.g. up to 2^53? 99 100* Definite-length object encoding even when object has more than 23 keys. 101 102* Map/Set encoding (once supported in the main engine), maybe tagged 103 so they decode back into Map/Set. 104 105* Bigint encoding (once supported in the main engine), as tagged byte 106 strings like in Python CBOR. 107 108* String encoding options: combining surrogate pairs, tagging non-UTF-8 109 byte strings so they decode back to string, using U+FFFD replacement, 110 etc. 111 112* Detection of Symbols, encode them in a useful tagged form. 113 114* Better encoding of functions. 115 116* Hook for serialization, to allow caller to serialize values (especially 117 objects) in a context specific manner (e.g. serialize functions with 118 IPC metadata to allow them to be called remotely). Such a hook should 119 be able to emit tag(s) to mark custom values for decode processing. 120 121Decoding: 122 123* Typed array decoding support. Should decoder convert to host 124 endianness? 125 126* Float16Array decoding support (once/if supported by main engine). 127 128* Decoding objects with non-string keys, could be represented as a Map. 129 130* Use bare objects and arrays when decoding? 131 132* Use a Map rather than a plain object when decoding, which would allow 133 non-string keys. 134 135* Bigint decoding (once supported in the main engine). 136 137* Decoding of non-BMP codepoints into surrogate pairs. 138 139* Decoding of Symbols when call site indicates it is safe. 140 141* Hooking for revival, to allow caller to revive objects in a context 142 specific manner (e.g. revive serialized function objects into IPC 143 proxy functions). Such a hook should have access to encoding tags, 144 so that revival can depend on tags present. 145 146* Option to compact decoded objects and arrays. 147 148* Improve fastint decoding support, e.g. decode non-optimally encoded 149 integers as fastints, decode compatible floating point values as 150 fastints. 151