@bcts/envelope-pattern 1.0.0-alpha.12

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@bcts/envelope-pattern",
+  "version": "1.0.0-alpha.12",
+  "type": "module",
+  "description": "Pattern matching for Gordian Envelope structures",
+  "license": "BSD-2-Clause-Patent",
+  "contributors": [
+    {
+      "name": "Leonardo Custodio",
+      "email": "leonardo.custodio@parity.io",
+      "url": "https://github.com/leonardocustodio"
+    },
+    {
+      "name": "Karim Jedda",
+      "email": "karim@parity.io",
+      "url": "https://github.com/KarimJedda"
+    }
+  ],
+  "homepage": "https://bcts.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leonardocustodio/bcts.git",
+    "directory": "packages/envelope-pattern"
+  },
+  "bugs": {
+    "url": "https://github.com/leonardocustodio/bcts/issues"
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "browser": "dist/index.iife.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs": "typedoc",
+    "prepublishOnly": "npm run clean && npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@bcts/eslint": "workspace:*",
+    "@bcts/tsconfig": "workspace:*",
+    "eslint": "^9.39.2",
+    "tsdown": "^0.18.3",
+    "typedoc": "^0.28.15",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "dependencies": {
+    "@bcts/dcbor": "workspace:*",
+    "@bcts/dcbor-pattern": "workspace:*",
+    "@bcts/envelope": "workspace:*",
+    "@bcts/components": "workspace:*",
+    "@bcts/tags": "workspace:*",
+    "@bcts/known-values": "workspace:*"
+  }
+}

package/src/error.ts

