TL;DR?
Reusable type-safe support for automatic plural forms in English & 7 other languages. Full code snippet at the end of the article

First things first, what do I mean when I say “pluralize”?

It’s a very common problem in app development. I’m sure you’ve written something like this at some point:

let count = 10
let articleCountString = "\(count) \(count == 1 ? "article" : "articles")"

It feels quite annoying, not to say incredibly wrong.

Obviously, the correct way to handle this is to use Xcode’s string catalogs, which support adding separate forms for different kinds of plurals.

The UI is even somewhat convenient, and definitely a huge improvement over stringsdict files that we had to use in pre-Xcode 15 era.

But, of course, it still takes you out of writing code and into some Xcode configuration files, and of course you still need to write different plural forms yourself.

A better way

Just to reiterate, if you want to do everything by the book, use Xcode string catalogs. But if you want something quicker, simpler and more convenient, there is a well-hidden Swift feature called automatic grammar agreement.

It almost feels like it shouldn’t work, but it does. Here’s an example from an excellent article by Natalia Panferova:

Text("You read ^[\(bookCount) book](inflect: true) this year!")

Believe it or not, in SwiftUI this will actually produce a text of “You read 10 books this year!” or “You read 1 book this year!”, depending on the bookCount

Now, I’m not gonna go into too much detail about how exactly it works. If you want, here are some great articles:

• Morphology in Swift by Jordan Morgan
• Handle plurals in SwiftUI Text views with inflection by Natalia Panferova

The issue with Swift’s inflection is that the easiest way to use it is in SwiftUI Text. And even then, you need to remember an obscure ^[\(count) item](inflect: true) syntax, which compiler knows nothing about. Make a typo or a mistake? Tough luck, now it doesn’t work. Want to use inflection outside of SwiftUI? Not your day.

Luckily, we can quite easily navigate the labyrinth of Swift’s String-adjacent types to make inflection easy-to-use and error-proof anywhere in our app.

First, let’s create a reusable function that will write the inflect: true syntax for us:

func pluralize(
    _ count: Int,
    _ text: LocalizedStringResource
) -> LocalizedStringResource {
    "^[\(count) \(text)](inflect: true)"
}

To use inflection, we must use these LocalizedStringResource types, which Swift will be able to “unfold” into localized text down the line.

Next, we create a localization template of type String.LocalizationValue, that we then need to feed into the AttributedString(localized:) initializer:

let count = 6
let template: String.LocalizationValue = """
You read \(pluralize(count, "book")) this year
"""
let localized = AttributedString(localized: template)

But of course, while AttributedString is useful on its own, mostly in app development we want to deal with plain String instances. Luckily, converting AttributedString to String is possible:

let string = String(localized.characters[...])

Now we finally get “You read 6 books this year”. If it feels like too many steps, it’s because it is. For such an incredibly useful feature, it sure is quite well-hidden (and also poorly documented).

