@bcts/envelope 1.0.0-alpha.5

package/src/base/queries.ts

@@ -0,0 +1,374 @@
+// Cbor type available if needed later
+import { Envelope } from "./envelope";
+import type { EnvelopeEncodableValue } from "./envelope-encodable";
+import { EnvelopeError } from "./error";
+
+/// Provides methods for querying envelope structure and extracting data.
+///
+/// The `queries` module contains methods for:
+///
+/// 1. **Structural queries**: Methods for examining the envelope's structure
+///    (`subject()`, `assertions()`)
+/// 2. **Type queries**: Methods for determining the envelope's type
+///    (`isLeaf()`, `isNode()`, etc.)
+/// 3. **Content extraction**: Methods for extracting typed content from
+///    envelopes (`extractSubject()`, `extractObjectForPredicate()`)
+/// 4. **Assertion queries**: Methods for finding assertions with specific
+///    predicates (`assertionWithPredicate()`)
+///
+/// These methods enable traversal and inspection of envelope hierarchies,
+/// allowing for flexible manipulation and access to envelope data structures.
+
+declare module "./envelope" {
+  interface Envelope {
+    /// Returns true if the envelope has at least one assertion.
+    ///
+    /// @returns `true` if there are assertions, `false` otherwise
+    hasAssertions(): boolean;
+
+    /// Returns the envelope as an assertion if it is one.
+    ///
+    /// @returns The assertion envelope or undefined
+    asAssertion(): Envelope | undefined;
+
+    /// Returns the envelope as an assertion or throws an error.
+    ///
+    /// @returns The assertion envelope
+    /// @throws {EnvelopeError} If the envelope is not an assertion
+    tryAssertion(): Envelope;
+
+    /// Returns the predicate of this assertion envelope.
+    ///
+    /// @returns The predicate envelope or undefined
+    asPredicate(): Envelope | undefined;
+
+    /// Returns the predicate of this assertion envelope or throws an error.
+    ///
+    /// @returns The predicate envelope
+    /// @throws {EnvelopeError} If the envelope is not an assertion
+    tryPredicate(): Envelope;
+
+    /// Returns the object of this assertion envelope.
+    ///
+    /// @returns The object envelope or undefined
+    asObject(): Envelope | undefined;
+
+    /// Returns the object of this assertion envelope or throws an error.
+    ///
+    /// @returns The object envelope
+    /// @throws {EnvelopeError} If the envelope is not an assertion
+    tryObject(): Envelope;
+
+    /// Checks if this envelope is case Assertion.
+    ///
+    /// @returns `true` if this is an assertion envelope
+    isAssertion(): boolean;
+
+    /// Checks if this envelope is case Elided.
+    ///
+    /// @returns `true` if this is an elided envelope
+    isElided(): boolean;
+
+    /// Checks if this envelope is case Leaf.
+    ///
+    /// @returns `true` if this is a leaf envelope
+    isLeaf(): boolean;
+
+    /// Checks if this envelope is case Node.
+    ///
+    /// @returns `true` if this is a node envelope
+    isNode(): boolean;
+
+    /// Checks if this envelope is case Wrapped.
+    ///
+    /// @returns `true` if this is a wrapped envelope
+    isWrapped(): boolean;
+
+    /// Checks if this envelope is internal (has child elements).
+    ///
+    /// Internal elements include node, wrapped, and assertion.
+    ///
+    /// @returns `true` if this envelope has children
+    isInternal(): boolean;
+
+    /// Checks if this envelope is obscured (elided, encrypted, or compressed).
+    ///
+    /// @returns `true` if this envelope is obscured
+    isObscured(): boolean;
+
+    /// Returns all assertions with the given predicate.
+    ///
+    /// Match is performed by comparing digests.
+    ///
+    /// @param predicate - The predicate to search for
+    /// @returns An array of matching assertion envelopes
+    assertionsWithPredicate(predicate: EnvelopeEncodableValue): Envelope[];
+
+    /// Returns the assertion with the given predicate.
+    ///
+    /// @param predicate - The predicate to search for
+    /// @returns The matching assertion envelope
+    /// @throws {EnvelopeError} If no assertion or multiple assertions match
+    assertionWithPredicate(predicate: EnvelopeEncodableValue): Envelope;
+
+    /// Returns the assertion with the given predicate, or undefined if not
+    /// found.
+    ///
+    /// @param predicate - The predicate to search for
+    /// @returns The matching assertion envelope or undefined
+    /// @throws {EnvelopeError} If multiple assertions match
+    optionalAssertionWithPredicate(predicate: EnvelopeEncodableValue): Envelope | undefined;
+
+    /// Returns the object of the assertion with the given predicate.
+    ///
+    /// @param predicate - The predicate to search for
+    /// @returns The object envelope
+    /// @throws {EnvelopeError} If no assertion or multiple assertions match
+    objectForPredicate(predicate: EnvelopeEncodableValue): Envelope;
+
+    /// Returns the object of the assertion with the given predicate, or
+    /// undefined if not found.
+    ///
+    /// @param predicate - The predicate to search for
+    /// @returns The object envelope or undefined
+    /// @throws {EnvelopeError} If multiple assertions match
+    optionalObjectForPredicate(predicate: EnvelopeEncodableValue): Envelope | undefined;
+
+    /// Returns the objects of all assertions with the matching predicate.
+    ///
+    /// @param predicate - The predicate to search for
+    /// @returns An array of object envelopes
+    objectsForPredicate(predicate: EnvelopeEncodableValue): Envelope[];
+
+    /// Returns the number of structural elements in the envelope.
+    ///
+    /// This includes the envelope itself and all nested elements.
+    ///
+    /// @returns The total element count
+    elementsCount(): number;
+  }
+}
+
+/// Implementation of hasAssertions()
+Envelope.prototype.hasAssertions = function (this: Envelope): boolean {
+  const c = this.case();
+  return c.type === "node" && c.assertions.length > 0;
+};
+
+/// Implementation of asAssertion()
+Envelope.prototype.asAssertion = function (this: Envelope): Envelope | undefined {
+  const c = this.case();
+  return c.type === "assertion" ? this : undefined;
+};
+
+/// Implementation of tryAssertion()
+Envelope.prototype.tryAssertion = function (this: Envelope): Envelope {
+  const result = this.asAssertion();
+  if (result === undefined) {
+    throw EnvelopeError.notAssertion();
+  }
+  return result;
+};
+
+/// Implementation of asPredicate()
+Envelope.prototype.asPredicate = function (this: Envelope): Envelope | undefined {
+  // Refer to subject in case the assertion is a node and therefore has
+  // its own assertions
+  const subj = this.subject();
+  const c = subj.case();
+  if (c.type === "assertion") {
+    return c.assertion.predicate();
+  }
+  return undefined;
+};
+
+/// Implementation of tryPredicate()
+Envelope.prototype.tryPredicate = function (this: Envelope): Envelope {
+  const result = this.asPredicate();
+  if (result === undefined) {
+    throw EnvelopeError.notAssertion();
+  }
+  return result;
+};
+
+/// Implementation of asObject()
+Envelope.prototype.asObject = function (this: Envelope): Envelope | undefined {
+  // Refer to subject in case the assertion is a node and therefore has
+  // its own assertions
+  const subj = this.subject();
+  const c = subj.case();
+  if (c.type === "assertion") {
+    return c.assertion.object();
+  }
+  return undefined;
+};
+
+/// Implementation of tryObject()
+Envelope.prototype.tryObject = function (this: Envelope): Envelope {
+  const result = this.asObject();
+  if (result === undefined) {
+    throw EnvelopeError.notAssertion();
+  }
+  return result;
+};
+
+/// Implementation of isAssertion()
+Envelope.prototype.isAssertion = function (this: Envelope): boolean {
+  return this.case().type === "assertion";
+};
+
+/// Implementation of isElided()
+Envelope.prototype.isElided = function (this: Envelope): boolean {
+  return this.case().type === "elided";
+};
+
+/// Implementation of isLeaf()
+Envelope.prototype.isLeaf = function (this: Envelope): boolean {
+  return this.case().type === "leaf";
+};
+
+/// Implementation of isNode()
+Envelope.prototype.isNode = function (this: Envelope): boolean {
+  return this.case().type === "node";
+};
+
+/// Implementation of isWrapped()
+Envelope.prototype.isWrapped = function (this: Envelope): boolean {
+  return this.case().type === "wrapped";
+};
+
+/// Implementation of isInternal()
+Envelope.prototype.isInternal = function (this: Envelope): boolean {
+  const type = this.case().type;
+  return type === "node" || type === "wrapped" || type === "assertion";
+};
+
+/// Implementation of isObscured()
+Envelope.prototype.isObscured = function (this: Envelope): boolean {
+  const type = this.case().type;
+  return type === "elided" || type === "encrypted" || type === "compressed";
+};
+
+/// Implementation of assertionsWithPredicate()
+Envelope.prototype.assertionsWithPredicate = function (
+  this: Envelope,
+  predicate: EnvelopeEncodableValue,
+): Envelope[] {
+  const predicateEnv = Envelope.new(predicate);
+  const predicateDigest = predicateEnv.digest();
+
+  return this.assertions().filter((assertion) => {
+    const pred = assertion.subject().asPredicate();
+    return pred?.digest().equals(predicateDigest) === true;
+  });
+};
+
+/// Implementation of assertionWithPredicate()
+Envelope.prototype.assertionWithPredicate = function (
+  this: Envelope,
+  predicate: EnvelopeEncodableValue,
+): Envelope {
+  const matches = this.assertionsWithPredicate(predicate);
+
+  if (matches.length === 0) {
+    throw EnvelopeError.nonexistentPredicate();
+  }
+  if (matches.length > 1) {
+    throw EnvelopeError.ambiguousPredicate();
+  }
+
+  return matches[0];
+};
+
+/// Implementation of optionalAssertionWithPredicate()
+Envelope.prototype.optionalAssertionWithPredicate = function (
+  this: Envelope,
+  predicate: EnvelopeEncodableValue,
+): Envelope | undefined {
+  const matches = this.assertionsWithPredicate(predicate);
+
+  if (matches.length === 0) {
+    return undefined;
+  }
+  if (matches.length > 1) {
+    throw EnvelopeError.ambiguousPredicate();
+  }
+
+  return matches[0];
+};
+
+/// Implementation of objectForPredicate()
+Envelope.prototype.objectForPredicate = function (
+  this: Envelope,
+  predicate: EnvelopeEncodableValue,
+): Envelope {
+  const assertion = this.assertionWithPredicate(predicate);
+  const obj = assertion.asObject();
+  if (obj === undefined) {
+    throw EnvelopeError.notAssertion();
+  }
+  return obj;
+};
+
+/// Implementation of optionalObjectForPredicate()
+Envelope.prototype.optionalObjectForPredicate = function (
+  this: Envelope,
+  predicate: EnvelopeEncodableValue,
+): Envelope | undefined {
+  const matches = this.assertionsWithPredicate(predicate);
+
+  if (matches.length === 0) {
+    return undefined;
+  }
+  if (matches.length > 1) {
+    throw EnvelopeError.ambiguousPredicate();
+  }
+
+  const obj = matches[0].subject().asObject();
+  return obj;
+};
+
+/// Implementation of objectsForPredicate()
+Envelope.prototype.objectsForPredicate = function (
+  this: Envelope,
+  predicate: EnvelopeEncodableValue,
+): Envelope[] {
+  return this.assertionsWithPredicate(predicate).map((assertion) => {
+    const obj = assertion.asObject();
+    if (obj === undefined) {
+      throw EnvelopeError.notAssertion();
+    }
+    return obj;
+  });
+};
+
+/// Implementation of elementsCount()
+Envelope.prototype.elementsCount = function (this: Envelope): number {
+  let count = 1; // Count this envelope
+
+  const c = this.case();
+  switch (c.type) {
+    case "node":
+      count += c.subject.elementsCount();
+      for (const assertion of c.assertions) {
+        count += assertion.elementsCount();
+      }
+      break;
+    case "assertion":
+      count += c.assertion.predicate().elementsCount();
+      count += c.assertion.object().elementsCount();
+      break;
+    case "wrapped":
+      count += c.envelope.elementsCount();
+      break;
+    case "leaf":
+    case "elided":
+    case "knownValue":
+    case "encrypted":
+    case "compressed":
+      // These cases don't contribute additional elements
+      break;
+  }
+
+  return count;
+};

