@bcts/dcbor 1.0.0-alpha.10

package/src/string-util.ts

@@ -0,0 +1,55 @@
+/**
+ * String utilities for dCBOR, including Unicode normalization.
+ *
+ * @module string-util
+ */
+
+/**
+ * Flank a string with left and right strings.
+ *
+ * @param s - String to flank
+ * @param left - Left flanking string
+ * @param right - Right flanking string
+ * @returns Flanked string
+ */
+export const flanked = (s: string, left: string, right: string): string => left + s + right;
+
+/**
+ * Check if a character is printable.
+ *
+ * @param c - Character to check
+ * @returns True if printable
+ */
+export const isPrintable = (c: string): boolean => {
+  if (c.length !== 1) return false;
+  const code = c.charCodeAt(0);
+  // Non-ASCII or ASCII printable (32-126)
+  return code > 127 || (code >= 32 && code <= 126);
+};
+
+/**
+ * Sanitize a string by replacing non-printable characters with dots.
+ * Returns None if the string has no printable characters.
+ *
+ * @param str - String to sanitize
+ * @returns Sanitized string or undefined if no printable characters
+ */
+export const sanitized = (str: string): string | undefined => {
+  let hasPrintable = false;
+  const chars: string[] = [];
+
+  for (const c of str) {
+    if (isPrintable(c)) {
+      hasPrintable = true;
+      chars.push(c);
+    } else {
+      chars.push(".");
+    }
+  }
+
+  if (!hasPrintable) {
+    return undefined;
+  }
+
+  return chars.join("");
+};

package/src/tag.ts

@@ -0,0 +1,53 @@
+/**
+ * CBOR Tag support for semantic tagging of values.
+ *
+ * Tags provide semantic information about CBOR data items.
+ * For example, tag 1 indicates a date/time value.
+ *
+ * @module tag
+ */
+
+import type { CborNumber } from "./cbor";
+
+/**
+ * A CBOR tag with an optional name.
+ *
+ * Tags consist of a numeric value and an optional human-readable name.
+ */
+export interface Tag {
+  /** The numeric tag value */
+  readonly value: CborNumber;
+  /** Optional human-readable name for the tag */
+  readonly name?: string;
+}
+
+/**
+ * Create a new Tag.
+ *
+ * @param value - The numeric tag value
+ * @param name - Optional human-readable name
+ * @returns A new Tag object
+ *
+ * @example
+ * ```typescript
+ * const dateTag = createTag(1, 'date');
+ * const customTag = createTag(12345, 'myCustomTag');
+ * ```
+ */
+export const createTag = (value: CborNumber, name?: string): Tag => {
+  if (name !== undefined) {
+    return { value, name };
+  }
+  return { value };
+};
+
+/**
+ * Get the string representation of a tag.
+ * Internal function used for error messages.
+ *
+ * @param tag - The tag to represent
+ * @returns String representation (name if available, otherwise value)
+ *
+ * @internal
+ */
+export const tagToString = (tag: Tag): string => tag.name ?? tag.value.toString();

package/src/tags-store.ts

