Once
A property wrapper that allows you to enforce that a closure is called exactly once. This is especially useful after the introduction of SE-0293 which makes it legal to place property wrappers on function and closure parameters.
Motivation
It’s very common to write code where you have a function with a completion handler which must be called with a success or failure value based on the underlying result of the work that the function does. But if you’re not careful, it can be easy to make mistakes where you don’t call the completion handler at all or call it more than once, especially if there’s complicated business logic or error handling.
func fetchSpecialUser(@Once completion: @escaping (Result
Error>)
->
Void) {
fetchUserImpl { user
in
guard
let user
= user
else {
// oops, forgot to call completion(...) here!
return
}
guard user.
isPendingEmailVerification
==
false
else {
completion(.
failure(.
userNotVerified))
return
}
if user.
hasSubscription {
switch
getSubscriptionType(user) {
case .
ultimate, .
premium
:
completion(.
success(user))
case .
standard
:
completion(.
failure(.
noPaidSubscription))
}
}
// ... more business logic here
// oops, forgot a 'return' in the if-statement above,
// so execution continues and closure is called twice
// (and with an invalid result!).
completion(.
failure(.
generic))
}
Usage
Simply annotate your function parameters with @Once and you will get a runtime error if the closure is not called at all or called more than once.
func fetchSpecialUser(@Once completion: @escaping (Result
Error>)
->
Void) {
fetchUserImpl { user
in
guard
let user
= user
else {
// runtime error: expected closure to have already been executed once!
return
}
guard user.
isPendingEmailVerification
==
false
else {
completion(.
failure(.
userNotVerified))
return
}
if user.
hasSubscription {
switch
getSubscriptionType(user) {
case .
ultimate, .
premium
:
completion(.
success(user))
case .
standard
:
completion(.
failure(.
noPaidSubscription))
}
}
// ... more business logic here
// runtime error: closure has already been invoked!
completion(.
failure(.
generic))
}
Note: There's also @ThrowingOnce which you can use if the closure throws.
Requirements
- Swift 5.2 or above
Limitations
- The property wrapper can only be used with escaping closures. If you want to use it on a non-escaping closure, you will need to annotate it with
@escaping. This is not ideal, but because the closure is stored inside the property wrapper, there is no way to say to the compiler that the closure does not escape when you know for a fact it doesn't (perhaps because your code is synchronous).
Installation
Add the following to your project's Package.swift file:
.package(url: "https://github.com/theblixguy/Once", from: "0.0.1")
or add this package via the Xcode UI by going to File > Swift Packages > Add Package Dependency.
License
MIT License
Copyright (c) 2021 Suyash Srijan
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
42 Dec 28, 2022
8 Aug 17, 2022
324 Dec 14, 2022
1.2k Dec 28, 2022
1.6k Dec 21, 2022
178 Sep 16, 2022
1 Oct 29, 2021
143 Oct 11, 2022
0 Dec 30, 2021
5 Jun 21, 2022
120 Jul 31, 2022
5 Jun 21, 2021
61 Nov 23, 2022
12 Aug 5, 2022
20 Nov 16, 2022
3 Feb 22, 2022
472 Dec 18, 2022
102 Dec 29, 2022
51 Dec 8, 2022
276 Aug 14, 2022
2 Aug 20, 2022
7 Nov 21, 2022
5 Dec 16, 2021
3 May 9, 2022
36 Jan 1, 2023
1.3k Dec 26, 2022
16.9k Dec 30, 2022
304 Dec 29, 2022