herow-redisk

Redisk is a TypeScript ORM library for Redis.

Features:

• Store entities.
• Single relation support.
• Unique keys support.
• Retrieve entities by his primary keys or his unique keys.
• Indexes support.
• List entities with common filters, like limit, count and sort by.
• Find entities with multiple conditions ('>', '<', '=', '!=').
• Search (Similar to LIKE in SQL)
• And much more.

Quick overview

const redisk = Redisk.init({url: 'redis://127.0.0.1:6379/0'});

@Entity('user')
export class User {

  @Primary()
  @Property()
  public readonly id: string;

  @Property()
  public name: string;

  constructor(
      id: string,
      name: string,
    ) {
      this.id = id;
      this.name = name;
  }
}

await redisk.save(new User('::id::', 'Foo'));

console.log(await redisk.getOne(User, '::id::'));

Installation

npm install redisk --save

Contents

• Connection
  • Options
• Models
  • Model definition
  • Entity
  • Property
    • Supported types
  • Primary
  • Unique
  • Embedding other entities
• Queries
  • Save
  • Update
  • Get by primary key
  • Get by unique key
  • Count
  • List all
  • List all with conditions
    • Simple
    • Multiple conditions
  • Pattern matching
  • Delete
• Logging

Connection

const redisk = Redisk.init(options);

Options

Property	Description
url	URL of the Redis server. Format [redis[s]:]//[[user][:password@]][host][:port][/db-number][?db=db-number[&password=bar[&option=value]]]
host	Host of the Redis server
port	Port of the Redis server
db	Number of the db (Default: 0)
password	Password of the Redis server
sentinels	Redis sentinel options (port and host)

Closing connection to Redis:

await redisk.close();

Models

Model definition

@Entity('user')
export class User {

  @Primary()
  @Property()
  public readonly id: string;

  @Property({searchable: true})
  public name: string;

  @Unique()
  @Property()
  public email: string;

  @Property({indexed: true})
  public color: string;

  @HasOne(type => Group, {cascadeInsert: true, cascadeUpdate: true})
  @Property()
  public group: Group;

  @Property({indexed: true})
  public created: Date;

  constructor(
      id: string,
      name: string,
      email: string,
      color: string,
      group: Group,
      created: Date,
    ) {
      this.id = id;
      this.name = name;
      this.email = email;
      this.color = color;
      this.group = group;
      this.created = created;
  }
}

Entity

Use the decorator Entity to convert your class into a Redisk entity.

You can pass the option canBeListed to 'false' (Default is true) to save some space, but you will not be able to list user entities.

@Entity('user', { canBeListed: true })
export class User {
}

Property

The decorator Property is used to save the fields into redis.

Optionally, you can pass the options indexed if you want to use the field to sort or to use as a condition in the 'list' method or searchable if you want to use pattern matching in this field.

You can also set a default value.

Both options are false by default.

@Entity('user')
export class User {

    @Property({indexed: true, searchable: false, defaultValue: 'foo'})
    public readonly created: Date;

}

Supported types

Redisk support multiple types to store and query.

• String
• Date (Will be saved as a timestamp)
• Boolean
• Number

All other types will be converted to a string.

Primary

Primary decorator is used to define the primary key of the entity. It can only be one primary key and his value must be unique for all the same entities.

@Entity('user')
export class User {

  @Primary()
  @Property()
  public readonly id: string;
}

Unique

This decorator is used to make the value of this field unique for all the same entities. Then you can use it to query the entity.

@Entity('user')
export class User {

  @Unique()
  @Property()
  public readonly email: string;
}

Embedding other entities

You can make one to one relations with the HasOne decorator.

Cascade inserts and updates are supported. (These options are false by default)

@Entity('user')
export class User {

  @HasOne(type => Group, {cascadeInsert: true, cascadeUpdate: true})
  @Property()
  public readonly group: Group;
}

Queries

Save

await redisk.save(new User(id, name));

Update

const user = await redisk.getOne(User, id);
user.name = 'Bar';
await redisk.save(user);

Note: Null fields will be removed from the persisted entity, undefined fields will not be modified from persisted entity.

Get by primary key

await redisk.getOne(User, id);

Get by unique key

const value = '[e-mail]';
const uniqueKeyName = 'email';
await redisk.getOne(User, value, uniqueKeyName);

Count

await redisk.count(User);

List all

Returns an array of all user entities.

await redisk.list(User); 

Returns the first 10 user entities

const limit = 10;
const offset = 0;
await redis.list(User, limit, offset);

Return an array of user entities sorted by his creation date in descending order

await redisk.list(User, undefined, undefined, undefined, {
    field: 'created',
    strategy: 'DESC',
});

List all with conditions

Simple

Returns an array of users where his color is red

const where = 
    conditions: [
        {
            key: 'color',
            value: 'red',
            comparator: '=',
        },
    ],
    type: 'AND',
};
await redisk.list(User, where, limit, offset); 

Returns an array of users where his creation date is greater than the day 23

const where = 
    conditions: [
        {
            key: 'created',
            value: new Date('2020-02-23 00:00:00'),
            comparator: '>',
        },
    ],
    type: 'AND',
};
await redisk.list(User, where, limit, offset); 

Multiple conditions

Returns an array of entities that his color field is 'red' or 'blue'.

Warning: Using multiple conditions leads to multiple queries with table intersections, to achieve high performance queries try to reduce the results with more concise conditional.

const where = 
    conditions: [
        {
            key: 'color',
            value: 'red',
            comparator: '=',
        },
        {
            key: 'color',
            value: 'blue',
            comparator: '=',
        },
    ],
    type: 'OR',
};
await redisk.list(User, where, limit, offset);

Returns an array of entities that his color field is 'red' and his food field is 'avocado'

const where = 
    conditions: [
        {
            key: 'color',
            value: 'red',
            comparator: '=',
        },
        {
            key: 'food',
            value: 'avocado',
            comparator: '=',
        },
    ],
    type: 'AND',
};
await redisk.list(User, where, limit, offset);

Pattern matching

You can search entities by properties marked as searchables.

const condition = {
    key: 'name',
    value: 'John',
};
const maxNumberOfResults = 10;
await redisk.search(User, condition, maxNumberOfResults);

Delete

await redisk.delete(User, id);

Logging

We use winston for logging, if you want to see more info, like redis command that are being executed you can set process.env.REDISK_LOG_LEVEL to 'info'.

For example:

REDISK_LOG_LEVEL=info npm test

Stay in touch

• Author - Nytyr
• Website - https://arkerlabs.com/