And, to make things worse, it is incredibly easy to misuse some of these types and end up with a gibberish like You read LocalizedStringResource(key: “^[%lld %@](inflect: true)”, defaultValue... in your UI instead of the text you need.

Luckily, we can make things much easier and type-safe so that no one will misuse it.

First, we will move pluralize into a semi-private type, so that we can “lock” this API for only certain scenarios:

struct InflectionBuilder {
    fileprivate init() { }
    func pluralize(
        _ count: Int,
        _ text: LocalizedStringResource
    ) -> LocalizedStringResource {
        "^[\(count) \(text)](inflect: true)"
    }
}

As you see, no one can freely create and use InflectionBuilder on their own. Instead, its usage will be restricted to our function called inflected:

extension String {
    static func inflected(
        _ makeTemplate: (InflectionBuilder) -> String.LocalizationValue
    ) -> String {
        let builder = InflectionBuilder()
        let template = makeTemplate(builder)
        let attributed = AttributedString(localized: template)
        return String(attributed.characters[...])
    }
}

We encapsulated all the necessary steps behind a type-safe API. Now we can use it like this:

let pluralized = String.inflected {
    "You read \($0.pluralize(count, "book")) this year"
}

It is required to use String interpolation here. Do not attempt to “build” a full string by concatenating several strings together with a String.inflected in the middle, because Swift gathers clues from the entire sentence to determine the language and other grammar information.

More notes:

• You are not limited to just using a single word. If you write “published book” instead of “book”, inflected will auto-convert to “5 published books” as well
• I strongly recommend only using singular forms of words when writing pluralize. So always write “book” not “books”.
• As per documentation, in addition to English the automatic grammar agreement feature also supports Spanish, German, French, Italian, Portuguese, Hindi, and Korean, with more languages hopefully coming in future iOS versions.

TL;DR: Full code snippet with extended functionality

extension String {
    /// Allows automatic pluralization using the `(inflect: true)` attribute. Use `$0.pluralize` with string interpolation to produce inflected strings
    ///
    /// For reference, see:
    /// - [How to pluralize English text in Swift without using Localizable strings - olegdreyman](https://olegdreyman.medium.com/how-to-pluralize-english-text-in-swift-without-using-localizable-strings-dc3e0348f1f3)
    /// - [Morphology in Swift - swiftjectivec](https://www.swiftjectivec.com/morphology-in-ios-with-automatic-grammar-agreement/)
    /// - [Handle plurals in SwiftUI Text views with inflection - nilcoalescing](https://nilcoalescing.com/blog/HandlePluralsInSwiftUITextViewsWithInflection/)
    /// - [Taking advantage of the iOS 15 grammar agreement feature for English strings - stackoverflow](https://stackoverflow.com/a/68156533)
    static func inflected(
        options: AttributedString.LocalizationOptions = .init(),
        _ makeTemplate: (InflectionBuilder) -> String.LocalizationValue
    ) -> String {
        let builder = InflectionBuilder()
        let template = makeTemplate(builder)
        let attributed = AttributedString(localized: template, options: options)
        return String(attributed.characters[...])
    }
}

extension AttributedString {
    /// Allows automatic pluralization using the `(inflect: true)` attribute. Use `$0.pluralize` with string interpolation to produce inflected strings
    ///
    /// For reference, see:
    /// - [How to pluralize English text in Swift without using Localizable strings - olegdreyman](https://olegdreyman.medium.com/how-to-pluralize-english-text-in-swift-without-using-localizable-strings-dc3e0348f1f3)
    /// - [Morphology in Swift - swiftjectivec](https://www.swiftjectivec.com/morphology-in-ios-with-automatic-grammar-agreement/)
    /// - [Handle plurals in SwiftUI Text views with inflection - nilcoalescing](https://nilcoalescing.com/blog/HandlePluralsInSwiftUITextViewsWithInflection/)
    /// - [Taking advantage of the iOS 15 grammar agreement feature for English strings - stackoverflow](https://stackoverflow.com/a/68156533)
    static func inflected(
        options: AttributedString.LocalizationOptions = .init(),
        _ makeTemplate: (InflectionBuilder) -> String.LocalizationValue
    ) -> AttributedString {
        let builder = InflectionBuilder()
        let template = makeTemplate(builder)
        let attributed = AttributedString(localized: template, options: options)
        return attributed
    }
}

struct InflectionBuilder {
    fileprivate init() { }
    
    /// Can only be used with string interpolation inside `String.inflected { }` or `AttributedString.inflected { }`. Allows automatic pluralization of text.
    ///
    /// - Warning: Use a **singular** form of the word. So "value"/"active user", not "values"/"active users"
    ///
    /// For reference, see:
    /// - [How to pluralize English text in Swift without using Localizable strings - olegdreyman](https://olegdreyman.medium.com/how-to-pluralize-english-text-in-swift-without-using-localizable-strings-dc3e0348f1f3)
    /// - [Morphology in Swift - swiftjectivec](https://www.swiftjectivec.com/morphology-in-ios-with-automatic-grammar-agreement/)
    /// - [Handle plurals in SwiftUI Text views with inflection - nilcoalescing](https://nilcoalescing.com/blog/HandlePluralsInSwiftUITextViewsWithInflection/)
    /// - [Taking advantage of the iOS 15 grammar agreement feature for English strings - stackoverflow](https://stackoverflow.com/a/68156533)
    func pluralize(
        _ count: Int,
        _ text: LocalizedStringResource
    ) -> LocalizedStringResource {
        "^[\(count) \(text)](inflect: true)"
    }
}

Usage:

let activeUserCount = 10
let activeUsers: String = .inflected {
    "There are \($0.pluralize(activeUserCount, "active user")) online"
} // There are 10 active users online

Thanks for reading! If you want to support me, please check out my apps: “Ask Yourself Everyday”, “Time and Again” & “Learn Numbers: Foreign Languages”.

For business inquiries, please reach out to me at oleg@dreyman.dev

If you ever try to figure out how to use Foundation’s Timer in SwiftUI, the first thing you’ll see will be something like this:

struct CurrentDateView: View {
    @State private var currentDate = Date.now
    
    let timer = Timer.publish(every: 1, on: .main, in: .common).autoconnect()

    var body: some View {
        Text(currentDate.formatted(date: .numeric, time: .standard))
            .onReceive(timer) { input in
                currentDate = input
            }
    }
} 

You create a Combine publisher directly via Timer.publish function, and then “listen” to it with the onReceive modifier on your view.

And while there’s nothing particularly wrong with this (it works exactly as it should), I’d argue there’s a better way to achieve this.

Two things that are imperfect about this solution, in my opinion, are:

1. Because of all the peculiarities of Timer publisher (remembering what run loop modes to use, and remembering the autoconnect() call), the API feels unintuitive and you’ll likely end up googling this snippet every time.
2. Having a timer publisher as a free-standing property of your View adds unnecessary clutter and complexity for something that should be quite simple, and feels out of place in declarative SwiftUI code.

Solution: reusable TimerModifier

A much better solution is to encapsulate this logic in a ViewModifier that you can then easily reuse in any part of your app. The end result will look like this:

struct CurrentDateView: View {
    @State private var currentDate = Date.now

    var body: some View {
        Text(currentDate.formatted(date: .numeric, time: .standard))
            .onTimer(every: 1) { date in
                currentDate = date
            }
    }
}

Doesn’t it look and feel much cleaner?

The implementation itself is also trivial, because we’re basically encapsulating our publisher logic within a separate ViewModifier

struct TimerModifier: ViewModifier {
    @State private var timer: Publishers.Autoconnect<Timer.TimerPublisher>
    private let perform: (Date) -> Void
    
    init(
        every interval: TimeInterval,
        tolerance: TimeInterval?,
        perform: @escaping (Date) -> Void
    ) {
        self.timer = Timer.publish(every: interval, tolerance: tolerance, on: .main, in: .common)
            .autoconnect()
        self.perform = perform
    }
    
    func body(content: Content) -> some View {
        content
            .onReceive(timer) { date in
                self.perform(date)
            }
    }
}

extension View {
    func onTimer(
        every interval: TimeInterval,
        tolerance: TimeInterval? = nil,
        perform: @escaping (Date) -> Void
    ) -> some View {
        self.modifier(
            TimerModifier(
                every: interval,
                tolerance: tolerance,
                perform: perform
            )
        )
    }
}

// usage:
Text(currentDate.formatted(date: .numeric, time: .standard))
    .onTimer(every: 1, tolerance: 0.05) { date in
        currentDate = date
    }

As you see, we can also easily supply tolerance to our timer with this modifier.

In my opinion, this is one of the under-appreciated features of the ViewModifier — they can contain their own internal @State and all other SwiftUI observations, and can nicely encapsulate complicated logic.

Now you can use .onTimer API in any part of your app, without ever needing to look up how to use it, or caring about the intricacies of its Combine API.

Bonus 1: Cancellation

Cancelling a Timer publisher is even more of a hassle because you need to remember this exciting line:

timer.upstream.connect().cancel()

To incorporate cancellations into our onTimer modifier, we will use something called a “Trigger value pattern”. It’s used in a bunch of Apple’s own APIs and you can find a great overview of it here: Trigger value pattern in SwiftUI.

In short, we will add a cancelTrigger property to our TimerModifier, and monitor its change via the onChange modifier, so whenever the cancelTrigger value changes, we will use it to cancel the underlying Timer.

struct TimerModifier: ViewModifier {
    @State private var timer: Publishers.Autoconnect<Timer.TimerPublisher>
    let cancelTrigger: AnyHashable?
    private let perform: (Date) -> Void
    
    init(
        every interval: TimeInterval,
        tolerance: TimeInterval?,
        cancelTrigger: AnyHashable?,
        perform: @escaping (Date) -> Void
    ) {
        self.timer = Timer.publish(every: interval, tolerance: tolerance, on: .main, in: .common)
            .autoconnect()
        self.cancelTrigger = cancelTrigger
        self.perform = perform
    }
    
    func body(content: Content) -> some View {
        content
            .onReceive(timer) { date in
                self.perform(date)
            }
            .onChange(of: cancelTrigger) {
                self.timer.upstream.connect().cancel()
            }
    }
}

extension View {
    func onTimer(
        every interval: TimeInterval,
        tolerance: TimeInterval? = nil,
        cancelTrigger: AnyHashable? = nil, // providing a trigger is optional
        perform: @escaping (Date) -> Void
    ) -> some View {
        self.modifier(
            TimerModifier(
                every: interval,
                tolerance: tolerance,
                cancelTrigger: cancelTrigger,
                perform: perform
            )
        )
    }
}

And this is how we can cancel a Timer by pressing a button

struct CurrentDateView: View {
    @State private var currentDate = Date.now
    @State private var cancelTimer = false

    var body: some View {
        VStack {
            Text(currentDate.formatted(date: .numeric, time: .standard))
            Button("Stop Timer") {
                cancelTimer = true
            }
        }
        .onTimer(every: 1, cancelTrigger: cancelTimer) { date in
            currentDate = date
        }
    }
}

Of course, the timer is also automatically cancelled when the View is removed from the render tree.

Conclusion

The main idea behind this article is not just to help you simplify the usage of the Timer in SwiftUI, but to generally suggest using view modifiers to encapsulate complicated logic. We all should strive to make our views as clean and readable as possible, and creating reusable view modifiers are a great way to achieve that.

A nicely packaged and extended version of this solution is available as a GitHub gist:

Stop using Timer.publish in your SwiftUI views was originally published in Parable Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you’ve ever worked on an iOS app with complex networking, sooner or later you’ll probably need to create ZIP archives from your files. In fact, zipping large files can significantly reduce the size of your HTTP payloads, giving you better networking performance & data usage. It is also arguably the best way to send over multiple files at once, instead of building out a huge multi-part request or sending a separate request for each file.

For most developers, the first instinct when approaching this problem is to reach for a third-party dependency that does it for you. “Zip” by marmelroy is a great Swift library that does just that. However, if you only need to create ZIP files, not unzip them, using Apple’s system API is enough.

Here’s how you can do it using Apple’s NSFileCoordinatorReadingForUploading API:

enum CreateZipError: Swift.Error {
    case urlNotADirectory(URL)
    case failedToCreateZIP(Swift.Error)
}

func createZip(
    zipFinalURL: URL,
    fromDirectory directoryURL: URL
) throws -> URL {
    // see URL extension below
    guard directoryURL.isDirectory else {
        throw CreateZipError.urlNotADirectory(directoryURL)
    }
    
    var fileManagerError: Swift.Error?
    var coordinatorError: NSError?
    let coordinator = NSFileCoordinator()
    coordinator.coordinate(
        readingItemAt: directoryURL,
        options: .forUploading,
        error: &coordinatorError
    ) { zipCreatedURL in
        do {
            // will fail if file already exists at finalURL
            // use `replaceItem` instead if you want "overwrite" behavior
            try FileManager.default.moveItem(at: zipCreatedURL, to: zipFinalURL)
        } catch {
            fileManagerError = error
        }
    }
    if let error = coordinatorError ?? fileManagerError {
        throw CreateZipError.failedToCreateZIP(error)
    }
    return zipFinalURL
}

extension URL {
    var isDirectory: Bool {
       (try? resourceValues(forKeys: [.isDirectoryKey]))?.isDirectory == true
    }
}

let mediaDirectoryURL = /* ... */

let zipURL = try createZip(
    zipFinalURL: FileManager.default.temporaryDirectory.appending(path: "new_archive.zip"),
    fromDirectory: mediaDirectoryURL
)

Per Apple’s documentation, the ZIP file will only be created if a provided URL is a directory:

If the item being read is a directory (such as a document package), then the snapshot is a new file containing the zipped contents of the directory. The URL passed to the accessor block points to the zipped file.

This is why we’re using guard directoryURL.isDirectory at the top of the function.

A helper function to easily create zip files in the tmp directory is also a good idea:

func createZipAtTmp(
    zipFilename: String,
    zipExtension: String = "zip",
    fromDirectory directoryURL: URL
) throws -> URL {
    let finalURL = FileManager.default.temporaryDirectory
        .appending(path: zipFilename)
        .appendingPathExtension(zipExtension)
    return try createZip(
        zipFinalURL: finalURL,
        fromDirectory: directoryURL
    )
}

let mediaDirectoryURL = /* ... */

let zipURL = try createZipAtTmp(
    zipFilename: "new_archive",
    fromDirectory: mediaDirectoryURL
)

Bonus: simplifying ZIP directory composition

To simplify creating the “directory to be zipped”, at Parable we built an additional layer called FileToZip

enum FileToZip {
    case data(Data, filename: String)
    case existingFile(URL)
    case renamedFile(URL, toFilename: String)
}

extension FileToZip {
    func prepareInDirectory(directoryURL: URL) throws {
        switch self {
        case .data(let data, filename: let filename):
            let fileURL = directoryURL.appendingPathComponent(filename)
            try data.write(to: fileURL)
        case .existingFile(let existingFileURL):
            let filename = existingFileURL.lastPathComponent
            let newFileURL = directoryURL.appendingPathComponent(filename)
            try FileManager.default.copyItem(at: existingFileURL, to: newFileURL)
        case .renamedFile(let existingFileURL, toFilename: let filename):
            let newFileURL = directoryURL.appendingPathComponent(filename)
            try FileManager.default.copyItem(at: existingFileURL, to: newFileURL)
        }
    }
}

prepareInDirectory will then be used by our zip function to create a “directory to be zipped” for us

func createZipAtTmp(
    zipFilename: String,
    zipExtension: String = "zip",
    filesToZip: [FileToZip]
) throws -> URL {
    let directoryToZipURL = FileManager.default.temporaryDirectory
        .appending(path: UUID().uuidString)
        .appending(path: zipFilename)
    try FileManager.default.createDirectory(at: directoryToZipURL, withIntermediateDirectories: true, attributes: [:])
    for fileToZip in filesToZip {
        try fileToZip.prepareInDirectory(directoryURL: directoryToZipURL)
    }
    return try createZipAtTmp(
        zipFilename: zipFilename,
        zipExtension: zipExtension,
        fromDirectory: directoryToZipURL
    )
}

let pngImageData: Data = /* ... */
let videoURL: URL = /* ... */
let dbFileURL: URL = /* ... */

let zipURL = try createZipAtTmp(
    zipFilename: "new_archive",
    filesToZip: [
        .data(imageData, filename: "image.png"),
        .existingFile(videoURL),
        .renamedFile(dbFileURL, toFilename: "local_db.sqlite")
    ]
)

A few important things to note in there:

1. As you see, we’re creating our “directory to be zipped” inside another directory with a UUID name — this is done to avoid possible naming collisions. You can remove this part, if you prefer.
2. If at least one “file to zip” can’t be prepared in a directory, the entire operation will fail. This can happen, for example, if two or more files will have the same filename. You might want to handle errors differently there.
3. In all of the functions, if the “zip filename” you’re trying to create already exists in the final destination, the operation will fail. If you don’t want that, use “replaceItem” instead of “moveItem” in the original createZip function

Conclusion

As you can see, it’s quite straightforward to create ZIP files on iOS using nothing but system APIs. Important to note that for unzipping, however, you will need to use a third-party solution.

A nicely packaged and extended version of this solution is available as a GitHub gist:

ZipService.swift

How to easily create ZIP files in Swift without third-party dependencies was originally published in Parable Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

If you’ve started with a free app in the App Store, and then you want to make some part of it paid, or if you’ve started with a paid app and want to move it to a subscription option with a free trial, the very important thing is to make right by the users who have already installed your app before.

If you’ve suddenly stopped providing functionality that your users already paid for, or that they were getting before for free, it can badly damage your reputation, not to mention that it’s just a wrong thing to do.

The solution is to check which was the first version of your app that the user installed previously, and thus if they’re “eligible” to some of the perks that you are now trying to put behind a paywall. Perhaps there are other reasons you might want to know the originally installed version of the app too.

There is actually a very straightforward way to get exactly that information, and super reliably, including if the user deleted and reinstalled your app multiple times (you can still know the first version they ever installed).

For that, you just need to take a look at the App Store Receipt that’s included in your app’s bundle. This article by RevenueCat provides a good overview of it if you’re unfamiliar with the concept.

Parsing the App Store Receipt

Getting the useful information out of the NSBundle.appStoreReceiptURL is not easy, as the file itself is a PKCS#7 container.

I won’t go into details about how one would extract the information on their own. It’s not a trivial task (again, the RevenueCat article outlines that). Instead, I’ll direct you to the amazing AppReceiptValidator Swift library by IdeasOnCanvas.

After you add the library to your project with SwiftPM, this is the only thing you’ll need to do:

import AppReceiptValidator

func getOriginalBuildNumber() -> String? {
    let receiptValidator = AppReceiptValidator()
    let appStoreReceipt = try? receiptValidator.parseReceipt(origin: .installedInMainBundle)
    return appStoreReceipt?.originalAppVersion
}

But, if we’re getting the originalAppVersion from the receipt, why did I call the function getOriginalBuildNumber ?

That’s because, according to Apple’s documentation:

Original Application Version
This corresponds to the value of CFBundleVersion (in iOS) or CFBundleShortVersionString (in macOS) in the Info.plist file when the purchase was originally made.

And CFBundleVersion is what you would see as a “build number” in Xcode as opposed to “marketing version”. So, if you’re making an iOS app, “original app version” will actually be “original build number”.

So, there are two important things to note about this:

1. Remember that this number is the build number, not the marketing version
2. If you’re using Xcode’s “Manage Version and Build Number” feature, you should know that the build number will get reset with each new version (so if you go from let’s say version 1.0 with build number 5 to version 1.1, next build will have build number 1). Because of this, “original build number” actually becomes absolutely useless.

In that case, you have two options.

First, you can stop using the “Manage Version and Build Number” feature, and make sure that your build numbers are not getting reset to zero with each new version. Build numbers should be unique and only go in ascending order. Otherwise, you cannot use App Store Receipt to figure out when the user first installed your app.

If you cannot achieve that, you’ll have to use original_purchase_date, which you can only get by making a HTTP request with the App Store Receipt to Apple’s verifyReceipt endpoint. However, as that endpoint is now deprecated, perhaps using consecutive build numbers is the only way forward.

Sadly, using receipt_creation_date from the local App Store Receipt is not a solution either, as that date is reset when the app is deleted and reinstalled.

Comparing build numbers

So, the getOriginalBuildNumber() function will return a build number.

Keep in mind that for TestFlight builds, the returned value will always be nil, and for Debug builds — it’s either gonna be “1.0” or also nil (I’ve seen both).

Now, comparing any kind of version strings (including build numbers) is easy:

func isBuildNumber(_ lhs: String, earlierThanBuildNumber rhs: String) -> Bool {
    rhs.compare(lhs, options: .numeric) == .orderedDescending
}

let newPricingBuildNumber = "15"
let originalBuildNumber = getOriginalBuildNumber()

if let originalBuildNumber, isBuildNumber(originalBuildNumber, earlierThanBuildNumber: newPricingBuildNumber) {
    // user installed the app before build number 15
} else {
    // user installed the app after build number 15
}

Thanks for reading! If you want to support me, please check out my apps: “Ask Yourself Everyday”, “Time and Again” & “Learn Numbers: Foreign Languages”. For business inquiries, please reach out to me at oleg@dreyman.dev. Thanks for reading!

🇺🇦 Donate to Ukraine here

TL;DR? Explaining how to create a system for intuitive Swift Timers with automatic memory management. Minimal gist here, fully featured Swift package here, or read the article for details

This article is not an explainer on Timer API. If you need a deep dive on Foundation.Timer in Swift, I recommend The ultimate guide to Timer by Paul Hudson

Swift’s Timer (ex-NSTimer) is a very powerful API, but can be quite unintuitive to use. My main issues with it are:

1. Vagueness about memory management: there are many ways to create and manage Timer instances, and all of them have different rules about when and how they are deallocated. Developers must always stay vigilant, as this complexity can lead to memory leaks and other bugs.
2. API complexity: after figuring out memory management, you are still presented with many options to get right: use Timer.init or Timer.scheduledTimer? Which RunLoop to use? What on earth are run loop modes? Developers often need to go searching for documentation instead of relying on the API intuitively. For the vast majority of use cases, this is simply unnecessary.

Solution: “Timers“ class

The initial idea is to create a Timers class that will hold references to timers and invalidate them (thus deallocating) once this object itself is deallocated. Here’s the core structure of it:

public final class Timers {
    
    private var timers: [Foundation.Timer] = []
    
    public init() { }
    
    public func clear() {
        for timer in timers {
            timer.invalidate()
        }
        timers = []
    }
    
    deinit {
        clear()
    }

    // to be continued...
}

Hopefully, the idea is clear. Whoever “owns” the Timers instance (for example, a view controller) controls when the timers are stopped and deallocated. No need to manually juggle timer instances: when the owner gets deallocated, Timers gets deallocated, which invalidates and deallocates all the timers. In the end, the usage will look like this:

final class ExampleViewController: UIViewController {
    
    // will invalidate & deallocate all the timers
    // when ExampleViewController deallocates
    let timers = Timers()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        timers.addTimer(/*...*/) // we'll get into specifics next
    }
}

