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