I’ve been dealing with CQRS, event-sourcing and DDD long enough now that I don’t need working with it anymore unfortunately, so at least for now this my formal farewell!
I want to thank everyone who has contributed in one way or another. Especially...
- Jan, who introduced me to this topic.
- Dimitar, one of the last bigger contributors and maintainer.
- My last employer, who gave me the possibility to use all these CQRS modules in a big Cloud-System.
- My family and friends, who very often came up short.
Finally, I would like to thank Golo Roden, who was there very early at the beginning of my CQRS/ES/DDD journey and is now here again to take over these modules.
Golo Roden is the founder, CTO and managing director of the native web, a company specializing in native web technologies. Among other things, he also teaches CQRS/ES/DDD etc. and based on his vast knowledge, he brought wolkenkit to life. wolkenkit is a CQRS and event-sourcing framework based on Node.js. It empowers you to build and run scalable distributed web and cloud services that process and store streams of domain events.
With this step, I can focus more on i18next, locize and localistars. I'm happy about that. 😊
So, there is no end, but the start of a new phase for my CQRS modules. 😉
I wish you all good luck on your journey.
Who knows, maybe we'll meet again in a github issue or PR at i18next 😉
Node-cqrs-domain is a node.js module based on node-eventstore. It can be very useful as domain component if you work with (d)ddd, cqrs, eventdenormalizer, host, etc.
Table of Contents
- Workflow
- Installation
- Usage
- Using factory methods for event store or / and aggregate lock in domain definition
- Exposed errors
- Catch connect ad disconnect events
- Define the command structure
- Define the event structure
- Define the id generator function [optional]
- Define the aggregate id generator function [optional]
- Wire up events [optional]
- Initialization
- Handling a command
- Request domain information
- Components definition
- License
│
cmd
│
∨
╔════════════╗
║ validation ║─────────> "rejected"
╚════════════╝
│
cmd
│
∨
╔═════════════════════╗
║ pre-load-conditions ║─────> "rejected"
╚═════════════════════╝
│
cmd
│
∨
╔════════════════╗
║ pre-conditions ║─────> "rejected"
╚════════════════╝
│
cmd
│
∨
╔════════════╗
║ handle cmd ║
╚════════════╝
│
evt
│
∨
╔═══════════╗
║ apply evt ║
╚═══════════╝
│
│
│
∨
╔════════════════╗
║ business rules ║─────> "rejected"
╚════════════════╝
│
│
│
∨
╔════════╗
║ commit ║
╚════════╝
npm install cqrs-domain
var domain = require('cqrs-domain')({
// the path to the "working directory"
// can be structured like
// [set 1](https://github.com/adrai/node-cqrs-domain/tree/master/test/integration/fixture/set1) or
// [set 2](https://github.com/adrai/node-cqrs-domain/tree/master/test/integration/fixture/set2)
domainPath: '/path/to/my/files',
// optional, default is 'commandRejected'
// will be used if an error occurs and an event should be generated
commandRejectedEventName: 'rejectedCommand',
// optional, default is 800
// if using in scaled systems and not guaranteeing that each command for an aggregate instance
// dispatches to the same worker process, this module tries to catch the concurrency issues and
// retries to handle the command after a timeout between 0 and the defined value
retryOnConcurrencyTimeout: 1000,
// optional, default is 100
// global snapshot threshold value for all aggregates
// defines the amount of loaded events, if there are more events to load, it will do a snapshot, so next loading is faster
// an individual snapshot threshold defining algorithm can be defined per aggregate (scroll down)
snapshotThreshold: 1000,
// optional, default is in-memory
// currently supports: mongodb, redis, tingodb, azuretable and inmemory
// hint: [eventstore](https://github.com/adrai/node-eventstore#provide-implementation-for-storage)
eventStore: {
type: 'mongodb',
host: 'localhost', // optional
port: 27017, // optional
dbName: 'domain', // optional
eventsCollectionName: 'events', // optional
snapshotsCollectionName: 'snapshots', // optional
transactionsCollectionName: 'transactions', // optional
timeout: 10000 // optional
// authSource: 'authedicationDatabase', // optional
// username: 'technicalDbUser', // optional
// password: 'secret' // optional
// url: 'mongodb://user:pass@host:port/db?opts // optional
},
// optional, default is in-memory
// currently supports: mongodb, redis, tingodb, couchdb, azuretable, dynamodb and inmemory
// hint settings like: [eventstore](https://github.com/adrai/node-eventstore#provide-implementation-for-storage)
aggregateLock: {
type: 'redis',
host: 'localhost', // optional
port: 6379, // optional
db: 0, // optional
prefix: 'domain_aggregate_lock', // optional
timeout: 10000 // optional
// password: 'secret' // optional
},
// optional, default is not set
// checks if command was already seen in the last time -> ttl
// currently supports: mongodb, redis, tingodb and inmemory
// hint settings like: [eventstore](https://github.com/adrai/node-eventstore#provide-implementation-for-storage)
deduplication: {
type: 'redis',
ttl: 1000 * 60 * 60 * 1, // 1 hour // optional
host: 'localhost', // optional
port: 6379, // optional
db: 0, // optional
prefix: 'domain_aggregate_lock', // optional
timeout: 10000 // optional
// password: 'secret' // optional
},
// optional, default false
// resolves valid file types from loader extensions instead of default values while parsing definition files
useLoaderExtensions: true
});
You can replace the framework-provided implementation of event store or / and aggregate lock with the one of your own. To do that, you need to include a factory method in the options object passed to the domain constructor. Using the factory methods, the example above might become:
var myGetEventStore = require('./getEventStore.js');
var myLock = require('./myLock.js');
var domain = require('cqrs-domain')({
domainPath: '/path/to/my/files',
commandRejectedEventName: 'rejectedCommand',
retryOnConcurrencyTimeout: 1000,
snapshotThreshold: 1000,
eventStore: function () {
return myGetEventStore({
host: '127.0.0.1',
port: 2113,
username: 'admin',
password: 'changeit'
});
},
aggregateLock: : function () {
return myLock({
// ....
});
},
deduplication: : function () {
return myCommandBumper({
// ....
});
}
});
When using factory methods, the objects they return are required to implement the following public interfaces:
Event Store:
f: init(function(err));
f: getNewId(function (err, id));
f: on(evtName, function (err));
f: getFromSnapshot(query, revMax, function(err, snapshot, stream));
f: createSnapshot(obj, function (err));
f: setEventToDispatched(evt, function (err));
Event Stream (returned by getFromSnapshot through the callback):
p: events
p: lastRevision
p: eventsToDispatch
f: addEvents(evts)
f: commit(function (err, stream));
Aggregate Lock:
f: connect(function(err, lock))
f: disconnect(function(err))
f: getNewId(function(err, id))
f: reserve(workerId, aggregateId, function(err))
f: getAll(aggregateId, function(err, workerIds))
f: resolve(aggregateId, function(err))
Command Bumper:
f: connect(function(err, lock))
f: disconnect(function(err))
f: getNewId(function(err, id))
f: add(key, ttl, function(err, added))
where:
f: function
p: property
You can also replace the built-in structure loader with one that suits your needs. To do that, you need to include a loading method in the options object passed to the domain constructor.
// options will contain a the domainPath, validatorExtension, and useLoaderExtensions options passed to the constructor
// as well as a definition object containing all the constructors of the domain components ( Context, Aggregate etc. ) and error constructors ( inside errors )
function myCustomLoader(options) {
return {
myContext: new Context({ name: 'myContext' }).addAggregate(new Aggregate({ name : 'agg' }, function(){}).addCommand({ name: 'cmd' }, function(){}))
}
// or, more probably
return myExternalCoolLoader(options.domainPath, options.definitions);
}
// or async
function myCustomLoaderAsync(options, callback) {
callback(null, myExternalCoolLoader(options.domainPath, options.definitions));
}
var domain = require('cqrs-domain')({
domainPath: '/path/to/my/files',
structureLoader: myCustomLoader
});
You can use this for example in you custom command handlers.
require('cqrs-domain').errors.ValidationError
require('cqrs-domain').errors.BusinessRuleError
require('cqrs-domain').errors.AggregateDestroyedError
require('cqrs-domain').errors.AggregateConcurrencyError
require('cqrs-domain').errors.ConcurrencyError
require('cqrs-domain').errors.DuplicateCommandError
// eventStore
domain.eventStore.on('connect', function() {
console.log('eventStore connected');
});
domain.eventStore.on('disconnect', function() {
console.log('eventStore disconnected');
});
// aggregateLock
domain.aggregateLock.on('connect', function() {
console.log('aggregateLock connected');
});
domain.aggregateLock.on('disconnect', function() {
console.log('aggregateLock disconnected');
});
// commandBumper
domain.commandBumper.on('connect', function() {
console.log('commandBumper connected');
});
domain.commandBumper.on('disconnect', function() {
console.log('commandBumper disconnected');
});
// anything (eventStore or aggregateLock or commandBumper)
domain.on('connect', function() {
console.log('something connected');
});
domain.on('disconnect', function() {
console.log('something disconnected');
});
The values describes the path to that property in the command message.
domain.defineCommand({
// optional, default is 'id'
id: 'id',
// optional, default is 'name'
name: 'name',
// optional, default is 'aggregate.id'
// if an aggregate id is not defined in the command, the command handler will create a new aggregate instance
aggregateId: 'aggregate.id',
// optional, only makes sense if contexts are defined in the 'domainPath' structure
context: 'context.name',
// optional, only makes sense if aggregates with names are defined in the 'domainPath' structure
aggregate: 'aggregate.name',
// optional, but recommended
payload: 'payload',
// optional, if defined the command handler will check if the command can be handled
// if you want the command to be handled in a secure/transactional way pass a revision value that matches the current aggregate revision
revision: 'revision',
// optional, if defined the command handler will search for a handle that matches command name and version number
version: 'version',
// optional, if defined theses values will be copied to the event (can be used to transport information like userId, etc..)
meta: 'meta'
});
The values describes the path to that property in the event message.
domain.defineEvent({
// optional, default is 'correlationId'
// will use the command id as correlationId, so you can match it in the sender
correlationId: 'correlationId',
// optional, default is 'id'
id: 'id',
// optional, default is 'name'
name: 'name',
// optional, default is 'aggregate.id'
aggregateId: 'aggregate.id',
// optional, only makes sense if contexts are defined in the 'domainPath' structure
context: 'context.name',
// optional, only makes sense if aggregates with names are defined in the 'domainPath' structure
aggregate: 'aggregate.name',
// optional, default is 'payload'
payload: 'payload',
// optional, default is 'revision'
// will represent the aggregate revision, can be used in next command
revision: 'revision',
// optional
version: 'version',
// optional, if defined the values of the command will be copied to the event (can be used to transport information like userId, etc..)
meta: 'meta',
// optional, if defined the commit date of the eventstore will be saved in this value
commitStamp: 'commitStamp',
// optional, if defined and the eventstore db implemntation supports this the position of the event in the eventstore will be saved in this value
position: 'position'
});
domain.idGenerator(function () {
var id = require('uuid').v4().toString();
return id;
});
domain.idGenerator(function (callback) {
setTimeout(function () {
var id = require('uuid').v4().toString();
callback(null, id);
}, 50);
});
domain.aggregateIdGenerator(function () {
var id = require('uuid').v4().toString();
return id;
});
domain.aggregateIdGenerator(function (callback) {
setTimeout(function () {
var id = require('uuid').v4().toString();
callback(null, id);
}, 50);
});
// pass events to bus
domain.onEvent(function (evt) {
bus.emit('event', evt);
});
// pass events to bus
domain.onEvent(function (evt, callback) {
bus.emit('event', evt, function ack () {
callback();
});
});
domain.init(function (err, warnings) {
// this callback is called when all is ready...
// warnings: if no warnings warnings is null, else it's an array containing errors during require of files
});
// or
domain.init(); // callback is optional
domain.handle({
id: 'b80ade36-dd05-4340-8a8b-846eea6e286f',
name: 'enterNewPerson',
aggregate: {
id: '3b4d44b0-34fb-4ceb-b212-68fe7a7c2f70',
name: 'person'
},
context: {
name: 'hr'
},
payload: {
firstname: 'Jack',
lastname: 'Huston'
},
revision: 0,
version: 1,
meta: {
userId: 'ccd65819-4da4-4df9-9f24-5b10bf89ef89'
}
}); // callback is optional
domain.handle({
id: 'b80ade36-dd05-4340-8a8b-846eea6e286f',
name: 'renamePerson',
aggregate: {
id: '3b4d44b0-34fb-4ceb-b212-68fe7a7c2f70',
name: 'person'
},
context: {
name: 'hr'
},
payload: {
firstname: 'Jack',
lastname: 'Huston'
},
revision: 0,
version: 1,
meta: {
userId: 'ccd65819-4da4-4df9-9f24-5b10bf89ef89'
}
}, function (err) {
// this callback is called when command is handled successfully or unsuccessfully
// err can be of type:
// - null
// - Error
// {
// name: 'Error',
// message: 'optional message'
// }
// - ValidationError
// {
// name: 'ValidationError',
// message: 'some message',
// more: { /* more infos */ }
// }
// - BusinessRuleError
// {
// name: 'BusinessRuleError',
// message: 'some message',
// more: { /* more infos */ }
// }
// - AggregateDestroyedError
// {
// name: 'AggregateDestroyedError',
// message: 'Aggregate has already been destroyed!',
// more: {
// aggregateId: 'ad10d2c0-6509-4cb0-86d2-76312d930001',
// aggregateRevision: 6
// }
// }
// - AggregateConcurrencyError
// {
// name: 'AggregateConcurrencyError',
// message: 'Actual revision in command is "3", but expected is "2"!',
// more: {
// aggregateId: 'ad10d2c0-6509-4cb0-86d2-76312d930001',
// aggregateRevision: 2,
// commandRevision: 3
// }
// }
});
domain.handle({
id: 'b80ade36-dd05-4340-8a8b-846eea6e286f',
name: 'renamePerson',
aggregate: {
id: '3b4d44b0-34fb-4ceb-b212-68fe7a7c2f70',
name: 'person'
},
context: {
name: 'hr'
},
payload: {
firstname: 'Jack',
lastname: 'Huston'
},
revision: 0,
version: 1,
meta: {
userId: 'ccd65819-4da4-4df9-9f24-5b10bf89ef89'
}
}, function (err, events, aggregateData, metaInfos) {
// this callback is called when command is handled successfully or unsuccessfully
// err: is the same as described before
// events: same as passed in 'onEvent' function
// events: in case of no error here is the array of all events that should be published
// events: in case of error are the one of these Errors (ValidationError, BusinessRuleError, AggregateDestroyedError, AggregateConcurrencyError)
// converted in an event with the event name defined in the options (default is 'commandRejected')
// aggregateData: represents the aggregateData after applying the resulting events
// metaInfos: { aggregateId: '3b4d44b0-34fb-4ceb-b212-68fe7a7c2f70', aggregate: 'person', context: 'context' }
});
After the initialization you can request the domain information:
domain.init(function (err) {
domain.getInfo();
// ==>
// { contexts: [
// {
// "name": "hr",
// "aggregates": [
// {
// "name": "person",
// "version": 3,
// "commands": [
// {
// "name": "enterNewPerson",
// "version": 0,
// "preconditions": [...]
// },
// {
// "name": "unregisterAllContactInformation",
// "version": 2,
// "preconditions": [...]
// },
// {
// "name": "unregisterAllContactInformation",
// "version": 1,
// "preconditions": [...]
// }
// ],
// "events": [
// {
// "name": "enteredNewPerson",
// "version": 3
// },
// {
// "name": "enteredNewPerson",
// "version": 0
// },
// {
// "name": "enteredNewPerson",
// "version": 2
// },
// {
// "name": "unregisteredEMailAddress",
// "version": 0
// },
// {
// "name": "unregisteredPhoneNumber",
// "version": 0
// }
// ],
// "businessRules": [
// {
// "name": "atLeast1EMail",
// "description": "at least one character should be in email address"
// },
// {
// "name": "nameEquality",
// "description": "firstname should never be equal lastname"
// }
// ]
// }
// ]
// }
//]}
});
module.exports = require('cqrs-domain').defineContext({
// optional, default is the directory name
name: 'hr'
});
A special option to define a context with all its aggregates, commands, events and rules exists by adding the externallyLoaded option to the context :
module.exports = require('cqrs-domain').defineContext({
// optional, default is the directory name
name: 'hr',
externallyLoaded: true
});
When doing so the context will be added 'as-is' to the domain, this means it won't go trough the normal tree loading and parsing process.
This option is aimed mainly at plugin developers, as it leaves the responsibility of structuring the domain right in the hand of the one defining the context ( most-probably a plug-in ).
module.exports = require('cqrs-domain').defineAggregate({
// optional, default is last part of path name
name: 'person',
// optional, default 0
version: 3,
// optional, default ''
defaultCommandPayload: 'payload',
// optional, default ''
defaultEventPayload: 'payload',
// optional, default ''
defaultPreConditionPayload: 'payload',
// optional, default false
// by skipping the history, only the last event will be loaded and defaultly not applyed (just to ensure the revision number increment)
skipHistory: true,
// optional, default false
// only optionally needed when skipHistory is set to true, only the last event will be loaded and applyed
applyLastEvent: true,
// optional, default false
// will publish the events but will not commit them to the eventstore
disablePersistence: false
},
// optionally, define some initialization data...
{
emails: ['default@mycomp.org'],
phoneNumbers: []
})
// optionally, define snapshot need algorithm...
.defineSnapshotNeed(function (loadingTime, events, aggregateData) {
// loadingTime is the loading time in ms of the eventstore data
// events are all loaded events in an array
// aggregateData represents the aggregateData after applying the resulting events
return events.length >= 200;
})
// optionally, define if snapshot should be ignored
// if true, the whole event stream will be loaded
.defineIgnoreSnapshot({
version: 0
}, function (data) {
return true;
})
//.defineIgnoreSnapshot({
// version: 0
//}, true)
//.defineIgnoreSnapshot({
// version: 0
//}) // default true
// optionally, define conversion algorithm for older snapshots
// always convert directly to newest version...
// when loaded a snapshot and it's an older snapshot, a new snapshot with same revision but with newer aggregate version will be created
.defineSnapshotConversion({
version: 1
}, function (data, aggregate) {
// data is the snapshot data
// aggregate is the aggregate object
aggregate.set('emails', data.emails);
aggregate.set('phoneNumbers', data.phoneNumbers);
var names = data.name.split(' ');
aggregate.set('firstname', names[0]);
aggregate.set('lastname', names[1]);
})
// optionally, define committingSnapshotTransformer (i.e. for GDPR: to encrypt data in storage)
.defineCommittingSnapshotTransformer({
version: 1
}, function (data) {
// data is the snapshot data
data.firstname = encrypt(data.firstname);
return data;
})
// or async
.defineCommittingSnapshotTransformer({
version: 1
}, function (data, callback) {
// data is the snapshot data
encrypt(data.firstname, function (err, encrypted) {
data.firstname = encrypted;
callback(err, data);
});
})
// optionally, define loadingSnapshotTransformer (i.e. for GDPR: to decrypt stored data)
.defineLoadingSnapshotTransformer({
version: 1
}, function (data) {
// data is the snapshot data
data.firstname = decrypt(data.firstname);
return data;
})
// or async
.defineLoadingSnapshotTransformer({
version: 1
}, function (data, callback) {
// data is the snapshot data
decrypt(data.firstname, function (err, decrypted) {
data.firstname = decrypted;
callback(err, data);
});
})
// optionally, define idGenerator function for new aggregate ids
// sync
.defineAggregateIdGenerator(function () {
return require('uuid').v4().toString();
});
// or async
.defineAggregateIdGenerator(function (callback) {
setTimeout(function () {
var id = require('uuid').v4().toString();
callback(null, id);
}, 50);
})
// optionally, define idGenerator function for new aggregate ids that are command aware
// if you define it that way, the normal defineAggregateIdGenerator function will be replaced
// sync
.defineCommandAwareAggregateIdGenerator(function (cmd) {
return cmd.id + require('uuid').v4().toString();
});
// or async
.defineCommandAwareAggregateIdGenerator(function (cmd, callback) {
setTimeout(function () {
var id = cmd.id + require('uuid').v4().toString();
callback(null, id);
}, 50);
});
All command schemas are json schemas. Hint http://jsonary.com/documentation/json-schema/
Internally the tv4 module is used for validation. Additionaly you can extend the tv4 instance with other functionality like tv4-formats, so you can easily use format constraints (i.e. 'email') for your 'string'-types. To extend tv4 just catch the validator before having initialized the domain:
domain.extendValidator(function (validator) {
// own formats
validator.addFormat(require('tv4-formats'));
validator.addFormat('mySpecialFormat', function (data) {
if (data === 'special') {
return null;
}
return 'wrong format for special';
});
// or other schemas
validator.addSchema({ 'mySharedSchema': { /* the schema json */ } });
validator.addSchema('myOtherSharedSchema', { /* the schema json */ });
// or replace the core valitator
validator.validator(function (options, schema) {
// options.schemas => all schemas
// options.formats => all formats
// sync
return function (cmdDataToValidate) {
if (everythingIsOk) {
return null;
} else {
return new require('cqrs-domain').errors.ValidationError('command not valid', { 'because': 'of this' });
}
};
// or async
return function (cmdDataToValidate, callback) {
externalAsyncValidator(cmdDataToValidate, function(errors){
if (!error) {
callback();
} else {
callback(new require('cqrs-domain').errors.ValidationError('command not valid', { 'because': 'of this' }));
}
});
};
});
});
Each command schema title should match the command name. Example: enterNewPerson.json
To support multiple versions look at: unregisterAllContactInformation.json
or: unregisterAllContactInformation_v1.json unregisterAllContactInformation_v2.json
You can also have an hierarchical command extension look at:
Can be used to perform some business rules before handling the command. Contrary to Pre-Conditions, these rules are applied BEFORE the aggregate is loaded.
This allows you to (for example) run checks against external information by using closures.
Tip: Pre-load conditions are especially useful when you have checks that you want to run on an aggregate, but when it is OK for those checks to run on potentially stale data (eg a view model). By doing these checks before the aggregate is locked, you avoid creating a locking bottleneck at the aggregate level, and can keep your aggregate smaller because the information for those checks is externalized to the domain. This helps for performance if the domain you are in is performance critical, and helps you keep focus on the real, strongly consistent invariants in your domain.
A Command can have multiple pre-load-conditions.
var externalDataLoader = require('some_file');
module.exports = require('cqrs-domain').definePreLoadCondition({
// the command name
// optional, default is file name without extension,
// if name is '' it will handle all commands that matches the appropriate aggregate
// if name is an array of strings it will handle all commands that matches the appropriate name
name: 'checkSomeViewModel',
// optional, default 0
version: 2,
// optional, if not defined it will use what is defined as default in aggregate or pass the whole command
payload: 'payload',
// optional
description: 'firstname should always be set',
// optional, default Infinity, all pre-conditions will be sorted by this value
priority: 1
}, function (data, callback) {
// data is the command data
// callback is optional, if not defined as function argument you can throw errors or return errors here (sync way)
if (externalDataLoader.get(data.id) !== data.value) {
return callback('not allowed');
// or
// return callback(new Error('not allowed'));
// or
// return callback(new Error()); // if no error message is defined then the description will be taken
// or
// return callback(new require('cqrs-domain').BusinessRuleError('not allowed', { /* more infos */ }));
}
callback(null);
// or if callback is not defined as function argument
// if (externalDataLoader.get(data.id) !== data.value)
// return 'not allowed';
// // or
// // return new Error('not allowed');
// // or
// // return new Error(); // if no error message is defined then the description will be taken
// // or
// // throw new Error(); // if no error message is defined then the description will be taken
// // or
// // throw new Error('not allowed');
// // or
// // throw new require('cqrs-domain').BusinessRuleError('not allowed', { /* more infos */ });
// }
});
Can be used to perform some business rules before handling the command. The aggregate is locked and loaded before the pre-condition is applied.
A Command can have multiple pre-conditions.
module.exports = require('cqrs-domain').definePreCondition({
// the command name
// optional, default is file name without extension,
// if name is '' it will handle all commands that matches the appropriate aggregate
// if name is an array of strings it will handle all commands that matches the appropriate name
name: 'unregisterAllContactInformation',
// optional, default 0
version: 2,
// optional, if not defined it will use what is defined as default in aggregate or pass the whole command
payload: 'payload',
// optional
description: 'firstname should always be set',
// optional, default Infinity, all pre-conditions will be sorted by this value
priority: 1
}, function (data, aggregate, callback) {
// data is the command data
// aggregate is the aggregate object
// callback is optional, if not defined as function argument you can throw errors or return errors here (sync way)
if (!agg.has('firstname')) {
return callback('not personalized');
// or
// return callback(new Error('not personalized'));
// or
// return callback(new Error()); // if no error message is defined then the description will be taken
// or
// return callback(new require('cqrs-domain').BusinessRuleError('not personalized', { /* more infos */ }));
}
callback(null);
// or if callback is not defined as function argument
// if (!agg.has('firstname')) {
// return 'not personalized';
// // or
// // return new Error('not personalized');
// // or
// // return new Error(); // if no error message is defined then the description will be taken
// // or
// // throw new Error(); // if no error message is defined then the description will be taken
// // or
// // throw new Error('not personalized');
// // or
// // throw new require('cqrs-domain').BusinessRuleError('not personalized', { /* more infos */ });
// }
});
Collect all needed infos from aggregate to generate your event(s).
Move checks out of here, the correct places are "business rules", "pre-conditions" or "pre-load consitions"!
Do NOT manipulate the aggregate here!
module.exports = require('cqrs-domain').defineCommand({
// optional, default is file name without extension
name: 'enterNewPerson',
// optional, default 0
version: 1,
// optional, if not defined it will use what is defined as default in aggregate or pass the whole command
payload: 'payload',
// optional, default undefined
// if true, ensures the aggregate to exists already before this command was handled
// if false, ensures the aggregate to not exists already before this command was handled
existing: true
}, function (data, aggregate) {
// data is the command data
// aggregate is the aggregate object
// if (aggregate.get('someAttr') === 'someValue' && aggregate.has('special')) { ... }
aggregate.apply('enteredNewPerson', data);
// or
// aggregate.apply('enteredNewPerson', data, version);
// or
// aggregate.apply({
// event: 'enteredNewPerson',
// payload: data
// });
})
// if defined it will load all the requested event streams
// useful if making bigger redesigns in domain and you need to handle a command on a new aggregate
.defineEventStreamsToLoad(function (cmd) {
return [{ // order is new to old
context: 'hr',
aggregate: 'mails',
aggregateId: cmd.meta.newAggId
},{
context: 'hr',
aggregate: 'persons',
aggregateId: cmd.aggregate.id
}];
});
This is the place where you should manipulate your aggregate.
module.exports = require('cqrs-domain').defineEvent({
// optional, default is file name without extension
name: 'enteredNewPerson',
// optional, default 0
version: 3,
// optional, if not defined it will use what is defined as default in aggregate or pass the whole event...
payload: 'payload'
},
// passing a function is optional
function (data, aggregate) {
// data is the event data
// aggregate is the aggregate object
aggregate.set('firstname', data.firstname);
aggregate.set('lastname', data.lastname);
// or
// aggregate.set(data);
});
module.exports = require('cqrs-domain').defineBusinessRule({
// optional, default is file name without extension
name: 'nameEquality',
// optional
description: 'firstname should never be equal lastname',
// optional, default Infinity, all business rules will be sorted by this value
priority: 1
}, function (changed, previous, events, command, callback) {
// changed is the new aggregate object
// previous is the old aggregate object
// events is the array with the resulting events
// command the handling command
// callback is optional, if not defined as function argument you can throw errors or return errors here (sync way)
if (changed.get('firstname') === changed.get('lastname')) {
return callback('names not valid');
// or
// return callback(new Error('names not valid'));
// or
// return callback(new Error()); // if no error message is defined then the description will be taken
// or
// return callback(new require('cqrs-domain').BusinessRuleError('names not valid', { /* more infos */ }));
}
callback(null);
// or if callback is not defined as function argument
// if (changed.get('firstname') === changed.get('lastname')) {
// return 'names not valid';
// // or
// // return new Error('names not valid');
// // or
// // return new Error(); // if no error message is defined then the description will be taken
// // or
// // throw new Error(); // if no error message is defined then the description will be taken
// // or
// // throw new Error('names not valid');
// // or
// // throw new require('cqrs-domain').BusinessRuleError('names not valid', { /* more infos */ });
// }
});
i.e. useful for GDPR relevant data... to have your data encrypted in the eventstore
// i.e. encrypt module.exports = require('cqrs-domain').defineCommittingEventTransformer({ // optional, default is file name without extension name: 'enteredNewPerson',
// optional, default 0
version: 3
},
// passing a function is optional
function (evt) {
evt.payload.firstname = encrypt(evt.payload.firstname);
return evt;
});
// or async module.exports = require('cqrs-domain').defineCommittingEventTransformer({ // optional, default is file name without extension name: 'enteredNewPerson',
// optional, default 0
version: 3
},
// passing a function is optional
function (evt, callback) {
encrypt(evt.payload.firstname, function (err, encrypted) {
evt.payload.firstname = encrypted;
callback(err, evt);
});
});
// i.e decrypt module.exports = require('cqrs-domain').defineLoadingEventTransformer({ // optional, default is file name without extension name: 'enteredNewPerson',
// optional, default 0
version: 3
},
// passing a function is optional
function (evt) {
evt.payload.firstname = decrypt(evt.payload.firstname);
return evt;
});
// or async module.exports = require('cqrs-domain').defineLoadingEventTransformer({ // optional, default is file name without extension name: 'enteredNewPerson',
// optional, default 0
version: 3
},
// passing a function is optional
function (evt, callback) {
decrypt(evt.payload.firstname, function (err, decrypted) {
evt.payload.firstname = decrypted;
callback(err, evt);
});
});
Is your use case not solvable without a custom command handling? Sagas? Micro-Services?
module.exports = require('cqrs-domain').defineCommandHandler({
// optional, default is file name without extension
name: 'enterNewSpecialPerson',
// optional, default 0
version: 1,
// optional, if not defined it will pass the whole command...
payload: 'payload'
}, function (aggId, cmd, commandHandler, callback) {
// aggId is the aggregate id
// cmd is the command data
commandHandler.loadAggregate(aggId, function (err, aggregate, stream) {
if (err) {
return callback(err);
}
callback(null, [{ my: 'special', ev: 'ent' }]);
// // check if destroyed, check revision, validate command
// var err = commandHandler.verifyAggregate(aggregate, cmd);
// if (err) {
// return callback(err);
// }
//
// // call api or emit a command or whatever...
// // and at the end perhaps you call: commandHandler.handle(cmd, callback);
});
});
Importing ES6 style default exports is supported for all definitions where you also use module.exports:
module.exports = defineContext({...});
works as well as
exports.default = defineContext({...});
as well as (must be transpiled by babel or tsc to be runnable in node)
export default defineContext({...});
Also:
exports.default = defineAggregate({...});
exports.default = defineCommand({...});
exports.default = defineEvent({...});
// etc...
Exports other than the default export are then ignored by this package's structure loader.
Copyright (c) 2018 Adriano Raiano
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.