Data.KindID

Similar to Data.TypeID, but the type is statically determined in the type level.

When using TypeID, if we want to check if the type matches, we usually need to get the prefix of the TypeID and compare it with the desired prefix at runtime. However, with Haskell's type system, we can do this at compile time instead. We call this TypeID with compile-time prefix a KindID.

Of course, that would require the desired prefix to be known at compile time. This is actually quite common, especially when we are using one prefix for one table in the database.

For example, suppose we have a function that takes a KindID with the prefix "user", it may have a signature like this: f :: KindID "user" -> IO ()

Then if we try to pass in a KindID with the prefix "post", the compiler will complain, thus removing the runtime check and the associated overhead.

All the prefixes are type-checked at compile time, so if we try to pass in invalid prefixes, the compiler (again) will complain.

This module contains functions to generate and parse these type-level TypeIDs as well as conversion functions to and from the usual term-level TypeIDs. These functions are usually used with a type application, e.g.

do
  kindID <- genKindID @"user"
  ...

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

Data types

type KindID = KindID' 'V7

A type alias for the default KindID implementation with UUIDv7.

data KindID' (version :: UUIDVersion) prefix

A TypeID with the prefix encoded at type level.

It is dubbed KindID because the prefix here is a data kind rather than a type.

Instances

(Typeable prefix, Typeable k, Typeable version) => Data (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

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

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

toConstr :: KindID' version prefix -> Constr

dataTypeOf :: KindID' version prefix -> DataType

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

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

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

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

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

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

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

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

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

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

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => Storable (KindID' version prefix)

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

Defined in Data.KindID.Internal

Methods

sizeOf :: KindID' version prefix -> Int

alignment :: KindID' version prefix -> Int

peekElemOff :: Ptr (KindID' version prefix) -> Int -> IO (KindID' version prefix)

pokeElemOff :: Ptr (KindID' version prefix) -> Int -> KindID' version prefix -> IO ()

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

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

peek :: Ptr (KindID' version prefix) -> IO (KindID' version prefix)

poke :: Ptr (KindID' version prefix) -> KindID' version prefix -> IO ()

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => Read (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

readsPrec :: Int -> ReadS (KindID' version prefix)

readList :: ReadS [KindID' version prefix]

readPrec :: ReadPrec (KindID' version prefix)

readListPrec :: ReadPrec [KindID' version prefix]

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => Show (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

showsPrec :: Int -> KindID' version prefix -> ShowS

show :: KindID' version prefix -> String

showList :: [KindID' version prefix] -> ShowS

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => Binary (KindID' version prefix)

See The Binary instance of TypeID'.

Defined in Data.KindID.Internal

Methods

put :: KindID' version prefix -> Put

get :: Get (KindID' version prefix)

putList :: [KindID' version prefix] -> Put

Eq (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

(==) :: KindID' version prefix -> KindID' version prefix -> Bool

(/=) :: KindID' version prefix -> KindID' version prefix -> Bool

Ord (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

compare :: KindID' version prefix -> KindID' version prefix -> Ordering

(<) :: KindID' version prefix -> KindID' version prefix -> Bool

(<=) :: KindID' version prefix -> KindID' version prefix -> Bool

(>) :: KindID' version prefix -> KindID' version prefix -> Bool

(>=) :: KindID' version prefix -> KindID' version prefix -> Bool

max :: KindID' version prefix -> KindID' version prefix -> KindID' version prefix

min :: KindID' version prefix -> KindID' version prefix -> KindID' version prefix

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => Hashable (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

hashWithSalt :: Int -> KindID' version prefix -> Int

hash :: KindID' version prefix -> Int

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => IDConv (KindID' version prefix)

Conversion between KindID' and StringTextByteString.

Defined in Data.KindID.Internal

Methods

string2ID :: String -> Either TypeIDError (KindID' version prefix)

text2ID :: Text -> Either TypeIDError (KindID' version prefix)

byteString2ID :: ByteString -> Either TypeIDError (KindID' version prefix)

id2String :: KindID' version prefix -> String

id2Text :: KindID' version prefix -> Text

id2ByteString :: KindID' version prefix -> ByteString

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

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

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

unsafeString2ID :: String -> KindID' version prefix

unsafeText2ID :: Text -> KindID' version prefix

unsafeByteString2ID :: ByteString -> KindID' version prefix

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => IDGen (KindID' 'V1 prefix)

Generate KindID' 'V1s.

Defined in Data.KindID.Internal

Associated Types

type IDGenPrefix (KindID' 'V1 prefix) :: Maybe Type

type IDGenReq (KindID' 'V1 prefix) r

Methods

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

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

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

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

checkID_ :: Proxy (KindID' 'V1 prefix) -> KindID' 'V1 prefix -> Maybe TypeIDError

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

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => IDGen (KindID' 'V4 prefix)

Generate KindID' 'V4s.

Defined in Data.KindID.Internal

Associated Types

type IDGenPrefix (KindID' 'V4 prefix) :: Maybe Type

type IDGenReq (KindID' 'V4 prefix) r

Methods

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

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

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

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

checkID_ :: Proxy (KindID' 'V4 prefix) -> KindID' 'V4 prefix -> Maybe TypeIDError

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

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => IDGen (KindID' 'V5 prefix)

Generate KindID' 'V5s.

Defined in Data.KindID.Internal

Associated Types

type IDGenPrefix (KindID' 'V5 prefix) :: Maybe Type

type IDGenReq (KindID' 'V5 prefix) r

Methods

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

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

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

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

checkID_ :: Proxy (KindID' 'V5 prefix) -> KindID' 'V5 prefix -> Maybe TypeIDError

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

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => IDGen (KindID' 'V7 prefix)

Generate KindIDs.

Defined in Data.KindID.Internal

Associated Types

type IDGenPrefix (KindID' 'V7 prefix) :: Maybe Type

type IDGenReq (KindID' 'V7 prefix) r

Methods

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

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

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

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

checkID_ :: Proxy (KindID' 'V7 prefix) -> KindID' 'V7 prefix -> Maybe TypeIDError

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

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => IDType (KindID' version prefix)

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

Defined in Data.KindID.Internal

Methods

getPrefix :: KindID' version prefix -> Text

getUUID :: KindID' version prefix -> UUID

getTime :: KindID' version prefix -> Word64

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => FromJSON (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

parseJSON :: Value -> Parser (KindID' version prefix)

parseJSONList :: Value -> Parser [KindID' version prefix]

omittedField :: Maybe (KindID' version prefix)

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => FromJSONKey (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

fromJSONKey :: FromJSONKeyFunction (KindID' version prefix)

fromJSONKeyList :: FromJSONKeyFunction [KindID' version prefix]

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => ToJSON (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

toJSON :: KindID' version prefix -> Value

toEncoding :: KindID' version prefix -> Encoding

toJSONList :: [KindID' version prefix] -> Value

toEncodingList :: [KindID' version prefix] -> Encoding

omitField :: KindID' version prefix -> Bool

(ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => ToJSONKey (KindID' version prefix)

Defined in Data.KindID.Internal

Methods

toJSONKey :: ToJSONKeyFunction (KindID' version prefix)

toJSONKeyList :: ToJSONKeyFunction [KindID' version prefix]

type IDGenPrefix (KindID' 'V1 prefix)

Defined in Data.KindID.Internal

type IDGenPrefix (KindID' 'V1 prefix) = 'Nothing :: Maybe Type

type IDGenPrefix (KindID' 'V4 prefix)

Defined in Data.KindID.Internal

type IDGenPrefix (KindID' 'V4 prefix) = 'Nothing :: Maybe Type

type IDGenPrefix (KindID' 'V5 prefix)

Defined in Data.KindID.Internal

type IDGenPrefix (KindID' 'V5 prefix) = 'Nothing :: Maybe Type

type IDGenPrefix (KindID' 'V7 prefix)

Defined in Data.KindID.Internal

type IDGenPrefix (KindID' 'V7 prefix) = 'Nothing :: Maybe Type

type IDGenReq (KindID' 'V1 prefix) r

Defined in Data.KindID.Internal

type IDGenReq (KindID' 'V1 prefix) r = r

type IDGenReq (KindID' 'V4 prefix) r

Defined in Data.KindID.Internal

type IDGenReq (KindID' 'V4 prefix) r = r

type IDGenReq (KindID' 'V5 prefix) r

Defined in Data.KindID.Internal

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

type IDGenReq (KindID' 'V7 prefix) r

Defined in Data.KindID.Internal

type IDGenReq (KindID' 'V7 prefix) r = r

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.

KindID generation (KindID-specific)

genKindID :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix), MonadIO m) => m (KindID prefix)

Generate a new KindID 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.

genKindID' :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix), MonadIO m) => m (KindID prefix)

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

See the documentation of genUUID' for more information.

genKindIDs :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix), MonadIO m) => Word16 -> m [KindID prefix]

Generate a list of KindIDs from a prefix.

It tries its best to generate KindIDs 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 KindIDs are generated at the same timestamp.

decorateKindID :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => UUID -> KindID prefix

Obtain a KindID from a prefix and a UUID.

KindID 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 (KindID-specific)

checkKindID :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => KindID prefix -> Maybe TypeIDError

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

checkKindIDWithEnv :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix), MonadIO m) => KindID' 'V7 prefix -> m (Maybe TypeIDError)

Similar to checkKindID, 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 (KindID-specific)

toString :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => KindID prefix -> String

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

toText :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => KindID prefix -> Text

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

toByteString :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => KindID prefix -> ByteString

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

parseString :: forall prefix. (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => String -> Either TypeIDError (KindID prefix)

Parse a KindID from its String representation. It is parseString with concrete type.

parseText :: forall prefix. (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => Text -> Either TypeIDError (KindID prefix)

Parse a KindID from its string representation as a strict Text. It is parseText with concrete type.

parseByteString :: forall prefix. (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => ByteString -> Either TypeIDError (KindID prefix)

Parse a KindID from its string representation as a lazy ByteString. It is parseByteString with concrete type.

parseStringM :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix), MonadIO m) => String -> m (KindID prefix)

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

parseTextM :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix), MonadIO m) => Text -> m (KindID prefix)

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

parseByteStringM :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix), MonadIO m) => ByteString -> m (KindID prefix)

Parse a KindID from its string representation as a lazy ByteString, throwing an error when the parsing fails. It is byteString2IDM with concrete type. It is parseByteStringM 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.

Type-level & term-level conversion

toTypeID :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => KindID prefix -> TypeID

Convert a KindID to a TypeID.

fromTypeID :: (ToPrefix prefix, ValidPrefix (PrefixSymbol prefix)) => TypeID -> Maybe (KindID prefix)

Convert a TypeID to a KindID.