### Install and Initialize EventSourcingDB Client (JavaScript/TypeScript)

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Demonstrates how to install the EventSourcingDB client SDK using npm and initialize a client instance with a server URL and API token. It also shows how to ping the server to check reachability and verify the API token.

```shell
npm install eventsourcingdb
```

```typescript
import { Client } from 'eventsourcingdb';

const url = new URL('http://localhost:3000');
const apiToken = 'secret';

const client = new Client(url, apiToken);

// Check server reachability
await client.ping();

// Verify API token
await client.verifyApiToken();
```

--------------------------------

### Read Subjects with EventSourcingDB Client

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Demonstrates the usage of the `readSubjects` method to list available subjects in the database. Examples show how to list all subjects, subjects under a specific path, and how to use an `AbortController` to cancel the read operation.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// List all subjects in the database
for await (const subject of client.readSubjects('/')) {
  console.log(`Subject: ${subject}`);
}

// List subjects under a specific branch
for await (const subject of client.readSubjects('/books')) {
  console.log(`Book subject: ${subject}`);
}

// With abort signal
const controller = new AbortController();
for await (const subject of client.readSubjects('/', controller.signal)) {
  console.log(`Subject: ${subject}`);
  if (subject === '/books/42') {
    controller.abort();
    break;
  }
}
```

--------------------------------

### Start Reading from Latest Event

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Starts reading from the latest event of a given type. If the event is missing, it can either skip reading ('read-nothing') or read all events ('read-everything'). Cannot be used with 'lowerBound'.

```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'
  }
})) {
  // ...
}
```

--------------------------------

### Manage Testcontainers

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Demonstrates the lifecycle of an EventSourcingDB test container, including starting, stopping, and checking the status of the container instance.

```typescript
import { Container } from 'eventsourcingdb';

const container = new Container();
await container.start();

const client = container.getClient();

// ...

await container.stop();

const isRunning = container.isRunning();
```

--------------------------------

### Run EventQL Queries with EventSourcingDB Client

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Shows how to execute EventQL queries using the `runEventQlQuery` method. Examples include querying all events, filtering events based on type and data, and performing aggregations like counting events. EventQL is a specialized query language for event sourcing data.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// Query all events
for await (const row of client.runEventQlQuery(
  `
  FROM e IN events
  PROJECT INTO e
`
)) {
  console.log('Event:', row);
}

// Query with filtering
for await (const row of client.runEventQlQuery(
  `
  FROM e IN events
  WHERE e.type == 'io.eventsourcingdb.library.book-borrowed'
  PROJECT INTO { borrower: e.data.borrower, subject: e.subject }
`
)) {
  console.log(`Book ${row.subject} borrowed by ${row.borrower}`);
}

// Aggregation query
for await (const row of client.runEventQlQuery(
  `
  FROM e IN events
  WHERE e.type == 'io.eventsourcingdb.library.book-borrowed'
  PROJECT INTO COUNT()
`
)) {
  console.log(`Total borrows: ${row}`);
}
```

--------------------------------

### GET /observeEvents

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Observes events on a subject in real-time.

```APIDOC
## GET /observeEvents

### Description
Subscribes to a stream of events for a given subject.

### Method
GET (via client.observeEvents)

### Parameters
- **subject** (string) - Required - The subject path to observe.
- **options** (object) - Required - { recursive: boolean }.

### Request Example
client.observeEvents('/books/42', { recursive: false })

### Response
#### Success Response (200)
- **event** (object) - An asynchronous iterator of incoming events.
```

--------------------------------

### Observe Events in Real-time with EventSourcingDB Client

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Demonstrates how to use the `observeEvents` method to subscribe to real-time event streams. It covers basic observation, resuming from a specific point using `lowerBound`, and starting from the latest event of a type with `fromLatestEvent`. This method keeps the connection open to yield new events as they are written.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');
const controller = new AbortController();

// Observe events in real-time
for await (const event of client.observeEvents('/books', {
  recursive: true
}, controller.signal)) {
  console.log(`New event received: ${event.type}`);
  console.log(`Subject: ${event.subject}`);
  console.log(`Data: ${JSON.stringify(event.data)}`);
}

