@bcts/envelope 1.0.0-alpha.5

package/src/extension/types.ts

@@ -0,0 +1,222 @@
+import { Envelope } from "../base/envelope";
+import { type EnvelopeEncodableValue } from "../base/envelope-encodable";
+import { EnvelopeError } from "../base/error";
+
+/// Type system for Gordian Envelopes.
+///
+/// This module provides functionality for adding, querying, and verifying types
+/// within envelopes. In Gordian Envelope, types are implemented using the
+/// special `'isA'` predicate (the string "isA"), which is semantically
+/// equivalent to the RDF `rdf:type` concept.
+///
+/// Type information enables:
+/// - Semantic classification of envelopes
+/// - Type verification before processing content
+/// - Conversion between domain objects and envelopes
+/// - Schema validation
+///
+/// ## Type Representation
+///
+/// Types are represented as assertions with the `'isA'` predicate and an object
+/// that specifies the type. The type object is typically a string or an envelope.
+///
+/// ## Usage Patterns
+///
+/// The type system is commonly used in two ways:
+///
+/// 1. **Type Tagging**: Adding type information to envelopes to indicate their
+///    semantic meaning
+///
+///    ```typescript
+///    // Create an envelope representing a person
+///    const person = Envelope.new("Alice")
+///      .addType("Person")
+///      .addAssertion("age", 30);
+///    ```
+///
+/// 2. **Type Checking**: Verifying that an envelope has the expected type
+///    before processing
+///
+///    ```typescript
+///    function processPerson(envelope: Envelope): void {
+///      // Verify this is a person before processing
+///      envelope.checkType("Person");
+///
+///      // Now we can safely extract person-specific information
+///      const name = envelope.subject().extractString();
+///      const age = envelope.objectForPredicate("age").extractNumber();
+///
+///      console.log(`${name} is ${age} years old`);
+///    }
+///    ```
+
+/// The standard predicate for type assertions
+export const IS_A = "isA";
+
+declare module "../base/envelope" {
+  interface Envelope {
+    /// Adds a type assertion to the envelope using the `'isA'` predicate.
+    ///
+    /// This method provides a convenient way to declare the type of an envelope
+    /// using the standard `'isA'` predicate. The type can be any value that can
+    /// be converted to an envelope, typically a string.
+    ///
+    /// @param object - The type to assign to this envelope
+    /// @returns A new envelope with the type assertion added
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create a document and declare its type
+    /// const document = Envelope.new("Important Content").addType("Document");
+    ///
+    /// // Verify the type was added
+    /// assert(document.hasType("Document"));
+    /// ```
+    addType(object: EnvelopeEncodableValue): Envelope;
+
+    /// Returns all type objects from the envelope's `'isA'` assertions.
+    ///
+    /// This method retrieves all objects of assertions that use the `'isA'`
+    /// predicate. Each returned envelope represents a type that has been
+    /// assigned to this envelope.
+    ///
+    /// @returns An array of envelopes, each representing a type assigned to
+    ///   this envelope
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create an envelope with multiple types
+    /// const multiTyped = Envelope.new("Versatile Entity")
+    ///   .addType("Person")
+    ///   .addType("Employee")
+    ///   .addType("Manager");
+    ///
+    /// // Get all the type objects
+    /// const types = multiTyped.types();
+    ///
+    /// // There should be 3 types
+    /// console.log(types.length); // 3
+    /// ```
+    types(): Envelope[];
+
+    /// Gets a single type object from the envelope's `'isA'` assertions.
+    ///
+    /// This method is useful when an envelope is expected to have exactly one
+    /// type. It throws an error if the envelope has zero or multiple types.
+    ///
+    /// @returns The single type object if exactly one exists
+    /// @throws {EnvelopeError} If multiple types exist or no types exist
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create an envelope with a single type
+    /// const person = Envelope.new("Alice").addType("Person");
+    ///
+    /// // Get the type
+    /// const typeObj = person.getType();
+    /// const typeString = typeObj.extractString();
+    /// console.log(typeString); // "Person"
+    /// ```
+    getType(): Envelope;
+
+    /// Checks if the envelope has a specific type, using an envelope as the
+    /// type identifier.
+    ///
+    /// This method compares the digest of each type object with the digest of
+    /// the provided value to determine if the envelope has the specified type.
+    ///
+    /// @param t - The type to check for, which will be converted to an envelope
+    /// @returns `true` if the envelope has the specified type, `false`
+    ///   otherwise
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create a typed envelope
+    /// const document = Envelope.new("Contract")
+    ///   .addType("LegalDocument")
+    ///   .addAssertion("status", "Draft");
+    ///
+    /// // Check for various types
+    /// console.log(document.hasType("LegalDocument")); // true
+    /// console.log(document.hasType("Spreadsheet")); // false
+    /// ```
+    hasType(t: EnvelopeEncodableValue): boolean;
+
+    /// Verifies that the envelope has a specific type.
+    ///
+    /// This method is similar to `hasType` but throws an error instead of
+    /// returning false, making it suitable for use in validation chains.
+    ///
+    /// @param t - The type to check for, which will be converted to an envelope
+    /// @throws {EnvelopeError} If the envelope does not have the specified type
+    ///
+    /// @example
+    /// ```typescript
+    /// // Function that processes a person
+    /// function processPerson(envelope: Envelope): string {
+    ///   // Verify this is a person
+    ///   envelope.checkType("Person");
+    ///
+    ///   // Extract the name
+    ///   const name = envelope.subject().extractString();
+    ///   return name;
+    /// }
+    ///
+    /// // Create a person envelope
+    /// const person = Envelope.new("Alice").addType("Person");
+    ///
+    /// // Process the person
+    /// const result = processPerson(person);
+    /// console.log(result); // "Alice"
+    ///
+    /// // Create a non-person envelope
+    /// const document = Envelope.new("Contract").addType("Document");
+    ///
+    /// // Processing will throw an error
+    /// try {
+    ///   processPerson(document);
+    /// } catch (e) {
+    ///   console.log("Not a person!");
+    /// }
+    /// ```
+    checkType(t: EnvelopeEncodableValue): void;
+  }
+}
+
+/// Implementation of addType()
+// eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+if (Envelope?.prototype) {
+  Envelope.prototype.addType = function (this: Envelope, object: EnvelopeEncodableValue): Envelope {
+    return this.addAssertion(IS_A, object);
+  };
+
+  /// Implementation of types()
+  Envelope.prototype.types = function (this: Envelope): Envelope[] {
+    return this.objectsForPredicate(IS_A);
+  };
+
+  /// Implementation of getType()
+  Envelope.prototype.getType = function (this: Envelope): Envelope {
+    const t = this.types();
+    if (t.length === 0) {
+      throw EnvelopeError.invalidType();
+    }
+    if (t.length === 1) {
+      return t[0];
+    }
+    throw EnvelopeError.ambiguousType();
+  };
+
+  /// Implementation of hasType()
+  Envelope.prototype.hasType = function (this: Envelope, t: EnvelopeEncodableValue): boolean {
+    const e = Envelope.new(t);
+    return this.types().some((x) => x.digest().equals(e.digest()));
+  };
+
+  /// Implementation of checkType()
+  Envelope.prototype.checkType = function (this: Envelope, t: EnvelopeEncodableValue): void {
+    if (!this.hasType(t)) {
+      throw EnvelopeError.invalidType();
+    }
+  };
+}

