@bcts/envelope 1.0.0-alpha.10

package/src/base/queries.ts

@@ -0,0 +1,244 @@
+// 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.
+
+/// 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,215 @@
+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];
+
+/// 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,26 @@
+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.
+
+/// 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();
+};