@bcts/envelope 1.0.0-alpha.10

package/src/format/tree.ts

@@ -0,0 +1,168 @@
+import { Envelope } from "../base/envelope";
+import { type EdgeType, edgeLabel } from "../base/walk";
+
+/// Tree formatting for Gordian Envelopes.
+///
+/// This module provides functionality for creating textual tree
+/// representations of envelopes, which is useful for debugging and visualizing
+/// the hierarchical structure of complex envelopes.
+///
+/// The tree format displays each component of an envelope (subject and
+/// assertions) as nodes in a tree, making it easy to understand the
+/// hierarchical structure of nested envelopes. Each node includes:
+///
+/// - The first 8 characters of the element's digest (for easy reference)
+/// - The type of the element (NODE, ASSERTION, ELIDED, etc.)
+/// - The content of the element (for leaf nodes)
+
+/// Options for tree formatting
+export interface TreeFormatOptions {
+  /// If true, hides NODE identifiers and only shows semantic content
+  hideNodes?: boolean;
+  /// Set of digest strings to highlight in the tree
+  highlightDigests?: Set<string>;
+  /// Format for displaying digests
+  digestDisplay?: "short" | "full";
+}
+
+/// Represents an element in the tree representation
+interface TreeElement {
+  /// Indentation level
+  level: number;
+  /// The envelope element
+  envelope: Envelope;
+  /// Type of incoming edge
+  incomingEdge: EdgeType;
+  /// Whether to show the digest ID
+  showId: boolean;
+  /// Whether this element is highlighted
+  isHighlighted: boolean;
+}
+
+// Note: Method declarations are in the base Envelope class.
+// This module provides the prototype implementations.
+
+/// Implementation of shortId()
+Envelope.prototype.shortId = function (this: Envelope, format: "short" | "full" = "short"): string {
+  const digest = this.digest();
+  if (format === "full") {
+    return digest.hex();
+  }
+  return digest.short();
+};
+
+/// Implementation of summary()
+Envelope.prototype.summary = function (this: Envelope, maxLength = 40): string {
+  const c = this.case();
+
+  switch (c.type) {
+    case "node":
+      return "NODE";
+    case "leaf": {
+      // Try to extract a readable value
+      try {
+        const text = this.asText();
+        if (text !== undefined) {
+          const truncated = text.length > maxLength ? `${text.substring(0, maxLength)}...` : text;
+          return JSON.stringify(truncated);
+        }
+      } catch {
+        // Fall through
+      }
+
+      try {
+        const num = this.extractNumber();
+        return String(num);
+      } catch {
+        // Fall through
+      }
+
+      try {
+        const bool = this.extractBoolean();
+        return String(bool);
+      } catch {
+        // Fall through
+      }
+
+      if (this.isNull()) {
+        return "null";
+      }
+
+      // Fallback: show byte string
+      const bytes = this.asByteString();
+      if (bytes !== undefined && bytes.length <= 16) {
+        const hex = Array.from(bytes)
+          .map((b) => b.toString(16).padStart(2, "0"))
+          .join("");
+        return `h'${hex}'`;
+      }
+
+      return "LEAF";
+    }
+    case "wrapped":
+      return "WRAPPED";
+    case "assertion":
+      return "ASSERTION";
+    case "elided":
+      return "ELIDED";
+    case "encrypted":
+      return "ENCRYPTED";
+    case "compressed":
+      return "COMPRESSED";
+    case "knownValue":
+      return "KNOWN_VALUE";
+    default:
+      return "UNKNOWN";
+  }
+};
+
+/// Implementation of treeFormat()
+Envelope.prototype.treeFormat = function (this: Envelope, options: TreeFormatOptions = {}): string {
+  const hideNodes = options.hideNodes ?? false;
+  const highlightDigests = options.highlightDigests ?? new Set<string>();
+  const digestDisplay = options.digestDisplay ?? "short";
+
+  const elements: TreeElement[] = [];
+
+  // Walk the envelope and collect elements
+  this.walk(hideNodes, undefined, (envelope, level, incomingEdge, _state) => {
+    const digestStr = envelope.digest().short();
+    const isHighlighted = highlightDigests.has(digestStr);
+
+    elements.push({
+      level,
+      envelope,
+      incomingEdge,
+      showId: !hideNodes,
+      isHighlighted,
+    });
+
+    return [undefined, false];
+  });
+
+  // Format each element as a line
+  const lines = elements.map((elem) => {
+    const parts: string[] = [];
+
+    if (elem.isHighlighted) {
+      parts.push("*");
+    }
+
+    if (elem.showId) {
+      parts.push(elem.envelope.shortId(digestDisplay));
+    }
+
+    const label = edgeLabel(elem.incomingEdge);
+    if (label !== undefined && label !== "") {
+      parts.push(label);
+    }
+
+    parts.push(elem.envelope.summary(40));
+
+    const line = parts.join(" ");
+    const indent = " ".repeat(elem.level * 4);
+    return indent + line;
+  });
+
+  return lines.join("\n");
+};

package/src/index.ts

@@ -0,0 +1,32 @@
+/// Gordian Envelope TypeScript Library
+///
+/// A TypeScript implementation of Blockchain Commons' Gordian Envelope
+/// specification for structured, privacy-focused data containers.
+///
+/// This is a 1:1 port of the Rust bc-envelope library, maintaining the same
+/// API structure and functionality.
+///
+/// @module bc-envelope
+
+// Re-export everything from the base module
+export * from "./base";
+
+// Re-export everything from the extension module
+export * from "./extension";
+
+// Import registration functions and call them to ensure proper initialization order
+import { registerEncryptExtension } from "./extension/encrypt";
+import { registerCompressExtension } from "./extension/compress";
+registerEncryptExtension();
+registerCompressExtension();
+
+// Re-export everything from the format module
+// Import for side effects (registers prototype extensions like treeFormat)
+import "./format";
+export type * from "./format";
+
+// Re-export everything from the utils module
+export * from "./utils";
+
+// Version information
+export const VERSION = "0.37.0";

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Utility functions for the envelope library.
+ */
+
+export { flanked } from "./string";
+
+// Side-effect import to extend String prototype
+import "./string";

package/src/utils/string.ts

@@ -0,0 +1,48 @@
+/**
+ * String utility functions used throughout the envelope library.
+ *
+ * Provides helper methods for string formatting and manipulation.
+ */
+
+/**
+ * Flanks a string with specified left and right delimiters.
+ *
+ * @param str - The string to flank
+ * @param left - The left delimiter
+ * @param right - The right delimiter
+ * @returns The flanked string
+ *
+ * @example
+ * ```typescript
+ * flanked('hello', '"', '"')  // Returns: "hello"
+ * flanked('name', "'", "'")   // Returns: 'name'
+ * flanked('item', '[', ']')   // Returns: [item]
+ * ```
+ */
+export function flanked(str: string, left: string, right: string): string {
+  return `${left}${str}${right}`;
+}
+
+/**
+ * Extension methods for String objects to support fluent API style.
+ */
+declare global {
+  interface String {
+    /**
+     * Flanks this string with specified left and right delimiters.
+     *
+     * @param left - The left delimiter
+     * @param right - The right delimiter
+     * @returns The flanked string
+     */
+    flankedBy(left: string, right: string): string;
+  }
+}
+
+// Extend String prototype with flankedBy method
+String.prototype.flankedBy = function (this: string, left: string, right: string): string {
+  return flanked(this, left, right);
+};
+
+// Export the extension for side-effects
+export {};