Skip to main content
Deno 2 is finally here 🎉️
Learn more
Functional Redis

A simple Redis client in tune with Functional Programming principles in JavaScript for Deno.

deno land deno version GitHub release GitHub licence Discord Chat

Usage

Functional Redis is optimized to write elegant and powerful point-free functions. This example uses the Ramda library - for simplification - but you should be able to use any library that implements the Fantasy-land specifications.

import { safeExtract } from "https://deno.land/x/functional@v1.3.2/library/utilities.js";
import File from "https://deno.land/x/functional_io@v1.1.0/library/File.js";
import { writeFile } from "https://deno.land/x/functional_io@v1.1.0/library/fs.js";
import RedisRequest from "https://deno.land/x/functional_redis@v0.1.3/library/RedisRequest.js";
import {
  createRedisSession,
  pipeRedisCommand
} from "https://deno.land/x/functional_redis@v0.1.3/library/client.js";

const copyHogeToFuga = createRedisSession(
  compose(
    chain(
      compose(
        writeFile({}),
        concat(File.fromPath(`${Deno.cwd()}/hoge`))
      )
    ),
    pipeRedisCommand(
      [
        RedisRequest.set({}, "hoge", "piyo"),
        RedisRequest.get("hoge"),
        RedisRequest.set({}, "fuga")
      ]
    )
  )
);

const container = await copyHogeToFuga({ port: 6379 }).run();

safeExtract("Failed to execute the request.", container);

Redis Request

The RedisRequest represents a Redis request. It has three attributes: the first is the Redis command, the second is a typed array named “raw”, the last is an array of arguments. The RedisRequest type is mostly interoperable with RedisResponse, Resource, File, (HTTP) Request
and (HTTP) Response.

The RedisRequest type implements the following algebras:

  • Group
  • Comonad
  • Monad

Example

import RedisRequest from "https://deno.land/x/functional-redis@v0.1.1/library/RedisRequest.js";

const redisRequest = RedisRequest("GET", new Uint8Array([]), [ "hoge" ]);

assert(RedisRequest.is(redisRequest));

A Symbol named rawPlaceholder may be used as a placeholder for the buffer. In the following example, the request will resolve to: SET hoge piyo.

import { encodeText } from "https://deno.land/x/functional@v1.3.2/library/utilities.js";
import RedisRequest from "https://deno.land/x/functional-redis@v0.1.1/library/RedisRequest.js";
import { $$rawPlaceholder } from "https://deno.land/x/functional-redis@v0.1.0/library/Symbol.js";

const redisRequest = RedisRequest("SET", encodeText("piyo"), [ "hoge", $$rawPlaceholder ]);

assert(RedisRequest.is(redisRequest));

The placeholder can be used multiple times if the buffer has multiple values separated by CLRF (\r\n).

import { encodeText } from "https://deno.land/x/functional@v1.3.2/library/utilities.js";
import RedisRequest from "https://deno.land/x/functional-redis@v0.1.1/library/RedisRequest.js";
import { $$rawPlaceholder } from "https://deno.land/x/functional-redis@v0.1.0/library/Symbol.js";

const redisRequest = RedisRequest(
  "MSET",
  encodeText("piyo\r\nfuga\r\n"),
  [ "hoge", $$rawPlaceholder, "hogefuga", $$rawPlaceholder ]
);

assert(RedisRequest.is(redisRequest));

Utilities

The RedisRequest namespace comes with methods for convenience to create an instance of RedisRequest with various commands. The methods are curried.

factorizeRedisRequest

String → Uint8Array → (String|Symbol)[] → RedisRequest

This curried function takes a string for the name of the Redis command, a (optionally empty) Uint8Array and, an array for the arguments. The return value is an instance of RedisRequest.

String commands

RedisRequest.append 📕

String → (String|Uint8Array) → RedisRequest

const redisRequest = RedisRequest.append("hoge", "piyo");
RedisRequest.bitcount 📕

String → [ Number, Number ] → RedisRequest

const redisRequest = RedisRequest.bitcount("hoge", [ 0, 1 ]);
RedisRequest.bitfield 📕

String → String[] → RedisRequest

const redisRequest = RedisRequest.bitfield("hoge", [ "GET", "i8", 100 ]);
RedisRequest.bitop 📕

String → String → String[] → RedisRequest

const redisRequest = RedisRequest.bitop("AND", "hoge", [ "piyo", "fuga" ]);
RedisRequest.bitpos 📕

String → [ Number, Number ] → RedisRequest

const redisRequest = RedisRequest.bitpos("hoge", [ 0, 1 ]);
RedisRequest.decr 📕

String → RedisRequest

const redisRequest = RedisRequest.decr("hoge");
RedisRequest.decrby 📕

String → Number → RedisRequest

const redisRequest = RedisRequest.decrby("hoge", 3);
RedisRequest.get 📕

String → RedisRequest

const redisRequest = RedisRequest.get("hoge");
RedisRequest.getbit 📕

String → Number → RedisRequest

const redisRequest = RedisRequest.getbit("hoge", 3);
RedisRequest.getrange 📕

String → [ Number, Number ] → RedisRequest

