Awesome
CXShim
CXShim is a virtual Combine interface that allows you to switch berween system Combine and open source Combine.
With CXShim, you shoudn't write different code for different Combine. If you find you are in need of it, please file an issue.
Installation
Add the following line to the dependencies in your Package.swift
file:
.package(url: "https://github.com/cx-org/CXShim", .upToNextMinor(from: "0.4.0"),
Requirements
- Swift 5.0+
Q&A
Why do I need it?
Because Combine has system limitation, and open source Combine doesn't compatible with SwiftUI. With CXShim, You can easily write one package that compatible with SwiftUI, support Linux, and can backward deploy to iOS 9.0.
Is there any downside?
No, CXShim introduce no extra dependency, no runtime cost, no binary size incrementation. It's not infectious. Migrating from Combine to CXShim is a non-breaking change.
Looks great! How can I adopt it?
If your package use Combine, just replace every import Combine
with import CXShim
, everything will still works fine. And with a little adjustment, your package can support Linux and lower system as well.
Why this library requires iOS 13+ / macOS 10.15+?
Because system Combine is used by default on Apple platforms. Don't worry, you can choose open source Combine manually and get rid of system requirement.
How do I choose which Combine to use?
You can choose Combine implementation by setting environment variable CX_COMBINE_IMPLEMENTATION
.
Library | Value of CX_COMBINE_IMPLEMENTATION |
---|---|
Combine (default on Apple platforms) | Combine |
CombineX (default on Linux) | CombineX |
Others | See below |
$ export CX_COMBINE_IMPLEMENTATION=CombineX
# for CLI tools, execute with env variable
$ swift build ...
$ xcodebuild ...
# for Xcode GUI, reopen Xcode with env variable
$ killall Xcode
$ open Package.swift
How it actually works?
CXShim
conditionally re-export appropriate Combine implementation. It also fill the gap between different Combine. For example, you would have needed to write different code for Combine
and CombineX
:
#if BACKWARD_DEPLOYMENT // we are target on lower system and use CombineX
// This method is under cx namespace because `URLSession.dataTaskPublisher`
// can't be overloaded and always use system Combine.
let pub = URLSession.shared.cx.dataTaskPublisher(for: url)
#else // use system Combine
let pub = URLSession.shared.dataTaskPublisher(for: url)
#endif
With CXShim
, you don't need compilation flags anymore:
import CXShim
// `cx` namespace is available even if you're using system Combine
let pub = URLSession.shared.cx.dataTaskPublisher(for: url)
Can I use other open source Combine?
Yes you can! CXShim
support every known Combine implementations and will support any future one. Just set environment variable CX_COMBINE_IMPLEMENTATION
to their respective value. If your library is not listed below, feel free to open an issue.
Library | Value of CX_COMBINE_IMPLEMENTATION |
---|---|
OpenCombine | OpenCombine |
Disclaimer: These project are not part of CombineX. They may have different consistent level with Apple's Combine than we promised, and not necessarily pass our test suit. We do not make any warranty of any kind for them.