@ofek.a/fastify-iovalkey

Fastify Valkey connection plugin, with this you can share the same Valkey connection in every part of your server.

Under the hood iovalkey is used as client.

Install

npm i @ofek.a/fastify-iovalkey

Compatibility

Plugin version	Fastify version
0.x	^5.x

Please note that if a Fastify version is out of support, then so are the corresponding versions of this plugin in the table above. See Fastify's LTS policy for more details.

Usage

Add it to your project with register and you are done!

Create a new Valkey Client

the options that you pass to register will be passed to the Valkey client.

1import Fastify from 'fastify'
2import fastifyValkey from '@ofek.a/fastify-iovalkey'
3
4const fastify = Fastify()
5
6// create by specifying host
7await fastify.register(fastifyValkey, { host: '127.0.0.1' })
8
9// OR by specifying Valkey URL
10await fastify.register(fastifyValkey, { url: 'valkey://127.0.0.1', /* other valkey options */ })
11
12// OR with more options
13await fastify.register(fastifyValkey, {
14  host: '127.0.0.1',
15  password: '***',
16  port: 6379, // Valkey port
17  family: 4   // 4 (IPv4) or 6 (IPv6)
18})

Accessing the Valkey Client

Once you have registered your plugin, you can access the Valkey client via fastify.iovalkey.

The client is automatically closed when the fastify instance is closed.

1import Fastify from 'fastify'
2import fastifyValkey from '@ofek.a/fastify-iovalkey'
3
4const fastify = Fastify({ logger: true })
5
6await fastify.register(fastifyValkey, {
7  host: '127.0.0.1',
8  password: 'your strong password here',
9  port: 6379, // Valkey port
10  family: 4   // 4 (IPv4) or 6 (IPv6)
11})
12
13fastify.get('/foo', async (req, reply) => {
14  const { iovalkey } = fastify
15  try {
16    const val = await iovalkey.get(req.query.key)
17    return val
18  } catch (err) {
19    return err
20  }
21})
22
23fastify.post('/foo', async (req, reply) => {
24  const { iovalkey } = fastify
25  try {
26    await iovalkey.set(req.body.key, req.body.value)
27    return { status: 'ok' }
28  } catch (err) {
29    return err
30  }
31})
32
33try {
34  await fastify.listen({ port: 3000 })
35  console.log(`server listening on ${fastify.server.address().port}`)
36} catch (err) {
37  fastify.log.error(err)
38  process.exit(1)
39}

Using an existing Valkey client

You may also supply an existing Valkey client instance by passing an options object with the client property set to the instance. In this case, the client is not automatically closed when the Fastify instance is closed.

1import Fastify from 'fastify'
2import Valkey from 'iovalkey'
3import fastifyValkey from '@ofek.a/fastify-iovalkey'
4
5const fastify = Fastify()
6const client = new Valkey({ host: 'localhost', port: 6379 })
7
8await fastify.register(fastifyValkey, { client })

You can also supply a Valkey Cluster instance to the client:

1import Fastify from 'fastify'
2import Valkey from 'iovalkey'
3import fastifyValkey from '@ofek.a/fastify-iovalkey'
4
5const fastify = Fastify()
6const client = new Valkey.Cluster([{ host: 'localhost', port: 6379 }]);
7
8await fastify.register(fastifyValkey, { client })

Note: by default, @ofek.a/fastify-iovalkey will not automatically close the client connection when the Fastify server shuts down.

To automatically close the client connection, set closeClient to true.

1await fastify.register(fastifyValkey, { client, closeClient: true })

Registering multiple Valkey client instances

By using the namespace option you can register multiple Valkey client instances.

1import Fastify from 'fastify'
2import Valkey from 'iovalkey'
3import fastifyValkey from '@ofek.a/fastify-iovalkey'
4
5const fastify = Fastify()
6const valkeyClient = new Valkey({ host: 'localhost', port: 6379 })
7
8await fastify.register(fastifyValkey, {
9  host: '127.0.0.1',
10  port: 6380,
11  namespace: 'hello'
12})
13
14await fastify.register(fastifyValkey, {
15  client: valkeyClient,
16  namespace: 'world'
17})
18
19// Here we will use the `hello` named instance
20fastify.get('/hello', async (req, reply) => {
21  const { iovalkey } = fastify
22  
23  try {
24    const val = await iovalkey.hello.get(req.query.key)
25    return val
26  } catch (err) {
27    return err
28  }
29})
30
31fastify.post('/hello', async (req, reply) => {
32  const { iovalkey } = fastify
33  
34  try {
35    await iovalkey['hello'].set(req.body.key, req.body.value)
36    return { status: 'ok' }
37  } catch (err) {
38    return err
39  }
40})
41
42// Here we will use the `world` named instance
43fastify.get('/world', async (req, reply) => {
44  const { iovalkey } = fastify
45  
46  try {
47    const val = await iovalkey['world'].get(req.query.key)
48    return val
49  } catch (err) {
50    return err
51  }
52})
53
54fastify.post('/world', async (req, reply) => {
55  const { iovalkey } = fastify
56  
57  try {
58    await iovalkey.world.set(req.body.key, req.body.value)
59    return { status: 'ok' }
60  } catch (err) {
61    return err
62  }
63})
64
65try {
66  await fastify.listen({ port: 3000 })
67  console.log(`server listening on ${fastify.server.address().port}`)
68} catch (err) {
69  fastify.log.error(err)
70  process.exit(1)
71}

Valkey streams (Valkey 5.0 or greater is required)

@fastify/iovalkey supports Valkey streams out of the box.

1import Fastify from 'fastify'
2import fastifyValkey from '@ofek.a/fastify-iovalkey'
3
4const fastify = Fastify()
5
6await fastify.register(fastifyValkey, {
7  host: '127.0.0.1',
8  port: 6380
9})
10
11fastify.get('/streams', async (request, reply) => {
12  // We write an event to the stream 'my awesome fastify stream name', setting 'key' to 'value'
13  await fastify.iovalkey.xadd(['my awesome fastify stream name', '*', 'hello', 'fastify is awesome'])
14
15  // We read events from the beginning of the stream called 'my awesome fastify stream name'
16  let valkeyStream = await fastify.iovalkey.xread(['STREAMS', 'my awesome fastify stream name', 0])
17
18  // We parse the results
19  let response = []
20  let events = valkeyStream[0][1]
21
22  for (let i = 0; i < events.length; i++) {
23    const e = events[i]
24    response.push(`#LOG: id is ${e[0].toString()}`)
25
26    // We log each key
27    for (const key in e[1]) {
28      response.push(e[1][key].toString())
29    }
30  }
31
32  return { output: response }
33  // Will return something like this :
34  // { "output": ["#LOG: id is 1559985742035-0", "hello", "fastify is awesome"] }
35})
36
37try {
38  await fastify.listen({ port: 3000 })
39  console.log(`server listening on ${fastify.server.address().port}`)
40} catch (err) {
41  fastify.log.error(err)
42  process.exit(1)
43}

NB you can find more information about Valkey streams and the relevant commands here and here.

Valkey connection error

The majority of errors are silent due to the iovalkey silent error handling but during the plugin registration it will check that the connection with the valkey instance is correctly established. In this case, you can receive an ERR_AVVIO_PLUGIN_TIMEOUT error if the connection cannot be established in the expected time frame or a dedicated error for an invalid connection.

License

Licensed under MIT.