const redisRequest = RedisRequest.getrange("hoge", [ 0, 1 ]);
RedisRequest.getset 📕

String → (String|Uint8Array) → RedisRequest

const redisRequestA = RedisRequest.getset("hoge", "piyo");
const redisRequestB = RedisRequest.getset("hoge", encodeText("piyo"));
RedisRequest.incr 📕

String → RedisRequest

const redisRequest = RedisRequest.incr("hoge");
RedisRequest.incrby 📕

String → Number → RedisRequest

const redisRequest = RedisRequest.incrby("hoge", 3);
RedisRequest.incrbyfloat 📕

String → Number → RedisRequest

const redisRequest = RedisRequest.incrbyfloat("hoge", 0.1);
RedisRequest.mget 📕

(...String) → RedisRequest

const redisRequest = RedisRequest.mget("hoge", "piyo");
RedisRequest.mset 📕

(...String) → RedisRequest, or (String|Symbol)[] → Uint8Array → RedisRequest

const redisRequestA = RedisRequest.mset("hoge", "piyo", "hogefuga", "fuga");
const redisRequestB = RedisRequest.mset(
  [ "hoge", $$rawPlaceholder, "hogefuga", $$rawPlaceholder ],
  encodeText("piyo\r\nfuga\r\n")
);
RedisRequest.msetnx 📕

(...String) → RedisRequest, or (String|Symbol)[] → Uint8Array → RedisRequest

const redisRequestA = RedisRequest.msetnx("hoge", "piyo", "hogefuga", "fuga");
const redisRequestB = RedisRequest.msetnx(
  [ "hoge", $$rawPlaceholder, "hogefuga", $$rawPlaceholder ],
  encodeText("piyo\r\nfuga\r\n")
);
RedisRequest.psetex 📕

Number → String → (String|Uint8Array) → RedisRequest

const redisRequestA = RedisRequest.psetex(1000, "hoge", "piyo");
const redisRequestB = RedisRequest.psetex(1000, "hoge", encodeText("piyo"));
RedisRequest.set 📕

Object → String → (String|Uint8Array) → RedisRequest

const redisRequestA = RedisRequest.set({}, "hoge", "piyo");
const redisRequestB = RedisRequest.set({}, "hoge", encodeText("piyo"));
const redisRequestC = RedisRequest.set({ EX: 2000 }, "hoge", encodeText("piyo"));
const redisRequestD = RedisRequest.set({ KEEPTTL: true }, "hoge", encodeText("piyo"));
RedisRequest.setbit 📕

String → Number → Number → RedisRequest

const redisRequest = RedisRequest.setbit("hoge", 7, 1);
RedisRequest.setex 📕

Number → String → (String|Uint8Array) → RedisRequest

const redisRequestA = RedisRequest.setex(10, "hoge", "piyo");
const redisRequestB = RedisRequest.setex(10, "hoge", encodeText("piyo"));
RedisRequest.setnx 📕

String → (String|Uint8Array) → RedisRequest

const redisRequestA = RedisRequest.setnx("hoge", "piyo");
const redisRequestB = RedisRequest.setnx("hoge", encodeText("piyo"));
RedisRequest.setrange 📕

String → Number → (String|Uint8Array) → RedisRequest

const redisRequest = RedisRequest.setrange("hoge", 2, "FU");
RedisRequest.stralgo 📕

(...String) → RedisRequest