// Observe with lower bound (resume from specific point)
for await (const event of client.observeEvents('/books/42', {
  recursive: false,
  lowerBound: { id: '50', type: 'exclusive' }
}, controller.signal)) {
  console.log(`Event after ID 50: ${event.id}`);
}

// Observe starting from latest event of a type
for await (const event of client.observeEvents('/books/42', {
  recursive: false,
  fromLatestEvent: {
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.checkpoint',
    ifEventIsMissing: 'wait-for-event'
  }
}, controller.signal)) {
  console.log(`Event since checkpoint: ${event.type}`);
}
```

--------------------------------

### Observe Events API

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

This API allows you to subscribe to real-time events. It keeps the connection open and yields new events as they are written, with options to specify a base path, recursion, lower bound, or start from the latest event.

```APIDOC
## Observe Events

The `observeEvents` method creates a real-time subscription to events. Unlike `readEvents`, this keeps the connection open and yields new events as they are written.

### Method
`client.observeEvents(basePath, options, signal)`

### Parameters
#### Path Parameters
- **basePath** (string) - Required - The base path to observe events from.

#### Query Parameters
- **options** (object) - Optional - Configuration for the observation.
  - **recursive** (boolean) - Optional - Whether to observe events recursively under the basePath. Defaults to false.
  - **lowerBound** (object) - Optional - Specifies a point to resume observation from.
    - **id** (string) - Required - The ID of the event to start after.
    - **type** (string) - Required - The type of the lower bound ('exclusive' or 'inclusive').
  - **fromLatestEvent** (object) - Optional - Specifies to start observing from the latest event of a specific type.
    - **subject** (string) - Required - The subject of the event.
    - **type** (string) - Required - The type of the event.
    - **ifEventIsMissing** (string) - Optional - Action to take if the specified event is missing ('wait-for-event' or 'skip'). Defaults to 'wait-for-event'.
- **signal** (AbortSignal) - Optional - An AbortSignal to cancel the observation.

### Request Example
```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');
const controller = new AbortController();

// Observe events in real-time
for await (const event of client.observeEvents('/books', {
  recursive: true
}, controller.signal)) {
  console.log(`New event received: ${event.type}`);
  console.log(`Subject: ${event.subject}`);
  console.log(`Data: ${JSON.stringify(event.data)}`);
}

// Observe with lower bound (resume from specific point)
for await (const event of client.observeEvents('/books/42', {
  recursive: false,
  lowerBound: { id: '50', type: 'exclusive' }
}, controller.signal)) {
  console.log(`Event after ID 50: ${event.id}`);
}

// Observe starting from latest event of a type
for await (const event of client.observeEvents('/books/42', {
  recursive: false,
  fromLatestEvent: {
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.checkpoint',
    ifEventIsMissing: 'wait-for-event'
  }
}, controller.signal)) {
  console.log(`Event since checkpoint: ${event.type}`);
}
```

### Response
#### Success Response (Iterator)
- **event** (object) - An object representing the event received.
  - **id** (string) - The unique identifier of the event.
  - **source** (string) - The source of the event.
  - **subject** (string) - The subject the event pertains to.
  - **type** (string) - The type of the event.
  - **data** (object) - The payload of the event.
  - **timestamp** (string) - The timestamp when the event was created.

#### Response Example
```json
{
  "id": "event-id-123",
  "source": "https://example.com",
  "subject": "/books/123",
  "type": "io.eventsourcingdb.library.book-acquired",
  "data": {
    "title": "Example Book",
    "author": "Author Name"
  },
  "timestamp": "2023-10-27T10:00:00Z"
}
```
```

--------------------------------

### Register Event Schema with EventSourcingDB Client

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Illustrates how to register a JSON Schema for a specific event type using `registerEventSchema`. This ensures that all subsequent events of that type are validated against the provided schema during writes. The example shows registering a schema for 'io.eventsourcingdb.library.book-acquired' and then writing a validated event.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

await client.registerEventSchema('io.eventsourcingdb.library.book-acquired', {
  type: 'object',
  properties: {
    title: { type: 'string' },
    author: { type: 'string' },
    isbn: { type: 'string' }
  },
  required: ['title', 'author', 'isbn'],
  additionalProperties: false
});

console.log('Schema registered successfully');

// Now writing events of this type will be validated
const events = await client.writeEvents([
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/123',
    type: 'io.eventsourcingdb.library.book-acquired',
    data: {
      title: 'The Pragmatic Programmer',
      author: 'David Thomas, Andrew Hunt',
      isbn: '978-0135957059'
    }
  }
]);
```

