@bcts/envelope-pattern 1.0.0-alpha.22 → 1.0.0-beta.0

package/src/parse/structure/node-parser.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Node parser — port of `bc-envelope-pattern-rust`
+ * `parse/structure/node_parser.rs`.
+ *
+ * Mirrors Rust:
+ * - Bare `node` → `any_node()`.
+ * - `node({n})` / `node({n,m})` / `node({n,})` → `node_with_assertions_range`.
+ * - Anything else inside the parens (e.g. `node(text)`) is a syntax error
+ *   in Rust; the previous TS port silently produced an always-matching
+ *   `WithSubject` node, which we have removed.
+ *
+ * @module envelope-pattern/parse/structure/node-parser
+ */
+
+import {
+  type Result,
+  err,
+  expectedCloseParen,
+  ok,
+  unexpectedEndOfInput,
+  unexpectedToken,
+} from "../../error";
+import { type Pattern, NodePattern, anyNode, patternStructure, structureNode } from "../../pattern";
+import type { Lexer } from "../token";
+
+export function parseNode(lexer: Lexer): Result<Pattern> {
+  const next = lexer.peekToken();
+  if (next?.token.type !== "ParenOpen") {
+    return ok(anyNode());
+  }
+  lexer.next(); // consume (
+
+  const inner = lexer.next();
+  if (inner === undefined) {
+    return err(unexpectedEndOfInput());
+  }
+  if (inner.token.type !== "Range") {
+    return err(unexpectedToken(inner.token, inner.span));
+  }
+  if (!inner.token.value.ok) return err(inner.token.value.error);
+  const interval = inner.token.value.value.interval();
+
+  const close = lexer.next();
+  if (close === undefined) {
+    return err(expectedCloseParen(lexer.span()));
+  }
+  if (close.token.type !== "ParenClose") {
+    return err(unexpectedToken(close.token, close.span));
+  }
+  return ok(patternStructure(structureNode(NodePattern.fromInterval(interval))));
+}

package/src/parse/structure/object-parser.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Object parser — port of `bc-envelope-pattern-rust`
+ * `parse/structure/object_parser.rs`.
+ *
+ * @module envelope-pattern/parse/structure/object-parser
+ */
+
+import { type Result, err, expectedCloseParen, ok, unexpectedToken } from "../../error";
+import { type Pattern, anyObject, object } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseOr } from "../meta/or-parser";
+
+export function parseObject(lexer: Lexer): Result<Pattern> {
+  const next = lexer.peekToken();
+  if (next?.token.type !== "ParenOpen") {
+    return ok(anyObject());
+  }
+  lexer.next(); // consume (
+  const inner = parseOr(lexer);
+  if (!inner.ok) return inner;
+  const close = lexer.next();
+  if (close === undefined) {
+    return err(expectedCloseParen(lexer.span()));
+  }
+  if (close.token.type !== "ParenClose") {
+    return err(unexpectedToken(close.token, close.span));
+  }
+  return ok(object(inner.value));
+}

package/src/parse/structure/obscured-parser.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Obscured parser — port of `bc-envelope-pattern-rust`
+ * `parse/structure/obscured_parser.rs`.
+ *
+ * @module envelope-pattern/parse/structure/obscured-parser
+ */
+
+import { type Result, ok } from "../../error";
+import { type Pattern, obscured } from "../../pattern";
+import type { Lexer } from "../token";
+
+export function parseObscured(_lexer: Lexer): Result<Pattern> {
+  return ok(obscured());
+}

