@bcts/dcbor 1.0.0-alpha.8 → 1.0.0-beta.0

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/index.d.cts CHANGED
@@ -1,5 +1,4 @@
1
1
  //#region src/map.d.ts
2
-
3
2
  interface MapEntry {
4
3
  readonly key: Cbor;
5
4
  readonly value: Cbor;
@@ -11,7 +10,7 @@ interface MapEntry {
11
10
  * encoded CBOR representation, ensuring deterministic encoding.
12
11
  */
13
12
  declare class CborMap {
14
- #private;
13
+ private _dict;
15
14
  /**
16
15
  * Creates a new, empty CBOR Map.
17
16
  * Optionally initializes from a JavaScript Map.
@@ -31,6 +30,7 @@ declare class CborMap {
31
30
  * Alias for set() to match Rust's insert() method.
32
31
  */
33
32
  insert<K extends CborInput, V extends CborInput>(key: K, value: V): void;
33
+ private _makeKey;
34
34
  /**
35
35
  * Get a value from the map, given a key.
36
36
  * Returns undefined if the key is not present in the map.
@@ -105,6 +105,10 @@ declare class CborMap {
105
105
  //#endregion
106
106
  //#region src/simple.d.ts
107
107
  /**
108
+ * Copyright © 2023-2026 Blockchain Commons, LLC
109
+ * Copyright © 2025-2026 Parity Technologies
110
+ *
111
+ *
108
112
  * CBOR Simple Values (Major Type 7).
109
113
  *
110
114
  * @module simple
@@ -148,14 +152,28 @@ declare const simpleName: (simple: Simple) => string;
148
152
  declare const isNaN: (simple: Simple) => boolean;
149
153
  //#endregion
150
154
  //#region src/tag.d.ts
155
+ /**
156
+ * Numeric tag value type alias.
157
+ *
158
+ * Mirrors Rust `pub type TagValue = u64`. Where Rust narrows to u64, TS
159
+ * accepts the broader `CborNumber` (`number | bigint`) since JavaScript
160
+ * has no native u64 — the runtime guards in `encodeVarInt` enforce the
161
+ * 0..=2^64-1 range.
162
+ */
163
+ type TagValue = CborNumber;
151
164
  /**
152
165
  * A CBOR tag with an optional name.
153
166
  *
154
167
  * Tags consist of a numeric value and an optional human-readable name.
168
+ *
169
+ * Note on equality: Rust derives `PartialEq` on `Tag` keyed on `value`
170
+ * only — two tags with the same value but different names compare equal.
171
+ * Use {@link tagsEqual} to mirror that behaviour from TypeScript; raw
172
+ * `===` on `Tag` objects compares by reference.
155
173
  */
156
174
  interface Tag {
157
175
  /** The numeric tag value */
158
- readonly value: CborNumber;
176
+ readonly value: TagValue;
159
177
  /** Optional human-readable name for the tag */
160
178
  readonly name?: string;
161
179
  }
@@ -172,7 +190,29 @@ interface Tag {
172
190
  * const customTag = createTag(12345, 'myCustomTag');
173
191
  * ```
174
192
  */
175
- declare const createTag: (value: CborNumber, name?: string) => Tag;
193
+ declare const createTag: (value: TagValue, name?: string) => Tag;
194
+ /**
195
+ * Create a Tag from just its numeric value, no name attached.
196
+ *
197
+ * Mirrors Rust's `Tag::with_value(v: TagValue)`.
198
+ */
199
+ declare const tagWithValue: (value: TagValue) => Tag;
200
+ /**
201
+ * Create a Tag with a static (string) name.
202
+ *
203
+ * In Rust this distinguishes `Tag::Static(&'static str)` from
204
+ * `Tag::Dynamic(String)`. TypeScript has no compile-time equivalent — both
205
+ * variants collapse to the same `{ value, name }` object — but the
206
+ * function name is preserved for API parity.
207
+ *
208
+ * Mirrors Rust's `Tag::with_static_name(v, name)`.
209
+ */
210
+ declare const tagWithStaticName: (value: TagValue, name: string) => Tag;
211
+ /**
212
+ * Compare two tags for equality. Mirrors Rust's `PartialEq for Tag`, which
213
+ * compares by `value` only and ignores the optional `name`.
214
+ */
215
+ declare const tagsEqual: (a: Tag, b: Tag) => boolean;
176
216
  //#endregion
177
217
  //#region src/byte-string.d.ts
178
218
  /**
@@ -202,7 +242,7 @@ declare const createTag: (value: CborNumber, name?: string) => Tag;
202
242
  * ```
203
243
  */
204
244
  declare class ByteString {
205
- #private;
245
+ private _data;
206
246
  /**
207
247
  * Creates a new `ByteString` from a Uint8Array or array of bytes.
208
248
  *
@@ -494,6 +534,15 @@ interface CborTaggedEncodable extends CborTagged {
494
534
  * @returns Tagged CBOR value
495
535
  */
496
536
  declare const createTaggedCbor: (encodable: CborTaggedEncodable) => Cbor;
537
+ /**
538
+ * Default `taggedCborData()` implementation — `taggedCbor().toData()`.
539
+ *
540
+ * Mirrors Rust's default `tagged_cbor_data()` impl on
541
+ * `CBORTaggedEncodable`. TypeScript interfaces don't carry method bodies,
542
+ * so this helper plays the role of the Rust trait default; concrete types
543
+ * call it from their own `taggedCborData()` if they don't need to override.
544
+ */
545
+ declare const taggedCborData: (encodable: CborTaggedEncodable) => Uint8Array;
497
546
  //#endregion
498
547
  //#region src/cbor-tagged-decodable.d.ts
499
548
  /**
@@ -634,6 +683,22 @@ declare const validateTag: (cbor: Cbor, expectedTags: Tag[]) => Tag;
634
683
  * @throws Error if the value is not tagged
635
684
  */
636
685
  declare const extractTaggedContent: (cbor: Cbor) => Cbor;
686
+ /**
687
+ * Default `fromTaggedCborData()` implementation — `decodeCbor(data)` then
688
+ * delegate to the decodable's `fromTaggedCbor()`.
689
+ *
690
+ * Mirrors Rust's default `from_tagged_cbor_data` impl on
691
+ * `CBORTaggedDecodable`.
692
+ */
693
+ declare function fromTaggedCborData<T>(decodable: CborTaggedDecodable<T>, data: Uint8Array): T;
694
+ /**
695
+ * Default `fromUntaggedCborData()` implementation — `decodeCbor(data)`
696
+ * then delegate to the decodable's `fromUntaggedCbor()`.
697
+ *
698
+ * Mirrors Rust's default `from_untagged_cbor_data` impl on
699
+ * `CBORTaggedDecodable`.
700
+ */
701
+ declare function fromUntaggedCborData<T>(decodable: CborTaggedDecodable<T>, data: Uint8Array): T;
637
702
  //#endregion
638
703
  //#region src/cbor-tagged-codable.d.ts
639
704
  /**
@@ -809,7 +874,20 @@ interface CborTagged {
809
874
  * ```
810
875
  */
811
876
  declare class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDecodable<CborDate> {
812
- #private;
877
+ /**
878
+ * Canonical timestamp in seconds since the Unix epoch as a JS `number`
879
+ * (`f64`). dCBOR encodes Date (tag 1) as a numeric value in seconds, so
880
+ * keeping `_seconds` as the source of truth avoids the millisecond-only
881
+ * round-trip precision loss that going through a JS `Date` instance
882
+ * introduced in earlier versions of this port.
883
+ *
884
+ * f64 still bounds the achievable precision (~16 decimal digits, so
885
+ * roughly microseconds for current epoch values); Rust's
886
+ * `chrono::DateTime<Utc>` retains nanoseconds in memory but encodes
887
+ * to the same f64 over the wire, so the *encode/decode round-trip* is
888
+ * byte-identical.
889
+ */
890
+ private _seconds;
813
891
  /**
814
892
  * Creates a new `CborDate` from the given JavaScript `Date`.
815
893
  *
@@ -1136,17 +1214,259 @@ declare class CborDate implements CborTagged, CborTaggedEncodable, CborTaggedDec
1136
1214
  private constructor();
1137
1215
  }
1138
1216
  //#endregion
1217
+ //#region src/error.d.ts
1218
+ /**
1219
+ * A comprehensive set of errors that can occur during CBOR encoding and
1220
+ * decoding operations with special focus on enforcing the deterministic
1221
+ * encoding rules specified in the dCBOR specification.
1222
+ *
1223
+ * The dCBOR implementation validates all encoded CBOR against the
1224
+ * deterministic encoding requirements of RFC 8949 §4.2.1, plus additional
1225
+ * constraints defined in the dCBOR application profile. These errors represent
1226
+ * all the possible validation failures and decoding issues that can arise.
1227
+ */
1228
+ type Error =
1229
+ /**
1230
+ * The CBOR data ended prematurely during decoding, before a complete CBOR
1231
+ * item could be decoded. This typically happens when a CBOR item's
1232
+ * structure indicates more data than is actually present.
1233
+ */
1234
+ {
1235
+ readonly type: "Underrun";
1236
+ }
1237
+ /**
1238
+ * An unsupported or invalid value was encountered in a CBOR header byte.
1239
+ * The parameter contains the unsupported header byte value.
1240
+ * This can occur when decoding CBOR that uses unsupported features or is
1241
+ * malformed.
1242
+ */
1243
+ | {
1244
+ readonly type: "UnsupportedHeaderValue";
1245
+ readonly value: number;
1246
+ }
1247
+ /**
1248
+ * A CBOR numeric value was encoded in a non-canonical form, violating the
1249
+ * deterministic encoding requirement of dCBOR (per Section 2.3 of the
1250
+ * dCBOR specification).
1251
+ *
1252
+ * This error is triggered when:
1253
+ * - An integer is not encoded in its shortest possible form
1254
+ * - A floating point value that could be represented as an integer was not
1255
+ * reduced
1256
+ * - A NaN value was not encoded in its canonical form (`f97e00`)
1257
+ */
1258
+ | {
1259
+ readonly type: "NonCanonicalNumeric";
1260
+ }
1261
+ /**
1262
+ * An invalid CBOR simple value was encountered during decoding.
1263
+ *
1264
+ * Per Section 2.4 of the dCBOR specification, only `false`, `true`,
1265
+ * `null`, and floating point values are valid simple values in dCBOR.
1266
+ * All other major type 7 values are invalid.
1267
+ */
1268
+ | {
1269
+ readonly type: "InvalidSimpleValue";
1270
+ }
1271
+ /**
1272
+ * A CBOR text string was not valid UTF-8. The parameter contains the
1273
+ * specific error message.
1274
+ *
1275
+ * All CBOR text strings (major type 3) must be valid UTF-8 per RFC 8949.
1276
+ */
1277
+ | {
1278
+ readonly type: "InvalidString";
1279
+ readonly message: string;
1280
+ }
1281
+ /**
1282
+ * A CBOR text string was not encoded in Unicode Canonical Normalization
1283
+ * Form C (NFC).
1284
+ *
1285
+ * Per Section 2.5 of the dCBOR specification, all text strings must be in
1286
+ * NFC form, and decoders must reject any encoded text strings that are
1287
+ * not in NFC.
1288
+ */
1289
+ | {
1290
+ readonly type: "NonCanonicalString";
1291
+ }
1292
+ /**
1293
+ * The decoded CBOR item didn't consume all input data.
1294
+ * The parameter contains the number of unused bytes.
1295
+ *
1296
+ * This error occurs when decoding functions expect exactly one CBOR item
1297
+ * but the input contains additional data after a valid CBOR item.
1298
+ */
1299
+ | {
1300
+ readonly type: "UnusedData";
1301
+ readonly count: number;
1302
+ }
1303
+ /**
1304
+ * The keys in a decoded CBOR map were not in the canonical lexicographic order
1305
+ * of their encoding.
1306
+ *
1307
+ * Per the CDE specification and Section 2.1 of dCBOR, map keys must be in
1308
+ * ascending lexicographic order of their encoded representation for
1309
+ * deterministic encoding.
1310
+ */
1311
+ | {
1312
+ readonly type: "MisorderedMapKey";
1313
+ }
1314
+ /**
1315
+ * A decoded CBOR map contains duplicate keys, which is invalid.
1316
+ *
1317
+ * Per Section 2.2 of the dCBOR specification, CBOR maps must not contain
1318
+ * duplicate keys, and decoders must reject encoded maps with duplicate
1319
+ * keys.
1320
+ */
1321
+ | {
1322
+ readonly type: "DuplicateMapKey";
1323
+ }
1324
+ /**
1325
+ * A requested key was not found in a CBOR map during data extraction.
1326
+ */
1327
+ | {
1328
+ readonly type: "MissingMapKey";
1329
+ }
1330
+ /**
1331
+ * A CBOR numeric value could not be represented in the specified target
1332
+ * numeric type.
1333
+ *
1334
+ * This occurs when attempting to convert a CBOR number to a numeric
1335
+ * type that is too small to represent the value without loss of
1336
+ * precision.
1337
+ */
1338
+ | {
1339
+ readonly type: "OutOfRange";
1340
+ }
1341
+ /**
1342
+ * The CBOR value is not of the expected type for a conversion or
1343
+ * operation.
1344
+ *
1345
+ * This occurs when attempting to convert a CBOR value to a type that
1346
+ * doesn't match the actual CBOR item's type (e.g., trying to convert a
1347
+ * string to an integer).
1348
+ */
1349
+ | {
1350
+ readonly type: "WrongType";
1351
+ }
1352
+ /**
1353
+ * The CBOR tagged value had a different tag than expected.
1354
+ * Contains the expected tag and the actual tag found.
1355
+ */
1356
+ | {
1357
+ readonly type: "WrongTag";
1358
+ readonly expected: Tag;
1359
+ readonly actual: Tag;
1360
+ }
1361
+ /**
1362
+ * Invalid UTF‑8 in a text string.
1363
+ */
1364
+ | {
1365
+ readonly type: "InvalidUtf8";
1366
+ readonly message: string;
1367
+ }
1368
+ /**
1369
+ * Invalid ISO 8601 date format.
1370
+ */
1371
+ | {
1372
+ readonly type: "InvalidDate";
1373
+ readonly message: string;
1374
+ }
1375
+ /**
1376
+ * Custom error message.
1377
+ */
1378
+ | {
1379
+ readonly type: "Custom";
1380
+ readonly message: string;
1381
+ };
1382
+ /**
1383
+ * Create a custom error with a message.
1384
+ *
1385
+ * Matches Rust's `Error::msg()` method.
1386
+ */
1387
+ declare const errorMsg: (message: string) => Error;
1388
+ /**
1389
+ * Convert an Error to a display string.
1390
+ *
1391
+ * Matches Rust's `Display` trait / `to_string()` method.
1392
+ */
1393
+ declare const errorToString: (error: Error) => string;
1394
+ /**
1395
+ * Result type matching Rust's `Result<T, Error>`.
1396
+ *
1397
+ * In TypeScript, we use a discriminated union for Result instead of
1398
+ * try/catch for better type safety and Rust compatibility.
1399
+ */
1400
+ type Result<T> = {
1401
+ ok: true;
1402
+ value: T;
1403
+ } | {
1404
+ ok: false;
1405
+ error: Error;
1406
+ };
1407
+ /**
1408
+ * Create a successful Result.
1409
+ */
1410
+ declare const Ok: <T>(value: T) => Result<T>;
1411
+ /**
1412
+ * Create a failed Result.
1413
+ */
1414
+ declare const Err: <T>(error: Error) => Result<T>;
1415
+ /**
1416
+ * Typed error class for all CBOR-related errors.
1417
+ *
1418
+ * Wraps the discriminated union Error type in a JavaScript Error object
1419
+ * for proper error handling with stack traces.
1420
+ *
1421
+ * @example
1422
+ * ```typescript
1423
+ * throw new CborError({ type: 'Underrun' });
1424
+ * throw new CborError({ type: 'WrongTag', expected: tag1, actual: tag2 });
1425
+ * ```
1426
+ */
1427
+ declare class CborError extends Error {
1428
+ /**
1429
+ * The structured error information.
1430
+ */
1431
+ readonly errorType: Error;
1432
+ /**
1433
+ * Create a new CborError.
1434
+ *
1435
+ * @param errorType - The discriminated union error type
1436
+ * @param message - Optional custom message (defaults to errorToString(errorType))
1437
+ */
1438
+ constructor(errorType: Error, message?: string);
1439
+ /**
1440
+ * Check if an error is a CborError.
1441
+ *
1442
+ * @param error - Error to check
1443
+ * @returns True if error is a CborError
1444
+ */
1445
+ static isCborError(error: unknown): error is CborError;
1446
+ }
1447
+ //#endregion
1139
1448
  //#region src/tags-store.d.ts
1449
+ /**
1450
+ * Result type for summarizer functions, matching Rust's Result<String, Error>.
1451
+ */
1452
+ type SummarizerResult = {
1453
+ readonly ok: true;
1454
+ readonly value: string;
1455
+ } | {
1456
+ readonly ok: false;
1457
+ readonly error: Error;
1458
+ };
1140
1459
  /**
1141
1460
  * Function type for custom CBOR value summarizers.
1142
1461
  *
1143
1462
  * Summarizers provide custom string representations for tagged values.
1463
+ * Returns a Result type matching Rust's `Result<String, Error>`.
1144
1464
  *
1145
1465
  * @param cbor - The CBOR value to summarize
1146
1466
  * @param flat - If true, produce single-line output
1147
- * @returns String summary of the value
1467
+ * @returns Result with summary string on success, or error on failure
1148
1468
  */
1149
- type CborSummarizer = (cbor: Cbor, flat: boolean) => string;
1469
+ type CborSummarizer = (cbor: Cbor, flat: boolean) => SummarizerResult;
1150
1470
  /**
1151
1471
  * Interface for tag store operations.
1152
1472
  */
@@ -1200,12 +1520,20 @@ interface TagsStoreTrait {
1200
1520
  * Stores tags with their names and optional summarizer functions.
1201
1521
  */
1202
1522
  declare class TagsStore implements TagsStoreTrait {
1203
- #private;
1523
+ private readonly _tagsByValue;
1524
+ private readonly _tagsByName;
1525
+ private readonly _summarizers;
1204
1526
  constructor();
1205
1527
  /**
1206
1528
  * Insert a tag into the registry.
1207
1529
  *
1208
- * @param tag - The tag to register
1530
+ * Matches Rust's TagsStore::insert() behavior:
1531
+ * - Throws if the tag name is undefined or empty
1532
+ * - Throws if a tag with the same value exists with a different name
1533
+ * - Allows re-registering the same tag value with the same name
1534
+ *
1535
+ * @param tag - The tag to register (must have a non-empty name)
1536
+ * @throws Error if tag has no name, empty name, or conflicts with existing registration
1209
1537
  *
1210
1538
  * @example
1211
1539
  * ```typescript
@@ -1245,13 +1573,6 @@ declare class TagsStore implements TagsStoreTrait {
1245
1573
  * ```
1246
1574
  */
1247
1575
  setSummarizer(tagValue: CborNumber, summarizer: CborSummarizer): void;
1248
- /**
1249
- * Remove a tag from the registry.
1250
- *
1251
- * @param tagValue - The numeric tag value to remove
1252
- * @returns true if a tag was removed, false otherwise
1253
- */
1254
- remove(tagValue: CborNumber): boolean;
1255
1576
  assignedNameForTag(tag: Tag): string | undefined;
1256
1577
  nameForTag(tag: Tag): string;
1257
1578
  tagForValue(value: CborNumber): Tag | undefined;
@@ -1259,21 +1580,12 @@ declare class TagsStore implements TagsStoreTrait {
1259
1580
  nameForValue(value: CborNumber): string;
1260
1581
  summarizer(tag: CborNumber): CborSummarizer | undefined;
1261
1582
  /**
1262
- * Get all registered tags.
1583
+ * Create a string key for a numeric tag value.
1584
+ * Handles both number and bigint types.
1263
1585
  *
1264
- * @returns Array of all registered tags
1265
- */
1266
- getAllTags(): Tag[];
1267
- /**
1268
- * Clear all registered tags and summarizers.
1586
+ * @private
1269
1587
  */
1270
- clear(): void;
1271
- /**
1272
- * Get the number of registered tags.
1273
- *
1274
- * @returns Number of tags in the registry
1275
- */
1276
- get size(): number;
1588
+ private _valueKey;
1277
1589
  }
1278
1590
  /**
1279
1591
  * Get the global tags store instance.
@@ -1306,7 +1618,7 @@ declare enum EdgeType {
1306
1618
  /** Value within a map */
1307
1619
  MapValue = "map_value",
1308
1620
  /** Content of a tagged value */
1309
- TaggedContent = "tagged_content",
1621
+ TaggedContent = "tagged_content"
1310
1622
  }
1311
1623
  /**
1312
1624
  * Discriminated union for edge type information.
@@ -1375,121 +1687,55 @@ declare const asSingle: (element: WalkElement) => Cbor | undefined;
1375
1687
  /**
1376
1688
  * Returns the key-value pair if this is a 'keyvalue' variant.
1377
1689
  *
1378
- * @param element - The walk element to extract from
1379
- * @returns Tuple of [key, value] if keyvalue, undefined otherwise
1380
- *
1381
- * @example
1382
- * ```typescript
1383
- * const element: WalkElement = { type: 'keyvalue', key: keyValue, value: valValue };
1384
- * const pair = asKeyValue(element); // Returns [keyValue, valValue]
1385
- * ```
1386
- */
1387
- declare const asKeyValue: (element: WalkElement) => [Cbor, Cbor] | undefined;
1388
- /**
1389
- * Visitor function type with state threading.
1390
- *
1391
- * @template State - The type of state passed through the traversal
1392
- * @param element - The element being visited
1393
- * @param level - The depth level in the tree (0 = root)
1394
- * @param edge - Information about the edge leading to this element
1395
- * @param state - Current state value
1396
- * @returns Tuple of [newState, stopDescent] where:
1397
- * - newState: The updated state to pass to subsequent visits
1398
- * - stopDescent: If true, don't descend into children of this element
1399
- */
1400
- type Visitor<State> = (element: WalkElement, level: number, edge: EdgeTypeVariant, state: State) => [State, boolean];
1401
- /**
1402
- * Helper: Count all elements in a CBOR tree.
1403
- *
1404
- * @param cbor - The CBOR value to count
1405
- * @returns Total number of elements visited
1406
- *
1407
- * @example
1408
- * ```typescript
1409
- * const structure = cbor([1, 2, [3, 4]]);
1410
- * const count = countElements(structure);
1411
- * console.log(count); // 6 (array, 1, 2, inner array, 3, 4)
1412
- * ```
1413
- */
1414
- declare const countElements: (cbor: Cbor) => number;
1415
- /**
1416
- * Helper: Collect all elements at a specific depth level.
1417
- *
1418
- * @param cbor - The CBOR value to traverse
1419
- * @param targetLevel - The depth level to collect (0 = root)
1420
- * @returns Array of CBOR values at the target level
1421
- *
1422
- * @example
1423
- * ```typescript
1424
- * const structure = cbor([[1, 2], [3, 4]]);
1425
- * const level1 = collectAtLevel(structure, 1);
1426
- * // Returns: [[1, 2], [3, 4]]
1427
- * const level2 = collectAtLevel(structure, 2);
1428
- * // Returns: [1, 2, 3, 4]
1429
- * ```
1430
- */
1431
- declare const collectAtLevel: (cbor: Cbor, targetLevel: number) => Cbor[];
1432
- /**
1433
- * Helper: Find first element matching a predicate.
1434
- *
1435
- * @template T - Type of extracted value
1436
- * @param cbor - The CBOR value to search
1437
- * @param predicate - Function to test each element
1438
- * @returns First matching element, or undefined if not found
1439
- *
1440
- * @example
1441
- * ```typescript
1442
- * const structure = cbor({ users: [
1443
- * { name: 'Alice', age: 30 },
1444
- * { name: 'Bob', age: 25 }
1445
- * ]});
1446
- *
1447
- * const bob = findFirst(structure, (element) => {
1448
- * if (element.type === 'single' &&
1449
- * element.cbor.type === MajorType.Text &&
1450
- * element.cbor.value === 'Bob') {
1451
- * return true;
1452
- * }
1453
- * return false;
1454
- * });
1455
- * ```
1456
- */
1457
- declare const findFirst: (cbor: Cbor, predicate: (element: WalkElement) => boolean) => Cbor | undefined;
1458
- /**
1459
- * Helper: Collect all text strings in a CBOR tree.
1460
- *
1461
- * @param cbor - The CBOR value to traverse
1462
- * @returns Array of all text string values found
1690
+ * @param element - The walk element to extract from
1691
+ * @returns Tuple of [key, value] if keyvalue, undefined otherwise
1463
1692
  *
1464
1693
  * @example
1465
1694
  * ```typescript
1466
- * const doc = cbor({
1467
- * title: 'Document',
1468
- * tags: ['urgent', 'draft'],
1469
- * author: { name: 'Alice' }
1470
- * });
1471
- *
1472
- * const texts = collectAllText(doc);
1473
- * // Returns: ['Document', 'urgent', 'draft', 'Alice']
1695
+ * const element: WalkElement = { type: 'keyvalue', key: keyValue, value: valValue };
1696
+ * const pair = asKeyValue(element); // Returns [keyValue, valValue]
1474
1697
  * ```
1475
1698
  */
1476
- declare const collectAllText: (cbor: Cbor) => string[];
1699
+ declare const asKeyValue: (element: WalkElement) => [Cbor, Cbor] | undefined;
1700
+ /**
1701
+ * Visitor function type.
1702
+ *
1703
+ * @template State - The type of state passed into each visit
1704
+ * @param element - The element being visited
1705
+ * @param level - The depth level in the tree (0 = root)
1706
+ * @param edge - Information about the edge leading to this element
1707
+ * @param state - The state value cloned from the parent visit
1708
+ * @returns Tuple of [newState, stopDescent] where:
1709
+ * - newState: The state to pass into descendants of this element. Each
1710
+ * descendant receives an independent clone of `newState`; sibling
1711
+ * subtrees do *not* see each other's mutations.
1712
+ * - stopDescent: If true, do not descend into children of this element.
1713
+ */
1714
+ type Visitor<State> = (element: WalkElement, level: number, edge: EdgeTypeVariant, state: State) => [State, boolean];
1477
1715
  /**
1478
- * Helper: Get the maximum depth of a CBOR tree.
1716
+ * Walk a CBOR tree, visiting each element with a visitor function.
1479
1717
  *
1480
- * @param cbor - The CBOR value to measure
1481
- * @returns Maximum depth (0 for leaf values, 1+ for containers)
1718
+ * The visitor function is called for each element in the tree, in depth-first order.
1719
+ * State semantics mirror Rust's `walk_internal`:
1482
1720
  *
1483
- * @example
1484
- * ```typescript
1485
- * const flat = cbor([1, 2, 3]);
1486
- * console.log(maxDepth(flat)); // 1
1721
+ * - The visitor's returned `newState` propagates **down** to descendants of
1722
+ * the just-visited node only.
1723
+ * - Sibling subtrees each receive an independent clone of the parent's
1724
+ * post-visit state, so accumulating mutations in one subtree never leak
1725
+ * into a sibling.
1726
+ * - State changes do not propagate **up**: the public `walk` returns `void`.
1487
1727
  *
1488
- * const nested = cbor([[[1]]]);
1489
- * console.log(maxDepth(nested)); // 3
1490
- * ```
1728
+ * For maps, the visitor is called with:
1729
+ * 1. A 'keyvalue' element containing both key and value
1730
+ * 2. The key individually (if descent wasn't stopped)
1731
+ * 3. The value individually (if descent wasn't stopped)
1732
+ *
1733
+ * @template State - The type of state to pass into each visit
1734
+ * @param cbor - The CBOR value to traverse
1735
+ * @param initialState - Initial state value
1736
+ * @param visitor - Function to call for each element
1491
1737
  */
1492
- declare const maxDepth: (cbor: Cbor) => number;
1738
+ declare const walk: <State>(cbor: Cbor, initialState: State, visitor: Visitor<State>) => void;
1493
1739
  //#endregion
1494
1740
  //#region src/cbor.d.ts
1495
1741
  declare const MajorType: {
@@ -1671,7 +1917,7 @@ interface CborMethods {
1671
1917
  * @param initialState - Initial state for the visitor
1672
1918
  * @param visitor - Visitor function called for each element
1673
1919
  */
1674
- walk<State>(initialState: State, visitor: Visitor<State>): State;
1920
+ walk<State>(initialState: State, visitor: Visitor<State>): void;
1675
1921
  /**
1676
1922
  * Validate that value has one of the expected tags.
1677
1923
  * @param expectedTags - Array of expected tag values
@@ -1684,6 +1930,17 @@ interface CborMethods {
1684
1930
  untagged(): Cbor;
1685
1931
  }
1686
1932
  type Cbor = (CborUnsignedType | CborNegativeType | CborByteStringType | CborTextType | CborArrayType | CborMapType | CborTaggedType | CborSimpleType) & CborMethods;
1933
+ /**
1934
+ * Structural CBOR value equality.
1935
+ *
1936
+ * Mirrors Rust's `derive(PartialEq) for CBOR`. dCBOR encoding is
1937
+ * deterministic, so two CBOR values are equal iff they encode to the
1938
+ * same byte sequence — this is the simplest correct comparator.
1939
+ *
1940
+ * Use this rather than `===` (which compares JS object references) when
1941
+ * you need value equality across two `Cbor` instances built independently.
1942
+ */
1943
+ declare const cborEquals: (a: Cbor, b: Cbor) => boolean;
1687
1944
  /**
1688
1945
  * Convert any value to a CBOR representation.
1689
1946
  * Matches Rust's `From` trait implementations for CBOR.
@@ -1697,6 +1954,10 @@ declare const cborData: (value: CborInput) => Uint8Array;
1697
1954
  declare const toByteString: (data: Uint8Array) => Cbor;
1698
1955
  declare const toByteStringFromHex: (hex: string) => Cbor;
1699
1956
  declare const toTaggedValue: (tag: CborNumber | Tag, item: CborInput) => Cbor;
1957
+ declare const cborFalse: () => Cbor;
1958
+ declare const cborTrue: () => Cbor;
1959
+ declare const cborNull: () => Cbor;
1960
+ declare const cborNaN: () => Cbor;
1700
1961
  /**
1701
1962
  * CBOR constants and helper methods.
1702
1963
  *
@@ -1793,7 +2054,7 @@ declare function decodeCbor(data: Uint8Array): Cbor;
1793
2054
  * ```
1794
2055
  */
1795
2056
  declare class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSet> {
1796
- #private;
2057
+ private readonly _map;
1797
2058
  constructor();
1798
2059
  /**
1799
2060
  * Create CborSet from array.
@@ -1846,6 +2107,20 @@ declare class CborSet implements CborTaggedEncodable, CborTaggedDecodable<CborSe
1846
2107
  * ```
1847
2108
  */
1848
2109
  insert(value: CborInput): void;
2110
+ /**
2111
+ * Insert an element into the set, requiring it to be strictly greater
2112
+ * (in canonical CBOR-encoded byte order) than every previously-inserted
2113
+ * element. Used by the decoder to reject misordered or duplicate
2114
+ * elements in tag-258 set encodings.
2115
+ *
2116
+ * Mirrors Rust `Set::insert_next` (`pub(crate)`); exposed here because
2117
+ * TypeScript doesn't have a crate-private visibility level.
2118
+ *
2119
+ * @throws CborError of type `MisorderedMap` if `value` would not preserve
2120
+ * strict ascending CBOR-byte order, or `DuplicateMapKey` for an exact
2121
+ * repeat.
2122
+ */
2123
+ insertNext(value: CborInput): void;
1849
2124
  /**
1850
2125
  * Check if set contains an element.
1851
2126
  *
@@ -2079,6 +2354,16 @@ declare const TAG_POSITIVE_BIGNUM = 2;
2079
2354
  * Tag 3: Negative bignum (signed arbitrary-precision integer)
2080
2355
  */
2081
2356
  declare const TAG_NEGATIVE_BIGNUM = 3;
2357
+ /**
2358
+ * Name for tag 2 (positive bignum).
2359
+ * Matches Rust's `TAG_NAME_POSITIVE_BIGNUM`.
2360
+ */
2361
+ declare const TAG_NAME_POSITIVE_BIGNUM = "positive-bignum";
2362
+ /**
2363
+ * Name for tag 3 (negative bignum).
2364
+ * Matches Rust's `TAG_NAME_NEGATIVE_BIGNUM`.
2365
+ */
2366
+ declare const TAG_NAME_NEGATIVE_BIGNUM = "negative-bignum";
2082
2367
  /**
2083
2368
  * Tag 4: Decimal fraction [exponent, mantissa]
2084
2369
  */
@@ -2218,9 +2503,14 @@ interface DiagFormatOpts {
2218
2503
  flat?: boolean;
2219
2504
  /**
2220
2505
  * Tag store to use for tag name resolution.
2221
- * - TagsStore instance: Use specific store
2222
- * - 'global': Use global singleton store
2223
- * - 'none': Don't use any store (show tag numbers)
2506
+ *
2507
+ * Mirrors Rust's `TagsStoreOpt<'a>` enum (`Custom(&'a dyn TagsStoreTrait)`,
2508
+ * `Global`, `None`). The TS port models the same three-way choice as a
2509
+ * string-literal union — semantically equivalent, just stringly-typed.
2510
+ *
2511
+ * - `TagsStore` instance: use this specific store (Rust `Custom`)
2512
+ * - `'global'`: use global singleton store (Rust `Global`)
2513
+ * - `'none'`: don't resolve names; print bare tag numbers (Rust `None`)
2224
2514
  *
2225
2515
  * @default 'global'
2226
2516
  */
@@ -2255,6 +2545,54 @@ interface DiagFormatOpts {
2255
2545
  * ```
2256
2546
  */
2257
2547
  declare function diagnosticOpt(cbor: Cbor, opts?: DiagFormatOpts): string;
2548
+ /**
2549
+ * Format CBOR value as standard diagnostic notation.
2550
+ *
2551
+ * @param cbor - CBOR value to format
2552
+ * @returns Diagnostic string (pretty-printed with multiple lines for complex structures)
2553
+ *
2554
+ * @example
2555
+ * ```typescript
2556
+ * const value = cbor([1, 2, 3]);
2557
+ * console.log(diagnostic(value));
2558
+ * // For simple arrays: "[1, 2, 3]"
2559
+ * // For nested structures: multi-line formatted output
2560
+ * ```
2561
+ */
2562
+ declare function diagnostic(cbor: Cbor): string;
2563
+ /**
2564
+ * Format CBOR value with tag name annotations.
2565
+ *
2566
+ * Tagged values are displayed with their registered names instead of numeric tags.
2567
+ *
2568
+ * @param cbor - CBOR value to format
2569
+ * @returns Annotated diagnostic string (pretty-printed format)
2570
+ *
2571
+ * @example
2572
+ * ```typescript
2573
+ * const date = CborDate.now().taggedCbor();
2574
+ * console.log(diagnosticAnnotated(date));
2575
+ * // date(1234567890) instead of 1(1234567890)
2576
+ * ```
2577
+ */
2578
+ declare function diagnosticAnnotated(cbor: Cbor): string;
2579
+ /**
2580
+ * Format CBOR value as flat (single-line) diagnostic notation.
2581
+ *
2582
+ * Arrays and maps are formatted without line breaks.
2583
+ *
2584
+ * @param cbor - CBOR value to format
2585
+ * @returns Flat diagnostic string
2586
+ *
2587
+ * @example
2588
+ * ```typescript
2589
+ * const nested = cbor([[1, 2], [3, 4]]);
2590
+ * console.log(diagnosticFlat(nested));
2591
+ * // "[[1, 2], [3, 4]]"
2592
+ * ```
2593
+ */
2594
+ declare function diagnosticFlat(cbor: Cbor): string;
2595
+ declare function diagnosticFlat(element: WalkElement): string;
2258
2596
  /**
2259
2597
  * Format CBOR value using custom summarizers for tagged values.
2260
2598
  *
@@ -2290,8 +2628,22 @@ interface HexFormatOpts {
2290
2628
  declare const bytesToHex: (bytes: Uint8Array) => string;
2291
2629
  /**
2292
2630
  * Convert hex string to bytes.
2631
+ *
2632
+ * **Whitespace tolerance.** This implementation strips ASCII whitespace
2633
+ * before decoding so users can paste annotated hex dumps directly. Rust's
2634
+ * `hex::decode` is strict and panics on any whitespace. This is a
2635
+ * deliberate TS-side ergonomic divergence — callers who need strict
2636
+ * Rust-compatible parsing should validate the input first (e.g.
2637
+ * `if (/\s/.test(s)) throw …`).
2293
2638
  */
2294
2639
  declare const hexToBytes: (hexString: string) => Uint8Array;
2640
+ /**
2641
+ * Returns the encoded hexadecimal representation of CBOR.
2642
+ *
2643
+ * @param cbor - CBOR value to convert
2644
+ * @returns Hex string
2645
+ */
2646
+ declare const hex: (cbor: Cbor) => string;
2295
2647
  /**
2296
2648
  * Returns the encoded hexadecimal representation of CBOR with options.
2297
2649
  *
@@ -2304,6 +2656,14 @@ declare const hexToBytes: (hexString: string) => Uint8Array;
2304
2656
  * @returns Hex string (possibly annotated)
2305
2657
  */
2306
2658
  declare const hexOpt: (cbor: Cbor, opts?: HexFormatOpts) => string;
2659
+ /**
2660
+ * Returns the encoded hexadecimal representation of CBOR, with annotations.
2661
+ *
2662
+ * @param cbor - CBOR value to convert
2663
+ * @param tagsStore - Optional tags store for tag name resolution
2664
+ * @returns Annotated hex string
2665
+ */
2666
+ declare const hexAnnotated: (cbor: Cbor, tagsStore?: TagsStore) => string;
2307
2667
  //#endregion
2308
2668
  //#region src/cbor-codable.d.ts
2309
2669
  /**
@@ -2453,221 +2813,144 @@ interface CborDecodable<T> {
2453
2813
  */
2454
2814
  interface CborCodable<T> extends CborEncodable, CborDecodable<T> {}
2455
2815
  //#endregion
2456
- //#region src/error.d.ts
2816
+ //#region src/bignum.d.ts
2457
2817
  /**
2458
- * A comprehensive set of errors that can occur during CBOR encoding and
2459
- * decoding operations with special focus on enforcing the deterministic
2460
- * encoding rules specified in the dCBOR specification.
2818
+ * Encode a non-negative bigint as a CBOR tag 2 (positive bignum).
2461
2819
  *
2462
- * The dCBOR implementation validates all encoded CBOR against the
2463
- * deterministic encoding requirements of RFC 8949 §4.2.1, plus additional
2464
- * constraints defined in the dCBOR application profile. These errors represent
2465
- * all the possible validation failures and decoding issues that can arise.
2466
- */
2467
- type Error =
2468
- /**
2469
- * The CBOR data ended prematurely during decoding, before a complete CBOR
2470
- * item could be decoded. This typically happens when a CBOR item's
2471
- * structure indicates more data than is actually present.
2820
+ * Matches Rust's `From<BigUint> for CBOR`.
2821
+ *
2822
+ * The value is always encoded as a bignum regardless of size.
2823
+ * Zero is encoded as tag 2 with an empty byte string.
2824
+ *
2825
+ * @param value - A non-negative bigint (must be >= 0n)
2826
+ * @returns CBOR tagged value
2827
+ * @throws CborError with type OutOfRange if value is negative
2472
2828
  */
2473
- {
2474
- readonly type: "Underrun";
2475
- }
2476
- /**
2477
- * An unsupported or invalid value was encountered in a CBOR header byte.
2478
- * The parameter contains the unsupported header byte value.
2479
- * This can occur when decoding CBOR that uses unsupported features or is
2480
- * malformed.
2481
- */ | {
2482
- readonly type: "UnsupportedHeaderValue";
2483
- readonly value: number;
2484
- }
2829
+ declare function biguintToCbor(value: bigint): Cbor;
2485
2830
  /**
2486
- * A CBOR numeric value was encoded in a non-canonical form, violating the
2487
- * deterministic encoding requirement of dCBOR (per Section 2.3 of the
2488
- * dCBOR specification).
2831
+ * Encode a bigint as a CBOR tag 2 or tag 3 bignum.
2489
2832
  *
2490
- * This error is triggered when:
2491
- * - An integer is not encoded in its shortest possible form
2492
- * - A floating point value that could be represented as an integer was not
2493
- * reduced
2494
- * - A NaN value was not encoded in its canonical form (`f97e00`)
2495
- */ | {
2496
- readonly type: "NonCanonicalNumeric";
2497
- }
2498
- /**
2499
- * An invalid CBOR simple value was encountered during decoding.
2833
+ * Matches Rust's `From<BigInt> for CBOR`.
2500
2834
  *
2501
- * Per Section 2.4 of the dCBOR specification, only `false`, `true`,
2502
- * `null`, and floating point values are valid simple values in dCBOR.
2503
- * All other major type 7 values are invalid.
2504
- */ | {
2505
- readonly type: "InvalidSimpleValue";
2506
- }
2507
- /**
2508
- * A CBOR text string was not valid UTF-8. The parameter contains the
2509
- * specific error message.
2835
+ * - Non-negative values use tag 2 (positive bignum).
2836
+ * - Negative values use tag 3 (negative bignum), where the encoded
2837
+ * magnitude is `|value| - 1` per RFC 8949.
2510
2838
  *
2511
- * All CBOR text strings (major type 3) must be valid UTF-8 per RFC 8949.
2512
- */ | {
2513
- readonly type: "InvalidString";
2514
- readonly message: string;
2515
- }
2839
+ * @param value - Any bigint value
2840
+ * @returns CBOR tagged value
2841
+ */
2842
+ declare function bigintToCbor(value: bigint): Cbor;
2516
2843
  /**
2517
- * A CBOR text string was not encoded in Unicode Canonical Normalization
2518
- * Form C (NFC).
2844
+ * Decode a BigUint from an untagged CBOR byte string.
2519
2845
  *
2520
- * Per Section 2.5 of the dCBOR specification, all text strings must be in
2521
- * NFC form, and decoders must reject any encoded text strings that are
2522
- * not in NFC.
2523
- */ | {
2524
- readonly type: "NonCanonicalString";
2525
- }
2526
- /**
2527
- * The decoded CBOR item didn't consume all input data.
2528
- * The parameter contains the number of unused bytes.
2846
+ * Matches Rust's `biguint_from_untagged_cbor()`.
2529
2847
  *
2530
- * This error occurs when decoding functions expect exactly one CBOR item
2531
- * but the input contains additional data after a valid CBOR item.
2532
- */ | {
2533
- readonly type: "UnusedData";
2534
- readonly count: number;
2535
- }
2536
- /**
2537
- * The keys in a decoded CBOR map were not in the canonical lexicographic order
2538
- * of their encoding.
2848
+ * This function is intended for use in tag summarizers where the tag has
2849
+ * already been stripped. It expects a CBOR byte string representing the
2850
+ * big-endian magnitude of a positive bignum (tag 2 content).
2539
2851
  *
2540
- * Per the CDE specification and Section 2.1 of dCBOR, map keys must be in
2541
- * ascending lexicographic order of their encoded representation for
2542
- * deterministic encoding.
2543
- */ | {
2544
- readonly type: "MisorderedMapKey";
2545
- }
2546
- /**
2547
- * A decoded CBOR map contains duplicate keys, which is invalid.
2852
+ * Enforces canonical encoding: no leading zero bytes (except empty for zero).
2548
2853
  *
2549
- * Per Section 2.2 of the dCBOR specification, CBOR maps must not contain
2550
- * duplicate keys, and decoders must reject encoded maps with duplicate
2551
- * keys.
2552
- */ | {
2553
- readonly type: "DuplicateMapKey";
2554
- }
2555
- /**
2556
- * A requested key was not found in a CBOR map during data extraction.
2557
- */ | {
2558
- readonly type: "MissingMapKey";
2559
- }
2854
+ * @param cbor - A CBOR value that should be a byte string
2855
+ * @returns Non-negative bigint
2856
+ * @throws CborError with type WrongType if not a byte string
2857
+ * @throws CborError with type NonCanonicalNumeric if encoding is non-canonical
2858
+ */
2859
+ declare function biguintFromUntaggedCbor(cbor: Cbor): bigint;
2560
2860
  /**
2561
- * A CBOR numeric value could not be represented in the specified target
2562
- * numeric type.
2861
+ * Decode a BigInt from an untagged CBOR byte string for a negative bignum.
2563
2862
  *
2564
- * This occurs when attempting to convert a CBOR number to a numeric
2565
- * type that is too small to represent the value without loss of
2566
- * precision.
2567
- */ | {
2568
- readonly type: "OutOfRange";
2569
- }
2570
- /**
2571
- * The CBOR value is not of the expected type for a conversion or
2572
- * operation.
2863
+ * Matches Rust's `bigint_from_negative_untagged_cbor()`.
2573
2864
  *
2574
- * This occurs when attempting to convert a CBOR value to a type that
2575
- * doesn't match the actual CBOR item's type (e.g., trying to convert a
2576
- * string to an integer).
2577
- */ | {
2578
- readonly type: "WrongType";
2579
- }
2580
- /**
2581
- * The CBOR tagged value had a different tag than expected.
2582
- * Contains the expected tag and the actual tag found.
2583
- */ | {
2584
- readonly type: "WrongTag";
2585
- readonly expected: Tag;
2586
- readonly actual: Tag;
2587
- }
2588
- /**
2589
- * Invalid UTF‑8 in a text string.
2590
- */ | {
2591
- readonly type: "InvalidUtf8";
2592
- readonly message: string;
2593
- }
2594
- /**
2595
- * Invalid ISO 8601 date format.
2596
- */ | {
2597
- readonly type: "InvalidDate";
2598
- readonly message: string;
2599
- }
2600
- /**
2601
- * Custom error message.
2602
- */ | {
2603
- readonly type: "Custom";
2604
- readonly message: string;
2605
- };
2606
- /**
2607
- * Create a custom error with a message.
2865
+ * This function is intended for use in tag summarizers where the tag has
2866
+ * already been stripped. It expects a CBOR byte string representing `n` where
2867
+ * the actual value is `-1 - n` (tag 3 content per RFC 8949).
2608
2868
  *
2609
- * Matches Rust's `Error::msg()` method.
2610
- */
2611
- declare const errorMsg: (message: string) => Error;
2612
- /**
2613
- * Convert an Error to a display string.
2869
+ * Enforces canonical encoding: no leading zero bytes (except single `0x00`
2870
+ * for -1).
2614
2871
  *
2615
- * Matches Rust's `Display` trait / `to_string()` method.
2872
+ * @param cbor - A CBOR value that should be a byte string
2873
+ * @returns Negative bigint
2874
+ * @throws CborError with type WrongType if not a byte string
2875
+ * @throws CborError with type NonCanonicalNumeric if encoding is non-canonical
2616
2876
  */
2617
- declare const errorToString: (error: Error) => string;
2877
+ declare function bigintFromNegativeUntaggedCbor(cbor: Cbor): bigint;
2618
2878
  /**
2619
- * Result type matching Rust's `Result<T, Error>`.
2879
+ * Convert CBOR to a non-negative bigint.
2620
2880
  *
2621
- * In TypeScript, we use a discriminated union for Result instead of
2622
- * try/catch for better type safety and Rust compatibility.
2623
- */
2624
- type Result<T> = {
2625
- ok: true;
2626
- value: T;
2627
- } | {
2628
- ok: false;
2629
- error: Error;
2630
- };
2631
- /**
2632
- * Create a successful Result.
2881
+ * Matches Rust's `TryFrom<CBOR> for BigUint`.
2882
+ *
2883
+ * Accepts:
2884
+ * - Major type 0 (unsigned integer)
2885
+ * - Tag 2 (positive bignum) with canonical byte string
2886
+ *
2887
+ * Rejects:
2888
+ * - Major type 1 (negative integer) -> OutOfRange
2889
+ * - Tag 3 (negative bignum) -> OutOfRange
2890
+ * - Floating-point values -> WrongType
2891
+ * - Non-canonical bignum encodings -> NonCanonicalNumeric
2892
+ *
2893
+ * @param cbor - The CBOR value to convert
2894
+ * @returns Non-negative bigint
2895
+ * @throws CborError
2633
2896
  */
2634
- declare const Ok: <T>(value: T) => Result<T>;
2897
+ declare function cborToBiguint(cbor: Cbor): bigint;
2635
2898
  /**
2636
- * Create a failed Result.
2899
+ * Convert CBOR to a bigint (any sign).
2900
+ *
2901
+ * Matches Rust's `TryFrom<CBOR> for BigInt`.
2902
+ *
2903
+ * Accepts:
2904
+ * - Major type 0 (unsigned integer)
2905
+ * - Major type 1 (negative integer)
2906
+ * - Tag 2 (positive bignum) with canonical byte string
2907
+ * - Tag 3 (negative bignum) with canonical byte string
2908
+ *
2909
+ * Rejects:
2910
+ * - Floating-point values -> WrongType
2911
+ * - Non-canonical bignum encodings -> NonCanonicalNumeric
2912
+ *
2913
+ * @param cbor - The CBOR value to convert
2914
+ * @returns A bigint value
2915
+ * @throws CborError
2637
2916
  */
2638
- declare const Err: <T>(error: Error) => Result<T>;
2917
+ declare function cborToBigint(cbor: Cbor): bigint;
2918
+ //#endregion
2919
+ //#region src/sortable.d.ts
2639
2920
  /**
2640
- * Typed error class for all CBOR-related errors.
2921
+ * Return a new array sorted by the bytewise lexicographic order of each
2922
+ * element's CBOR encoding.
2641
2923
  *
2642
- * Wraps the discriminated union Error type in a JavaScript Error object
2643
- * for proper error handling with stack traces.
2924
+ * Mirrors Rust `pub fn sort_array_by_cbor_encoding<T>(array)`.
2644
2925
  *
2645
2926
  * @example
2646
2927
  * ```typescript
2647
- * throw new CborError({ type: 'Underrun' });
2648
- * throw new CborError({ type: 'WrongTag', expected: tag1, actual: tag2 });
2928
+ * const sorted = sortArrayByCborEncoding([3, 1, 2]); // [1, 2, 3]
2649
2929
  * ```
2650
2930
  */
2651
- declare class CborError extends Error {
2652
- /**
2653
- * The structured error information.
2654
- */
2655
- readonly errorType: Error;
2656
- /**
2657
- * Create a new CborError.
2658
- *
2659
- * @param errorType - The discriminated union error type
2660
- * @param message - Optional custom message (defaults to errorToString(errorType))
2661
- */
2662
- constructor(errorType: Error, message?: string);
2663
- /**
2664
- * Check if an error is a CborError.
2665
- *
2666
- * @param error - Error to check
2667
- * @returns True if error is a CborError
2668
- */
2669
- static isCborError(error: unknown): error is CborError;
2931
+ declare function sortArrayByCborEncoding<T extends CborInput>(array: readonly T[]): T[];
2932
+ /**
2933
+ * Sortable-by-CBOR-encoding trait shape.
2934
+ *
2935
+ * Mirrors Rust `pub trait CBORSortable<T> { fn sort_by_cbor_encoding(&self)
2936
+ * -> Vec<T>; }` with blanket implementations for `Vec<T>`, `&[T]`,
2937
+ * `HashSet<T>`. In TypeScript we expose a narrow interface plus
2938
+ * `arraySortable` / `setSortable` helpers that wrap any iterable into a
2939
+ * `CBORSortable` view.
2940
+ */
2941
+ interface CBORSortable<T extends CborInput> {
2942
+ sortByCborEncoding(): T[];
2670
2943
  }
2944
+ /**
2945
+ * Wrap a readonly array as a {@link CBORSortable}. Equivalent to Rust's
2946
+ * blanket `impl CBORSortable<T> for Vec<T>` / `for &[T]`.
2947
+ */
2948
+ declare function arraySortable<T extends CborInput>(array: readonly T[]): CBORSortable<T>;
2949
+ /**
2950
+ * Wrap a `Set<T>` as a {@link CBORSortable}. Equivalent to Rust's
2951
+ * `impl CBORSortable<T> for HashSet<T>`.
2952
+ */
2953
+ declare function setSortable<T extends CborInput>(set: ReadonlySet<T>): CBORSortable<T>;
2671
2954
  //#endregion
2672
2955
  //#region src/float.d.ts
2673
2956
  /**
@@ -3049,10 +3332,13 @@ declare const getTaggedContent: (cbor: Cbor, tag: number | bigint) => Cbor | und
3049
3332
  /**
3050
3333
  * Extract content if has specific tag, throwing if not.
3051
3334
  *
3335
+ * Mirrors Rust `try_into_expected_tagged_value`. Throws `{ type: "WrongType" }`
3336
+ * if `cbor` is not tagged at all, otherwise `{ type: "WrongTag", expected,
3337
+ * actual }` if the tag doesn't match.
3338
+ *
3052
3339
  * @param cbor - CBOR value
3053
3340
  * @param tag - Expected tag value
3054
3341
  * @returns Tagged content
3055
- * @throws {CborError} With type 'WrongType' if cbor is not tagged with the expected tag
3056
3342
  */
3057
3343
  declare const expectTaggedContent: (cbor: Cbor, tag: number | bigint) => Cbor;
3058
3344
  /**
@@ -3103,5 +3389,5 @@ declare const asCborMap: (cbor: Cbor) => CborMap | undefined;
3103
3389
  */
3104
3390
  declare const isNumber: (cbor: Cbor) => boolean;
3105
3391
  //#endregion
3106
- export { ByteString, Cbor, type CborArrayType, type CborArrayWrapper, type CborByteStringType, type CborCodable, CborDate, type CborDecodable, type CborEncodable, CborError, type CborInput, CborMap, type CborMapType, type CborMethods, type CborNegativeType, type CborNumber, CborSet, type CborSimpleType, type CborSummarizer, type CborTagged, type CborTaggedCodable, type CborTaggedDecodable, type CborTaggedEncodable, type CborTaggedType, type CborTextType, type CborUnsignedType, type DiagFormatOpts, type EdgeType, type EdgeTypeVariant, Err, type Error, type HexFormatOpts, MajorType, type MapEntry, Ok, type Result, type Simple, TAG_BASE16, TAG_BASE64, TAG_BASE64URL, TAG_BASE64URL_TEXT, TAG_BASE64_TEXT, TAG_BIGFLOAT, TAG_BINARY_UUID, TAG_DATE, TAG_DATE_TIME_STRING, TAG_DECIMAL_FRACTION, TAG_ENCODED_CBOR, TAG_EPOCH_DATE, TAG_EPOCH_DATE_TIME, TAG_MIME_MESSAGE, TAG_NAME_DATE, TAG_NEGATIVE_BIGNUM, TAG_POSITIVE_BIGNUM, TAG_REGEXP, TAG_SELF_DESCRIBE_CBOR, TAG_SET, TAG_STRING_REF_NAMESPACE, TAG_URI, TAG_UUID, type Tag, TagsStore, type TagsStoreTrait, type Visitor, type WalkElement, arrayIsEmpty, arrayItem, arrayLength, asArray, asBoolean, asByteString, asBytes, asCborArray, asCborMap, asFloat, asInteger, asKeyValue, asMap, asNegative, asNumber, asSingle, asTaggedValue, asText, asUnsigned, bytesToHex, cbor, cborData, collectAllText, collectAtLevel, countElements, createTag, createTaggedCbor, decodeCbor, decodeVarInt, decodeVarIntData, diagnosticOpt, edgeLabel, encodeVarInt, errorMsg, errorToString, expectArray, expectBoolean, expectBoolean as tryIntoBool, expectBytes, expectBytes as tryIntoByteString, expectFloat, expectInteger, expectMap, expectNegative, expectNumber, expectTaggedContent, expectTaggedContent as tryExpectedTaggedValue, expectText, expectText as tryIntoText, expectUnsigned, extractCbor, extractTaggedContent, findFirst, getGlobalTagsStore, getTaggedContent, hasFractionalPart, hasTag, hexOpt, hexToBytes, isArray, isBoolean, isBytes, isFloat, isInteger, isMap, isNaN, isNegative, isNull, isNumber, isSimple, isTagged, isText, isUnsigned, mapHas, mapIsEmpty, mapKeys, mapSize, mapValue, mapValues, maxDepth, registerTags, registerTagsIn, simpleName, summary, tagContent, tagValue, tagsForValues, toByteString, toByteStringFromHex, toTaggedValue, validateTag };
3392
+ export { ByteString, type CBORSortable, Cbor, type CborArrayType, type CborArrayWrapper, type CborByteStringType, type CborCodable, CborDate, type CborDecodable, type CborEncodable, CborError, type CborInput, CborMap, type CborMapType, type CborMethods, type CborNegativeType, type CborNumber, CborSet, type CborSimpleType, type CborSummarizer, type CborTagged, type CborTaggedCodable, type CborTaggedDecodable, type CborTaggedEncodable, type CborTaggedType, type CborTextType, type CborUnsignedType, type DiagFormatOpts, type EdgeType, type EdgeTypeVariant, Err, type Error, type HexFormatOpts, MajorType, type MapEntry, Ok, type Result, type Simple, type SummarizerResult, TAG_BASE16, TAG_BASE64, TAG_BASE64URL, TAG_BASE64URL_TEXT, TAG_BASE64_TEXT, TAG_BIGFLOAT, TAG_BINARY_UUID, TAG_DATE, TAG_DATE_TIME_STRING, TAG_DECIMAL_FRACTION, TAG_ENCODED_CBOR, TAG_EPOCH_DATE, TAG_EPOCH_DATE_TIME, TAG_MIME_MESSAGE, TAG_NAME_DATE, TAG_NAME_NEGATIVE_BIGNUM, TAG_NAME_POSITIVE_BIGNUM, TAG_NEGATIVE_BIGNUM, TAG_POSITIVE_BIGNUM, TAG_REGEXP, TAG_SELF_DESCRIBE_CBOR, TAG_SET, TAG_STRING_REF_NAMESPACE, TAG_URI, TAG_UUID, type Tag, type TagValue, TagsStore, type TagsStoreTrait, type Visitor, type WalkElement, arrayIsEmpty, arrayItem, arrayLength, arraySortable, asArray, asBoolean, asByteString, asBytes, asCborArray, asCborMap, asFloat, asInteger, asKeyValue, asMap, asNegative, asNumber, asSingle, asTaggedValue, asText, asUnsigned, bigintFromNegativeUntaggedCbor, bigintToCbor, biguintFromUntaggedCbor, biguintToCbor, bytesToHex, cbor, cborData, cborEquals, cborFalse, cborNaN, cborNull, cborToBigint, cborToBiguint, cborTrue, createTag, createTaggedCbor, decodeCbor, decodeVarInt, decodeVarIntData, diagnostic, diagnosticAnnotated, diagnosticFlat, diagnosticOpt, edgeLabel, encodeVarInt, errorMsg, errorToString, expectArray, expectBoolean, expectBoolean as tryIntoBool, expectBytes, expectBytes as tryIntoByteString, expectFloat, expectInteger, expectMap, expectNegative, expectNumber, expectTaggedContent, expectTaggedContent as tryExpectedTaggedValue, expectText, expectText as tryIntoText, expectUnsigned, extractCbor, extractTaggedContent, fromTaggedCborData, fromUntaggedCborData, getGlobalTagsStore, getTaggedContent, hasFractionalPart, hasTag, hex, hexAnnotated, hexOpt, hexToBytes, isArray, isBoolean, isBytes, isFloat, isInteger, isMap, isNaN, isNegative, isNull, isNumber, isSimple, isTagged, isText, isUnsigned, mapHas, mapIsEmpty, mapKeys, mapSize, mapValue, mapValues, registerTags, registerTagsIn, setSortable, simpleName, sortArrayByCborEncoding, summary, tagContent, tagValue, tagWithStaticName, tagWithValue, taggedCborData, tagsEqual, tagsForValues, toByteString, toByteStringFromHex, toTaggedValue, validateTag, walk };
3107
3393
  //# sourceMappingURL=index.d.cts.map