Adding helper Timer functions

Our goal is to create an easy-to-use, intuitive API for Timers while also giving our API users full power of Foundation’s Timer. So first we’ll create one “core” addTimer function that will enable us to make memory-safe timers easily, and then we can add convenience functions that are more than enough for common use cases.

The “core” function looks like this:

 extension Timers {
    public func addTimerManually(
        runLoop: RunLoop = .main,
        runLoopMode: RunLoop.Mode = .common,
        timer: Foundation.Timer
    ) {
        runLoop.add(timer, forMode: runLoopMode)
        timers.append(timer)
    }
}

Users can still use custom run loop and run loop modes for those more sophisticated scenarios, but this function provides reasonable default values (RunLoop.main and RunLoop.Mode.common) for standard use cases.

This already gives us the benefit of simplified automatic memory management, since the timer added this way will get automatically invalidated and deallocated when the Timers instance gets deallocated.

And now it’s time to introduce out first helper function, which goes one step further:

extension Timers {
    public func addRepeating<TargetType: AnyObject>(
        timeInterval: TimeInterval,
        tolerance: TimeInterval = 0,
        withTarget target: TargetType,
        _ handler: @escaping (TargetType, Timer) -> Void
    ) {
        let newTimer = Timer(timeInterval: timeInterval, repeats: true) { [weak target] timer in
            if let target {
                handler(target, timer)
            }
        }
        newTimer.tolerance = tolerance
        self.addTimerManually(timer: newTimer)
    }
}

