[Feature Request] Enhance support for MongoDB Operators in FSXA-API Library

[PepoMarko]

The current implementation of the fsxa-api library does not support several standard MongoDB query operators, including $elemMatch and $exists.

This significantly limits the ability to express complex filter logic in CaaS queries. Specifically, it is currently impossible to apply $elemMatch.

---

Example Use Case:

I want to build a query that does the following:

• Check if a field (e.g., formData.tt_permissions.value) exists
• If it exists, apply $elemMatch with $in on its contents

This is not possible currently because:

• Using $elemMatch as an operator directly in the FSXA query builder results in:

  Unknown operator passed

• Using $exists is also unsupported but one can use $eq with the null value instead, which works similarly.

• I approached the problem using QueryBuilderQuery like this:

  function getTypePermissionsFilter(type: PermissionType, typePermissions: Set<string> | Array<string>) {
      const permissionFieldName = permissionHelper.mapPermissionTypeToFieldName(type);
      return {
          operator: LogicalQueryOperatorEnum.OR,
          filters: [
              {
                  operator: ComparisonQueryOperatorEnum.EQUALS,
                  field: `formData.tt_permissions.value.formData.${permissionFieldName}`,
                  value: null
              },
              {
                  operator: ComparisonQueryOperatorEnum.EQUALS,
                  field: `formData.tt_permissions.value.formData.${permissionFieldName}.value`,
                  value: []
              },
              {
                  operator: '$elemMatch',
                  field: `formData.tt_permissions.value.formData.${permissionFieldName}.value`,
                  value: {
                      'label': {
                          '$in': [...typePermissions]
                      }
                  }
              }
          ]
      } as LogicalFilter;
  }

• This problem can be solved with the filter CaaS query directly inside the URL. Here is the example for query by lt_role permission type:

  {
     "$or":[
        {
           "page.formData.tt_permissions.value.formData.lt_role":{
              "$eq":null
           }
        },
        {
           "page.formData.tt_permissions.value.formData.lt_role.value":{
              "$eq":[]
           }
        },
        {
           "page.formData.tt_permissions.value.formData.lt_role.value":{
              "$elemMatch":{
                 "label":{
                    "$in":[
                       "VDs",
                       "Direct Sales"
                    ]
                 }
              }
           }
        }
     ]
  }
  

---

Why This Matters:

These operators are part of the standard MongoDB query language and are crucial for:

• Safely querying optional fields
• Filtering documents by matching values in nested arrays or objects
• Preventing runtime errors due to accessing undefined properties

---

Requested Enhancement:

• Add support for $elemMatch operator in the FSXA-API query builder.
• Optionally: expose a way to pass raw MongoDB filters to allow more advanced use cases without being constrained by the internal operator mapping logic.

[nico-mcalley]

Hi PepoMarko!

Thank you for your feature request.
There are two main options available for moving forward:

1. Submit a Pull Request (PR): We work together to bring your improvements to this repository.
2. Work in a Fork: Alternatively, you can implement the feature in a personal fork of the project.

A fork can often be the more practical approach, especially if you prefer to move independently and at your own pace. It gives you full control over the implementation, though it may introduce slight divergences from the main project.
A Pull Request may be slower and more work, as it requires review, adherence to project standards, and may be rejected if it doesn't align.
Adding an $elemMatch operator appears to be a small, relevant and potentially beneficial use case for other users of this project as well.
If you choose to contribute via a Pull Request, please ensure that it meets the following criteria:

• The changes are concise and limited in scope (eg affecting the least amount of files necessary)
• Backward compatibility is maintained
• New functionality is thoroughly tested
• Existing tests continue to pass
• The PR can be merged cleanly without conflicts
• Additionally, please make sure to read and follow our contribution guide before submitting a PR.

Best regards,
Nico