README.md

🆔 Identity

Welcome to Identity, a small library that makes it easy to create type-safe identifiers in Swift. Identifiers are often core to how models and other values are referenced within a code base, 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.

The above Article identifier is now backed by a UUID instead of a String.

Conveniences built-in

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

let user =User(id: "johnsundell", name: "John Sundell")

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

let tag =Tag(id: 7, name: "swift")

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

Type safety

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

articleManager.article(withID: user.id)

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

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

structUser: Identifiable {
let id: Identifier<Article>
}

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

Installation

Since Identity 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 Identity as a dependency in your Package.swift file:

Contributions & support

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

Before you start using Identity 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.

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.