We’re using TargetType pattern here to avoid relying on our users typing [weak self] every time to avoid retain cycles. Instead, we are the one who are writing [weak target]. This might look strange to you, but it’s actually a pattern that is used by Apple itself. You can read more about the core idea of this pattern in my article No more [weak self], or the weird new future of delegation.

As such, creating a repeating timer now becomes easy and safe:

final class ExampleViewController: UIViewController {
    
    let timers = Timers()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        timers.addRepeating(timeInterval: 1, withTarget: self) { (self, timer) in
            self.reloadData()
        }
    }

    // ...
}

Adding more helper functions

From here, the Timers class is infinitely extendable.

First, we can write a version of addRepeating where you can simply use (self) instead of (self, timer):

extension Timers {
    public func addRepeating<TargetType: AnyObject>(
        timeInterval: TimeInterval,
        tolerance: TimeInterval = 0,
        withTarget target: TargetType,
        handler: @escaping (TargetType) -> Void
    ) {
        self.addRepeating(
            timeInterval: timeInterval,
            tolerance: tolerance,
            withTarget: target,
            handler: { target, _ in handler(target) }
        )
    }
}

final class ExampleViewController: UIViewController {
    
    let timers = Timers()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        timers.addRepeating(timeInterval: 1, withTarget: self) { (self) in
            self.reloadData()
        }
    }

    // ...
}

