feat: enhance parseTransactionFlags with string overload and includeAll option (#1903)

- Add overload accepting (txType: string, flags: number) for parsing
  numeric flags directly from raw API responses without constructing
  a full Transaction object
- Add optional { includeAll: true } parameter to include all possible
  flags for a transaction type with their boolean values (not just
  enabled flags)
- Improve return type from object to Record<string, boolean>
- Add missing EnableAmendment and LoanSet to txToFlag mapping
- Add comprehensive tests for all new functionality

Author: slurpyone

packages/xrpl/src/models/utils/flags.ts

@@ -10,8 +10,10 @@ import { AMMDepositFlags } from '../transactions/AMMDeposit'
 import { AMMWithdrawFlags } from '../transactions/AMMWithdraw'
 import { BatchFlags } from '../transactions/batch'
 import { GlobalFlags } from '../transactions/common'
+import { EnableAmendmentFlags } from '../transactions/enableAmendment'
 import { LoanManageFlags } from '../transactions/loanManage'
 import { LoanPayFlags } from '../transactions/loanPay'
+import { LoanSetFlags } from '../transactions/loanSet'
 import { MPTokenAuthorizeFlags } from '../transactions/MPTokenAuthorize'
 import { MPTokenIssuanceCreateFlags } from '../transactions/MPTokenIssuanceCreate'
 import { MPTokenIssuanceSetFlags } from '../transactions/MPTokenIssuanceSet'
@@ -57,8 +59,10 @@ const txToFlag = {
   AMMDeposit: AMMDepositFlags,
   AMMWithdraw: AMMWithdrawFlags,
   Batch: BatchFlags,
+  EnableAmendment: EnableAmendmentFlags,
   LoanManage: LoanManageFlags,
   LoanPay: LoanPayFlags,
+  LoanSet: LoanSetFlags,
   MPTokenAuthorize: MPTokenAuthorizeFlags,
   MPTokenIssuanceCreate: MPTokenIssuanceCreateFlags,
   MPTokenIssuanceSet: MPTokenIssuanceSetFlags,
@@ -141,32 +145,72 @@ export function convertTxFlagsToNumber(tx: Transaction): number {
 /**
  * Convert a Transaction flags property into a map for easy interpretation.
  *
- * @param tx - A transaction to parse flags for.
- * @returns A map with all flags as booleans.
+ * Can be called with a Transaction object or with a transaction type string
+ * and numeric flags value directly (useful when working with raw API responses).
+ *
+ * By default, only enabled (true) flags are included in the result.
+ * Pass `includeAll: true` in options to include all possible flags for the
+ * transaction type with their boolean values.
+ *
+ * @example
+ * ```typescript
+ * // With a Transaction object (existing behavior)
+ * parseTransactionFlags(tx)
+ * // => { tfSell: true }
+ *
+ * // With transaction type and numeric flags
+ * parseTransactionFlags('OfferCreate', 0x00080000)
+ * // => { tfSell: true }
+ *
+ * // Include all possible flags for the transaction type
+ * parseTransactionFlags('Payment', 0x00020000, { includeAll: true })
+ * // => { tfNoRippleDirect: false, tfPartialPayment: true, tfLimitQuality: false }
+ * ```
+ *
+ * @param txOrType - A transaction to parse flags for, or a transaction type string.
+ * @param flagsNum - The numeric flags value (required when txOrType is a string).
+ * @param options - Optional settings.
+ * @param options.includeAll - Set to `true` to include disabled flags.
+ * @returns A map of flag names to booleans.
  */
-export function parseTransactionFlags(tx: Transaction): object {
-  const flags = convertTxFlagsToNumber(tx)
-  if (flags === 0) {
-    return {}
+export function parseTransactionFlags(
+  txOrType: Transaction | string,
+  flagsNum?: number,
+  options?: { includeAll?: boolean },
+): Record<string, boolean> {
+  let flags: number
+  let transactionType: string
+
+  if (typeof txOrType === 'string') {
+    transactionType = txOrType
+    flags = flagsNum ?? 0
+  } else {
+    transactionType = txOrType.TransactionType
+    flags = convertTxFlagsToNumber(txOrType)
   }
 
-  const booleanFlagMap = {}
+  const includeAll = options?.includeAll ?? false
 
-  if (isTxToFlagKey(tx.TransactionType)) {
-    const transactionTypeFlags = txToFlag[tx.TransactionType]
+  const booleanFlagMap: Record<string, boolean> = {}
+
+  if (isTxToFlagKey(transactionType)) {
+    const transactionTypeFlags = txToFlag[transactionType]
     Object.values(transactionTypeFlags).forEach((flag) => {
-      if (
-        typeof flag === 'string' &&
-        isFlagEnabled(flags, transactionTypeFlags[flag])
-      ) {
-        booleanFlagMap[flag] = true
+      if (typeof flag === 'string') {
+        const enabled = isFlagEnabled(flags, transactionTypeFlags[flag])
+        if (enabled || includeAll) {
+          booleanFlagMap[flag] = enabled
+        }
       }
     })
   }
 
   Object.values(GlobalFlags).forEach((flag) => {
-    if (typeof flag === 'string' && isFlagEnabled(flags, GlobalFlags[flag])) {
-      booleanFlagMap[flag] = true
+    if (typeof flag === 'string') {
+      const enabled = isFlagEnabled(flags, GlobalFlags[flag])
+      if (enabled || includeAll) {
+        booleanFlagMap[flag] = enabled
+      }
     }
   })
 

packages/xrpl/test/models/utils.test.ts

@@ -393,6 +393,82 @@ describe('Models Utils', function () {
       const flagsMap = parseTransactionFlags(tx)
       assert.deepEqual(flagsMap, expected)
     })
+
+    it('parseTransactionFlags with transaction type string and numeric flags', function () {
+      const flagsMap = parseTransactionFlags(
+        'PaymentChannelClaim',
+        PaymentChannelClaimFlags.tfRenew,
+      )
+      assert.deepEqual(flagsMap, { tfRenew: true })
+    })
+
+    it('parseTransactionFlags with type string and combined numeric flags', function () {
+      const flagsMap = parseTransactionFlags(
+        'OfferCreate',
+        OfferCreateFlags.tfSell | OfferCreateFlags.tfImmediateOrCancel,
+      )
+      assert.deepEqual(flagsMap, {
+        tfSell: true,
+        tfImmediateOrCancel: true,
+      })
+    })
+
+    it('parseTransactionFlags with type string and zero flags', function () {
+      const flagsMap = parseTransactionFlags('Payment', 0)
+      assert.deepEqual(flagsMap, {})
+    })
+
+    it('parseTransactionFlags with type string, numeric flags, and includeAll', function () {
+      const flagsMap = parseTransactionFlags(
+        'Payment',
+        PaymentFlags.tfPartialPayment,
+        { includeAll: true },
+      )
+      assert.deepEqual(flagsMap, {
+        tfNoRippleDirect: false,
+        tfPartialPayment: true,
+        tfLimitQuality: false,
+        tfInnerBatchTxn: false,
+      })
+    })
+
+    it('parseTransactionFlags with Transaction object and includeAll', function () {
+      const tx: PaymentChannelClaim = {
+        Account: 'r...',
+        TransactionType: 'PaymentChannelClaim',
+        Channel:
+          'C1AE6DDDEEC05CF2978C0BAD6FE302948E9533691DC749DCDD3B9E5992CA6198',
+        Flags: PaymentChannelClaimFlags.tfRenew,
+      }
+
+      const flagsMap = parseTransactionFlags(tx, undefined, {
+        includeAll: true,
+      })
+      assert.deepEqual(flagsMap, {
+        tfRenew: true,
+        tfClose: false,
+        tfInnerBatchTxn: false,
+      })
+    })
+
+    it('parseTransactionFlags with unknown transaction type and global flags only', function () {
+      const flagsMap = parseTransactionFlags(
+        'SetRegularKey',
+        GlobalFlags.tfInnerBatchTxn,
+      )
+      assert.deepEqual(flagsMap, { tfInnerBatchTxn: true })
+    })
+
+    it('parseTransactionFlags with type string including global flag', function () {
+      const flagsMap = parseTransactionFlags(
+        'PaymentChannelClaim',
+        PaymentChannelClaimFlags.tfRenew | GlobalFlags.tfInnerBatchTxn,
+      )
+      assert.deepEqual(flagsMap, {
+        tfRenew: true,
+        tfInnerBatchTxn: true,
+      })
+    })
   })
 
   describe('convertTxFlagsToNumber', function () {