--------------------------------

### Read Events with Ordering and Bounds using TypeScript

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Illustrates advanced event reading capabilities, including specifying the order of events (chronological or antichronological) and setting bounds based on event IDs. It also shows how to read events starting from the latest event of a specific type.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// Read in reverse chronological order
for await (const event of client.readEvents('/books/42', {
  recursive: false,
  order: 'antichronological'
})) {
  console.log(`Event ${event.id}: ${event.type}`);
}

// Read events within a specific ID range
for await (const event of client.readEvents('/books/42', {
  recursive: false,
  lowerBound: { id: '100', type: 'inclusive' },
  upperBound: { id: '200', type: 'exclusive' }
})) {
  console.log(`Event ${event.id} in range [100, 200)`);
}

// Read starting from the latest event of a given type
for await (const event of client.readEvents('/books/42', {
  recursive: false,
  fromLatestEvent: {
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.book-borrowed',
    ifEventIsMissing: 'read-everything'
  }
})) {
  console.log(`Event since last borrow: ${event.type}`);
}
```

--------------------------------

### Observe Events from Latest - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Observe events starting from the latest event of a specific type using the 'fromLatestEvent' option. Configure behavior for missing events with 'wait-for-event' or 'read-everything'. Cannot be used with 'lowerBound'.

```typescript
for await (const event of client.observeEvents('/books/42', {
  recursive: false,
  fromLatestEvent: {
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.book-borrowed',
    ifEventIsMissing: 'read-everything'
  }
})) {
  // ...
}
```

--------------------------------

### Read Events with TypeScript

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Shows how to read events from a subject using the `readEvents` method. It returns an async iterator that can be used to process events one by one. Examples include reading from a specific subject, recursively reading from a subject tree, and reading all events in the database.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// Read events from a specific subject
for await (const event of client.readEvents('/books/42', { recursive: false })) {
  console.log(`Event: ${event.type} - ${JSON.stringify(event.data)}`);
}

// Read all events recursively from a subject tree
for await (const event of client.readEvents('/books', { recursive: true })) {
  console.log(`Subject: ${event.subject}, Type: ${event.type}`);
}

// Read all events in the database
for await (const event of client.readEvents('/', { recursive: true })) {
  console.log(`ID: ${event.id}, Subject: ${event.subject}`);
}
```

--------------------------------

### Read Events with Abort Signal using TypeScript

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Demonstrates how to cancel long-running event reading operations using an `AbortController` signal. This is useful for implementing timeouts or allowing users to stop processes manually. The example shows setting a timeout and aborting based on a condition within the event stream.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');
const controller = new AbortController();

// Set timeout to abort after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  for await (const event of client.readEvents('/', { recursive: true }, controller.signal)) {
    console.log(`Processing event ${event.id}`);

    // Manually abort based on condition
    if (event.type === 'io.eventsourcingdb.library.stop-processing') {
      controller.abort();
    }
  }
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Reading was aborted');
  } else {
    throw error;
  }
}
```

--------------------------------

### GET /readEvents

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Reads events from a specific subject with support for recursion, ordering, bounds, and abort signals.

```APIDOC
## GET /readEvents

### Description
Reads events from a subject. Supports recursive reading, chronological/anti-chronological ordering, and range-based bounds.

### Method
GET (via client.readEvents)

### Parameters
#### Path Parameters
- **subject** (string) - Required - The subject path to read from.

#### Query Parameters
- **recursive** (boolean) - Optional - If true, includes events from nested subjects.
- **order** (string) - Optional - 'chronological' or 'antichronological'.
- **lowerBound** (object) - Optional - { id: string, type: 'inclusive' | 'exclusive' }.
- **upperBound** (object) - Optional - { id: string, type: 'inclusive' | 'exclusive' }.

### Request Example
client.readEvents('/books/42', { recursive: true, order: 'antichronological' })

### Response
#### Success Response (200)
- **event** (object) - An asynchronous iterator of event objects.
```

--------------------------------

### Initialize EventSourcingDB Client

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Demonstrates how to instantiate the Client class using a database URL and an API token. This is the primary entry point for all database operations.

```typescript
import { Client } from 'eventsourcingdb';

