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

import { connect } from "https://deno.land/x/redis/mod.ts";

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

Streams

import { connect } from "https://deno.land/x/redis/mod.ts";

const redis = await connect({ hostname: "127.0.0.1" });
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

First, if you need to set up nodes into a working redis cluster:

import { connect } from "https://deno.land/x/redis/mod.ts";

const redis = await connect({ hostname: "127.0.0.1", port: 6379 });

// connect each node to form a cluster (see https://redis.io/commands/cluster-meet)
await redis.clusterMeet("127.0.0.1", 6380);
// ...

// List the nodes in the cluster
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

To consume a redis cluster, you can use experimental/cluster module.

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.

import { connect } from "https://deno.land/x/redis/mod.ts";

const redis = await connect({ hostname: "127.0.0.1", 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.

import { connect } from "https://deno.land/x/redis/mod.ts";

const options = { hostname: "127.0.0.1" };
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.sendCommand is low level interface for redis protocol. You can send raw redis commands and receive replies.

import { connect, replyTypes } from "https://deno.land/x/redis/mod.ts";

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

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

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

Pipelining

https://redis.io/topics/pipelining

import { connect } from "https://deno.land/x/redis/mod.ts";

const redis = await connect({ hostname: "127.0.0.1" });
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

import { connect } from "https://deno.land/x/redis/mod.ts";

const redis = await connect({ hostname: "127.0.0.1" });
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

import { connect } from "https://deno.land/x/redis/mod.ts";

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