NPM module - izara-shared

Overview

Shared libraries used across multiple izara projects

Repository

https://bitbucket.org/stb_working/izara-shared/src/master/

CoreSharedLib

constants

• {string} systemTextGraphTag ("systemText")
• {string} systemTextServiceNameGraphTag ("systemTextServiceName")

LambdaSharedLib

Helper functions for interacting with Lambda resources.

LambdaSharedLib.lambdaFunctionName

/**
 * Executes a Get query to DynamoDB
 * @param {string} serviceName
 * @param {string} functionName
 *
 * @returns {string} deployed Lambda service name
 */

• concatenate with env stage setting

DynamodbSharedLib

Helper functions for interacting with DynamoDB resources.

Idempotence

• DynamodbSharedLib functions that have invoke queries with conditional expression can pass in a setting that says whether to throw on conditionalExpression failure
• if for idempotent conditionalExpression error not want to throw, we want to keep processing as if the query passed like normal
• default is to not throw, because in most cases we will be protecting for idempotent processing
• if conditionalExpression is critical, eg not for idemptent test, then we throw, calling code can set whether to throw noRetryError or normal error that will trigger retries, calling code passes in a setting to do this, default is noRetryError

Notes

• could add another setting that waits and retries on certain errors, within the one function call, could also set delay and how many retries
• might not be needed as DynamoDocument library already has built in retry logic, errors might be an edge case that can be handled through normal throw/retry/dlq flow

dynamodbSharedLib.getItem

/**
 * Executes a GetItem query to DynamoDB
 * @param {string} tableName
 * @param {object} keyValues
 * @param {[object]} queryElements // eg returned only some attributes (ProjectionExpression)
 * @param {[object]} settings
 * @param {boolean} settings.errorOnNoRecordFound
 * @param {boolean} settings.retryOnErrorNoRecordFound
 * @returns {object} single record return value from the query, or Null if none found
 */

• return the .Item property
• if record not found Null will be returned unless errorOnNoRecordFound set to true which will throw error

errorOnNoRecordFound

• if set truthy create an error that includes tableName and keyValues
• noRetryError error is thrown unless retryOnErrorNoRecordFound is set truthy, then a normal error is thrown which will trigger retry code

other errors

• other unhandled DynamoDB errors might include Dynamo throttling/failure
• for these we throw a normal error so the request gets retried before passing to DLQ

dynamodbSharedLib.query

/**
 * Executes a Query on DynamoDB
 * @param {string} tableName
 * @param {object} partitionKeyValue
 * @param {[object]} queryElements
 * @param {[object]} queryElements.sortKeyConditions
 * @param {[object]} queryElements.ExclusiveStartKey
 * @param {[object]} settings
 * @param {numeric} settings.numPagesToRequest // not sure will use? Script will automatically request multiple pages of results
 *
 * @returns {object[], object} array of records from .Items in query result, and queryInfo object with properties such as LastEvaluatedKey
 */

errors

• unhandled DynamoDB errors might include Dynamo throttling/failure
• for these we throw a normal error so the request gets retried before passing to DLQ

dynamodbSharedLib.putItem

/**
 * Executes a PutItem query on DynamoDB
 * @param {string} tableName
 * @param {object} keyValues
 * @param {object} attributes
 * @param {[object]} queryElements 
 * @param {[object]} queryElements.conditionalExpressions
 * @param {[object]} settings
 * @param {numeric} settings.errorOnConditionalExpNotPass // if set then an error will be thrown, otherwise function returns with no error
 * @param {numeric} settings.retryOnErrorConditionalExpNotPass
 *
 * @returns {} .. maybe nothing
 */

errorOnConditionalExpNotPass

• if set truthy create an error that includes tableName and keyValues, maybe conditionalExpressions or DynamoDB error if it describes not passing condition/s
• noRetryError error is thrown unless retryOnErrorConditionalExpNotPass is set truthy, then a normal error is thrown which will trigger retry code

other errors

• other unhandled DynamoDB errors might include Dynamo throttling/failure
• for these we throw a normal error so the request gets retried before passing to DLQ

dynamodbSharedLib.updateItem

/**
 * Executes an UpdateItem query on DynamoDB
 * @param {string} tableName
 * @param {object} keyValues
 * @param {object} attributes
 * @param {[object]} queryElements 
 * @param {[object]} queryElements.conditionalExpressions
 * @param {[object]} settings
 * @param {numeric} settings.errorOnConditionalExpNotPass // if set then an error will be thrown, otherwise function returns with no error
 * @param {numeric} settings.retryOnErrorConditionalExpNotPass
 *
 * @returns {} .. maybe nothing
 */

