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

package/src/parse/meta/not-parser.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Not parser — port of `bc-envelope-pattern-rust`
+ * `parse/meta/not_parser.rs`.
+ *
+ * Mirrors Rust:
+ * - On `!`, recurse into `parse_not` so chained negation parses as
+ *   `not(not(x))` rather than `not(group(x))`.
+ * - Otherwise descend into `parse_and`.
+ *
+ * @module envelope-pattern/parse/meta/not-parser
+ */
+
+import { type Result, ok } from "../../error";
+import { type Pattern, notMatching } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseAnd } from "./and-parser";
+
+export function parseNot(lexer: Lexer): Result<Pattern> {
+  const next = lexer.peekToken();
+  if (next?.token.type === "Not") {
+    lexer.next(); // consume !
+    const inner = parseNot(lexer);
+    if (!inner.ok) return inner;
+    return ok(notMatching(inner.value));
+  }
+  return parseAnd(lexer);
+}

package/src/parse/meta/or-parser.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Or parser — port of `bc-envelope-pattern-rust` `parse/meta/or_parser.rs`.
+ *
+ * @module envelope-pattern/parse/meta/or-parser
+ */
+
+import { type Result, ok } from "../../error";
+import { type Pattern, or } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseTraverse } from "./traverse-parser";
+
+export function parseOr(lexer: Lexer): Result<Pattern> {
+  const patterns: Pattern[] = [];
+  const first = parseTraverse(lexer);
+  if (!first.ok) return first;
+  patterns.push(first.value);
+
+  while (true) {
+    const next = lexer.peekToken();
+    if (next?.token.type !== "Or") {
+      break;
+    }
+    lexer.next(); // consume |
+    const nextExpr = parseTraverse(lexer);
+    if (!nextExpr.ok) return nextExpr;
+    patterns.push(nextExpr.value);
+  }
+
+  if (patterns.length === 1) {
+    return ok(patterns[0]);
+  }
+  return ok(or(patterns));
+}

package/src/parse/meta/primary-parser.ts

