Neat. Show me.

Ok. Here’s an example:

{"body":{"key1":[1,2,3],"key2":{"key3":3,"key5":"string"},"key4":"value","key5":[]}}

Given the above file, example.json, we can run this simple command:

cat example.json | jt '{body{key1,key2{key3},key4}}'

This will produce the following trimmed output:

{"body":{"key1":[1,2,3],"key2":{"key3":3},"key4":"value"}}

As mentioned above, jt will take the JSON input and transform it based on the schema provided, outputting only the selected keys and values.

Ok… But why jt?

JSON responses from REST endpoints often become bloated over time, and in many cases, mobile clients only need a small portion of the response — a response which may have been originally intended for a desktop interface. jt was created to address this issue by allowing clients to select only the portion of a network response that they need. This has the benefit of reducing the amount of data sent over the wire.

While GraphQL is a powerful tool that can also accomplish this, this is not its end goal in and of itself, and choosing GraphQL comes with its own costs and tradeoffs. It requires a significant investment of time and resources to convert a project or company’s backend and clients to GraphQL, it has a steep learning curve, and queries from the client can quickly become difficult to optimize when numerous endpoints are stitched together (sometimes creating N+1 query issues that need to be addressed.)

jt is designed to be a simpler, targeted tool for trimming JSON responses. The client can send a schema for a given request as a custom header, or this data can be persisted server-side and versioned alongside client updates. While similar json manipulation tools, such as jq, exist, jt is specifically designed for deep, nested filtering.

Please note that jt is a new tool and may overlook many complexities, corner cases, and perhaps even support of the full JSON spec. That said, I’d love for you to try jt and share your thoughts and suggestions for improvements. You can check it out at https://github.com/namolnad/jt. Feel free to share feedback with me using any of the methods shown at the bottom of this page — looking forward to hearing from you!

class MyViewController: UIViewController {
    private var isLoading: Bool = false

    func load() {
        guard !isLoading else { return }

        isLoading = true

        model
            .fetch()
            .handleEvents(receiveCompletion: { [weak self] _ in
                self?.isLoading = false
            }
        ...
    }
}

This methodology—one I’ve used many times—is plenty effective, but has always felt slightly cumbersome and potentially error prone as there are several areas where you need to toggle the isLoading boolean and—as such—there are several opportunities to forget to do so. I’ve long been considering a propertyWrapper to encapsulate and streamline this logic, but I struggled to come up with naming and ergonomics which felt like an improvement over the existing solution.

After a bit of brainstorming, I initially wanted to relate this concept to a mutex. However with the help of a colleague, I decided that overloading the mutex name wasn’t the right decision. Following some further ideation, I came upon the Gatekeeper concept. Essentially, we can imagine there is a human gatekeeper who only allows passage if you haven’t already entered, and with whom we must check if we are able to “pass”. After toying around with this a bit, I decided there wasn’t a need for a propertyWrapper and that a simple struct should suffice.

Here is a simple example of such a type in action:

class MyViewController: UIViewController {
    private var loadingGatekeeper = Gatekeeper()

    func load() {
        guard loadingGatekeeper.attemptPassage() else { return }

        model
            .fetch()
            .handleEvents(receiveCompletion: { [weak self] _ in
                self?.loadingGatekeeper.reset()
            })
        ...
    }
}

We’ve now reduced the need for an extra toggling of the isLoading boolean as this has been handled by the Gatekeeper type during the attemptPassage() call. One less chance for errors. 🎉

Of course this is not without its tradeoffs. In this case there may be a slight bit of cognitive overhead understanding the Gatekeeper type as well as the intention behind this particular instance. However, I feel the type is simple enough where a developer should be able to quickly understand it in its entirety—and with proper naming of the gatekeeper property, the purpose of this instance should remain very straightforward.

As we dive into the declaration of the struct behind this, we can see it is incredibly simple, yet extensible enough to allow for managing various portions of “stateful” control flow.

public struct Gatekeeper<Value> {
    private var value: Value
}

extension Gatekeeper where Value == Bool {
    var mayPass: Bool { value }

    init() {
        self.value = true
    }

    @discardableResult
    public mutating func attemptPassage() -> Bool {
        defer { value = false }
        return value
    }

    public mutating func reset() {
        self.value = true
    }
}

The boolean extension above covers the majority of simple cases, however, we can easily add another extension to enable this to work for a much more complex bit of state management.

extension Gatekeeper where Value: SetAlgebra {
    public init() {
        self.value = []
    }

