Metronom is user friendly Redis ORM based on node-redis

You can save, read, update, filter, delete and bulk operations JavaScript objects in Redis without needing to know Redis commands.

It is used effortlessly without installing any plugins like RedisJSON. The system works with Hashes. It shreds the objects and saves them as key strings in the hash, and while reading, they break it down again according to the given scheme and type conversion with TypeScript. Also you can use String Data type too.

Although currently only Hash and String types are processed, our new version that will support all core types is on the way.

| Documentation | Source Code | Package | | ------- | ----------- | ------- | | anchovycation.github.io/metronom | GitHub | npm |

Let's start

1. Install metronom

Firstly, install this package to your project via your package manager.

npm:

npm i metronom

yarn:

yarn add metronom

2. Create Metronom object

The Metronom object is create Model with your defined options like port, host, url or ttl. This step is not required but recomended because at the unnormal usage scenario(you need to use diffirent url from default redis ...) you must to pass that options to all Model defines otherwise Metronom object do it automatically.

import { Metronom } from 'metronom';

const metronom = new Metronom({
  redisClientOptions: {
    host: '172.168.1.123',
    port: 1234
  }
});

2.1 Get/Set String Key

Now, you can get/set key from defined metronom object

  const isSuccess = await metronom.setKey('foo', 'bar'); // its return "OK"
  const value = await metronom.getKey('foo'); // bar

3. Define Model

Model is redis hash maper. It has two diffirent flow.

• flex: you don't need to define schema. All hash keys dynamically mapped
• schema based: You define type, default value etc. in to the schema and metronom use it read/write operations. Keys not found in the schema are ignored.

const userModel = metronom.define(
// const userModel = new Model(
  schema, redisKeyPrefix, modelOptions
);

4. Use model's query inferface

Now, you can use all metronom queries(Metronom, Model and ModelInstance) like Model.create, Model.findById, Model.destroy, ModelInstance.save, etc. .

Start coding the project that will save the world :)

For example:

const { Metronom, Model, Types, LogLevels } = require('metronom');

const metronom = new Metronom({
  redisClientOptions: {
    host: '172.168.1.123',
    port: 1234
  },
  log: LogLevels.Error
});

const userModel = metronom.define(
// const userModel = new Model(
  {
    name: {
      type: Types.String,
    },
    surname: {
      type: Types.String,
    },
    age: {
      type: Types.Number,
      default: 1
    },
    isAdmin: {
      type: Types.Boolean,
      dafeult: false,
    }
  },
  'users', // default `object`
  { 
    keyUnique: 'name', // if you don't define, we use unix timestamp for `keyUniqe` value
    log: LogLevels.All, // default is `None`
    // set `flexSchema` to true and never define schema
  }
);

let user = await userModel.create({
  name: 'Chandler',
  surname: 'Bing',
  age: 18,
});
// Redis key - 'users:Chandler'
// {
//  name: 'Chandler',
//  surname: 'Bing',
//  age: 18,
//  isAdmin: false
// }

user.isAdmin = true;
await user.save();

let admin = userModel.findById('Chandler');
// {
//  name: 'Chandler',
//  surname: 'Bing',
//  age: 18,
//  isAdmin: true
// }

// del users:Chandler
await admin.destroy();

Commands

Metronom Basic

Metronom object is main and static operator object which Model creator and non-hash type operator.

const metronom = new Metronom({
  redisClientOptions: {
    url: 'redis://localhost:6380',
    // host: '172.168.1.123',
    // port: 1234
  }
});

Configs

Paramaters:

All keys in to the one object

| Key | Type | Default Value | | --- | ---- | ------------- | | redisClientOptions | RedisClientOptions object | undefined | | log | boolean LogLevels | false |

define

It create Model from this Metronom options. For detail go to Model Basics

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | schema | Schema | | | key prefix | string | objects | | model options | ModelOptions | undefined |

    const tokenModel = await metronom.define({}, 'tokens', { flexSchema: true });

setKey

Set String key

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | key | string | | | value | string | |

  const isOk = await metronom.setKey('foo', 'bar'); // OK