package/src/parse/structure/predicate-parser.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Predicate parser — port of `bc-envelope-pattern-rust`
+ * `parse/structure/predicate_parser.rs`.
+ *
+ * @module envelope-pattern/parse/structure/predicate-parser
+ */
+
+import { type Result, err, expectedCloseParen, ok, unexpectedToken } from "../../error";
+import { type Pattern, anyPredicate, predicate } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseOr } from "../meta/or-parser";
+
+export function parsePredicate(lexer: Lexer): Result<Pattern> {
+  const next = lexer.peekToken();
+  if (next?.token.type !== "ParenOpen") {
+    return ok(anyPredicate());
+  }
+  lexer.next(); // consume (
+  const inner = parseOr(lexer);
+  if (!inner.ok) return inner;
+  const close = lexer.next();
+  if (close === undefined) {
+    return err(expectedCloseParen(lexer.span()));
+  }
+  if (close.token.type !== "ParenClose") {
+    return err(unexpectedToken(close.token, close.span));
+  }
+  return ok(predicate(inner.value));
+}

package/src/parse/structure/subject-parser.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Subject parser — port of `bc-envelope-pattern-rust`
+ * `parse/structure/subject_parser.rs`.
+ *
+ * @module envelope-pattern/parse/structure/subject-parser
+ */
+
+import { type Result, err, expectedCloseParen, ok, unexpectedToken } from "../../error";
+import { type Pattern, anySubject, subject } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseOr } from "../meta/or-parser";
+
+export function parseSubject(lexer: Lexer): Result<Pattern> {
+  const next = lexer.peekToken();
+  if (next?.token.type !== "ParenOpen") {
+    return ok(anySubject());
+  }
+  lexer.next(); // consume (
+  const inner = parseOr(lexer);
+  if (!inner.ok) return inner;
+  const close = lexer.next();
+  if (close === undefined) {
+    return err(expectedCloseParen(lexer.span()));
+  }
+  if (close.token.type !== "ParenClose") {
+    return err(unexpectedToken(close.token, close.span));
+  }
+  return ok(subject(inner.value));
+}

package/src/parse/structure/wrapped-parser.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Wrapped/unwrap parser — port of `bc-envelope-pattern-rust`
+ * `parse/structure/wrapped_parser.rs`.
+ *
+ * @module envelope-pattern/parse/structure/wrapped-parser
+ */
+
+import { type Result, err, expectedCloseParen, ok, unexpectedToken } from "../../error";
+import { type Pattern, unwrapEnvelope, unwrapMatching, wrapped } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseOr } from "../meta/or-parser";
+
+export function parseWrapped(_lexer: Lexer): Result<Pattern> {
+  return ok(wrapped());
+}
+
+export function parseUnwrap(lexer: Lexer): Result<Pattern> {
+  const next = lexer.peekToken();
+  if (next?.token.type !== "ParenOpen") {
+    return ok(unwrapEnvelope());
+  }
+  lexer.next(); // consume (
+  const inner = parseOr(lexer);
+  if (!inner.ok) return inner;
+  const close = lexer.next();
+  if (close === undefined) {
+    return err(expectedCloseParen(lexer.span()));
+  }
+  if (close.token.type !== "ParenClose") {
+    return err(unexpectedToken(close.token, close.span));
+  }
+  return ok(unwrapMatching(inner.value));
+}

package/src/pattern/dcbor-integration.ts