const url = new URL('http://localhost:3000');
const apiToken = 'your-api-token';

const client = new Client(url, apiToken);
```

--------------------------------

### Configure Container Instance

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Configures a container instance with custom image tags, ports, API tokens, and cryptographic signing keys.

```typescript
const container = new Container()
  .withImageTag('1.0.0')
  .withPort(4000)
  .withApiToken('secret')
  .withSigningKey();

const signingKey = container.getSigningKey();
const verificationKey = container.getVerificationKey();
```

--------------------------------

### Write Events with EventSourcingDB Client (JavaScript/TypeScript)

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Shows how to write events to EventSourcingDB using the `writeEvents` function. It covers basic event writing and demonstrates various preconditions like `isSubjectPristine`, `isSubjectPopulated`, `isSubjectOnEventId`, and `isEventQlQueryTrue` to control event writing based on the current state of a subject or query results.

```typescript
import { Client, isSubjectPristine, isSubjectPopulated, isSubjectOnEventId, isEventQlQueryTrue } from 'eventsourcingdb';

const url = new URL('http://localhost:3000');
const apiToken = 'secret';
const client = new Client(url, apiToken);

// Basic event writing
const writtenEvents = await client.writeEvents([
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.book-acquired',
    data: {
      title: '2001 – A Space Odyssey',
      author: 'Arthur C. Clarke',
      isbn: '978-0756906788'
    }
  }
]);

// Writing with isSubjectPristine precondition
await client.writeEvents([
  // events
], [
  isSubjectPristine('/books/42')
]);

// Writing with isSubjectPopulated precondition
await client.writeEvents([
  // events
], [
  isSubjectPopulated('/books/42')
]);

// Writing with isSubjectOnEventId precondition
await client.writeEvents([
  // events
], [
  isSubjectOnEventId('/books/42', '0')
]);

// Writing with isEventQlQueryTrue precondition
await client.writeEvents([
  // events
], [
  isEventQlQueryTrue(`FROM e IN events WHERE e.type == 'io.eventsourcingdb.library.book-borrowed' PROJECT INTO COUNT() < 10`)
]);
```

--------------------------------

### Write Events with Preconditions using TypeScript

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Demonstrates writing events to EventSourcingDB with various preconditions. It shows how to use functions like `isSubjectPristine`, `isSubjectPopulated`, `isSubjectOnEventId`, and `isEventQlQueryTrue` to ensure events are written only when specific conditions are met. This is crucial for maintaining data integrity and implementing optimistic concurrency control.

```typescript
import {
  Client,
  isSubjectPristine,
  isSubjectPopulated,
  isSubjectOnEventId,
  isEventQlQueryTrue
} from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// Write only if subject has no events
const newBookEvents = await client.writeEvents([
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/100',
    type: 'io.eventsourcingdb.library.book-acquired',
    data: { title: 'New Book', author: 'New Author', isbn: '123-456' }
  }
], [isSubjectPristine('/books/100')]);

// Write only if subject already has events
const updateEvents = await client.writeEvents([
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.book-updated',
    data: { title: 'Updated Title' }
  }
], [isSubjectPopulated('/books/42')]);

// Write only if subject is at specific event ID (optimistic concurrency)
const conditionalEvents = await client.writeEvents([
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.book-returned',
    data: { returnedAt: '2024-01-20T14:00:00Z' }
  }
], [isSubjectOnEventId('/books/42', '5')]);

// Write only if EventQL query returns true
const limitedBorrowEvents = await client.writeEvents([
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.book-borrowed',
    data: { borrower: 'Jane Doe' }
  }
], [isEventQlQueryTrue(`FROM e IN events WHERE e.type == 'io.eventsourcingdb.library.book-borrowed' PROJECT INTO COUNT() < 10`)]);
```

--------------------------------

### POST /runEventQlQuery

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Executes an EventQL query and returns an asynchronous iterator of the results.

```APIDOC
## POST /runEventQlQuery

### Description
Runs a custom EventQL query against the database.

### Method
POST (via client.runEventQlQuery)

### Parameters
- **query** (string) - Required - The EventQL query string.
- **signal** (AbortSignal) - Optional - An AbortSignal to cancel the query execution.

