{"_id":"commands-events","_rev":"325962","name":"commands-events","description":"commands-events provides commands and events for DDD-based applications.","dist-tags":{"latest":"1.0.4"},"maintainers":[{"name":"goloroden","email":"webmaster@goloroden.de"},{"name":"nhummel","email":"hummel@marvelous.systems"},{"name":"thenativeweb-admin","email":"hello@thenativeweb.io"}],"time":{"modified":"2021-06-07T02:44:40.000Z","created":"2017-06-15T10:17:00.150Z","1.0.4":"2019-01-08T20:05:10.912Z","1.0.3":"2018-06-14T09:20:55.170Z","1.0.2":"2018-06-09T17:54:27.154Z","1.0.1":"2018-02-08T21:12:15.661Z","1.0.0":"2017-06-15T10:17:00.150Z"},"users":{},"repository":{"type":"git","url":"git://github.com/thenativeweb/commands-events.git"},"versions":{"1.0.4":{"name":"commands-events","version":"1.0.4","description":"commands-events provides commands and events for DDD-based applications.","contributors":[{"name":"Golo Roden","email":"golo.roden@thenativeweb.io"},{"name":"Matthias Wagler","email":"matthias.wagler@thenativeweb.io"}],"main":"dist/index.js","dependencies":{"@babel/runtime":"7.2.0","formats":"1.0.0","uuidv4":"2.0.0"},"devDependencies":{"assertthat":"2.0.1","roboter":"3.0.3"},"repository":{"type":"git","url":"git://github.com/thenativeweb/commands-events.git"},"keywords":["cqrs","ddd","wolkenkit"],"license":"AGPL-3.0","gitHead":"85998693ff9a00d7db5b7f0225f5797f26cca5fa","bugs":{"url":"https://github.com/thenativeweb/commands-events/issues"},"homepage":"https://github.com/thenativeweb/commands-events#readme","_id":"commands-events@1.0.4","_npmVersion":"6.4.1","_nodeVersion":"10.13.0","_npmUser":{"name":"goloroden","email":"webmaster@goloroden.de"},"dist":{"shasum":"772123d7f175b2984474bce37a722f4c2d3d2830","size":19760,"noattachment":false,"key":"/commands-events/-/commands-events-1.0.4.tgz","tarball":"http://registry.cnpm.dingdandao.com/commands-events/download/commands-events-1.0.4.tgz"},"maintainers":[{"name":"goloroden","email":"webmaster@goloroden.de"},{"name":"nhummel","email":"hummel@marvelous.systems"},{"name":"thenativeweb-admin","email":"hello@thenativeweb.io"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/commands-events_1.0.4_1546977910778_0.6086429516416345"},"_hasShrinkwrap":false,"publish_time":1546977910912,"_cnpm_publish_time":1546977910912},"1.0.3":{"name":"commands-events","version":"1.0.3","description":"commands-events provides commands and events for DDD-based applications.","contributors":[{"name":"Golo Roden","email":"golo.roden@thenativeweb.io"},{"name":"Matthias Wagler","email":"matthias.wagler@thenativeweb.io"}],"main":"dist/index.js","dependencies":{"formats":"1.0.0","uuidv4":"1.0.1"},"devDependencies":{"assertthat":"1.0.0","roboter":"1.0.4"},"repository":{"type":"git","url":"git://github.com/thenativeweb/commands-events.git"},"keywords":["cqrs","ddd","wolkenkit"],"license":"AGPL-3.0","gitHead":"9ec824df1542c1c024984225beb0c84015e58351","bugs":{"url":"https://github.com/thenativeweb/commands-events/issues"},"homepage":"https://github.com/thenativeweb/commands-events#readme","_id":"commands-events@1.0.3","_npmVersion":"5.6.0","_nodeVersion":"8.11.2","_npmUser":{"name":"goloroden","email":"webmaster@goloroden.de"},"dist":{"shasum":"da81e555b1c9f6969eb320569671a3f749d4583a","size":19576,"noattachment":false,"key":"/commands-events/-/commands-events-1.0.3.tgz","tarball":"http://registry.cnpm.dingdandao.com/commands-events/download/commands-events-1.0.3.tgz"},"maintainers":[{"name":"goloroden","email":"webmaster@goloroden.de"},{"name":"nhummel","email":"hummel@marvelous.systems"},{"name":"thenativeweb-admin","email":"hello@thenativeweb.io"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/commands-events_1.0.3_1528968055112_0.573441669458103"},"_hasShrinkwrap":false,"publish_time":1528968055170,"_cnpm_publish_time":1528968055170},"1.0.2":{"name":"commands-events","version":"1.0.2","description":"commands-events provides commands and events for DDD-based applications.","contributors":[{"name":"Golo Roden","email":"golo.roden@thenativeweb.io"},{"name":"Matthias Wagler","email":"matthias.wagler@thenativeweb.io"}],"main":"dist/index.js","dependencies":{"formats":"1.0.0","uuidv4":"1.0.0"},"devDependencies":{"assertthat":"1.0.0","roboter":"1.0.4"},"repository":{"type":"git","url":"git://github.com/thenativeweb/commands-events.git"},"keywords":["cqrs","ddd","wolkenkit"],"license":"AGPL-3.0","gitHead":"42e133c32d337339ecc7aff8eb18786ad9cdb45e","bugs":{"url":"https://github.com/thenativeweb/commands-events/issues"},"homepage":"https://github.com/thenativeweb/commands-events#readme","_id":"commands-events@1.0.2","_npmVersion":"6.1.0","_nodeVersion":"8.11.1","_npmUser":{"name":"goloroden","email":"webmaster@goloroden.de"},"dist":{"shasum":"f91d513c624a8bfe77212943a48a9963e5af6526","size":19514,"noattachment":false,"key":"/commands-events/-/commands-events-1.0.2.tgz","tarball":"http://registry.cnpm.dingdandao.com/commands-events/download/commands-events-1.0.2.tgz"},"maintainers":[{"name":"goloroden","email":"webmaster@goloroden.de"},{"name":"nhummel","email":"hummel@marvelous.systems"},{"name":"thenativeweb-admin","email":"hello@thenativeweb.io"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/commands-events_1.0.2_1528566867033_0.5106811714425219"},"_hasShrinkwrap":false,"publish_time":1528566867154,"_cnpm_publish_time":1528566867154},"1.0.1":{"name":"commands-events","version":"1.0.1","description":"commands-events provides commands and events for DDD-based applications.","contributors":[{"name":"Golo Roden","email":"golo.roden@thenativeweb.io"},{"name":"Matthias Wagler","email":"matthias.wagler@thenativeweb.io"}],"main":"dist/index.js","dependencies":{"formats":"1.0.0","uuidv4":"1.0.0"},"devDependencies":{"assertthat":"1.0.0","roboter":"0.15.6","roboter-server":"0.15.6"},"repository":{"type":"git","url":"git://github.com/thenativeweb/commands-events.git"},"keywords":["cqrs","ddd","wolkenkit"],"license":"AGPL-3.0","gitHead":"d2d8c0052a2413d82c40d8ed98781ea166bcf8c7","bugs":{"url":"https://github.com/thenativeweb/commands-events/issues"},"homepage":"https://github.com/thenativeweb/commands-events#readme","_id":"commands-events@1.0.1","_npmVersion":"5.6.0","_nodeVersion":"8.9.4","_npmUser":{"name":"goloroden","email":"webmaster@goloroden.de"},"dist":{"shasum":"8513c9d48bc2caeba18c64dce946f85fc4d8d668","size":20176,"noattachment":false,"key":"/commands-events/-/commands-events-1.0.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/commands-events/download/commands-events-1.0.1.tgz"},"maintainers":[{"name":"goloroden","email":"webmaster@goloroden.de"},{"name":"nhummel","email":"hummel@marvelous.systems"},{"name":"thenativeweb-admin","email":"hello@thenativeweb.io"}],"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/commands-events_1.0.1_1518124334521_0.567536880558065"},"_hasShrinkwrap":false,"publish_time":1518124335661,"_cnpm_publish_time":1518124335661},"1.0.0":{"name":"commands-events","version":"1.0.0","description":"commands-events provides commands and events for DDD-based applications.","contributors":[{"name":"Golo Roden","email":"golo.roden@thenativeweb.io"},{"name":"Matthias Wagler","email":"matthias.wagler@thenativeweb.io"}],"main":"dist/index.js","dependencies":{"formats":"0.5.5","uuidv4":"0.5.0"},"devDependencies":{"assertthat":"0.9.0","roboter":"0.15.2","roboter-server":"0.15.2"},"repository":{"type":"git","url":"git://github.com/thenativeweb/commands-events.git"},"keywords":["cqrs","ddd","wolkenkit"],"license":"AGPL-3.0","gitHead":"9c074f67d24807686d2943eb8805cf8feaa502b6","bugs":{"url":"https://github.com/thenativeweb/commands-events/issues"},"homepage":"https://github.com/thenativeweb/commands-events#readme","_id":"commands-events@1.0.0","_npmVersion":"5.0.3","_nodeVersion":"6.10.0","_npmUser":{"name":"goloroden","email":"webmaster@goloroden.de"},"dist":{"shasum":"1bad92d19366b41bcdf11c1e52a57fa60d038456","size":20262,"noattachment":false,"key":"/commands-events/-/commands-events-1.0.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/commands-events/download/commands-events-1.0.0.tgz"},"maintainers":[{"name":"goloroden","email":"webmaster@goloroden.de"},{"name":"nhummel","email":"hummel@marvelous.systems"},{"name":"thenativeweb-admin","email":"hello@thenativeweb.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/commands-events-1.0.0.tgz_1497521819022_0.10583173972554505"},"directories":{},"publish_time":1497521820150,"_cnpm_publish_time":1497521820150,"_hasShrinkwrap":false}},"readme":"# commands-events\n\ncommands-events provides commands and events for DDD-based applications.\n\n## Installation\n\n```shell\n$ npm install commands-events\n```\n\n## Quick start\n\nFirst, you need to add a reference to the commands-events module. Since you will use its `Command` and `Event` constructor functions, it's most probably a good idea to reference them directly.\n\n```javascript\nconst { Command, Event } = require('commands-events');\n```\n\n## Using commands\n\n### Creating commands\n\nIf you need to create a command, call the `Command` constructor function and provide the appropriate parameters.\n\n```javascript\nconst command = new Command({\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'ping'\n});\n```\n\nMost of the times, you will want to attach data to the command. For that provide a `data` property when creating the command. If you omit the `data` property, it will be set to an empty object.\n\n```javascript\nconst command = new Command({\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'ping',\n  data: {\n    ttl: 10 * 1000\n  }\n});\n```\n\nIf, additionally, you need to add metadata to the command, specify its `custom` property. If you omit the `custom` property, it will also be set to an empty object.\n\n```javascript\nconst command = new Command({\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'ping',\n  data: {\n    ttl: 10 * 1000\n  },\n  custom: {\n    sourceIp: '127.0.0.1'\n  }\n});\n```\n\nIn any case, the result is an object with an additional `metadata` property.\n\n```javascript\n{\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'ping',\n  id: '4784bce1-4b7b-45a0-87e4-3058303194e6',\n  data: {\n    ttl: 10000\n  },\n  custom: {\n    sourceIp: '127.0.0.1'\n  },\n  user: null,\n  metadata: {\n    timestamp: 1421260133331,\n    correlationId: '4784bce1-4b7b-45a0-87e4-3058303194e6',\n    causationId: '4784bce1-4b7b-45a0-87e4-3058303194e6'\n  }\n}\n```\n\n### Adding a token to a command\n\nTo add a JWT token to a command, e.g. to indicate which user caused it, call the `addToken` function and hand over the token.\n\n```javascript\nconst token = getJwt();\n\ncommand.addToken(token);\n```\n\nThen you can access the user's id (which is identical to the `sub` claim) by using the `command.user.id` property. If you want to access the entire token use `command.user.token`.\n\nPlease note that until you provide a token, the command's `user` property will be `null`.\n\n### Handling deserialized commands\n\nIf you serialize and deserialize a command, all its data is kept, but its constructor and prototype are lost. To recreate them, use the `wrap` function.\n\n```javascript\nconst command = Command.wrap(deserializedCommand);\n```\n\n## Using events\n\n### Creating events\n\nIf you need to create an event, call the `Event` constructor function and provide the appropriate parameters.\n\n```javascript\nconst event = new Event({\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'pinged',\n  metadata: {\n    correlationId: '13505cab-0ca2-4502-b8c9-8f3ce63ae390',\n    causationId: '124885f3-d35e-43a6-84eb-e28c70b5be66'\n  }\n});\n```\n\nIf you want to attach data to the event, specify its `data` property. If you omit the `data` property, it will be set to an empty object.\n\n```javascript\nconst event = new Event({\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'pinged',\n  data: {\n    ttl: 10 * 1000\n  },\n  metadata: {\n    correlationId: '13505cab-0ca2-4502-b8c9-8f3ce63ae390',\n    causationId: '124885f3-d35e-43a6-84eb-e28c70b5be66'\n  }\n});\n```\n\nBy default, an event will always be a `domain` event. For other types of events, specify the event's `type` property.\n\n```javascript\nconst event = new Event({\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'pingFailed',\n  type: 'error',\n  data: {\n    ttl: 10 * 1000\n  },\n  metadata: {\n    correlationId: '13505cab-0ca2-4502-b8c9-8f3ce63ae390',\n    causationId: '124885f3-d35e-43a6-84eb-e28c70b5be66'\n  }\n});\n```\n\nIf, additionally, you need to add metadata to the event, specify its `custom` property. If you omit the `custom` property, it will also be set to an empty object.\n\n```javascript\nconst event = new Event({\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'pinged',\n  data: {\n    ttl: 10 * 1000\n  },\n  custom: {\n    sourceIp: '127.0.0.1'\n  },\n  metadata: {\n    correlationId: '13505cab-0ca2-4502-b8c9-8f3ce63ae390',\n    causationId: '124885f3-d35e-43a6-84eb-e28c70b5be66'\n  }\n});\n```\n\nIn any case, the result is an object with the following structure.\n\n```javascript\n{\n  context: {\n    name: 'network'\n  },\n  aggregate: {\n    name: 'node',\n    id: '85932442-bf87-472d-8b5a-b0eac3aa8be9'\n  },\n  name: 'pinged',\n  type: 'domain',\n  data: {\n    ttl: 10000\n  },\n  metadata: {\n    timestamp: 1421261012560,\n    published: false,\n    correlationId: '13505cab-0ca2-4502-b8c9-8f3ce63ae390',\n    causationId: '124885f3-d35e-43a6-84eb-e28c70b5be66'\n  }\n}\n```\n\n### Adding authorization metadata\n\nYou might want to add authorization metadata to an event in order to specify clearly who is allowed to read this event. Use the `metadata.isAuthorized` property and make sure to set the `owner`, `forAuthenticated` and `forPublic` properties.\n\n```javascript\nconst event = new Event({\n  // ...\n  metadata: {\n    correlationId: '13505cab-0ca2-4502-b8c9-8f3ce63ae390',\n    causationId: '124885f3-d35e-43a6-84eb-e28c70b5be66'\n    isAuthorized: {\n      owner: 'a7e2a714-17f0-45e4-9693-6e3a472cc3d9',\n      forAuthenticated: true,\n      forPublic: false\n    }\n  }\n});\n```\n\n### Adding a user to an event\n\nTo add a user to an event, e.g. to indicate which user caused it, call the `addUser` function and hand over the user. The user may be taken from a command, e.g. with `command.user`. It must contain an `id`.\n\n```javascript\nevent.addUser(command.user);\n```\n\nThen you can access the user's id by using the `event.user.id` property.\n\nPlease note that until you provide a user, the event's `user` property will be `null`.\n\n### Handling deserialized events\n\nIf you serialize and deserialize an event, all its data is kept, but its constructor and prototype are lost. To recreate them, use the `wrap` function.\n\n```javascript\nconst event = Event.wrap(deserializedEvent);\n```\n\n## Manually creating commands and events\n\nIf, for whatever reason, you need to create a command or event manually, i.e. without the help of the constructor functions, you may use the `Command.isWellformed` and `Event.isWellformed` functions to verify whether the created object has the correct format.\n\n```javascript\nconst command = { /* ... */ },\n      event = { /* ... */ };\n\nconsole.log(Command.isWellformed(command)); // => true\nconsole.log(Event.isWellformed(event));     // => true\n```\n\n## Relations between commands and events\n\nEach command and each event is identified by a unique id. It is automatically set whenever you create a new command or event, and it is accessible using the `id` property.\n\nSince each event is caused by a command, you may want to find out by which command a given event was caused. You can do so using the event's `metadata.causationId` property which contains the causing command's `id`. The same is true for commands that were caused by an event, e.g. within a flow.\n\nAll commands and events that arise from an originating command additionally have a common id, the so-called `metadata.correlationId`. You can use this id to gather all commands and events that deal with a long-running transaction and belong together.\n\n## Running the build\n\nTo build this module use [roboter](https://www.npmjs.com/package/roboter).\n\n```shell\n$ npx roboter\n```\n\n## License\n\nCopyright (c) 2014-2018 the native web.\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License along with this program. If not, see [GNU Licenses](http://www.gnu.org/licenses/).\n","_attachments":{},"homepage":"https://github.com/thenativeweb/commands-events#readme","bugs":{"url":"https://github.com/thenativeweb/commands-events/issues"},"license":"AGPL-3.0"}