@schema-pack/message-pack 0.0.0-commit.26afe064c7a56c37bf7fb74f67222a4decd06fd4 → 0.0.0-commit.721b26d0d077bb71e76afea09e4aa75652e85c7b

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Pawnary, Inc. and Elvis Muñoz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -6,7 +6,18 @@
 
 # @schema-pack/message-pack
 
-A [MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md)
+<p align="center">
+  <a href='/docs/message-pack'>
+    Documentation
+  </a>
+  |
+  <a href='/docs/message-pack/install'>
+    Quick start
+  </a>
+</p>
+
+Incremental
+[MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md)
 encoder/decoder for TypeScript and JavaScript. It targets full compliance with
 the MessagePack spec and exposes a pluggable extension system for encoding
 custom types.
@@ -14,138 +25,9 @@ custom types.
 ## Installation
 
 ```bash
-pnpm add @schema-pack/message-pack
+pnpm add @schema-pack/message-pack@next
 ```
 
-## Quick start
-
-```ts
-import { Decoder, Encoder } from '@schema-pack/message-pack';
-
-const encoder = new Encoder();
-const bytes = encoder.encode({ hello: 'world', values: [1, 2, 3] });
-
-const decoder = new Decoder();
-const value = decoder.decode(bytes);
-// { hello: 'world', values: [1, 2, 3] }
-```
-
-## The 64-bit integer caveat
-
-JavaScript numbers are IEEE 754 double-precision floats, so they can only
-represent integers safely between `Number.MIN_SAFE_INTEGER` and
-`Number.MAX_SAFE_INTEGER` (±(2^53 - 1)) — exported here as `INT64_MIN` and
-`UINT64_MAX`. MessagePack's native `uint 64` / `int 64` formats, however, cover
-the _full_ 64-bit range.
-
-By default, the encoder and decoder read and write these formats as regular JS
-`number`s, which is safe as long as your values stay within that safe integer
-range. If you need the full 64-bit range — or want to work with `bigint`
-directly — register the built-in `BigIntExtension`:
-
-```ts
-import { BigIntExtension, Decoder, Encoder } from '@schema-pack/message-pack';
-
-const extension = new BigIntExtension(); // extension type 0-127, defaults to 0
-
-const encoder = new Encoder().addExtension(extension);
-const decoder = new Decoder().addExtension(extension);
-
-const bytes = encoder.encode(123_456_789_012_345_678_901_234_567_890n);
-decoder.decode(bytes); // 123456789012345678901234567890n
-```
-
-Values within the safe integer range are still encoded as native MessagePack
-`uint`/`int` formats even with the extension registered — `BigIntExtension` only
-takes over once a `bigint` value falls outside that range.
-
-## Built-in extensions
-
-- **`BigIntExtension`** — encodes/decodes `bigint` values outside the safe
-  integer range, using a variable-length representation of the value's magnitude
-  plus sign.
-- **`TimestampDateExtension`** — encodes/decodes JS `Date` objects using the
-  standard MessagePack
-  [timestamp extension type](https://github.com/msgpack/msgpack/blob/master/spec.md#timestamp-extension-type)
-  (`-1`), automatically choosing the 32-bit, 64-bit, or 96-bit format based on
-  the date's range and precision. Because it uses the reserved timestamp type,
-  register it as an _internal_ extension:
-
-```ts
-import {
-  Decoder,
-  Encoder,
-  TimestampDateExtension,
-} from '@schema-pack/message-pack';
-
-const extension = new TimestampDateExtension();
-
-const encoder = new Encoder().addInternalExtension(extension);
-const decoder = new Decoder().addInternalExtension(extension);
-
-const bytes = encoder.encode(new Date());
-decoder.decode(bytes); // Date instance
-```
-
-## Writing your own extensions
-
-Implement the `MessagePackExtension<TValue, TBuffer>` interface (or extend the
-abstract `UntypedExtension` helper, which takes care of storing `type`):
-
-```ts
-interface MessagePackExtension<
-  TValue = unknown,
-  TBuffer extends Uint8Array = Uint8Array,
-> {
-  readonly type: number;
-  encode(
-    value: object | bigint,
-    buffer: MessagePackEncoderBuffer<TBuffer>,
-  ): void;
-  decode(decoderBuffer: MessagePackDecoderBuffer, size: number): TValue;
-}
-```
-
-Then register it on both the encoder and the decoder:
-
-- `addExtension(extension)` — custom extension types, in the range `0` to `127`.
-- `addExtensionType(type, extension)` — same as above, with the type passed as a
-  separate argument.
-- `addInternalExtension(extension)` — reserved types, in the range `-128` to
-  `-1`, used for spec-defined extensions such as timestamps.
-- `fetchExtension(type)` — look up a registered extension by its type.
-
-Inside `encode()`, the buffer argument exposes low-level writers (`writeUint8`,
-`writeUint32`, `writeBin`, `ensureCapacity`, `view`, `offset`, etc.) for
-building a custom binary payload — see the `MessagePackEncoderBuffer` interface
-for the full API.
-
-## Encoder options
-
-| Option                    | Default                          | Description                                                                                                                                                                                                               |
-| ------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `initialBufferSize`       | `1024`                           | Initial size of the encoding buffer; grows automatically as needed.                                                                                                                                                       |
-| `newBufferFn`             | `(size) => new Uint8Array(size)` | Factory used to allocate new buffers.                                                                                                                                                                                     |
-| `initialSharedBufferSize` | `1024`                           | Initial size of the shared buffer used when encoding strings, to reduce allocations.                                                                                                                                      |
-| `textEncoder`             | `DefaultTextEncoder`             | Encoder used to turn strings into bytes. A `NodeTextEncoder` is also provided for faster string encoding on Node.                                                                                                         |
-| `sortKeys`                | `false`                          | Sort object keys before encoding, for deterministic output.                                                                                                                                                               |
-| `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. |
-
-## Decoder options
-
-| Option              | Default                          | Description                                                         |
-| ------------------- | -------------------------------- | ------------------------------------------------------------------- |
-| `initialBufferSize` | `1024`                           | Initial size of the decoding buffer; grows automatically as needed. |
-| `newBufferFn`       | `(size) => new Uint8Array(size)` | Factory used to allocate new buffers.                               |
-
-## Error handling
-
-The encoder and decoder currently throw plain `Error`s for invalid usage — e.g.
-registering a duplicate or out-of-range extension type, looking up an extension
-that isn't registered, or decoding a malformed timestamp payload. There's no
-dedicated error class hierarchy yet, so catch `Error` and inspect `message` if
-you need to branch on failure.
-
 ## License
 
 MIT

package/dist/cjs/benchmark/decoderDataTypesFactory.cjs

@@ -0,0 +1,37 @@
+const require_encoder_encoder = require("../encoder/encoder.cjs");
+let _schema_pack_benchmark = require("@schema-pack/benchmark");
+//#region src/benchmark/decoderDataTypesFactory.ts
+const encoder = new require_encoder_encoder();
+const decoderDataTypesFactory = {
+	array16: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.array16()),
+	array32: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.array32()),
+	bin16: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.bin16()),
+	bin32: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.bin32()),
+	bin8: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.bin8()),
+	false: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.false()),
+	fixarray: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.fixarray()),
+	fixmap: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.fixmap()),
+	fixstr: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.fixstr()),
+	float32: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.float32()),
+	float64: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.float64()),
+	int16: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.int16()),
+	int32: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.int32()),
+	int64: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.int64()),
+	int8: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.int8()),
+	map16: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.map16()),
+	map32: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.map32()),
+	negativeFixint: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.negativeFixint()),
+	nil: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.nil()),
+	positiveFixint: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.positiveFixint()),
+	str16: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.str16()),
+	str32: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.str32()),
+	str8: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.str8()),
+	true: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.true()),
+	uint16: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.uint16()),
+	uint32: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.uint32()),
+	uint64: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.uint64()),
+	uint8: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.uint8()),
+	undefined: () => encoder.encode(_schema_pack_benchmark.dataTypesFactory.undefined())
+};
+//#endregion
+module.exports = decoderDataTypesFactory;

package/dist/cjs/benchmark/decoderDataTypesFactory.d.cts

@@ -0,0 +1,5 @@
+import { dataTypesFactory } from "@schema-pack/benchmark";
+//#region src/benchmark/decoderDataTypesFactory.d.ts
+declare const decoderDataTypesFactory: Record<keyof typeof dataTypesFactory, () => Uint8Array>;
+export = decoderDataTypesFactory;
+//# sourceMappingURL=decoderDataTypesFactory.d.cts.map

package/dist/cjs/benchmark/decoderDataTypesFactory.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoderDataTypesFactory.d.cts","names":[],"sources":["../../../src/benchmark/decoderDataTypesFactory.ts"],"mappings":";;cAMM,yBAAyB,oBAChB,wBACP"}

package/dist/cjs/bigInt-BdjzezQQ.d.cts

@@ -0,0 +1,35 @@
+import { t as MessagePackDecoderBuffer } from "./messagePackDecoderBuffer-B2rRVlMX.cjs";
+import { i as ExtensionEncoderBuffer } from "./messagePackExtension-Cd99Rw9t.cjs";
+import { t as UntypedExtension } from "./untypedExtension-wx6-_4mg.cjs";
+//#region src/extensions/bigint/bigInt.d.ts
+/**
+ * This class encodes and decodes JavaScript BigInt values that are outside the
+ * safe integer range. It encodes and decodes BigInt values using a custom
+ * extension type, allowing for the serialization of large integers that cannot
+ * be represented as standard JavaScript numbers. The encoding scheme uses a
+ * variable-length representation to efficiently store the magnitude of the
+ * BigInt value.
+ */
+declare class BigIntExtension<TBuffer extends Uint8Array = Uint8Array> extends UntypedExtension<bigint, TBuffer> {
+  /**
+   * Encodes a BigInt value into the provided buffer. If the value is within the
+   * safe integer range, it is encoded directly following the Message Pack
+   * specification. Otherwise, if the value is outside the safe integer range,
+   * it is encoded using a variable-length representation. Negative values are
+   * handled by encoding their magnitude and using a specific bit pattern to
+   * indicate negativity.
+   *
+   * @param value - The BigInt value to encode.
+   * @param buffer - The buffer to write the encoded data to.
+   */
+  encode(value: object | bigint, buffer: ExtensionEncoderBuffer<TBuffer>): void;
+  /**
+   * Decodes a BigInt value from the provided DataView. It reads the encoded
+   * data, reconstructs the magnitude, and determines the sign based on the
+   * encoding scheme. The method returns the decoded BigInt value.
+   */
+  decode(buffer: MessagePackDecoderBuffer, size: number): bigint;
+}
+//#endregion
+export { BigIntExtension as t };
+//# sourceMappingURL=bigInt-BdjzezQQ.d.cts.map

package/dist/cjs/bigInt-BdjzezQQ.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bigInt-BdjzezQQ.d.cts","names":[],"sources":["../../src/extensions/bigint/bigInt.ts"],"mappings":";;;;;;;;;;;;cAcM,gBACJ,gBAAgB,aAAa,oBACrB,yBAAyB;;;;;;;;;;;;EAYjC,OACE,wBACA,QAAQ,uBAAuB;;;;;;EAyBjC,OAAO,QAAQ,0BAA0B"}

package/dist/cjs/bufferWithExtensions-n6DtcUoA.d.cts

@@ -0,0 +1,12 @@
+import { o as MessagePackBufferWithExtensions, t as MessagePackExtension } from "./messagePackExtension-Cd99Rw9t.cjs";
+//#region src/bufferWithExtensions.d.ts
+declare abstract class BufferWithExtensions<TBuffer extends Uint8Array = Uint8Array> implements MessagePackBufferWithExtensions<TBuffer> {
+  protected extensions: Map<number, MessagePackExtension<unknown, TBuffer>>;
+  constructor();
+  addExtension(extension: MessagePackExtension<unknown, TBuffer>): this;
+  addInternalExtension(extension: MessagePackExtension<unknown, TBuffer>): this;
+  fetchExtension(type: number): MessagePackExtension<unknown, TBuffer>;
+}
+//#endregion
+export { BufferWithExtensions as t };
+//# sourceMappingURL=bufferWithExtensions-n6DtcUoA.d.cts.map

package/dist/cjs/bufferWithExtensions-n6DtcUoA.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferWithExtensions-n6DtcUoA.d.cts","names":[],"sources":["../../src/bufferWithExtensions.ts"],"mappings":";;uBAGe,qBACb,gBAAgB,aAAa,uBAClB,gCAAgC;YACjC,YAAY,YAAY,8BAA8B;EAEhE;EAIA,aAAa,WAAW,8BAA8B;EAsBtD,qBACE,WAAW,8BAA8B;EAuB3C,eAAe,eAAe,8BAA8B"}

package/dist/cjs/bufferWithExtensions.cjs

@@ -0,0 +1,28 @@
+//#region src/bufferWithExtensions.ts
+var BufferWithExtensions = class {
+	extensions;
+	constructor() {
+		this.extensions = /* @__PURE__ */ new Map();
+	}
+	addExtension(extension) {
+		if (this.extensions.has(extension.type)) throw new Error(`Extension with type ${extension.type} already exists`);
+		if (extension.type < 0) throw new Error(`Extension type must be a non-negative integer, got ${extension.type}. Extensions between -128 and -1 are reserved for internal use. Use addInternalExtension() to register an internal extension.`);
+		if (extension.type > 127) throw new Error(`Extension type must be in the range 0 to 127, got ${extension.type}`);
+		this.extensions.set(extension.type, extension);
+		return this;
+	}
+	addInternalExtension(extension) {
+		if (this.extensions.has(extension.type)) throw new Error(`Extension with type ${extension.type} already exists`);
+		if (extension.type >= 0) throw new Error(`Internal extension type must be a negative integer, got ${extension.type}. Use addExtension() to register a custom extension.`);
+		if (extension.type < -128) throw new Error(`Internal extension type must be in the range -128 to -1, got ${extension.type}`);
+		this.extensions.set(extension.type, extension);
+		return this;
+	}
+	fetchExtension(type) {
+		const extension = this.extensions.get(type);
+		if (!extension) throw new Error(`Extension with type ${type} not found`);
+		return extension;
+	}
+};
+//#endregion
+module.exports = BufferWithExtensions;

package/dist/cjs/bufferWithExtensions.d.cts

@@ -0,0 +1,2 @@
+import { t as BufferWithExtensions } from "./bufferWithExtensions-n6DtcUoA.cjs";
+export = BufferWithExtensions;

package/dist/cjs/constants.cjs

@@ -0,0 +1,36 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/constants.ts
+/**
+* JavaScript numbers are stored as IEEE 754 double precision floating point
+* numbers, which means that they can only safely represent max uint64 as:
+*
+* 2^53 - 1 = 9007199254740991, or Number.MAX_SAFE_INTEGER.
+*
+* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
+*/
+const UINT64_MAX = Number.MAX_SAFE_INTEGER;
+/**
+* JavaScript numbers are stored as IEEE 754 double precision floating point
+* numbers, which means that they can only safely represent min int64 as:
+*
+* -(2^53 - 1) = -9007199254740991, or Number.MIN_SAFE_INTEGER.
+*
+* @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER
+*/
+const INT64_MIN = Number.MIN_SAFE_INTEGER;
+/** 4294967295. */
+const UINT32_MAX = -1 >>> 0;
+/** -2147483648. */
+const INT32_MIN = -2147483648;
+/**
+* Default allocation size for the encoder and decoder buffers. This is the
+* initial size of the buffer when it is created, and it will grow as needed
+* when more data is written to it.
+*/
+const DEFAULT_ALLOCATION_SIZE = 1024;
+//#endregion
+exports.DEFAULT_ALLOCATION_SIZE = DEFAULT_ALLOCATION_SIZE;
+exports.INT32_MIN = INT32_MIN;
+exports.INT64_MIN = INT64_MIN;
+exports.UINT32_MAX = UINT32_MAX;
+exports.UINT64_MAX = UINT64_MAX;

package/dist/cjs/constants.d.cts

@@ -0,0 +1,32 @@
+//#region src/constants.d.ts
+/**
+ * JavaScript numbers are stored as IEEE 754 double precision floating point
+ * numbers, which means that they can only safely represent max uint64 as:
+ *
+ * 2^53 - 1 = 9007199254740991, or Number.MAX_SAFE_INTEGER.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER
+ */
+declare const UINT64_MAX: number;
+/**
+ * JavaScript numbers are stored as IEEE 754 double precision floating point
+ * numbers, which means that they can only safely represent min int64 as:
+ *
+ * -(2^53 - 1) = -9007199254740991, or Number.MIN_SAFE_INTEGER.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER
+ */
+declare const INT64_MIN: number;
+/** 4294967295. */
+declare const UINT32_MAX: number;
+/** -2147483648. */
+declare const INT32_MIN = -2147483648;
+/**
+ * Default allocation size for the encoder and decoder buffers. This is the
+ * initial size of the buffer when it is created, and it will grow as needed
+ * when more data is written to it.
+ */
+declare const DEFAULT_ALLOCATION_SIZE = 1024;
+//#endregion
+export { DEFAULT_ALLOCATION_SIZE, INT32_MIN, INT64_MIN, UINT32_MAX, UINT64_MAX };
+//# sourceMappingURL=constants.d.cts.map

package/dist/cjs/constants.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.cts","names":[],"sources":["../../src/constants.ts"],"mappings":";;;;;;;;;cAQa;;;;;;;;;cAUA;;cAGA;;cAGA;;;;;;cAOA"}

package/dist/cjs/decode-BraWmoPw.d.cts

@@ -0,0 +1,5 @@
+//#region src/decoder/decode.d.ts
+declare function decode<TValue = unknown>(buffer: Uint8Array): TValue;
+//#endregion
+export { decode as t };
+//# sourceMappingURL=decode-BraWmoPw.d.cts.map

package/dist/cjs/decode-BraWmoPw.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-BraWmoPw.d.cts","names":[],"sources":["../../src/decoder/decode.ts"],"mappings":";iBAIwB,OAAO,kBAAkB,QAAQ,aAAa"}

package/dist/cjs/decoder/decode.cjs

@@ -0,0 +1,8 @@
+//#region src/decoder/decode.ts
+const sharedDecoderBuffer = new (require("./decoderBuffer.cjs"))();
+function decode(buffer) {
+	sharedDecoderBuffer.setBuffer(buffer);
+	return sharedDecoderBuffer.nextValue();
+}
+//#endregion
+module.exports = decode;

package/dist/cjs/decoder/decode.d.cts

@@ -0,0 +1,2 @@
+import { t as decode } from "../decode-BraWmoPw.cjs";
+export = decode;

package/dist/cjs/decoder/decoder.cjs

@@ -0,0 +1,30 @@
+const require_decoder_decoderBuffer = require("./decoderBuffer.cjs");
+//#region src/decoder/decoder.ts
+var Decoder = class {
+	decoderBuffer;
+	constructor(options) {
+		this.decoderBuffer = new require_decoder_decoderBuffer(options);
+	}
+	decode(encodedBuffer) {
+		const decoderBuffer = this.decoderBuffer;
+		decoderBuffer.setBuffer(encodedBuffer);
+		return decoderBuffer.nextValue();
+	}
+	addExtension(extension) {
+		this.decoderBuffer.addExtension(extension);
+		return this;
+	}
+	addInternalExtension(extension) {
+		this.decoderBuffer.addInternalExtension(extension);
+		return this;
+	}
+	addExtensionType(type, extension) {
+		this.decoderBuffer.addExtension({
+			type,
+			...extension
+		});
+		return this;
+	}
+};
+//#endregion
+module.exports = Decoder;

package/dist/cjs/decoder/decoder.d.cts

@@ -0,0 +1,2 @@
+import { t as Decoder } from "../decoder-3WpVBZjY.cjs";
+export = Decoder;