@@ -0,0 +1,234 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Primary parser — port of `bc-envelope-pattern-rust`
+ * `parse/meta/primary_parser.rs`.
+ *
+ * Dispatches on the next token to the appropriate leaf/structure/meta
+ * parser. When a `(` is encountered the open paren is consumed here and
+ * `parse_group` handles the rest (paren'd expression + optional
+ * quantifier suffix).
+ *
+ * @module envelope-pattern/parse/meta/primary-parser
+ */
+
+import {
+  type Result,
+  err,
+  invalidRegex,
+  ok,
+  unexpectedEndOfInput,
+  unexpectedToken,
+  unrecognizedToken,
+} from "../../error";
+import {
+  type Pattern,
+  ByteStringPattern,
+  KnownValuePattern,
+  NumberPattern,
+  any,
+  anyBool,
+  anyByteString,
+  anyDate,
+  anyKnownValue,
+  anyNumber,
+  anyText,
+  bool,
+  byteString,
+  leaf,
+  leafByteString,
+  leafKnownValue,
+  leafNumber,
+  number,
+  nullPattern,
+  patternLeaf,
+  text,
+  textRegex,
+} from "../../pattern";
+import type { Lexer } from "../token";
+import { parseArray } from "../leaf/array-parser";
+import { parseCbor } from "../leaf/cbor-parser";
+import { parseDateContent } from "../leaf/date-parser";
+import { parseKnownValueContent } from "../leaf/known-value-parser";
+import { parseComparisonNumber, parseNumberRangeOrComparison } from "../leaf/number-parser";
+import { parseTag } from "../leaf/tag-parser";
+import { parseAssertion } from "../structure/assertion-parser";
+import { parseAssertionObj } from "../structure/assertion-obj-parser";
+import { parseAssertionPred } from "../structure/assertion-pred-parser";
+import { parseCompressed } from "../structure/compressed-parser";
+import { parseDigest } from "../structure/digest-parser";
+import { parseElided } from "../structure/elided-parser";
+import { parseEncrypted } from "../structure/encrypted-parser";
+import { parseNode } from "../structure/node-parser";
+import { parseObject } from "../structure/object-parser";
+import { parseObscured } from "../structure/obscured-parser";
+import { parsePredicate } from "../structure/predicate-parser";
+import { parseSubject } from "../structure/subject-parser";
+import { parseUnwrap, parseWrapped } from "../structure/wrapped-parser";
+import { parseCapture } from "./capture-parser";
+import { parseGroup } from "./group-parser";
+import { parseSearch } from "./search-parser";
+
+export function parsePrimary(lexer: Lexer): Result<Pattern> {
+  const tokenResult = lexer.next();
+  if (tokenResult === undefined) {
+    return err(unexpectedEndOfInput());
+  }
+
+  const { token, span } = tokenResult;
+
+  switch (token.type) {
+    case "Search":
+      return parseSearch(lexer);
+    case "Node":
+      return parseNode(lexer);
+    case "Assertion":
+      return parseAssertion(lexer);
+    case "AssertionPred":
+      return parseAssertionPred(lexer);
+    case "AssertionObj":
+      return parseAssertionObj(lexer);
+    case "Digest":
+      return parseDigest(lexer);
+    case "Obj":
+      return parseObject(lexer);
+    case "Obscured":
+      return parseObscured(lexer);
+    case "Elided":
+      return parseElided(lexer);
+    case "Encrypted":
+      return parseEncrypted(lexer);
+    case "Compressed":
+      return parseCompressed(lexer);
+    case "Pred":
+      return parsePredicate(lexer);
+    case "Subject":
+      return parseSubject(lexer);
+    case "Wrapped":
+      return parseWrapped(lexer);
+    case "Unwrap":
+      return parseUnwrap(lexer);
+    case "Leaf":
+      return ok(leaf());
+
+    case "GroupName":
+      return parseCapture(lexer, token.name);
+
+    case "ParenOpen":
+      return parseGroup(lexer);
+
+    case "Cbor":
+      return parseCbor(lexer);
+
+    case "RepeatZeroOrMore":
+      return ok(any());
+    case "BoolKeyword":
+      return ok(anyBool());
+    case "BoolTrue":
+      return ok(bool(true));
+    case "BoolFalse":
+      return ok(bool(false));
+    case "NumberKeyword":
+      return ok(anyNumber());
+    case "TextKeyword":
+      return ok(anyText());
+    case "StringLiteral":
+      if (!token.value.ok) return err(token.value.error);
+      return ok(text(token.value.value));
+    case "UnsignedInteger":
+      if (!token.value.ok) return err(token.value.error);
+      return parseNumberRangeOrComparison(lexer, token.value.value);
+    case "Integer":
+      if (!token.value.ok) return err(token.value.error);
+      return parseNumberRangeOrComparison(lexer, token.value.value);
+    case "Float":
+      if (!token.value.ok) return err(token.value.error);
+      return parseNumberRangeOrComparison(lexer, token.value.value);
+    case "GreaterThanOrEqual":
+      return parseComparisonNumber(lexer, ">=");
+    case "LessThanOrEqual":
+      return parseComparisonNumber(lexer, "<=");
+    case "GreaterThan":
+      return parseComparisonNumber(lexer, ">");
+    case "LessThan":
+      return parseComparisonNumber(lexer, "<");
+    case "NaN":
+      return ok(patternLeaf(leafNumber(NumberPattern.nan())));
+    case "Infinity":
+      return ok(number(Infinity));
+    case "NegativeInfinity":
+      return ok(number(-Infinity));
+    case "Regex":
+      if (!token.value.ok) return err(token.value.error);
+      try {
+        return ok(textRegex(new RegExp(token.value.value)));
+      } catch {
+        return err(invalidRegex(span));
+      }
+    case "BracketOpen":
+      return parseArray(lexer);
+    case "ByteString":
+      return ok(anyByteString());
+    case "HexPattern":
+      if (!token.value.ok) return err(token.value.error);
+      return ok(byteString(token.value.value));
+    case "HexBinaryRegex":
+      if (!token.value.ok) return err(token.value.error);
+      try {
+        return ok(
+          patternLeaf(leafByteString(ByteStringPattern.regex(new RegExp(token.value.value)))),
+        );
+      } catch {
+        return err(invalidRegex(span));
+      }
+    case "DateKeyword":
+      return ok(anyDate());
+    case "DatePattern":
+      if (!token.value.ok) return err(token.value.error);
+      return parseDateContent(token.value.value, span);
+    case "Tagged":
+      return parseTag(lexer);
+    case "Known":
+      return ok(anyKnownValue());
+    case "SingleQuotedPattern":
+      if (!token.value.ok) return err(token.value.error);
+      return parseKnownValueContent(token.value.value);
+    case "SingleQuotedRegex":
+      if (!token.value.ok) return err(token.value.error);
+      try {
+        return ok(
+          patternLeaf(leafKnownValue(KnownValuePattern.regex(new RegExp(token.value.value)))),
+        );
+      } catch {
+        return err(invalidRegex(span));
+      }
+    case "Null":
+      return ok(nullPattern());
+
+    case "Identifier":
+      // Rust's logos lexer never produces `Identifier` for unknown
+      // words; it errors with `UnrecognizedToken`. Mirror that behaviour
+      // here so error positions line up with Rust.
+      return err(unrecognizedToken(span));
+
+    case "And":
+    case "Or":
+    case "Not":
+    case "Traverse":
+    case "RepeatZeroOrMoreLazy":
+    case "RepeatZeroOrMorePossessive":
+    case "RepeatOneOrMore":
+    case "RepeatOneOrMoreLazy":
+    case "RepeatOneOrMorePossessive":
+    case "RepeatZeroOrOne":
+    case "RepeatZeroOrOneLazy":
+    case "RepeatZeroOrOnePossessive":
+    case "ParenClose":
+    case "BracketClose":
+    case "Comma":
+    case "Ellipsis":
+    case "Range":
+      return err(unexpectedToken(token, span));
+  }
+}

