blockbid-persistence

Persistence store wrapper

TypeORM library is used to create a wrapper for all the MySQL database operations for now. This library will make it easy to migrate to other databases (Postgres/SQLite/MongoDB etc.) and helps us in seperating the persistence operations from application. This repo is created using the blockbid-tools library and all the configs are standard templates from blockbid-tools.

NOTE: I have added only basic operations and will be enhanced as per the requirements going forward. This library is currently being using in KYC service.

Road map

At a later point this library should support multiple databases.

• MySQL
• Postgres

Environments

• Node

Installation

You can install by referencing a version tag directly off the github repo.

yarn add blockbid/blockbid-persistence#1.x

Framework Usage

This library is using lazy connection approach, Creates the connection on the first request and reuses the same connection for subsequent requests, creates a new connection to database, If connection is unavailable.

In distributed environments connections are identified by connection name provided in the ORM config.

All the CRUD operations returns Promises and hence it helps in chaining the actions.

• Create an Entity as below in the app

NOTE: Entity structure is dependent on app framework. Refer https://github.com/typeorm/javascript-example for javascript implementation

import {Column, Entity, PrimaryColumn} from 'blockbid-persistence';

@Entity()
export default class Sample {

    @PrimaryColumn()
    id: number;

    @Column()
    timestamp: Date;

    @Column('text')
    name: string;

    @Column('simple-json')
    details: JSON;
}

• Define the ORM config and link the entity(s) in the app

import Sample from './entities/Sample';

const ormconfig = {
  database: 'test',
  entities: [Sample],
  host: 'localhost',
  name: 'test',
  password: 'testPassword',
  port: 3306,
  synchronize: true,
  type: 'mysql',
  username: 'testUser'
};

export default ormconfig;

• Add

success: returns Promise with meta data
fail: returns Promise with err (stack trace)

Note: Element passed is a JSON object based on Entity class

import add from 'blockbid-persistence';

add(ormconfig, entity, {columnName: columnValue})

• Find

success: returns Promise with data fetched
fail: returns Promise with err (stack trace)

NOTE: This operation returns only one row from the database. If multiple rows are matched then it returns the first match.

import find from 'blockbid-persistence';

find(ormconfig, entity, primaryKey)

find(ormconfig, entity, {coulmnName: 'columnValue'})

• Update

success: returns Promise with update meta data
fail: returns Promise with err (stack trace)

Note: clause object is expected to have 2 keys, criteria to update and update value.

import update from 'blockbid-persistence';

const clause: {
 criteria: 'primaryKey',
 data: {
    columnName: columnValue
 }
}

update(ormconfig, entity, clause);

• Remove

success: returns Promise with deleted row meta data
fail: returns Promise with err (stack trace)

import remove from 'blockbid-persistence';

remove(ormconfig, entity, primaryKey);

For more details, Refer tests under src/tests directory.

Publishing to private NPM

If it is your first time publishing visit https://npm.blockbid.io

Click Login in the top right and oauth with Github.

It should redirect you to the dashboard. In the middle of the top bar you should see two npm commands. You only need the first one npm config set //npm.blockbid.io/:_authToken "oMOAeXZctRqEu7VUKS0HYHi0yHcIaQkTXRW1mdLJ0FiR7EAcBVKQTtximeMS...

But be careful the browser might be truncating the full command (if you see ...) (We will fix this asap)

In this case, inspect the element and get the full code out of developer tools.

In full it should look like

npm config set //npm.blockbid.io/:_authToken "oMOAeXZctRqEu7VUKS0HYHi0yHcIaQkTXRW1mdLJ0FiR7EAcBVKQTtximeMSL6lQjwIpRSmmy8dZQmokDohmew=="

Run this command in your terminal, afterwards load up ~/.npmrc in your editor

You should see the config from the command you just ran. You will also need to add another line

@Blockbid:registry=https://npm.blockbid.io

This tells NPM to use our private registry when fetching packages that are scoped with @Blockbid

Publish command

Open up a npm module that you have been working on.

Make sure that your package name is prefixed with @Blockbid/

Your package.json should have

"name": "@Blockbid/some-package"

Now to publish

npm publish --registry https://npm.blockbid.io

Do this every time there is a new version.

We will potentially move this to the build server so it happens automatically.

TODOs

• Add all the possible variants of Add, Find, Update, Remove.
• Add query builder option
• Move tests outside of src directory
• Fix Unhandled promise rejection in remove unit test

References

• TypeORM https://github.com/typeorm/typeorm
• https://github.com/typeorm/javascript-example
• https://github.com/typeorm/typescript-example