@schema-pack/message-pack 0.0.0-commit.26afe064c7a56c37bf7fb74f67222a4decd06fd4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +151 -0
- package/package.json +200 -0
package/README.md
ADDED
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
<!-- prettier-ignore-start -->
|
|
2
|
+
> [!WARNING]
|
|
3
|
+
> This is a Work In Progress, and the API is not stable yet. Breaking changes
|
|
4
|
+
> may be introduced at any time.
|
|
5
|
+
<!-- prettier-ignore-end -->
|
|
6
|
+
|
|
7
|
+
# @schema-pack/message-pack
|
|
8
|
+
|
|
9
|
+
A [MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md)
|
|
10
|
+
encoder/decoder for TypeScript and JavaScript. It targets full compliance with
|
|
11
|
+
the MessagePack spec and exposes a pluggable extension system for encoding
|
|
12
|
+
custom types.
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pnpm add @schema-pack/message-pack
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Quick start
|
|
21
|
+
|
|
22
|
+
```ts
|
|
23
|
+
import { Decoder, Encoder } from '@schema-pack/message-pack';
|
|
24
|
+
|
|
25
|
+
const encoder = new Encoder();
|
|
26
|
+
const bytes = encoder.encode({ hello: 'world', values: [1, 2, 3] });
|
|
27
|
+
|
|
28
|
+
const decoder = new Decoder();
|
|
29
|
+
const value = decoder.decode(bytes);
|
|
30
|
+
// { hello: 'world', values: [1, 2, 3] }
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## The 64-bit integer caveat
|
|
34
|
+
|
|
35
|
+
JavaScript numbers are IEEE 754 double-precision floats, so they can only
|
|
36
|
+
represent integers safely between `Number.MIN_SAFE_INTEGER` and
|
|
37
|
+
`Number.MAX_SAFE_INTEGER` (±(2^53 - 1)) — exported here as `INT64_MIN` and
|
|
38
|
+
`UINT64_MAX`. MessagePack's native `uint 64` / `int 64` formats, however, cover
|
|
39
|
+
the _full_ 64-bit range.
|
|
40
|
+
|
|
41
|
+
By default, the encoder and decoder read and write these formats as regular JS
|
|
42
|
+
`number`s, which is safe as long as your values stay within that safe integer
|
|
43
|
+
range. If you need the full 64-bit range — or want to work with `bigint`
|
|
44
|
+
directly — register the built-in `BigIntExtension`:
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
import { BigIntExtension, Decoder, Encoder } from '@schema-pack/message-pack';
|
|
48
|
+
|
|
49
|
+
const extension = new BigIntExtension(); // extension type 0-127, defaults to 0
|
|
50
|
+
|
|
51
|
+
const encoder = new Encoder().addExtension(extension);
|
|
52
|
+
const decoder = new Decoder().addExtension(extension);
|
|
53
|
+
|
|
54
|
+
const bytes = encoder.encode(123_456_789_012_345_678_901_234_567_890n);
|
|
55
|
+
decoder.decode(bytes); // 123456789012345678901234567890n
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Values within the safe integer range are still encoded as native MessagePack
|
|
59
|
+
`uint`/`int` formats even with the extension registered — `BigIntExtension` only
|
|
60
|
+
takes over once a `bigint` value falls outside that range.
|
|
61
|
+
|
|
62
|
+
## Built-in extensions
|
|
63
|
+
|
|
64
|
+
- **`BigIntExtension`** — encodes/decodes `bigint` values outside the safe
|
|
65
|
+
integer range, using a variable-length representation of the value's magnitude
|
|
66
|
+
plus sign.
|
|
67
|
+
- **`TimestampDateExtension`** — encodes/decodes JS `Date` objects using the
|
|
68
|
+
standard MessagePack
|
|
69
|
+
[timestamp extension type](https://github.com/msgpack/msgpack/blob/master/spec.md#timestamp-extension-type)
|
|
70
|
+
(`-1`), automatically choosing the 32-bit, 64-bit, or 96-bit format based on
|
|
71
|
+
the date's range and precision. Because it uses the reserved timestamp type,
|
|
72
|
+
register it as an _internal_ extension:
|
|
73
|
+
|
|
74
|
+
```ts
|
|
75
|
+
import {
|
|
76
|
+
Decoder,
|
|
77
|
+
Encoder,
|
|
78
|
+
TimestampDateExtension,
|
|
79
|
+
} from '@schema-pack/message-pack';
|
|
80
|
+
|
|
81
|
+
const extension = new TimestampDateExtension();
|
|
82
|
+
|
|
83
|
+
const encoder = new Encoder().addInternalExtension(extension);
|
|
84
|
+
const decoder = new Decoder().addInternalExtension(extension);
|
|
85
|
+
|
|
86
|
+
const bytes = encoder.encode(new Date());
|
|
87
|
+
decoder.decode(bytes); // Date instance
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Writing your own extensions
|
|
91
|
+
|
|
92
|
+
Implement the `MessagePackExtension<TValue, TBuffer>` interface (or extend the
|
|
93
|
+
abstract `UntypedExtension` helper, which takes care of storing `type`):
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
interface MessagePackExtension<
|
|
97
|
+
TValue = unknown,
|
|
98
|
+
TBuffer extends Uint8Array = Uint8Array,
|
|
99
|
+
> {
|
|
100
|
+
readonly type: number;
|
|
101
|
+
encode(
|
|
102
|
+
value: object | bigint,
|
|
103
|
+
buffer: MessagePackEncoderBuffer<TBuffer>,
|
|
104
|
+
): void;
|
|
105
|
+
decode(decoderBuffer: MessagePackDecoderBuffer, size: number): TValue;
|
|
106
|
+
}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Then register it on both the encoder and the decoder:
|
|
110
|
+
|
|
111
|
+
- `addExtension(extension)` — custom extension types, in the range `0` to `127`.
|
|
112
|
+
- `addExtensionType(type, extension)` — same as above, with the type passed as a
|
|
113
|
+
separate argument.
|
|
114
|
+
- `addInternalExtension(extension)` — reserved types, in the range `-128` to
|
|
115
|
+
`-1`, used for spec-defined extensions such as timestamps.
|
|
116
|
+
- `fetchExtension(type)` — look up a registered extension by its type.
|
|
117
|
+
|
|
118
|
+
Inside `encode()`, the buffer argument exposes low-level writers (`writeUint8`,
|
|
119
|
+
`writeUint32`, `writeBin`, `ensureCapacity`, `view`, `offset`, etc.) for
|
|
120
|
+
building a custom binary payload — see the `MessagePackEncoderBuffer` interface
|
|
121
|
+
for the full API.
|
|
122
|
+
|
|
123
|
+
## Encoder options
|
|
124
|
+
|
|
125
|
+
| Option | Default | Description |
|
|
126
|
+
| ------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
127
|
+
| `initialBufferSize` | `1024` | Initial size of the encoding buffer; grows automatically as needed. |
|
|
128
|
+
| `newBufferFn` | `(size) => new Uint8Array(size)` | Factory used to allocate new buffers. |
|
|
129
|
+
| `initialSharedBufferSize` | `1024` | Initial size of the shared buffer used when encoding strings, to reduce allocations. |
|
|
130
|
+
| `textEncoder` | `DefaultTextEncoder` | Encoder used to turn strings into bytes. A `NodeTextEncoder` is also provided for faster string encoding on Node. |
|
|
131
|
+
| `sortKeys` | `false` | Sort object keys before encoding, for deterministic output. |
|
|
132
|
+
| `forceFloat32` | `false` | Always encode floating point numbers as `float32` instead of `float64`. This may lose precision for values that don't fit exactly in 32 bits (e.g. `1.2`) — only enable it if you know your floats can round-trip safely. |
|
|
133
|
+
|
|
134
|
+
## Decoder options
|
|
135
|
+
|
|
136
|
+
| Option | Default | Description |
|
|
137
|
+
| ------------------- | -------------------------------- | ------------------------------------------------------------------- |
|
|
138
|
+
| `initialBufferSize` | `1024` | Initial size of the decoding buffer; grows automatically as needed. |
|
|
139
|
+
| `newBufferFn` | `(size) => new Uint8Array(size)` | Factory used to allocate new buffers. |
|
|
140
|
+
|
|
141
|
+
## Error handling
|
|
142
|
+
|
|
143
|
+
The encoder and decoder currently throw plain `Error`s for invalid usage — e.g.
|
|
144
|
+
registering a duplicate or out-of-range extension type, looking up an extension
|
|
145
|
+
that isn't registered, or decoding a malformed timestamp payload. There's no
|
|
146
|
+
dedicated error class hierarchy yet, so catch `Error` and inspect `message` if
|
|
147
|
+
you need to branch on failure.
|
|
148
|
+
|
|
149
|
+
## License
|
|
150
|
+
|
|
151
|
+
MIT
|
package/package.json
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@schema-pack/message-pack",
|
|
3
|
+
"version": "0.0.0-commit.26afe064c7a56c37bf7fb74f67222a4decd06fd4",
|
|
4
|
+
"description": "MessagePack implementation",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"MessagePack",
|
|
7
|
+
"binary",
|
|
8
|
+
"data",
|
|
9
|
+
"deserialization",
|
|
10
|
+
"format",
|
|
11
|
+
"msgpack",
|
|
12
|
+
"serialization"
|
|
13
|
+
],
|
|
14
|
+
"license": "MIT",
|
|
15
|
+
"author": "Elvis Muñoz <elvis.munoz.f@gmail.com>",
|
|
16
|
+
"files": [
|
|
17
|
+
"./dist"
|
|
18
|
+
],
|
|
19
|
+
"type": "module",
|
|
20
|
+
"sideEffects": false,
|
|
21
|
+
"main": "./dist/cjs/index.cjs",
|
|
22
|
+
"module": "./dist/esm/index.mjs",
|
|
23
|
+
"types": "./dist/cjs/index.d.cts",
|
|
24
|
+
"exports": {
|
|
25
|
+
".": {
|
|
26
|
+
"import": "./dist/esm/index.mjs",
|
|
27
|
+
"require": "./dist/cjs/index.cjs"
|
|
28
|
+
},
|
|
29
|
+
"./benchmark/decoderDataTypesFactory": {
|
|
30
|
+
"import": "./dist/esm/benchmark/decoderDataTypesFactory.mjs",
|
|
31
|
+
"require": "./dist/cjs/benchmark/decoderDataTypesFactory.cjs"
|
|
32
|
+
},
|
|
33
|
+
"./bufferWithExtensions": {
|
|
34
|
+
"import": "./dist/esm/bufferWithExtensions.mjs",
|
|
35
|
+
"require": "./dist/cjs/bufferWithExtensions.cjs"
|
|
36
|
+
},
|
|
37
|
+
"./constants": {
|
|
38
|
+
"import": "./dist/esm/constants.mjs",
|
|
39
|
+
"require": "./dist/cjs/constants.cjs"
|
|
40
|
+
},
|
|
41
|
+
"./decoder": {
|
|
42
|
+
"import": "./dist/esm/decoder/index.mjs",
|
|
43
|
+
"require": "./dist/cjs/decoder/index.cjs"
|
|
44
|
+
},
|
|
45
|
+
"./decoder/decoder": {
|
|
46
|
+
"import": "./dist/esm/decoder/decoder.mjs",
|
|
47
|
+
"require": "./dist/cjs/decoder/decoder.cjs"
|
|
48
|
+
},
|
|
49
|
+
"./decoder/decoderBuffer": {
|
|
50
|
+
"import": "./dist/esm/decoder/decoderBuffer.mjs",
|
|
51
|
+
"require": "./dist/cjs/decoder/decoderBuffer.cjs"
|
|
52
|
+
},
|
|
53
|
+
"./decoder/interfaces": {
|
|
54
|
+
"import": "./dist/esm/decoder/interfaces/index.mjs",
|
|
55
|
+
"require": "./dist/cjs/decoder/interfaces/index.cjs"
|
|
56
|
+
},
|
|
57
|
+
"./decoder/interfaces/messagePackDecoderBuffer": {
|
|
58
|
+
"import": "./dist/esm/decoder/interfaces/messagePackDecoderBuffer.mjs",
|
|
59
|
+
"require": "./dist/cjs/decoder/interfaces/messagePackDecoderBuffer.cjs"
|
|
60
|
+
},
|
|
61
|
+
"./decoder/interfaces/messagePackTextDecoder": {
|
|
62
|
+
"import": "./dist/esm/decoder/interfaces/messagePackTextDecoder.mjs",
|
|
63
|
+
"require": "./dist/cjs/decoder/interfaces/messagePackTextDecoder.cjs"
|
|
64
|
+
},
|
|
65
|
+
"./decoder/textDecoders/defaultTextDecoder": {
|
|
66
|
+
"import": "./dist/esm/decoder/textDecoders/defaultTextDecoder.mjs",
|
|
67
|
+
"require": "./dist/cjs/decoder/textDecoders/defaultTextDecoder.cjs"
|
|
68
|
+
},
|
|
69
|
+
"./decoder/types": {
|
|
70
|
+
"import": "./dist/esm/decoder/types.mjs",
|
|
71
|
+
"require": "./dist/cjs/decoder/types.cjs"
|
|
72
|
+
},
|
|
73
|
+
"./defaultNewBufferFn": {
|
|
74
|
+
"import": "./dist/esm/defaultNewBufferFn.mjs",
|
|
75
|
+
"require": "./dist/cjs/defaultNewBufferFn.cjs"
|
|
76
|
+
},
|
|
77
|
+
"./encoder": {
|
|
78
|
+
"import": "./dist/esm/encoder/index.mjs",
|
|
79
|
+
"require": "./dist/cjs/encoder/index.cjs"
|
|
80
|
+
},
|
|
81
|
+
"./encoder/encoder": {
|
|
82
|
+
"import": "./dist/esm/encoder/encoder.mjs",
|
|
83
|
+
"require": "./dist/cjs/encoder/encoder.cjs"
|
|
84
|
+
},
|
|
85
|
+
"./encoder/encoderBuffer": {
|
|
86
|
+
"import": "./dist/esm/encoder/encoderBuffer.mjs",
|
|
87
|
+
"require": "./dist/cjs/encoder/encoderBuffer.cjs"
|
|
88
|
+
},
|
|
89
|
+
"./encoder/interfaces": {
|
|
90
|
+
"import": "./dist/esm/encoder/interfaces/index.mjs",
|
|
91
|
+
"require": "./dist/cjs/encoder/interfaces/index.cjs"
|
|
92
|
+
},
|
|
93
|
+
"./encoder/interfaces/messagePackEncoderBuffer": {
|
|
94
|
+
"import": "./dist/esm/encoder/interfaces/messagePackEncoderBuffer.mjs",
|
|
95
|
+
"require": "./dist/cjs/encoder/interfaces/messagePackEncoderBuffer.cjs"
|
|
96
|
+
},
|
|
97
|
+
"./encoder/interfaces/messagePackTextEncoder": {
|
|
98
|
+
"import": "./dist/esm/encoder/interfaces/messagePackTextEncoder.mjs",
|
|
99
|
+
"require": "./dist/cjs/encoder/interfaces/messagePackTextEncoder.cjs"
|
|
100
|
+
},
|
|
101
|
+
"./encoder/textEncoders": {
|
|
102
|
+
"import": "./dist/esm/encoder/textEncoders/index.mjs",
|
|
103
|
+
"require": "./dist/cjs/encoder/textEncoders/index.cjs"
|
|
104
|
+
},
|
|
105
|
+
"./encoder/textEncoders/defaultTextEncoder": {
|
|
106
|
+
"import": "./dist/esm/encoder/textEncoders/defaultTextEncoder.mjs",
|
|
107
|
+
"require": "./dist/cjs/encoder/textEncoders/defaultTextEncoder.cjs"
|
|
108
|
+
},
|
|
109
|
+
"./encoder/textEncoders/nodeTextEncoder": {
|
|
110
|
+
"import": "./dist/esm/encoder/textEncoders/nodeTextEncoder.mjs",
|
|
111
|
+
"require": "./dist/cjs/encoder/textEncoders/nodeTextEncoder.cjs"
|
|
112
|
+
},
|
|
113
|
+
"./encoder/types": {
|
|
114
|
+
"import": "./dist/esm/encoder/types.mjs",
|
|
115
|
+
"require": "./dist/cjs/encoder/types.cjs"
|
|
116
|
+
},
|
|
117
|
+
"./extensions": {
|
|
118
|
+
"import": "./dist/esm/extensions/index.mjs",
|
|
119
|
+
"require": "./dist/cjs/extensions/index.cjs"
|
|
120
|
+
},
|
|
121
|
+
"./extensions/bigint": {
|
|
122
|
+
"import": "./dist/esm/extensions/bigint/index.mjs",
|
|
123
|
+
"require": "./dist/cjs/extensions/bigint/index.cjs"
|
|
124
|
+
},
|
|
125
|
+
"./extensions/bigint/bigInt": {
|
|
126
|
+
"import": "./dist/esm/extensions/bigint/bigInt.mjs",
|
|
127
|
+
"require": "./dist/cjs/extensions/bigint/bigInt.cjs"
|
|
128
|
+
},
|
|
129
|
+
"./extensions/interfaces": {
|
|
130
|
+
"import": "./dist/esm/extensions/interfaces/index.mjs",
|
|
131
|
+
"require": "./dist/cjs/extensions/interfaces/index.cjs"
|
|
132
|
+
},
|
|
133
|
+
"./extensions/interfaces/messagePackExtension": {
|
|
134
|
+
"import": "./dist/esm/extensions/interfaces/messagePackExtension.mjs",
|
|
135
|
+
"require": "./dist/cjs/extensions/interfaces/messagePackExtension.cjs"
|
|
136
|
+
},
|
|
137
|
+
"./extensions/timestampDate": {
|
|
138
|
+
"import": "./dist/esm/extensions/timestampDate/index.mjs",
|
|
139
|
+
"require": "./dist/cjs/extensions/timestampDate/index.cjs"
|
|
140
|
+
},
|
|
141
|
+
"./extensions/timestampDate/timestampDate": {
|
|
142
|
+
"import": "./dist/esm/extensions/timestampDate/timestampDate.mjs",
|
|
143
|
+
"require": "./dist/cjs/extensions/timestampDate/timestampDate.cjs"
|
|
144
|
+
},
|
|
145
|
+
"./extensions/timestampDate/types": {
|
|
146
|
+
"import": "./dist/esm/extensions/timestampDate/types.mjs",
|
|
147
|
+
"require": "./dist/cjs/extensions/timestampDate/types.cjs"
|
|
148
|
+
},
|
|
149
|
+
"./interfaces": {
|
|
150
|
+
"import": "./dist/esm/interfaces/index.mjs",
|
|
151
|
+
"require": "./dist/cjs/interfaces/index.cjs"
|
|
152
|
+
},
|
|
153
|
+
"./interfaces/messagePackBufferWithExtensions": {
|
|
154
|
+
"import": "./dist/esm/interfaces/messagePackBufferWithExtensions.mjs",
|
|
155
|
+
"require": "./dist/cjs/interfaces/messagePackBufferWithExtensions.cjs"
|
|
156
|
+
},
|
|
157
|
+
"./symbols": {
|
|
158
|
+
"import": "./dist/esm/symbols.mjs",
|
|
159
|
+
"require": "./dist/cjs/symbols.cjs"
|
|
160
|
+
},
|
|
161
|
+
"./types": {
|
|
162
|
+
"import": "./dist/esm/types.mjs",
|
|
163
|
+
"require": "./dist/cjs/types.cjs"
|
|
164
|
+
},
|
|
165
|
+
"./untypedExtension": {
|
|
166
|
+
"import": "./dist/esm/untypedExtension.mjs",
|
|
167
|
+
"require": "./dist/cjs/untypedExtension.cjs"
|
|
168
|
+
},
|
|
169
|
+
"./utils": {
|
|
170
|
+
"import": "./dist/esm/utils/index.mjs",
|
|
171
|
+
"require": "./dist/cjs/utils/index.cjs"
|
|
172
|
+
},
|
|
173
|
+
"./utils/fitIn16Bits": {
|
|
174
|
+
"import": "./dist/esm/utils/fitIn16Bits.mjs",
|
|
175
|
+
"require": "./dist/cjs/utils/fitIn16Bits.cjs"
|
|
176
|
+
},
|
|
177
|
+
"./utils/fitIn32Bits": {
|
|
178
|
+
"import": "./dist/esm/utils/fitIn32Bits.mjs",
|
|
179
|
+
"require": "./dist/cjs/utils/fitIn32Bits.cjs"
|
|
180
|
+
},
|
|
181
|
+
"./utils/fitIn7Bits": {
|
|
182
|
+
"import": "./dist/esm/utils/fitIn7Bits.mjs",
|
|
183
|
+
"require": "./dist/cjs/utils/fitIn7Bits.cjs"
|
|
184
|
+
},
|
|
185
|
+
"./utils/fitIn8Bits": {
|
|
186
|
+
"import": "./dist/esm/utils/fitIn8Bits.mjs",
|
|
187
|
+
"require": "./dist/cjs/utils/fitIn8Bits.cjs"
|
|
188
|
+
},
|
|
189
|
+
"./utils/fitInt64Bits": {
|
|
190
|
+
"import": "./dist/esm/utils/fitInt64Bits.mjs",
|
|
191
|
+
"require": "./dist/cjs/utils/fitInt64Bits.cjs"
|
|
192
|
+
},
|
|
193
|
+
"./package.json": "./package.json"
|
|
194
|
+
},
|
|
195
|
+
"devDependencies": {
|
|
196
|
+
"@jsonjoy.com/json-pack": "^18.28.0",
|
|
197
|
+
"@msgpack/msgpack": "^3.1.3",
|
|
198
|
+
"msgpackr": "^2.0.5"
|
|
199
|
+
}
|
|
200
|
+
}
|