token-based-map
v0.0.1
Published
A simple way to store and retrieve arbitrary data in a type-safe way without using generics.
Downloads
1
Maintainers
Readme
token-based-map
A simple way to store and retrieve arbitrary data in a type-safe way without using generics. Useful when a system requires occasionally sharing data between loosely coupled components (the middleware pattern, interceptors, complex pipelines).
Usage
$ npm install token-based-map
import { Token, TokenBasedMap } from 'token-based-map'
// Create a map. Note how there is not type information at
// this level. The map itself doesn't retain type information
// about its contents.
const map = new TokenBasedMap()
// Tokens are the only things you can use as keys in the map.
// Type information is stored in them. The string given
// through the constructor is for debugging purposes only.
const A_TOKEN = new Token<number>('a token')
// Type checking happens when setting and getting values.
// Only numbers will be accepted for this token, due to the
// way the token is defined.
map.set(A_TOKEN, 3)
// When retreiving data from the map, type is inferred from
// the type of token. Even without an explicit type annotation,
// `retriesCount` will be of type `number | null`.
const retriesCount = map.get(A_TOKEN)
// If the map doesn't contain a particular token set, `null`
// will be returned by default. You can change this behavior
// by supplying the second argument. This returns a `number`.
const retriesCount2 = map.get(A_TOKEN, { onMiss: 'throw' })
// To check if a key is set, use `has`.
const isPresent = map.has(A_TOKEN)
// When setting a value for a key that's already been set, the
// default behavior is to overwrite the previous value. You can
// choose to throw an error instead or ignore the attempt.
map.set(A_TOKEN, 4, { onConflict: 'throw' })
map.set(A_TOKEN, 5, { onConflict: 'ignore' })
// Deleting a key is straight-forward as well. If you're trying
// to delete a key that hasn't been set, nothing happens by
// default. You can choose to raise an error instead.
map.delete(A_TOKEN)
map.delete(A_TOKEN, { onMiss: 'throw' })
Differences from a Map
No initializer
You can initialize a map by feeding it with an iterable of key-value pairs through the constructor.
const map = new Map([['a', 1], ['b', 2]])
Due to difficulties in type-checking such an iterable, this is not allowed in TokenBasedMap
. All maps are created empty.
const map = new TokenBasedMap()
null
instead of undefined
When getting a value for a key which isn't in the map, Map
returns undefined
.
const map = new Map()
console.assert(map.get('a') === undefined)
A TokenBasedMap
will return a null
instead.
const map = new TokenBasedMap()
const token = new Token<number>('demo')
console.assert(map.get(token) === null)
No iteration
You can iterate over key-value pairs in a Map
.
for (const [key, value] of map) {
console.log(key, value)
}
map.forEach(([key, value]) => {
console.log(key, value)
})
This is not possible with a TokenBasedMap
by design. If it were, you'd be able to access (and change) arbitrary data. Tokens are “keys” in the literal sense too; you need the dedicated key to unlock the value.
No clearing everything
Similarly to above, you cannot clear everything from a TokenBasedMap
like you can with a Map
.
const map = new Map()
map.clear()
The rationale is the same as previously: it would allow deleting tokens that a particular piece of logic should not have access to.