feat(core): Add bytesLen and bytesLenUnsafe utilities

Author: phroi

.changeset/eighty-terms-cry.md

@@ -0,0 +1,5 @@
+---
+"@ckb-ccc/core": patch
+---
+
+Add `bytesLen` and `bytesLenUnsafe` utilities

packages/core/src/hex/index.ts

@@ -18,7 +18,7 @@ export type HexLike = BytesLike;
  * A valid hexadecimal string:
  * - Has at least two characters.
  * - Starts with "0x".
- * - Has an even length.
+ * - Has an even length (odd-length hex is considered non-standard).
  * - Contains only characters representing digits (0-9) or lowercase letters (a-f) after the "0x" prefix.
  *
  * @param v - The value to validate as a hexadecimal (ccc.Hex) string.
@@ -58,3 +58,59 @@ export function hexFrom(hex: HexLike): Hex {
 
   return `0x${bytesTo(bytesFrom(hex), "hex")}`;
 }
+
+/**
+ * Return the number of bytes occupied by `hexLike`.
+ *
+ * This function efficiently calculates the byte length of hex-like values:
+ * - For valid Hex strings, uses fast-path `bytesLenUnsafe` helper
+ * - For other types, falls back to length via `bytesFrom`
+ *
+ * @param hexLike - Hex-like value (Hex string, Uint8Array, ArrayBuffer, or iterable of numbers).
+ * @returns Byte length of `hexLike`.
+ *
+ * @throws May throw if `hexLike` contains invalid byte values when passed to `bytesFrom`.
+ * @see bytesFrom - Convert values to Bytes (Uint8Array)
+ * @see bytesLenUnsafe - Fast byte length for valid Hex strings
+ *
+ * @example
+ * ```typescript
+ * bytesLen("0x48656c6c6f") // 5
+ * bytesLen(new Uint8Array([1, 2, 3])) // 3
+ * bytesLen(new ArrayBuffer(4)) // 4
+ * bytesLen([0x01, 0x02]) // 2
+ * ```
+ *
+ * @note For performance, access `.length` directly on `Bytes` (`Uint8Array`).
+ * If `bytesFrom(hexLike)` is called for other operations, access `.length` on
+ * that result instead. This function is only useful when performing no further
+ * operations on `hexLike`.
+ */
+export function bytesLen(hexLike: HexLike): number {
+  if (isHex(hexLike)) {
+    return bytesLenUnsafe(hexLike);
+  }
+
+  return bytesFrom(hexLike).length;
+}
+
+/**
+ * Fast byte length for Hex strings.
+ *
+ * This function efficiently calculates the byte length of Hex values:
+ * - Skips isHex validation
+ * - Handles odd-length hex by rounding up (matching bytesFrom behavior).
+ *
+ * @param hex - A Hex string (with "0x" prefix).
+ * @returns Byte length.
+ *
+ * @example
+ * ```typescript
+ * bytesLenUnsafe("0x48656c6c6f") // 5
+ * bytesLenUnsafe("0x123")        // 2 (odd digits → ceiling)
+ * ```
+ */
+export function bytesLenUnsafe(hex: Hex): number {
+  // Rounds up for odd-digit hex. Equivalent to Math.ceil((hex.length - 2) / 2).
+  return (hex.length - 1) >> 1;
+}