This is optional but nice to have, as usually we don’t need direct access to Timer instances in the block.

Then, we can write additional helpers to support other use cases, for example, this one that fires at a specific time and then repeats with a set interval:

extension Timers {
    public func addRepeating<TargetType: AnyObject>(
        initiallyFireAt fireAt: Date,
        thenRepeatWithInterval timeInterval: TimeInterval,
        tolerance: TimeInterval = 0,
        withTarget target: TargetType,
        handler: @escaping (TargetType, Timer) -> Void
    ) {
        let newTimer = Timer(
            fire: fireAt,
            interval: timeInterval,
            repeats: true,
            block: { [weak target] timer in
                if let target {
                    handler(target, timer)
                }
            }
        )
        newTimer.tolerance = tolerance
        self.addTimerManually(timer: newTimer)
    }
}

// usage:
timers.addRepeating(
    initiallyFireAt: .now.addingTimeInterval(10),
    thenRepeatWithInterval: 5,
    withTarget: self
) { (self, timer) in
    self.reloadData()
}

Or a timer that fires once:

extension Timers {
    public func fireAt<TargetType: AnyObject>(
        _ fireAt: Date,
        withTarget target: TargetType,
        handler: @escaping (TargetType) -> Void
    ) {
        let newTimer = Timer(
            fire: fireAt,
            interval: 0,
            repeats: false,
            block: { [weak target] _ in
                if let target {
                    handler(target)
                }
            }
        )
        addTimerManually(timer: newTimer)
    }
}

// usage:
timers.fireAt(date, withTarget: self) { (self) in
    self.reloadData()
}

It’s straightforward to add your own helper functions to suit your specific needs — even the more complex ones — without sacrificing simplicity and memory-leak safety. Feel free to do so

Final code

For easy copy-pasting, here’s our final Timers class with one helper function:

public final class Timers {
    
    private var timers: [Foundation.Timer] = []
    
    public init() { }
    
    public func clear() {
        for timer in timers {
            timer.invalidate()
        }
        timers = []
    }
    
    deinit {
        clear()
    }

    public func addTimerManually(
        runLoop: RunLoop = .main,
        runLoopMode: RunLoop.Mode = .common,
        timer: Timer
    ) {
        runLoop.add(timer, forMode: runLoopMode)
        timers.append(timer)
    }

    public func addRepeating<TargetType: AnyObject>(
        timeInterval: TimeInterval,
        tolerance: TimeInterval = 0,
        withTarget target: TargetType,
        handler: @escaping (TargetType, Timer) -> Void
    ) {
        let newTimer = Timer(timeInterval: timeInterval, repeats: true) { [weak target] timer in
            if let target {
                handler(target, timer)
            }
        }
        newTimer.tolerance = tolerance
        addTimerManually(timer: newTimer)
    }
}

An extended version is also available as a Swift package:

GitHub - dreymonde/Timers: ⏲️ Intuitive Swift timers with automatic memory management

It has more helper functions and an additional generic function to reduce code repetition and help you write your own helpers more easily.

Hopefully, this proves helpful. In my personal experience, I have found it much more enjoyable to use the Timers class instead of creating NSTimers directly. It also helps knowing my code is much safer as a result.

Thanks for reading the post! Don’t hesitate to ask or suggest anything in the “responses” section below. You can also contact me on Twitter or find me on GitHub. If you’ve written an article — or stumbled upon one — exploring a similar topic, be sure to post a link to it in the responses, and I’ll include it below.

Hi! If you want to support me, please check out my apps: “Ask Yourself Everyday” and “Time and Again”. For business inquiries, please reach out to me at oleg@dreyman.dev. Thanks for reading!

🇺🇦 Donate to Ukraine here

Theoretically, building a URLRequest in Swift is easy:

let googleURL = URL(string: "https://google.com")!
var urlRequest = URLRequest(url: googleURL)
urlRequest.httpMethod = "POST"

But at some point, when your requests are complex enough, it starts to get frustrating.

First of all, there will be a lot of repetition — setting all the correct headers (but only in correct places), handling the encoding of the content (if necessary) and so on.

Secondly, there is also an issue that’s incredibly easy for developers to mess up: a URL query.

Most developers just try to work with the query directly, but percent encoding separate query items can be a tricky thing. Foundation has a built-in mechanism for it — URLComponents with its queryItems property, but it can feel like a hassle to dance around with URLComponents instances.

Instead, it would’ve been nice if we could operate with a query in a similar way we operate with, say, HTTP headers.

So in this article we will build a reusable, flexible URL request builder system that will help you out tremendously once you have complex enough requests.

Step 1: Separating the path from the base

Once you start building your networking layer, you’ll quickly notice that you need a system that allows you to use any base URL (for example, representing different servers based on dev environment), not just the one that’s “hardcoded” into the URL.