@@ -0,0 +1,262 @@
+/**
+ * @bcts/envelope-pattern - Error types for envelope pattern parsing
+ *
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust error.rs
+ *
+ * @module envelope-pattern/error
+ */
+
+import type { Token } from "./parse/token";
+
+/**
+ * Span represents a range in the source input.
+ */
+export interface Span {
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * Error types that can occur during parsing of Envelope patterns.
+ *
+ * Corresponds to the Rust `Error` enum in error.rs
+ */
+export type EnvelopePatternError =
+  | { readonly type: "EmptyInput" }
+  | { readonly type: "UnexpectedEndOfInput" }
+  | { readonly type: "ExtraData"; readonly span: Span }
+  | { readonly type: "UnexpectedToken"; readonly token: Token; readonly span: Span }
+  | { readonly type: "UnrecognizedToken"; readonly span: Span }
+  | { readonly type: "InvalidRegex"; readonly span: Span }
+  | { readonly type: "UnterminatedRegex"; readonly span: Span }
+  | { readonly type: "InvalidRange"; readonly span: Span }
+  | { readonly type: "InvalidHexString"; readonly span: Span }
+  | { readonly type: "InvalidDateFormat"; readonly span: Span }
+  | { readonly type: "InvalidNumberFormat"; readonly span: Span }
+  | { readonly type: "InvalidUr"; readonly message: string; readonly span: Span }
+  | { readonly type: "ExpectedOpenParen"; readonly span: Span }
+  | { readonly type: "ExpectedCloseParen"; readonly span: Span }
+  | { readonly type: "ExpectedOpenBracket"; readonly span: Span }
+  | { readonly type: "ExpectedCloseBracket"; readonly span: Span }
+  | { readonly type: "ExpectedPattern"; readonly span: Span }
+  | { readonly type: "UnmatchedParentheses"; readonly span: Span }
+  | { readonly type: "UnmatchedBraces"; readonly span: Span }
+  | { readonly type: "InvalidCaptureGroupName"; readonly name: string; readonly span: Span }
+  | { readonly type: "InvalidPattern"; readonly span: Span }
+  | { readonly type: "Unknown" }
+  | { readonly type: "DCBORPatternError"; readonly error: unknown };
+
+/**
+ * Result type specialized for envelope pattern parsing.
+ */
+export type Result<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: EnvelopePatternError };
+
+/**
+ * Creates a successful result.
+ */
+export function ok<T>(value: T): Result<T> {
+  return { ok: true, value };
+}
+
+/**
+ * Creates a failed result.
+ */
+export function err<T>(error: EnvelopePatternError): Result<T> {
+  return { ok: false, error };
+}
+
+/**
+ * Type guard for successful results.
+ */
+export function isOk<T>(result: Result<T>): result is { readonly ok: true; readonly value: T } {
+  return result.ok;
+}
+
+/**
+ * Type guard for failed results.
+ */
+export function isErr<T>(
+  result: Result<T>,
+): result is { readonly ok: false; readonly error: EnvelopePatternError } {
+  return !result.ok;
+}
+
+/**
+ * Unwraps a successful result or throws the error.
+ */
+export function unwrap<T>(result: Result<T>): T {
+  if (result.ok) {
+    return result.value;
+  }
+  throw new Error(formatError(result.error));
+}
+
+/**
+ * Unwraps a successful result or returns a default value.
+ */
+export function unwrapOr<T>(result: Result<T>, defaultValue: T): T {
+  if (result.ok) {
+    return result.value;
+  }
+  return defaultValue;
+}
+
+/**
+ * Maps a successful result value.
+ */
+export function map<T, U>(result: Result<T>, fn: (value: T) => U): Result<U> {
+  if (result.ok) {
+    return ok(fn(result.value));
+  }
+  return result as Result<U>;
+}
+
+/**
+ * Formats an error for display.
+ */
+export function formatError(error: EnvelopePatternError): string {
+  switch (error.type) {
+    case "EmptyInput":
+      return "Empty input";
+    case "UnexpectedEndOfInput":
+      return "Unexpected end of input";
+    case "ExtraData":
+      return `Extra data at end of input at position ${error.span.start}-${error.span.end}`;
+    case "UnexpectedToken":
+      return `Unexpected token ${JSON.stringify(error.token)} at position ${error.span.start}-${error.span.end}`;
+    case "UnrecognizedToken":
+      return `Unrecognized token at position ${error.span.start}-${error.span.end}`;
+    case "InvalidRegex":
+      return `Invalid regex pattern at position ${error.span.start}-${error.span.end}`;
+    case "UnterminatedRegex":
+      return `Unterminated regex pattern at position ${error.span.start}-${error.span.end}`;
+    case "InvalidRange":
+      return `Invalid range at position ${error.span.start}-${error.span.end}`;
+    case "InvalidHexString":
+      return `Invalid hex string at position ${error.span.start}-${error.span.end}`;
+    case "InvalidDateFormat":
+      return `Invalid date format at position ${error.span.start}-${error.span.end}`;
+    case "InvalidNumberFormat":
+      return `Invalid number format at position ${error.span.start}-${error.span.end}`;
+    case "InvalidUr":
+      return `Invalid UR: ${error.message} at position ${error.span.start}-${error.span.end}`;
+    case "ExpectedOpenParen":
+      return `Expected opening parenthesis at position ${error.span.start}-${error.span.end}`;
+    case "ExpectedCloseParen":
+      return `Expected closing parenthesis at position ${error.span.start}-${error.span.end}`;
+    case "ExpectedOpenBracket":
+      return `Expected opening bracket at position ${error.span.start}-${error.span.end}`;
+    case "ExpectedCloseBracket":
+      return `Expected closing bracket at position ${error.span.start}-${error.span.end}`;
+    case "ExpectedPattern":
+      return `Expected pattern after operator at position ${error.span.start}-${error.span.end}`;
+    case "UnmatchedParentheses":
+      return `Unmatched parentheses at position ${error.span.start}-${error.span.end}`;
+    case "UnmatchedBraces":
+      return `Unmatched braces at position ${error.span.start}-${error.span.end}`;
+    case "InvalidCaptureGroupName":
+      return `Invalid capture group name '${error.name}' at position ${error.span.start}-${error.span.end}`;
+    case "InvalidPattern":
+      return `Invalid pattern at position ${error.span.start}-${error.span.end}`;
+    case "Unknown":
+      return "Unknown error";
+    case "DCBORPatternError":
+      return `DCBOR pattern error: ${String(error.error)}`;
+  }
+}
+
+// Error factory functions for convenience
+
+export function emptyInput(): EnvelopePatternError {
+  return { type: "EmptyInput" };
+}
+
+export function unexpectedEndOfInput(): EnvelopePatternError {
+  return { type: "UnexpectedEndOfInput" };
+}
+
+export function extraData(span: Span): EnvelopePatternError {
+  return { type: "ExtraData", span };
+}
+
+export function unexpectedToken(token: Token, span: Span): EnvelopePatternError {
+  return { type: "UnexpectedToken", token, span };
+}
+
+export function unrecognizedToken(span: Span): EnvelopePatternError {
+  return { type: "UnrecognizedToken", span };
+}
+
+export function invalidRegex(span: Span): EnvelopePatternError {
+  return { type: "InvalidRegex", span };
+}
+
+export function unterminatedRegex(span: Span): EnvelopePatternError {
+  return { type: "UnterminatedRegex", span };
+}
+
+export function invalidRange(span: Span): EnvelopePatternError {
+  return { type: "InvalidRange", span };
+}
+
+export function invalidHexString(span: Span): EnvelopePatternError {
+  return { type: "InvalidHexString", span };
+}
+
+export function invalidDateFormat(span: Span): EnvelopePatternError {
+  return { type: "InvalidDateFormat", span };
+}
+
+export function invalidNumberFormat(span: Span): EnvelopePatternError {
+  return { type: "InvalidNumberFormat", span };
+}
+
+export function invalidUr(message: string, span: Span): EnvelopePatternError {
+  return { type: "InvalidUr", message, span };
+}
+
+export function expectedOpenParen(span: Span): EnvelopePatternError {
+  return { type: "ExpectedOpenParen", span };
+}
+
+export function expectedCloseParen(span: Span): EnvelopePatternError {
+  return { type: "ExpectedCloseParen", span };
+}
+
+export function expectedOpenBracket(span: Span): EnvelopePatternError {
+  return { type: "ExpectedOpenBracket", span };
+}
+
+export function expectedCloseBracket(span: Span): EnvelopePatternError {
+  return { type: "ExpectedCloseBracket", span };
+}
+
+export function expectedPattern(span: Span): EnvelopePatternError {
+  return { type: "ExpectedPattern", span };
+}
+
+export function unmatchedParentheses(span: Span): EnvelopePatternError {
+  return { type: "UnmatchedParentheses", span };
+}
+
+export function unmatchedBraces(span: Span): EnvelopePatternError {
+  return { type: "UnmatchedBraces", span };
+}
+
+export function invalidCaptureGroupName(name: string, span: Span): EnvelopePatternError {
+  return { type: "InvalidCaptureGroupName", name, span };
+}
+
+export function invalidPattern(span: Span): EnvelopePatternError {
+  return { type: "InvalidPattern", span };
+}
+
+export function unknown(): EnvelopePatternError {
+  return { type: "Unknown" };
+}
+
+export function dcborPatternError(error: unknown): EnvelopePatternError {
+  return { type: "DCBORPatternError", error };
+}

