@openstfoundation/openst-base v0.9.2

OpenST Base - Collection of Utilities & Helpers used by OpenST network

While OpenST 0.9 is available as-is for anyone to use, we caution that this is early stage software and under heavy ongoing development and improvement. Please report bugs and suggested improvements.

Install OpenST Base

npm install @openstfoundation/openst-base --save

OSTWeb3 Usage

const OSTBase    = require('@openstfoundation/openst-base')
    , wsEndPoint = "ws://127.0.0.1:8546"
    , httpEndPoint = "http://127.0.0.1:8545"
;

// The below instance of web3 uses OstWSProvider.
// OstWSProvider automatically tries to reconnect when connection is broken.
let wsWeb3 = new OSTBase.OSTWeb3( wsEndPoint );

// The below instance is same as new Web3( httpEndPoint );
let httpWeb3 = new OSTBase.OSTWeb3( httpEndPoint );

PromiseQueueManager Usage

const OSTBase = require('@openstfoundation/openst-base')
    , logger  = new OSTBase.Logger("my_module_name")
;

const queueManagerOptions = {
  // Specify the name for easy identification in logs.
  name: "my_module_name_promise_queue"

  // resolvePromiseOnTimeout :: set this flag to false if you need custom handling.
  // By Default, the manager will neither resolve nor reject the Promise on time out.
  , resolvePromiseOnTimeout: false
  // The value to be passed to resolve when the Promise has timedout.
  , resolvedValueOnTimeout: null

  // rejectPromiseOnTimeout :: set this flag to true if you need custom handling.
  , rejectPromiseOnTimeout : false

  //  Pass timeoutInMilliSecs in options to set the timeout.
  //  If less than or equal to zero, timeout will not be observed.
  , timeoutInMilliSecs: 5000

  //  Pass maxZombieCount in options to set the max acceptable zombie count.
  //  When this zombie promise count reaches this limit, onMaxZombieCountReached will be triggered.
  //  If less than or equal to zero, onMaxZombieCountReached callback will not triggered.
  , maxZombieCount: 0

  //  Pass logInfoTimeInterval in options to log queue healthcheck information.
  //  If less than or equal to zero, healthcheck will not be logged.
  , logInfoTimeInterval : 0


  , onPromiseResolved: function ( resolvedValue, promiseContext ) {
    //onPromiseResolved will be executed when the any promise is resolved.
    //This callback method should be set by instance creator.
    //It can be set using options parameter in constructor.
    const oThis = this;

    logger.log(oThis.name, " :: a promise has been resolved. resolvedValue:", resolvedValue);
  }

  , onPromiseRejected: function ( rejectReason, promiseContext ) {
    //onPromiseRejected will be executed when the any promise is timedout.
    //This callback method should be set by instance creator.
    //It can be set using options parameter in constructor.
    const oThis = this;

    logger.log(oThis.name, " :: a promise has been rejected. rejectReason: ", rejectReason);
  }

  , onPromiseTimedout: function ( promiseContext ) {
    //onPromiseTimedout will be executed when the any promise is timedout.
    //This callback method should be set by instance creator.
    //It can be set using options parameter in constructor.
    const oThis = this;

    logger.log(oThis.name, ":: a promise has timed out.", promiseContext.executorParams);
  }

  , onMaxZombieCountReached: function () {
    //onMaxZombieCountReached will be executed when maxZombieCount >= 0 && current zombie count (oThis.zombieCount) >= maxZombieCount.
    //This callback method should be set by instance creator.
    //It can be set using options parameter in constructor.
    const oThis = this;

    logger.log(oThis.name, ":: maxZombieCount reached.");

  }

  , onPromiseCompleted: function ( promiseContext ) {
    //onPromiseCompleted will be executed when the any promise is removed from pendingPromise queue.
    //This callback method should be set by instance creator.
    //It can be set using options parameter in constructor.
    const oThis = this;

    logger.log(oThis.name, ":: a promise has been completed.");
  }  
  , onAllPromisesCompleted: function () {
    //onAllPromisesCompleted will be executed when the last promise in pendingPromise is resolved/rejected.
    //This callback method should be set by instance creator.
    //It can be set using options parameter in constructor.
    //Ideally, you should set this inside SIGINT/SIGTERM handlers.

    logger.log("Examples.allResolve :: onAllPromisesCompleted triggered");
    manager.logInfo();
  }
};


