NoRedInk / elm-uuid / Prng.Uuid

This modules provides an opaque type for Uuids, helpers to serialize from and to String and helpers to generate new Uuids using the Random.Pcg.Extended pseudo-random generator library.

Uuids are Universally Unique IDentifiers. They are 128 bit ids that are designed to be extremely unlikely to collide with other Uuids.

This library only supports generating Version 4 Uuid (those generated using random numbers, as opposed to hashing. See Wikipedia on Uuids for more details). Version 4 Uuids are constructed using 122 pseudo random bits.

Disclaimer: If you use this Library to generate Uuids, please make sure to correctly seed your random generator, as shown in the examples. Don't use the current time or something similar to seed the generator. If your generator isn't seeded properly, the chance of a collision between multiple clients is drastically increased!

Uuids can be generated either by parsing them from the canonical string representation (see fromString) or by generating them. If you are unfamiliar with random number generation in pure functional languages, this can be a bit confusing. The gist of it is that:

  1. you need a good random seed and this has to come from outside our wonderfully predictable Elm code (meaning you have to create an incoming port and feed in some initial randomness)

  2. every call to generate will give you a tuple of a Uuid and a new seed. It is very important that whenever you generate a new Uuid you store this seed you get back into your model and use this one for the next Uuid generation. If you reuse a seed, you will create the same Uuid twice!

Have a look at the examples in the package to see how to use it!


type Uuid

Uuid type. Represents a 128 bit Uuid (Version 4)

generator : Random.Pcg.Extended.Generator Uuid

Random.Pcg.Extended generator for Uuids.

To provide enough randomness, you should seed this generator with at least 4 32-bit integers that are aquired from JavaScript via crypto.getRandomValues(...). See the examples on how to do this properly.

fromString : String -> Maybe Uuid

Create a Uuid from a String in the canonical form (e.g. "63B9AAA2-6AAF-473E-B37E-22EB66E66B76"). Note that this module only supports canonical Uuids, Versions 1-5 and will refuse to parse other Uuid variants.

toString : Uuid -> String

Create a string representation from a Uuid in the canonical 8-4-4-4-12 form, i.e. "63B9AAA2-6AAF-473E-B37E-22EB66E66B76"

encode : Uuid -> Json.Encode.Value

Encode Uuid to Json

decoder : Json.Decode.Decoder Uuid

Decoder for getting Uuid out of Json

Barebones

stringGenerator : Random.Pcg.Extended.Generator String

Random.Pcg.Extended generator for Uuid Strings.

isValidUuid : String -> Basics.Bool

Check if the given string is a valid UUID