package/src/base/walk.ts

@@ -0,0 +1,241 @@
+import { Envelope } from "./envelope";
+
+/// Functions for traversing and manipulating the envelope hierarchy.
+///
+/// This module provides functionality for traversing the hierarchical structure
+/// of envelopes, allowing for operations such as inspection, transformation,
+/// and extraction of specific elements. It implements a visitor pattern that
+/// enables executing arbitrary code on each element of an envelope in a
+/// structured way.
+///
+/// The traversal can be performed in two modes:
+/// - Structure-based traversal: Visits every element in the envelope hierarchy
+/// - Tree-based traversal: Skips node elements and focuses on the semantic
+///   content
+
+/// The type of incoming edge provided to the visitor.
+///
+/// This enum identifies how an envelope element is connected to its parent in
+/// the hierarchy during traversal. It helps the visitor function understand the
+/// semantic relationship between elements.
+export enum EdgeType {
+  /// No incoming edge (root)
+  None = "none",
+  /// Element is the subject of a node
+  Subject = "subject",
+  /// Element is an assertion on a node
+  Assertion = "assertion",
+  /// Element is the predicate of an assertion
+  Predicate = "predicate",
+  /// Element is the object of an assertion
+  Object = "object",
+  /// Element is the content wrapped by another envelope
+  Content = "content",
+}
+
+/// Returns a short text label for the edge type, or undefined if no label is
+/// needed.
+///
+/// This is primarily used for tree formatting to identify relationships
+/// between elements.
+///
+/// @param edgeType - The edge type
+/// @returns A short label or undefined
+export function edgeLabel(edgeType: EdgeType): string | undefined {
+  switch (edgeType) {
+    case EdgeType.Subject:
+      return "subj";
+    case EdgeType.Content:
+      return "cont";
+    case EdgeType.Predicate:
+      return "pred";
+    case EdgeType.Object:
+      return "obj";
+    case EdgeType.None:
+    case EdgeType.Assertion:
+      return undefined;
+    default:
+      return undefined;
+  }
+}
+
+/// A visitor function that is called for each element in the envelope.
+///
+/// The visitor function takes the following parameters:
+/// - `envelope`: The current envelope element being visited
+/// - `level`: The depth level in the hierarchy (0 for root)
+/// - `incomingEdge`: The type of edge connecting this element to its parent
+/// - `state`: Optional context passed down from the parent's visitor call
+///
+/// The visitor returns a tuple of:
+/// - The state that will be passed to child elements
+/// - A boolean indicating whether to stop traversal (true = stop)
+///
+/// This enables accumulating state or passing context during traversal.
+export type Visitor<State> = (
+  envelope: Envelope,
+  level: number,
+  incomingEdge: EdgeType,
+  state: State,
+) => [State, boolean];
+
+declare module "./envelope" {
+  interface Envelope {
+    /// Walks the envelope structure, calling the visitor function for each
+    /// element.
+    ///
+    /// This function traverses the entire envelope hierarchy and calls the
+    /// visitor function on each element. The traversal can be performed in
+    /// two modes:
+    ///
+    /// - Structure-based traversal (`hideNodes = false`): Visits every element
+    ///   including node containers
+    /// - Tree-based traversal (`hideNodes = true`): Skips node elements and
+    ///   focuses on semantic content
+    ///
+    /// The visitor function can optionally return a context value that is
+    /// passed to child elements, enabling state to be accumulated or passed
+    /// down during traversal.
+    ///
+    /// @param hideNodes - If true, the visitor will not be called for node
+    ///   containers
+    /// @param state - Initial state passed to the visitor
+    /// @param visit - The visitor function called for each element
+    walk<State>(hideNodes: boolean, state: State, visit: Visitor<State>): void;
+  }
+}
+
+/// Implementation of walk()
+Envelope.prototype.walk = function <State>(
+  this: Envelope,
+  hideNodes: boolean,
+  state: State,
+  visit: Visitor<State>,
+): void {
+  if (hideNodes) {
+    walkTree(this, 0, EdgeType.None, state, visit);
+  } else {
+    walkStructure(this, 0, EdgeType.None, state, visit);
+  }
+};
+
+/// Recursive implementation of structure-based traversal.
+///
+/// This internal function performs the actual recursive traversal of the
+/// envelope structure, visiting every element and maintaining the
+/// correct level and edge relationships.
+function walkStructure<State>(
+  envelope: Envelope,
+  level: number,
+  incomingEdge: EdgeType,
+  state: State,
+  visit: Visitor<State>,
+): void {
+  // Visit this envelope
+  const [newState, stop] = visit(envelope, level, incomingEdge, state);
+  if (stop) {
+    return;
+  }
+
+  const nextLevel = level + 1;
+  const c = envelope.case();
+
+  switch (c.type) {
+    case "node":
+      // Visit subject
+      walkStructure(c.subject, nextLevel, EdgeType.Subject, newState, visit);
+      // Visit all assertions
+      for (const assertion of c.assertions) {
+        walkStructure(assertion, nextLevel, EdgeType.Assertion, newState, visit);
+      }
+      break;
+
+    case "wrapped":
+      // Visit wrapped envelope
+      walkStructure(c.envelope, nextLevel, EdgeType.Content, newState, visit);
+      break;
+
+    case "assertion":
+      // Visit predicate and object
+      walkStructure(c.assertion.predicate(), nextLevel, EdgeType.Predicate, newState, visit);
+      walkStructure(c.assertion.object(), nextLevel, EdgeType.Object, newState, visit);
+      break;
+
+    case "leaf":
+    case "elided":
+    case "knownValue":
+    case "encrypted":
+    case "compressed":
+      // Leaf nodes and other types have no children
+      break;
+  }
+}
+
+/// Recursive implementation of tree-based traversal.
+///
+/// This internal function performs the actual recursive traversal of the
+/// envelope's semantic tree, skipping node containers and focusing on
+/// the semantic content elements. It maintains the correct level and
+/// edge relationships while skipping structural elements.
+function walkTree<State>(
+  envelope: Envelope,
+  level: number,
+  incomingEdge: EdgeType,
+  state: State,
+  visit: Visitor<State>,
+): State {
+  let currentState = state;
+  let subjectLevel = level;
+
+  // Skip visiting if this is a node
+  if (!envelope.isNode()) {
+    const [newState, stop] = visit(envelope, level, incomingEdge, currentState);
+    if (stop) {
+      return newState;
+    }
+    currentState = newState;
+    subjectLevel = level + 1;
+  }
+
+  const c = envelope.case();
+
+  switch (c.type) {
+    case "node": {
+      // Visit subject
+      const assertionState = walkTree(
+        c.subject,
+        subjectLevel,
+        EdgeType.Subject,
+        currentState,
+        visit,
+      );
+      // Visit all assertions
+      const assertionLevel = subjectLevel + 1;
+      for (const assertion of c.assertions) {
+        walkTree(assertion, assertionLevel, EdgeType.Assertion, assertionState, visit);
+      }
+      break;
+    }
+
+    case "wrapped":
+      // Visit wrapped envelope
+      walkTree(c.envelope, subjectLevel, EdgeType.Content, currentState, visit);
+      break;
+
+    case "assertion":
+      // Visit predicate and object
+      walkTree(c.assertion.predicate(), subjectLevel, EdgeType.Predicate, currentState, visit);
+      walkTree(c.assertion.object(), subjectLevel, EdgeType.Object, currentState, visit);
+      break;
+
+    case "leaf":
+    case "elided":
+    case "knownValue":
+    case "encrypted":
+    case "compressed":
+      // Leaf nodes and other types have no children
+      break;
+  }
+
+  return currentState;
+}