### Request Example
client.runEventQlQuery('FROM e IN events PROJECT INTO e')

### Response
#### Success Response (200)
- **row** (object) - An asynchronous iterator of rows matching the projection.
```

--------------------------------

### Run EventQL Queries API

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

This API allows you to execute EventQL queries against the database. EventQL is a powerful query language for filtering, projecting, and aggregating events.

```APIDOC
## Run EventQL Queries

The `runEventQlQuery` method executes EventQL queries against the database. EventQL is a query language designed for event sourcing that allows filtering, projecting, and aggregating events.

### Method
`client.runEventQlQuery(query)`

### Parameters
#### Query Parameters
- **query** (string) - Required - The EventQL query string.

### Request Example
```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// Query all events
for await (const row of client.runEventQlQuery(`
  FROM e IN events
  PROJECT INTO e
`)) {
  console.log('Event:', row);
}

// Query with filtering
for await (const row of client.runEventQlQuery(`
  FROM e IN events
  WHERE e.type == 'io.eventsourcingdb.library.book-borrowed'
  PROJECT INTO { borrower: e.data.borrower, subject: e.subject }
`)) {
  console.log(`Book ${row.subject} borrowed by ${row.borrower}`);
}

// Aggregation query
for await (const row of client.runEventQlQuery(`
  FROM e IN events
  WHERE e.type == 'io.eventsourcingdb.library.book-borrowed'
  PROJECT INTO COUNT()
`)) {
  console.log(`Total borrows: ${row}`);
}
```

### Response
#### Success Response (Iterator)
- **row** (any) - The result of the query, which can be an event object, a projected object, or an aggregated value, depending on the query.

#### Response Example
```json
{
  "borrower": "Alice",
  "subject": "/books/123"
}
```

```json
50
```
```

--------------------------------

### Read Events from EventSourcingDB Client (JavaScript/TypeScript)

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Illustrates how to read events for a specific subject using the `readEvents` function. It shows how to configure the read operation, such as setting `recursive: false` to only retrieve events for the exact subject, and how to iterate over the returned asynchronous iterator.

```typescript
import { Client } from 'eventsourcingdb';

const url = new URL('http://localhost:3000');
const apiToken = 'secret';
const client = new Client(url, apiToken);

// Read events for a specific subject, non-recursively
for await (const event of client.readEvents('/books/42', {
  recursive: false
})) {
  // Process each event
  console.log(event);
}
```

--------------------------------

### Verify Event Integrity

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Demonstrates how to verify event integrity using cryptographic hashes and digital signatures. This ensures that events have not been tampered with since they were written.

```typescript
import { Client } from 'eventsourcingdb';
import crypto from 'node:crypto';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// Verify Hash
for await (const event of client.readEvents('/books/42', { recursive: false })) {
  try {
    event.verifyHash();
    console.log(`Event ${event.id} hash verified successfully`);
  } catch (error) {
    console.error(`Event ${event.id} hash verification failed:`, error.message);
  }
}

// Verify Signature
const verificationKey = crypto.createPublicKey({
  key: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----',
  format: 'pem'
});

for await (const event of client.readEvents('/books/42', { recursive: false })) {
  try {
    event.verifySignature(verificationKey);
    console.log(`Event ${event.id} signature verified`);
  } catch (error) {
    console.error(`Event ${event.id} signature verification failed:`, error.message);
  }
}
```

--------------------------------

### Run EventQL Query

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Executes an EventQL query and returns an asynchronous iterator for the results. Each row corresponds to the projection specified in the query.

```typescript
for await (const row of client.runEventQlQuery(
  `
  FROM e IN events
  PROJECT INTO e
`
)) {
  // ...
}
```

--------------------------------

### Read Event Types with EventSourcingDB Client

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Explains how to use the `readEventTypes` method to retrieve a list of all event types present in the database. The output includes the event type name, whether it's a phantom event, and its registered schema if available.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// List all event types
for await (const eventType of client.readEventTypes()) {
  console.log(`Event type: ${eventType.eventType}`);
  console.log(`Is phantom: ${eventType.isPhantom}`);
  if (eventType.schema) {
    console.log(`Schema: ${JSON.stringify(eventType.schema)}`);
  }
}
```

--------------------------------

