@bcts/dcbor 1.0.0-alpha.10

package/src/cbor-tagged-codable.ts

@@ -0,0 +1,72 @@
+/**
+ * Tagged CBOR encoding and decoding support.
+ *
+ * This module provides the `CborTaggedCodable` interface, which serves as a
+ * convenience marker for types that can be both encoded to and decoded from
+ * tagged CBOR values.
+ *
+ * The interface is automatically implemented for any type that implements both
+ * `CborTaggedEncodable` and `CborTaggedDecodable`.
+ *
+ * @module cbor-tagged-codable
+ */
+
+import type { CborTaggedEncodable } from "./cbor-tagged-encodable";
+import type { CborTaggedDecodable } from "./cbor-tagged-decodable";
+
+/**
+ * Interface for types that can be both encoded to and decoded from CBOR with a
+ * specific tag.
+ *
+ * This interface is automatically implemented for any type that implements both
+ * `CborTaggedEncodable` and `CborTaggedDecodable`. It serves as a convenience
+ * marker to indicate full-tagged CBOR serialization support.
+ *
+ * @example
+ * ```typescript
+ * // Define a Date type
+ * class Date implements CborTaggedCodable<Date> {
+ *   constructor(public timestamp: number) {}
+ *
+ *   cborTags(): Tag[] {
+ *     return [createTag(1, 'date')]; // Standard date tag
+ *   }
+ *
+ *   // Implement encoding to tagged CBOR
+ *   untaggedCbor(): Cbor {
+ *     return cbor(this.timestamp);
+ *   }
+ *
+ *   taggedCbor(): Cbor {
+ *     const tags = this.cborTags();
+ *     return {
+ *       isCbor: true,
+ *       type: MajorType.Tagged,
+ *       tag: tags[0].value,
+ *       value: this.untaggedCbor()
+ *     };
+ *   }
+ *
+ *   // Implement decoding from tagged CBOR
+ *   fromUntaggedCbor(cbor: Cbor): Date {
+ *     const timestamp = cbor.value as number;
+ *     return new Date(timestamp);
+ *   }
+ *
+ *   fromTaggedCbor(cbor: Cbor): Date {
+ *     if (cbor.type !== MajorType.Tagged) {
+ *       throw new Error('Wrong type');
+ *     }
+ *     return this.fromUntaggedCbor(cbor.value);
+ *   }
+ * }
+ *
+ * // The CborTaggedCodable interface is automatically implemented
+ * // Create a date and demonstrate round-trip conversion
+ * const original = new Date(1609459200);
+ * const cborValue = original.taggedCbor();
+ * const roundtrip = new Date(0).fromTaggedCbor(cborValue);
+ * assert(original.timestamp === roundtrip.timestamp);
+ * ```
+ */
+export interface CborTaggedCodable<T> extends CborTaggedEncodable, CborTaggedDecodable<T> {}

package/src/cbor-tagged-decodable.ts

