Poetry

Out-of-the-box framework for NodeJS Microservices

Edito

Todo

CLI

Todo

API

Web routing (hapi)

Poetry.route(object routeOptions, function handler)

Register a new route handled by the MicroService. The routeOptions are used by the web server (HAPI) to route HTTP(s) requests to the handler function. They can contain :

• path (required)
• method
• vhost
• config
  • description
  • notes
  • tags
  • payload
  • validation
  • …

Everything's given to the local microservice HAPI web server, and sent for registration to the Web Gateway. If more than one microservice listen the same route, they will be equally balanced.

ORM (Promised Mongo)

Collection

#####db.collection.aggregate([pipeline], callback)

#####db.collection.count([query], callback)

#####db.collection.createIndex(keys, options, [callback])

#####db.collection.distinct(field, query, callback)

#####db.collection.drop([callback])

#####db.collection.dropIndex(index, [callback])

#####db.collection.dropIndexes([callback])

#####db.collection.ensureIndex(keys, options, [callback])

#####db.collection.find([criteria], [projection], [callback])

This function applies a query to a collection. You can get the return value, which is a cursor, or pass a callback as the last parameter. Said callback receives (err, documents)

#####db.collection.findOne([criteria], [projection], callback)

Apply a query and get one single document passed as a callback. The callback receives (err, document)

#####db.collection.findAndModify(document, callback)

#####db.collection.getIndexes(callback)

#####db.collection.group(document, callback)

#####db.collection.insert(docOrDocs, callback)

#####db.collection.isCapped(callback)

#####db.collection.mapReduce(map, reduce, options, callback)

#####db.collection.reIndex(callback)

#####db.collection.remove(query, [justOne], [callback])

#####db.collection.runCommand(command, callback)

#####db.collection.save(doc, callback)

#####db.collection.stats(callback)

#####db.collection.update(query, update, [options], callback)

Cursor

#####cursor.batchSize(size, [callback])

#####cursor.count(callback)

#####cursor.explain(callback)

#####cursor.forEach(function)

#####cursor.limit(n, [callback])

#####cursor.map(function, [callback])

#####cursor.next(callback)

#####cursor.skip(n, [callback])

#####cursor.sort(sortOptions, [callback])

#####cursor.toArray(callback)

Logging (winston)

Poetry.log.silly(... message)

Poetry.log.debug(... message)

Poetry.log.verbose(... message)

Poetry.log.info(... message)

Poetry.log.warn(... message)

Poetry.log.error(... message)

Poetry.log(... message)

Alias for Poetry.log.debug().

Event messaging

Poetry.emit(string eventName, object message)

Poetry.on(string eventName, object pattern, function callback)

Poetry.emit AND Poetry.on use MODE.kafka and MODE.db, MODE.kafka replace for evenName ":" by "-"

Storage API Usage

The Storage API is accessible by importing @iotfactory/poetry/storage:

import { getModel, useAssets, useSites, toObjectId } from '@iotfactory/poetry/storage';

Getting a MongoDB Collection

Use the getModel method to access a MongoDB collection by name:

const collection = getModel('assets');

"use" Methods

These helper methods return a MongoDB collection for a specific entity:

• useAgents
• useAssets
• useAssetTypes
• useContacts
• useDevices
• useGroups
• useSharedDevices
• useSites
• useSmartdevices
• useStaticlists
• useSvgs
• useTeams
• useTeamsettings
• useUserGoups
• useUsers
• useSmartmeasurements
• usePlannings
• useMeasurementsTs
• useStaticlistValues

Example usage:

const assets = useAssets();
const sites = useSites();

useSmartmeasurements

The useSmartmeasurements method returns a MongoDB collection for smart measurements.
You can optionally pass a SmartmeasurementAggregation argument to specify the aggregation level for the collection.

Signature:

useSmartmeasurements(aggr?: SmartmeasurementAggregation): Collection<ISmartmeasurement>

SmartmeasurementAggregation

SmartmeasurementAggregation is a type that specifies the aggregation level for smart measurements.
It can be one of the following string values:

• 'dailys'
• 'hourlys'
• 'monthlys'
• 'quarthourlys'
• 'weeklys'
• 'yearlys'

Example usage:

// Get smart measurements collection (no aggregation)
const smartmeasurements = useSmartmeasurements();

// Get smart measurements aggregated by day
const dailySmartmeasurements = useSmartmeasurements('dailys');

// Get smart measurements aggregated by month
const monthlySmartmeasurements = useSmartmeasurements('monthlys');

Converting to ObjectId

Use the toObjectId method to convert a string to a MongoDB ObjectId:

const id = toObjectId('507f1f77bcf86cd799439011');

aggregation

The aggregation method runs an aggregation pipeline on a MongoDB collection.
It uses default options (allowDiskUse: true, cursor: {}) and merges any additional options you provide.

Signature:

aggregation<T extends Document = Document>(
  collection: Collection<T>,
  options?: AggregateOptions & Abortable
): AggregationCursor<T>

• collection: The MongoDB collection to aggregate.
• options: (Optional) Additional aggregation options (such as allowDiskUse, maxTimeMS, etc).

Example usage:

const cursor = aggregation(myCollection, { allowDiskUse: true, maxTimeMS: 1000 });
for await (const doc of cursor) {
  // process doc
}