{Function} Entity
{Function} EntityError
module:eventemitter3, module:debug, module:lodash.clonedeep
**License**: MIT
* [Entity](#Entity)
* [new Entity([snapshot], [events])](#new_Entity_new)
* _instance_
* [.emit()](#Entity+emit)
* [.enqueue()](#Entity+enqueue)
* [.digest(method, data)](#Entity+digest)
* [.merge(snapshot)](#Entity+merge)
* [.mergeProperty(name, value)](#Entity+mergeProperty)
* [.replay(events)](#Entity+replay)
* [.snapshot()](#Entity+snapshot) ⇒ Object
* [.trimSnapshot(snapshot)](#Entity+trimSnapshot)
* _static_
* [.digestMethod(type, fn)](#Entity.digestMethod)
* [.mergeProperty(type, name, fn)](#Entity.mergeProperty)
### new Entity([snapshot], [events])
Creates an event-sourced Entity.
| Param | Type | Description |
| --- | --- | --- |
| [snapshot] | Object | A previously saved snapshot of an entity. |
| [events] | Array | An array of events to apply on instantiation. |
### entity.emit()
Wrapper around the EventEmitter.emit method that adds a condition so events
are not fired during replay.
**Kind**: instance method of [Entity](#Entity)
### entity.enqueue()
Add events to the queue of events to emit. If called during replay, this
method does nothing.
**Kind**: instance method of [Entity](#Entity)
### entity.digest(method, data)
Digest a command with given data.This is called whenever you want to record
a command into the events for the entity. If called during replay, this
method does nothing.
**Kind**: instance method of [Entity](#Entity)
| Param | Type | Description |
| --- | --- | --- |
| method | String | the name of the method/command you want to digest. |
| data | Object | the data that should be passed to the replay. |
### entity.merge(snapshot)
Merge a snapshot onto the entity.
For every property passed in the snapshot, the value is deep-cloned and then
merged into the instance through mergeProperty. See mergeProperty for details.
**Kind**: instance method of [Entity](#Entity)
**See**: Entity.prototype.mergeProperty
| Param | Type | Description |
| --- | --- | --- |
| snapshot | Object | snapshot object. |
### entity.mergeProperty(name, value)
Merge a property onto the instance.
Given a name and a value, mergeProperty checks first attempt to find the
property in the mergeProperties map using the constructor name as key. If it
is found and it is a function, the function is called. If it is NOT found
we check if the property is an object. If so, we merge. If not, we simply
assign the passed value to the instance.
**Kind**: instance method of [Entity](#Entity)
**See**
- mergeProperties
- Entity.mergeProperty
| Param | Type | Description |
| --- | --- | --- |
| name | String | the name of the property being merged. |
| value | Object | the value of the property being merged. |
### entity.replay(events)
Replay an array of events onto the instance.
The goal here is to allow application of events without emitting, enqueueing
nor digesting the replayed events. This is done by setting this.replaying to
true which emit, enqueue and digest check for.
If the method in the event being replayed exists in the instance, we call
the mathod with the data in the event and set the version of the instance to
the version of the event. If the method is not found, we attempt to parse the
constructor to give a more descriptive error.
**Kind**: instance method of [Entity](#Entity)
| Param | Type | Description |
| --- | --- | --- |
| events | Array | an array of events to be replayed. |
### entity.state() ⇒ Object
Return a clone of current state of the entity instance without event sourcing properties. Does not modify anything.
**Kind**: instance method of [Entity](#Entity)
### entity.snapshot() ⇒ Object
Create a snapshot of the current state of the entity instance.
Here the instance's snapshotVersion property is set to the current version,
then the instance is deep-cloned and the clone is trimmed of the internal
sourced attributes using trimSnapshot and returned.
**Kind**: instance method of [Entity](#Entity)
### entity.trimSnapshot(snapshot)
Remove the internal sourced properties from the passed snapshot.
Snapshots are to contain only entity data properties. This trims all other
properties from the snapshot.
**Kind**: instance method of [Entity](#Entity)
**See**: Entity.prototype.snapshot
| Param | Type | Description |
| --- | --- | --- |
| snapshot | Object | the snapshot to be trimmed. |
### Entity.digestMethod(type, fn)
Helper function to automatically create a method that calls digest on the
param provided. Use it to add methods that automatically call digest.
**Kind**: static method of [Entity](#Entity)
| Param | Type | Description |
| --- | --- | --- |
| type | Object | the entity class to which the method will be added. |
| fn | function | the actual function to be added. |
**Example**
```js
Entity.digestMethod(Car, function clearSettings (param) {
const self = this;
this.settings.get(param.name).forEach((name, config) => {
config.sources.forEach((source) => {
source.remove();
});
});
return this.settings;
});
```
### Entity.mergeProperty(type, name, fn)
Convenience function to store references to functions that should be run
when mergin a particular property.
**Kind**: static method of [Entity](#Entity)
**See**: mergeProperties
| Param | Type | Description |
| --- | --- | --- |
| type | Object | the entity class to which the property->fn belongs to. |
| name | String | the name of the property that holds the fn. |
| fn | function | the function to execute when merging the property. |
**Example**
```js
function Wheel (status) {
this.status = status;
}
Wheel.prototype.go = function () {
this.status = 'going';
}
function Car () {
this.id = null;
this.wheel = new Wheel(); // for instantiating our default wheel, when we first 'new' up a Car
Entity.apply(this, arguments);
}
util.inherits(Car, Entity);
Entity.mergeProperty(Car, 'interests', function (obj) {
this.wheel = new Wheel(); // for instantiating our wheel from saved values in a database
});
```
## eventsToEmit : Array
[Description]
**Kind**: global variable
**Todo**
- [ ] discuss the use of this so it can be documented better.
## newEvents : Array
[Description]
**Kind**: global variable
**Todo**
- [ ] discuss the use of this so it can be documented better.
## replaying : Boolean
Boolean to prevent emit, enqueue and digest from running during replay.
**Kind**: global variable
## snapshotVersion : Number
Holds the version of the latest snapshot for the entity.
**Kind**: global variable
## timestamp : Number
Holds the event's timestamp in the entity.
**Kind**: global variable
## version : Number
Holds the current version of the entity.
**Kind**: global variable
## mergeProperties
mergeProperties holds a map of entity types to properties.
**Kind**: global variable
**See**
- Entity.mergeProperty
- Entity.prototype.mergeProperty
## EntityError
{Function} EntityError
**Kind**: global class
### new EntityError(msg, [constr])
Extending native Error.
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| msg | String | | The error message. |
| [constr] | Object | this | The constructor or instance. |
# In the browser
Sourced works just the same in the browser as in Node.js, though you'll want to use it with a browser based repo, such as [sourced-repo-svelte-local-storage-store](https://github.com/CloudNativeEntrepreneur/sourced-repo-svelte-local-storage-store).
You can see an example event sourced SvelteKit application here: [CloudNativeEntrepreneur/sveltekit-eventsourced-funnel](https://github.com/CloudNativeEntrepreneur/sveltekit-eventsourced-funnel)
# Upgrading from V2 to v3
To upgrade from v2, to v3, update your imports of `SourcedEntity` to `Entity`.
Before:
```
import { SourcedEntity as Entity } from 'sourced'
class YourAggregate extends Entity {
```
Now:
```
import { Entity } from 'sourced'
class YourAggregate extends Entity {
// ...
```
If you are using classical prototypical inheritance, then you were using the `Entity` export - this was actually a proxy constructor that allowed the classical syntax to work with ES6 classes. This is now named `EntityProxy`.
Before:
```
const Entity = require('sourced').Entity
```
Now:
```
const Entity = require('sourced').EntityProxy
```
See examples directory for an examply of using the `EntityProxy` - run it with `npm ci && npm run build && node examples/auth/example.js`
# Upgrading
## sourced v4
- Typescript rewrite - thanks to work on this at https://github.com/PDMLab/sourced-ts by @alexander.zeitler and @stephanknull, pulled in by @patrickleet
- BREAKING CHANGE: now publishes ESM and CJS modules at /dist/esm and /dist/cjs
## sourced v3
- Browser support by using `eventemitter3.EventEmitter` instead of Node `events.EventEmitter` by @patrickleet
- BREAKING CHANGE: `Entity` is now `EntityProxy`. `SourcedEntity` is now `Entity`
## sourced v2
- updated to ES6 syntax by @patrickleet
- `SourcedEntity` an ES6 implementation of `Entity` added.
- `Entity` is now just a proxy to the new `SourcedEntity` ES6 class.
- Deprecation notice: `SourcedEntity` will become `Entity` in the next major version, and `Entity`, which is now a proxy, left for backwards compatibility
## sourced v1
- original lib by @mateodelnorte - battle tested in financial systems that tranact billions of dollars.
---
_Source: https://npm.io/package/sourced · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._