@@ -0,0 +1,184 @@
+/**
+ * Tagged CBOR decoding support.
+ *
+ * This module provides the `CborTaggedDecodable` interface, which enables types to
+ * be decoded from tagged CBOR values.
+ *
+ * Tagged CBOR values include semantic information about how to interpret the
+ * data. This interface allows TypeScript types to verify that incoming CBOR data has the
+ * expected tag(s) and to decode the data appropriately.
+ *
+ * @module cbor-tagged-decodable
+ */
+
+import { type Cbor, MajorType } from "./cbor";
+import type { CborTagged } from "./cbor-tagged";
+import type { Tag } from "./tag";
+import { CborError } from "./error";
+
+/**
+ * Interface for types that can be decoded from CBOR with a specific tag.
+ *
+ * This interface extends `CborTagged` to provide methods for
+ * decoding tagged CBOR data into TypeScript types. It handles verification that
+ * the CBOR data has the expected tag(s) and provides utilities for both
+ * tagged and untagged decoding.
+ *
+ * @example
+ * ```typescript
+ * // Define a Date type
+ * class Date implements CborTaggedDecodable<Date> {
+ *   constructor(public timestamp: number) {}
+ *
+ *   cborTags(): Tag[] {
+ *     return [createTag(1, 'date')]; // Standard date tag
+ *   }
+ *
+ *   fromUntaggedCbor(cbor: Cbor): Date {
+ *     // Convert the untagged CBOR to a number
+ *     if (cbor.type !== MajorType.Unsigned) {
+ *       throw new Error('Wrong type');
+ *     }
+ *     const timestamp = typeof cbor.value === 'bigint' ? Number(cbor.value) : cbor.value;
+ *     return new Date(timestamp);
+ *   }
+ *
+ *   fromTaggedCbor(cbor: Cbor): Date {
+ *     if (cbor.type !== MajorType.Tagged) {
+ *       throw new Error('Wrong type');
+ *     }
+ *
+ *     const tags = this.cborTags();
+ *     const tagValues = tags.map(t => t.value);
+ *     if (!tagValues.includes(cbor.tag as number)) {
+ *       throw new Error(`Wrong tag: expected ${tagValues[0]}, got ${cbor.tag}`);
+ *     }
+ *
+ *     return this.fromUntaggedCbor(cbor.value);
+ *   }
+ *
+ *   static fromTaggedCborData(data: Uint8Array): Date {
+ *     const cbor = decodeCbor(data);
+ *     return new Date(0).fromTaggedCbor(cbor);
+ *   }
+ *
+ *   static fromUntaggedCborData(data: Uint8Array): Date {
+ *     const cbor = decodeCbor(data);
+ *     return new Date(0).fromUntaggedCbor(cbor);
+ *   }
+ * }
+ *
+ * // Create tagged CBOR data
+ * const taggedCbor = {
+ *   isCbor: true,
+ *   type: MajorType.Tagged,
+ *   tag: 1,
+ *   value: cbor(1609459200)
+ * };
+ *
+ * // Decode using the interface
+ * const date = new Date(0).fromTaggedCbor(taggedCbor);
+ * assert(date.timestamp === 1609459200);
+ * ```
+ */
+export interface CborTaggedDecodable<T> extends CborTagged {
+  /**
+   * Creates an instance of this type by decoding it from untagged CBOR.
+   *
+   * This method defines how to interpret the CBOR content (without
+   * considering the tag) and convert it to the implementing type.
+   *
+   * @param cbor - Untagged CBOR value
+   * @returns Decoded instance
+   * @throws Error if the CBOR value cannot be decoded
+   */
+  fromUntaggedCbor(cbor: Cbor): T;
+
+  /**
+   * Creates an instance of this type by decoding it from tagged CBOR.
+   *
+   * This method first verifies that the CBOR value has one of the expected
+   * tags (as defined by `cborTags()`), then delegates to
+   * `fromUntaggedCbor()` to decode the content.
+   *
+   * For backward compatibility, this method accepts any tag from the
+   * `cborTags()` array, not just the first one. This allows new
+   * versions of types to still accept data tagged with older/alternative
+   * tag values.
+   *
+   * In most cases, you don't need to override this method.
+   *
+   * @param cbor - Tagged CBOR value
+   * @returns Decoded instance
+   * @throws Error if the CBOR value has the wrong tag or cannot be decoded
+   */
+  fromTaggedCbor(cbor: Cbor): T;
+
+  /**
+   * Creates an instance of this type by decoding it from binary encoded
+   * tagged CBOR.
+   *
+   * This is a convenience method that first parses the binary data into a
+   * CBOR value, then uses `fromTaggedCbor()` to decode it.
+   *
+   * @param data - Binary CBOR data
+   * @returns Decoded instance
+   * @throws Error if the data cannot be parsed or decoded
+   */
+  fromTaggedCborData?(data: Uint8Array): T;
+
+  /**
+   * Creates an instance of this type by decoding it from binary encoded
+   * untagged CBOR.
+   *
+   * This is a convenience method that first parses the binary data into a
+   * CBOR value, then uses `fromUntaggedCbor()` to decode it.
+   *
+   * @param data - Binary CBOR data
+   * @returns Decoded instance
+   * @throws Error if the data cannot be parsed or decoded
+   */
+  fromUntaggedCborData?(data: Uint8Array): T;
+}
+
+/**
+ * Helper function to validate that a CBOR value has one of the expected tags.
+ *
+ * @param cbor - CBOR value to validate
+ * @param expectedTags - Array of valid tags
+ * @returns The matching tag
+ * @throws Error if the value is not tagged or has an unexpected tag
+ */
+export const validateTag = (cbor: Cbor, expectedTags: Tag[]): Tag => {
+  if (cbor.type !== MajorType.Tagged) {
+    throw new CborError({ type: "WrongType" });
+  }
+
+  const expectedValues = expectedTags.map((t) => t.value);
+  const tagValue = cbor.tag;
+
+  const matchingTag = expectedTags.find((t) => t.value === tagValue);
+  if (matchingTag === undefined) {
+    const expectedStr = expectedValues.join(" or ");
+    throw new CborError({
+      type: "Custom",
+      message: `Wrong tag: expected ${expectedStr}, got ${tagValue}`,
+    });
+  }
+
+  return matchingTag;
+};
+
+/**
+ * Helper function to extract the content from a tagged CBOR value.
+ *
+ * @param cbor - Tagged CBOR value
+ * @returns The untagged content
+ * @throws Error if the value is not tagged
+ */
+export const extractTaggedContent = (cbor: Cbor): Cbor => {
+  if (cbor.type !== MajorType.Tagged) {
+    throw new CborError({ type: "WrongType" });
+  }
+  return cbor.value;
+};

