Use KV Store with a Redis-compatible client

Reach KV Store through a Redis-like client interface, with the familiar set, get, delete, and hash operations mapped onto Azion's library.

Last updated

View as Markdown Agent setup

The azion library exposes a Redis-like client for KV Store, so an application already written against Redis patterns keeps the shape of its calls. This guide covers the client, its options, the operations it carries, and how each one maps to the Redis command it stands in for.

Prerequisites

  • An Azion account. To create one, refer to How to create an account on Azion.
  • A KV Store namespace. It is created through the Azion API; refer to Namespaces.
  • Node.js 18 or later, or a compatible JavaScript runtime.

Install the library

npm install azion

Create a client

The client follows a Redis-like pattern, with chainable methods and a connection step:

TypeScript
01import { createClient } from 'azion/kv';
02
03const client = await createClient()
04 .on('error', (err) => console.error('KV Client Error:', err))
05 .connect();

Client options

TypeScript
01const client = await createClient({
02 namespace: 'my-namespace',
03 apiToken: 'my-token',
04})
05 .on('error', (err) => console.error('KV Error:', err))
06 .connect();
OptionTypeDescription
namespacestringThe KV Store namespace the client addresses
apiTokenstringAn Azion API token, required by the API provider

Store a value

set writes a value, with optional expiration and metadata:

TypeScript
01// A plain value
02await client.set('user:123', 'John Doe');
03
04// With an expiration of 10 seconds
05await client.set('session:abc', 'session-data', {
06 expiration: {
07 type: 'EX',
08 value: 10,
09 },
10});
11
12// With metadata
13await client.set('config:theme', 'dark', {
14 metadata: {
15 updatedBy: 'admin',
16 version: 1
17 },
18});
19
20// With both
21await client.set('cache:api-response', JSON.stringify(data), {
22 expiration: {
23 type: 'EX',
24 value: 300, // 5 minutes
25 },
26 metadata: {
27 source: 'external-api',
28 cached_at: Date.now()
29 },
30});

Expiration types

TypeDescription
EXExpiration time in seconds
PXExpiration time in milliseconds
EXATUnix timestamp in seconds
PXATUnix timestamp in milliseconds

Read a value

get returns the value, or null when the namespace holds no such key:

TypeScript
01const value = await client.get('user:123');
02console.log(value); // 'John Doe'
03
04// A key that does not exist returns null
05const missing = await client.get('non-existent');
06console.log(missing); // null

Read a value with its metadata

getWithMetadata returns the value and the metadata that was written with it:

TypeScript
01const result = await client.getWithMetadata('config:theme');
02console.log(result.value); // 'dark'
03console.log(result.metadata); // { updatedBy: 'admin', version: 1 }

Delete a key

delete removes a key, and del is an alias for it:

TypeScript
01await client.delete('user:123');
02// or
03await client.del('user:123');

Hash operations

The client carries Redis-compatible hash operations for field-value pairs under one key. Each one has an uppercase alias.

hSet

Writes one field of a hash:

TypeScript
01await client.hSet('user:profile:123', 'name', 'John Doe');
02await client.hSet('user:profile:123', 'email', 'john@example.com');
03await client.hSet('user:profile:123', 'role', 'admin');
04
05// The uppercase alias
06await client.HSET('user:profile:123', 'status', 'active');

hGetAll

Returns every field and value of a hash:

TypeScript
01const profile = await client.hGetAll('user:profile:123');
02console.log(profile);
03// { name: 'John Doe', email: 'john@example.com', role: 'admin', status: 'active' }
04
05const data = await client.HGETALL('user:profile:123');

hVals

Returns every value of a hash, without the field names:

TypeScript
01const values = await client.hVals('user:profile:123');
02console.log(values);
03// ['John Doe', 'john@example.com', 'admin', 'active']
04
05const vals = await client.HVALS('user:profile:123');

Provider detection

The client detects the runtime it is executing in and selects a provider:

  • Native provider: selected inside the Azion Runtime, where a function executes.
  • API provider: selected outside Azion, in local development or on an external server.

getProviderType reports which one is in use:

TypeScript
01const providerType = client.getProviderType();
02console.log(providerType); // 'native' or 'api'

Handle errors

The client reports failures through an error event:

TypeScript
01const client = await createClient()
02 .on('error', (err) => {
03 console.error('KV Error:', err.message);
04 // Retry, fall back, or surface the failure
05 })
06 .connect();

A single operation is also wrapped in try/catch:

TypeScript
01try {
02 await client.set('key', 'value');
03} catch (error) {
04 console.error('Failed to set value:', error);
05}

Close the connection

Close the client when the work is finished:

TypeScript
01await client.disconnect();
02// or
03await client.quit();

Complete example

The operations above, composed into one run:

TypeScript
01import { createClient } from 'azion/kv';
02
03async function main() {
04 const client = await createClient({
05 namespace: 'my-app',
06 })
07 .on('error', (err) => console.error('KV Error:', err))
08 .connect();
09
10 try {
11 // Store user data
12 await client.set('user:1', JSON.stringify({ name: 'Alice', age: 30 }), {
13 expiration: { type: 'EX', value: 3600 }, // 1 hour
14 metadata: { created: Date.now() },
15 });
16
17 // Store a profile as a hash
18 await client.hSet('profile:1', 'theme', 'dark');
19 await client.hSet('profile:1', 'language', 'en');
20 await client.hSet('profile:1', 'notifications', 'true');
21
22 // Read the user data back
23 const userData = await client.get('user:1');
24 console.log('User:', JSON.parse(userData));
25
26 // Read it with its metadata
27 const result = await client.getWithMetadata('user:1');
28 console.log('Created at:', result.metadata.created);
29
30 // Read every profile field
31 const profile = await client.hGetAll('profile:1');
32 console.log('Profile:', profile);
33
34 // Remove the key
35 await client.delete('user:1');
36
37 } finally {
38 await client.disconnect();
39 }
40}
41
42main().catch(console.error);

Redis method mapping

Redis commandClient methodDescription
GETget(key)Read a value
SETset(key, value, options?)Write a value
DELdelete(key) / del(key)Remove a key
HSEThSet(key, field, value) / HSET(...)Write a hash field
HGETALLhGetAll(key) / HGETALL(key)Read every hash field
HVALShVals(key) / HVALS(key)Read every hash value

Next steps

KV clientThe Azion.KV interface a function uses, with every method and option.Manage key-value data from a functionStore, read, and delete data from inside a function.NamespacesCreate the namespace this client addresses, through the Azion API.KV StoreWhat the product is, its two interfaces, and where it stops.