🏷 Tagging

Welcome to Tagging, a small library that makes it easy to create type-safe tags in Swift. Categorization are often very useful for our models, so leveraging the compiler to ensure that they're used in a correct manner can go a long way to making the model layer of an app or system more robust.

This library is strongly inspired by JohnSundell/🆔entity and mbleigh/acts-as-taggable-on, for theoretical information, check out "Type-safe identifiers in Swift" on Swift by Sundell.

All you have to do to use Tagging is to make a model conform to Taggable, and give it an tags property, like this:

struct Article: Taggable {
    let tags: [Tag<Article>]
    let title: String
}

And just like that, the above Article tags are now type-safe! Thanks to Swift’s type inference capabilities, it’s also possible to implement an Taggable type’s tags simply by using Tags as its type:

struct Article: Taggable {
    let tags: Tags
    let title: String
}

The Tags type alias is automatically added for all Taggable types, which also makes it possible to refer to [Tag<Article>] as Article.Tags.

Tag values are backed by strings by default, but that can easily be customized by giving an Taggable type a RawTag, but must be at least Hashable:

struct Article: Taggable {
    typealias RawTag = UUID

    let tags: Tags
    let title: String
}

The above Article tags are now backed by a UUID instead of a String.

Even though Tagging is focused on type safety, it still offers several conveniences to help reduce verbosity. For example, if a Tag is backed by a raw value type that can be expressed by a String literal, so can the tags:

let article = Article(tags: ["foo", "bar"], title: "Example")

The same is also true for tags that are backend by a raw value type that can be expressed by Int literals:

let article = Article(tags: [7, 9], title: "Example")

Tag also becomes Codable, Hashable and Equatable whenever its raw value type conforms to one of those protocols.

So how exactly does Tagging make tags more type-safe? First, when using Tagging, it no longer becomes possible to accidentally pass a tag for one type to an API that accepts an tag for another type. For example, this code won't compile when using Tagging:

articleManager.articles(withTags: user.tags)

The compiler will give us an error above, since we're trying to pass an [Tag<User>] value to a method that accepts an [Tag<Article>] - giving us much stronger type safety than when using plain values, like String or Int, as tag types.

Tagging also makes it impossible to accidentally declare tags properties of the wrong type. So the following won't compile either:

struct User: Tagging {
    let tags: [Tag<Article>]
}

The reason the above code will fail to compile is because Taggable requires types conforming to it to declare tags that are bound to the same type as the conformer, again providing an extra level of type safety.

You can find the most or least used tags by using:

taggableCollection.mostUsedTags()
taggableCollection.leastUsedTags()

You can also filter the results by passing the method a limit, however the default limit is 20.

taggableCollection.mostUsedTags(10)
taggableCollection.leastUsedTags(10)

Or directly get the raw values.

taggableCollection.mostUsedRawTags()
taggableCollection.leastUsedRawTags()

taggableCollection.tagged(with: "foo")
taggableCollection.tagged(with: ["foo"])
taggableCollection.tagged(with: ["foo", "bar"])
taggableCollection.tagged(with: taggable.tags)

taggableCollection.tagged(with: ["foo", "bar"], match: .all)
taggableCollection.tagged(with: taggable.tags, match: .all)

taggableCollection.tagged(with: ["foo", "bar"], match: .none)
taggableCollection.tagged(with: taggable.tags, match: .none)

Since Tagging is implemented within a single file!, the easiest way to use it is to simply drag and drop it into your Xcode project.

But if you wish to use a dependency manager, you can use the Swift Package Manager by declaring Tagging as a dependency in your Package.swift file:

.package(url: "https://github.com/alexruperez/Tagging", from: "0.1.0")

For more information, see the Swift Package Manager documentation.

Tagging is developed completely in the open, and your contributions are more than welcome.

Before you start using Tagging in any of your projects, it’s highly recommended that you spend a few minutes familiarizing yourself with its documentation and internal implementation (it all fits in a single file!), so that you’ll be ready to tackle any issues or edge cases that you might encounter.

To learn more about the principles used to implement Tagging, check out "Type-safe identifiers in Swift" on Swift by Sundell.

This project does not come with GitHub Issues-based support, and users are instead encouraged to become active participants in its continued development — by fixing any bugs that they encounter, or improving the documentation wherever it’s found to be lacking.

If you wish to make a change, open a Pull Request — even if it just contains a draft of the changes you’re planning, or a test that reproduces an issue — and we can discuss it further from there.

Hope you’ll enjoy using Tagging! 😀