eventsourcingdb 1.9.1 → 2.0.0

package/README.md

@@ -8,6 +8,8 @@ For more information on EventSourcingDB, see its [official documentation](https:
 
 This client SDK includes support for [Testcontainers](https://testcontainers.com/) to spin up EventSourcingDB instances in integration tests. For details, see [Using Testcontainers](#using-testcontainers).
 
+If you are upgrading from version 1 of this client SDK, see [Upgrading From Version 1](#upgrading-from-version-1).
+
 ## Getting Started
 
 Install the client SDK:
@@ -41,6 +43,119 @@ If you want to verify the API token, call `verifyApiToken`. If the token is inva
 await client.verifyApiToken();
 ```
 
+### Choosing the API
+
+EventSourcingDB offers its v2 API since version 1.3, while older versions offer only the v1 API. This client SDK works with both. Creating a client does not send a request. Instead, the first request of a client asks the server whether it offers the v2 API, by sending a `GET` request to `/api/v2/system/ping`, and the client uses the v2 API if it does, and the v1 API otherwise. The client keeps the answer for its lifetime, so every later request goes straight to the API it found. If the client cannot find out, for example because the server is not reachable, the first request fails with that error, and the next request asks again.
+
+Through the v2 API, all functions that read use the HTTP method `QUERY` ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008)), which, unlike `GET`, carries a request body. If there is a proxy or a load balancer in front of EventSourcingDB, it has to let `QUERY` requests through. There is no fallback to `POST`.
+
+### Handling Stalled Connections
+
+Every request fails once nothing arrives from the server for 30 seconds, for example because the server does not respond, or because a proxy keeps the connection open but no longer passes anything through. The time counts from sending the request until it ends, including connecting and waiting for the response. Everything that arrives starts it anew, so a long stream that keeps receiving events, rows, or heartbeats is never cut off, and the time you spend handling an item of a stream does not count.
+
+A request that stalls throws a `ConnectionStalledError`. It extends `TypeError`, since `fetch` throws a `TypeError` when its own timeouts run out, and its `cause` has the `code` that the cause of that `TypeError` has, `UND_ERR_HEADERS_TIMEOUT` while waiting for the response headers and `UND_ERR_BODY_TIMEOUT` afterwards:
+
+```typescript
+import { ConnectionStalledError } from 'eventsourcingdb';
+
+try {
+  await client.ping();
+} catch (error) {
+  if (error instanceof ConnectionStalledError) {
+    // ...
+  }
+}
+```
+
+To change the 30 seconds, hand over the `stallTimeout` option in milliseconds as third argument when creating the client:
+
+```typescript
+const client = new Client(url, apiToken, {
+  stallTimeout: 10_000
+});
+```
+
+*Note that the `fetch` built into Node.js has timeouts of its own, which keep applying: 10 seconds for connecting, 300 seconds for waiting for the response headers, and 300 seconds without data in the response body. If one of them runs out first, the request throws the `TypeError` of `fetch`, with the message `fetch failed` or `terminated`. A `stallTimeout` above these values therefore cannot extend them.*
+
+*Note that a write that stalls, a call of `writeEvents` or `registerEventSchema`, throws an `OutcomeUnknownError` whose `cause` is the `ConnectionStalledError`, since the write may have been stored nonetheless, see [Knowing Whether a Write Was Stored](#knowing-whether-a-write-was-stored).*
+
+### Aborting a Request
+
+Every function that sends a request takes an abort signal as last argument. To abort a call of `ping`, `verifyApiToken`, or `readEventType`, hand over an abort signal, and abort the appropriate `AbortController`. The call then throws the reason of the abort, which is an `AbortError` unless you provide a reason of your own:
+
+```typescript
+const controller = new AbortController();
+
+try {
+  await client.readEventType('io.eventsourcingdb.library.book-acquired', controller.signal);
+} catch (error) {
+  if (error instanceof DOMException && error.name === 'AbortError') {
+    // ...
+  }
+}
+
+// Somewhere else, abort the controller, which will cause
+// readEventType to throw.
+controller.abort();
+```
+
+Aborting `writeEvents` or `registerEventSchema` once the write has been sent does not undo it, so the write may have been stored nonetheless. The call then throws an `OutcomeUnknownError` whose `cause` is the reason of the abort, see [Knowing Whether a Write Was Stored](#knowing-whether-a-write-was-stored). If the write has not been sent yet, because the signal was aborted before or while the client SDK still establishes the connection, the call throws the reason of the abort itself.
+
+*Note that aborting a function that returns an asynchronous iterator, such as `readEvents`, does not throw, but ends the iteration, see [Aborting Reading](#aborting-reading).*
+
+### Handling Errors
+
+Every error that the server reports throws a `DbApiError`, whether the server describes it in its answer, answers with an HTTP status other than `200`, or reports it while a stream is running. A `DbApiError` has the following fields:
+
+- `code` is the URL that names the error, exactly as the server sends it, for example `https://docs.eventsourcingdb.io/errors/precondition-violated`. It doubles as a link to the documentation of the error. It is `undefined` for an error without a code.
+- `description` is the text that describes the error.
+- `details` is an object with details on the error, such as the index of the precondition that does not hold. It is empty for an error without details.
+- `status` is the HTTP status of the answer, which is `200` for an error that the server describes in its answer.
+- `retryAfter` is the number of seconds after which the server accepts requests again, which only an answer with the HTTP status `429` may name. The client SDK never repeats a request on its own.
+
+To tell errors apart, compare the `code` with the constants of `ErrorCode`, which has a constant for each code that the server knows:
+
+```typescript
+import { DbApiError, ErrorCode, isSubjectPristine } from 'eventsourcingdb';
+
+try {
+  await client.writeEvents([
+    // events
+  ], [
+    isSubjectPristine('/books/42')
+  ]);
+} catch (error) {
+  if (error instanceof DbApiError && error.code === ErrorCode.preconditionViolated) {
+    // ...
+  }
+}
+```
+
+The v1 API does not send codes. For the errors of the v1 API that clearly match a code of the v2 API, the client SDK sets that code, so that the same code works with both APIs: `preconditionViolated`, `capacityExceeded`, `eventSchemaViolated`, and `licenseInvalid` for writing events, `eventSchemaAlreadyRegistered` and `eventSchemaViolated` for registering an event schema, `rangeUnsatisfiable` for reading events, `eventTypeUnknown` for reading an event type, and `storeReadOnly` for every request. Every other error of the v1 API has no code.
+
+A stream that the server ends with an end item, which every stream of the v2 API except observing does, throws an error if it breaks off before that item. Observing never ends on its own, so a stream of observed events that the server closes without reporting an error throws the same error, with both APIs.
+
+#### Knowing Whether a Write Was Stored
+
+EventSourcingDB never stops a write halfway, so a write whose answer is lost may have been stored nonetheless. If `writeEvents` or `registerEventSchema` fails once the write may have reached the server, it throws an `OutcomeUnknownError`, whose `cause` tells what went wrong, for example a `ConnectionStalledError`, a broken connection, an abort after sending, a stream that broke off, or an answer with the HTTP status `500`:
+
+```typescript
+import { OutcomeUnknownError } from 'eventsourcingdb';
+
+try {
+  await client.writeEvents([
+    // events
+  ]);
+} catch (error) {
+  if (error instanceof OutcomeUnknownError) {
+    // Find out whether the events were stored, for example by
+    // reading them, before writing them again.
+  }
+}
+```
+
+A write certainly was not stored, and throws the error itself, only if its request never went out, for example since the client SDK could not establish a connection, or since the write was aborted or stalled while connecting, or if the server refused the write before storing anything. A request counts as gone out once its headers have been sent. The server refuses a write with every `DbApiError` except one with the code `ErrorCode.storeFailed`, and, through the v2 API, with the HTTP status `400`, `401`, `408`, `413`, `429`, or `503`, or, through the v1 API, with an HTTP status of `4xx`, `503`, or `507`. A write that the server refuses with the HTTP status `429` may be sent again after `retryAfter` seconds.
+
 ### Writing Events
 
 Call the `writeEvents` function and hand over an array with one or more events. You do not have to provide all event fields – some are automatically added by the server.
@@ -262,10 +377,10 @@ controller.abort();
 
 #### Detecting a Stalled Connection
 
-While a query is running, EventSourcingDB sends a heartbeat every second whenever there is no row to send. If neither a row nor a heartbeat arrives for 30 seconds, for example because a proxy keeps the connection open but no longer passes anything through, the client SDK closes the connection and the iterator throws a `HeartbeatTimeoutError`:
+While a query is running, EventSourcingDB sends a heartbeat every second whenever there is no row to send. If neither a row nor a heartbeat arrives for the stall timeout, 30 seconds by default, for example because a proxy keeps the connection open but no longer passes anything through, the client SDK closes the connection and the iterator throws a `ConnectionStalledError`, see [Handling Stalled Connections](#handling-stalled-connections):
 
 ```typescript
-import { HeartbeatTimeoutError } from 'eventsourcingdb';
+import { ConnectionStalledError } from 'eventsourcingdb';
 
 try {
   for await (const row of client.runEventQlQuery(`
@@ -275,13 +390,13 @@ try {
     // ...
   }
 } catch (error) {
-  if (error instanceof HeartbeatTimeoutError) {
+  if (error instanceof ConnectionStalledError) {
     // ...
   }
 }
 ```
 
-*Note that the time you spend handling a row does not count towards the 30 seconds, and that aborting the query does not cause a `HeartbeatTimeoutError`.*
+*Note that the time you spend handling a row does not count towards the stall timeout, and that aborting the query does not cause a `ConnectionStalledError`.*
 
 ### Observing Events
 
@@ -297,6 +412,8 @@ for await (const event of client.observeEvents('/books/42', {
 }
 ```
 
+*Note that observing never ends on its own. If the server closes the stream without reporting an error, the iterator throws an error, so that a failure does not go unnoticed. To stop observing, use `break`, `return`, or an abort signal, see [Aborting Observing](#aborting-observing).*
+
 #### Observing From Subjects Recursively
 
 If you want to observe not only all the events of a subject, but also the events of all nested subjects, set the `recursive` option to `true`:
@@ -369,10 +486,10 @@ controller.abort();
 
 #### Detecting a Stalled Connection
 
-While observing, EventSourcingDB sends a heartbeat every second whenever there is no event to send. If neither an event nor a heartbeat arrives for 30 seconds, for example because a proxy keeps the connection open but no longer passes anything through, the client SDK closes the connection and the iterator throws a `HeartbeatTimeoutError`:
+While observing, EventSourcingDB sends a heartbeat every second whenever there is no event to send. If neither an event nor a heartbeat arrives for the stall timeout, 30 seconds by default, for example because a proxy keeps the connection open but no longer passes anything through, the client SDK closes the connection and the iterator throws a `ConnectionStalledError`, see [Handling Stalled Connections](#handling-stalled-connections):
 
 ```typescript
-import { HeartbeatTimeoutError } from 'eventsourcingdb';
+import { ConnectionStalledError } from 'eventsourcingdb';
 
 try {
   for await (const event of client.observeEvents('/books/42', {
@@ -381,13 +498,13 @@ try {
     // ...
   }
 } catch (error) {
-  if (error instanceof HeartbeatTimeoutError) {
+  if (error instanceof ConnectionStalledError) {
     // ...
   }
 }
 ```
 
-*Note that the time you spend handling an event does not count towards the 30 seconds, and that aborting observing does not cause a `HeartbeatTimeoutError`.*
+*Note that the time you spend handling an event does not count towards the stall timeout, and that aborting observing does not cause a `ConnectionStalledError`.*
 
 ### Registering an Event Schema
 
@@ -410,20 +527,36 @@ await client.registerEventSchema('io.eventsourcingdb.library.book-acquired', {
 });
 ```
 
+If a schema is already registered for the event type, the function throws a `DbApiError` with the code `ErrorCode.eventSchemaAlreadyRegistered`, since a schema can be neither replaced nor removed.
+
 ### Listing Subjects
 
-To list all subjects, call the `readSubjects` function with `/` as the base subject. The function returns an asynchronous iterator, which you can use e.g. inside a `for await` loop:
+To list subjects, call the `readSubjects` function with a subject as the first argument and an options object as the second argument. The `recursive` option is required. Set it to `true` to list the subject together with all its nested subjects, so that `/` lists all subjects. The function returns an asynchronous iterator, which you can use e.g. inside a `for await` loop:
 
 ```typescript
-for await (const subject of client.readSubjects('/')) {
+for await (const subject of client.readSubjects('/', {
+  recursive: true
+})) {
+  // ...
+}
+```
+
+If you only want to list subjects within a specific branch, provide the desired subject instead:
+
+```typescript
+for await (const subject of client.readSubjects('/books', {
+  recursive: true
+})) {
   // ...
 }
 ```
 
-If you only want to list subjects within a specific branch, provide the desired base subject instead:
+To find out whether a subject exists, set the `recursive` option to `false`. The iterator then returns only the subject itself, if it exists:
 
 ```typescript
-for await (const subject of client.readSubjects('/books')) {
+for await (const subject of client.readSubjects('/books/42', {
+  recursive: false
+})) {
   // ...
 }
 ```
@@ -432,14 +565,14 @@ for await (const subject of client.readSubjects('/books')) {
 
 If you need to abort listing use `break` or `return` within the `for await` loop. However, this only works if there is currently an iteration going on.
 
-To abort listing independently of that, hand over an abort signal as second argument when calling `readSubjects`, and abort the appropriate `AbortController`:
+To abort listing independently of that, hand over an abort signal as third argument when calling `readSubjects`, and abort the appropriate `AbortController`:
 
 ```typescript
 const controller = new AbortController();
 
-for await (const subject of client.readSubjects(
-  '/', controller.signal)
-) {
+for await (const subject of client.readSubjects('/', {
+  recursive: true
+}, controller.signal)) {
   // ...
 }
 
@@ -458,6 +591,8 @@ for await (const eventType of client.readEventTypes()) {
 }
 ```
 
+Each event type has the fields `type`, which names it, `hasEvents`, which tells whether there are events of this type, and `schema`, which is the registered schema, if there is one.
+
 #### Aborting Listing
 
 If you need to abort listing use `break` or `return` within the `for await` loop. However, this only works if there is currently an iteration going on.
@@ -467,7 +602,7 @@ To abort listing independently of that, hand over an abort signal as argument wh
 ```typescript
 const controller = new AbortController();
 
-for await (const eventType of client.readEventTypes()) {
+for await (const eventType of client.readEventTypes(controller.signal)) {
   // ...
 }
 
@@ -481,24 +616,43 @@ controller.abort();
 To list a specific event type, call the `readEventType` function with the event type as an argument. The function returns the detailed event type, which includes the schema:
 
 ```typescript
-eventType = await client.readEventType("io.eventsourcingdb.library.book-acquired");
+const eventType = await client.readEventType('io.eventsourcingdb.library.book-acquired');
 ```
 
+If there are neither events of this type nor a registered schema, the function throws a `DbApiError` with the code `ErrorCode.eventTypeUnknown`.
+
 ### Verifying an Event's Hash
 
-To verify the integrity of an event, call the `verifyHash` function on the event instance. This recomputes the event's hash locally and compares it to the hash stored in the event. If the hashes differ, the function returns an error:
+To verify the integrity of an event, call the `verifyHash` function on the event instance. This recomputes the event's hash locally and compares it to the hash stored in the event. If the hashes differ, or if the event's `data` has been changed since it was received, the function throws a `HashVerificationFailedError`:
 
 ```typescript
 event.verifyHash();
 ```
 
+The hash of an event tells its version. A hash that starts with `esdb:hash:v2:` is of version 2, which EventSourcingDB writes since version 1.3. A hash without a prefix is of version 1, which events written before keep. `verifyHash` supports both. If the hash is of a version the client SDK does not know, the function throws an `UnsupportedHashVersionError` that names the version, since such a hash cannot be verified, rather than being invalid:
+
+```typescript
+import { HashVerificationFailedError, UnsupportedHashVersionError } from 'eventsourcingdb';
+
+try {
+  event.verifyHash();
+} catch (error) {
+  if (error instanceof HashVerificationFailedError) {
+    // ...
+  }
+  if (error instanceof UnsupportedHashVersionError) {
+    // ...
+  }
+}
+```
+
 *Note that this only verifies the hash. If you also want to verify the signature, you can skip this step and call `verifySignature` directly, which performs a hash verification internally.*
 
 ### Verifying an Event's Signature
 
 To verify the authenticity of an event, call the `verifySignature` function on the event instance. This requires the public key that matches the private key used for signing on the server.
 
-The function first verifies the event's hash, and then checks the signature. If any verification step fails, it returns an error:
+The function first verifies the event's hash, and then checks the signature. If any verification step fails, it throws an error, for example a `SignatureVerificationFailedError` if the signature is invalid:
 
 ```typescript
 const verificationKey = // an ed25519 public key
@@ -570,3 +724,94 @@ In case you need to set up the client yourself, use the following functions to g
 - `getMappedPort()` returns the port
 - `getBaseUrl()` returns the full URL of the container
 - `getApiToken()` returns the API token
+
+## Upgrading From Version 1
+
+Version 2 of this client SDK speaks the v2 API of EventSourcingDB 1.3 as well as the v1 API of older versions, see [Choosing the API](#choosing-the-api). It brings the following breaking changes:
+
+- **Event types:** An event type names its type in the field `type` instead of `eventType`, and tells whether it has events in the field `hasEvents` instead of `isPhantom`, which meant the opposite.
+
+  ```typescript
+  // Before
+  if (!eventType.isPhantom) {
+    console.log(eventType.eventType);
+  }
+
+  // After
+  if (eventType.hasEvents) {
+    console.log(eventType.type);
+  }
+  ```
+
+- **Listing subjects:** `readSubjects` takes the subject and an options object with the required `recursive` option, instead of a base subject alone. Calling it without the option throws an error. To keep the previous behavior, set `recursive` to `true`. The abort signal moves from the second to the third argument.
+
+  ```typescript
+  // Before
+  client.readSubjects('/books', signal);
+
+  // After
+  client.readSubjects('/books', { recursive: true }, signal);
+  ```
+
+- **Errors of the server:** Every error that the server reports throws a `DbApiError` with `code`, `description`, `details`, `status`, and `retryAfter`, instead of an `Error` whose message names the HTTP status, see [Handling Errors](#handling-errors).
+
+  ```typescript
+  // Before
+  if (error instanceof Error && error.message.includes("'409'")) {
+    // ...
+  }
+
+  // After
+  if (error instanceof DbApiError && error.code === ErrorCode.preconditionViolated) {
+    // ...
+  }
+  ```
+
+- **Stalled streams:** `HeartbeatTimeoutError` is gone. A stream in which neither an item nor a heartbeat arrives in time throws a `ConnectionStalledError`, as every other request that stalls does, whose `cause` has the `code` `UND_ERR_BODY_TIMEOUT`.
+
+  ```typescript
+  // Before
+  if (error instanceof HeartbeatTimeoutError) {
+    // ...
+  }
+
+  // After
+  if (error instanceof ConnectionStalledError) {
+    // ...
+  }
+  ```
+
+- **Failed writes:** `writeEvents` and `registerEventSchema` throw an `OutcomeUnknownError`, whose `cause` is the original error, whenever the write may have been stored nonetheless, see [Knowing Whether a Write Was Stored](#knowing-whether-a-write-was-stored). This includes aborting the signal once the write has been sent, which threw the reason of the abort before, and a write that stalls, which threw a `ConnectionStalledError` before.
+
+  ```typescript
+  // Before
+  if (error instanceof ConnectionStalledError) {
+    // ...
+  }
+
+  // After
+  if (error instanceof OutcomeUnknownError && error.cause instanceof ConnectionStalledError) {
+    // ...
+  }
+  ```
+
+- **Observing that ends:** A stream of observed events that the server closes without reporting an error throws an error, instead of ending the iteration quietly. Stopping with `break`, `return`, or an abort signal still ends it without an error.
+
+  ```typescript
+  // Before
+  for await (const event of client.observeEvents('/books', { recursive: true })) {
+    // ...
+  }
+  // Reached once the server closed the stream.
+
+  // After
+  try {
+    for await (const event of client.observeEvents('/books', { recursive: true })) {
+      // ...
+    }
+  } catch (error) {
+    // Reached once the server closed the stream.
+  }
+  ```
+
+- **Reading through a proxy:** Against EventSourcingDB 1.3 and later, the functions that read use the HTTP method `QUERY` instead of `POST`, which a proxy in front of the database has to let through, see [Choosing the API](#choosing-the-api).

package/dist/Client.d.ts

@@ -1,21 +1,23 @@
+import type { ClientOptions } from './ClientOptions.js';
 import type { Event } from './Event.js';
 import type { EventCandidate } from './EventCandidate.js';
 import type { EventType } from './EventType.js';
 import type { ObserveEventsOptions } from './ObserveEventsOptions.js';
 import type { Precondition } from './Precondition.js';
 import type { ReadEventsOptions } from './ReadEventsOptions.js';
+import type { ReadSubjectsOptions } from './ReadSubjectsOptions.js';
 declare class Client {
     #private;
-    constructor(url: URL, apiToken: string);
-    ping(): Promise<void>;
-    verifyApiToken(): Promise<void>;
-    writeEvents(events: EventCandidate[], preconditions?: Precondition[]): Promise<Event[]>;
+    constructor(url: URL, apiToken: string, options?: ClientOptions);
+    ping(signal?: AbortSignal): Promise<void>;
+    verifyApiToken(signal?: AbortSignal): Promise<void>;
+    writeEvents(events: EventCandidate[], preconditions?: Precondition[], signal?: AbortSignal): Promise<Event[]>;
     readEvents(subject: string, options: ReadEventsOptions, signal?: AbortSignal): AsyncGenerator<Event, void, void>;
     runEventQlQuery(query: string, signal?: AbortSignal): AsyncGenerator<unknown, void, void>;
     observeEvents(subject: string, options: ObserveEventsOptions, signal?: AbortSignal): AsyncGenerator<Event, void, void>;
-    registerEventSchema(eventType: string, schema: Record<string, unknown>): Promise<void>;
-    readSubjects(baseSubject: string, signal?: AbortSignal): AsyncGenerator<string, void, void>;
-    readEventType(eventType: string): Promise<EventType>;
+    registerEventSchema(eventType: string, schema: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
+    readSubjects(subject: string, options: ReadSubjectsOptions, signal?: AbortSignal): AsyncGenerator<string, void, void>;
+    readEventType(eventType: string, signal?: AbortSignal): Promise<EventType>;
     readEventTypes(signal?: AbortSignal): AsyncGenerator<EventType, void, void>;
 }
 export { Client };