    @discardableResult
    public mutating func attemptPassage(for option: Value.Element) -> Bool {
        defer { value.insert(option) }
        return !value.contains(option)
    }

    public func mayPass(for option: Value.Element) -> Bool {
        !value.contains(option)
    }

    public mutating func reset(for option: Value.Element) {
        self.value.remove(option)
    }
}

Putting this to use, if we imagine a State OptionSet we can see where using a Gatekeeper here may really shine:

struct State: OptionSet {
    var rawValue: Int

    static let loading: Self = .init(rawValue: 1 << 0)
    static let loaded: Self = .init(rawValue: 1 << 1)
}

class MyViewController: UIViewController {
    private var stateGatekeeper = Gatekeeper<State>()

    func load() {
        guard stateGatekeeper.attemptPassage(for: .loading), stateGatekeeper.mayPass(for: .loaded) else { return }

        model
            .fetch()
            .handleEvents(receiveCompletion: { [weak self] _ in
                self?.stateGatekeeper.reset(for: .loading)
                self?.stateGatekeeper.attemptPassage(for: .loaded)
            })
        ...
    }
}

This will prevent further loads if the stateGatekeeper indicates that it is either currently loading or has already been loaded. Pretty cool!

As a final example, if you had a requirement to track each time an element was viewed on screen, but you wanted to ensure duplicate views were not recorded, you could use this type to ensure you track each element only a single time.

class MyViewController: UIViewController {
    private var trackingGatekeeper = Gatekeeper<Set<String>>()

