From 4146f97e0d151a2d7d20b381e752cb42419fa47c Mon Sep 17 00:00:00 2001
From: James Rodewig <james.rodewig@fauna.com>
Date: Fri, 8 Nov 2024 10:08:28 -0500
Subject: [PATCH] docs: Add event feeds to README (#215)

---
 README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/README.md b/README.md
index 89960dda..c51c83de 100644
--- a/README.md
+++ b/README.md
@@ -291,6 +291,65 @@ if (r.Data.Exists) {
 
 ```
 
+## Event Feeds (beta)
+
+The driver supports [Event
+Feeds](https://docs.fauna.com/fauna/current/learn/cdc/#event-feeds).
+
+An Event Feed asynchronously polls an [event
+source](https://docs.fauna.com/fauna/current/learn/cdc/#create-an-event-source)
+for events.
+
+To get paginated events, pass an [event
+source](https://docs.fauna.com/fauna/current/learn/cdc/#create-an-event-source)
+or a query that produces an event source to `EventFeedAsync()`:
+
+```csharp
+// Get an event source from a supported Set
+EventSource eventSource = await client.QueryAsync<EventSource>(FQL($"Person.all().eventSource()"));
+
+// Calculate timestamp for 10 minutes ago in microseconds
+long tenMinutesAgo = DateTimeOffset.UtcNow.AddMinutes(-10).ToUnixTimeMilliseconds() * 1000;
+var feedOptions = new FeedOptions(startTs: tenMinutesAgo, pageSize: 10);
+
+// Pass the event source and `FeedOptions` to `EventFeedAsync()`:
+var feed = await client.EventFeedAsync<Person>(eventSource, feedOptions);
+
+// You can also pass a query that produces an event source directly to `EventFeedAsync()`:
+var feedFromQuery = await client.EventFeedAsync<Person>(FQL($"Person.all().eventsOn({{ .price, .stock }})"), feedOptions);
+
+// EventFeedAsync() returns a `FeedEnumerable` instance that can act as an `AsyncEnumerator`.
+// Use `foreach()` or `NextAsync()` to iterate through the pages of events.
+
+// Example 1: Use `foreach()` to iterate through feed pages.
+await foreach (var page in feed)
+{
+    foreach (var evt in page.Events)
+    {
+        Console.WriteLine($"Event Type: {evt.Type}");
+        Person person = evt.Data;
+        Console.WriteLine($"First Name: {person.FirstName} - Last Name: {person.LastName} - Age: {person.Age}");
+    }
+}
+
+// Example 2: Use `NextAsync()` to manually iterate through feed pages.
+// `NextAsync()` requests the next page:
+await feed.NextAsync();
+
+if (feedFromQuery.CurrentPage != null && feedFromQuery.CurrentPage.Events.Any())
+{
+    foreach (var evt in feedFromQuery.CurrentPage.Events)
+    {
+        Console.WriteLine($"Event Type: {evt.Type}");
+        Person person = evt.Data;
+        Console.WriteLine($"First Name: {person.FirstName} - Last Name: {person.LastName} - Age: {person.Age}");
+    }
+}
+
+// Call `NextAsync()` again to fetch the next page:
+await feed.NextAsync();
+```
+
 ## Event Streaming
 
 The driver supports [Event Streaming](https://docs.fauna.com/fauna/current/learn/cdc/#event-streaming).