@solana/codecs-data-structures 8.4.0 → 8.5.0-canary-20261006090716

package/README.md

@@ -71,6 +71,8 @@ Because the sentinel is only compared at the start of the next item slot, two in
 1. **No item may _begin_ with the sentinel's bytes.** A valid item that starts with the sentinel is indistinguishable from the terminator, so decoding would stop early at that item. The sentinel may still appear _inside_ an item, just never at its start. For example, a single `0xff` byte is a poor sentinel for a list of public keys, since roughly one key in 256 starts with `0xff`; a sentinel as wide as an item (such as the all-zero public key) avoids this because only that exact key can match the terminator.
 2. **Under `"optional"` and `"omitted"`, the sentinel must be no wider than the smallest possible item.** Otherwise a trailing region shorter than the sentinel but large enough to hold a valid item would be skipped, since decoding stops as soon as fewer bytes than the sentinel remain. This cannot arise under `"required"` because a terminator is always written.
 
+Unlike the invariants above, one condition is enforced by the codec: the sentinel and `"remainder"` strategies reject zero-byte item codecs (e.g. `getStructCodec([])`), on both the encoding and decoding sides, since such items can never advance past a sentinel boundary or the end of the byte array. Creating one throws `SOLANA_ERROR__CODECS__UNEXPECTED_ZERO_FIXED_SIZE_ITEM_FOR_ARRAY_LIKE_SIZE_STRATEGY`. Zero-byte items remain valid when the collection size is explicit, such as a size prefix or a fixed number of items.
+
 When the size is stored as a prefix, decoding an exhausted byte array yields an empty array instead of failing. This allows arrays to be appended to existing data layouts without breaking the decoding of older data. Use the `requireSizePrefix` option to throw instead.
 
 ```ts

package/dist/index.browser.cjs

@@ -34,7 +34,9 @@ function getMaxSize(codec) {
 function getArrayEncoder(item, config = {}) {
   const size = config.size ?? codecsNumbers.getU32Encoder();
   assertValidSize(size);
-  const fixedSize = computeArrayLikeCodecSize(size, getFixedSize(item));
+  const itemSize = getFixedSize(item);
+  assertItemCodecSupportsSizeStrategy(config.description ?? "array", size, itemSize);
+  const fixedSize = computeArrayLikeCodecSize(size, itemSize);
   const maxSize = computeArrayLikeCodecSize(size, getMaxSize(item)) ?? void 0;
   return codecsCore.createEncoder({
     ...fixedSize !== null ? { fixedSize } : {
@@ -67,6 +69,7 @@ function getArrayDecoder(item, config = {}) {
   const size = config.size ?? codecsNumbers.getU32Decoder();
   assertValidSize(size);
   const itemSize = getFixedSize(item);
+  assertItemCodecSupportsSizeStrategy(config.description ?? "array", size, itemSize);
   const fixedSize = computeArrayLikeCodecSize(size, itemSize);
   const maxSize = computeArrayLikeCodecSize(size, getMaxSize(item)) ?? void 0;
   return codecsCore.createDecoder({
@@ -137,6 +140,15 @@ function assertValidSize(size) {
     throw new errors.SolanaError(errors.SOLANA_ERROR__CODECS__SENTINEL_MUST_NOT_BE_EMPTY);
   }
 }
+function assertItemCodecSupportsSizeStrategy(codecDescription, size, itemFixedSize) {
+  if (itemFixedSize !== 0) return;
+  if (size === "remainder" || isSentinelSize(size)) {
+    throw new errors.SolanaError(errors.SOLANA_ERROR__CODECS__UNEXPECTED_ZERO_FIXED_SIZE_ITEM_FOR_ARRAY_LIKE_SIZE_STRATEGY, {
+      codecDescription,
+      sizeStrategy: size === "remainder" ? "remainder" : "sentinel"
+    });
+  }
+}
 function hexBytes(bytes) {
   return bytes.reduce((str, byte) => str + byte.toString(16).padStart(2, "0"), "");
 }