@@ -135,17 +135,49 @@ function convertStructurePatternToEnvelopePattern(
 ): Result<Pattern> {
   switch (structurePattern.type) {
     case "Array": {
-      // Wrap the full dcbor pattern for array matching
-      const arrayPattern = ArrayPattern.fromDcborPattern({
-        kind: "Structure",
-        pattern: structurePattern,
-      });
+      // Mirror Rust `convert_structure_pattern_to_envelope_pattern`'s
+      // `Array` arm: dispatch on the dcbor `ArrayPattern` variant so
+      // that `array` (Any) round-trips to `array`, `[{n,m}]` (Length)
+      // round-trips to `[{n,m}]`, and only Elements variants stay
+      // wrapped. Using `fromDcborPattern` for the Any variant produces
+      // an `Elements`-wrapped pattern that prints as `[array]`,
+      // breaking parser parity.
+      const inner = structurePattern.pattern;
+      let arrayPattern: ArrayPattern;
+      switch (inner.variant) {
+        case "Any":
+          arrayPattern = ArrayPattern.any();
+          break;
+        case "Length":
+          arrayPattern = ArrayPattern.fromInterval(inner.length);
+          break;
+        case "Elements":
+          arrayPattern = ArrayPattern.fromDcborArrayPattern(inner);
+          break;
+      }
       return ok({ type: "Leaf", pattern: leafArray(arrayPattern) });
     }
     case "Map": {
-      // MapPattern only supports interval-based matching currently
-      // Use any() for general map patterns from dcbor
-      const mapPattern = MapPattern.any();
+      // Mirror Rust's variant dispatch — preserve `{{n,m}}` length
+      // info instead of collapsing every map pattern to `Any` (which
+      // breaks parser parity for `{{3}}`, `{{2,4}}`, `{{2,}}`).
+      const inner = structurePattern.pattern;
+      let mapPattern: MapPattern;
+      switch (inner.variant) {
+        case "Any":
+          mapPattern = MapPattern.any();
+          break;
+        case "Length":
+          mapPattern = MapPattern.fromInterval(inner.length);
+          break;
+        case "Constraints":
+          // The envelope-pattern `MapPattern` doesn't yet model dcbor
+          // map constraints. Falling back to `Any` is conservative —
+          // round-trip parity here is broken until envelope-pattern
+          // grows a constraints variant.
+          mapPattern = MapPattern.any();
+          break;
+      }
       return ok({ type: "Leaf", pattern: leafMap(mapPattern) });
     }
     case "Tagged": {

package/src/pattern/index.ts

@@ -110,6 +110,9 @@ import {
   registerObscuredPatternFactory,
   registerWrappedPatternFactory,
   registerWrappedPatternDispatch,
+  registerWrappedPatternAny,
+  registerAssertionsPatternToStringDispatch,
+  registerSubjectPatternDispatch,
 } from "./structure";
 
 // Import meta patterns
@@ -801,6 +804,12 @@ function registerAllFactories(): void {
     compile: patternCompile,
     toString: patternToString,
   });
+  registerWrappedPatternAny(any);
+  registerAssertionsPatternToStringDispatch(patternToString);
+  registerSubjectPatternDispatch({
+    compile: patternCompile,
+    toString: patternToString,
+  });
 
   // Meta pattern factories
   registerAnyPatternFactory((p) => patternMeta(metaAny(p)));
@@ -820,6 +829,26 @@ registerAllFactories();
 import { registerVMPatternFunctions } from "./vm";
 registerVMPatternFunctions(patternPathsWithCaptures, patternMatches, patternPaths);
 
+// Register pattern-construction factories used by `parse/utils.ts` while it
+// runs `parse_cbor_inner` / `parse_array_inner`. These mirror Rust's direct
+// calls to `Pattern::cbor_pattern`, `Pattern::any_array`, etc. — exposed
+// here as factory hooks because the parser sits one module layer below the
+// `Pattern` factories and would otherwise create a circular import.
+import { registerPatternFactories as registerParseUtilsFactories } from "../parse/utils";
+import { type Pattern as DCBORPatternRegister } from "@bcts/dcbor-pattern";
+import type { Cbor } from "@bcts/dcbor";
+
+registerParseUtilsFactories({
+  cborPattern: (value: Cbor) => cborValue(value),
+  cborPatternFromDcbor: (pattern: DCBORPatternRegister) => cborPattern(pattern),
+  anyArray,
+  arrayWithCount: (count: number) => patternLeaf(leafArray(ArrayPattern.count(count))),
+  arrayWithRange: (min: number, max?: number) =>
+    patternLeaf(leafArray(ArrayPattern.interval(min, max))),
+  arrayFromDcborPattern: (pattern: DCBORPatternRegister) =>
+    patternLeaf(leafArray(ArrayPattern.fromDcborPattern(pattern))),
+});
+
 // Register pattern dispatch functions for meta patterns
 import { registerPatternMatchFn, registerPatternDispatchFns } from "./matcher";
 registerPatternMatchFn(patternMatches);

package/src/pattern/leaf/array-pattern.ts

@@ -5,17 +5,29 @@
  *
  * @bcts/envelope-pattern - Array pattern matching
  *
- * This is a 1:1 TypeScript port of bc-envelope-pattern-rust array_pattern.rs
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust array_pattern.rs.
+ *
+ * Like the Rust port, this is a thin wrapper around `dcbor_pattern::ArrayPattern`
+ * that delegates all matching to dcbor-pattern. The envelope-pattern's
+ * `ArrayPattern` adds nothing beyond extracting the leaf CBOR from the
+ * envelope subject before delegating.
  *
  * @module envelope-pattern/pattern/leaf/array-pattern
  */
 
-import { Envelope } from "@bcts/envelope";
-import { asCborArray, type Cbor } from "@bcts/dcbor";
+import type { Envelope } from "@bcts/envelope";
 import {
+  type ArrayPattern as DCBORArrayPattern,
   type Pattern as DCBORPattern,
-  Interval,
-  patternPathsWithCaptures as dcborPatternPathsWithCaptures,
+  type Interval,
+  arrayPatternAny,
+  arrayPatternMatches,
+  arrayPatternWithElements,
+  arrayPatternWithLength,
+  arrayPatternWithLengthInterval,
+  arrayPatternWithLengthRange,
+  arrayPatternDisplay,
+  arrayPatternEquals,
   patternDisplay as dcborPatternDisplay,
 } from "@bcts/dcbor-pattern";
 import type { Path } from "../../format";
@@ -32,25 +44,16 @@ export function registerArrayPatternFactory(factory: (pattern: ArrayPattern) =>
 }
 
 /**
- * Pattern for matching array values.
+ * Pattern for matching arrays.
  *
- * Corresponds to the Rust `ArrayPattern` enum in array_pattern.rs
- */
-export type ArrayPatternType =
-  | { readonly type: "Any" }
-  | { readonly type: "Interval"; readonly interval: Interval }
-  | { readonly type: "DCBORPattern"; readonly pattern: DCBORPattern }
-  | { readonly type: "WithPatterns"; readonly patterns: Pattern[] };
-
-/**
- * Pattern for matching array values in envelope leaf nodes.
- *
- * Corresponds to the Rust `ArrayPattern` struct in array_pattern.rs
+ * Mirrors Rust `ArrayPattern(dcbor_pattern::ArrayPattern)` from
+ * `bc-envelope-pattern-rust/src/pattern/leaf/array_pattern.rs`. All
+ * matching, display, and equality is delegated to dcbor-pattern.
  */
 export class ArrayPattern implements Matcher {
-  private readonly _pattern: ArrayPatternType;
+  private readonly _pattern: DCBORArrayPattern;
 
-  private constructor(pattern: ArrayPatternType) {
+  private constructor(pattern: DCBORArrayPattern) {
     this._pattern = pattern;
   }
 
@@ -58,124 +61,65 @@ export class ArrayPattern implements Matcher {
    * Creates a new ArrayPattern that matches any array.
    */
   static any(): ArrayPattern {
-    return new ArrayPattern({ type: "Any" });
+    return new ArrayPattern(arrayPatternAny());
   }
 
   /**
    * Creates a new ArrayPattern that matches arrays with a specific length.
    */
   static count(count: number): ArrayPattern {
-    return new ArrayPattern({
-      type: "Interval",
-      interval: Interval.exactly(count),
-    });
+    return new ArrayPattern(arrayPatternWithLength(count));
   }
 
   /**
    * Creates a new ArrayPattern that matches arrays within a length range.
    */
   static interval(min: number, max?: number): ArrayPattern {
-    const interval = max !== undefined ? Interval.from(min, max) : Interval.atLeast(min);
-    return new ArrayPattern({ type: "Interval", interval });
+    return new ArrayPattern(arrayPatternWithLengthRange(min, max));
+  }
+
+  /**
+   * Creates a new ArrayPattern from a length Interval.
+   */
+  static fromInterval(interval: Interval): ArrayPattern {
+    return new ArrayPattern(arrayPatternWithLengthInterval(interval));
   }
 
   /**
-   * Creates a new ArrayPattern from a dcbor-pattern.
+   * Creates a new ArrayPattern from a top-level dcbor-pattern.
+   *
+   * Mirrors Rust `ArrayPattern::from_dcbor_pattern`, which constructs an
+   * `ArrayPattern::Elements`-style dcbor array pattern.
    */
-  static fromDcborPattern(dcborPattern: DCBORPattern): ArrayPattern {
-    return new ArrayPattern({ type: "DCBORPattern", pattern: dcborPattern });
+  static fromDcborPattern(pattern: DCBORPattern): ArrayPattern {
+    return new ArrayPattern(arrayPatternWithElements(pattern));
   }
 
   /**
-   * Creates a new ArrayPattern with envelope patterns for element matching.
+   * Creates a new ArrayPattern from an existing dcbor-pattern ArrayPattern.
+   *
+   * Mirrors Rust `ArrayPattern::from_dcbor_array_pattern`.
    */
-  static withPatterns(patterns: Pattern[]): ArrayPattern {
-    return new ArrayPattern({ type: "WithPatterns", patterns });
+  static fromDcborArrayPattern(arrayPattern: DCBORArrayPattern): ArrayPattern {
+    return new ArrayPattern(arrayPattern);
   }
 
   /**
-   * Gets the pattern type.
+   * Returns the underlying dcbor-pattern ArrayPattern.
    */
-  get pattern(): ArrayPatternType {
+  inner(): DCBORArrayPattern {
     return this._pattern;
   }
 
   pathsWithCaptures(haystack: Envelope): [Path[], Map<string, Path[]>] {
-    // Try to extract CBOR from the envelope
     const cbor = haystack.subject().asLeaf();
     if (cbor === undefined) {
       return [[], new Map<string, Path[]>()];
     }
-
-    // Check if it's an array
-    const array = asCborArray(cbor);
-    if (array === undefined) {
-      return [[], new Map<string, Path[]>()];
-    }
-
-    switch (this._pattern.type) {
-      case "Any":
-        return [[[haystack]], new Map<string, Path[]>()];
-
-      case "Interval": {
-        const length = array.length;
-        if (this._pattern.interval.contains(length)) {
-          return [[[haystack]], new Map<string, Path[]>()];
-        }
-        return [[], new Map<string, Path[]>()];
-      }
-
-      case "DCBORPattern": {
-        // Delegate to dcbor-pattern for matching
-        const { paths: dcborPaths, captures: dcborCaptures } = dcborPatternPathsWithCaptures(
-          this._pattern.pattern,
-          cbor,
-        );
-
-        if (dcborPaths.length > 0) {
-          // Convert dcbor paths to envelope paths
-          const envelopePaths: Path[] = dcborPaths.map((dcborPath: Cbor[]) => {
-            const envPath: Path = [haystack];
-            // Skip the first element (root) and convert rest to envelopes
-            for (let i = 1; i < dcborPath.length; i++) {
-              const elem = dcborPath[i];
-              if (elem !== undefined) {
-                envPath.push(Envelope.newLeaf(elem));
-              }
-            }
-            return envPath;
-          });
-
-          // Convert dcbor captures to envelope captures
-          const envelopeCaptures = new Map<string, Path[]>();
-          for (const [name, capturePaths] of dcborCaptures) {
-            const envCapturePaths: Path[] = capturePaths.map((dcborPath: Cbor[]) => {
-              const envPath: Path = [haystack];
-              for (let i = 1; i < dcborPath.length; i++) {
-                const elem = dcborPath[i];
-                if (elem !== undefined) {
-                  envPath.push(Envelope.newLeaf(elem));
-                }
-              }
-              return envPath;
-            });
-            envelopeCaptures.set(name, envCapturePaths);
-          }
-
-          return [envelopePaths, envelopeCaptures];
-        }
-
-        return [[], new Map<string, Path[]>()];
-      }
-
-      case "WithPatterns":
-        // For envelope patterns, match if array length equals patterns count
-        // Full element-by-element matching would require additional implementation
-        if (array.length === this._pattern.patterns.length) {
-          return [[[haystack]], new Map<string, Path[]>()];
-        }
-        return [[], new Map<string, Path[]>()];
+    if (arrayPatternMatches(this._pattern, cbor)) {
+      return [[[haystack]], new Map<string, Path[]>()];
     }
+    return [[], new Map<string, Path[]>()];
   }
 
   paths(haystack: Envelope): Path[] {
@@ -198,80 +142,34 @@ export class ArrayPattern implements Matcher {
   }
 
   toString(): string {
-    switch (this._pattern.type) {
-      case "Any":
-        return "[*]";
-      case "Interval":
-        return `[{${this._pattern.interval.toString()}}]`;
-      case "DCBORPattern":
-        return dcborPatternDisplay(this._pattern.pattern);
-      case "WithPatterns":
-        return `[${this._pattern.patterns.map(String).join(", ")}]`;
-    }
+    return arrayPatternDisplay(this._pattern, dcborPatternDisplay);
   }
 
   /**
-   * Equality comparison.
+   * Equality comparison. Delegates to dcbor-pattern's structural equality
+   * with a display-string fallback for pattern-equality (mirrors Rust's
+   * `Hash` impl that hashes the display, since dcbor `ArrayPattern`
+   * itself does not derive `Hash`).
    */
   equals(other: ArrayPattern): boolean {
-    if (this._pattern.type !== other._pattern.type) {
-      return false;
-    }
-    switch (this._pattern.type) {
-      case "Any":
-        return true;
-      case "Interval":
-        return this._pattern.interval.equals(
-          (other._pattern as { type: "Interval"; interval: Interval }).interval,
-        );
-      case "DCBORPattern":
-        // Compare using display representation
-        return (
-          dcborPatternDisplay(this._pattern.pattern) ===
-          dcborPatternDisplay(
-            (other._pattern as { type: "DCBORPattern"; pattern: DCBORPattern }).pattern,
-          )
-        );
-      case "WithPatterns": {
-        const otherPatterns = (other._pattern as { type: "WithPatterns"; patterns: Pattern[] })
-          .patterns;
-        if (this._pattern.patterns.length !== otherPatterns.length) return false;
-        for (let i = 0; i < this._pattern.patterns.length; i++) {
-          if (this._pattern.patterns[i] !== otherPatterns[i]) return false;
-        }
-        return true;
-      }
-    }
+    return arrayPatternEquals(
+      this._pattern,
+      other._pattern,
+      (a, b) => dcborPatternDisplay(a) === dcborPatternDisplay(b),
+    );
   }
 
   /**
-   * Hash code for use in Maps/Sets.
+   * Hash code for use in Maps/Sets. Mirrors Rust's
+   * "hash the string representation" approach.
    */
   hashCode(): number {
-    switch (this._pattern.type) {
-      case "Any":
-        return 0;
-      case "Interval":
-        // Simple hash based on min/max
-        return this._pattern.interval.min() * 31 + (this._pattern.interval.max() ?? 0);
-      case "DCBORPattern":
-        // Simple hash based on display string
-        return simpleStringHash(dcborPatternDisplay(this._pattern.pattern));
-      case "WithPatterns":
-        return this._pattern.patterns.length;
+    let hash = 0;
+    const str = this.toString();
+    for (let i = 0; i < str.length; i++) {
+      hash = (hash << 5) - hash + str.charCodeAt(i);
+      hash = hash & hash;
     }
+    return hash;
   }
 }
-
-/**
- * Simple string hash function for hashCode implementations.
- */
-function simpleStringHash(str: string): number {
-  let hash = 0;
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
-    hash = (hash << 5) - hash + char;
-    hash = hash & hash; // Convert to 32-bit integer
-  }
-  return hash;
-}