Probably the most common example of a similar data structure is an API where we provide a Class to get an instance of it. In Java, it could look like this:

Guava’s ClassToInstanceMap is a good example of such a data structure. Additionally, there are e.g. EntityManager.unwrap() and BeanManager.getExtension() methods that utilize similar API, however, their purpose is more specialized.

typedmap supports this feature with a clean API:

Due to advanced type inferring in Kotlin, in many cases we don’t need to specify a type when getting an item:

typedmap fully supports parameterized types:

Looking for items by their type is very convenient, but in many cases this is not enough. For example, it is difficult to store multiple instances of the same class and access them individually. Moreover, if we need to store an item of a common type, e.g. String, then the code get() becomes enigmatic, because it is not clear what is the String we requested. In such cases, we can create keys to identify items in the map.

Let’s assume we develop a web application, and we store some data in the web session. In the previous example, we stored a user object in the session, but this time we just need to store a username. In addition, we would like to store a session ID and visits count. We have to create a key for each item and use these keys to identify values:

When creating a key, we need to provide a type of its associated value. This makes possible to provide a fully type-safe API:

Similarly as in the previous section, we can use keys in conjunction with parameterized types:

Declaring keys in the way described above is fine if we need to store a finite set of known items, so we can create a distinct key for each of them. In practice though, we very often need to create keys dynamically and store an arbitrary number of items in a map. This is supported by typedmap as well, and we still keep its type-safety feature. In fact, this case is implemented in typedmap in a very similar way to regular maps.

Instead of creating the key as a singleton object, we need to define it as a class. hashCode() and equals() have to be properly implemented, so the easiest is to use a data class:

This example could be improved by using the AutoKey util. AutoKey is a very simple interface that we can implement to make map items responsible for creating their keys:

There are several existing examples in Java with similar requirements to described above and implemented using either untyped container and manual casting or with a class-to-instance map or function:

• In Servlet API we could store and retrieve additional untyped data at request level (ServletRequest.getAttribute()), session level (HttpSession.getAttribute()) and globally (ServletContext.getAttribute()).

• Jax-RS Filters (middleware) could store/retrieve additional request data using: ContainerRequestContext.getProperty().

• In JPA we could store custom data in EntityManager in its properties: EntityManager.getProperties(), although I’m not sure this functionality was intended for such purposes.

• Spring Framework uses untyped map for session data: WebSession.getAttribute(), Session.getAttribute(). It is a little smarter than previous examples, because it uses type inference, so we don’t need to cast the value manually. It doesn’t change much though - we still need to remember which value was stored with which key and specify the type manually.

• In Spring Integration one of its main components, Message, is a generic data holder/wrapper and it could contain headers which is basically an untyped map. Additionally, there are wrappers for this untyped map to provide a strongly typed API, e.g.: SimpMessageHeaderAccessor.

• In Android, we very often pass data as untyped Bundle map, for example in Intent extras.

Additionally, there are examples of data structures very similar to typedmap. In fact, they exist in one of the most popular libraries for Kotlin:

• CoroutineContext - its Key interface and get() function. It allows to store any data within a coroutine.

• Attributes of Ktor web framework by JetBrains. It is used as a storage for middleware.

Typed maps aren’t the only solution to a similar problem. There are other techniques, including:

• Use untyped map (e.g. Map) as a central storage and provide strongly-typed accessors by clients/modules. Accessors could be: extension functions, static functions or even classes that wrap untyped map and provide an easy to use API.

  This solution could be very convenient to use, especially with extension functions, however, writing accessors requires much more work than just creating a typed key. Furthermore, typedmap naturally guarantees that each key is unique. Accessors need to do the same or they would risk conflicts.

• class-to-instance maps.

  In many cases they are less convenient to use. For example, if we need to store multiple simple items (strings, integers), we need to create a wrapper class for each of them and then wrap/unwrap a value whenever storing/retrieving it. Also, it is not trivial to store collections of items as in Key With Data.