redis-object-storage v0.2.5

Redis Object Storage

A Node.js object manager for Redis that uses hashes to store, retrieve, update and delete objects.

Inspired by this article by Roshan Kumar at Redis Labs and this discussion on StackOverflow

Uses ioredis as a Redis client (its sole dependency) and does not use ReJSON or any Redis plugins!

Currently in beta! See the example code, implementing a Shopping Cart in Redis using hashes and redis-object-storage

Get started

1. Make sure Redis is installed on your system

2. npm install redis-object-storage

3. Read the docs and example code

What are hashes? How do they work?

Hashes are data types that can be stored in Redis efficiently. Similar to an SQL table or MongoDB document, a hash can represent a certain object type. However in Redis, objects must be simple key value pairs (strings only). This library does not support database relations.

In this library, you can define a schema for your hashes:

class CartItemHash extends StorableHash {
    product: string
    user: string
    name: string
    price: number

    constructor(product: string, user: string, name: string, price: number) {
        super()
        this.product = product
        this.user = user
        this.name = name
        this.price = price
    }
}

And also add some properties for the "tables" to store our hashes:

// cart_items is the name of the table
// price is the indexed integer key
// product, user, name are indexed string keys
const cartItemHashTable = new StorableHashTable('cart_items', ['price'], ['product', 'user', 'name'])

CRUD

With this library, you can create, read, update, delete hashes using hashInsert(), hashUpdate(), hashDelete() respectively.

Creating, updating and deleting will automatically handle column indexes if you setup your table correctly.

When retrieving hashes, the hashParse() function will return JSON (strings only*). For example:

{
    "product": "4a45ae4",
    "user": "9ae14d9",
    "name": "Logitech BRIO",
    "price": "24999"
}

*To remedy this, use compareStorableHashes() to compare your original hash to your retrieved hash.

Indexing?

In addition to hashes, when creating a table you can define which fields are indexed (whether indexed as a string or integer).

Indices for strings and integers are set by using an unordered list. You can query hashes by using string/integer using SINTER, implemented by hashGetByIndexedValues()

Indices for integers are set using an ordered list. This allows you to query on an integer range using ZRANGEBYSCORE, implemented by hashGetByIntegerRange()

Not all fields need to be indexed, however this library does not support scanning, but you can still scan manually with your own Redis client.

Example Redis database

127.0.0.1:6379> keys *
 1) "cart_items.price=9999"
 2) "cart_items:5"
 3) "cart_items.product=2482cda"
 4) "cart_items.price=3499"
 5) "cart_items.name=Logitech G203"
 6) "cart_items.name=Logitech KB"
 7) "cart_items.name=Starbucks Coffee"
 8) "cart_items_list"
 9) "cart_items.user=05995c2"
10) "cart_items.name=Logitech BRIO"
11) "cart_items.product=66a0ebb"
12) "cart_items.price=999"
13) "cart_items.product=4a45ae4"
14) "cart_items.price=24999"
15) "cart_items:7"
16) "cart_items:1"
17) "cart_items_seq"
18) "cart_items.user=9ae14d9"
19) "cart_items:2"
20) "cart_items:6"
21) "cart_items.product=50376e5"
22) "cart_items.price"
23) "cart_items:3"

In this example, we have a table cart_items.

• cart_items:1, cart_items:2, cart_items:3, etc. are stored hashes.
• cart_items.price=9999 is an indexed integer value, stored as an unordered set
• cart_items.name=Logitech KB is an indexed string value, stored as an unordered set
• cart_items.price is an indexed integer column, stored as an ordered set
• cart_items_list is an ordered set of hashes in the table
• cart_items_seq is a sequence that can be implemented to get the next ID for the table

Contributing

If you want to contribute code, please submit a GitHub issue about what you wish to add first.

To run tests, you can run docker-compose up to spin up a Redis container and npm test to run tests.

Please run prettier --write . before submitting a pull request to format the code.

Some ideas:

• Make hashParse() convert integer string keys to number type automatically (requires schema change)
• Contribute more examples (in TypeScript or Javascript)
• Contribute more test cases, using multiple tables
• Submit bug reports

This repo is formerly known as "Redis HashQL" or redis-hashql