const promiseExecutor = function ( resolve, reject, params, promiseContext ) {
  //promiseExecutor
  setTimeout(function () {
    resolve( params.cnt ); // Try different things here.
  }, 1000);
}

const manager = new OSTBase.OSTPromise.QueueManager( promiseExecutor, queueManagerOptions);

for( var cnt = 0; cnt < 50; cnt++ ) {
  manager.createPromise( {"cnt": (cnt + 1) } );
}

OpenST Logger Usage

const OSTBase = require('@openstfoundation/openst-base')
    , Logger  = OSTBase.Logger
    , logger  = new Logger("my_module_name", Logger.LOG_LEVELS.TRACE)
;

//Log Level FATAL 
logger.notify("notify called");

//Log Level ERROR
logger.error("error called");

//Log Level WARN
logger.warn("warn called");

//Log Level INFO
logger.info("info Invoked");
logger.step("step Invoked");
logger.win("win called");

//Log Level DEBUG
logger.log("log called");
logger.debug("debug called");
logger.dir({ l1: { l2 : { l3Val: "val3", l3: { l4Val: { val: "val"  }}} }});

//Log Level TRACE
logger.trace("trace called");

All methods will be available for use irrespcetive of configured log level. Log Level only controls what needs to be logged.

Method to Log Level Map

OpenST response formatter usage

const rootPrefix = '.'
    , paramErrorConfig = require(rootPrefix + '/tests/mocha/lib/formatter/param_error_config')
    , apiErrorConfig = require(rootPrefix + '/tests/mocha/lib/formatter/api_error_config')
;

const OSTCore = require('@openstfoundation/openst-base')
    , ResponseHelper  = OSTCore.responseHelper
    , responseHelper = new ResponseHelper({
      moduleName: 'companyRestFulApi'
    });
    
    //using error function
    responseHelper.error({
        internal_error_identifier: 's_vt_1', 
        api_error_identifier: 'test_1',
        debug_options: {client_id: 1234},
        error_config: {
                param_error_config: paramErrorConfig,
                api_error_config: apiErrorConfig   
              }
    });
    
    //using paramValidationError function
    responseHelper.paramValidationError({
        internal_error_identifier:"s_vt_2", 
        api_error_identifier: "test_1", 
        params_error_identifiers: ["user_name_inappropriate"], 
        debug_options: {client_id: 1234},
        error_config: {
            param_error_config: paramErrorConfig,
            api_error_config: apiErrorConfig   
          }
    });
    
    // Result object is returned from responseHelper method invocations above, we can chain several methods as shown below
        
    responseHelper.error({
        internal_error_identifier: 's_vt_1', 
        api_error_identifier: 'invalid_api_params',
        debug_options: {client_id: 1234},
        error_config: {
            param_error_config: paramErrorConfig,
            api_error_config: apiErrorConfig   
          }
    }).isSuccess();
    
    responseHelper.error({
        internal_error_identifier: 's_vt_1', 
        api_error_identifier: 'invalid_api_params',
        debug_options: {client_id: 1234},
        error_config: {
            param_error_config: paramErrorConfig,
            api_error_config: apiErrorConfig   
          }
    }).isFailure();
    
    responseHelper.error({
        internal_error_identifier: 's_vt_1', 
        api_error_identifier: 'invalid_api_params',
        debug_options: {client_id: 1234},
        error_config: {
            param_error_config: paramErrorConfig,
            api_error_config: apiErrorConfig   
          }
    }).toHash();
   
    

OpenST Dynamodb Services

For Parametes description refer - https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/DynamoDB.html