So we’ll start our system by working on a “path” level, like this:

struct RequestBuilder {
    var urlComponents: URLComponents
    
    private init(urlComponents: URLComponents) {
        self.urlComponents = urlComponents
    }
    
    init(path: String) {
        var components = URLComponents()
        components.path = path
        self.init(urlComponents: components)
    }
}

And then one can build a full URLRequest like this:

extension RequestBuilder {
    func makeRequest(baseURL: URL) -> URLRequest? {
        guard let finalURL = urlComponents.url(relativeTo: baseURL) else {
            return nil
        }
        return URLRequest(url: finalURL)
    }
}

//

let request = RequestBuilder(endpoint: "users/get")
    .makeRequest(baseURL: apiBaseURL)

relativeTo: is a rather unknown feature of Foundation’s URL ecosystem, but one that works here really well.

CAUTION: if you get weird errors, make sure that your base URL does not have a “/” at the end, and that your path does not contain “/” at the start.

Step 2: Adding support for query items

Let’s continue by introducing a simple operator “template” for our new features:

extension RequestBuilder {
    func modifyURLComponents(_ modifyURLComponents: @escaping (inout URLComponents) -> Void) -> RequestBuilder {
        var copy = self
        modifyURLComponents(&copy.urlComponents)
        return copy
    }
}

This function will modify the stored URLComponents and will return a new instance.

With this template ready, building the query items support is trivial:

extension RequestBuilder {
    func queryItems(_ queryItems: [URLQueryItem]) -> RequestBuilder {
        modifyURLComponents { urlComponents in
            var items = urlComponents.queryItems ?? []
            items.append(contentsOf: queryItems)
            urlComponents.queryItems = items
        }
    }
}

From a usage perspective, this will work similarly to how you operate on SwiftUI views or Combine pipelines. And the final use of the whole thing so far is clear:

let request = RequestBuilder(path: "users/search")
    .queryItems([
        URLQueryItem(name: "city", value: "San Francisco")
    ])
    .makeRequest(baseURL: apiBaseURL)

// https://example.com/users/search?city=San%20Francisco

URLQueryItem API provided by Foundation will perform all the necessary percent encoding for us, so there’s no need for us to worry about that at all.

Now we can even add some sugar to make working with the query even nicer:

extension RequestBuilder {
    func queryItems(_ queryItems: [(name: String, value: String)]) -> RequestBuilder {
        self.queryItems(queryItems.map { .init(name: $0.name, value: $0.value) })
    }

    func queryItem(name: String, value: String) -> RequestBuilder {
        queryItems([(name: name, value: value)])
    }
}

let request = RequestBuilder(path: "users/search")
    .queryItem(name: "city", value: "San Francisco")
    .queryItem(name: "maxResults", value: 100.description)
    .makeRequest(baseURL: apiBaseURL)

// https://example.com/users/search?city=San%20Francisco&maxResults=100

Step 3: Modifying the URL request

Well, so far our system works with creating the URL we need, including the query. But what about all the HTTP request stuff?

Well, the main challenge is that URLRequest and URLComponents both contain a representation of a URL. If we have both the urlRequest and urlComponents in our RequestBuilder, they could end up having “conflicting views” on what the correct URL is.

Since our RequestBuilder operates on a path level, urlComponents should be the main “source of truth” regarding all things URL. But the issue is — we can’t create a URLRequest without a URL. So instead, let’s not store the URLRequest instance itself, but instead store instructions on how we’ll need to modify the request after it’s set up with the correct URL.

It might sound a bit confusing, but the concept is actually quite simple:

struct RequestBuilder {
    var buildURLRequest: (inout URLRequest) -> Void
    var urlComponents: URLComponents

    private init(urlComponents: URLComponents) {
        self.urlComponents = urlComponents
        self.buildURLRequest = { _ in }
    }

    init(path: String) {
        var components = URLComponents()
        components.path = path
        self.init(urlComponents: components)
    }

    func makeRequest(baseURL: URL) -> URLRequest? {
        let finalURL = urlComponents.url(relativeTo: baseURL) ?? baseURL

        var urlRequest = URLRequest(url: finalURL)
        buildURLRequest(&urlRequest)

        return urlRequest
    }
}

And the “template” operator is implemented like this:

extension RequestBuilder {
    func modifyURLRequest(_ modifyURLRequest: @escaping (inout URLRequest) -> Void) -> RequestBuilder {
        var copy = self
        let existing = buildURLRequest
        copy.buildURLRequest = { request in
            existing(&request)
            modifyURLRequest(&request)
        }
        return copy
    }
}

//

let request = RequestBuilder(path: "users/submit")
    .modifyURLRequest({ request in
        request.httpMethod = "POST"
    })
    .makeRequest(baseURL: apiBaseURL)

So far, we already have a system that:

• Separates the path from the base URL
• Allows working on a URLComponents level, which gives easy control of the query
• Allows us to modify the URLRequest instance

Step 4: Creating operators for URL request

Now we can add an infinite number of useful operators that modify our URLRequest instance.

For example, HTTP method:

extension RequestBuilder {
    enum HTTPRequestMethod: String {
        case get = "GET"
        case post = "POST"
        case put = "PUT"
        case head = "HEAD"
        case delete = "DELETE"
        case patch = "PATCH"
        case options = "OPTIONS"
        case connect = "CONNECT"
        case trace = "TRACE"
    }

    func httpMethod(_ method: HTTPRequestMethod) -> RequestBuilder {
        modifyURLRequest { $0.httpMethod = method.rawValue }
    }
}

//

let request = RequestBuilder(path: "users/submit")
    .httpMethod(.post)
    .makeRequest(baseURL: apiBaseURL)

Or HTTP headers:

extension RequestBuilder {
    func httpHeader(name: String, value: String) -> RequestBuilder {
        modifyURLRequest { $0.addValue(value, forHTTPHeaderField: name) }
    }
}

//

let request = RequestBuilder(path: "users/submit")
    .httpMethod(.post)
    .httpHeader(name: "Content-Type", value: "application/json")
    .makeRequest(baseURL: apiBaseURL)

HTTP body:

extension RequestBuilder {
    func httpBody(_ body: Data) -> RequestBuilder {
        modifyURLRequest { $0.httpBody = body }
    }

    static let jsonEncoder = JSONEncoder()

    func httpJSONBody<Content: Encodable>(_ body: Content, encoder: JSONEncoder = RequestBuilder.jsonEncoder) throws -> RequestBuilder {
        let body = try encoder.encode(body)
        return httpBody(body)
    }
}

//

let request = RequestBuilder(path: "users/submit")
    .httpMethod(.post)
    .httpHeader(name: "Content-Type", value: "application/json")
    .httpJSONBody(userForm)
    .makeRequest(baseURL: apiBaseURL)