package/src/parse/meta/search-parser.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Search parser — port of `bc-envelope-pattern-rust`
+ * `parse/meta/search_parser.rs`.
+ *
+ * @module envelope-pattern/parse/meta/search-parser
+ */
+
+import {
+  type Result,
+  err,
+  expectedCloseParen,
+  ok,
+  unexpectedEndOfInput,
+  unexpectedToken,
+} from "../../error";
+import { type Pattern, search } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseOr } from "./or-parser";
+
+export function parseSearch(lexer: Lexer): Result<Pattern> {
+  const open = lexer.next();
+  if (open === undefined) {
+    return err(unexpectedEndOfInput());
+  }
+  if (open.token.type !== "ParenOpen") {
+    return err(unexpectedToken(open.token, open.span));
+  }
+  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(search(inner.value));
+}

package/src/parse/meta/traverse-parser.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Traverse parser — port of `bc-envelope-pattern-rust`
+ * `parse/meta/traverse_parser.rs`.
+ *
+ * Note the precedence chain: `parse_or → parse_traverse → parse_not →
+ * parse_and → parse_primary`. The earlier TS port had `parse_traverse`
+ * call `parse_and` directly, which pushed `!` below `&` and
+ * miscompiled `!a & b`.
+ *
+ * @module envelope-pattern/parse/meta/traverse-parser
+ */
+
+import { type Result, ok } from "../../error";
+import { type Pattern, traverse } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseNot } from "./not-parser";
+
+export function parseTraverse(lexer: Lexer): Result<Pattern> {
+  const patterns: Pattern[] = [];
+  const first = parseNot(lexer);
+  if (!first.ok) return first;
+  patterns.push(first.value);
+
+  while (true) {
+    const next = lexer.peekToken();
+    if (next?.token.type !== "Traverse") {
+      break;
+    }
+    lexer.next(); // consume ->
+    const nextExpr = parseNot(lexer);
+    if (!nextExpr.ok) return nextExpr;
+    patterns.push(nextExpr.value);
+  }
+
+  if (patterns.length === 1) {
+    return ok(patterns[0]);
+  }
+  return ok(traverse(patterns));
+}