@@ -0,0 +1,294 @@
+/**
+ * Tag registry and management system.
+ *
+ * The TagsStore provides a centralized registry for CBOR tags,
+ * including name resolution and custom summarizer functions.
+ *
+ * @module tags-store
+ */
+
+import type { Cbor, CborNumber } from "./cbor";
+import type { Tag } from "./tag";
+
+/**
+ * Function type for custom CBOR value summarizers.
+ *
+ * Summarizers provide custom string representations for tagged values.
+ *
+ * @param cbor - The CBOR value to summarize
+ * @param flat - If true, produce single-line output
+ * @returns String summary of the value
+ */
+export type CborSummarizer = (cbor: Cbor, flat: boolean) => string;
+
+/**
+ * Interface for tag store operations.
+ */
+export interface TagsStoreTrait {
+  /**
+   * Get the assigned name for a tag, if any.
+   *
+   * @param tag - The tag to look up
+   * @returns The assigned name, or undefined if no name is registered
+   */
+  assignedNameForTag(tag: Tag): string | undefined;
+
+  /**
+   * Get a display name for a tag.
+   *
+   * @param tag - The tag to get a name for
+   * @returns The assigned name if available, otherwise the tag value as a string
+   */
+  nameForTag(tag: Tag): string;
+
+  /**
+   * Look up a tag by its numeric value.
+   *
+   * @param value - The numeric tag value
+   * @returns The Tag object if found, undefined otherwise
+   */
+  tagForValue(value: CborNumber): Tag | undefined;
+
+  /**
+   * Look up a tag by its name.
+   *
+   * @param name - The tag name
+   * @returns The Tag object if found, undefined otherwise
+   */
+  tagForName(name: string): Tag | undefined;
+
+  /**
+   * Get a display name for a tag value.
+   *
+   * @param value - The numeric tag value
+   * @returns The tag name if registered, otherwise the value as a string
+   */
+  nameForValue(value: CborNumber): string;
+
+  /**
+   * Get a custom summarizer function for a tag, if registered.
+   *
+   * @param tag - The numeric tag value
+   * @returns The summarizer function if registered, undefined otherwise
+   */
+  summarizer(tag: CborNumber): CborSummarizer | undefined;
+}
+
+/**
+ * Tag registry implementation.
+ *
+ * Stores tags with their names and optional summarizer functions.
+ */
+export class TagsStore implements TagsStoreTrait {
+  readonly #tagsByValue = new Map<string, Tag>();
+  readonly #tagsByName = new Map<string, Tag>();
+  readonly #summarizers = new Map<string, CborSummarizer>();
+
+  constructor() {
+    // Start with empty store, matching Rust's Default implementation
+    // Tags must be explicitly registered using insert() or registerTags()
+  }
+
+  /**
+   * Insert a tag into the registry.
+   *
+   * @param tag - The tag to register
+   *
+   * @example
+   * ```typescript
+   * const store = new TagsStore();
+   * store.insert(createTag(12345, 'myCustomTag'));
+   * ```
+   */
+  insert(tag: Tag): void {
+    const key = this.#valueKey(tag.value);
+    this.#tagsByValue.set(key, tag);
+    if (tag.name !== undefined) {
+      this.#tagsByName.set(tag.name, tag);
+    }
+  }
+
+  /**
+   * Insert multiple tags into the registry.
+   * Matches Rust's insert_all() method.
+   *
+   * @param tags - Array of tags to register
+   *
+   * @example
+   * ```typescript
+   * const store = new TagsStore();
+   * store.insertAll([
+   *   createTag(1, 'date'),
+   *   createTag(100, 'custom')
+   * ]);
+   * ```
+   */
+  insertAll(tags: Tag[]): void {
+    for (const tag of tags) {
+      this.insert(tag);
+    }
+  }
+
+  /**
+   * Register a custom summarizer function for a tag.
+   *
+   * @param tagValue - The numeric tag value
+   * @param summarizer - The summarizer function
+   *
+   * @example
+   * ```typescript
+   * store.setSummarizer(1, (cbor, flat) => {
+   *   // Custom date formatting
+   *   return `Date(${extractCbor(cbor)})`;
+   * });
+   * ```
+   */
+  setSummarizer(tagValue: CborNumber, summarizer: CborSummarizer): void {
+    const key = this.#valueKey(tagValue);
+    this.#summarizers.set(key, summarizer);
+  }
+
+  /**
+   * Remove a tag from the registry.
+   *
+   * @param tagValue - The numeric tag value to remove
+   * @returns true if a tag was removed, false otherwise
+   */
+  remove(tagValue: CborNumber): boolean {
+    const key = this.#valueKey(tagValue);
+    const tag = this.#tagsByValue.get(key);
+    if (tag === undefined) {
+      return false;
+    }
+
+    this.#tagsByValue.delete(key);
+    if (tag.name !== undefined) {
+      this.#tagsByName.delete(tag.name);
+    }
+    this.#summarizers.delete(key);
+    return true;
+  }
+
+  assignedNameForTag(tag: Tag): string | undefined {
+    const key = this.#valueKey(tag.value);
+    const stored = this.#tagsByValue.get(key);
+    return stored?.name;
+  }
+
+  nameForTag(tag: Tag): string {
+    return this.assignedNameForTag(tag) ?? tag.value.toString();
+  }
+
+  tagForValue(value: CborNumber): Tag | undefined {
+    const key = this.#valueKey(value);
+    return this.#tagsByValue.get(key);
+  }
+
+  tagForName(name: string): Tag | undefined {
+    return this.#tagsByName.get(name);
+  }
+
+  nameForValue(value: CborNumber): string {
+    const tag = this.tagForValue(value);
+    return tag !== undefined ? this.nameForTag(tag) : value.toString();
+  }
+
+  summarizer(tag: CborNumber): CborSummarizer | undefined {
+    const key = this.#valueKey(tag);
+    return this.#summarizers.get(key);
+  }
+
+  /**
+   * Get all registered tags.
+   *
+   * @returns Array of all registered tags
+   */
+  getAllTags(): Tag[] {
+    return Array.from(this.#tagsByValue.values());
+  }
+
+  /**
+   * Clear all registered tags and summarizers.
+   */
+  clear(): void {
+    this.#tagsByValue.clear();
+    this.#tagsByName.clear();
+    this.#summarizers.clear();
+  }
+
+  /**
+   * Get the number of registered tags.
+   *
+   * @returns Number of tags in the registry
+   */
+  get size(): number {
+    return this.#tagsByValue.size;
+  }
+
+  /**
+   * Create a string key for a numeric tag value.
+   * Handles both number and bigint types.
+   *
+   * @private
+   */
+  #valueKey(value: CborNumber): string {
+    return value.toString();
+  }
+}
+
+// ============================================================================
+// Global Tags Store Singleton
+// ============================================================================
+
+/**
+ * Global singleton instance of the tags store.
+ */
+let globalTagsStore: TagsStore | undefined;
+
+/**
+ * Get the global tags store instance.
+ *
+ * Creates the instance on first access.
+ *
+ * @returns The global TagsStore instance
+ *
+ * @example
+ * ```typescript
+ * const store = getGlobalTagsStore();
+ * store.insert(createTag(999, 'myTag'));
+ * ```
+ */
+export const getGlobalTagsStore = (): TagsStore => {
+  globalTagsStore ??= new TagsStore();
+  return globalTagsStore;
+};
+
+/**
+ * Execute a function with access to the global tags store.
+ *
+ * @template T - Return type of the action function
+ * @param action - Function to execute with the tags store
+ * @returns Result of the action function
+ *
+ * @example
+ * ```typescript
+ * const tagName = withTags(store => store.nameForValue(1));
+ * console.log(tagName); // 'date'
+ * ```
+ */
+export const withTags = <T>(action: (tags: TagsStore) => T): T => {
+  return action(getGlobalTagsStore());
+};
+
+/**
+ * Execute a function with mutable access to the global tags store.
+ *
+ * This is an alias for withTags() for consistency with Rust API.
+ *
+ * @template T - Return type of the action function
+ * @param action - Function to execute with the tags store
+ * @returns Result of the action function
+ */
+export const withTagsMut = <T>(action: (tags: TagsStore) => T): T => {
+  return action(getGlobalTagsStore());
+};