### Manage Integration Test Containers

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Utilizes Testcontainers to spin up and configure isolated EventSourcingDB instances for testing. Includes lifecycle management and custom configuration options.

```typescript
import { Container } from 'eventsourcingdb';

// Basic usage
const container = new Container();
await container.start();
const client = container.getClient();
await client.writeEvents([{ source: 'https://test.example.com', subject: '/test/1', type: 'io.test.event-created', data: { message: 'Hello' } }]);
await container.stop();

// Advanced configuration
const configContainer = new Container()
  .withImageTag('1.0.0')
  .withPort(4000)
  .withApiToken('my-test-token')
  .withSigningKey();

await configContainer.start();
console.log(`Base URL: ${configContainer.getBaseUrl()}`);
await configContainer.stop();
```

--------------------------------

### Check Database Connectivity

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Uses the ping method to verify if the EventSourcingDB instance is reachable. This operation does not require authentication.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

try {
  await client.ping();
  console.log('EventSourcingDB is reachable');
} catch (error) {
  console.error('Failed to connect to EventSourcingDB:', error.message);
}
```

--------------------------------

### Abort EventQL Query with AbortSignal

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Aborts an EventQL query execution independently of the loop by providing an AbortSignal to the runEventQlQuery function. This requires an AbortController.

```typescript
const controller = new AbortController();

for await (const row of client.runEventQlQuery(
  `
  FROM e IN events
  PROJECT INTO e
`,
  controller.signal
)) {
  // ...
}

// Somewhere else, abort the controller, which will cause
// the query to end.
controller.abort();
```

--------------------------------

### Observe Events with Lower Bound - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Observe events within a specified range by setting the 'lowerBound' option. This allows for targeted event retrieval based on event ID and inclusion/exclusion criteria. It cannot be used with 'fromLatestEvent'.

```typescript
for await (const event of client.observeEvents('/books/42', {
  recursive: false,
  lowerBound: { id: '100', type: 'inclusive' }
})) {
  // ...
}
```

--------------------------------

### Read Event Types API

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

This API lists all event types that have been written to the database, including schema information if registered.

```APIDOC
## Read Event Types

The `readEventTypes` method lists all event types that have been written to the database, including schema information if registered.

### Method
`client.readEventTypes()`

### Parameters
None

### Request Example
```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// List all event types
for await (const eventType of client.readEventTypes()) {
  console.log(`Event type: ${eventType.eventType}`);
  console.log(`Is phantom: ${eventType.isPhantom}`);
  if (eventType.schema) {
    console.log(`Schema: ${JSON.stringify(eventType.schema)}`);
  }
}
```

### Response
#### Success Response (Iterator)
- **eventType** (object) - An object containing information about an event type.
  - **eventType** (string) - The name of the event type.
  - **isPhantom** (boolean) - Indicates if the event type is considered phantom (e.g., used for internal state changes).
  - **schema** (object | null) - The registered JSON Schema for this event type, or null if none is registered.

#### Response Example
```json
{
  "eventType": "io.eventsourcingdb.library.book-acquired",
  "isPhantom": false,
  "schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "author": { "type": "string" },
      "isbn": { "type": "string" }
    },
    "required": ["title", "author", "isbn"],
    "additionalProperties": false
  }
}
```
```

--------------------------------

### Verify Event Signature

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Verifies the authenticity of an event by checking its hash and signature against a provided ed25519 public key. Throws an error if verification fails.

```typescript
const verificationKey = // an ed25519 public key
event.verifySignature(verificationKey);
```

--------------------------------

### Read Subjects API

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

This API lists all subjects that have events under a given base subject path, allowing you to explore the structure of your event data.

```APIDOC
## Read Subjects

The `readSubjects` method lists all subjects that have events under a given base subject path.

### Method
`client.readSubjects(basePath, signal)`

### Parameters
#### Path Parameters
- **basePath** (string) - Required - The base path to list subjects from.

#### Query Parameters
- **signal** (AbortSignal) - Optional - An AbortSignal to cancel the operation.

### Request Example
```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

// List all subjects in the database
for await (const subject of client.readSubjects('/')) {
  console.log(`Subject: ${subject}`);
}

// List subjects under a specific branch
for await (const subject of client.readSubjects('/books')) {
  console.log(`Book subject: ${subject}`);
}

// With abort signal
const controller = new AbortController();
for await (const subject of client.readSubjects('/', controller.signal)) {
  console.log(`Subject: ${subject}`);
  if (subject === '/books/42') {
    controller.abort();
    break;
  }
}
```

