๐ 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.
For more information, check out "Type-safe identifiers in Swift" on Swift by Sundell.
Making types identifiable
All you have to do to use Identity is to make a model conform to Identifiable
, and give it an id
property, like this:
struct User: Identifiable {
let id: Identifier<User>
let name: String
}
And just like that, the above User
identifier is now type-safe! Thanks to Swiftโs type inference capabilities, itโs also possible to implement an Identifiable
typeโs id
simply by using ID
as its type:
struct User: Identifiable {
let id: ID
let name: String
}
The ID
type alias is automatically added for all Identifiable
types, which also makes it possible to refer to Identifier<User>
as User.ID
.
Customizing the raw type
Identifier
values are backed by strings by default, but that can easily be customized by giving an Identifiable
type a RawIdentifier
:
struct Article: Identifiable {
typealias RawIdentifier = UUID
let id: ID
let title: String
}
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:
struct User: 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:
.package(url: "https://github.com/JohnSundell/Identity", from: "0.1.0")
For more information, see the Swift Package Manager documentation.
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.
To learn more about the principles used to implement Identity, 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 Identity! ๐