Timeout:

extension RequestBuilder {
    func timeout(seconds timeout: TimeInterval) -> RequestBuilder {
        modifyURLRequest { $0.timeoutInterval = timeout }
    }
}

let request = RequestBuilder(path: "users/submit")
    .httpMethod(.post)
    .httpHeader(name: "Content-Type", value: "application/json")
    .timeout(seconds: 10)
    .makeRequest(baseURL: apiBaseURL)

As you can see, we can have as many of these operators as we want. The system is really flexible, and you can always create operators that are specific to your own app.

What we also found helpful is the concept of “factories” — easy “starting points” for your requests. For example, these are the one we use often:

extension RequestBuilder {
    // MARK: - Factories

    static func get(path: String) -> RequestBuilder {
        RequestBuilder(path: path)
            .httpMethod(.get)
    }

    static func post(path: String) -> RequestBuilder {
        RequestBuilder(path: path)
            .httpMethod(.post)
    }

    // MARK: - JSON Factories

    static func jsonGet(path: String) -> RequestBuilder {
        .get(path: path)
            .httpHeader(name: "Accept", value: "application/json")
    }

    static func jsonPost(path: String, jsonData: Data) -> RequestBuilder {
        .post(path: path)
            .httpHeader(name: "Content-Type", value: "application/json")
            .httpBody(jsonData)
    }

    static func jsonPost<Content: Encodable>(
        path: String,
        jsonObject: Content,
        encoder: JSONEncoder = RequestBuilder.jsonEncoder
    ) throws -> EndpointRequest {
        try .post(path: path)
            .httpHeader(name: "Content-Type", value: "application/json")
            .httpJSONBody(jsonObject, encoder: encoder)
    }
}

//

let request = RequestBuilder.jsonPost(path: "users/submit", jsonObject: userForm)
    .timeout(seconds: 10)
    .makeRequest(baseURL: apiBaseURL)

The system can really be extended and adapted to your every need.

Conclusion

Hopefully, you find this guide useful. For us, the biggest benefit of this approach is that we can operate on query items and HTTP stuff in the same centralised space, without messing with URLComponents directly. It simplified a lot of the code we had — code was not only bulky and sometimes hard to grasp, but also very repetitive and error-prone.

Of course, there are still many improvements that can be made here. Let us know in the comments if there’s anything you’d want to add to this system!

We also published an improved version of this system to our GitHub account, feel free to check it out here:

GitHub - ParableHealth/URLRequestBuilder: Reusable system for complex URL requests with Swift. Deal with query items, HTTP headers, request body and more in an easy, declarative way

Building a reusable system for complex URL requests with Swift was originally published in Parable Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

The Problem

Let’s say after years of experimentation, you finally came up with an absolutely perfectly tweaked spring animation for your app using nothing but default UIView.animate parameters. Let’s say, hypothetically, that the code is something like this:

UIView.animate(
    withDuration: 0.4,
    delay: 0,
    usingSpringWithDamping: 0.8,
    initialSpringVelocity: 1.75,
    options: [.curveEaseInOut, .beginFromCurrentState, .allowUserInteraction]
) {
    self.view.center.y += 50
} completion: { (isCompleted) in
    // completion code
}

Well, if you absolutely nail it and you want to start using this animation everywhere in your app, you suddenly start seeing yourself copying and pasting this snippet everywhere. And we both know that copy-pasted code is no good.

Many people try to solve this by creating a centralized “constants” type, where one can store their perfectly-tuned parameters and quickly grab them when needed. Something like this:

UIView.animate(
    withDuration: AnimationDefaults.defaultDuration,
    delay: 0,
    usingSpringWithDamping: AnimationDefaults.defaultSpringDamping,
    initialSpringVelocity: AnimationDefaults.defaultSpringVelocity,
    options: AnimationDefaults.defaultOptions
) {
    self.view.center.y += 50
} completion: { (isCompleted) in
    // completion code
}

But while this is better than copy-pasted code, it’s still somewhat the same. Cause if one day you’ll want to migrate your animations to UIViewPropertyAnimator, well… you’ll have yourself a problem.

The Solution: “Animator” struct

Instead, here’s what we can come up with. First, let’s create a new type called Animator:

struct Animator {
    typealias Animations = () -> ()
    typealias Completion = (Bool) -> ()
    
    let perform: (@escaping Animations, Completion?) -> ()
}

And with that, a simple extension on a UIView to mirror the usual UIView.animate as closely as possible:

extension UIView {
    static func animate(with animator: Animator, animations: @escaping () -> (), completion: ((Bool) -> ())? = nil) {
        animator.perform(animations, completion)
    }
}

I hope by now you understand where we’re going with this. Now adding a reusable, perfectly tuned spring animation is simple:

extension Animator {
    static let defaultSpring = Animator { (animations, completion) in
        UIView.animate(
            withDuration: 0.4,
            delay: 0,
            usingSpringWithDamping: 0.8,
            initialSpringVelocity: 1.75,
            options: [.curveEaseInOut, .beginFromCurrentState, .allowUserInteraction],
            animations: animations,
            completion: completion
        )
    }
}

So as you see, we’re simply wrapping our spring animation in a reusable block of code. The usage?

UIView.animate(with: .defaultSpring) {
    self.view.center.y += 50
} completion: { (isCompleted) in
    // completion code
}

Now it’s not just reusable, but also incredibly clean and easy to read.

With this technique, you can create as many reusable animations as you want.

One More Thing

Often, you want your methods that perform animations to have an animated: Bool parameter. Well, you probably remember how much of a pain that is with custom animations, right? Fret no more, here’s a neat little trick using the Animator:

extension Animator {
    static let noAnimation = Animator { (animations, completion) in
        animations()
        completion?(true)
    }
}

And the usage:

func moveView(animated: Bool) {
    UIView.animate(with: animated ? .defaultSpring : .noAnimation) {
        self.view.center.y += 50
    } completion: { (isCompleted) in
        // completion code
    }
}

Hopefully, you find this as cool as I do.

It’s a well-known fact that app development (like any job) has its fair share of mundane tasks. Tasks like creating Legal pages, support screens, and settings screens, to name a few.

Let’s talk about adding a Privacy Policy. Maybe you already have written it (great work!), now how are you going to display it?

Should you just use a giant UITextView? What if the privacy policy changes? You always need to have your Privacy Policy up to date. It needs to be backend-editable.

Oh no, now what: buying a domain? Hosting a website? Choosing a CMS? For many apps, this is overkill.

I usually try to make these processes as simple and as streamlined as possible. So we usually host our Privacy Policies on Telegra.ph.

Telegraph is an anonymous publishing tool that lets you create richly formatted posts with photos and all sorts of embedded stuff. To create something on Telegraph, it literally takes ten seconds:

