Skip to content

Combine Consistency

ddddxxx edited this page Oct 12, 2021 · 22 revisions

CombineX is committed to providing identical API and behavior with Apple Combine. Any inconsistent behavior is considered as a bug. Our test suit also run against Apple Combine.

However, there's still some behavior that is not guaranteed to be consistent with Combine:

Known Inconsistency

CXInconsistentTests contains known inconsistent behavior. Some of them need to be fixed.

API Violation

Combine handles API violation inconsistently. For example, if your Publisher send value without requesting demand, some Combine operator let these invalid value slip through, or drop values on the floor, or simply crash. Their behavior also changes over time. In CombineX, we leave such behavior unspecified and not necessarily sync with Apple Combine.

Description and Mirror

Protocol conformance consistency is our goal. But we decide to treat CustomStringConvertible, CustomDebugStringConvertible, and CustomReflectable as implementation details. Our objects still conforms to these protocol, yet they might return different description, debugDescription, and customMirror from Apple Combine. Here is the reason:

  • They are mostly used in debugging situation.
  • It adds a lot of bikeshedding work without obvious benifit.
  • The behavior of Apple Combine is not consistent and actually leak implementation details. e.g: for Publishers.TryMap, Description of Subscription is "TryMap", but for Publishers.Map it's "PassthroughSubject".

Mirror is not part of our public API, obviously.

Extensions on Standard Library, Foundation, and Dispatch

It's not possible for technical reason. Currently Swift is not able to disambiguate between two modules that define the same method or property. Directly extending these type introduces ambiguity therefore you can use neither of them. This issue is tracked here.

To solve this problem, we introduced cx namespace. You need to write result.cx.publisher or dispatchQueue.cx.schedule(...). We promise their behavior is identical to Apple Combine, beside the cx namespace.

The cx and CXWrappers namespace are exclusive to CombineX. You can use CXShim to use them with Apple Combine.

Utility Module

If you use CombineX as dependency, you may find following modules are also importable. It's not public API, use on your own risk.

  • CXUtility

If you are using CocoaPods, these module are available even without import. Be careful.

Others

If you find any other inconsistency, please file an issue, or submit a test case to CXInconsistentTests.