@schema-pack/message-pack 0.0.0-commit.26afe064c7a56c37bf7fb74f67222a4decd06fd4 → 0.0.0-commit.2ea6fc3f9c377c8d3c31c5690c0f42c9add30ded

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,8 @@
 
 # @schema-pack/message-pack
 
-A [MessagePack](https://github.com/msgpack/msgpack/blob/master/spec.md)
+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,137 +15,22 @@ custom types.
 ## Installation
 
 ```bash
-pnpm add @schema-pack/message-pack
+pnpm add @schema-pack/message-pack@next
 ```
 
-## Quick start
+### Quick start
 
 ```ts
-import { Decoder, Encoder } from '@schema-pack/message-pack';
+import { encode, decode } from '@schema-pack/message-pack';
 
-const encoder = new Encoder();
-const bytes = encoder.encode({ hello: 'world', values: [1, 2, 3] });
+const buffer = encode({ hello: 'world', values: [1, 2, 3] });
 
-const decoder = new Decoder();
-const value = decoder.decode(bytes);
+const value = decode(buffer);
 // { 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.
+For more information, visit the
+[documentation](https://pawnary.github.io/schema-pack/docs/message-pack).
 
 ## License
 

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

@@ -0,0 +1,51 @@
+import { d as TimestampDateExtension, f as MessagePackBuiltInExtension, i as MessagePackExtension, r as MessagePackBufferWithExtensions, s as BigIntExtensionOptions, t as ErrorExtension, u as BufferWithExtensionsOptions } from "./error-B129l__v.cjs";
+//#region src/bufferWithExtensions.d.ts
+type MessagePackExtensionLike<TBuffer extends Uint8Array> = MessagePackExtension<object, TBuffer> | MessagePackBuiltInExtension<object, TBuffer>;
+declare abstract class BufferWithExtensions<TBuffer extends Uint8Array = Uint8Array> implements MessagePackBufferWithExtensions<TBuffer> {
+  /**
+   * Default extension type for `BigInt` values. This is used when the user does
+   * not provide a custom extension type for `BigInt` values.
+   */
+  static readonly DEFAULT_BIG_INT_EXTENSION_TYPE = 0;
+  /**
+   * The extensions map is used to store the registered extensions. The key is
+   * the extension type, and the value is the extension instance.
+   */
+  protected extensions: Map<number, MessagePackExtension<object, TBuffer>>;
+  /**
+   * The built-in extensions map is used to store the built-in extensions. The
+   * key is the extension type, and the value is the extension instance.
+   */
+  protected builtInExtensions: Map<number, MessagePackBuiltInExtension<object, TBuffer>>;
+  /**
+   * The timestamp date extension is used to encode and decode `Date` values. It
+   * is optional and can be disabled by setting the `extensions.timestampDate`
+   * option to `false`.
+   */
+  readonly timestampDateExtension?: TimestampDateExtension<TBuffer>;
+  /**
+   * The big integer extension is used to encode and decode `BigInt` values. It
+   * is optional and can be disabled by setting the `extensions.bigInt` option
+   * to `false`.
+   *
+   * If enabled, the user can provide a custom extension type for `BigInt`
+   * values by setting the `extensions.bigInt.type` option.
+   */
+  readonly bigIntExtension?: BigIntExtensionOptions;
+  /**
+   * The error extension is used to encode and decode `Error` values. It is
+   * optional and can be disabled by setting the `extensions.error` option to
+   * `false`.
+   *
+   * If enabled, the user can provide a custom extension for `Error` values by
+   * setting the `extensions.error` option to an instance of `ErrorExtension`.
+   */
+  readonly errorExtension?: ErrorExtension<TBuffer>;
+  constructor(options?: BufferWithExtensionsOptions<TBuffer>);
+  getExtensions(): ReadonlyMap<number, MessagePackExtension<object, TBuffer>>;
+  addExtension<TValue extends object>(extension: MessagePackExtension<TValue, TBuffer>): this;
+  fetchExtension(type: number): MessagePackExtensionLike<TBuffer>;
+}
+//#endregion
+export { BufferWithExtensions as t };
+//# sourceMappingURL=bufferWithExtensions-Cg4LGSIy.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bufferWithExtensions-Cg4LGSIy.d.cts","names":[],"sources":["../../src/bufferWithExtensions.ts"],"mappings":";;KAYK,yBAAyB,gBAAgB,cAC1C,6BAA6B,WAC7B,oCAAoC;uBAEzB,qBACb,gBAAgB,aAAa,uBAClB,gCAAgC;;;;;kBAK3B;;;;;YAMN,YAAU,YAAA,6BAAA;;;;;YASV,mBAAiB,YAAA,oCAAA;;;;;;WAUlB,yBAAyB,uBAAuB;;;;;;;;;WAUhD,kBAAkB;;;;;;;;;WAUlB,iBAAiB,eAAe;EAEzC,YAAY,UAAU,4BAA4B;EA0ClD,iBAAiB,oBAAoB,6BAA6B;EAIlE,aAAa,uBACX,WAAW,qBAAqB,QAAQ;EAiC1C,eAAe,eAAe,yBAAyB"}

package/dist/cjs/bufferWithExtensions.cjs

@@ -0,0 +1,91 @@
+const require_extensions_error_error = require("./extensions/error/error.cjs");
+const require_extensions_timestampDate_timestampDate = require("./extensions/timestampDate/timestampDate.cjs");
+const require_utils_assertValidExtensionType = require("./utils/assertValidExtensionType.cjs");
+//#region src/bufferWithExtensions.ts
+var BufferWithExtensions = class BufferWithExtensions {
+	/**
+	* Default extension type for `BigInt` values. This is used when the user does
+	* not provide a custom extension type for `BigInt` values.
+	*/
+	static DEFAULT_BIG_INT_EXTENSION_TYPE = 0;
+	/**
+	* The extensions map is used to store the registered extensions. The key is
+	* the extension type, and the value is the extension instance.
+	*/
+	extensions = /* @__PURE__ */ new Map();
+	/**
+	* The built-in extensions map is used to store the built-in extensions. The
+	* key is the extension type, and the value is the extension instance.
+	*/
+	builtInExtensions = /* @__PURE__ */ new Map();
+	/**
+	* The timestamp date extension is used to encode and decode `Date` values. It
+	* is optional and can be disabled by setting the `extensions.timestampDate`
+	* option to `false`.
+	*/
+	timestampDateExtension = void 0;
+	/**
+	* The big integer extension is used to encode and decode `BigInt` values. It
+	* is optional and can be disabled by setting the `extensions.bigInt` option
+	* to `false`.
+	*
+	* If enabled, the user can provide a custom extension type for `BigInt`
+	* values by setting the `extensions.bigInt.type` option.
+	*/
+	bigIntExtension = void 0;
+	/**
+	* The error extension is used to encode and decode `Error` values. It is
+	* optional and can be disabled by setting the `extensions.error` option to
+	* `false`.
+	*
+	* If enabled, the user can provide a custom extension for `Error` values by
+	* setting the `extensions.error` option to an instance of `ErrorExtension`.
+	*/
+	errorExtension = void 0;
+	constructor(options) {
+		if (options?.extensions !== false) {
+			if (options?.extensions?.bigInt !== false) {
+				this.bigIntExtension = options?.extensions?.bigInt ?? { type: BufferWithExtensions.DEFAULT_BIG_INT_EXTENSION_TYPE };
+				require_utils_assertValidExtensionType(this.bigIntExtension.type);
+			}
+			if (options?.extensions?.error !== false) {
+				if (options?.extensions?.error instanceof require_extensions_error_error) this.errorExtension = options.extensions.error;
+				else this.errorExtension = new require_extensions_error_error(options?.extensions?.error);
+				require_utils_assertValidExtensionType(this.errorExtension.type);
+				this.builtInExtensions.set(this.errorExtension.type, this.errorExtension);
+			}
+			if (options?.extensions?.timestampDate !== false) {
+				if (options?.extensions?.timestampDate instanceof require_extensions_timestampDate_timestampDate) this.timestampDateExtension = options.extensions.timestampDate;
+				else this.timestampDateExtension = new require_extensions_timestampDate_timestampDate();
+				this.builtInExtensions.set(require_extensions_timestampDate_timestampDate.DEFAULT_TYPE, this.timestampDateExtension);
+			}
+		}
+	}
+	getExtensions() {
+		return this.extensions;
+	}
+	addExtension(extension) {
+		if (this.extensions.has(extension.type)) {
+			const existent = this.extensions.get(extension.type);
+			throw new Error(`Extension with type ${extension.type} already registered for ${existent.constructor.name}`);
+		}
+		require_utils_assertValidExtensionType(extension.type);
+		if (this.builtInExtensions.has(extension.type)) {
+			const existent = this.builtInExtensions.get(extension.type);
+			throw new Error(`Extension with type ${extension.type} conflicts with built-in extension ${existent.constructor.name}`);
+		}
+		if (extension.type === this.bigIntExtension?.type) throw new Error(`Extension with type ${extension.type} conflicts with built-in BigInt extension`);
+		this.extensions.set(extension.type, extension);
+		return this;
+	}
+	fetchExtension(type) {
+		let extension = this.builtInExtensions.get(type);
+		if (!extension) {
+			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-Cg4LGSIy.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 sharedDecoder = new (require("./decoder.cjs"))();
+function decode(buffer) {
+	sharedDecoder.setBuffer(buffer);
+	return sharedDecoder.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;