@evolu/common 8.8.0 → 8.10.0

package/dist/src/Binary.d.ts

@@ -1,254 +0,0 @@
-/**
- * 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 { bytesToUtf8, utf8ToBytes } from "@noble/ciphers/utils.js";
-import type { FiniteNumber, JsonValue, NonNegativeInt, PositiveInt } from "./Type.ts";
-export { bytesToHex, concatBytes, hexToBytes } from "@noble/ciphers/utils.js";
-export { bytesToUtf8, utf8ToBytes };
-/**
- * Custom error for {@link Buffer}-related failures like premature end of data.
- * Provides better stack traces for debugging binary protocol issues.
- */
-export declare class BufferError extends Error {
-    constructor(message: string);
-}
-/**
- * A Buffer is a dynamic, resizable container for binary data, optimized for
- * scenarios where the final size is unknown. It grows exponentially (doubling
- * its capacity) to minimize memory reallocations and uses `subarray` for
- * efficient, copy-free data access in methods like `unwrap` and `shift`.
- *
- * ## Recommended Usage
- *
- * Create as few Buffers as possible—typically one main Buffer for the final
- * output. Temporary Buffers are allowed when necessary (e.g., for
- * variable-length headers), but avoid excessive allocations. Buffers can be
- * 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.
- *
- * ### Example
- *
- * ```ts
- * import {
- *   assertEqual,
- *   assertErr,
- *   assertInstanceOf,
- *   createBuffer,
- *   createIdFromString,
- *   IdBytes,
- *   idBytesToId,
- *   idBytesTypeValueLength,
- *   idToIdBytes,
- *   NonNegativeInt,
- *   trySync,
- *   decodeNonNegativeInt,
- *   encodeNonNegativeInt,
- * } from "@evolu/common";
- *
- * const buffer = createBuffer();
- * const id = createIdFromString("buffer-example");
- * encodeNonNegativeInt(buffer, NonNegativeInt.orThrow(300));
- * buffer.extend(idToIdBytes(id));
- *
- * const decoder = createBuffer(buffer.unwrap());
- * assertEqual(decodeNonNegativeInt(decoder), 300);
- * const decodedId = idBytesToId(
- *   IdBytes.orThrow(decoder.shiftN(idBytesTypeValueLength)),
- * );
- * assertEqual(decodedId, id);
- * const result = trySync(() => decodeNonNegativeInt(decoder));
- * assertErr(result);
- * assertInstanceOf(result.error, Error);
- * assertEqual(result.error.message, "Buffer parse ended prematurely");
- * ```
- *
- * For more on exponential growth, see:
- * https://blog.mozilla.org/nnethercote/2014/11/04/please-grow-your-buffers-exponentially
- */
-export interface Buffer {
-    /** Returns the current capacity of the buffer. */
-    getCapacity: () => NonNegativeInt;
-    /** Returns the current number of bytes stored in the buffer. */
-    getLength: () => NonNegativeInt;
-    /**
-     * Appends binary data to the buffer, resizing if necessary. Throws if
-     * `arg.length` is not a non-negative safe integer.
-     */
-    extend: (arg: Uint8Array | ArrayLike<number>) => void;
-    /**
-     * Removes and returns the first byte. Throws an `Error` with message "Buffer
-     * parse ended prematurely" if the buffer is empty.
-     */
-    shift: () => NonNegativeInt;
-    /**
-     * Removes and returns the first `n` bytes. Throws an `Error` with message
-     * "Buffer parse ended prematurely" if fewer than `n` bytes remain.
-     */
-    shiftN: (n: NonNegativeInt) => Uint8Array;
-    /**
-     * Truncates the buffer to the specified length, discarding data from the end.
-     * Throws if the new length is greater than the current length.
-     */
-    truncate: (length: NonNegativeInt) => void;
-    /**
-     * Resets the buffer to its initial empty state, preserving its capacity.
-     *
-     * This allows efficient buffer reuse without reallocating memory. Use this
-     * when you want to clear the buffer and write new data, avoiding unnecessary
-     * allocations.
-     */
-    reset: () => void;
-    /**
-     * Returns a view of the buffer’s current data. Do not modify this array, as
-     * it directly alters the buffer’s internal state, potentially breaking
-     * subsequent operations.
-     */
-    unwrap: () => Uint8Array;
-}
-/** Creates a {@link Buffer} for efficient byte operations. */
-export declare const createBuffer: (arrayLike?: Uint8Array | ArrayLike<number>) => Buffer;
-/**
- * Evolu uses MessagePack to handle finite numbers except for NonNegativeInt.
- * For NonNegativeInt, Evolu provides more efficient encoding.
- */
-export declare const encodeNumber: (buffer: Buffer, number: FiniteNumber) => void;
-export declare const decodeNumber: (buffer: Buffer) => FiniteNumber;
-/**
- * Encodes an array of boolean flags into a single byte.
- *
- * Each element in the array corresponds to a bit (0-7). Array can have 0-8
- * elements.
- *
- * ### Example
- *
- * ```ts
- * import { assertEqual, createBuffer, encodeFlags } from "@evolu/common";
- *
- * const buffer = createBuffer();
- * encodeFlags(buffer, [true, false, true]);
- *
- * assertEqual(buffer.unwrap(), new Uint8Array([0b101]));
- * ```
- */
-export declare const encodeFlags: (buffer: Buffer, flags: ReadonlyArray<boolean>) => void;
-/**
- * Decodes a byte into an array of boolean flags.
- *
- * ### Example
- *
- * ```ts
- * import {
- *   assertEqual,
- *   createBuffer,
- *   decodeFlags,
- *   PositiveInt,
- * } from "@evolu/common";
- *
- * const buffer = createBuffer([0b101]);
- * const flags = decodeFlags(buffer, PositiveInt.orThrow(3));
- *
- * assertEqual(flags, [true, false, true]);
- * assertEqual(buffer.getLength(), 0);
- * ```
- */
-export declare const decodeFlags: (buffer: Buffer, count: PositiveInt) => ReadonlyArray<boolean>;
-/**
- * Encodes a non-negative integer into a variable-length integer format. It's
- * more efficient than encoding via {@link encodeNumber}.
- *
- * https://en.wikipedia.org/wiki/Variable-length_quantity
- */
-export declare const encodeNonNegativeInt: (buffer: Buffer, value: NonNegativeInt) => void;
-/**
- * Decodes a non-negative integer from a variable-length integer format.
- *
- * https://en.wikipedia.org/wiki/Variable-length_quantity
- */
-export declare const decodeNonNegativeInt: (buffer: Buffer) => NonNegativeInt;
-/** Encodes the length of an array-like value. */
-export declare const encodeLength: (buffer: Buffer, value: ArrayLike<unknown>) => void;
-/** Decodes an array-like value length. */
-export declare const decodeLength: typeof decodeNonNegativeInt;
-/** Encodes a length-prefixed UTF-8 string. */
-export declare const encodeString: (buffer: Buffer, value: string) => void;
-/** Decodes a length-prefixed UTF-8 string. */
-export declare const decodeString: (buffer: Buffer) => string;
-/** Incrementally encodes consecutive equal values using run-length encoding. */
-export interface RunLengthEncoder<T> {
-    readonly add: (value: T) => void;
-    readonly getLength: () => NonNegativeInt;
-    readonly unwrap: () => Uint8Array;
-}
-/** Creates an incremental run-length encoder. */
-export declare const createRunLengthEncoder: <T>(encodeValue: (buffer: Buffer, value: T) => void) => RunLengthEncoder<T>;
-/** Decodes a run-length encoded sequence. */
-export declare const decodeRle: <T>(buffer: Buffer, length: NonNegativeInt, decodeValue: () => T) => ReadonlyArray<T>;
-/**
- * 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=Binary.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Binary.d.ts","sourceRoot":"","sources":["../../src/Binary.ts"],"names":[],"mappings":"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"}