package/src/format/diagnostic.ts

@@ -0,0 +1,116 @@
+import { Envelope } from "../base/envelope";
+
+// Type for CBOR values that can appear in diagnostic notation
+type CborValue =
+  | string
+  | number
+  | boolean
+  | null
+  | Uint8Array
+  | CborValue[]
+  | Map<CborValue, CborValue>
+  | { tag: number; value: CborValue }
+  | { type: number; value: unknown };
+
+/// Diagnostic notation formatting for Gordian Envelopes.
+///
+/// This module provides methods for converting envelopes to CBOR diagnostic
+/// notation, a human-readable text format defined in RFC 8949 §8.
+///
+/// See [RFC-8949 §8](https://www.rfc-editor.org/rfc/rfc8949.html#name-diagnostic-notation)
+/// for information on CBOR diagnostic notation.
+
+// Note: Method declarations are in the base Envelope class.
+// This module provides the prototype implementations.
+
+/// Converts a CBOR value to diagnostic notation
+function cborToDiagnostic(cbor: CborValue, indent = 0): string {
+  // Handle tagged values (CBOR tags)
+  if (typeof cbor === "object" && cbor !== null && "tag" in cbor && "value" in cbor) {
+    const tagged = cbor as { tag: number; value: CborValue };
+    return `${tagged.tag}(${cborToDiagnostic(tagged.value, indent)})`;
+  }
+
+  // Handle arrays
+  if (Array.isArray(cbor)) {
+    if (cbor.length === 0) {
+      return "[]";
+    }
+    const items = cbor.map((item) => cborToDiagnostic(item, indent + 2));
+    return `[${items.join(", ")}]`;
+  }
+
+  // Handle Maps
+  if (cbor instanceof Map) {
+    if (cbor.size === 0) {
+      return "{}";
+    }
+    const entries: string[] = [];
+    for (const [key, value] of cbor) {
+      const keyStr = cborToDiagnostic(key, indent + 2);
+      const valueStr = cborToDiagnostic(value, indent + 2);
+      entries.push(`${keyStr}: ${valueStr}`);
+    }
+    return `{${entries.join(", ")}}`;
+  }
+
+  // Handle Uint8Array (byte strings)
+  if (cbor instanceof Uint8Array) {
+    const hex = Array.from(cbor)
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+    return `h'${hex}'`;
+  }
+
+  // Handle strings
+  if (typeof cbor === "string") {
+    return JSON.stringify(cbor);
+  }
+
+  // Handle CBOR objects with type information
+  if (typeof cbor === "object" && cbor !== null && "type" in cbor) {
+    const typed = cbor as { type: number; value: unknown };
+    switch (typed.type) {
+      case 0: // Unsigned
+        return String(typed.value);
+      case 1: // Negative
+        return String(-1 - Number(typed.value));
+      case 7: {
+        // Simple
+        const simpleValue = typed.value;
+        if (simpleValue !== null && typeof simpleValue === "object" && "type" in simpleValue) {
+          const floatValue = simpleValue as { type: string; value: unknown };
+          if (floatValue.type === "Float") {
+            return String(floatValue.value);
+          }
+        }
+        if (simpleValue === 20) return "false";
+        if (simpleValue === 21) return "true";
+        if (simpleValue === 22) return "null";
+        if (simpleValue === 23) return "undefined";
+        return `simple(${String(simpleValue)})`;
+      }
+    }
+  }
+
+  // Fallback for primitives
+  if (typeof cbor === "boolean") return String(cbor);
+  if (typeof cbor === "number") return String(cbor);
+  if (typeof cbor === "bigint") return String(cbor);
+  if (cbor === null) return "null";
+  if (cbor === undefined) return "undefined";
+
+  // Unknown type - try JSON stringify
+  try {
+    return JSON.stringify(cbor);
+  } catch {
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    return String(cbor);
+  }
+}
+
+/// Implementation of diagnostic()
+Envelope.prototype.diagnostic = function (this: Envelope): string {
+  const cbor = this.taggedCbor();
+  return cborToDiagnostic(cbor);
+};

