fix: Add documentation on reading events.

Author: goloroden

README.md

@@ -82,3 +82,86 @@ const writtenEvents = await client.writeEvents([
 ], [
   isSubjectOnEventId('/books/42', '0')
 ]);
+```
+
+*Note that according to the CloudEvents standard, event IDs must be of type string.*
+
+### Reading Events
+
+To read all events of a subject, call the `readEvents` function with the subject as the first argument and an options object as the second argument. Set the `recursive` option to `false`. This ensures that only events of the given subject are returned, not events of nested subjects.
+
+The function returns an asynchronous iterator, which you can use e.g. inside a `for await` loop:
+
+```typescript
+for await (const event of client.readEvents('/books/42', {
+  recursive: false
+})) {
+  // ...
+}
+```
+
+#### Reading From Subjects Recursively
+
+If you want to read not only all the events of a subject, but also the events of all nested subjects, set the `recursive` option to `true`:
+
+```typescript
+for await (const event of client.readEvents('/books/42', {
+  recursive: true
+})) {
+  // ...
+}
+```
+
+This also allows you to read *all* events ever written. To do so, provide `/` as the subject and set `recursive` to `true`, since all subjects are nested under the root subject.
+
+#### Reading in Anti-Chronological Order
+
+By default, events are read in chronological order. To read in anti-chronological order, provide the `order` option and set it to `antichronological`:
+
+```typescript
+for await (const event of client.readEvents('/books/42', {
+  recursive: false,
+  order: 'antichronological'
+})) {
+  // ...
+}
+```
+
+*Note that you can also specify `chronological` to explicitly enforce the default order.*
+
+#### Specifying Bounds
+
+Sometimes you do not want to read all events, but only a range of events. For that, you can specify the `lowerBound` and `upperBound` options – either one of them or even both at the same time.
+
+Specify the ID and whether to include or exclude it, for both the lower and upper bound:
+
+```typescript
+for await (const event of client.readEvents('/books/42', {
+  recursive: false,
+  lowerBound: { id: '100', type: 'inclusive' },
+  upperBound: { id: '200', type: 'exclusive' }
+})) {
+  // ...
+}
+```
+
+#### Starting From the Latest Event of a Given Type
+
+To read starting from the latest event of a given type, provide the `fromLatestEvent` option and specify the subject, the type, and how to proceed if no such event exists.
+
+Possible options are `read-nothing`, which skips reading entirely, or `read-everything`, which effectively behaves as if `fromLatestEvent` was not specified:
+
+```typescript
+for await (const event of client.readEvents('/books/42', {
+  recursive: false,
+  fromLatestEvent: {
+    subject: '/books/42',
+    type: 'io.eventsourcingdb.library.book-borrowed',
+    ifEventIsMissing: 'read-everything'
+  }
+})) {
+  // ...
+}
+```
+
+*Note that `fromLatestEvent` and `lowerBound` can not be provided at the same time.*