@omnibuf/core 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/wire.js CHANGED
@@ -338,24 +338,127 @@ export function decodeUTF8(bytes, start = 0, end = bytes.length) {
338
338
  }
339
339
  return activeStringCodec.decode(bytes, start, end);
340
340
  }
341
+ /**
342
+ * Throws an Error if `bytes[start..end)` is not valid UTF-8.
343
+ */
344
+ export function assertValidUTF8(bytes, start = 0, end = bytes.length) {
345
+ if (!isValidUTF8Slice(bytes, start, end)) {
346
+ throw new Error('omnibuf: invalid UTF-8 string');
347
+ }
348
+ }
349
+ /**
350
+ * Compares two JavaScript UTF-16 strings in canonical UTF-8 byte order (Unicode scalar value order).
351
+ * Unlike JS `<`/`>` (which compares UTF-16 code units and orders astral surrogate pairs `0xD800..0xDBFF`
352
+ * before BMP `U+E000..U+FFFF`), this orders astral code points (`>= U+10000`, UTF-8 `>= 0xF0`) after
353
+ * all BMP code points (`<= U+FFFF`, UTF-8 `<= 0xEF`), matching Go/Rust/C++ UTF-8 byte order.
354
+ */
355
+ export function compareUTF8Strings(a, b) {
356
+ if (a === b)
357
+ return 0;
358
+ const lenA = a.length;
359
+ const lenB = b.length;
360
+ let iA = 0;
361
+ let iB = 0;
362
+ while (iA < lenA && iB < lenB) {
363
+ const cA = a.charCodeAt(iA);
364
+ const cB = b.charCodeAt(iB);
365
+ if (cA === cB && (cA < 0xd800 || cA > 0xdfff)) {
366
+ iA++;
367
+ iB++;
368
+ continue;
369
+ }
370
+ if ((cA < 0xd800 || cA > 0xdfff) && (cB < 0xd800 || cB > 0xdfff)) {
371
+ return cA - cB;
372
+ }
373
+ let cpA = cA;
374
+ if (cA >= 0xd800 && cA <= 0xdbff && iA + 1 < lenA) {
375
+ const loA = a.charCodeAt(iA + 1);
376
+ if (loA >= 0xdc00 && loA <= 0xdfff) {
377
+ cpA = 0x10000 + ((cA - 0xd800) << 10) + (loA - 0xdc00);
378
+ iA += 2;
379
+ }
380
+ else {
381
+ cpA = 0xfffd;
382
+ iA += 1;
383
+ }
384
+ }
385
+ else if (cA >= 0xd800 && cA <= 0xdfff) {
386
+ cpA = 0xfffd;
387
+ iA += 1;
388
+ }
389
+ else {
390
+ iA += 1;
391
+ }
392
+ let cpB = cB;
393
+ if (cB >= 0xd800 && cB <= 0xdbff && iB + 1 < lenB) {
394
+ const loB = b.charCodeAt(iB + 1);
395
+ if (loB >= 0xdc00 && loB <= 0xdfff) {
396
+ cpB = 0x10000 + ((cB - 0xd800) << 10) + (loB - 0xdc00);
397
+ iB += 2;
398
+ }
399
+ else {
400
+ cpB = 0xfffd;
401
+ iB += 1;
402
+ }
403
+ }
404
+ else if (cB >= 0xd800 && cB <= 0xdfff) {
405
+ cpB = 0xfffd;
406
+ iB += 1;
407
+ }
408
+ else {
409
+ iB += 1;
410
+ }
411
+ if (cpA !== cpB) {
412
+ return cpA - cpB;
413
+ }
414
+ }
415
+ return lenA - iA - (lenB - iB);
416
+ }
341
417
  // ============================================================================
342
418
  // ZigZag Signed Integer Mapping
343
419
  // ============================================================================
