Historia

KO | EN

gitlite — search

#hacktoberfest #ai #golang #android #rust #macos #nodejs #java #windows #awesome #vue #security #pytorch #openai

(★ 12)

Objects propagation based on event sourcing

Historia Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Historia

[Event sourcing](https://learn.microsoft.com/en-us/azure/architecture/patterns/event-sourcing) implementation in Pharo Smalltalk.

## Features

- Model objects' mutations are recorded as events with timestamps.
- ModelSpace (Aggregation) can manage model objects with specific names.
- ModelSpace can save the states of managed objects as snapshots.
- ModelSpace can load object states from snapshots or replay events to return to any timestamp.
- ModelSpaces can be notified of mutations or notifications from other ModelSpaces.
- Snapshots and events are stored in reliable persistent storage (currently Redis is used).
- A Bank Account example is included to demonstrate how to use the framework.
- Extensible:
  - Customizable Event/Snapshot codecs (STON and Fuel are used by default)
  - Customizable Model and ModelSpace behaviors (for example, you can add audit logs for all mutations)

## Installation

In Playground:

```smalltalk
Metacello new
  baseline: 'Historia';
  repository: 'github://mumez/Historia:main/src';
  load.
```

If Redis is not running, you will also need to:

```
docker run -d --name redis-stack -p 6379:6379 -p 8001:8001 redis/redis-stack:latest
```

## Quick example

```Smalltalk
spaceId := 'sample-space'.

"Step 1: Create a ModelSpace for managing models"
modelSpace := HsModelSpace spaceId: spaceId.

"Step 2: Register a Model (In a real application, you would register a domain-specific model. Here, we use a generic HsOrderedCollectionModel for demonstration purposes)"
modelSpace putModelOf: HsOrderedCollectionModel id: 'numbers'.
vmodel := modelSpace modelAt: 'numbers'.

"Step 3: Perform operations on the model (e.g., adding numbers to a collection)"
1 to: 5 do: [ :idx | vmodel add: idx ].

"Step 4: Save the model state (All mutations are recorded as events and saved to the event stream)"
vmodel save.

"Step 5: Create another ModelSpace for replaying events"
modelSpace2 := HsModelSpace spaceId: spaceId.

"Step 6: Catch up to the current state by replaying mutation events"
modelSpace2 catchup.

"Step 7: Print the model state (You may need to wait briefly for the events to propagate)"
(modelSpace2 modelAt: 'numbers') values. "-> an OrderedCollection(1 2 3 4 5)"
```

## How to use the framework

Please see the

- [Tutorial](./doc/tutorial)
- [チュートリアル(日本語)](./doc/tutorial_ja)

## FAQ

### Q: How to change Redis connection address / port?

A: Send `#targetUrl:` to `RsStreamSettings` default instance:

```Smalltalk
RsStreamSettings default targetUrl: 'sync://localhost:6379'
```

### Q: How do I use other event codecs?

A: Set the event codec by sending `#eventCodec:` to the modelSpace's settings:

```Smalltalk
modelSpace settings eventCodec: #json.
```

The JSON codec is useful if you want to receive Historia events from other systems via the Redis event stream.

If you need a more compact event format, you can use the MessagePack codec:

```Smalltalk
modelSpace settings eventCodec: #mp.
```

Note: The MessagePack codec is provided as an optional package. To use it, you must explicitly load it:

```Smalltalk
Metacello new
  baseline: 'Historia';
  repository: 'github://mumez/Historia:main/src';
  load: #('default' 'MessagePackCodec-Tests').
```

Historia

Historia Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Historia

Historia Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README