package/src/parse/structure/assertion-obj-parser.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Assertion-object parser — port of
+ * `bc-envelope-pattern-rust/src/parse/structure/assertion_obj_parser.rs`.
+ *
+ * Requires `assertobj(<pattern>)`. The bare `assertobj` keyword is a
+ * syntax error in Rust; we now mirror that behaviour.
+ *
+ * @module envelope-pattern/parse/structure/assertion-obj-parser
+ */
+
+import {
+  type Result,
+  err,
+  expectedCloseParen,
+  ok,
+  unexpectedEndOfInput,
+  unexpectedToken,
+} from "../../error";
+import { type Pattern, assertionWithObject } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseOr } from "../meta/or-parser";
+
+export function parseAssertionObj(lexer: Lexer): Result<Pattern> {
+  const open = lexer.next();
+  if (open === undefined) {
+    return err(unexpectedEndOfInput());
+  }
+  if (open.token.type !== "ParenOpen") {
+    return err(unexpectedToken(open.token, open.span));
+  }
+  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(assertionWithObject(inner.value));
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Assertion parser — port of `bc-envelope-pattern-rust`
+ * `parse/structure/assertion_parser.rs`.
+ *
+ * Note: Rust's `parse_assertion` ignores its lexer entirely and always
+ * returns `Pattern::any_assertion()`. There is intentionally **no**
+ * `assert(pred, obj)` syntax — predicate/object filters are written via
+ * the dedicated `assertpred(...)` / `assertobj(...)` keywords.
+ *
+ * @module envelope-pattern/parse/structure/assertion-parser
+ */
+
+import { type Result, ok } from "../../error";
+import { type Pattern, anyAssertion } from "../../pattern";
+import type { Lexer } from "../token";
+
+export function parseAssertion(_lexer: Lexer): Result<Pattern> {
+  return ok(anyAssertion());
+}

package/src/parse/structure/assertion-pred-parser.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Assertion-predicate parser — port of
+ * `bc-envelope-pattern-rust/src/parse/structure/assertion_pred_parser.rs`.
+ *
+ * Requires `assertpred(<pattern>)`. The bare `assertpred` keyword is a
+ * syntax error in Rust (it errors on `UnexpectedEndOfInput` /
+ * `UnexpectedToken`); we now mirror that behaviour.
+ *
+ * @module envelope-pattern/parse/structure/assertion-pred-parser
+ */
+
+import {
+  type Result,
+  err,
+  expectedCloseParen,
+  ok,
+  unexpectedEndOfInput,
+  unexpectedToken,
+} from "../../error";
+import { type Pattern, assertionWithPredicate } from "../../pattern";
+import type { Lexer } from "../token";
+import { parseOr } from "../meta/or-parser";
+
+export function parseAssertionPred(lexer: Lexer): Result<Pattern> {
+  const open = lexer.next();
+  if (open === undefined) {
+    return err(unexpectedEndOfInput());
+  }
+  if (open.token.type !== "ParenOpen") {
+    return err(unexpectedToken(open.token, open.span));
+  }
+  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(assertionWithPredicate(inner.value));
+}

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

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

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

@@ -0,0 +1,132 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ * Digest parser — port of `bc-envelope-pattern-rust`
+ * `parse/structure/digest_parser.rs`.
+ *
+ * Mirrors Rust exactly:
+ *
+ * - Requires `digest(...)` — bare `digest` is an `UnexpectedEndOfInput`
+ *   error (the previous TS port silently returned `digest(any)`).
+ * - Inside the parens, accepts either a UR string (`ur:digest/...`,
+ *   parsed via `Digest.fromURString`) or a hex byte prefix.
+ * - Hex prefixes must have even length and not exceed `Digest.DIGEST_SIZE`
+ *   bytes; otherwise the parser surfaces `InvalidHexString`.
+ *
+ * @module envelope-pattern/parse/structure/digest-parser
+ */
+
+import { Digest } from "@bcts/envelope";
+import {
+  type Result,
+  err,
+  expectedCloseParen,
+  invalidHexString,
+  invalidUr,
+  ok,
+  unexpectedEndOfInput,
+  unexpectedToken,
+} from "../../error";
+import { type Pattern, digest, digestPrefix } from "../../pattern";
+import type { Lexer } from "../token";
+
+const DIGEST_SIZE = Digest.DIGEST_SIZE;
+
+export function parseDigest(lexer: Lexer): Result<Pattern> {
+  const open = lexer.next();
+  if (open === undefined) {
+    return err(unexpectedEndOfInput());
+  }
+  if (open.token.type !== "ParenOpen") {
+    return err(unexpectedToken(open.token, open.span));
+  }
+
+  const remainder = lexer.remainder();
+  const innerResult = parseDigestInner(remainder, lexer.position);
+  if (!innerResult.ok) return innerResult;
+  const [pattern, consumed] = innerResult.value;
+  lexer.bump(consumed);
+
+  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(pattern);
+}
+
+function parseDigestInner(src: string, basePos: number): Result<[Pattern, number]> {
+  let pos = 0;
+  pos = skipWs(src, pos);
+
+  if (src.startsWith("ur:", pos)) {
+    const start = pos;
+    while (pos < src.length && src[pos] !== ")") {
+      pos += 1;
+    }
+    const ur = src.slice(start, pos).trimEnd();
+    let parsed: Digest;
+    try {
+      parsed = Digest.fromURString(ur);
+    } catch {
+      return err(invalidUr(ur, { start: basePos + start, end: basePos + pos }));
+    }
+    pos = skipWs(src, pos);
+    return ok([digest(parsed), pos]);
+  }
+
+  const start = pos;
+  while (pos < src.length && isAsciiHexDigit(src.charCodeAt(pos))) {
+    pos += 1;
+  }
+  if (pos === start) {
+    return err(invalidHexString({ start: basePos + pos, end: basePos + pos }));
+  }
+  const hexStr = src.slice(start, pos);
+  if (hexStr.length % 2 !== 0) {
+    return err(invalidHexString({ start: basePos + pos, end: basePos + pos }));
+  }
+  const bytes = decodeHex(hexStr);
+  if (bytes === undefined) {
+    return err(invalidHexString({ start: basePos + pos, end: basePos + pos }));
+  }
+  if (bytes.length > DIGEST_SIZE) {
+    return err(invalidHexString({ start: basePos + pos, end: basePos + pos }));
+  }
+  pos = skipWs(src, pos);
+  return ok([digestPrefix(bytes), pos]);
+}
+
+function skipWs(src: string, pos: number): number {
+  while (pos < src.length) {
+    const ch = src[pos];
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r" || ch === "\f") {
+      pos += 1;
+    } else {
+      break;
+    }
+  }
+  return pos;
+}
+
+function isAsciiHexDigit(c: number): boolean {
+  return (
+    (c >= 0x30 && c <= 0x39) /* 0-9 */ ||
+    (c >= 0x41 && c <= 0x46) /* A-F */ ||
+    (c >= 0x61 && c <= 0x66) /* a-f */
+  );
+}
+
+function decodeHex(hex: string): Uint8Array | undefined {
+  if (hex.length % 2 !== 0) return undefined;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    const value = Number.parseInt(hex.slice(i, i + 2), 16);
+    if (Number.isNaN(value)) return undefined;
+    out[i / 2] = value;
+  }
+  return out;
+}

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

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

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

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