420
+ /**
421
+ * Converts a `number`, `bigint`, or decimal integer `string` into a `bigint` without losing
422
+ * 64-bit precision through IEEE-754 float64 coercion. Throws on `NaN`, `Infinity`, or malformed strings.
423
+ */
424
+ export function toBigInt64Input(v) {
425
+ if (typeof v === 'bigint')
426
+ return v;
427
+ if (typeof v === 'string') {
428
+ const trimmed = v.trim();
429
+ if (trimmed.length === 0) {
430
+ throw new Error('omnibuf: invalid empty integer string');
431
+ }
432
+ return BigInt(trimmed);
433
+ }
434
+ if (typeof v === 'number') {
435
+ if (!Number.isFinite(v)) {
436
+ throw new Error(`omnibuf: non-finite integer value ${v}`);
437
+ }
438
+ return BigInt(Math.trunc(v));
439
+ }
440
+ return BigInt(v);
441
+ }
344
442
  /**
345
443
  * Maps a signed integer (number or bigint) to an unsigned 64-bit bigint via ZigZag encoding:
346
444
  * u = (n << 1) ^ (n >> 63)
347
445
  */
348
446
  export function encodeZigZag(n) {
349
- const b = BigInt.asIntN(64, typeof n === 'bigint' ? n : BigInt(Math.trunc(n)));
447
+ const b = BigInt.asIntN(64, toBigInt64Input(n));
350
448
  return BigInt.asUintN(64, (b << 1n) ^ (b >> 63n));
351
449
  }
352
450
  /**
353
451
  * Fast-path ZigZag encoding for 32-bit signed integers that fit in safe number range.
354
452
  */
