deno-redis

Build Status https://img.shields.io/github/tag/denodrivers/redis.svg license deno doc Discord

An experimental implementation of redis client for deno

Usage

needs --allow-net privilege

Stateless Commands

import { connect } from "https://deno.land/x/redis/mod.ts";
const redis = await connect({
  hostname: "127.0.0.1",
  port: 6379,
});
const ok = await redis.set("hoge", "fuga");
const fuga = await redis.get("hoge");

PubSub

const sub = await redis.subscribe("channel");
(async function () {
  for await (const { channel, message } of sub.receive()) {
    // on message
  }
})();

Streams

await redis.xadd(
  "somestream",
  "*", // let redis assign message ID
  { yes: "please", no: "thankyou" },
  { elements: 10 },
);

const [stream] = await redis.xread(
  [{ key: "somestream", xid: 0 }], // read from beginning
  { block: 5000 },
);

const msgFV = stream.messages[0].fieldValues;
const plz = msgFV["yes"];
const thx = msgFV["no"];

Cluster

await redis.clusterMeet("127.0.0.1", 6380);
await redis.clusterNodes();
// ... 127.0.0.1:6379@16379 myself,master - 0 1593978765000 0 connected
// ... 127.0.0.1:6380@16380 master - 0 1593978766503 1 connected

Advanced Usage

Retriable connection

By default, a client's connection will throw an error if the server dies or the network becomes unavailable. A connection can be made "retriable" by setting the value maxRetryCount when connecting a new client.

const redis = await connect({ ...options, maxRetryCount: 10 });

// The client will try to connect to the server 10 times if the server dies or the network becomes unavailable.

The property is set automatically to 10 when creating a subscriber client. After a reconnection succeeds, the client will subscribe again to all the channels and patterns.

const redis = await connect(options);
const subscriberClient = await redis.subscribe("channel");

// The client's connection will now be forced to try to connect to the server 10 times if the server dies or the network
//   becomes unavailable.

Execute raw commands

redis.executor is raw level redis protocol executor. You can send raw redis commands and receive replies.

{
  const reply = await redis.executor.exec("SET", "redis", "nice");
  assert(reply.type === replyTypes.SimpleString);
  assert(reply.value() === "OK");
}

{
  const reply = await redis.executor.exec("GET", "redis");
  assert(reply.type === replyTypes.BulkString);
  assert(reply.value() === "nice");
}

Pipelining

https://redis.io/topics/pipelining

const redis = await connect({
  hostname: "127.0.0.1",
  port: 6379,
});
const pl = redis.pipeline();
pl.ping();
pl.ping();
pl.set("set1", "value1");
pl.set("set2", "value2");
pl.mget("set1", "set2");
pl.del("set1");
pl.del("set2");
const replies = await pl.flush();

TxPipeline (pipeline with MULTI/EXEC)

We recommend to use tx() instead of multi()/exec() for transactional operation. MULTI/EXEC are potentially stateful operation so that operation's atomicity is guaranteed but redis's state may change between MULTI and EXEC.

WATCH is designed for these problems. You can ignore it by using TxPipeline because pipelined MULTI/EXEC commands are strictly executed in order at the time and no changes will happen during execution.

See detail https://redis.io/topics/transactions

const tx = redis.tx();
tx.set("a", "aa");
tx.set("b", "bb");
tx.del("c");
await tx.flush();
// MULTI
// SET a aa
// SET b bb
// DEL c
// EXEC

Client side caching

https://redis.io/topics/client-side-caching

const mainClient = await connect({ hostname: "127.0.0.1" });
const cacheClient = await connect({ hostname: "127.0.0.1" });

const cacheClientID = await cacheClient.clientID();
await mainClient.clientTracking({
  mode: "ON",
  redirect: cacheClientID,
});
const sub = await cacheClient.subscribe<string[]>("__redis__:invalidate");

(async () => {
  for await (const { channel, message } of sub.receive()) {
    // Handle invalidation messages...
  }
})();

Experimental features

deno-redis provides some experimental features.

See experimental/README.md for details.

Roadmap for v1