package/src/tags.ts

@@ -0,0 +1,231 @@
+/**
+ * Standard CBOR tag definitions from the IANA registry.
+ *
+ * @module tags
+ * @see https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml
+ */
+
+import { type Tag, createTag } from "./tag";
+
+// ============================================================================
+// Standard Date/Time Tags
+// ============================================================================
+
+/**
+ * Tag 0: Standard date/time string (RFC 3339)
+ */
+export const TAG_DATE_TIME_STRING = 0;
+
+/**
+ * Tag 1: Epoch-based date/time (seconds since 1970-01-01T00:00:00Z)
+ */
+export const TAG_EPOCH_DATE_TIME = 1;
+
+/**
+ * Tag 100: Epoch-based date (days since 1970-01-01)
+ */
+export const TAG_EPOCH_DATE = 100;
+
+// ============================================================================
+// Numeric Tags
+// ============================================================================
+
+/**
+ * Tag 2: Positive bignum (unsigned arbitrary-precision integer)
+ */
+export const TAG_POSITIVE_BIGNUM = 2;
+
+/**
+ * Tag 3: Negative bignum (signed arbitrary-precision integer)
+ */
+export const TAG_NEGATIVE_BIGNUM = 3;
+
+/**
+ * Tag 4: Decimal fraction [exponent, mantissa]
+ */
+export const TAG_DECIMAL_FRACTION = 4;
+
+/**
+ * Tag 5: Bigfloat [exponent, mantissa]
+ */
+export const TAG_BIGFLOAT = 5;
+
+// ============================================================================
+// Encoding Hints
+// ============================================================================
+
+/**
+ * Tag 21: Expected conversion to base64url encoding
+ */
+export const TAG_BASE64URL = 21;
+
+/**
+ * Tag 22: Expected conversion to base64 encoding
+ */
+export const TAG_BASE64 = 22;
+
+/**
+ * Tag 23: Expected conversion to base16 encoding
+ */
+export const TAG_BASE16 = 23;
+
+/**
+ * Tag 24: Encoded CBOR data item
+ */
+export const TAG_ENCODED_CBOR = 24;
+
+// ============================================================================
+// URI and Network Tags
+// ============================================================================
+
+/**
+ * Tag 32: URI (text string)
+ */
+export const TAG_URI = 32;
+
+/**
+ * Tag 33: base64url-encoded text
+ */
+export const TAG_BASE64URL_TEXT = 33;
+
+/**
+ * Tag 34: base64-encoded text
+ */
+export const TAG_BASE64_TEXT = 34;
+
+/**
+ * Tag 35: Regular expression (PCRE/ECMA262)
+ */
+export const TAG_REGEXP = 35;
+
+/**
+ * Tag 36: MIME message
+ */
+export const TAG_MIME_MESSAGE = 36;
+
+/**
+ * Tag 37: Binary UUID
+ */
+export const TAG_UUID = 37;
+
+// ============================================================================
+// Cryptography Tags
+// ============================================================================
+
+/**
+ * Tag 256: string reference (namespace)
+ */
+export const TAG_STRING_REF_NAMESPACE = 256;
+
+/**
+ * Tag 257: binary UUID reference
+ */
+export const TAG_BINARY_UUID = 257;
+
+/**
+ * Tag 258: Set of values (array with no duplicates)
+ */
+export const TAG_SET = 258;
+
+// ============================================================================
+// NOTE: Blockchain Commons envelope and extension tags (TAG_ENVELOPE, TAG_LEAF,
+// TAG_KNOWN_VALUE, TAG_COMPRESSED, etc.) are defined in the @bcts/tags
+// package, NOT in dcbor. This matches the Rust architecture where bc-dcbor-rust
+// only defines TAG_DATE, and bc-tags-rust defines all envelope-related tags.
+// ============================================================================
+
+// ============================================================================
+// Self-describing CBOR
+// ============================================================================
+
+/**
+ * Tag 55799: Self-describe CBOR (magic number 0xd9d9f7)
+ */
+export const TAG_SELF_DESCRIBE_CBOR = 55799;
+
+// ============================================================================
+// Global Tags Store Registration
+// Matches Rust's register_tags() functionality
+// ============================================================================
+
+import type { TagsStore } from "./tags-store";
+import { getGlobalTagsStore } from "./tags-store";
+import { CborDate } from "./date";
+import type { Cbor } from "./cbor";
+import { diagnostic } from "./diag";
+
+// Tag constants matching Rust
+export const TAG_DATE = 1;
+export const TAG_NAME_DATE = "date";
+
+/**
+ * Register standard tags in a specific tags store.
+ * Matches Rust's register_tags_in() function.
+ *
+ * @param tagsStore - The tags store to register tags into
+ */
+export const registerTagsIn = (tagsStore: TagsStore): void => {
+  const tags = [createTag(TAG_DATE, TAG_NAME_DATE)];
+  tagsStore.insertAll(tags);
+
+  // Set summarizer for date tag
+  tagsStore.setSummarizer(TAG_DATE, (untaggedCbor: Cbor, _flat: boolean): string => {
+    try {
+      return CborDate.fromUntaggedCbor(untaggedCbor).toString();
+    } catch {
+      return diagnostic(untaggedCbor);
+    }
+  });
+};
+
+/**
+ * Register standard tags in the global tags store.
+ * Matches Rust's register_tags() function.
+ *
+ * This function is idempotent - calling it multiple times is safe.
+ */
+export const registerTags = (): void => {
+  const globalStore = getGlobalTagsStore();
+  registerTagsIn(globalStore);
+};
+
+/**
+ * Converts an array of tag values to their corresponding Tag objects.
+ * Matches Rust's tags_for_values() function.
+ *
+ * This function looks up each tag value in the global tag registry and returns
+ * an array of complete Tag objects. For any tag values that aren't
+ * registered in the global registry, it creates a basic Tag with just the
+ * value (no name).
+ *
+ * @param values - Array of numeric tag values to convert
+ * @returns Array of Tag objects corresponding to the input values
+ *
+ * @example
+ * ```typescript
+ * // Register some tags first
+ * registerTags();
+ *
+ * // Convert tag values to Tag objects
+ * const tags = tagsForValues([1, 42, 999]);
+ *
+ * // The first tag (value 1) should be registered as "date"
+ * console.log(tags[0].value); // 1
+ * console.log(tags[0].name); // "date"
+ *
+ * // Unregistered tags will have a value but no name
+ * console.log(tags[1].value); // 42
+ * console.log(tags[2].value); // 999
+ * ```
+ */
+export const tagsForValues = (values: (number | bigint)[]): Tag[] => {
+  const globalStore = getGlobalTagsStore();
+  return values.map((value) => {
+    const tag = globalStore.tagForValue(value);
+    if (tag !== undefined) {
+      return tag;
+    }
+    // Create basic tag with just the value
+    return createTag(value);
+  });
+};