errorOnConditionalExpNotPass

• if set truthy create an error that includes tableName and keyValues, maybe conditionalExpressions or DynamoDB error if it describes not passing condition/s
• noRetryError error is thrown unless retryOnErrorConditionalExpNotPass is set truthy, then a normal error is thrown which will trigger retry code

other errors

• other unhandled DynamoDB errors might include Dynamo throttling/failure
• for these we throw a normal error so the request gets retried before passing to DLQ

dynamodbSharedLib.deleteItem

/**
 * Executes a DeleteItem query on DynamoDB
 * @param {string} tableName
 * @param {object} keyValues
 * @param {[object]} queryElements 
 * @param {[object]} queryElements.conditionalExpressions
 * @param {[object]} settings
 * @param {numeric} settings.errorOnConditionalExpNotPass // if set then an error will be thrown, otherwise function returns with no error
 * @param {numeric} settings.retryOnErrorConditionalExpNotPass
 *
 * @returns {} .. maybe nothing
 */

errorOnConditionalExpNotPass

• if set truthy create an error that includes tableName and keyValues, maybe conditionalExpressions or DynamoDB error if it describes not passing condition/s
• noRetryError error is thrown unless retryOnErrorConditionalExpNotPass is set truthy, then a normal error is thrown which will trigger retry code

other errors

• other unhandled DynamoDB errors might include Dynamo throttling/failure
• for these we throw a normal error so the request gets retried before passing to DLQ

dynamodbSharedLib.createStringSet

/**
 * Creates a string set element for use with documentClient
 * @param {string[]} stringSet
 *
 * @returns {string} String formatted as a string set for Dynamo
 */

ConfigSharedLib

Helper functions for Config tables.

configSharedLib.getConfigValue

/**
 * @param {string} configTag
 * @param {string} configKey
 *
 * @returns {Object} returns the configValue for a single config record, or null if none found
 */

GraphSharedLib

Helper functions for interacting with Neptune graph databases from any service.

constants

• {string} userGraphTag ("user")
• {string} createdByEdgeLabel ("createdBy")
• {string} hasEdgeLabelPrefix ("has_")
• {string} settingsVersionedDataTag ("Settings")
• {string} versionedDataFromPropertyName ("from")
• {string} versionedDataToPropertyName ("to")

graphSharedLib.createVertexId

/**
 * Creates vertexId from vertexTag and unique id
 * @param {string} vertexTag - is the type of object
 * @param {string} vertexUniqueId
 *
 * @returns {string} vertexId
 */

1. Concatenate vertexTag + '_' + vertexUniqueId

graphSharedLib.createEdgeIdFromVertexIds

/**
 * Creates standardized edgeId
 * @param {string} subjectVertexId
 * @param {string} edgeLabel
 * @param {string} [objectVertexId=""]
 *
 * @returns {string} edgeId
 */

1. let edgeid = subjectVertexId + '_' + edgeLabel
2. if(objectVertexId)
   1. edgeid = edgeid + '_' + objectVertexId
3. return edgeid

graphSharedLib.createEdgeIdFromVertexTagsAndUniqueIds

/**
 * Creates standardized edgeId
 * @param {string} subjectVertexTag
 * @param {string} subjectVertexUniqueId
 * @param {string} edgeLabel
 * @param {string} [objectVertexTag=""]
 * @param {string} [objectVertexUniqueId=""]
 *
 * @returns {string} edgeId
 */

1. const subjectVertexId = graphSharedLib.createVertexId
   1. vertexTag = subjectVertexTag
   2. uniqueId = subjectVertexUniqueId
2. let objectVertexId = ""
3. if(objectVertexTag)
   1. objectVertexId = graphSharedLib.createVertexId
      1. vertexTag = objectVertexTag
      2. uniqueId = objectVertexUniqueId
4. return = graphSharedLib.createEdgeIdFromVertexIds
   1. subjectVertexId: subjectVertexId'
   2. edgeLabel: edgeLabel
   3. objectVertexId: objectVertexId

graphSharedLib.createVersionedDataVertexTag

/**
 * Creates standardized versionedDataVertexLabel
 * @param {string} subjectVertexTag
 * @param {string} versionedDataTag
 *
 * @returns {string} versionedDataVertexLabel
 */

1. let versionedDataVertexTag = subjectVertexTag + versionedDataTag
2. return versionedDataVertexTag