package/src/cbor-tagged-encodable.ts

@@ -0,0 +1,138 @@
+/**
+ * Tagged CBOR encoding support.
+ *
+ * This module provides the `CborTaggedEncodable` interface, which enables types to
+ * be encoded as tagged CBOR values.
+ *
+ * CBOR tags provide semantic information about the encoded data. For example,
+ * tag 1 is used for dates, indicating that the value should be interpreted
+ * as a timestamp. The dCBOR library ensures these tags are encoded
+ * deterministically.
+ *
+ * This interface enables seamless encoding of TypeScript types to properly tagged CBOR
+ * values.
+ *
+ * @module cbor-tagged-encodable
+ */
+
+import { type Cbor, MajorType, attachMethods } from "./cbor";
+import type { CborTagged } from "./cbor-tagged";
+import { CborError } from "./error";
+
+/**
+ * Interface for types that can be encoded to CBOR with a specific tag.
+ *
+ * This interface extends `CborTagged` to provide methods for encoding a value
+ * with its associated tag. Types that implement this interface define how they
+ * should be represented in CBOR format, both with and without their tag.
+ *
+ * @example
+ * ```typescript
+ * // Define a Date type
+ * class Date implements CborTaggedEncodable {
+ *   constructor(private timestamp: number) {}
+ *
+ *   cborTags(): Tag[] {
+ *     return [createTag(1, 'date')]; // Standard date tag
+ *   }
+ *
+ *   untaggedCbor(): Cbor {
+ *     // Date content is represented as a number
+ *     return cbor(this.timestamp);
+ *   }
+ *
+ *   taggedCbor(): Cbor {
+ *     const tags = this.cborTags();
+ *     return {
+ *       isCbor: true,
+ *       type: MajorType.Tagged,
+ *       tag: tags[0].value,
+ *       value: this.untaggedCbor()
+ *     };
+ *   }
+ *
+ *   taggedCborData(): Uint8Array {
+ *     return cborData(this.taggedCbor());
+ *   }
+ * }
+ *
+ * // Create a date and encode it
+ * const date = new Date(1609459200);
+ *
+ * // Get the untagged CBOR (just the timestamp)
+ * const untagged = date.untaggedCbor();
+ *
+ * // Get the tagged CBOR (with tag 1)
+ * const tagged = date.taggedCbor();
+ *
+ * // Get binary representation
+ * const data = date.taggedCborData();
+ * ```
+ */
+export interface CborTaggedEncodable extends CborTagged {
+  /**
+   * Returns the untagged CBOR encoding of this instance.
+   *
+   * This method defines how the value itself (without its tag) should
+   * be represented in CBOR format.
+   *
+   * @returns Untagged CBOR representation
+   */
+  untaggedCbor(): Cbor;
+
+  /**
+   * Returns the tagged CBOR encoding of this instance.
+   *
+   * This method wraps the result of `untaggedCbor()` with the first tag
+   * from `cborTags()`, which is considered the "preferred" tag for the
+   * type.
+   *
+   * Even if a type supports multiple tags for backward-compatible decoding
+   * via `cborTags()`, only the first (preferred) tag is used for encoding.
+   * This ensures consistency in newly created data while maintaining the
+   * ability to read older formats.
+   *
+   * In most cases, you don't need to override this method.
+   *
+   * @returns Tagged CBOR representation
+   */
+  taggedCbor(): Cbor;
+
+  /**
+   * Returns the tagged value in CBOR binary representation.
+   *
+   * This is a convenience method that converts the result of `taggedCbor()`
+   * to binary format.
+   *
+   * @returns Binary CBOR representation
+   */
+  taggedCborData?(): Uint8Array;
+}
+
+/**
+ * Helper function to create tagged CBOR from an encodable object.
+ *
+ * Uses the first tag from cborTags().
+ *
+ * @param encodable - Object implementing CborTaggedEncodable
+ * @returns Tagged CBOR value
+ */
+export const createTaggedCbor = (encodable: CborTaggedEncodable): Cbor => {
+  const tags = encodable.cborTags();
+  if (tags.length === 0) {
+    throw new CborError({ type: "Custom", message: "No tags defined for this type" });
+  }
+
+  const tag = tags[0];
+  if (tag === undefined) {
+    throw new CborError({ type: "Custom", message: "Tag is undefined" });
+  }
+  const untagged = encodable.untaggedCbor();
+
+  return attachMethods({
+    isCbor: true,
+    type: MajorType.Tagged,
+    tag: tag.value,
+    value: untagged,
+  });
+};