const redisRequest = RedisRequest.strlen("LCS", "KEYS, "hoge", "piyo");
RedisRequest.strlen 📕

String → RedisRequest

const redisRequest = RedisRequest.strlen("hoge");
RedisRequest.flushall 📕

() → RedisRequest

const redisRequest = RedisRequest.flushall();

Redis Response

The RedisResponse represents a Redis response. It has only one argument, a typed array named “raw”. The RedisResponse type is mostly interoperable with RedisRequest, Resource, File, (HTTP) Request and, (HTTP) Response.

The RedisResponse type implements the following algebras:

  • Alternative
  • Group
  • Comonad
  • Monad

Example

import RedisResponse from "https://deno.land/x/functional-redis@v0.1.1/library/RedisResponse.js";

const redisResponse = RedisResponse.Success(new Uint8Array([]));

assert(RedisResponse.is(redisResponse));

Utilities

factorizeRedisResponseSuccess

Uint8Array → RedisResponse.Success

factorizeRedisResponseFailure

Uint8Array → RedisResponse.Failure

Client

The client module provides various utility functions to interact with a Redis server.

decodeRedisResponse

RedisResponse → *

This functions takes a RedisResponse and, returns the most appropriate JavaScript primitive. For example, string command’s response would return a string and, hash command’s response would return an array…

parseRedisResponse

RedisResponse → Buffer

This functions takes a RedisResponse and, returns a Buffer which can be interoperated cleanly with RedisRequest, Resource, File and, (HTTP) Request.

connectRedisClient

Object → Task Resource

This function takes an object for the connection options and, return a Task of a Resource.

import { connectRedisClient } from "https://deno.land/x/functional_redis@v0.1.3/library/client.js";

const container = await connectRedisClient({ port: 6379 }).run();
const redisResource = safeExtract("Failed to connect the client.", container);

disconnectRedisClient

Resource → Task Resource

This function takes a Resource and, return a Task of a Resource.

import { disconnectRedisClient } from "https://deno.land/x/functional_redis@v0.1.3/library/client.js";

await disconnectRedisClient(redisResource).run();

executeRedisCommand

RedisRequest → Resource → Task RedisResponse

This curried function accepts a RedisRequest and a Resource that represents a connection to the Redis server and, returns a Task of a RedisResponse.

import { safeExtract } from "https://deno.land/x/functional@v1.3.2/library/utilities.js";
import { executeRedisCommand } from "https://deno.land/x/functional_redis@v0.1.3/library/client.js";
import RedisRequest from "https://deno.land/x/functional_redis@v0.1.3/library/RedisRequest.js";
import RedisResponse from "https://deno.land/x/functional_redis@v0.1.3/library/RedisResponse.js";

const container = await executeRedisCommand(
  RedisRequest.set({}, "hoge", "piyo"),
  redisResource
).run();
const redisResponse = safeExtract("Failed to execute the command..", container);

assert(RedisResponse.is(redisResponse));

executeRedisCommandPipeline

RedisRequest[] → Resource → Task RedisResponse[]

This curried function accepts an array of RedisRequest and, a Resource that represents a connection to the Redis server. The function returns a Task of an array of RedisResponse. Do not confuse this function with pipeRedisCommand; the term “pipeline” refers to the ability of a Redis server to parse multiple request at a time.

import { safeExtract } from "https://deno.land/x/functional@v1.3.2/library/utilities.js";
import { executeRedisCommandPipeline } from "https://deno.land/x/functional_redis@v0.1.3/library/client.js";
import RedisRequest from "https://deno.land/x/functional_redis@v0.1.3/library/RedisRequest.js";
import RedisResponse from "https://deno.land/x/functional_redis@v0.1.3/library/RedisResponse.js";

const container = await executeRedisCommandPipeline(
  [
    RedisRequest.set({}, "hoge", "piyo"),
    RedisRequest.get("hoge")
  ],
  redisResource
).run();
const redisResponseList = safeExtract("Failed to execute the command..", container);

assert(redisResponseList.every(RedisResponse.is));

createRedisSession

(Resource → Task *) → Object → Task Resource

This function takes an unary function that accepts a Resource that represents a connection to the Redis server and, Return a Task.

This functions will sequentially connect to the Redis server, execute the unary function and, finally disconnect.

const setHoge = createRedisSession(executeRedisCommand(RedisRequest.set({}, "hoge", "piyo")));

const container = await setHoge({ port: 6379 }).run();

safeExtract("Failed to read the response.", container);

The function resolves to a Task of the Resource; if you need to access the RedisResponse, the unary function should compose with the handler.

import { safeExtract } from "https://deno.land/x/functional@v1.3.2/library/utilities.js";
import File from "https://deno.land/x/functional_io@v1.1.0/library/File.js";
import { writeFile } from "https://deno.land/x/functional_io@v1.1.0/library/fs.js";
import {
  createRedisSession,
  executeRedisCommand
} from "https://deno.land/x/functional_redis@v0.1.3/library/client.js";
import RedisRequest from "https://deno.land/x/functional_redis@v0.1.3/library/RedisRequest.js";

const writeHogeToFile = createRedisSession(
  compose(
    chain(
      compose(
        writeFile({}),
        concat(File.fromPath(`${Deno.cwd()}/hoge`)),
        parseRedisResponse
      )
    ),
    executeRedisCommand(RedisRequest.get("hoge"))
  )
);

const containerB = await writeHogeToFile({ port: 6379 }).run();

safeExtract("Failed to read the response.", containerB);

pipeRedisCommand

(RedisRequest|(* → RedisRequest))[] → Resource → Task RedisResponse

This curried function accepts an array of RedisRequest or a function that would return a RedisRequest and, a Resource that represents a connection to the Redis server. The return value is a Task of the RedisResponse of the last RedisRequest.

This function will execute all Redis requests sequentially and optionally pipe the previous response into the next request.

import { safeExtract } from "https://deno.land/x/functional@v1.3.2/library/utilities.js";
import {
  createRedisSession,
  pipeRedisCommand
} from "https://deno.land/x/functional_redis@v0.1.3/library/client.js";
import RedisRequest from "https://deno.land/x/functional_redis@v0.1.3/library/RedisRequest.js";

const copyHogeToFuga = createRedisSession(
  compose(
    pipeRedisCommand(
      [
        RedisRequest.set({}, "hoge", "piyo"),
        RedisRequest.get("hoge"),
        RedisRequest.set({}, "fuga")
      ]
    )
  )
);

const container = await copyHogeToFuga({ port: 6379 }).run();

safeExtract("Failed to read the response.", container);

This example works because RedisRequest.set is a curried function that requires 3 arguments and, returns a RedisRequest.

Contributing

We appreciate your help! Please, read the guidelines.

License

MIT License

Copyright © 2020 - Sebastien Filion

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.