    func didView(elementIds: [String]) {
        for id in elementIds where trackingGatekeeper.attemptPassage(for: id) {
            trackView(for: id)
        }
    }
}

Alright, I’ll wrap it up here and leave it to you to see how else you can leverage this simple Gatekeeper type. If you find this idea useful or have thoughts on improving the approach, please reach out to me on Twitter. I hope that this inspires you to clean up your codebase just a little bit.

Happy coding!

Today I’d like to introduce Ahoy iOS. It’s a lightweight library for Apple platforms which enables you to quickly and easily set up first-party analytics on your client for sending to your Rails backend. At its core, Ahoy iOS is really just a simple wrapper around the Ahoy API, though it also provides a number of powerful built-in features.

The backend framework this library was built around, Ahoy, was written by Andrew Kane and is a fully-featured analytics tool you can quickly plug into your existing Rails application. It is easy to setup, easy to use, and is first party, so all of your (and your users’) data will remain on your servers and under your control.

Installation

Ahoy iOS, despite its name, also supports macOS, tvOS, and watchOS. It’s set up for integration via Swift Package Manager and its inclusion in your project is as simple as adding the following to your Package.swift file (or following Apple’s instructions for Xcode).

let package = Package(
    name: "YourProject",
    … // package definition cont.
    dependencies: [
        .package(url: "https://github.com/namolnad/ahoy-ios.git", from: "0.2.0"),
    … // package definition cont.
)

Usage

Ahoy iOS tracks both visits and events. All events are associated with the current visit, and as such, a visit must first be tracked prior to tracking any subsequent events. To track a visit, create a new Ahoy client (maintain a reference) and use the trackVisit() method.

ahoy.trackVisit()
    .sink(receiveCompletion: { _ in }, receiveOutput: { visit in print(visit) })
    .store(in: &cancellables)

After a visit has successfully been tracked, you are free to track events at will. The simplest method of tracking an event is to use the fire-and-forget track(_:properties:) method.

ahoy.track("Viewed book", properties: ["book_id": 4])

If you’d prefer to minimize the number of calls to your backend, a bulk track(events:) method is also available.

And that’s really all there is to it — easy as 🥧, right?!?

Given the ever-growing concerns over data privacy, there has never been a better time to ensure you’re owning your tracking events end-to-end and not sharing this data with third parties. Ahoy iOS, Ahoy and Ahoy Android are great tools to make this as easy as possible.

Thanks for reading! Feel free to share your feedback with me and/or contribute to help improve Ahoy iOS.

A good changelog can save a lot of potential headaches down the road. Whether it be to report to stakeholders when a change was introduced, to let customers know what new features are coming out, or to aid developers who are tracking down a new bug, it can be invaluable to keep track of when every feature, bug fix, or otherwise substantial change came about.

Unfortunately, developers already have more than enough on their plates - which often leaves changelogs untimely, completely forgotten, or in the best case, difficult to maintain stylistically between various team members. These problems are what inspired the creation of Finch.

Viewing Finch’s raw git log which powers the generated changelog

Through the use of well-formed and intentional Git commit messages, Finch can very easily convert your Git commits into a consistently formatted, and fully automated changelog. The commit messages serve as the underlying data which is then passed through a formatting system according your project’s custom configuration. The only requirement Finch has is the use of some relatively minor commit-message discipline - the simple use of “tag” prefixed commit messages. For example:

git commit -m ‘[feature] Add the bells. And the whistles’

With just that — and according to whatever conventions your team would like to use - Finch can help you automate your internal and external-facing changelogs, providing as much detail or polish as is desired. All you have to do is run finch compare and Finch will take care of the rest.

Using Finch to generate a changelog between two recent versions of Finch. Super meta.

It’s that simple! And the above raw markdown renders beatifully as your formatted changelog:

The Finch changelog as fully rendered markdown - so simple!

Check it out here and let me know what you think!

For the past year and a half or so, we have been actively moving our customer-facing* iOS codebase from Objective-C to Swift and have all been thoroughly enjoying the transition. There are a lot of advantages gained with the move to Swift and the Swift-ier our code gets, the happier you’ll tend to see us (well, except for Min, he’s our Prince of Darkness… 😈😉)

As with anything, there are a couple of quirks to the language and the evolving conventions that come along with it. Swift, more than almost anything else, is focused on safety. In most cases, as a Swift developer, you want to do whatever it takes to avoid a 💥CRASH💥. The guard statement is a great tool for this. If you want to make sure a condition exists prior to executing some code, consider utilizing a guard statement, and you’ll likely be safe to assume things are as you’d expect them to be. Crash successfully avoided. Yay!

Using a guard let even allows you to unwrap Swift’s Optionals and access their unwrapped values below the guard. Awesome. Seriously. We love it.

With guard let, however, you find yourself creating a fair amount of these:

guard let blah = blah else {
    return
}

This else block is a great place to handle the unexpected case, but, when guard is used extensively throughout your app, that’s a lot of special cases when you were probably just assuming that you were unwrapping an Optional that should have some value. It seems likely you don’t expect that else block to run fairly often. So, as is seeming to be the general Swift convention these days, you probably leave it to else { return }, except for a few rare cases.

That. That right there. That’s where we see an issue. Unless you are consistently very good about logging or handling the else block appropriately, you basically have no idea how often it’s failing in the wild. 🙀 Ohhh jeez. No one likes being left in the dark like that.

To handle this situation, and give ourselves a general idea of how to track down where issues may be occurring more often than we’d think, we wrote a lightweight framework which we have called Safeguard.

The meat and potatoes of what Safeguard consists of, is really just a simple extension on Optional with built in logging capabilities that can easily plug into your existing logging system. By implementing the framework’s safeguard() function in mission-critical areas, we are able to pass important information to our logger to help us track down what the issue may be. safeguard() passes the #function where it was called, the #file, the #line and the Type. In addition to these clues, with Safeguard’s extra customLoggingParams, we can pass up relevant session info which may help us reproduce and diagnose the problem later on.

Safeguard also provides us with a customizable callback: nilHandler, which makes it easy to manage custom use cases when an Optional has failed to unwrap. This nilHandler also conveniently passes a Bool flag to indicate whether or not the app is running in DEBUG mode. Agh! So many helpful things!!!

To implement safeguard(), and give ourselves this nice bit of reassurance, we can add all of the above functionality to any Optional simply by adding:

guard let blah = blah.safeguard() else {
    return
}

Pretty easy. One word added. World saved. Woot woot! 🎉

In the spirit of saving the world and sharing all the goodness, we have open-sourced Safeguard, and have made it easy to install through either Carthage or Cocoapods. We’ve also included some basic installation, usage and configuration instructions in the README file. (Of course, if you have any suggestions for improvements or additions, please feel free to add an issue or submit a pull request!)

We hope you enjoy turning all those stupid 🙉 silent failures into 📣 loud failures!

Till next time,

-Dan & the Customer iOS team

If you love Swift and are interested in finding solutions like the above, we
are currently hiring mobile engineers and would love to speak with you.

*Note: Our Shopper App team has been working on the same Obj-C -> Swift
transition, credit where it’s due and all that, but I’m on the
customer-facing team and am the one writing this, sooooo, I’ll be writing
from our perspective 😉