CQL 1.5.3 Implications for CQL Execution

After reviewing the current CQL 1.5.3 CI Build Change Log and corresponding CQL 1.5.3 CI Build specification, we've identified the following items as requiring changes in the current TypeScript CQL Execution engine:

FHIR-48482: Clarified seconds and milliseconds are a single precision in duration and difference calculations

• Update durationBetween and differenceBetween in src/datatypes/datetime.js to treat null milliseconds as 0 when calculating at precisions other than milliseconds.

FHIR-46363: Clarified semantics of null for list membership determination in IndexOf and Equal

• Update IndexOf in src/elm/list.ts to consider null values as equal.
• Update equals in src/util/comparison.ts to consider null values as equal when comparing arrays.
• Review other membership operators, as listed in FHIR-35904, to determine if the exception for null equality is properly implemented.

FHIR-46283: Clarified null behavior for properly includes and included in

• NOTE: I've left a comment on the Jira issue asking for confirmation regarding the calculation of the Interval / point overload when the interval has a null boundary (open or closed) and the point is null. I've also asked for guidance determining how to detect which overload is in play when the second argument is null (since you can't easily tell if it's a list/interval or a point).
  • UPDATE: Bryn has provided answers here indicating that when a boundary is null and the point is null, then the result is null. In addition, he has clarified type precedence in the spec such that the point overload is preferred over the interval overload when the type cannot be determined.
• Update Interval.properlyIncludes in src/datatypes/interval.ts to support the point-based overload. The point-based overload was introduced prior to 1.5.3, but we missed supporting it. As noted above, when comparing a null boundary to a null point, the result is null.
• Update doProperIncludes and doIncludes in src/elm/list.ts to support the point-based overload. The point-based overload was introduced prior to 1.5.3, but we missed supporting it. Based on FHIR-35904, a null point is considered equal to any null item in the list.
• Update ProperIncludes and ProperIncludedIn in src/elm/overloaded.ts to allow for null values on the point-based overloads. If the 2nd argument is null, then consult the signature information in the ELM (if available) to determine which overload to use; otherwise default to the point-based overload (see note above).

FHIR-46437: Added documentation about accessibility of $this and $index elements in sort expressions

• NOTE: This change originally encompassed much more, but based on my review and feedback has been scoped back to behavior within sort only.
• $this is already supported for sort but $index is not.
• Update classes as needed in src/elm/query.ts and related files to support $index.

FHIR-46436: Clarified identifier hiding semantics

• I think the engine supports this already, but we don't currently have any unit tests to verify this.
• Add unit tests to test/elm/query to test identifier hiding with aliases and let clauses.
• Add unit tests to test/elm/reusable to test identifier hiding with function operands.
• If any tests fail, implement fixes as appropriate.

FHIR-45987: Clarified round semantics

• The current implementation uses Math.round which always rounds up. Since the CQL spec now indicates to round away from 0, we need to update Round in src/elm/arithmetic.ts to properly handle rounding negative numbers.

FHIR-44921: Clarified tuple equality semantics with missing elements

• In looking into this, I think I discovered a bug in our code. If two tuples have the same keys, but not all the values are the same, then if the algorithm finds a case where one key's value is null but the other isn't, and that case is evaluated before keys that have different non-null values, it will return null instead of false.
• Update deepCompareKeysAndValues in src/util/comparison.ts so that if only returns null when shouldReturnNull is true and finalComparisonResult is also true.
• Add tests for this specific use case in test/util/comparison-test.ts and test/elm/comparison.
• Fixed in #327.

FHIR-44783: Clarified type compatibility in conversion precedence

• The specific issue addressed in this update does not affect the engine since the engine already determines compatibility of tuples and choices in this way. This language, however, is within a portion of the spec that describes a precedence for resolving overloaded operations -- and the engine does not yet fully implement that precedence as described.
• Improve function resolution for FunctionRef in src/elm/reusable.ts and any corresponding classes/functions it uses for resolution.

FHIR-44826: Clarified regular expression matching behavior

• Previous versions of the specification (or tests?) implied that regular expression matching must match the full string, so the current implementation adds the ^ (start) and $ (end) boundary markers to the regular expression.
• Update Matches in src/elm/string.ts to stop automatically applying the ^ and $ characters to the regular expression.

The following items were reviewed and determined not to have any impact on the TypeScript CQL Execution engine:

• FHIR-46707: Publication uplift to latest tooling (no material changes)
  • No impact since there were no changes to the content.
• FHIR-46483: Corrected spelling of descendants operator as specified in FHIRPath
  • No impact since the engine does not implement this FHIRPath operator. I'm not sure if you can use it outside of FHIRPath, but if so, we could consider supporting it.
• FHIR-46426: Added missing mapping for union in FHIRPath
  • No impact since the engine does not use FHIRPath mappings.
• FHIR-46362: Clarified behavior of equivalent with respect to empty lists and strings
  • No impact since the engine already implements null equivalence in this way.
• FHIR-46360: Clarified concept equivalence semantics
  • No impact since the engine already implements Concept equivalence in this way.
• FHIR-46675: Clarified during operator synonyms in the reference
  • No impact since this is an authoring language option that still results in the same ELM that the engine already supports.
• FHIR-46434: Corrected inconsistent descriptions of combine semantics
  • No impact as the engine already implements combine in this way.
• FHIR-46435: Clarified implicit system model resolution semantics
  • No impact since datatypes are fully qualified in the ELM.
• FHIR-46051: Corrected description of meets and overlaps operators
  • No impact since the engine already implements overlaps and meets in this way.
• FHIR-46053: Clarified semantics of is operator and linked to type testing discussion
  • No impact since this is mainly a concern of cql-exec-fhir, and that already implements is in this way.
• FHIR-45913: Fixed formatting of implicit conversions table
  • No impact since this is just a formatting issue in the spec.
• FHIR-45911: Added missing equivalent and not-equivalent symbols to the symbols table
  • No impact since this is just a formatting issue in the spec.
• FHIR-44830: Corrected day formatting range (01..31)
  • No impact since day 00 doesn't make sense anyway.
• FHIR-44780: Added missing Long overloads for ToQuantity conversions
  • No impact since the engine does not currently support the Long type at all.
• FHIR-41489: Corrected inconsistent statements about overflow/underflow with successor and predecessor
  • No impact since the engine already implements successor and predecessor in this way.
• FHIR-40225: Clarified query type inference and null evaluation semantics
  • No impact since the engine already implements null sources as described.
• FHIR-36050: Corrected links to raw g4 grammar files
  • No impact this this is just fixing a link in the spec.