graphSharedLib.createVersionedDataEdgeLabel

/**
 * Creates standardized versionedDataEdgeLabel
 * @param {string} ''versionedDataTag''
 *
 * @returns {string} versionedDataEdgeLabel
 */

1. return NPM module - izara-shared#graphSharedLib.hasEdgeLabelPrefix + versionedDataTag

graphSharedLib.getVerticesByVertexLabel

/**
 * Returns all vertices that match the vertex label for the given graph
 * @param {string} graphServiceName
 * @param {string} vertexLabel
 *
 * @returns {string} vertexId
 */

1. ..

graphSharedLib.getVertexByVertexId

/**
 * Returns vertex that matched the vertex id
 * @param {string} graphServiceName
 * @param {string} vertexId
 *
 * @returns {string} vertexId
 */

1. ..

graphSharedLib.getVertexByVertexTagAndVertexUniqueId

/**
 * Returns vertex that matched the vertex id
 * @param {string} graphServiceName
 * @param {string} vertexTag
 * @param {string} vertexUniqueId
 *
 * @returns {object} vertex
 */

1. const vertexId = NPM module - izara-shared#graphSharedLib.createVertexId
   1. vertexTag: vertexTag
   2. vertexUniqueId: vertexUniqueId
2. const vertex = invoke #graphSharedLib.getVertexByVertexId
   1. graphServiceName: graphServiceName
   2. vertexId: vertexId
3. return vertex

graphSharedLib.getVertexOutEdgesByVertexId

/**
 * Returns all edges, allowing label and property filters
 * @param {string} graphServiceName
 * @param {string} subjectVertexId
 * @param {string} [edgeLabel=""]
 * @param {object} [edgeProperties={}]
 *
 * @returns {string} vertexId
 */

1. ..

graphSharedLib.getVertexOutEdgesByVertexTagAndVertexUniqueId

/**
 * Returns all edges, allowing label and property filters
 * @param {string} graphServiceName
 * @param {string} subjectVertexTag
 * @param {string} subjectVertexUniqueId
 * @param {string} [edgeLabel=""]
 * @param {object} [edgeProperties={}]
 *
 * @returns {string} vertexId
 */

1. const vertexId = NPM module - izara-shared#graphSharedLib.createVertexId
   1. vertexTag: subjectVertexTag
   2. vertexUniqueId: subjectVertexUniqueId
2. const edges = invoke #graphSharedLib.getVertexOutEdgesByVertexId
   1. graphServiceName: graphServiceName
   2. vertexId: vertexId
   3. edgeLabel: edgeLabel
   4. edgeProperties: edgeProperties
3. return edges

graphSharedLib.getVertexOutEdgesAndVerticesByVertexId

/**
 * Find related vertices and their connecting edges, including properties, allowing label and property filters
 * @param {string} graphServiceName
 * @param {string} subjectVertexId
 * @param {string} [edgeLabel=""] - edge label to filter edges by
 * @param {object} [edgeProperties={}] - edge properties to filter by, is an array of key > value pairs
 * @param {object} [vertexProperties={}] - object vertex properties to filter by, is an array of key > value pairs
 *
 * @returns {Object[]} array of vertices and the connecting edges
 */

1. ..

graphSharedLib.getVertexOutEdgesAndVerticesByVertexTagAndVertexUniqueId

/**
 * Find related vertices and their connecting edges, including properties, allowing label and property filters
 * @param {string} graphServiceName
 * @param {string} subjectVertexTag
 * @param {string} subjectVertexUniqueId
 * @param {string} [edgeLabel=""] - edge label to filter edges by
 * @param {object} [edgeProperties={}] - edge properties to filter by, is an array of key > value pairs
 * @param {object} [vertexProperties={}] - object vertex properties to filter by, is an array of key > value pairs
 *
 * @returns {Object[]} array of vertices and the connecting edges
 */

1. const vertexId = NPM module - izara-shared#graphSharedLib.createVertexId
   1. vertexTag: subjectVertexTag
   2. vertexUniqueId: subjectVertexUniqueId
2. const vertexAndEdges = invoke #graphSharedLib.getVertexOutEdgesAndVerticesByVertexId
   1. graphServiceName: graphServiceName
   2. vertexId: vertexId
   3. edgeLabel: edgeLabel
   4. edgeProperties: edgeProperties
3. return vertexAndEdges

graphSharedLib.getVertexInEdgesAndVerticesByVertexId

