@evolu/common 8.6.1 → 8.7.0

package/dist/src/Buffer.d.ts

@@ -1,9 +1,16 @@
 /**
  * Binary data handling and byte array utilities.
  *
+ * Buffer-based decoding functions intentionally throw errors instead of
+ * returning {@link Result}. This is a deliberate micro-optimization for Evolu
+ * Protocol's hot paths: Result is inexpensive, but returning decoded values
+ * directly avoids its success-case allocation, and using `Error` objects
+ * preserves stack traces. In the future, we will try returning `Error` objects
+ * in `Result` values to measure the real-world performance impact.
+ *
  * @module
  */
-import { NonNegativeInt } from "./Type.ts";
+import type { JsonValue, NonNegativeInt } from "./Type.ts";
 export { bytesToHex, bytesToUtf8, concatBytes, hexToBytes, utf8ToBytes, } from "@noble/ciphers/utils.js";
 /**
  * Custom error for {@link Buffer}-related failures like premature end of data.
@@ -26,12 +33,7 @@ export declare class BufferError extends Error {
  * reused within functions by leveraging `reset` to clear contents while
  * preserving capacity, or `truncate` to adjust the length to a specific size,
  * reducing the need for new allocations. Pass Buffers to `encode*` functions to
- * append serialized data and use `decode*` functions to extract data. Both
- * `shift` and `shiftN` throw an {@link BufferError} with message "Buffer parse
- * ended prematurely" on failure, as do higher-level `decode*` functions,
- * providing stack traces for debugging instead of using {@link Result}. This
- * avoids allocation overhead in success cases and leverages exceptions'
- * diagnostic benefits.
+ * append serialized data and use `decode*` functions to extract data.
  *
  * ### Example
  *
@@ -84,7 +86,7 @@ export interface Buffer {
     getLength: () => NonNegativeInt;
     /**
      * Appends binary data to the buffer, resizing if necessary. Throws if
-     * `arg.length` is not a non-negative integer.
+     * `arg.length` is not a non-negative safe integer.
      */
     extend: (arg: Uint8Array | ArrayLike<number>) => void;
     /**
@@ -119,4 +121,61 @@ export interface Buffer {
 }
 /** Creates a {@link Buffer} for efficient byte operations. */
 export declare const createBuffer: (arrayLike?: Uint8Array | ArrayLike<number>) => Buffer;
+/**
+ * Encodes a {@link JsonValue} using the MessagePack format.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   createBuffer,
+ *   encodeJsonValue,
+ *   JsonValue,
+ * } from "@evolu/common";
+ *
+ * const buffer = createBuffer();
+ * const value = JsonValue.orThrow({ name: "Ada" });
+ *
+ * encodeJsonValue(buffer, value);
+ *
+ * assertEqual(
+ *   buffer.unwrap(),
+ *   new Uint8Array([
+ *     0x81, 0xa4, 0x6e, 0x61, 0x6d, 0x65, 0xa3, 0x41, 0x64, 0x61,
+ *   ]),
+ * );
+ * ```
+ *
+ * Encoding is artificially limited to 1,000 nested arrays or objects to keep
+ * recursive encoding and decoding safe and symmetric. JSON data should not
+ * require such depth; flatten or split deeply nested data, or use a
+ * purpose-built serialization format.
+ */
+export declare const encodeJsonValue: (buffer: Buffer, value: JsonValue) => void;
+/**
+ * Decodes a {@link JsonValue} using the MessagePack format.
+ *
+ * Throws a {@link BufferError} without modifying the Buffer if the encoded value
+ * is malformed, truncated, unsupported, outside the JsonValue domain, or
+ * exceeds 1,000 nested arrays or objects.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   createBuffer,
+ *   decodeJsonValue,
+ * } from "@evolu/common";
+ *
+ * const buffer = createBuffer([
+ *   0x81, 0xa4, 0x6e, 0x61, 0x6d, 0x65, 0xa3, 0x41, 0x64, 0x61,
+ * ]);
+ *
+ * assertEqual(decodeJsonValue(buffer), { name: "Ada" });
+ * assertEqual(buffer.unwrap(), new Uint8Array());
+ * ```
+ */
+export declare const decodeJsonValue: (buffer: Buffer) => JsonValue;
 //# sourceMappingURL=Buffer.d.ts.map

package/dist/src/Buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Buffer.d.ts","sourceRoot":"","sources":["../../src/Buffer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,cAAc,EAAsB,MAAM,WAAW,CAAC;AAC/D,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAO,EAAE,MAAM,EAK1B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,WAAW,MAAM;IACrB,kDAAkD;IAClD,WAAW,EAAE,MAAM,cAAc,CAAC;IAElC,gEAAgE;IAChE,SAAS,EAAE,MAAM,cAAc,CAAC;IAEhC;;;OAGG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAEtD;;;OAGG;IACH,KAAK,EAAE,MAAM,cAAc,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,UAAU,CAAC;IAE1C;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAE3C;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB;;;;OAIG;IACH,MAAM,EAAE,MAAM,UAAU,CAAC;CAC1B;AAED,8DAA8D;AAC9D,eAAO,MAAM,YAAY,eACX,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KACzC,MA4DF,CAAC"}
+{"version":3,"file":"Buffer.d.ts","sourceRoot":"","sources":["../../src/Buffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAEjC;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAO,EAAE,MAAM,EAK1B;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,WAAW,MAAM;IACrB,kDAAkD;IAClD,WAAW,EAAE,MAAM,cAAc,CAAC;IAElC,gEAAgE;IAChE,SAAS,EAAE,MAAM,cAAc,CAAC;IAEhC;;;OAGG;IACH,MAAM,EAAE,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAEtD;;;OAGG;IACH,KAAK,EAAE,MAAM,cAAc,CAAC;IAE5B;;;OAGG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,cAAc,KAAK,UAAU,CAAC;IAE1C;;;OAGG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,CAAC;IAE3C;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAElB;;;;OAIG;IACH,MAAM,EAAE,MAAM,UAAU,CAAC;CAC1B;AAED,8DAA8D;AAC9D,eAAO,MAAM,YAAY,eACX,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,KACzC,MAgEF,CAAC;AAqDF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,WAAY,MAAM,SAAS,SAAS,KAAG,IAelE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,WAAY,MAAM,KAAG,SAwBhD,CAAC"}