cbor-x 0.8.0 → 0.9.0

package/.vscode/launch.json

@@ -0,0 +1,22 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "pwa-node",
+            "request": "launch",
+            "name": "Run cbor-x tests",
+            "runtimeArgs": [
+                "test"
+            ],
+            "runtimeExecutable": "npm",
+            "skipFiles": [
+                "<node_internals>/**"
+            ],
+            "console": "internalConsole", 
+            "outputCapture": "std"
+        }
+    ]
+}

package/README.md

@@ -6,7 +6,7 @@
 [![types](https://img.shields.io/npm/types/cbor-x)](README.md)
 [![module](https://img.shields.io/badge/module-ESM%2FCJS-blue)](README.md)
 
-The cbor-x package is an extremely fast CBOR NodeJS/JavaScript implementation. Currently, it is significantly faster than any other known implementations, faster than Avro (for JS), and generally faster than native V8 JSON.stringify/parse. It implements the CBOR format as specificed in [RFC-8949](https://www.rfc-editor.org/rfc/rfc8949.html), numerous [registered IANA tag extensions](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml) (the `x` in cbor-x), [RFC-8746](https://tools.ietf.org/html/rfc8746) and proposed optional record extension, for defining record structures that makes CBOR even faster and more compact, often over twice as fast as even native JSON functions, several times faster than other JS implementations, and 15-50% more compact. See the performance section for more details. Structured cloning (with support for cyclical references) is supported through these tag extensions.
+The cbor-x package is an extremely fast CBOR NodeJS/JavaScript implementation. Currently, it is significantly faster than any other known implementations, faster than Avro (for JS), and generally faster than native V8 JSON.stringify/parse, on NodeJS. It implements the CBOR format as specificed in [RFC-8949](https://www.rfc-editor.org/rfc/rfc8949.html), numerous [registered IANA tag extensions](https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml) (the `x` in cbor-x), [RFC-8746](https://tools.ietf.org/html/rfc8746) and proposed optional [record extension](https://github.com/kriszyp/cbor-records), for defining record structures that makes CBOR even faster and more compact, often over twice as fast as even native JSON functions, several times faster than other JS implementations, and 15-50% more compact. See the performance section for more details. Structured cloning (with support for cyclical references) is supported through these tag extensions.
 
 ## Basic Usage
 
@@ -48,10 +48,10 @@ receivingStream.on('data', (data) => {
 	// received data
 });
 ```
- The `EncoderStream` and `DecoderStream` instances  will have also the record structure extension enabled by default (see below).
+The `EncoderStream` and `DecoderStream` instances  will have also the record structure extension enabled by default (see below).
 
 ## Deno Usage
-Msgpackr modules are standard ESM modules and can be loaded directly from github (https://raw.githubusercontent.com/kriszyp/msgpackr/master/index.js) or downloaded and used directly in Deno. The standard pack/encode and unpack/decode functionality is available on Deno, like other platforms.
+CBOR modules are standard ESM modules and can be loaded directly from github (https://raw.githubusercontent.com/kriszyp/cbor-x/master/index.js) or downloaded and used directly in Deno. The standard encode and decode functionality is available on Deno, like other platforms.
 
 ## Browser Usage
 Cbor-x  works as standalone JavaScript as well, and runs on modern browsers. It includes a bundled script, at `dist/index.js` for ease of direct loading:
@@ -82,10 +82,10 @@ copy.set.has('a') // true
 
 ```
 
-This option is disabled by default because it uses extensions and reference checking degrades performance (by about 25-30%). (Note this implementation doesn't serialize every class/type specified in the HTML specification since not all of them make sense for storing across platforms.)
+This option is disabled by default because reference checking degrades performance (by about 25-30%). (Note this implementation doesn't serialize every class/type specified in the HTML specification since not all of them make sense for storing across platforms.)
 
 ## Record / Object Structures
-There is a critical difference between maps (or dictionaries) that hold an arbitrary set of keys and values (JavaScript `Map` is designed for these), and records or object structures that have a well-defined set of fields. Typical JS objects/records may have many instances re(use) the same structure. By using the record extension, this distinction is preserved in CBOR and the encoding can reuse structures and not only provides better type preservation, but yield much more compact encodings and increase decoding performance by 2-3x. cbor-x automatically generates record definitions that are reused and referenced by objects with the same structure. Records use CBOR's tags to align well CBOR's tag/extension mechanism. There are a number of ways to use this to our advantage. For large object structures with repeating nested objects with similar structures, simply serializing with the record extension can yield significant benefits. To use the record structures extension, we create a new `Encoder` instance. By default a new `Encoder` instance will have the record extension enabled:
+There is a critical difference between maps (or dictionaries) that hold an arbitrary set of keys and values (JavaScript `Map` is designed for these), and records or object structures that have a well-defined set of fields. Typical JS objects/records may have many instances re(use) the same structure. By using the record extension, this distinction is preserved in CBOR and the encoding can reuse structures and not only provides better type preservation, but yield much more compact encodings and increase decoding performance by 2-3x. Cbor-x automatically generates record definitions that are reused and referenced by objects with the same structure. Records use CBOR's tags to align well CBOR's tag/extension mechanism. There are a number of ways to use this to our advantage. For large object structures with repeating nested objects with similar structures, simply serializing with the record extension can yield significant benefits. To use the record structures extension, we create a new `Encoder` instance. By default a new `Encoder` instance will have the record extension enabled:
 ```
 import { Encoder } from 'cbor-x';
 let encoder = new Encoder();
@@ -96,6 +96,8 @@ Another way to further leverage the benefits of the cbor-x record structures is
 
 When creating a new `Encoder`, `EncoderStream`, or `DecoderStream` instance, we can enable or disable the record structure extension with the `objectsAsMaps` property. When this is `true`, the record structure extension will be disabled, and all objects will revert to being serialized using MessageMap `map`s, and all `map`s will be deserialized to JS `Object`s as properties (like the standalone `encode` and `decode` functions).
 
+Streaming with record structures works by encoding a structure the first time it is seen in a stream and referencing the structure in later messages that are sent across that stream. When an encoder can expect a decoder to understand previous structure references, this can be configured using the `sequential: true` flag, which is auto-enabled by streams, but can also be used with Packr instances.
+
 ### Shared Record Structures
 Another useful way of using cbor-x, and the record extension, is for storing data in a databases, files, or other storage systems. If a number of objects with common data structures are being stored, a shared structure can be used to greatly improve data storage and deserialization efficiency. In the simplest form, provide a `structures` array, which is updated if any new object structure is encountered:
 
@@ -119,18 +121,18 @@ let encoder = new Encoder({
 	structures: []
 });
 ```
-Cbor-x will automatically add and saves structures as it encounters any new object structures (up to a limit of 32). It will always add structures in incremental/compatible way: Any object encoded with an earlier structure can be decoded with a later version (as long as it is persisted).
+Cbor-x will automatically add and saves structures as it encounters any new object structures (up to a limit of 64). It will always add structures in incremental/compatible way: Any object encoded with an earlier structure can be decoded with a later version (as long as it is persisted).
 
 ### Reading Multiple Values
 If you have a buffer with multiple values sequentially encoded, you can choose to parse and read multiple values. This can be done using the `unpackMultiple` function/method, which can return an array of all the values it can sequentially parse within the provided buffer. For example:
 ```js
 let data = new Uint8Array([1, 2, 3]) // encodings of values 1, 2, and 3
-let values = unpackMultiple(data) // [1, 2, 3]
+let values = decodeMultiple(data) // [1, 2, 3]
 ```
 Alternately, you can provide a callback function that is called as the parsing occurs with each value, and can optionally terminate the parsing by returning `false`:
 ```js
 let data = new Uint8Array([1, 2, 3]) // encodings of values 1, 2, and 3
-unpackMultiple(data, (value) => {
+decodeMultiple(data, (value) => {
 	// called for each value
 	// return false if you wish to end the parsing
 })
@@ -139,15 +141,17 @@ unpackMultiple(data, (value) => {
 ## Options
 The following options properties can be provided to the Encoder or Decoder constructor:
 
-* `useRecords` - Setting this to `false` disables the record extension and stores JavaScript objects as CBOR maps, and decodes maps as JavaScript `Object`s, which ensures compatibilty with other decoders.
-* `structures` - Provides the array of structures that is to be used for record extension, if you want the structures saved and used again. This array will be modified in place with new record structures that are serialized (if less than 32 structures are in the array).
+* `useRecords` - Setting this to `false` disables the record extension and stores JavaScript objects as CBOR maps (with tag 259), and decodes maps as JavaScript `Object`s, which ensures compatibilty with other decoders.
+* `structures` - Provides the array of structures that is to be used for record extension, if you want the structures saved and used again. This array will be modified in place with new record structures that are serialized (if less than 64 structures are in the array).
 * `structuredClone` - This enables the structured cloning extensions that will encode object/cyclic references and additional built-in types/classes.
-* `mapsAsObjects` - If `true`, this will decode CBOR maps and JS `Object`s with the map entries decoded to object properties. If `false`, maps are decoded as JavaScript `Map`s. This is disabled by default if `useRecords` is enabled (which allows `Map`s to be preserved), and is enabled by default if `useRecords` is disabled.
-* `useFloat32` - This will enable cbor-x to encode non-integer numbers as `float32`. See next section for possible values.
-* `variableMapSize` - This will use varying map size definition (fixmap, map16, map32) based on the number of keys when encoding objects, which yields slightly more compact encodings (for small objects), but is typically 5-10% slower during encoding. This is only relevant when record extension is disabled.
-* `copyBuffers` - When decoding a CBOR with binary data (Buffers are encoded as binary data), copy the buffer rather than providing a slice/view of the buffer. If you want your input data to be collected or modified while the decoded embedded buffer continues to live on, you can use this option (there is extra overhead to copying).
+* `mapsAsObjects` - If `true`, this will decode CBOR maps and JS `Object`s with the map entries decoded to object properties. If `false`, maps are decoded as JavaScript `Map`s. This is disabled by default if `useRecords` is enabled (`Map`s are preserved since they are distinct from records), and is enabled by default if `useRecords` is disabled.
+* `useFloat32` - This will enable cbor-x to encode non-integer numbers as 32-bit (4 byte) floating point numbers. See next section for possible values.
+* `variableMapSize` - This will use varying map size definition (from single-byte to full 32-bit representation) based on the number of keys when encoding objects, which yields slightly more compact encodings (for small objects), but is typically 5-10% slower during encoding. This is only relevant when record extension is disabled.
+* `copyBuffers` - When decoding a CBOR message with binary data (Buffers are encoded as binary data), copy the buffer rather than providing a slice/view of the buffer. If you want your input data to be collected or modified while the decoded embedded buffer continues to live on, you can use this option (there is extra overhead to copying).
 * `useTimestamp32` - Encode JS `Date`s in 32-bit format when possible by dropping the milliseconds. This is a more efficient encoding of dates. You can also cause dates to use 32-bit format by manually setting the milliseconds to zero (`date.setMilliseconds(0)`).
+* `sequential` - Encode structures in serialized data, and reference previously encoded structures with expectation that decoder will read the encoded structures in the same order as encoded, with `unpackMultiple`.
 * `largeBigIntToFloat` - If a bigint needs to be encoded that is larger than will fit in 64-bit integers, it will be encoded as a float-64 (otherwise will throw a RangeError).
+* `useTag259ForMaps` - This flag indicates if [tag 259 (explicit maps)](https://github.com/shanewholloway/js-cbor-codec/blob/master/docs/CBOR-259-spec--explicit-maps.md) should be used to encode JS `Map`s. When using records is enabled, this is disabled by default, since plain objects are encoded with record structures and unambigiously differentiated from `Map`s, which are encoded as CBOR maps. Without using records, this enabled by default and is necessary to distinguish plain objects from `Map`s (but can be disabled by setting this to `false`).
 
 ### 32-bit Float Options
 By default all non-integer numbers are serialized as 64-bit float (double). This is fast, and ensures maximum precision. However, often real-world data doesn't not need 64-bits of precision, and using 32-bit encoding can be much more space efficient. There are several options that provide more efficient encodings. Using the decimal rounding options for encoding and decoding provides lossless storage of common decimal representations like 7.99, in more efficient 32-bit format (rather than 64-bit). The `useFloat32` property has several possible options, available from the module as constants:
@@ -157,10 +161,12 @@ import { ALWAYS, DECIMAL_ROUND, DECIMAL_FIT } from 'cbor-x'
 
 * `ALWAYS` (1) - Always will encode non-integers (absolute less than 2147483648) as 32-bit float.
 * `DECIMAL_ROUND` (3) - Always will encode non-integers as 32-bit float, and when decoding 32-bit float, round to the significant decimal digits (usually 7, but 6 or 8 digits for some ranges).
-* `DECIMAL_FIT` (4) - Only encode non-integers as 32-bit float if all significant digits (usually up to 7) can be unamiguously encoded as a 32-bit float, and decode with decimal rounding (same as above). This will ensure round-trip encoding/decoding without loss in precision and use 32-bit when possible.
+* `DECIMAL_FIT` (4) - Only encode non-integers as 32-bit float if all significant digits (usually up to 7) can be unamiguously encoded as a 32-bit float, and decode with decimal rounding (same as above). This will ensure round-trip encoding/decoding without loss in precision and uses 32-bit when possible.
 
 Note, that the performance is decreased with decimal rounding by about 20-25%, although if only 5% of your values are floating point, that will only have about a 1% impact overall.
 
+In addition, msgpackr exports a `roundFloat32(number)` function that can be used to round floating point numbers to the maximum significant decimal digits that can be stored in 32-bit float, just as DECIMAL_ROUND does when decoding. This can be useful for determining how a number will be decoded prior to encoding it.
+
 ## Performance
 Cbor-x is fast. Really fast. Here is comparison with the next fastest JS projects using the benchmark tool from `msgpack-lite` (and the sample data is from some clinical research data we use that has a good mix of different value types and structures). It also includes comparison to V8 native JSON functionality, and JavaScript Avro (`avsc`, a very optimized Avro implementation):
 
@@ -226,29 +232,6 @@ addExtension({
 	}
 });
 ```
-If you want to use msgpackr to encode and decode the data within your extensions, you can use the `read` and `write` functions and read and write data/objects that will be encoded and decoded by msgpackr, which can be easier and faster than creating and receiving separate buffers (note that you can't just return the instance from `write` or msgpackr will recursively try to use extension infinitely):
-```js
-import { addExtension, Packr } from 'msgpackr';
-
-class MyCustomClass {...}
-
-let extPackr = new Packr();
-addExtension({
-	Class: MyCustomClass,
-	type: 11, // register your own extension code (a type code from 1-100)
-	write(instance) {
-		// define how your custom class should be encoded
-		return instance.myData; // return some data to be encoded
-	}
-	read(data) {
-		// define how your custom class should be decoded,
-		// data will already be unpacked/decoded
-		let instance = new MyCustomClass();
-		instance.myData = data;
-		return instance; // return decoded value
-	}
-});
-```
 
 ## Unknown Tags
 If no extension is registered for a tag, the decoder will return an instance of the `Tag` class, where the value provided for the tag will be available in the `value` property of the `Tag` instance. The `Tag` class is an export of the package and decode module.
@@ -263,20 +246,41 @@ Cbor-x is already fast, but here are some tips for making it faster.
 During the serialization process, data is written to buffers. Again, allocating new buffers is a relatively expensive process, and the `useBuffer` method can help allow reuse of buffers that will further improve performance. With `useBuffer` method, you can provide a buffer, serialize data into it, and when it is known that you are done using that buffer, you can call `useBuffer` again to reuse it. The use of `useBuffer` is never required, buffers will still be handled and cleaned up through GC if not used, it just provides a small performance boost.
 
 ## Extensions
-Cbor-x currently uses tag ids 40000 to 40500 for its proposed extensions (until accepted).
-
-## Record Structure Extension Definition
-The record struction extension uses tag 40006 to declare a new record structure. This is followed by an array where the first element indicates the tag id of the record structure to declare and the next element is an array of the field names, and the third element is array of the property values. The extension declaration must be immediately follow by the field names of the record structure.
+Cbor-x currently uses tag id 105 and 26880-27135 for its [proposed extension for records](https://github.com/kriszyp/cbor-records).
 
 ### Dates
-cbor-x saves all JavaScript `Date`s using the standard CBOR date extension (tag 1).
+Cbor-x saves all JavaScript `Date`s using the standard CBOR date extension (tag 1).
 
 ### Structured Cloning
 With structured cloning enabled, cbor-x will also use tags/extensions to store Set, Map, Error, RegExp, ArrayBufferView objects and preserve their types.
 
+### List of supported tags for decoding
+Here is a list of CBOR tags that are supported for decoding:
+
+* 0 - String date
+* 1 - Numeric Date
+* 2 - BigInt
+* 3 - Negative BigInt
+* 27 - Generic named objects (used for Error, RegExp)
+* 64 - Uint8Array
+* 68 - Uint8ClampedArray
+* 69 - Uint16Array
+* 70 - Uint32Array
+* 71 - BigUint64Array
+* 72 - Int8Array
+* 77 - Int16Array
+* 78 - Int32Array
+* 79 - BigInt64Array
+* 81 - Float32Array
+* 82 - Float64Array
+* 105 - Records
+* 258 - Set
+* 259 - Map
+* 40009, 40010 - Pointers for cycles
+
 ## Alternate Encoding/Package
 The high-performance serialization and deserialization algorithms in this package are also available in the [msgpackr](https://github.com/kriszyp/msgpackr) for the MessagePack format, with the same API and design. A quick summary of the pros and cons of using MessagePack vs CBOR are:
-* MessagePack has wider adoption, and, at least with this implementation is slightly more efficient (by roughly 2-4%).
+* MessagePack has wider adoption, and, at least with this implementation is slightly more efficient (by roughly 1%, but YMMV).
 * CBOR has an [official IETF standardization track](https://www.rfc-editor.org/rfc/rfc8949.html), and the record extensions is conceptually/philosophically a better fit for CBOR tags.
 
 ## License
@@ -284,7 +288,7 @@ The high-performance serialization and deserialization algorithms in this packag
 MIT
 
 ### Browser Consideration
-CBOR can be a great choice for high-performance data delivery to browsers, as reasonable data size is possible without compression. And msgpackr works very well in modern browsers. However, it is worth noting that if you want highly compact data, brotli or gzip are most effective in compressing, and CBOR's character frequency tends to defeat Huffman encoding used by these standard compression algorithms, resulting in less compact data than compressed JSON.
+CBOR can be a great choice for high-performance data delivery to browsers, as reasonable data size is possible without compression. And CBOR works very well in modern browsers. However, it is worth noting that if you want highly compact data, brotli or gzip are most effective in compressing, and CBOR's character frequency tends to defeat Huffman encoding used by these standard compression algorithms, often resulting in less compact data than compressed JSON.
 
 ### Credits
 

package/SECURITY.md

@@ -0,0 +1,11 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.4.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities to kriszyp@gmail.com.

package/{unpack.d.ts → decode.d.ts}

@@ -5,7 +5,7 @@ export enum FLOAT32_OPTIONS {
 	DECIMAL_FIT = 4
 }
 
-interface Options {
+export interface Options {
 	useFloat32?: FLOAT32_OPTIONS
 	useRecords?: boolean
 	structures?: {}[]
@@ -15,24 +15,25 @@ interface Options {
 	copyBuffers?: boolean
 	useTimestamp32?: boolean
 	largeBigIntToFloat?: boolean
+	encodeUndefinedAsNil?: boolean
+	maxSharedStructures?: number
+	maxOwnStructures?: number
+	shouldShareStructure?: (keys: string[]) => boolean
 	getStructures?(): {}[]
 	saveStructures?(structures: {}[]): boolean | void
 }
 interface Extension {
 	Class: Function
-	type: number
-	pack(value: any): Buffer | Uint8Array
-	unpack(messagePack: Buffer | Uint8Array): any
+	tag: number
+	encode(value: any): Buffer | Uint8Array
+	decode(messagePack: Buffer | Uint8Array): any
 }
-export class Unpackr {
+export class Decoder {
 	constructor(options?: Options)
-	unpack(messagePack: Buffer | Uint8Array): any
 	decode(messagePack: Buffer | Uint8Array): any
-	unpackMultiple(messagePack: Buffer | Uint8Array, forEach?: (value: any) => any): [] | void
+	decodeMultiple(messagePack: Buffer | Uint8Array, forEach?: (value: any) => any): [] | void
 }
-export class Decoder extends Unpackr {}
-export function unpack(messagePack: Buffer | Uint8Array): any
-export function unpackMultiple(messagePack: Buffer | Uint8Array, forEach?: (value: any) => any): [] | void
 export function decode(messagePack: Buffer | Uint8Array): any
+export function decodeMultiple(messagePack: Buffer | Uint8Array, forEach?: (value: any) => any): [] | void
 export function addExtension(extension: Extension): void
-export const C1: {}
+export function roundFloat32(float32Number: number): number

package/decode.js

@@ -20,10 +20,12 @@ let srcStringEnd = 0
 let referenceMap
 let currentExtensions = []
 let dataView
+let restoreMapsAsObject
 let defaultOptions = {
 	useRecords: false,
 	mapsAsObjects: true
 }
+let sequentialMode = false
 
 export class Decoder {
 	constructor(options) {
@@ -35,12 +37,12 @@ export class Decoder {
 		}
 		Object.assign(this, options)
 	}
-	decode(source, end, continueReading) {
+	decode(source, end) {
 		if (src) {
 			// re-entrant execution, save the state and restore it after we do this decode
 			return saveState(() => {
 				clearSource()
-				return this ? this.decode(source, end, continueReading) : Decoder.prototype.decode.call(defaultOptions, source, end, continueReading)
+				return this ? this.decode(source, end) : Decoder.prototype.decode.call(defaultOptions, source, end)
 			})
 		}
 		srcEnd = end > -1 ? end : source.length
@@ -58,17 +60,7 @@ export class Decoder {
 			currentDecoder = this
 			if (this.structures) {
 				currentStructures = this.structures
-				try {
-					return read()
-				} finally {
-					if (position >= srcEnd || !continueReading) {
-						// finished reading this source, cleanup references
-						currentStructures = null
-						src = null
-						if (referenceMap)
-							referenceMap = null
-					}
-				}
+				return checkedRead()
 			} else if (!currentStructures || currentStructures.length > 0) {
 				currentStructures = []
 			}
@@ -77,26 +69,19 @@ export class Decoder {
 			if (!currentStructures || currentStructures.length > 0)
 				currentStructures = []
 		}
-		try {
-			return read()
-		} finally {
-			if (position >= srcEnd || !continueReading) {
-				src = null
-				if (referenceMap)
-					referenceMap = null
-			}
-		}
+		return checkedRead()
 	}
 	decodeMultiple(source, forEach) {
+		let values, lastPosition = 0
 		try {
-			let decoder = this
 			let size = source.length
-			let value = this ? this.decode(source, size, true) : defaultDecoder.decode(source, size, true)
-			let values
+			sequentialMode = true
+			let value = this ? this.decode(source, size) : defaultDecoder.decode(source, size)
 			if (forEach) {
 				forEach(value)
 				while(position < size) {
-					if (forEach(read()) === false) {
+					lastPosition = position
+					if (forEach(checkedRead()) === false) {
 						return
 					}
 				}
@@ -104,11 +89,17 @@ export class Decoder {
 			else {
 				values = [ value ]
 				while(position < size) {
-					values.push(read())
+					lastPosition = position
+					values.push(checkedRead())
 				}
 				return values
 			}
+		} catch(error) {
+			error.lastPosition = lastPosition
+			error.values = values
+			throw error
 		} finally {
+			sequentialMode = false
 			clearSource()
 		}
 	}
@@ -116,6 +107,33 @@ export class Decoder {
 export function getPosition() {
 	return position
 }
+export function checkedRead() {
+	try {
+		let result = read()
+		if (position == srcEnd) {
+			// finished reading this source, cleanup references
+			currentStructures = null
+			src = null
+			if (referenceMap)
+				referenceMap = null
+		} else if (position > srcEnd) {
+			// over read
+			let error = new Error('Unexpected end of CBOR data')
+			error.incomplete = true
+			throw error
+		} else if (!sequentialMode) {
+			throw new Error('Data read, but end of buffer not reached')
+		}
+		// else more to read, but we are reading sequentially, so don't clear source yet
+		return result
+	} catch(error) {
+		clearSource()
+		if (error instanceof RangeError || error.message.startsWith('Unexpected end of buffer')) {
+			error.incomplete = true
+		}
+		throw error
+	}
+}
 
 export function read() {
 	let token = src[position++]
@@ -180,6 +198,10 @@ export function read() {
 								object[key] = read()
 							return object
 						} else {
+							if (restoreMapsAsObject) {
+								currentDecoder.mapsAsObjects = true
+								restoreMapsAsObject = false
+							}
 							let map = new Map()
 							while ((key = read()) != STOP_CODE)
 								map.set(key, read())
@@ -226,6 +248,10 @@ export function read() {
 				}
 				return object
 			} else {
+				if (restoreMapsAsObject) {
+					currentDecoder.mapsAsObjects = true
+					restoreMapsAsObject = false
+				}
 				let map = new Map()
 				for (let i = 0; i < token; i++) {
 					map.set(read(), read())
@@ -339,10 +365,18 @@ export function setExtractor(extractStrings) {
 		return function readString(length) {
 			let string = strings[stringPosition++]
 			if (string == null) {
-				strings = extractStrings(position, srcEnd, length, src)
-				stringPosition = 0
-				srcStringEnd = 1 // even if a utf-8 string was decoded, must indicate we are in the midst of extracted strings and can't skip strings
-				string = strings[stringPosition++]
+				let extraction = extractStrings(position, srcEnd, length, src)
+				if (typeof extraction == 'string') {
+					string = extraction
+					strings = EMPTY_ARRAY
+				} else {
+					strings = extraction
+					stringPosition = 1
+					srcStringEnd = 1 // even if a utf-8 string was decoded, must indicate we are in the midst of extracted strings and can't skip strings
+					string = strings[0]
+					if (string === undefined)
+						throw new Error('Unexpected end of buffer')
+				}
 			}
 			let srcStringLength = string.length
 			if (srcStringLength <= length) {
@@ -735,7 +769,17 @@ currentExtensions[40010] = (id) => {
 	return refEntry.target
 }
 
-currentExtensions[258] = (array) => new Set(array) // https://github.com/input-output-hk/cbor-sets-spec/blob/master/CBOR_SETS.md
+currentExtensions[258] = (array) => new Set(array); // https://github.com/input-output-hk/cbor-sets-spec/blob/master/CBOR_SETS.md
+(currentExtensions[259] = (read) => {
+	// https://github.com/shanewholloway/js-cbor-codec/blob/master/docs/CBOR-259-spec
+	// for decoding as a standard Map
+	if (currentDecoder.mapsAsObjects) {
+		currentDecoder.mapsAsObjects = false
+		restoreMapsAsObject = true
+	}
+	return read()
+}).handlesRead = true
+
 
 export const typedArrays = ['Uint8', 'Uint8Clamped', 'Uint16', 'Uint32', 'BigUint64','Int8', 'Int16', 'Int32', 'BigInt64', 'Float32', 'Float64'].map(type => type + 'Array')
 const typedArrayTags = [64, 68, 69, 70, 71, 72, 77, 78, 79, 81, 82]
@@ -764,6 +808,7 @@ function saveState(callback) {
 	let savedSrc = new Uint8Array(src.slice(0, srcEnd)) // we copy the data in case it changes while external data is processed
 	let savedStructures = currentStructures
 	let savedDecoder = currentDecoder
+	let savedSequentialMode = sequentialMode
 	let value = callback()
 	srcEnd = savedSrcEnd
 	position = savedPosition
@@ -774,6 +819,7 @@ function saveState(callback) {
 	strings = savedStrings
 	referenceMap = savedReferenceMap
 	src = savedSrc
+	sequentialMode = savedSequentialMode
 	currentStructures = savedStructures
 	currentDecoder = savedDecoder
 	dataView = new DataView(src.buffer, src.byteOffset, src.byteLength)
@@ -789,7 +835,7 @@ export function addExtension(extension) {
 	currentExtensions[extension.tag] = extension.decode
 }
 
-export let mult10 = new Array(147) // this is a table matching binary exponents to the multiplier to determine significant digit rounding
+export const mult10 = new Array(147) // this is a table matching binary exponents to the multiplier to determine significant digit rounding
 for (let i = 0; i < 256; i++) {
 	mult10[i] = +('1e' + Math.floor(45.15 - i * 0.30103))
 }
@@ -804,3 +850,10 @@ export const FLOAT32_OPTIONS = {
 	DECIMAL_ROUND: 3,
 	DECIMAL_FIT: 4
 }
+let f32Array = new Float32Array(1)
+let u8Array = new Uint8Array(f32Array.buffer, 0, 4)
+export function roundFloat32(float32Number) {
+	f32Array[0] = float32Number
+	let multiplier = mult10[((u8Array[3] & 0x7f) << 1) | (u8Array[2] >> 7)]
+	return ((multiplier * float32Number + (float32Number > 0 ? 0.5 : -0.5)) >> 0) / multiplier
+}