### Response
#### Success Response (Iterator)
- **subject** (string) - The name of a subject found under the basePath.

#### Response Example
```
/books
/books/123
/users
```
```

--------------------------------

### Write CloudEvents to Database

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Persists one or more events to the database using the writeEvents method. Events must adhere to the CloudEvents format, and the method returns the confirmed events with server-generated metadata.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

const writtenEvents = await client.writeEvents([
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.book-acquired',
    data: {
      title: '2001 – A Space Odyssey',
      author: 'Arthur C. Clarke',
      isbn: '978-0756906788'
    }
  },
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/42',
    type: 'io.eventsourcingdb.library.book-borrowed',
    data: {
      borrower: 'John Doe',
      borrowedAt: '2024-01-15T10:30:00Z'
    }
  }
]);

for (const event of writtenEvents) {
  console.log(`Event written - ID: ${event.id}, Type: ${event.type}`);
}
```

--------------------------------

### Register Event Schema API

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

This API allows you to register a JSON Schema for a specific event type. EventSourcingDB will then validate events of that type during writes.

```APIDOC
## Register Event Schema

The `registerEventSchema` method registers a JSON Schema for validating events of a specific type. Once registered, EventSourcingDB validates events against the schema during writes.

### Method
`client.registerEventSchema(eventTypeName, schema)`

### Parameters
#### Path Parameters
- **eventTypeName** (string) - Required - The name of the event type to register the schema for.
- **schema** (object) - Required - The JSON Schema object for validation.

### Request Example
```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

await client.registerEventSchema('io.eventsourcingdb.library.book-acquired', {
  type: 'object',
  properties: {
    title: { type: 'string' },
    author: { type: 'string' },
    isbn: { type: 'string' }
  },
  required: ['title', 'author', 'isbn'],
  additionalProperties: false
});

console.log('Schema registered successfully');

// Now writing events of this type will be validated
const events = await client.writeEvents([
  {
    source: 'https://library.eventsourcingdb.io',
    subject: '/books/123',
    type: 'io.eventsourcingdb.library.book-acquired',
    data: {
      title: 'The Pragmatic Programmer',
      author: 'David Thomas, Andrew Hunt',
      isbn: '978-0135957059'
    }
  }
]);
```

### Response
#### Success Response (204 No Content)
Indicates that the schema was registered successfully.

#### Error Response (400 Bad Request)
Returned if the provided schema is invalid or if the event type name is invalid.
```

--------------------------------

### Read Event Type Details

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Retrieves the metadata and schema definition for a specific event type. This is useful for validating event structures before processing.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

const eventType = await client.readEventType('io.eventsourcingdb.library.book-acquired');

console.log(`Event type: ${eventType.eventType}`);
console.log(`Is phantom: ${eventType.isPhantom}`);
if (eventType.schema) {
  console.log(`Schema properties:`, Object.keys(eventType.schema.properties || {}));
}
```

--------------------------------

### Read Events in Anti-Chronological Order

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Reads events in anti-chronological order by setting the 'order' option to 'antichronological'. The default order is chronological, which can also be explicitly specified.

```typescript
for await (const event of client.readEvents('/books/42', {
  recursive: false,
  order: 'antichronological'
})) {
  // ...
}
```

--------------------------------

### Validate API Token

Source: https://context7.com/thenativeweb/eventsourcingdb-client-javascript/llms.txt

Verifies the authenticity of the provided API token against the server. Throws an error if the token is invalid.

```typescript
import { Client } from 'eventsourcingdb';

const client = new Client(new URL('http://localhost:3000'), 'secret');