package/src/format.ts

@@ -0,0 +1,375 @@
+/**
+ * @bcts/envelope-pattern - Path formatting utilities
+ *
+ * This is a 1:1 TypeScript port of bc-envelope-pattern-rust format.rs
+ *
+ * @module envelope-pattern/format
+ */
+
+import type { Envelope } from "@bcts/envelope";
+
+/**
+ * A path is a sequence of envelopes from root to a matched element.
+ */
+export type Path = Envelope[];
+
+/**
+ * Format options for each path element.
+ *
+ * Corresponds to the Rust `PathElementFormat` enum in format.rs
+ */
+export type PathElementFormat =
+  | { readonly type: "Summary"; readonly maxLength?: number }
+  | { readonly type: "EnvelopeUR" }
+  | { readonly type: "DigestUR" };
+
+/**
+ * Creates a Summary format.
+ */
+export function summaryFormat(maxLength?: number): PathElementFormat {
+  if (maxLength !== undefined) {
+    return { type: "Summary", maxLength };
+  }
+  return { type: "Summary" };
+}
+
+/**
+ * Creates an EnvelopeUR format.
+ */
+export function envelopeURFormat(): PathElementFormat {
+  return { type: "EnvelopeUR" };
+}
+
+/**
+ * Creates a DigestUR format.
+ */
+export function digestURFormat(): PathElementFormat {
+  return { type: "DigestUR" };
+}
+
+/**
+ * Default path element format.
+ */
+export function defaultPathElementFormat(): PathElementFormat {
+  return summaryFormat(undefined);
+}
+
+/**
+ * Options for formatting paths.
+ *
+ * Corresponds to the Rust `FormatPathsOpts` struct in format.rs
+ */
+export interface FormatPathsOpts {
+  /**
+   * Whether to indent each path element.
+   * If true, each element will be indented by 4 spaces per level.
+   * Default: true
+   */
+  readonly indent: boolean;
+
+  /**
+   * Format for each path element.
+   * Default: Summary(None)
+   */
+  readonly elementFormat: PathElementFormat;
+
+  /**
+   * If true, only the last element of each path will be formatted.
+   * This is useful for displaying only the final destination of a path.
+   * If false, all elements will be formatted.
+   * Default: false
+   */
+  readonly lastElementOnly: boolean;
+}
+
+/**
+ * Creates default formatting options.
+ */
+export function defaultFormatPathsOpts(): FormatPathsOpts {
+  return {
+    indent: true,
+    elementFormat: defaultPathElementFormat(),
+    lastElementOnly: false,
+  };
+}
+
+/**
+ * Builder for FormatPathsOpts.
+ */
+export class FormatPathsOptsBuilder {
+  #indent = true;
+  #elementFormat: PathElementFormat = defaultPathElementFormat();
+  #lastElementOnly = false;
+
+  /**
+   * Sets whether to indent each path element.
+   */
+  indent(indent: boolean): this {
+    this.#indent = indent;
+    return this;
+  }
+
+  /**
+   * Sets the format for each path element.
+   */
+  elementFormat(format: PathElementFormat): this {
+    this.#elementFormat = format;
+    return this;
+  }
+
+  /**
+   * Sets whether to format only the last element of each path.
+   */
+  lastElementOnly(lastElementOnly: boolean): this {
+    this.#lastElementOnly = lastElementOnly;
+    return this;
+  }
+
+  /**
+   * Builds the FormatPathsOpts.
+   */
+  build(): FormatPathsOpts {
+    return {
+      indent: this.#indent,
+      elementFormat: this.#elementFormat,
+      lastElementOnly: this.#lastElementOnly,
+    };
+  }
+}
+
+/**
+ * Creates a new FormatPathsOptsBuilder.
+ */
+export function formatPathsOpts(): FormatPathsOptsBuilder {
+  return new FormatPathsOptsBuilder();
+}
+
+/**
+ * Gets a summary of an envelope for display.
+ *
+ * @param env - The envelope to summarize
+ * @returns A string summary of the envelope
+ */
+export function envelopeSummary(env: Envelope): string {
+  const id = env.shortId("short");
+  const c = env.case();
+
+  let summary: string;
+  switch (c.type) {
+    case "node":
+      summary = `NODE ${env.summary(Number.MAX_SAFE_INTEGER)}`;
+      break;
+    case "leaf":
+      summary = `LEAF ${env.summary(Number.MAX_SAFE_INTEGER)}`;
+      break;
+    case "wrapped":
+      summary = `WRAPPED ${env.summary(Number.MAX_SAFE_INTEGER)}`;
+      break;
+    case "assertion":
+      summary = `ASSERTION ${env.summary(Number.MAX_SAFE_INTEGER)}`;
+      break;
+    case "elided":
+      summary = "ELIDED";
+      break;
+    case "knownValue":
+      summary = `KNOWN_VALUE '${c.value.name()}'`;
+      break;
+    case "encrypted":
+      summary = "ENCRYPTED";
+      break;
+    case "compressed":
+      summary = "COMPRESSED";
+      break;
+    default:
+      summary = "UNKNOWN";
+  }
+
+  return `${id} ${summary}`;
+}
+
+/**
+ * Truncates a string to the specified maximum length, appending an ellipsis if truncated.
+ *
+ * @param s - The string to truncate
+ * @param maxLength - Optional maximum length
+ * @returns The truncated string
+ */
+function truncateWithEllipsis(s: string, maxLength?: number): string {
+  if (maxLength === undefined) {
+    return s;
+  }
+  if (s.length > maxLength) {
+    if (maxLength > 1) {
+      return `${s.substring(0, maxLength - 1)}…`;
+    }
+    return "…";
+  }
+  return s;
+}
+
+/**
+ * Format a single path element on its own line with custom options.
+ *
+ * @param path - The path to format
+ * @param opts - Formatting options
+ * @returns The formatted path string
+ */
+export function formatPathOpt(
+  path: Path,
+  opts: FormatPathsOpts = defaultFormatPathsOpts(),
+): string {
+  if (opts.lastElementOnly) {
+    // Only format the last element, no indentation
+    const element = path[path.length - 1];
+    if (element === undefined) {
+      return "";
+    }
+
+    switch (opts.elementFormat.type) {
+      case "Summary": {
+        const summary = envelopeSummary(element);
+        return truncateWithEllipsis(summary, opts.elementFormat.maxLength);
+      }
+      case "EnvelopeUR":
+        // TODO: Implement proper UR string format when available
+        return element.digest().toString();
+      case "DigestUR":
+        return element.digest().toString();
+    }
+  }
+
+  switch (opts.elementFormat.type) {
+    case "Summary": {
+      // Multi-line output with indentation for summaries
+      const lines: string[] = [];
+      for (let index = 0; index < path.length; index++) {
+        const element = path[index];
+        if (element === undefined) continue;
+
+        const indent = opts.indent ? " ".repeat(index * 4) : "";
+        const summary = envelopeSummary(element);
+        const content = truncateWithEllipsis(summary, opts.elementFormat.maxLength);
+        lines.push(`${indent}${content}`);
+      }
+      return lines.join("\n");
+    }
+    case "EnvelopeUR":
+      // TODO: Implement proper UR string format when available
+      return path.map((element) => element.digest().toString()).join(" ");
+    case "DigestUR":
+      // Single-line, space-separated digest strings
+      return path.map((element) => element.digest().toString()).join(" ");
+  }
+}
+
+/**
+ * Format a single path with default options.
+ *
+ * @param path - The path to format
+ * @returns The formatted path string
+ */
+export function formatPath(path: Path): string {
+  return formatPathOpt(path, defaultFormatPathsOpts());
+}
+
+/**
+ * Format multiple paths with captures and custom options.
+ *
+ * Captures come first, sorted lexicographically by name, with their name
+ * prefixed by '@'. Regular paths follow after all captures.
+ *
+ * @param paths - The paths to format
+ * @param captures - Map of capture name to captured paths
+ * @param opts - Formatting options
+ * @returns The formatted string
+ */
+export function formatPathsWithCapturesOpt(
+  paths: Path[],
+  captures: Map<string, Path[]>,
+  opts: FormatPathsOpts = defaultFormatPathsOpts(),
+): string {
+  const result: string[] = [];
+
+  // First, format all captures, sorted lexicographically by name
+  const captureNames = Array.from(captures.keys()).sort();
+
+  for (const captureName of captureNames) {
+    const capturePaths = captures.get(captureName);
+    if (capturePaths === undefined) continue;
+
+    result.push(`@${captureName}`);
+    for (const path of capturePaths) {
+      const formattedPath = formatPathOpt(path, opts);
+      // Add indentation to each line of the formatted path
+      for (const line of formattedPath.split("\n")) {
+        if (line.length > 0) {
+          result.push(`    ${line}`);
+        }
+      }
+    }
+  }
+
+  // Then, format all regular paths
+  switch (opts.elementFormat.type) {
+    case "EnvelopeUR":
+    case "DigestUR": {
+      // For UR formats, join paths with spaces on same line
+      if (paths.length > 0) {
+        const formattedPaths = paths.map((path) => formatPathOpt(path, opts)).join(" ");
+        if (formattedPaths.length > 0) {
+          result.push(formattedPaths);
+        }
+      }
+      break;
+    }
+    case "Summary": {
+      // For summary format, format each path separately
+      for (const path of paths) {
+        const formattedPath = formatPathOpt(path, opts);
+        for (const line of formattedPath.split("\n")) {
+          if (line.length > 0) {
+            result.push(line);
+          }
+        }
+      }
+      break;
+    }
+  }
+
+  return result.join("\n");
+}
+
+/**
+ * Format multiple paths with captures using default options.
+ *
+ * @param paths - The paths to format
+ * @param captures - Map of capture name to captured paths
+ * @returns The formatted string
+ */
+export function formatPathsWithCaptures(paths: Path[], captures: Map<string, Path[]>): string {
+  return formatPathsWithCapturesOpt(paths, captures, defaultFormatPathsOpts());
+}
+
+/**
+ * Format multiple paths with custom options.
+ *
+ * @param paths - The paths to format
+ * @param opts - Formatting options
+ * @returns The formatted string
+ */
+export function formatPathsOpt(
+  paths: Path[],
+  opts: FormatPathsOpts = defaultFormatPathsOpts(),
+): string {
+  return formatPathsWithCapturesOpt(paths, new Map(), opts);
+}
+
+/**
+ * Format multiple paths with default options.
+ *
+ * @param paths - The paths to format
+ * @returns The formatted string
+ */
+export function formatPaths(paths: Path[]): string {
+  return formatPathsOpt(paths, defaultFormatPathsOpts());
+}