getKey

Get String key

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | key | string | |

  // await metronom.setKey('foo', 'bar');
  const value = await metronom.getKey('foo'); // bar

Model Basics

Represents the Redis object you created in your database. You can create, read, update, delete, filter operations. It also includes system information.

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | schema | Schema | | | key prefix | string | objects | | model options | ModelOptions | undefined |

// create user model
// new Model(<model-schema>, <redis-key-prefix>, <model-options>)
const userModel = new Model(
  {
    name: {
      type: Types.String,
      default: 'Joe',
    },
    surname: {
      type: Types.String,
    },
    age: {
      type: Types.Number,
      default: 1,
    },
    isAdmin: {
      type: Types.Boolean,
      default: false,
    },
  },
  'users', // default `object`
  {
    keyUnique: 'name', // if you don't define, we use unix timestamp for `keyUniqe` value
    // set `flexSchema` to true and never define schema
    // you can set custom `redisClientOptions` here
  }
);

// const tokenModel = new Model({}, 'tokens', {isFlex: true});

CREATE Methods

create

Creates ModelInstance by parameter then saves it to Redis and returns it.

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | data | object | {} |

// create user
// create(<value-object>)
const user = await userModel.create({ name: "Beyza", surname: "Erkan" });
// { 
//   firstName: "Beyza",
//   lastName: "Erkan",
//   age: 1,
//   isAdmin: false,
//   _Model: {
//     _model: [Model Object],
//     _dataInfo: {
//       redisKey: 'users:Beyza'
//     }
//   }
// }

READ Methods

findById

Fetches record by keyUnique . Returns ModelInstance or null.

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | key unique | number string | |

// find user with id
// findById(<id>)
user = await userModel.findById(user.name);
console.log({ user: user.getPureData() });

getAll

Fetches all records with the same keyPrefix value. Returns list of ModelInstance.

Paramaters:

All keys in to the one object

| Key | Type | Default Value | | --- | ---- | ------------- | | limit | number | undefined |

// find all users
let users = await userModel.getAll();
console.log({ users });

filter

Filters in the same way as Array.filter, pulling all records with the same keyPrefix value. Returns filtred ModelInstances or empty array.

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | filter function | FilterFunction | |

// filters users by condition
// filter(filter-function)
// filter function takes the values  (value, index, array) and returns  `true`  then the record is filtered. It can be asynchronous function
let users = await  userModel.filter((user) =>  user.age > 18);
console.log({ users })

DELETE Methods

deleteById

Delete record by keyUnique. Returns deleted records count it always '1' if it succesfull.

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | key unique | number string | |

// delete user with id
// deleteById(<id>)
let isDeleted = await userModel.deleteById(user.name);
console.log({ isDeleted });

deleteAll

Delete all records with the same keyPrefix value. Returns deleted records count or 0.

// delete all users
await userModel.deleteAll();

Other Methods

runCommand

Redis command executer.

Paramaters: | paramater | Type | Default Value | | --- | ---- | ------------- | | command array | array | |

// runCommand(<commands>)
userModel.runCommand(['hget', 'user:1234', 'name'])

ModelInstance Basics

It is the object from the Redis. You can directly process on the record then save or destroy it.

UPDATE Methods

save

Saves the current state of the object to Redis.

// update user and save
let user = await userModel.create({ name: "Beyza", surname: "Erkan" });
user.age = 20;
await user.save();

DELETE Methods

destroy

Destroy the object from Redis. Returns true or false that it has been deleted.

// destroy this user object
await  user.destroy();

OTHER Methods

getPureData

Clears all metronom-related data within the object and restores it to its raw state. Returns raw data.

// get raw data of user
user = await  userModel.findById(user.name);
console.log({ user:  user.getPureData() });

toJSON

Converts the object to JSON. Returns stringified object.

// convert the user object to JSON
user = await  userModel.findById(user.name);
console.log({ user: user.toJSON() });

Contributors

License

GNU GENERAL PUBLIC LICENSE Version 3