const OSTBase = require('@openstfoundation/openst-base')
    , DynamodbApiObject  = new OSTBase.Dynamodb(DynamodbConnectionParams)
   ;
    
    //Create Dynamodb Table
    DynamodbApiObject.DynamodbApiObject(createTableParams);
    
    // Create Table Migration
    // 1. Creates table
    // 2. Enables ContinuousBackup 
    // 3. Enables read/write auto scaling
    // 4. Returns describe table response 
    DynamodbApiObject.createTableMigration(createTableMigrationParams);
    
    // Update Dynamodb Table
    DynamodbApiObject.updateTable(updateTableParams)
    
    // Describe Dynamodb Table 
    DynamodbApiObject.describeTable(describeTableParams)
    
    // List Dynamodb Tables
    DynamodbApiObject.describeTable(listTableParams)
    
    // Point in time recovery for Dynamodb Table
    DynamodbApiObject.updateContinuousBackup(updateConitnousParams)
    
    // Delete Dynamodb table
    DynamodbApiObject.deleteTable(deleteTableParams)
    
    // Batch Get Items
    DynamodbApiObject.batchGet(batchGetParams)
    
    // Batch Write Items
    DynamodbApiObject.batchWrite(batchWriteParams)
    
    // Query Items
    DynamodbApiObject.query(queryParams)
    
    // Scan Items
    DynamodbApiObject.scan(queryParams)
    
    // Put Items
    DynamodbApiObject.putItem(putItemParams)
    
    // Update an Item
    DynamodbApiObject.updateItem(updateItemParams)
    
    // Delete Items
    DynamodbApiObject.deleteItem(deleteItemParams)
    
    // Check if table exists using wait for method
    DynamodbApiObject.tableExistsUsingWaitFor(tableExistsParams)
    
    // Check if table doesn't exists using wait for method
    DynamodbApiObject.tableNotExistsUsingWaitFor(tableNotExistsParams)
    
    // Check if table exist in ACTIVE state using describe table method
    // If table is being created, then response will be false
    DynamodbApiObject.checkTableExist(tableExistParams)
    

OpenST Shard Management Services

const OSTBase = require('@openstfoundation/openst-base')
    , DynamodbApiObject  = new OSTBase.Dynamodb(DynamodbConnectionParams)
    , ShardManagementObject = DynamodbApiObject.shardManagement()
   ;
    
    // Run Shard Migration
    // Created available_shards and managed_shards table
    ShardManagementObject.runShardMigration(dynamoDbObject, autoScaleObj);
    
    // Add Shard
    // Creates item in available_shards table
    ShardManagementObject.addShard(addShardParams);
    
    // Configure Shard
    // Configure Enable/Disable allocation type
    ShardManagementObject.configureShard(configureShardParams);
    
    // Get Shards By Different Types
    // Type Values : all/enabled/disabled
    ShardManagementObject.getShardsByType(getShardsByTypeParams);
    
    // Does this shard exist in available_shards table
    ShardManagementObject.hasShard(hasShardParams);
    
    // Assign Shard to an identifier
    // Creates entry in managed_shards table
    ShardManagementObject.assignShard(assignShardParams);
    
    // Get Managed shards
    ShardManagementObject.getManagedShard(managedShardParams);
    

OpenST Auto Scaling Services

For Parametes description refer - https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/ApplicationAutoScaling.html

const OSTBase = require('@openstfoundation/openst-base')
    , AutoScalingObject  = new OSTBase.AutoScaling(AutoScalingConnectionParams)
   ;
    
    // Registers or updates a scalable target.  scalable target is a resource that Application Auto Scaling can scale out or scale in. After you have registered a scalable target, you can use this operation to update the minimum and maximum values for its scalable dimension.
    AutoScalingObject.registerScalableTarget(registerScalableTargetParams);
    
    // Creates or updates a policy for an Application Auto Scaling scalable target
    AutoScalingObject.putScalingPolicy(putScalingPolicyParams);
    
    // Deletes the specified Application Auto Scaling scaling policy
    AutoScalingObject.deleteScalingPolicy(deletecalingPolicyParams);
    
    // Deregistering a scalable target deletes the scaling policies that are associated with it.
    AutoScalingObject.deregisterScalableTarget(deregisterScalableTargetParams);
      
    // Gets information about the scalable targets in the specified namespace. 
    AutoScalingObject.describeScalableTargets(describeScalableTargetsParams); 
   
   // Describes the scaling policies for the specified service namespace.
    AutoScalingObject.describeScalingPolicies(describeScalingPoliciesParams);