From db2d1f634495464fc0803c9d846043fc023d714b Mon Sep 17 00:00:00 2001
From: zak <zak.knill@ably.io>
Date: Mon, 25 Sep 2023 16:53:10 +0100
Subject: [PATCH] Add docs for event buffering

---
 docs/concepts/event-buffering.md | 42 ++++++++++++++++++++++++++++++++
 src/Models.ts                    |  1 +
 src/types/model.ts               |  1 +
 3 files changed, 44 insertions(+)
 create mode 100644 docs/concepts/event-buffering.md

diff --git a/docs/concepts/event-buffering.md b/docs/concepts/event-buffering.md
new file mode 100644
index 00000000..7aa11a77
--- /dev/null
+++ b/docs/concepts/event-buffering.md
@@ -0,0 +1,42 @@
+# Event Buffering
+
+*Event buffer* describes how the Models SDK buffers a sliding window of events to enable short-term reordering and de-duplication.
+
+## Buffering
+
+By default the sliding window event buffer is off.
+It can be enabled but setting the number of millisecond to buffer events for, when instantiating the library:
+
+```ts
+const models = new Models({
+    ably,
+    eventBufferOptions: {bufferMs: 100}
+});
+```
+
+## Event re-ordering
+
+Internally, the Models SDK holds a sliding window of events. By default the events in the buffer are ordered lexicographically by their message id.
+That is, smaller message ids are moved earlier in the list of messages in the buffer.
+
+You can specify a custom ordering based on any part of the message by passing an eventOrderer function:
+
+```ts
+const models = new Models({
+    ably,
+    eventBufferOptions: {bufferMs: 100, eventOrderer: (a, b) => { ... }}
+});
+```
+
+## Event expiry
+
+The buffer is a sliding window. When an event expires from the buffer it is passed to the update function to be merged into the confirmed state.
+
+Because events may be re-ordered, the sliding window guarantees that when a given event expires, all events in the buffer before the expiring event will be passed to the update
+function first. This ensures the order is maintained and  means that some events may remain in the buffer for less than the `bufferMs` number of milliseconds.
+
+
+## Event de-duplication
+
+Events in the buffer are deduplicated based on message id. Later events with the same message id are discarded in favour of earlier events for that message id. Deduplication only
+happens for events that are in the buffer, and not for events that have expired from the buffer.
diff --git a/src/Models.ts b/src/Models.ts
index 56ef480b..90128bb1 100644
--- a/src/Models.ts
+++ b/src/Models.ts
@@ -22,6 +22,7 @@ export default class Models {
       logger: pino({ level: options.logLevel || 'silent' }),
       ably: options.ably,
       ...(options.defaultMutationOptions && { defaultMutationOptions: options.defaultMutationOptions }),
+      eventBufferOptions: options.eventBufferOptions,
     };
     this.options.ably.time();
   }
diff --git a/src/types/model.ts b/src/types/model.ts
index c0c55407..4e994c17 100644
--- a/src/types/model.ts
+++ b/src/types/model.ts
@@ -12,6 +12,7 @@ export type ModelsOptions = {
   ably: AblyTypes.RealtimePromise;
   logLevel?: LevelWithSilent;
   defaultMutationOptions?: Partial<MutationOptions>;
+  eventBufferOptions?: EventBufferOptions;
 };
 
 /**