package/src/format/hex.ts

@@ -0,0 +1,25 @@
+import { Envelope } from "../base/envelope";
+import { cborData } from "@bcts/dcbor";
+
+/// Hex formatting for Gordian Envelopes.
+///
+/// This module provides methods for converting envelopes to hexadecimal
+/// representations of their CBOR encoding, useful for debugging and
+/// low-level inspection.
+
+// Note: Method declarations are in the base Envelope class.
+// This module provides the prototype implementations.
+
+/// Implementation of hex()
+Envelope.prototype.hex = function (this: Envelope): string {
+  const bytes = this.cborBytes();
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+};
+
+/// Implementation of cborBytes()
+Envelope.prototype.cborBytes = function (this: Envelope): Uint8Array {
+  const cbor = this.taggedCbor();
+  return cborData(cbor);
+};

package/src/format/index.ts

@@ -0,0 +1,13 @@
+/// Format module exports for Gordian Envelope.
+///
+/// This module provides various formatting options for displaying and
+/// serializing envelopes, including hex, diagnostic, notation, tree,
+/// and mermaid diagram formats.
+
+// Export types
+export type { TreeFormatOptions } from "./tree";
+
+// Import side-effect modules to register prototype extensions
+import "./hex";
+import "./diagnostic";
+import "./tree";

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 {};