package/src/cbor-tagged.ts

@@ -0,0 +1,104 @@
+/**
+ * Base trait for types that have associated CBOR tags.
+ *
+ * CBOR allows values to be "tagged" with semantic information using tag
+ * numbers. The dCBOR library provides a set of interfaces for working with tagged
+ * values in a type-safe manner.
+ *
+ * Tags in CBOR provide additional context about how a value should be
+ * interpreted. For example, tag 1 is used for dates, indicating the value is a
+ * timestamp.
+ *
+ * This interface system allows TypeScript types to define their associated CBOR tags
+ * and provide serialization/deserialization logic specifically for tagged
+ * values.
+ *
+ * @module cbor-tagged
+ */
+
+import type { Tag } from "./tag";
+
+/**
+ * Interface for types that have associated CBOR tags.
+ *
+ * In CBOR, tags provide semantic information about how to interpret data
+ * items. This interface defines which CBOR tag(s) are associated with a particular
+ * TypeScript type.
+ *
+ * Implementing this interface is a prerequisite for implementing
+ * `CborTaggedEncodable` and `CborTaggedDecodable`.
+ *
+ * ## Multiple Tags for Backward Compatibility
+ *
+ * The `cborTags()` method returns an array of tags, enabling support for
+ * backward compatibility with older tag versions:
+ *
+ * - **When encoding**: Only the first tag in the array is used for
+ *   serialization
+ * - **When decoding**: Any of the tags in the array will be accepted
+ *
+ * This design solves several real-world problems:
+ *
+ * 1. **IANA Registration Simplification**: If you initially choose a tag in
+ *    the Specification Required range (24-32767) and later want to move to the
+ *    simpler First Come, First Served range (32768+), you can migrate while
+ *    maintaining compatibility with existing data.
+ *
+ * 2. **Protocol Evolution**: As your protocol evolves, you can introduce new
+ *    preferred tags while still supporting data encoded with older tags.
+ *
+ * 3. **Versioning**: Different tags can represent different versions of your
+ *    data format while sharing the same TypeScript type for handling.
+ *
+ * @example
+ * ```typescript
+ * // Single tag
+ * class Date implements CborTagged {
+ *   cborTags(): Tag[] {
+ *     return [createTag(1, 'date')];
+ *   }
+ * }
+ *
+ * // Multiple tags for backward compatibility
+ * class Seed implements CborTagged {
+ *   cborTags(): Tag[] {
+ *     return [
+ *       createTag(40300, 'seed'),  // Primary tag (used for encoding)
+ *       createTag(300, 'seed-legacy'), // Legacy tag (accepted for decoding)
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+export interface CborTagged {
+  /**
+   * Returns the CBOR tags associated with this type.
+   *
+   * This method should return an array of tags in order of preference:
+   *
+   * - The first tag in the array is the "preferred" tag and will be used
+   *   when encoding values of this type via
+   *   `CborTaggedEncodable.taggedCbor()`.
+   *
+   * - All tags in the array are considered equivalent for decoding. When
+   *   `CborTaggedDecodable.fromTaggedCbor()` is called, any tag in this
+   *   array will be accepted as valid for this type.
+   *
+   * This design enables backward compatibility: you can introduce a new tag
+   * (placed first in the array) while still supporting older tags for
+   * decoding.
+   *
+   * For standard CBOR tags, you can use predefined tag constants from the
+   * `tags` module, or create custom tags with `createTag()`.
+   */
+  cborTags(): Tag[];
+}
+
+// Re-export interfaces and functions from separate modules for convenience
+export { type CborTaggedEncodable, createTaggedCbor } from "./cbor-tagged-encodable";
+export {
+  type CborTaggedDecodable,
+  validateTag,
+  extractTaggedContent,
+} from "./cbor-tagged-decodable";
+export { type CborTaggedCodable } from "./cbor-tagged-codable";