try {
  await client.verifyApiToken();
  console.log('API token is valid');
} catch (error) {
  console.error('Invalid API token:', error.message);
}
```

--------------------------------

### Observe Events Recursively for a Subject

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Observes events for a subject and all its nested subjects by setting the 'recursive' option to true. This can be used to observe all events by specifying the root subject '/'.

```typescript
for await (const event of client.observeEvents('/books/42', {
  recursive: true
})) {
  // ...
}
```

--------------------------------

### List Event Types - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

List all available event types in the event store by calling the 'readEventTypes' function. The result is an asynchronous iterator for easy iteration over event type names.

```typescript
for await (const eventType of client.readEventTypes()) {
  // ...
}
```

--------------------------------

### Verify Event Hash - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Verify the integrity of an event by calling its 'verifyHash' method. This locally recomputes the event's hash and compares it to the stored hash, returning an error if they do not match.

```typescript
event.verifyHash();
```

--------------------------------

### Read Events within Specified Bounds

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Reads a range of events by specifying 'lowerBound' and 'upperBound' options. Each bound can include or exclude an event ID.

```typescript
for await (const event of client.readEvents('/books/42', {
  recursive: false,
  lowerBound: { id: '100', type: 'inclusive' },
  upperBound: { id: '200', type: 'exclusive' }
})) {
  // ...
}
```

--------------------------------

### List Subjects - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

List all subjects within the event store using the 'readSubjects' function. This function returns an asynchronous iterator that can be used to traverse the subject hierarchy, optionally specifying a base path.

```typescript
for await (const subject of client.readSubjects('/')) {
  // ...
}
```

```typescript
for await (const subject of client.readSubjects('/books')) {
  // ...
}
```

--------------------------------

### Register Event Schema - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Register a new event schema by calling the 'registerEventSchema' function with the event type and its corresponding JSON schema definition. This ensures data consistency for events of that type.

```typescript
await client.registerEventSchema('io.eventsourcingdb.library.book-acquired', {
  type: 'object',
  properties: {
    title: { type: 'string' },
    author: { type: 'string' },
    isbn: { type: 'string' }
  },
  required: [
    'title',
    'author',
    'isbn'
  ],
  additionalProperties: false
});
```

--------------------------------

### Abort Reading Events with AbortSignal

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Aborts the event reading process independently of the loop by providing an AbortSignal to the readEvents function. This requires an AbortController.

```typescript
const controller = new AbortController();

for await (const event of client.readEvents('/books/42', {
  recursive: false
}, controller.signal)) {
  // ...
}

// Somewhere else, abort the controller, which will cause
// reading to end.
controller.abort();
```

--------------------------------

### Read Events Recursively with Client

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Reads events from a subject and all its nested subjects by setting the 'recursive' option to true. This can be used to read all events by specifying the root subject '/'.

```typescript
for await (const event of client.readEvents('/books/42', {
  recursive: true
})) {
  // ...
}
```

--------------------------------

### Observe Events for a Subject

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Observes events for a specific subject without including nested subjects by setting 'recursive' to false. Returns an asynchronous iterator.

```typescript
for await (const event of client.observeEvents('/books/42', {
  recursive: false
})) {
  // ...
}
```

--------------------------------

### Abort Subject Listing - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Abort the listing of subjects asynchronously by providing an AbortSignal to the readSubjects function. This enables external control over the subject iteration process.

```typescript
const controller = new AbortController();

for await (const subject of client.readSubjects(
  '/', controller.signal)
) {
  // ...
}

// Somewhere else, abort the controller, which will cause
// reading to end.
controller.abort();
```

--------------------------------

### Abort Event Observation - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Abort event observation asynchronously by providing an AbortSignal to the observeEvents function. This allows for external control over the observation loop, independent of loop iteration status.

```typescript
const controller = new AbortController();

for await (const event of client.observeEvents('/books/42', {
  recursive: false
}, controller.signal)) {
  // ...
}

// Somewhere else, abort the controller, which will cause
// observing to end.
controller.abort();
```

--------------------------------

### Read Specific Event Type - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Retrieve the detailed schema for a specific event type by calling the 'readEventType' function with the event type name. This returns a promise that resolves to the event type details.

```typescript
eventType = await client.readEventType("io.eventsourcingdb.library.book-acquired");
```

--------------------------------

### Abort Event Type Listing - TypeScript

Source: https://github.com/thenativeweb/eventsourcingdb-client-javascript/blob/main/README.md

Abort the listing of event types asynchronously by providing an AbortSignal to the readEventTypes function. This provides external control over the event type iteration.

```typescript
const controller = new AbortController();

for await (const eventType of client.readEventTypes()) {
  // ...
}

// Somewhere else, abort the controller, which will cause
// reading to end.
controller.abort();
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.