Data.TypeID

An implementation of the TypeID specification: https://github.com/jetpack-io/typeid.

It is a re-export of Data.TypeID.V7.

Data types

type TypeID = TypeID' 'V7

A type alias for the default TypeID implementation with UUIDv7.

data TypeID' (version :: UUIDVersion)

This data type also supports TypeIDs with UUID versions other than v7.

The constructor is not exposed to the public API to prevent generating invalid TypeID's.

Instances

Typeable version => Data (TypeID' version)

Defined in Data.TypeID.Internal

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> TypeID' version -> c (TypeID' version)

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (TypeID' version)

toConstr :: TypeID' version -> Constr

dataTypeOf :: TypeID' version -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (TypeID' version))

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (TypeID' version))

gmapT :: (forall b. Data b => b -> b) -> TypeID' version -> TypeID' version

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> TypeID' version -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> TypeID' version -> r

gmapQ :: (forall d. Data d => d -> u) -> TypeID' version -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> TypeID' version -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> TypeID' version -> m (TypeID' version)

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> TypeID' version -> m (TypeID' version)

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> TypeID' version -> m (TypeID' version)

Storable (TypeID' version)

Similar to the Binary instance, but the UUID is stored in host endian.

Defined in Data.TypeID.Internal

Methods

sizeOf :: TypeID' version -> Int

alignment :: TypeID' version -> Int

peekElemOff :: Ptr (TypeID' version) -> Int -> IO (TypeID' version)

pokeElemOff :: Ptr (TypeID' version) -> Int -> TypeID' version -> IO ()

peekByteOff :: Ptr b -> Int -> IO (TypeID' version)

pokeByteOff :: Ptr b -> Int -> TypeID' version -> IO ()

peek :: Ptr (TypeID' version) -> IO (TypeID' version)

poke :: Ptr (TypeID' version) -> TypeID' version -> IO ()

Read (TypeID' version)

Defined in Data.TypeID.Internal

Methods

readsPrec :: Int -> ReadS (TypeID' version)

readList :: ReadS [TypeID' version]

readPrec :: ReadPrec (TypeID' version)

readListPrec :: ReadPrec [TypeID' version]

Show (TypeID' version)

Defined in Data.TypeID.Internal

Methods

showsPrec :: Int -> TypeID' version -> ShowS

show :: TypeID' version -> String

showList :: [TypeID' version] -> ShowS

Binary (TypeID' version)

Since the specification does not formulate a concrete binary format, this instance is based on the following custom format:

• The first 16 bytes are the suffix UUID encoded in base32.
• The next byte is the length of the prefix encoded in a byte.
• The next bytes are the prefix, each letter taking 5 bits, mapping 'a' to 1 and 'z' to 26. The underscore '_' is mapped to 27.

Note that the prefix and the UUID is swapped compared to the string representation, this is for the convenience of the use case where only the suffix UUID is required. Because of this, the sorting order may be different from the string representation, but they are guaranteed to be the same if the same prefix is used.

Defined in Data.TypeID.Internal

Methods

put :: TypeID' version -> Put

get :: Get (TypeID' version)

putList :: [TypeID' version] -> Put

Eq (TypeID' version)

Defined in Data.TypeID.Internal

Methods

(==) :: TypeID' version -> TypeID' version -> Bool

(/=) :: TypeID' version -> TypeID' version -> Bool

Ord (TypeID' version)

Defined in Data.TypeID.Internal

Methods

compare :: TypeID' version -> TypeID' version -> Ordering

(<) :: TypeID' version -> TypeID' version -> Bool

(<=) :: TypeID' version -> TypeID' version -> Bool

(>) :: TypeID' version -> TypeID' version -> Bool

(>=) :: TypeID' version -> TypeID' version -> Bool

max :: TypeID' version -> TypeID' version -> TypeID' version

min :: TypeID' version -> TypeID' version -> TypeID' version

Hashable (TypeID' version)

Defined in Data.TypeID.Internal

Methods

hashWithSalt :: Int -> TypeID' version -> Int

hash :: TypeID' version -> Int

IDConv (TypeID' version)

Conversion between TypeID' and StringTextByteString.

Defined in Data.TypeID.Internal

Methods

string2ID :: String -> Either TypeIDError (TypeID' version)

text2ID :: Text -> Either TypeIDError (TypeID' version)

byteString2ID :: ByteString -> Either TypeIDError (TypeID' version)

id2String :: TypeID' version -> String

id2Text :: TypeID' version -> Text

id2ByteString :: TypeID' version -> ByteString

string2IDM :: MonadIO m => String -> m (TypeID' version)

text2IDM :: MonadIO m => Text -> m (TypeID' version)

byteString2IDM :: MonadIO m => ByteString -> m (TypeID' version)

unsafeString2ID :: String -> TypeID' version

unsafeText2ID :: Text -> TypeID' version

unsafeByteString2ID :: ByteString -> TypeID' version

IDGen (TypeID' 'V1)

Generate TypeID' 'V1s.

Defined in Data.TypeID.Internal

Associated Types

type IDGenPrefix (TypeID' 'V1) :: Maybe Type

type IDGenReq (TypeID' 'V1) r

Methods

genID_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V1) -> GenFunc (IDGenPrefix (TypeID' 'V1)) (IDGenReq (TypeID' 'V1) (m (TypeID' 'V1)))

genID'_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V1) -> GenFunc (IDGenPrefix (TypeID' 'V1)) (IDGenReq (TypeID' 'V1) (m (TypeID' 'V1)))

genIDs_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V1) -> GenFunc (IDGenPrefix (TypeID' 'V1)) (IDGenReq (TypeID' 'V1) (Word16 -> m [TypeID' 'V1]))

decorate_ :: Proxy (TypeID' 'V1) -> GenFunc (IDGenPrefix (TypeID' 'V1)) (UUID -> ResWithErr (IDGenPrefix (TypeID' 'V1)) (TypeID' 'V1))

checkID_ :: Proxy (TypeID' 'V1) -> TypeID' 'V1 -> Maybe TypeIDError

checkIDWithEnv_ :: MonadIO m => Proxy (TypeID' 'V1) -> TypeID' 'V1 -> m (Maybe TypeIDError)

IDGen (TypeID' 'V4)

Generate TypeID' 'V4s.

Defined in Data.TypeID.Internal

Associated Types

type IDGenPrefix (TypeID' 'V4) :: Maybe Type

type IDGenReq (TypeID' 'V4) r

Methods

genID_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V4) -> GenFunc (IDGenPrefix (TypeID' 'V4)) (IDGenReq (TypeID' 'V4) (m (TypeID' 'V4)))

genID'_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V4) -> GenFunc (IDGenPrefix (TypeID' 'V4)) (IDGenReq (TypeID' 'V4) (m (TypeID' 'V4)))

genIDs_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V4) -> GenFunc (IDGenPrefix (TypeID' 'V4)) (IDGenReq (TypeID' 'V4) (Word16 -> m [TypeID' 'V4]))

decorate_ :: Proxy (TypeID' 'V4) -> GenFunc (IDGenPrefix (TypeID' 'V4)) (UUID -> ResWithErr (IDGenPrefix (TypeID' 'V4)) (TypeID' 'V4))

checkID_ :: Proxy (TypeID' 'V4) -> TypeID' 'V4 -> Maybe TypeIDError

checkIDWithEnv_ :: MonadIO m => Proxy (TypeID' 'V4) -> TypeID' 'V4 -> m (Maybe TypeIDError)

IDGen (TypeID' 'V5)

Generate TypeID' 'V5s.

Defined in Data.TypeID.Internal

Associated Types

type IDGenPrefix (TypeID' 'V5) :: Maybe Type

type IDGenReq (TypeID' 'V5) r

Methods

genID_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V5) -> GenFunc (IDGenPrefix (TypeID' 'V5)) (IDGenReq (TypeID' 'V5) (m (TypeID' 'V5)))

genID'_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V5) -> GenFunc (IDGenPrefix (TypeID' 'V5)) (IDGenReq (TypeID' 'V5) (m (TypeID' 'V5)))

genIDs_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V5) -> GenFunc (IDGenPrefix (TypeID' 'V5)) (IDGenReq (TypeID' 'V5) (Word16 -> m [TypeID' 'V5]))

decorate_ :: Proxy (TypeID' 'V5) -> GenFunc (IDGenPrefix (TypeID' 'V5)) (UUID -> ResWithErr (IDGenPrefix (TypeID' 'V5)) (TypeID' 'V5))

checkID_ :: Proxy (TypeID' 'V5) -> TypeID' 'V5 -> Maybe TypeIDError

checkIDWithEnv_ :: MonadIO m => Proxy (TypeID' 'V5) -> TypeID' 'V5 -> m (Maybe TypeIDError)

IDGen (TypeID' 'V7)

Generate TypeIDs.

Defined in Data.TypeID.Internal

Associated Types

type IDGenPrefix (TypeID' 'V7) :: Maybe Type

type IDGenReq (TypeID' 'V7) r

Methods

genID_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V7) -> GenFunc (IDGenPrefix (TypeID' 'V7)) (IDGenReq (TypeID' 'V7) (m (TypeID' 'V7)))

genID'_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V7) -> GenFunc (IDGenPrefix (TypeID' 'V7)) (IDGenReq (TypeID' 'V7) (m (TypeID' 'V7)))

genIDs_ :: forall (m :: Type -> Type). MonadIO m => Proxy (TypeID' 'V7) -> GenFunc (IDGenPrefix (TypeID' 'V7)) (IDGenReq (TypeID' 'V7) (Word16 -> m [TypeID' 'V7]))

decorate_ :: Proxy (TypeID' 'V7) -> GenFunc (IDGenPrefix (TypeID' 'V7)) (UUID -> ResWithErr (IDGenPrefix (TypeID' 'V7)) (TypeID' 'V7))

checkID_ :: Proxy (TypeID' 'V7) -> TypeID' 'V7 -> Maybe TypeIDError

checkIDWithEnv_ :: MonadIO m => Proxy (TypeID' 'V7) -> TypeID' 'V7 -> m (Maybe TypeIDError)

IDType (TypeID' version)

Get the prefix, UUID, and timestamp of a TypeID'.

Defined in Data.TypeID.Internal

Methods

getPrefix :: TypeID' version -> Text

getUUID :: TypeID' version -> UUID

getTime :: TypeID' version -> Word64

FromJSON (TypeID' version)

Defined in Data.TypeID.Internal

Methods

parseJSON :: Value -> Parser (TypeID' version)

parseJSONList :: Value -> Parser [TypeID' version]

omittedField :: Maybe (TypeID' version)

FromJSONKey (TypeID' version)

Defined in Data.TypeID.Internal

Methods

fromJSONKey :: FromJSONKeyFunction (TypeID' version)

fromJSONKeyList :: FromJSONKeyFunction [TypeID' version]

ToJSON (TypeID' version)

Defined in Data.TypeID.Internal

Methods

toJSON :: TypeID' version -> Value

toEncoding :: TypeID' version -> Encoding

toJSONList :: [TypeID' version] -> Value

toEncodingList :: [TypeID' version] -> Encoding

omitField :: TypeID' version -> Bool

ToJSONKey (TypeID' version)

Defined in Data.TypeID.Internal

Methods

toJSONKey :: ToJSONKeyFunction (TypeID' version)

toJSONKeyList :: ToJSONKeyFunction [TypeID' version]

type IDGenPrefix (TypeID' 'V1)

Defined in Data.TypeID.Internal

type IDGenPrefix (TypeID' 'V1) = 'Just Text

type IDGenPrefix (TypeID' 'V4)

Defined in Data.TypeID.Internal

type IDGenPrefix (TypeID' 'V4) = 'Just Text

type IDGenPrefix (TypeID' 'V5)

Defined in Data.TypeID.Internal

type IDGenPrefix (TypeID' 'V5) = 'Just Text

type IDGenPrefix (TypeID' 'V7)

Defined in Data.TypeID.Internal

type IDGenPrefix (TypeID' 'V7) = 'Just Text

type IDGenReq (TypeID' 'V1) a

Defined in Data.TypeID.Internal

type IDGenReq (TypeID' 'V1) a = a

type IDGenReq (TypeID' 'V4) a

Defined in Data.TypeID.Internal

type IDGenReq (TypeID' 'V4) a = a

type IDGenReq (TypeID' 'V5) r

Defined in Data.TypeID.Internal

type IDGenReq (TypeID' 'V5) r = UUID -> [Word8] -> r

type IDGenReq (TypeID' 'V7) a

Defined in Data.TypeID.Internal

type IDGenReq (TypeID' 'V7) a = a

getPrefix :: IDType a => a -> Text

Get the prefix of the identifier.

getUUID :: IDType a => a -> UUID

Get the UUID suffix of the identifier.

getTime :: IDType a => a -> Word64

Get the timestamp of the identifier. Returns 0 if the identifier is not timestamp-based.

TypeID generation (TypeID-specific)

genTypeID :: MonadIO m => Text -> m TypeID

Generate a new TypeID from a prefix.

It throws a TypeIDError if the prefix does not match the specification, namely if it's longer than 63 characters or if it contains characters other than lowercase latin letters.

genTypeID' :: MonadIO m => Text -> m TypeID

Generate a new TypeID from a prefix based on stateless UUIDv7.

See the documentation of genUUID' for more information.

genTypeIDs :: MonadIO m => Text -> Word16 -> m [TypeID]

Generate a list of TypeIDs from a prefix.

It tries its best to generate TypeIDs at the same timestamp, but it may not be possible if we are asking too many UUIDs at the same time.

It is guaranteed that the first 32768 TypeIDs are generated at the same timestamp.

decorateTypeID :: Text -> UUID -> Either TypeIDError TypeID

Obtain a TypeID from a prefix and a UUID.

TypeID generation (class methods)

genID :: forall a m. (IDGen a, MonadIO m) => GenFunc (IDGenPrefix a) (IDGenReq a (m a))

Generate a new identifier with the given prefix.

genID' :: forall a m. (IDGen a, MonadIO m) => GenFunc (IDGenPrefix a) (IDGenReq a (m a))

Similar to genID, but stateless. It can be a faster implementation than genID, but it does not guarantee any stateful property, such as monotonically increasing for UUIDv7-based identifiers.

The default implementation is the same as genID.

genIDs :: forall a m. (IDGen a, MonadIO m) => GenFunc (IDGenPrefix a) (IDGenReq a (Word16 -> m [a]))

Generate a list of identifiers with the given prefix.

decorate :: forall a. IDGen a => GenFunc (IDGenPrefix a) (UUID -> ResWithErr (IDGenPrefix a) a)

Generate a new identifier with the given prefix and UUID suffix.

Validation (TypeID-specific)

checkPrefix :: Text -> Maybe TypeIDError

Check if the given prefix is a valid TypeID prefix.

checkTypeID :: TypeID -> Maybe TypeIDError

Check if the prefix is valid and the suffix UUID has the correct v7 version and variant.

checkTypeIDWithEnv :: MonadIO m => TypeID -> m (Maybe TypeIDError)

Similar to checkTypeID, but also checks if the suffix UUID is generated in the past.

Validation (class methods)

checkID :: forall a. IDGen a => a -> Maybe TypeIDError

Check the validity of the identifier.

checkIDWithEnv :: forall a m. (IDGen a, MonadIO m) => a -> m (Maybe TypeIDError)

Check the validity of the identifier, potentially with impure criteria.

Encoding & decoding (TypeID-specific)

toString :: TypeID -> String

Pretty-print a TypeID. It is id2String with concrete type.

toText :: TypeID -> Text

Pretty-print a TypeID to strict Text. It is id2Text with concrete type.

toByteString :: TypeID -> ByteString

Pretty-print a TypeID to lazy ByteString. It is id2ByteString with concrete type.

parseString :: String -> Either TypeIDError TypeID

Parse a TypeID from its String representation. It is string2ID with concrete type.

parseText :: Text -> Either TypeIDError TypeID

Parse a TypeID from its string representation as a strict Text. It is text2ID with concrete type.

parseByteString :: ByteString -> Either TypeIDError TypeID

Parse a TypeID from its string representation as a lazy ByteString. It is byteString2ID with concrete type.

parseStringM :: MonadIO m => String -> m TypeID

Parse a TypeID from its String representation, throwing an error when the parsing fails. It is string2IDM with concrete type.

parseTextM :: MonadIO m => Text -> m TypeID

Parse a TypeID from its string representation as a strict Text, throwing an error when the parsing fails. It is text2IDM with concrete type.

parseByteStringM :: MonadIO m => ByteString -> m TypeID

Parse a TypeID from its string representation as a lazy ByteString, throwing an error when the parsing fails. It is byteString2IDM with concrete type.

Encoding & decoding (class methods)

id2String :: IDConv a => a -> String

Pretty-print the identifier to a String.

id2Text :: IDConv a => a -> Text

Pretty-print the identifier to a strict Text.

id2ByteString :: IDConv a => a -> ByteString

Pretty-print the identifier to a lazy ByteString.

string2ID :: IDConv a => String -> Either TypeIDError a

Parse the identifier from its String representation.

text2ID :: IDConv a => Text -> Either TypeIDError a

Parse the identifier from its string representation as a strict Text.

byteString2ID :: IDConv a => ByteString -> Either TypeIDError a

Parse the identifier from its string representation as a lazy ByteString.

string2IDM :: (IDConv a, MonadIO m) => String -> m a

Parse the identifier from its String representation, throwing an error when the parsing fails.

text2IDM :: (IDConv a, MonadIO m) => Text -> m a

Parse the identifier from its string representation as a strict Text, throwing an error when the parsing fails.

byteString2IDM :: (IDConv a, MonadIO m) => ByteString -> m a

Parse the identifier from its string representation as a lazy ByteString, throwing an error when the parsing fails.