Implemented journaling and snapshot functionalities

- Added journaling feature to log order book changes.
- Implemented snapshot feature to save the current state of the order book.
- Introduced `enabledJournaling`, `journal` and `snapshot` options in the Orderbook constructor to enable journaling and initialize with saved logs.

BRAKING CHANGES
- The order book now exposes a new `snapshot` function to take a snapshot of the order book and a new `lastOp` getter to retrieve the ID of the last operation performed.
- New `log` property to the responses of each operation when the `enableJournaling` option is enabled
- Every order now have a new `origSize` property

Author: fasenderos

README.md

@@ -252,6 +252,61 @@ bids: 90  -> 5      90  -> 5
       80  -> 1      80  -> 1
 ```
 
+## Options
+
+The orderbook can be initialized with the following options by passing them to the constructor:
+
+### Snapshot
+A `snapshot` represents the state of the order book at a specific point in time. It includes the following properties:
+
+ - `asks`: An array of ask orders, where each order contains a price and a list of orders associated with that price.
+ - `bids`: An array of bid orders, where each order contains a price and a list of orders associated with that price.
+ - `ts`: A timestamp indicating when the snapshot was taken, in Unix timestamp format.
+ - `lastOp`: The id of the last operation included in the snapshot
+
+Snapshots are crucial for restoring the order book to a previous state. The system can restore from a snapshot before processing any journal logs, ensuring consistency and accuracy.
+After taking the snapshot, you can safely remove all logs preceding the `lastOp` id.
+
+```js
+const lob = new OrderBook({ enableJournaling: true});
+
+// after every order save the log to the database
+const order = lob.limit("sell", "uniqueID", 55, 100)
+await saveLog(order.log)
+
+// ... after some time take a snapshot of the order book and save it on the database
+
+const snapshot = lob.snapshot();
+await saveSnapshot(snapshot)
+
+// If you want you can safely remove all logs preceding the `lastOp` id of the snapshot, and continue to save each subsequent log to the database
+await removePreviousLogs(snapshot.lastOp)
+
+// On server restart get the snapshot from the database and initialize the order book
+const logs = await getLogs()
+const lob = new OrderBook({ snapshot, journal: log enableJournaling: true });
+```
+
+### Journal Logs
+The `journal` feature allows for the logging of changes and activities within the orderbook and contains all the orders operations. This is useful for recovering the state of orderbook after unexpected events.
+```js
+// Assuming 'logs' is an array of log entries retrieved from the database
+
+const logs = await getLogs();
+const lob = new OrderBook({ journal: logs, enableJournalLog: true });
+```
+By combining snapshots with journaling, the system can effectively restore and audit the state of the order book, ensuring data integrity and providing a reliable mechanism for state recovery.
+
+### Enable Journaling
+`enabledJournaling` is a configuration setting that determines whether journaling is enabled or disabled. When enabled, all changes to the order book and related activities are logged into a journal. This helps in tracking and auditing the state of the order book over time.
+```js
+const lob = new OrderBook({ enableJournaling: true }); // false by default
+
+// after every order save the log to the database
+const order = lob.limit("sell", "uniqueID", 55, 100)
+await saveLog(order.log)
+```
+
 ## Development
 
 ### Build

src/errors.ts

@@ -11,6 +11,7 @@ export enum ERROR {
   ErrLimitFOKNotFillable = 'orderbook: limit FOK order not fillable',
   ErrOrderExists = 'orderbook: order already exists',
   ErrOrderNotFound = 'orderbook: order not found',
+  ErrJournalLog = 'journal: invalid journal log format',
 }
 
 export const CustomError = (error?: ERROR | string): Error => {
@@ -37,6 +38,8 @@ export const CustomError = (error?: ERROR | string): Error => {
       return new Error(ERROR.ErrInvalidTimeInForce)
     case ERROR.ErrLimitFOKNotFillable:
       return new Error(ERROR.ErrLimitFOKNotFillable)
+    case ERROR.ErrJournalLog:
+      return new Error(ERROR.ErrJournalLog)
     default:
       error = error === undefined || error === '' ? '' : `: ${error}`
       return new Error(`${ERROR.Default}${error}`)

src/order.ts

@@ -1,16 +1,5 @@
 import { Side } from './side'
-
-interface IOrder {
-  id: string
-  side: Side
-  size: number
-  price: number
-  time: number
-  isMaker: boolean
-}
-
-export interface OrderUpdatePrice { price: number, size?: number }
-export interface OrderUpdateSize { price?: number, size: number }
+import { IOrder } from './types'
 
 export enum OrderType {
   LIMIT = 'limit',
@@ -27,6 +16,7 @@ export class Order {
   private readonly _id: string
   private readonly _side: Side
   private _size: number
+  private readonly _origSize: number
   private _price: number
   private _time: number
   private readonly _isMaker: boolean
@@ -36,12 +26,14 @@ export class Order {
     size: number,
     price: number,
     time?: number,
-    isMaker?: boolean
+    isMaker?: boolean,
+    origSize?: number
   ) {
     this._id = orderId
     this._side = side
     this._price = price
     this._size = size
+    this._origSize = origSize ?? size
     this._time = time ?? Date.now()
     this._isMaker = isMaker ?? false
   }
@@ -76,6 +68,11 @@ export class Order {
     this._size = size
   }
 
+  // Getter for the original size of the order
+  get origSize (): number {
+    return this._origSize
+  }
+
   // Getter for order timestamp
   get time (): number {
     return this._time
@@ -92,29 +89,24 @@ export class Order {
   }
 
   // This method returns a string representation of the order
-  toString = (): string => (
+  toString = (): string =>
     `${this._id}:
     side: ${this._side}
+    origSize: ${this._origSize.toString()}
     size: ${this._size.toString()}
     price: ${this._price}
     time: ${this._time}
     isMaker: ${this._isMaker as unknown as string}`
-  )
 
   // This method returns a JSON string representation of the order
-  toJSON = (): string => JSON.stringify({
-    id: this._id,
-    side: this._side,
-    size: this._size,
-    price: this._price,
-    time: this._time,
-    isMaker: this._isMaker
-  })
+  toJSON = (): string =>
+    JSON.stringify(this.toObject())
 
   // This method returns an object representation of the order
   toObject = (): IOrder => ({
     id: this._id,
     side: this._side,
+    origSize: this._origSize,
     size: this._size,
     price: this._price,
     time: this._time,