Need help with swift-gen?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

222 Stars 7 Forks MIT License 19 Commits 1 Opened issues


🎱 Composable, transformable, controllable randomness.

Services available


Need anything else?

Contributors list

🎱 Gen


Composable, transformable, controllable randomness.

Table of Contents


Swift's randomness API is powerful and simple to use. It allows us to create random values from many basic types, such as booleans and numeric types, and it allows us to randomly shuffle arrays and pluck random elements from collections.

However, it does not make it easy for us to extend the randomness API, nor does it provide an API that is composable, which would allow us to create complex types of randomness from simpler pieces.

Gen is a lightweight wrapper over Swift's randomness APIs that makes it easy to build custom generators of any kind of value.


Gen's namesake type,

, is responsible for producing random values. Most often you will reach for one of the static variables inside
to get access to a
// Gen

Rather than immediately producing a random value,

describes a random value that can be produced by calling its
let myGen = Gen.bool
// Gen // true // true // false

Every random function that comes with Swift is also available as a static function on


| Swift's API | Gen's API | | --- | --- | |

Int.random(in: 0...9)
| 0...9)
Double.random(in: 0...9)
Gen.double(in: 0...9)
[1, 2, 3].randomElement()
Gen.element(of: [1, 2, 3])
[1, 2, 3].shuffled()
Gen.shuffle([1, 2, 3])

The reason it is powerful to wrap randomness in the

type is that we can make the
type composable. For example, a generator of integers can be turned into a generator of numeric strings with a simple application of the
let digit = 0...9)           // Gen
let stringDigit = // Gen // "7" // "1" // "3"

Already this is a form of randomness that Swift's API's do not provide out of the box.

Gen provides many operators for generating new types of randomness, such as

, as well as helper functions for generating random arrays, sets, dictionaries, strings, distributions and more! A random password generator, for example, is just a few operators away.
// Take a generator of random letters and numbers.
let password = Gen.letterOrNumber
  // Generate 6-character strings of them.
  .string(of: .always(6))
  // Generate 3 segments of these strings.
  .array(of: .always(3))
  // And join them.
  .map { $0.joined(separator: "-") } // "9BiGYA-fmvsOf-VYDtDv" // "dS2MGr-FQSuC4-ZLEicl" // "YusZGF-HILrCo-rNGfCA"

This kind of composition makes it simple to generate random values of anything.

// Use `zip` to combine generators together and build structures.

let randomPoint = zip(.int(in: -10...10), .int(in: -10...10)) .map(CGPoint.init(x:y:)) // Gen

But composability isn't the only reason the

type shines. By delaying the creation of random values until the
method is invoked, we allow ourselves to control randomness in circumstances where we need determinism, such as tests. The
method has an overload that takes a
value, which is Swift's protocol that powers their randomness API. By default it uses the
, which is a good source of randomness, but we can also provide a seedable "pseudo" random number generator, so that we can get predictable results in tests:
var xoshiro = Xoshiro(seed: 0) 0...9).run(using: &xoshiro) // "1" 0...9).run(using: &xoshiro) // "0" 0...9).run(using: &xoshiro) // "4"

xoshiro = Xoshiro(seed: 0) 0...9).run(using: &xoshiro) // "1" 0...9).run(using: &xoshiro) // "0" 0...9).run(using: &xoshiro) // "4"

This means you don't have to sacrifice testability when leveraging randomness in your application.

For more examples of using Gen to build complex randomness, see our blog post on creating a Zalgo generator and our two-part video series (part 1 and part 2) on creating generative art.


If you want to use Gen in a project that uses SwiftPM, it's as simple as adding a

clause to your
dependencies: [
  .package(url: "", from: "0.3.0")

Xcode Sub-project

Submodule, clone, or download Gen, and drag

into your project.

Interested in learning more?

These concepts (and more) are explored thoroughly in Point-Free, a video series exploring functional programming and Swift hosted by Brandon Williams and Stephen Celis.

The design of this library was explored in the following Point-Free episodes:

video poster image


All modules are released under the MIT license. See LICENSE for details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.