355
453
  export function encodeZigZagNumber(n) {
356
- if (typeof n === 'number' && n >= -268435456 && n <= 268435455) {
357
- const i = n | 0;
358
- return ((i << 1) ^ (i >> 31)) >>> 0;
454
+ if (typeof n === 'number') {
455
+ if (!Number.isFinite(n)) {
456
+ throw new Error(`omnibuf: non-finite integer value ${n}`);
457
+ }
458
+ if (n >= -268435456 && n <= 268435455) {
459
+ const i = n | 0;
460
+ return ((i << 1) ^ (i >> 31)) >>> 0;
461
+ }
359
462
  }
360
463
  return encodeZigZag(n);
361
464
  }
@@ -364,7 +467,7 @@ export function encodeZigZagNumber(n) {
364
467
  * n = (u >> 1) ^ -(u & 1)
365
468
  */
366
469
  export function decodeZigZagBigInt(u) {
367
- const b = BigInt.asUintN(64, typeof u === 'bigint' ? u : BigInt(Math.trunc(u)));
470
+ const b = BigInt.asUintN(64, toBigInt64Input(u));
368
471
  return BigInt.asIntN(64, (b >> 1n) ^ -(b & 1n));
369
472
  }
370
473
  /**
@@ -417,6 +520,9 @@ const MAX_4B_VARINT = 536870911;
417
520
  */
418
521
  export function varintByteLength(v) {
419
522
  if (typeof v === 'number') {
523
+ if (!Number.isFinite(v)) {
524
+ throw new Error(`omnibuf: non-finite integer value ${v}`);
525
+ }
420
526
  if (v >= 0 && v <= MAX_1B_VARINT)
421
527
  return 1;
422
528
  if (v >= 0 && v <= MAX_2B_VARINT)
@@ -425,7 +531,7 @@ export function varintByteLength(v) {
425
531
  return 4;
426
532
  return 9;
427
533
  }
428
- const u = BigInt.asUintN(64, v);
534
+ const u = BigInt.asUintN(64, toBigInt64Input(v));
429
535
  if (u <= 127n)
430
536
  return 1;
431
537
  if (u <= 16383n)
@@ -472,7 +578,7 @@ export function writeVarintAt(dst, pos, v) {
472
578
  dst[pos + 8] = (hi >>> 24) & 0xff;
473
579
  return pos + 9;
474
580
  }
475
- const u = BigInt.asUintN(64, typeof v === 'bigint' ? v : BigInt(Math.trunc(v)));
581
+ const u = BigInt.asUintN(64, toBigInt64Input(v));
476
582
  if (u <= 127n) {
477
583
  dst[pos] = Number((u << 1n) | 1n);
478
584
  return pos + 1;
@@ -930,6 +1036,18 @@ function validateUnknownEntryAt(body, p, wt, depth, limit) {
930
1036
  return -1;
931
1037
  return p + 1;
932
1038
  }
1039
+ if (wt === WireString) {
1040
+ if (p >= body.length)
1041
+ return -1;
1042
+ const [bLen, bn] = decodeVarintBigInt(body, p);
1043
+ if (bn === 0 || bLen > BigInt(body.length - (p + bn)))
1044
+ return -1;
1045
+ const start = p + bn;
1046
+ const end = start + Number(bLen);
1047
+ if (!isValidUTF8Slice(body, start, end))
1048
+ return -1;
1049
+ return end;
1050
+ }
933
1051
  if (wt === WireSubMsg) {
934
1052
  if (p >= body.length)
935
1053
  return -1;
@@ -950,6 +1068,18 @@ function validateUnknownEntryAt(body, p, wt, depth, limit) {
950
1068
  function validateUnknownValueAt(data, pos, wt, depth, limit) {
951
1069
  if (depth > limit)
952
1070
  return -1;
1071
+ if (wt === WireString) {
1072
+ if (pos >= data.length)
1073
+ return -1;
1074
+ const [bLen, bn] = decodeVarintBigInt(data, pos);
1075
+ if (bn === 0 || bLen > BigInt(data.length - (pos + bn)))
1076
+ return -1;
1077
+ const start = pos + bn;
1078
+ const end = start + Number(bLen);
1079
+ if (!isValidUTF8Slice(data, start, end))
1080
+ return -1;
1081
+ return end;
1082
+ }
953
1083
  if (wt === WireSubMsg) {
954
1084
  if (pos >= data.length)
955
1085
  return -1;
@@ -1047,109 +1177,243 @@ function validateUnknownMessageBytes(data, depth, limit = MaxNestingDepth) {
1047
1177
  }
1048
1178
  return true;
1049
1179
  }
1180
+ function isValidUTF8Slice(bytes, start, end) {
1181
+ let i = start;
1182
+ const end4 = end - 3;
1183
+ while (i < end4) {
1184
+ if (((bytes[i] | bytes[i + 1] | bytes[i + 2] | bytes[i + 3]) & 0x80) !== 0) {
1185
+ try {
1186
+ sharedTextDecoder.decode(bytes.subarray(i, end));
1187
+ return true;
1188
+ }
1189
+ catch {
1190
+ return false;
1191
+ }
1192
+ }
1193
+ i += 4;
1194
+ }
1195
+ while (i < end) {
1196
+ if (bytes[i] >= 0x80) {
1197
+ try {
1198
+ sharedTextDecoder.decode(bytes.subarray(i, end));
1199
+ return true;
1200
+ }
1201
+ catch {
1202
+ return false;
1203
+ }
1204
+ }
1205
+ i++;
1206
+ }
1207
+ return true;
1208
+ }
1050
1209
  /**
1051
1210
  * Validates an `omnibuf.v1.SchemaMeta` payload at `depth`.
1052
1211
  */
1053
- export function validateSchemaMetaBytes(data, depth, limit = MaxNestingDepth) {
1212
+ export function validateSchemaMetaBytes(data, depth, limit = MaxNestingDepth, start = 0, endLimit = data.length) {
1054
1213
  if (depth > limit)
1055
1214
  return false;
1056
- let pos = 0;
1057
- const n = data.length;
1215
+ let pos = start;
1216
+ const n = endLimit;
1058
1217
  while (pos < n) {
1059
- const [tag, tn] = decodeVarintBigInt(data, pos);
1060
- if (tn === 0 || tag >> 4n > 536870911n)
1061
- return false;
1062
- pos += tn;
1063
- const fnum = Number(tag >> 4n);
1064
- const wt = Number(tag & 0x0fn);
1218
+ let fnum = 0;
1219
+ let wt = 0;
1220
+ const tb = data[pos];
1221
+ if ((tb & 1) !== 0) {
1222
+ fnum = tb >>> 5;
1223
+ wt = (tb >>> 1) & 0x0f;
1224
+ pos += 1;
1225
+ }
1226
+ else if ((tb & 2) !== 0) {
1227
+ if (pos + 2 > n)
1228
+ return false;
1229
+ const u16 = (tb | (data[pos + 1] << 8)) >>> 2;
1230
+ fnum = u16 >>> 4;
1231
+ wt = u16 & 0x0f;
1232
+ pos += 2;
1233
+ }
1234
+ else {
1235
+ const [tag, tn] = decodeVarintBigInt(data, pos, n);
1236
+ if (tn === 0 || tag >> 4n > 536870911n)
1237
+ return false;
1238
+ pos += tn;
1239
+ fnum = Number(tag >> 4n);
1240
+ wt = Number(tag & 0x0fn);
1241
+ }
1065
1242
  switch (fnum) {
1066
1243
  case 1: {
1067
1244
  if (wt !== WireString || pos >= n)
1068
1245
  return false;
1069
- const [sLen, sn] = decodeVarintBigInt(data, pos);
1070
- if (sn === 0 || sLen > BigInt(n - (pos + sn)))
1071
- return false;
1072
- pos += sn;
1073
- const end = pos + Number(sLen);
1074
- try {
1075
- decodeUTF8(data, pos, end);
1246
+ let sLen = 0;
1247
+ const sb = data[pos];
1248
+ if ((sb & 1) !== 0) {
1249
+ sLen = sb >>> 1;
1250
+ pos += 1;
1076
1251
  }
1077
- catch {
1078
- return false;
1252
+ else {
1253
+ const [sl64, sn] = decodeVarintBigInt(data, pos, n);
1254
+ if (sn === 0 || sl64 > BigInt(n - (pos + sn)))
1255
+ return false;
1256
+ pos += sn;
1257
+ sLen = Number(sl64);
1079
1258
  }
1259
+ const end = pos + sLen;
1260
+ if (end > n || !isValidUTF8Slice(data, pos, end))
1261
+ return false;
1080
1262
  pos = end;
1081
1263
  break;
1082
1264
  }
1083
1265
  case 2: {
1084
1266
  if (wt !== WireMap || depth + 1 > limit || pos >= n)
1085
1267
  return false;
1086
- const [bLen, bn] = decodeVarintBigInt(data, pos);
1087
- if (bn === 0 || bLen < 3n || bLen > BigInt(n - (pos + bn)))
1268
+ let bLen = 0;
1269
+ const lb = data[pos];
1270
+ if ((lb & 1) !== 0) {
1271
+ bLen = lb >>> 1;
1272
+ pos += 1;
1273
+ }
1274
+ else if ((lb & 2) !== 0) {
1275
+ if (pos + 2 > n)
1276
+ return false;
1277
+ bLen = (lb | (data[pos + 1] << 8)) >>> 2;
1278
+ pos += 2;
1279
+ }
1280
+ else {
1281
+ const [bl64, bn] = decodeVarintBigInt(data, pos, n);
1282
+ if (bn === 0 || bl64 > BigInt(n - (pos + bn)))
1283
+ return false;
1284
+ pos += bn;
1285
+ bLen = Number(bl64);
1286
+ }
1287
+ const bodyEnd = pos + bLen;
1288
+ if (bLen < 3 || bodyEnd > n)
1088
1289
  return false;
1089
- const bodyEnd = pos + bn + Number(bLen);
1090
- const body = data.subarray(pos + bn, bodyEnd);
1091
- pos = bodyEnd;
1092
- const [keyWT, valWT, count, startP, ok] = parseMapHeader(body);
1290
+ const [keyWT, valWT, count, startP, ok] = parseMapHeader(data, pos, bodyEnd);
1093
1291
  if (!ok || keyWT !== WireUint || valWT !== WireString)
1094
1292
  return false;
1095
1293
  let p = startP;
1096
1294
  for (let i = 0; i < count; i++) {
1097
- const [k64, kn] = decodeVarintBigInt(body, p);
1098
- if (kn === 0 || k64 === 0n || k64 > 536870911n)
1295
+ if (p >= bodyEnd)
1099
1296
  return false;
1100
- p += kn;
1101
- const [sLen, sn] = decodeVarintBigInt(body, p);
1102
- if (sn === 0 || sLen > BigInt(body.length - (p + sn)))
1103
- return false;
1104
- p += sn;
1105
- const sEnd = p + Number(sLen);
1106
- try {
1107
- decodeUTF8(body, p, sEnd);
1297
+ let kNum = 0;
1298
+ const kb = data[p];
1299
+ if ((kb & 1) !== 0) {
1300
+ kNum = kb >>> 1;
1301
+ p += 1;
1302
+ }
1303
+ else {
1304
+ const [k64, kn] = decodeVarintBigInt(data, p, bodyEnd);
1305
+ if (kn === 0 || k64 === 0n || k64 > 536870911n)
1306
+ return false;
1307
+ p += kn;
1308
+ kNum = Number(k64);
1108
1309
  }
1109
- catch {
1310
+ if (kNum === 0 || kNum > 536870911 || p >= bodyEnd)
1110
1311
  return false;
1312
+ let sLen = 0;
1313
+ const sb = data[p];
1314
+ if ((sb & 1) !== 0) {
1315
+ sLen = sb >>> 1;
1316
+ p += 1;
1111
1317
  }
1318
+ else {
1319
+ const [sl64, sn] = decodeVarintBigInt(data, p, bodyEnd);
1320
+ if (sn === 0 || sl64 > BigInt(bodyEnd - (p + sn)))
1321
+ return false;
1322
+ p += sn;
1323
+ sLen = Number(sl64);
1324
+ }
1325
+ const sEnd = p + sLen;
1326
+ if (sEnd > bodyEnd || !isValidUTF8Slice(data, p, sEnd))
1327
+ return false;
1112
1328
  p = sEnd;
1113
1329
  }
1114
- if (p !== body.length)
1330
+ if (p !== bodyEnd)
1115
1331
  return false;
1332
+ pos = bodyEnd;
1116
1333
  break;
1117
1334
  }
1118
1335
  case 3: {
1119
1336
  if (wt !== WireMap || depth + 1 > limit || pos >= n)
1120
1337
  return false;
1121
- const [bLen, bn] = decodeVarintBigInt(data, pos);
1122
- if (bn === 0 || bLen < 3n || bLen > BigInt(n - (pos + bn)))
1338
+ let bLen = 0;
1339
+ const lb = data[pos];
1340
+ if ((lb & 1) !== 0) {
1341
+ bLen = lb >>> 1;
1342
+ pos += 1;
1343
+ }
1344
+ else if ((lb & 2) !== 0) {
1345
+ if (pos + 2 > n)
1346
+ return false;
1347
+ bLen = (lb | (data[pos + 1] << 8)) >>> 2;
1348
+ pos += 2;
1349
+ }
1350
+ else {
1351
+ const [bl64, bn] = decodeVarintBigInt(data, pos, n);
1352
+ if (bn === 0 || bl64 > BigInt(n - (pos + bn)))
1353
+ return false;
1354
+ pos += bn;
1355
+ bLen = Number(bl64);
1356
+ }
1357
+ const bodyEnd = pos + bLen;
1358
+ if (bLen < 3 || bodyEnd > n)
1123
1359
  return false;
1124
- const bodyEnd = pos + bn + Number(bLen);
1125
- const body = data.subarray(pos + bn, bodyEnd);
1126
- pos = bodyEnd;
1127
- const [keyWT, valWT, count, startP, ok] = parseMapHeader(body);
1360
+ const [keyWT, valWT, count, startP, ok] = parseMapHeader(data, pos, bodyEnd);
1128
1361
  if (!ok || keyWT !== WireUint || valWT !== WireSubMsg)
1129
1362
  return false;
1130
1363
  let p = startP;
1131
1364
  for (let i = 0; i < count; i++) {
1132
- const [k64, kn] = decodeVarintBigInt(body, p);
1133
- if (kn === 0 || k64 === 0n || k64 > 536870911n)
1365
+ if (p >= bodyEnd)
1134
1366
  return false;
1135
- p += kn;
1136
- const [cLen, cn] = decodeVarintBigInt(body, p);
1137
- if (cn === 0 || cLen > BigInt(body.length - (p + cn)))
1367
+ let kNum = 0;
1368
+ const kb = data[p];
1369
+ if ((kb & 1) !== 0) {
1370
+ kNum = kb >>> 1;
1371
+ p += 1;
1372
+ }
1373
+ else {
1374
+ const [k64, kn] = decodeVarintBigInt(data, p, bodyEnd);
1375
+ if (kn === 0 || k64 === 0n || k64 > 536870911n)
1376
+ return false;
1377
+ p += kn;
1378
+ kNum = Number(k64);
1379
+ }
1380
+ if (kNum === 0 || kNum > 536870911 || p >= bodyEnd)
1138
1381
  return false;
1139
- p += cn;
1140
- const cEnd = p + Number(cLen);
1141
- if (!validateSchemaMetaBytes(body.subarray(p, cEnd), depth + 2, limit))
1382
+ let cLen = 0;
1383
+ const cb = data[p];
1384
+ if ((cb & 1) !== 0) {
1385
+ cLen = cb >>> 1;
1386
+ p += 1;
1387
+ }
1388
+ else if ((cb & 2) !== 0) {
1389
+ if (p + 2 > bodyEnd)
1390
+ return false;
1391
+ cLen = (cb | (data[p + 1] << 8)) >>> 2;
1392
+ p += 2;
1393
+ }
1394
+ else {
1395
+ const [cl64, cn] = decodeVarintBigInt(data, p, bodyEnd);
1396
+ if (cn === 0 || cl64 > BigInt(bodyEnd - (p + cn)))
1397
+ return false;
1398
+ p += cn;
1399
+ cLen = Number(cl64);
1400
+ }
1401
+ const cEnd = p + cLen;
1402
+ if (cEnd > bodyEnd || !validateSchemaMetaBytes(data, depth + 2, limit, p, cEnd)) {
1142
1403
  return false;
1404
+ }
1143
1405
  p = cEnd;
1144
1406
  }
1145
- if (p !== body.length)
1407
+ if (p !== bodyEnd)
1146
1408
  return false;
1409
+ pos = bodyEnd;
1147
1410
  break;
1148
1411
  }
1149
1412
  default: {
1150
1413
  if (fnum === 0)
1151
1414
  return false;
1152
- const nextPos = validateUnknownValueAt(data, pos, wt, depth, limit);
1415
+ const sub = n === data.length ? data : data.subarray(0, n);
1416
+ const nextPos = validateUnknownValueAt(sub, pos, wt, depth, limit);
1153
1417
  if (nextPos < 0)
1154
1418
  return false;
1155
1419
  pos = nextPos;
@@ -1163,15 +1427,34 @@ export function validateSchemaMetaBytes(data, depth, limit = MaxNestingDepth) {
1163
1427
  * Validates a `Field #0` (`omnibuf.v1.SchemaMeta`) entry starting at value offset `pos`.
1164
1428
  * Returns the end offset after `Field #0`, or `-1` if invalid.
1165
1429
  */
1166
- export function validateField0At(packet, pos, wt, depth = 0, limit = MaxNestingDepth) {
1167
- if (wt !== WireSubMsg || pos < 0 || pos >= packet.length)
1168
- return -1;
1169
- const [bLen, bn] = decodeVarintBigInt(packet, pos);
1170
- if (bn === 0 || bLen > BigInt(packet.length - (pos + bn)))
1430
+ export function validateField0At(packet, pos, wt, depth = 0, limit = MaxNestingDepth, endLimit = packet.length) {
1431
+ if (wt !== WireSubMsg || pos < 0 || pos >= endLimit)
1171
1432
  return -1;
1433
+ let bLen = 0;
1434
+ let bn = 0;
1435
+ const lb = packet[pos];
1436
+ if ((lb & 1) !== 0) {
1437
+ bLen = lb >>> 1;
1438
+ bn = 1;
1439
+ }
1440
+ else if ((lb & 2) !== 0) {
1441
+ if (pos + 2 > endLimit)
1442
+ return -1;
1443
+ bLen = (lb | (packet[pos + 1] << 8)) >>> 2;
1444
+ bn = 2;
1445
+ }
1446
+ else {
1447
+ const [bl64, nBytes] = decodeVarintBigInt(packet, pos, endLimit);
1448
+ if (nBytes === 0 || bl64 > BigInt(endLimit - (pos + nBytes)))
1449
+ return -1;
1450
+ bLen = Number(bl64);
1451
+ bn = nBytes;
1452
+ }
1172
1453
  const start = pos + bn;
1173
- const end = start + Number(bLen);
1174
- if (!validateSchemaMetaBytes(packet.subarray(start, end), depth + 1, limit))
1454
+ const end = start + bLen;
1455
+ if (end > endLimit)
1456
+ return -1;
1457
+ if (!validateSchemaMetaBytes(packet, depth + 1, limit, start, end))
1175
1458
  return -1;
1176
1459
  return end;
1177
1460
  }
@@ -1249,6 +1532,71 @@ export function locateField(packet, targetField, expMask = 0xffff) {
1249
1532
  ok: true,
1250
1533
  };
1251
1534
  }
1535
+ /**
1536
+ * Scans top-level field headers of `packet` in a single pass and builds an `OpaqueDirectory`
1537
+ * for `O(1)` direct slice lookups on clean `Opaque` getters.
1538
+ */
1539
+ export function buildOpaqueDirectory(packet, maxDenseField, depth = 0) {
1540
+ const maxDense = Math.min(Math.max(maxDenseField, 0), 256);
1541
+ const dense = new Int32Array((maxDense + 1) << 2);
1542
+ if (depth > MaxNestingDepth) {
1543
+ return { valid: false, maxDense, dense };
1544
+ }
1545
+ let pos = 0;
1546
+ const n = packet.length;
1547
+ while (pos < n) {
1548
+ const fieldStart = pos;
1549
+ let fnum = 0;
1550
+ let wt = 0;
1551
+ const b0 = packet[pos];
1552
+ if ((b0 & 1) !== 0) {
1553
+ fnum = b0 >>> 5;
1554
+ wt = (b0 >>> 1) & 0x0f;
1555
+ pos += 1;
1556
+ }
1557
+ else if ((b0 & 2) !== 0) {
1558
+ if (pos + 2 > n)
1559
+ return { valid: false, maxDense, dense };
1560
+ const u16 = (b0 | (packet[pos + 1] << 8)) >>> 2;
1561
+ fnum = u16 >>> 4;
1562
+ wt = u16 & 0x0f;
1563
+ pos += 2;
1564
+ }
1565
+ else {
1566
+ const [tag, tn] = decodeVarintBigInt(packet, pos);
1567
+ if (tn === 0 || tag >> 4n > 536870911n) {
1568
+ return { valid: false, maxDense, dense };
1569
+ }
1570
+ fnum = Number(tag >> 4n);
1571
+ wt = Number(tag & 0x0fn);
1572
+ pos += tn;
1573
+ }
1574
+ if (fnum === 0) {
1575
+ const f0End = validateField0At(packet, pos, wt, depth);
1576
+ if (f0End < 0) {
1577
+ return { valid: false, maxDense, dense };
1578
+ }
1579
+ pos = f0End;
1580
+ continue;
1581
+ }
1582
+ const valPos = pos;
1583
+ const valEnd = skipValidatedValue(packet, pos, wt);
1584
+ if (valEnd < 0) {
1585
+ return { valid: false, maxDense, dense };
1586
+ }
1587
+ if (fnum <= maxDense) {
1588
+ const base = fnum << 2;
1589
+ const prevCount = dense[base + 3] >>> 4;
1590
+ const nextCount = prevCount === 0 ? 1 : 2;
1591
+ dense[base] = fieldStart;
1592
+ dense[base + 1] = valPos;
1593
+ dense[base + 2] = valEnd;
1594
+ dense[base + 3] = (nextCount << 4) | wt;
1595
+ }
1596
+ pos = valEnd;
1597
+ }
1598
+ return { valid: true, maxDense, dense };
1599
+ }
1252
1600
  /**
1253
1601
  * Scans `packet` starting at `pos` for the next occurrence of `targetField`.
1254
1602
  * Validates `wt === expWT` and `byteLen >= minLen`, returning the container body slice.