eventsourcingdb 0.10.2 → 0.10.4

package/README.md

@@ -55,3 +55,113 @@ const writtenEvents = await client.writeEvents([
   }
 ]);
 ```
+
+#### Using the `isSubjectPristine` precondition
+
+If you only want to write events in case a subject (such as `/books/42`) does not yet have any events, import the `isSubjectPristine` function and pass it as the second argument as an array of preconditions:
+
+```typescript
+import { isSubjectPristine } from 'eventsourcingdb';
+
+const writtenEvents = await client.writeEvents([
+  // events
+], [
+  isSubjectPristine('/books/42')
+]);
+```
+
+#### Using the `isSubjectOnEventId` precondition
+
+If you only want to write events in case the last event of a subject (such as `/books/42`) has a specific ID (e.g., `0`), import the `isSubjectOnEventId` function and pass it as an array of preconditions in the second argument:
+
+```typescript
+import { isSubjectOnEventId } from 'eventsourcingdb';
+
+const writtenEvents = await client.writeEvents([
+  // events
+], [
+  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.*

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "eventsourcingdb",
-	"version": "0.10.2",
+	"version": "0.10.4",
 	"description": "The official JavaScript client SDK for EventSourcingDB.",
 	"author": {
 		"name": "the native web GmbH",