@msgpack/msgpack - npm Package Compare versions

Comparing version 3.0.0-beta1 to 3.0.0-beta2

dist/ExtensionCodec.js

@@ -70,4 +70,4 @@ "use strict";
 }
+ExtensionCodec.defaultCodec = new ExtensionCodec();
 exports.ExtensionCodec = ExtensionCodec;
-ExtensionCodec.defaultCodec = new ExtensionCodec();
 //# sourceMappingURL=ExtensionCodec.js.map

package.json

 {
   "name": "@msgpack/msgpack",
-  "version": "3.0.0-beta1",
+  "version": "3.0.0-beta2",
   "description": "MessagePack for ECMA-262/JavaScript/TypeScript",
@@ -5,0 +5,0 @@ "author": "The MessagePack community",

README.md

@@ -5,10 +5,12 @@ # MessagePack for JavaScript/ECMA-262  <!-- omit in toc -->
 
-This is a JavaScript/ECMA-262 implementation of **MessagePack**, an efficient binary serilization format:
+This library is an implementation of **MessagePack** for TypeScript and JavaScript, providing a compact and efficient binary serialization format. Learn more about MessagePack at:
 
 https://msgpack.org/
 
-This library is a universal JavaScript, meaning it is compatible with all the major browsers and NodeJS. In addition, because it is implemented in [TypeScript](https://www.typescriptlang.org/), type definition files (`d.ts`) are always up-to-date and bundled in the distribution.
+This library serves as a comprehensive reference implementation of MessagePack for JavaScript with a focus on accuracy, compatibility, interoperability, and performance.
 
-*Note that this is the second version of MessagePack for JavaScript. The first version, which was implemented in ES5 and was never released to npmjs.com, is tagged as [classic](https://github.com/msgpack/msgpack-javascript/tree/classic).*
+Additionally, this is also a universal JavaScript library. It is compatible not only with browsers, but with Node.js or other JavaScript engines that implement ES2015+ standards. As it is written in [TypeScript](https://www.typescriptlang.org/), this library bundles up-to-date type definition files (`d.ts`).
 
+*Note that this is the second edition of "MessagePack for JavaScript". The first edition, which was implemented in ES5 and never released to npmjs.com, is tagged as [`classic`](https://github.com/msgpack/msgpack-javascript/tree/classic).
+
 ## Synopsis
@@ -114,2 +116,4 @@
 extensionCodec | ExtensionCodec | `ExtensionCodec.defaultCodec`
+context | user-defined | -
+useBigInt64 | boolean | false
 maxDepth | number | `100`
@@ -121,3 +125,2 @@ initialBufferSize | number | `2048`
 ignoreUndefined | boolean | false
-context | user-defined | -
 
@@ -149,2 +152,4 @@ ### `decode(buffer: ArrayLike<number> | BufferSource, options?: DecoderOptions): unknown`
 extensionCodec | ExtensionCodec | `ExtensionCodec.defaultCodec`
+context | user-defined | -
+useBigInt64 | boolean | false
 maxStrLength | number | `4_294_967_295` (UINT32_MAX)
@@ -155,3 +160,2 @@ maxBinLength | number | `4_294_967_295` (UINT32_MAX)
 maxExtLength | number | `4_294_967_295` (UINT32_MAX)
-context | user-defined | -
 
@@ -356,4 +360,14 @@ You can use `max${Type}Length` to limit the length of each type decoded.
 
-This library does not handle BigInt by default, but you can handle it with `ExtensionCodec` like this:
+This library does not handle BigInt by default, but you have two options to handle it:
 
+* Set `useBigInt64: true` to map bigint to MessagePack's int64/uint64
+* Define a custom `ExtensionCodec` to map bigint to a MessagePack's extension type
+
+`useBigInt64: true` is the simplest way to handle bigint, but it has limitations:
+
+* A bigint is encoded in 8 byte binaries even if it's a small integer
+* A bigint must be smaller than the max value of the uint64 and larger than the min value of the int64. Otherwise the behavior is undefined.
+
+So you might want to define a custom codec to handle bigint like this:
+
 ```typescript
@@ -363,22 +377,28 @@ import { deepStrictEqual } from "assert";
 
+// to define a custom codec:
 const BIGINT_EXT_TYPE = 0; // Any in 0-127
 const extensionCodec = new ExtensionCodec();
 extensionCodec.register({
-    type: BIGINT_EXT_TYPE,
-    encode: (input: unknown) => {
-        if (typeof input === "bigint") {
-            if (input <= Number.MAX_SAFE_INTEGER && input >= Number.MIN_SAFE_INTEGER) {
-                return encode(parseInt(input.toString(), 10));
-            } else {
-                return encode(input.toString());
-            }
-        } else {
-            return null;
-        }
-    },
-    decode: (data: Uint8Array) => {
-        return BigInt(decode(data));
-    },
+  type: BIGINT_EXT_TYPE,
+  encode(input: unknown): Uint8Array | null {
+    if (typeof input === "bigint") {
+      if (input <= Number.MAX_SAFE_INTEGER && input >= Number.MIN_SAFE_INTEGER) {
+        return encode(Number(input));
+      } else {
+        return encode(String(input));
+      }
+    } else {
+      return null;
+    }
+  },
+  decode(data: Uint8Array): bigint {
+    const val = decode(data);
+    if (!(typeof val === "string" || typeof val === "number")) {
+      throw new DecodeError(`unexpected BigInt source: ${val} (${typeof val})`);
+    }
+    return BigInt(val);
+  },
 });
 
+// to use it:
 const value = BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1);
@@ -409,6 +429,7 @@ const encoded: = encode(value, { extensionCodec });
 
+// to define a custom codec
 const extensionCodec = new ExtensionCodec();
 extensionCodec.register({
   type: EXT_TIMESTAMP, // override the default behavior!
-  encode: (input: any) => {
+  encode(input: unknown): Uint8Array | null {
     if (input instanceof Instant) {
@@ -422,3 +443,3 @@ const sec = input.seconds;
   },
-  decode: (data: Uint8Array) => {
+  decode(data: Uint8Array): Instant {
     const timeSpec = decodeTimestampToTimeSpec(data);
@@ -431,2 +452,3 @@ const sec = BigInt(timeSpec.sec);
 
+// to use it
 const instant = Instant.fromEpochMilliseconds(Date.now());
@@ -477,2 +499,6 @@ const encoded = encode(instant, { extensionCodec });
 
+The mapping of integers varies on the setting of `useBigInt64`.
+
+The default, `useBigInt64: false` is:
+
 Source Value|MessagePack Format|Value Decoded
@@ -482,4 +508,4 @@ ----|----|----
 boolean (true, false)|bool family|boolean (true, false)
-number (53-bit int)|int family|number (53-bit int)
-number (64-bit float)|float family|number (64-bit float)
+number (53-bit int)|int family|number
+number (64-bit float)|float family|number
 string|str family|string
@@ -490,2 +516,3 @@ ArrayBufferView |bin family|Uint8Array (*2)
 Date|timestamp ext family|Date (*4)
+bigint|N/A|N/A (*5)
 
@@ -496,3 +523,22 @@ * *1 Both `null` and `undefined` are mapped to `nil` (`0xC0`) type, and are decoded into `null`
 * *4 MessagePack timestamps may have nanoseconds, which will lost when it is decoded into JavaScript `Date`. This behavior can be overridden by registering `-1` for the extension codec.
+* *5 bigint is not supported in `useBigInt64: false` mode, but you can define an extension codec for it.
 
+If you set `useBigInt64: true`, the following mapping is used:
+
+Source Value|MessagePack Format|Value Decoded
+----|----|----
+null, undefined|nil|null
+boolean (true, false)|bool family|boolean (true, false)
+**number (32-bit int)**|int family|number
+**number (except for the above)**|float family|number
+**bigint**|int64 / uint64|bigint (*6)
+string|str family|string
+ArrayBufferView |bin family|Uint8Array
+Array|array family|Array
+Object|map family|Object
+Date|timestamp ext family|Date
+
+
+* *6 If the bigint is larger than the max value of uint64 or smaller than the min value of int64, then the behavior is undefined.
+
 ## Prerequisites
@@ -504,18 +550,17 @@
 
-* ES5 language features
+* ES2015 language features
 * ES2018 standard library, including:
   * Typed arrays (ES2015)
   * Async iterations (ES2018)
-  * Features added in ES2015-ES2018
+  * Features added in ES2015-ES2022
+* whatwg encodings (`TextEncoder` and `TextDecoder`)
 
-ES2018 standard library used in this library can be polyfilled with [core-js](https://github.com/zloirock/core-js).
+ES2022 standard library used in this library can be polyfilled with [core-js](https://github.com/zloirock/core-js).
 
-If you support IE11, import `core-js` in your application entrypoints, as this library does in testing for browsers.
+IE11 is no longer supported. If you'd like to use this library in IE11, use v2.x versions.
 
 ### NodeJS
 
-NodeJS v10 is required, but NodeJS v12 or later is recommended because it includes the V8 feature of [Improving DataView performance in V8](https://v8.dev/blog/dataview).
+NodeJS v14 is required.
 
-NodeJS before v10 will work by importing `@msgpack/msgpack/dist.es5+umd/msgpack`.
-
 ### TypeScript Compiler / Type Definitions
@@ -522,0 +567,0 @@

src/Encoder.ts

@@ -6,3 +6,3 @@ import { utf8Count, utf8Encode } from "./utils/utf8";
 import type { ExtData } from "./ExtData";
-import type { ContextOf, SplitUndefined } from "./context";
+import type { ContextOf } from "./context";
 
@@ -9,0 +9,0 @@

No alert changes

Improved metrics

Total package byte prevSize

661638

increased by0.24%

Number of lines in readme file

667

increased by7.23%

Worsened metrics

Lines of code

7962

decreased by-0.01%

No dependency changes