Proposing to expand `available` to introduce `discouraged`

Evolution Pitches
11

I support this pitch. I have recently used deprecated in order to warn the user against a sub-efficient use of a method.

The context: a SinglerPublisher subprotocol of Combine's Publisher provides the guarantee that a publisher publishes exactly one element, or an error. SinglePublisher · GitHub

The protocol comes with operators that check, at runtime, if a publisher honors the contract:

// Completes with a `SingleError` if contract is not honored
let singlePublisher = publisher.checkSingle()

// Raises a fatal error if contract is not honored
let singlePublisher = publisher.assertSingle()

Those runtime checks are both useless and costly for publishers that are statically known to conform to SinglePublisher, such as Just, Result.Publisher, Publishers.Map when upstream is already a single publisher, etc.

  • I want the compiler to discourage the user from using the checking operators checkSingle() and assertSingle() on such publishers.

  • I want the compiler to let the user know a checking operator checkSingle() and assertSingle() in no longer needed once SinglePublisher conformance has been added to a publisher type.

Today, I have to use deprecated:

extension SinglePublisher {
    /// :nodoc:
    @available(*, deprecated, message: "Publisher is already a single publisher")
    func checkSingle() -> CheckSinglePublisher<Self> {
        CheckSinglePublisher(upstream: self)
    }
    
    /// :nodoc:
    @available(*, deprecated, message: "Publisher is already a single publisher")
    public func assertSingle() -> AssertSinglePublisher<Self> {
        checkSingle().assertNoSingleFailure()
    }
    
    /// :nodoc:
    @available(*, deprecated, message: "Publisher is already a single publisher: use publisher.eraseToAnySinglePublisher() instead.")
    public func uncheckedSingle() -> AnySinglePublisher<Output, Failure> {
        AnySinglePublisher(self)
    }
}

Unfortunately, those methods are not deprecated. They are indeed quite supported. I just want the compiler to emit a warning when they are misused.

4 Likes