package/src/base/wrap.ts

@@ -0,0 +1,72 @@
+import { Envelope } from "./envelope";
+import { EnvelopeError } from "./error";
+
+/// Support for wrapping and unwrapping envelopes.
+///
+/// Wrapping allows treating an envelope (including its assertions) as a single
+/// unit, making it possible to add assertions about the envelope as a whole.
+
+declare module "./envelope" {
+  interface Envelope {
+    /// Returns a new envelope which wraps the current envelope.
+    ///
+    /// Wrapping an envelope allows you to treat an envelope (including its
+    /// assertions) as a single unit, making it possible to add assertions
+    /// about the envelope as a whole.
+    ///
+    /// @returns A new wrapped envelope
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create an envelope with an assertion
+    /// const envelope = Envelope.new("Hello.").addAssertion("language", "English");
+    ///
+    /// // Wrap it to add an assertion about the envelope as a whole
+    /// const wrapped = envelope.wrap().addAssertion("authenticated", true);
+    /// ```
+    wrap(): Envelope;
+
+    /// Unwraps and returns the inner envelope.
+    ///
+    /// This extracts the envelope contained within a wrapped envelope.
+    ///
+    /// @returns The unwrapped envelope
+    /// @throws {EnvelopeError} If this is not a wrapped envelope
+    ///
+    /// @example
+    /// ```typescript
+    /// // Create an envelope and wrap it
+    /// const envelope = Envelope.new("Hello.");
+    /// const wrapped = envelope.wrap();
+    ///
+    /// // Unwrap to get the original envelope
+    /// const unwrapped = wrapped.tryUnwrap();
+    /// ```
+    tryUnwrap(): Envelope;
+
+    /// Alias for tryUnwrap() - unwraps and returns the inner envelope.
+    ///
+    /// @returns The unwrapped envelope
+    /// @throws {EnvelopeError} If this is not a wrapped envelope
+    unwrap(): Envelope;
+  }
+}
+
+/// Implementation of wrap()
+Envelope.prototype.wrap = function (this: Envelope): Envelope {
+  return Envelope.newWrapped(this);
+};
+
+/// Implementation of tryUnwrap()
+Envelope.prototype.tryUnwrap = function (this: Envelope): Envelope {
+  const c = this.subject().case();
+  if (c.type === "wrapped") {
+    return c.envelope;
+  }
+  throw EnvelopeError.notWrapped();
+};
+
+/// Implementation of unwrap() - alias for tryUnwrap()
+Envelope.prototype.unwrap = function (this: Envelope): Envelope {
+  return this.tryUnwrap();
+};