@evolu/common 8.7.0 → 8.8.0

package/src/{Buffer.ts → Binary.ts}

@@ -11,15 +11,16 @@
  * @module
  */
 
+import { bytesToUtf8, utf8ToBytes } from "@noble/ciphers/utils.js";
 import type { Result } from "./Result.ts";
-import type { JsonValue, NonNegativeInt } from "./Type.ts";
-export {
-  bytesToHex,
-  bytesToUtf8,
-  concatBytes,
-  hexToBytes,
-  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.
@@ -54,9 +55,9 @@ export class BufferError extends Error {
  *
  * ```ts
  * import {
- *   assert,
  *   assertEqual,
  *   assertErr,
+ *   assertInstanceOf,
  *   createBuffer,
  *   createIdFromString,
  *   IdBytes,
@@ -65,11 +66,9 @@ export class BufferError extends Error {
  *   idToIdBytes,
  *   NonNegativeInt,
  *   trySync,
- * } from "@evolu/common";
- * import {
  *   decodeNonNegativeInt,
  *   encodeNonNegativeInt,
- * } from "@evolu/common/local-first";
+ * } from "@evolu/common";
  *
  * const buffer = createBuffer();
  * const id = createIdFromString("buffer-example");
@@ -84,11 +83,8 @@ export class BufferError extends Error {
  * assertEqual(decodedId, id);
  * const result = trySync(() => decodeNonNegativeInt(decoder));
  * assertErr(result);
- * assert(
- *   result.error instanceof Error &&
- *     result.error.message === "Buffer parse ended prematurely",
- *   "Expected the premature-buffer-end error.",
- * );
+ * assertInstanceOf(result.error, Error);
+ * assertEqual(result.error.message, "Buffer parse ended prematurely");
  * ```
  *
  * For more on exponential growth, see:
@@ -149,9 +145,7 @@ export const createBuffer = (
   const initialLength = arrayLike?.length ?? 0;
   assertNonNegativeInt(initialLength, "arrayLike.length");
 
-  let value = arrayLike
-    ? new globalThis.Uint8Array(arrayLike)
-    : new globalThis.Uint8Array(512);
+  let value = arrayLike ? new Uint8Array(arrayLike) : new Uint8Array(512);
   let length = initialLength;
 
   const buffer: Buffer = {
@@ -169,7 +163,7 @@ export const createBuffer = (
       if (value.length < targetSize) {
         const oldValue = value;
         const newCapacity = Math.max(value.length * 2, targetSize);
-        value = new globalThis.Uint8Array(newCapacity);
+        value = new Uint8Array(newCapacity);
         value.set(oldValue);
       }
       value.set(arg, length);
@@ -211,6 +205,244 @@ export const createBuffer = (
   return buffer;
 };
 
+/**
+ * Evolu uses MessagePack to handle finite numbers except for NonNegativeInt.
+ * For NonNegativeInt, Evolu provides more efficient encoding.
+ */
+export const encodeNumber = (buffer: Buffer, number: FiniteNumber): void => {
+  encodeJsonValue(buffer, number);
+};
+
+export const decodeNumber = (buffer: Buffer): FiniteNumber => {
+  const value = decodeJsonValue(buffer);
+  if (typeof value !== "number") {
+    throw new BufferError("Expected an encoded number.");
+  }
+  return value;
+};
+
+/**
+ * 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 const encodeFlags = (
+  buffer: Buffer,
+  flags: ReadonlyArray<boolean>,
+): void => {
+  let byte = 0;
+  for (let i = 0; i < flags.length && i < 8; i++) {
+    if (flags[i]) {
+      byte |= 1 << i;
+    }
+  }
+  buffer.extend([byte]);
+};
+
+/**
+ * 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 const decodeFlags = (
+  buffer: Buffer,
+  count: PositiveInt,
+): ReadonlyArray<boolean> => {
+  const byte = buffer.shift();
+  const length = Math.min(count, 8);
+  // oxlint-disable-next-line unicorn/no-new-array -- Preallocation is intentional in this decoding hot path.
+  const flags = new Array<boolean>(length);
+  for (let i = 0; i < length; i++) {
+    flags[i] = (byte & (1 << i)) !== 0;
+  }
+  return flags;
+};
+
+/**
+ * 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 const encodeNonNegativeInt = (
+  buffer: Buffer,
+  value: NonNegativeInt,
+): void => {
+  if (value === 0) {
+    buffer.extend([0]);
+    return;
+  }
+
+  let remaining = BigInt(value);
+  const bytes: Array<number> = [];
+
+  while (remaining !== 0n) {
+    const byte = Number(remaining & 127n);
+    bytes.push(byte);
+    remaining >>= 7n;
+  }
+
+  for (let i = 0; i < bytes.length - 1; i++) {
+    bytes[i] |= 128;
+  }
+
+  buffer.extend(bytes);
+};
+
+/**
+ * Decodes a non-negative integer from a variable-length integer format.
+ *
+ * https://en.wikipedia.org/wiki/Variable-length_quantity
+ */
+export const decodeNonNegativeInt = (buffer: Buffer): NonNegativeInt => {
+  let result = 0n;
+  let shift = 0n;
+  let byte = 0;
+
+  // 8 is the smallest required count
+  for (let byteCount = 0; byteCount < 8; byteCount++) {
+    byte = buffer.shift();
+    result |= BigInt(byte & 127) << shift;
+    if ((byte & 128) === 0) break;
+    shift += 7n;
+  }
+
+  if ((byte & 128) !== 0) {
+    throw new BufferError(
+      "Variable-length quantity must terminate within 8 bytes.",
+    );
+  }
+
+  const value = Number(result);
+  assertNonNegativeInt(value, "Decoded integer");
+  return value;
+};
+
+/** Encodes the length of an array-like value. */
+export const encodeLength = (
+  buffer: Buffer,
+  value: ArrayLike<unknown>,
+): void => {
+  assertNonNegativeInt(value.length, "Array-like length");
+  encodeNonNegativeInt(buffer, value.length);
+};
+
+/** Decodes an array-like value length. */
+export const decodeLength = decodeNonNegativeInt;
+
+/** Encodes a length-prefixed UTF-8 string. */
+export const encodeString = (buffer: Buffer, value: string): void => {
+  const bytes = utf8ToBytes(value);
+  encodeLength(buffer, bytes);
+  buffer.extend(bytes);
+};
+
+/** Decodes a length-prefixed UTF-8 string. */
+export const decodeString = (buffer: Buffer): string => {
+  const length = decodeLength(buffer);
+  const bytes = buffer.shiftN(length);
+  return bytesToUtf8(bytes);
+};
+
+/** 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 const createRunLengthEncoder = <T>(
+  encodeValue: (buffer: Buffer, value: T) => void,
+): RunLengthEncoder<T> => {
+  const buffer = createBuffer();
+  let previousLength = 0 as NonNegativeInt;
+  let previousValue = null as T | null;
+  let runLength = 0 as NonNegativeInt;
+
+  return {
+    add: (value) => {
+      if (Object.is(value, previousValue)) {
+        runLength++;
+        buffer.truncate(previousLength);
+      } else {
+        previousValue = value;
+        runLength = 1 as NonNegativeInt;
+      }
+      previousLength = buffer.getLength();
+      encodeValue(buffer, value);
+      encodeNonNegativeInt(buffer, runLength);
+    },
+
+    getLength: () => buffer.getLength(),
+
+    unwrap: () => buffer.unwrap(),
+  };
+};
+
+/** Decodes a run-length encoded sequence. */
+export const decodeRle = <T>(
+  buffer: Buffer,
+  length: NonNegativeInt,
+  decodeValue: () => T,
+): ReadonlyArray<T> => {
+  // oxlint-disable-next-line unicorn/no-new-array -- Preallocation is intentional in this decoding hot path.
+  const values = new Array<T>(length);
+  let index = 0;
+  while (index < length) {
+    const value = decodeValue();
+    const runLength = decodeNonNegativeInt(buffer);
+
+    // Prevent infinite loop on malformed input.
+    if (runLength === 0) {
+      throw new BufferError("Invalid RLE encoding: runLength must be positive");
+    }
+
+    const remaining = length - index;
+
+    // Prevent CPU/memory amplification via oversized runLength.
+    if (runLength > remaining) {
+      throw new BufferError(
+        `Invalid RLE encoding: runLength ${runLength} exceeds remaining ${remaining}`,
+      );
+    }
+
+    for (let i = 0; i < runLength; i++) {
+      values[index] = value;
+      index++;
+    }
+  }
+
+  return values;
+};
+
 // Inspired by msgpackr 2.0.5, licensed under the MIT License.
 // This implementation is specialized for Evolu's JsonValue domain.
 //
@@ -244,23 +476,25 @@ interface JsonKeyCacheEntry {
 const jsonKeyCacheSize = 4096;
 const maxCachedJsonKeyByteLength = 32;
 const maxJsonNestingDepth = 1_000;
-let jsonEncoderTarget = new globalThis.Uint8Array(8192);
-let jsonEncoderTargetView = new globalThis.DataView(jsonEncoderTarget.buffer);
+let jsonEncoderTarget = new Uint8Array(8192);
+let jsonEncoderTargetView = new DataView(jsonEncoderTarget.buffer);
 let jsonEncoderPosition = 0;
 let jsonEncoderDepth = 0;
 let jsonEncoderIsActive = false;
-const emptyJsonDecoderSource: Uint8Array = new globalThis.Uint8Array(0);
-const emptyJsonDecoderView: DataView = new globalThis.DataView(
+const emptyJsonDecoderSource: Uint8Array = new Uint8Array(0);
+const emptyJsonDecoderView: DataView = new DataView(
   emptyJsonDecoderSource.buffer,
 );
 let jsonDecoderSource: Uint8Array = emptyJsonDecoderSource;
 let jsonDecoderView: DataView = emptyJsonDecoderView;
 let jsonDecoderPosition = 0;
 let jsonDecoderDepth = 0;
-const jsonStringFromCharCode = globalThis.String.fromCharCode;
+const jsonStringFromCharCode = String.fromCharCode;
 // Cache only short keys and use a fixed table to bound retained memory.
-const jsonKeyCache: Array<JsonKeyCacheEntry | undefined> =
-  globalThis.Array.from({ length: jsonKeyCacheSize }, () => undefined);
+const jsonKeyCache: Array<JsonKeyCacheEntry | undefined> = Array.from(
+  { length: jsonKeyCacheSize },
+  () => undefined,
+);
 
 /**
  * Encodes a {@link JsonValue} using the MessagePack format.
@@ -337,7 +571,7 @@ export const encodeJsonValue = (buffer: Buffer, value: JsonValue): void => {
 export const decodeJsonValue = (buffer: Buffer): JsonValue => {
   const source = buffer.unwrap();
   jsonDecoderSource = source;
-  jsonDecoderView = new globalThis.DataView(
+  jsonDecoderView = new DataView(
     source.buffer,
     source.byteOffset,
     source.byteLength,
@@ -372,7 +606,7 @@ const encodeJsonValueToTarget = (value: JsonValue): void => {
       encodeJsonStringToTarget(value);
       return;
     case "number": {
-      if (globalThis.Object.is(value, -0)) {
+      if (Object.is(value, -0)) {
         ensureJsonEncoderCapacity(9);
         jsonEncoderTarget[jsonEncoderPosition++] = 0xcb;
         jsonEncoderTargetView.setFloat64(jsonEncoderPosition, value);
@@ -401,11 +635,7 @@ const encodeJsonValueToTarget = (value: JsonValue): void => {
         return;
       }
 
-      if (
-        globalThis.Number.isInteger(value) &&
-        value >= -0x80000000 &&
-        value < 0
-      ) {
+      if (Number.isInteger(value) && value >= -0x80000000 && value < 0) {
         if (value >= -0x20) {
           writeJsonEncoderByte(0x100 + value);
         } else if (value >= -0x80) {
@@ -443,7 +673,7 @@ const encodeJsonValueToTarget = (value: JsonValue): void => {
       }
       jsonEncoderDepth++;
 
-      if (globalThis.Array.isArray(value)) {
+      if (Array.isArray(value)) {
         const array = value as ReadonlyArray<JsonValue>;
         const length = array.length;
         writeJsonCollectionHeader(length, 0x90, 0xdc, 0xdd);
@@ -454,7 +684,7 @@ const encodeJsonValueToTarget = (value: JsonValue): void => {
       }
 
       const object = value as Readonly<Record<string, JsonValue>>;
-      const keys = globalThis.Object.keys(object);
+      const keys = Object.keys(object);
       writeJsonCollectionHeader(keys.length, 0x80, 0xde, 0xdf);
 
       for (const key of keys) {
@@ -590,16 +820,13 @@ const ensureJsonEncoderCapacity = (additionalLength: number): void => {
 
   if (requiredLength <= jsonEncoderTarget.length) return;
 
-  const newCapacity = globalThis.Math.max(
-    jsonEncoderTarget.length * 2,
-    requiredLength,
-  );
+  const newCapacity = Math.max(jsonEncoderTarget.length * 2, requiredLength);
   assertNonNegativeInt(newCapacity, "JSON encoder capacity");
 
   const oldTarget = jsonEncoderTarget;
-  jsonEncoderTarget = new globalThis.Uint8Array(newCapacity);
+  jsonEncoderTarget = new Uint8Array(newCapacity);
   jsonEncoderTarget.set(oldTarget.subarray(0, jsonEncoderPosition));
-  jsonEncoderTargetView = new globalThis.DataView(jsonEncoderTarget.buffer);
+  jsonEncoderTargetView = new DataView(jsonEncoderTarget.buffer);
 };
 
 const assertMessagePackLength = (length: number, name: string): void => {
@@ -679,7 +906,7 @@ const decodeJsonFloat = (byteLength: 4 | 8): JsonValue => {
       : jsonDecoderView.getFloat64(jsonDecoderPosition);
   jsonDecoderPosition += byteLength;
 
-  if (!globalThis.Number.isFinite(value)) {
+  if (!Number.isFinite(value)) {
     throw new BufferError("A decoded JSON number must be finite.");
   }
   return value as JsonValue;
@@ -1036,7 +1263,7 @@ const decodeJsonMap = (length: number): JsonValue => {
     const entryValue = decodeJsonValueFromSource();
 
     if (key === "__proto__") {
-      globalThis.Object.defineProperty(value, key, {
+      Object.defineProperty(value, key, {
         value: entryValue,
         configurable: true,
         enumerable: true,
@@ -1135,7 +1362,7 @@ const assertNonNegativeInt: (
   value: number,
   name: string,
 ) => asserts value is NonNegativeInt = (value, name) => {
-  if (!globalThis.Number.isSafeInteger(value) || value < 0) {
+  if (!Number.isSafeInteger(value) || value < 0) {
     throw new BufferError(`${name} must be a non-negative safe integer.`);
   }
 };

package/src/Brand.test.ts

@@ -0,0 +1,90 @@
+import { test } from "node:test";
+
+import type { Brand, IsBranded } from "./Brand.ts";
+import { constVoid } from "./Function.ts";
+import { assertType } from "./Type.ts";
+
+test("Brand", () => {
+  type UserId = string & Brand<"UserId">;
+  type ProductId = number & Brand<"ProductId">;
+
+  const validUserId: UserId = "user123" as UserId;
+  assertType<typeof validUserId, string & Brand<"UserId">>();
+
+  const validProductId: ProductId = 42 as ProductId;
+  assertType<typeof validProductId, number & Brand<"ProductId">>();
+
+  // Invalid assignment (string to ProductId)
+  // @ts-expect-error - Should not allow a string to be assigned to ProductId
+  const invalidProductId: ProductId = "not-a-number";
+
+  // Invalid assignment (unbranded string to UserId)
+  // @ts-expect-error - Should not allow unbranded string to be assigned to UserId
+  const invalidUserId: UserId = "user123";
+
+  // Invalid assignment (mixing different brands)
+  // @ts-expect-error - Should not allow assigning a ProductId to a UserId
+  const mismatchedId: UserId = validProductId;
+});
+
+test("Brand - multiple brands", () => {
+  type Min1 = string & Brand<"Min1">;
+  type Max100 = string & Brand<"Max100">;
+  type Min1Max100 = string & Brand<"Min1" | "Max100">;
+
+  const requiresMin1 = (_value: Min1) => constVoid;
+  const requiresMax100 = (_value: Max100) => constVoid;
+
+  const min1Value: Min1 = "hello" as Min1;
+  const max100Value: Max100 = "world" as Max100;
+  const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
+
+  requiresMin1(min1Value);
+  requiresMax100(max100Value);
+  requiresMin1(min1Max100Value);
+  requiresMax100(min1Max100Value);
+
+  // @ts-expect-error: brands works
+  requiresMin1("hello");
+  // @ts-expect-error: brands works
+  requiresMin1(max100Value);
+  // @ts-expect-error: brands works
+  requiresMax100("world");
+  // @ts-expect-error: brands works
+  requiresMax100(min1Value);
+});
+
+test("IsBranded", () => {
+  type UnbrandedString = string;
+  type BrandedString = string & Brand<"UserId">;
+  type BrandedNumber = number & Brand<"ProductId">;
+  type DoubleBranded = string & Brand<"Min"> & Brand<"Max">;
+
+  assertType<IsBranded<UnbrandedString>, false>();
+  assertType<IsBranded<BrandedString>, true>();
+  assertType<IsBranded<BrandedNumber>, true>();
+  assertType<IsBranded<DoubleBranded>, true>();
+});
+
+test("Brand - standalone (nominal type)", () => {
+  // Brand can be used alone without a base type for purely nominal typing.
+  // Useful for platform-specific values where type identity is based on name only.
+  type NativePort = Brand<"NativePort">;
+
+  const requiresNativePort = (_port: NativePort) => constVoid;
+
+  // Only branded values can be passed
+  const nativePort: NativePort = {} as NativePort;
+  requiresNativePort(nativePort);
+
+  // @ts-expect-error: plain unknown cannot be passed
+  requiresNativePort({} as unknown);
+
+  // @ts-expect-error: other types cannot be passed
+  requiresNativePort({});
+
+  // @ts-expect-error: null cannot be passed
+  requiresNativePort(null);
+
+  assertType<IsBranded<NativePort>, true>();
+});