No account required. Zero configuration. Open the page, type, press Publish and copy the link. That’s it. (You can edit these pages in the same browser you’ve created them. To make it more robust, you can also link them to your Telegram account).

Introducing TelegraphKit

You could put this in a WKWebView as-is and call it a day, and it would still be a good experience (Telegra.ph pages load incredibly fast). But I went a little bit further.

The goal was for the end result to be simple and convenient for the developers, and delightful for the users. It felt important to present these pages in a way that looked and felt native.

Here’s what I was able to achieve (default Telegra.ph appearance vs. TelegraphKit):

Before I go into any details, let me first note that I’ve published this code as a Swift package, and it’s available on GitHub now:

GitHub - dreymonde/TelegraphKit: The ultimate solution for showing ad hoc, server-editable web content (FAQs, Tutorials, Privacy Policy, etc.) in your iOS apps

Now, what exactly is it?

Some dark WKWebView magic

Quite a few improvements were made, but these two are the most obvious:

• Dark mode support
• System fonts and styles

It really has a native look & feel, which is lovely. And what’s interesting is that even though it looks native, it’s still just WKWebView under the hood! Just modified extensively to make it look just right.

To achieve that, I used a function called evaluateJavaScript to extend and modify the page’s look using HTML Styles. To support dark mode, the code simply reacts to the appearance change by turning on and off the corresponding “dark appearance” style. I’ve discovered this technique in this fantastic article by Daniel Jalkut, and it lies in the core of TelegraphKit.

To be fully satisfied with the look, hours were spent digging through Telegraph’s internal HTML structure with Chrome’s debugger. There was a lot of trial & error in the experiments. In the end, the result was well worth it.

You can check out the usage docs on the GitHub page, but it essentially boils down to this:

import TelegraphKit

let url = URL(string: "<your-telegraph-url>")!
let telegraphVC = TelegraphViewController(url: url)
let nvc = UINavigationController(rootViewController: telegraphVC)
self.present(nvc, animated: true)

TelegraphKit is now my go-to solution to show any informational content I need to create quickly and edit remotely. Beyond using it to display a Privacy Policy, I also use it to display Support pages, Guides, “What’s New” notes, and much more. It’s a highly valuable tool in my toolset that saves me tons of time. Hopefully it will be helpful for you as well!

GitHub - dreymonde/TelegraphKit: The ultimate solution for showing ad hoc, server-editable web content (FAQs, Tutorials, Privacy Policy, etc.) in your iOS apps

I’m very excited about launching TelegraphKit, and excited to hear your thoughts and opinions on it!

Please try it out and let me know how it goes! Do you find it useful? Is there anything that you’re missing? Do you want it to have any other features, or to have even more flexibility and customization? Use the comments section below, open a GitHub issue or drop me a line at oleg@dreyman.dev, I’ll be happy to help!

TL;DR? I’ve open sourced DateBuilder, a powerful date calculation library. Check out the README to see all the incredible stuff it can do.

Apple’s Calendar API is amazing, it is. It’s quite obscure in some parts, true, and it requires quite a little bit of learning and adjusting, but it’s very effective, very expansive, and, most of all, very correct. If you do everything right, it works great and it handles all the weird edge cases for you.

But still, when you need to create very specific dates it can get a little tricky. Expressing even something as simple as “tomorrow at 8pm” requires you to know exactly what you’re doing, and calculating something like “first day of next week” will send you down a 30-minute Google road exploring billions of different solutions, most of which are wrong (because yes, believe it or not, there are places in the world where the week doesn’t start on Sunday).

Introducing DateBuilder

To make the power of Calendar and date calculations available to everyone, I’ve now open sourced DateBuilder. It’s a powerful date creation engine that lets you create Date and DateComponents objects with incredible ease using a very visual, declarative syntax.

nicephoton/DateBuilder

I built this while working on my upcoming local notification library. For the scheduling component I wanted something very expressive, very concise and easy-to-understand.

For example, at one point I needed to schedule a notification for every first day of the week, with a sort of “weekly review”. With DateBuilder, it’s incredibly easy:

EveryWeek(forWeeks: 50, starting: .thisWeek)
    .firstDay
    .at(hour: 10, minute: 00)
    .dateComponents() // [DateComponents]

One can then use this array of DateComponents to schedule a bunch of notifications, easy as that.

I won’t go into much detail about the API in this post, because there’s a whole README on GitHub! Just take a brief look to see all the stuff DateBuilder can do.

I’m very excited about launching this new open source package, and excited to hear your thoughts and opinions on it! I’m sure it’ll be quite useful for many many apps out there.

Please try it out and let me know how it goes! Do you find it useful? Is there anything that you’re missing? Do you want it to have any other features, or to have even more flexibility? Use the comments section below, open a GitHub issue or drop me a line at oleg@dreyman.dev, I’ll be happy to help!

TL;DR? Check out our new Swift package, it helps you debug local notifications with ease and elegance.

At my company we’ve had a few projects recently where we had to implement a sophisticated and sometimes quite complex local notifications system. It’s always tricky to get right, because there are always tons and tons of moving parts. It’s very nuanced, as one would expect.

Making sure that your code works as expected is not always easy. Say you’ve scheduled notifications for the next 40 days — now what? Should you wait 40 days to make sure that they get delivered as intended? I didn't think so.

That’s why recently I’ve created a simple debug screen that lets you see all of the pending local notifications in one place. All the data you could possibly need is there: next trigger date, identifiers, categories, and so on.

It proved extremely useful to be able to check if your notifications are scheduled properly right on your device or the simulator, without having to juggle breakpoints or searching the logs. It definitely helped to discover at least a few bugs that otherwise would’ve been extremely easy to miss.

The coolest feature I’ve added was simulating the notification delivery. So when we tap on any scheduled notification, its exact copy will be delivered immediately! It feels like magic:

This helps to see exactly how our notification will look once it’s delivered. And it doesn’t “replace” the scheduled notification too — the “real” one will still be delivered as planned!

This thing was so cool, that I ultimately decided to open source it

I quickly realized just how useful this screen was, and how many hours of development and debugging time it saved me. It is fairly self-contained and app-agnostic, so I knew I had to open source it and share it with all of you! I’m absolutely sure you’ll love this.

So, ScheduledNotificationsViewController is now available as a SwiftPM package on GitHub! Get it here:

GitHub - dreymonde/ScheduledNotificationsViewController: See all your scheduled local notifications in one place

It has no dependencies and a minimal API. It’s as “plug and play” as it gets. No configuration, no setup: just create a ScheduledNotificationsViewController() instance and you’re good to go.

Please try it out and let me know how it goes! Do you find it useful? Is there anything that you’re missing? Do you want it to have any other features, or to show more data? Use the comments section below, open a GitHub issue or drop me a line at oleg@dreyman.dev, I’ll be happy to help!