/**
 * Find related vertices and their connecting edges, including properties, allowing label and property filters
 * @param {string} graphServiceName
 * @param {string} objectVertexId
 * @param {string} [edgeLabel=""] - edge label to filter edges by
 * @param {object} [edgeProperties={}] - edge properties to filter by, is an array of key > value pairs
 * @param {object} [vertexProperties={}] - object vertex properties to filter by, is an array of key > value pairs
 *
 * @returns {Object[]} array of vertices and the connecting edges
 */

1. ..

graphSharedLib.getVertexInEdgesAndVerticesByVertexTagAndVertexUniqueId

/**
 * Find related vertices and their connecting edges, including properties, allowing label and property filters
 * @param {string} graphServiceName
 * @param {string} objectVertexTag
 * @param {string} objectVertexUniqueId
 * @param {string} [edgeLabel=""] - edge label to filter edges by
 * @param {object} [edgeProperties={}] - edge properties to filter by, is an array of key > value pairs
 * @param {object} [vertexProperties={}] - object vertex properties to filter by, is an array of key > value pairs
 *
 * @returns {Object[]} array of vertices and the connecting edges
 */

1. const vertexId = NPM module - izara-shared#graphSharedLib.createVertexId
   1. vertexTag: objectVertexTag
   2. vertexUniqueId: objectVertexUniqueId
2. const vertexAndEdges = invoke #graphSharedLib.getVertexOutEdgesAndVerticesByVertexId
   1. graphServiceName: graphServiceName
   2. vertexId: vertexId
   3. edgeLabel: edgeLabel
   4. edgeProperties: edgeProperties
3. return vertexAndEdges

graphSharedLib.getObjectVertexByEdgeId

/**
 * Find the object/target vertex for a specific edgeId
 * @param {string} graphServiceName
 * @param {string} edgeId - edge label to filter edges by
 *
 * @returns {Object} vertex or null if not found
 */

1. ..

graphSharedLib.getEdgeAndSubjectAndObjectByEdgeId

/**
 * Returns vertex that matched the vertex id
 * @param {string} graphServiceName
 * @param {string} edgeId
 *
 * @returns {object} edge/subject/object vertices
 */

1. ..

graphSharedLib.getCurrentVersionedDataByVertexId

/**
 * @param {string} graphServiceName
 * @param {string} vertexId
 * @param {string} versionedDataTag
 *
 * @returns {Object} versionedData object
 */

1. .. needs to filter edge by currently active versioned data..
2. ... work through queries to get the current versioned data

1. // will need versionedDataEdgeLabel to find edges that are versioned data
2. const versionedDataEdgeLabel = #createVersionedDataEdgeLabel
   1. versionedDataTag: versionedDataTag

graphSharedLib.getCurrentVersionedDataByVertexTagAndVertexUniqueId

/**
 * @param {string} graphServiceName
 * @param {string} vertexTag
 * @param {string} vertexUniqueId
 * @param {string} versionedDataTag
 *
 * @returns {string} versionedData object
 */

1. const vertexId = NPM module - izara-shared#graphSharedLib.createVertexId
   1. vertexTag: vertexTag
   2. vertexUniqueId: vertexUniqueId
2. const versionedDataVertexTag = #graphSharedLib.getCurrentVersionedDataByVertexId
   1. graphServiceName: graphServiceName
   2. vertexId: vertexId
   3. versionedDataTag: versionedDataTag

MsgCfgSharedLib

Helper functions for interacting with Message Configs

MsgCfgLib.createMsgConfigId

/**
 * 
 * @param {string} serviceName
 * @param {string} topicName
 *
 * @returns {string} msgCfgId
 */

• concatenate {serviceName} + "_" + {topicName}

MsgCfgLib.explodeMsgConfigId

/**
 * 
 * @param {string} msgCfgId
 *
 * @returns {string[]} serviceName, topicName
 */

AwsSharedLib

Generic functions for AWS

AwsSharedLib.getResourceNameFromArn

/**
 * 
 * @param {string} arn
 * @param {string} serviceName
 *
 * @returns {string} resourceName
 */

• invoke AwsSharedLib.explodeArn to get fullResourceName
• remove serviceName and env.iz_stage to from fullResourceName to return basic resourceName

AwsSharedLib.explodeArn

/**
 * 
 * @param {string} arn
 *
 * @returns {object} arnElements
 */

• explodes the arn and returns the different elements
• currently only need arnElements.fullResourceName

Working documents

Working_documents - NPM module - izara-shared