XO Integration Part II

packages/primitives/package.json

@@ -13,6 +13,7 @@
     "build": "tsc --build --clean && tsc --build",
     "prepublishOnly": "npm run build",
     "format": "prettier --write \"**/*.{js,ts,md,json}\" --ignore-path .gitignore",
+    "madge": "npx madge --circular ./src/index.ts",
     "test": "vitest --run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",

packages/primitives/src/satoshis.ts

@@ -1,4 +1,4 @@
-export type BCHUnits = ['sats', 'bits', 'mBCH', 'BCH'];
+export type BCHUnits = 'sats' | 'bits' | 'mBCH' | 'BCH';
 
 /**
  * Satoshis Primitive
@@ -206,4 +206,70 @@ export class Satoshis {
   toRaw() {
     return this.satoshis;
   }
+
+  /**
+   * Formats the amount in the specified unit with formatting options.
+   *
+   * @param units - The unit to format as ('sats', 'bits', 'mBCH', 'BCH')
+   * @param opts - Formatting options
+   * @param opts.roundToDigits - Number of decimals to round to
+   * @param opts.appendSuffix - Whether to append the unit suffix
+   * @returns Formatted amount as string
+   *
+   * @example
+   * // Format as BCH with 2 decimal places and suffix
+   * satoshis.format('BCH', { roundToDigits: 2, appendSuffix: true }) // "0.12 BCH"
+   *
+   * @example
+   * // Format as satoshis without suffix
+   * satoshis.format('sats', { roundToDigits: 0, appendSuffix: false }) // "12345678"
+   */
+  public format(
+    units: BCHUnits,
+    opts: {
+      roundToDigits?: number;
+      appendSuffix?: boolean;
+      showApproximationSymbol?: boolean;
+    } = {},
+  ): string {
+    // Set default values if not provided
+    const roundToDigits = opts.roundToDigits ?? 4;
+    const appendSuffix = opts.appendSuffix ?? true;
+    const showApproximationSymbol = opts.showApproximationSymbol ?? true;
+
+    // Get the exact amount in the specified unit before rounding
+    let exactAmount: number;
+
+    // Use type assertion to help TypeScript understand this is a valid BCHUnits value
+    switch (units) {
+      case 'sats':
+        exactAmount = this.toSats();
+        break;
+      case 'bits':
+        exactAmount = Number(this.satoshis) / 100;
+        break;
+      case 'mBCH':
+        exactAmount = Number(this.satoshis) / 100_000;
+        break;
+      case 'BCH':
+        exactAmount = Number(this.satoshis) / 100_000_000;
+        break;
+      default:
+        throw new Error(`Unsupported unit: ${units}`);
+    }
+
+    // Format the amount with the specified number of decimal places
+    const roundedAmount = Satoshis.roundToDigits(exactAmount, roundToDigits);
+
+    // Check if rounding occurred
+    const wasRounded = exactAmount !== roundedAmount;
+
+    // Add approximation symbol if needed and enabled
+    const prefix = wasRounded && showApproximationSymbol ? '~' : '';
+
+    // Return the formatted amount with prefix and/or suffix
+    return appendSuffix
+      ? `${prefix}${roundedAmount} ${units}`
+      : `${prefix}${roundedAmount}`;
+  }
 }

packages/stack/package.json

@@ -23,6 +23,7 @@
     "bench": "vitest bench",
     "build": "tsc --build --clean && tsc --build",
     "format": "prettier --write \"**/*.{js,ts,md,json}\" --ignore-path .gitignore",
+    "madge": "npx madge --circular ./src/index.ts",
     "prepublishOnly": "npm run build",
     "test": "vitest --run",
     "test:coverage": "vitest run --coverage",