@cratis/chronicle 3.0.0 → 3.1.1

package/ChronicleClient.ts

@@ -6,6 +6,7 @@ import { diag } from '@opentelemetry/api';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleOptions } from './ChronicleOptions';
 import { ChronicleConnection } from './connection';
+import { ensureCommandSuccess, ensureQuerySuccess, firstQueryResult } from './connection/callResults';
 import { ConnectionLifecycle } from './connection/ConnectionLifecycle';
 import { KernelKeepAlive } from './connection/KernelKeepAlive';
 import { EventStore } from './EventStore';
@@ -131,7 +132,7 @@ export class ChronicleClient implements IChronicleClient {
                     this._logger.debug('Ensuring event store exists in kernel', {
                         eventStore: storeName.value
                     });
-                    await this._connection.eventStores.ensure({ Name: storeName.value });
+                    ensureCommandSuccess('ensure event store', await this._connection.eventStores.ensureEventStore({ Name: storeName.value }));
 
                     const created = new EventStore(storeName, namespaceName, this._connection, this._lifecycle, this.options.defaultSinkTypeId);
                     this._stores.set(key, created);
@@ -167,9 +168,9 @@ export class ChronicleClient implements IChronicleClient {
             try {
                 const response = await this.withReconnect('get_event_stores', async () => {
                     await this.ensureConnected();
-                    return this._connection.eventStores.getEventStores({});
+                    return firstQueryResult('get event stores', this._connection.eventStores.allEventStores({}));
                 });
-                const result = (response.items ?? []).map((name: string) => new EventStoreName(name));
+                const result = ensureQuerySuccess('get event stores', response).map((name: string) => new EventStoreName(name));
                 this._logger.verbose('Retrieved event stores from kernel', {
                     count: result.length
                 });

package/EventStore.ts

@@ -5,6 +5,7 @@ import { diag } from '@opentelemetry/api';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { ChronicleConnection } from './connection';
 import { ConnectionLifecycle } from './connection/ConnectionLifecycle';
+import { ensureQuerySuccess, firstQueryResult } from './connection/callResults';
 import { EventLog } from './eventSequences/EventLog';
 import { EventSequence } from './eventSequences/EventSequence';
 import { EventSequenceId } from './eventSequences/EventSequenceId';
@@ -37,6 +38,14 @@ import { IWebhooks } from './webhooks/IWebhooks';
 import { Webhooks } from './webhooks/Webhooks';
 import { EventStoreSubscriptions } from './eventStoreSubscriptions/EventStoreSubscriptions';
 import { IEventStoreSubscriptions } from './eventStoreSubscriptions/IEventStoreSubscriptions';
+import { ExternalServices } from './externalServices/ExternalServices';
+import { IExternalServices } from './externalServices/IExternalServices';
+import { IdentityManager } from './identities/IdentityManager';
+import { IIdentityManager } from './identities/IIdentityManager';
+import { PIIManager } from './compliance/PIIManager';
+import { IPIIManager } from './compliance/IPIIManager';
+import { FailedPartitions } from './observation/FailedPartitions';
+import { IFailedPartitions } from './observation/IFailedPartitions';
 
 /**
  * Implements {@link IEventStore} by communicating with the Chronicle Kernel
@@ -59,6 +68,10 @@ export class EventStore implements IEventStore {
     readonly webhooks: IWebhooks;
     readonly subscriptions: IEventStoreSubscriptions;
     readonly seeding: IEventSeeding;
+    readonly externalServices: IExternalServices;
+    readonly identities: IIdentityManager;
+    readonly pii: IPIIManager;
+    readonly failedPartitions: IFailedPartitions;
 
     private readonly _sequences: Map<string, IEventSequence> = new Map();
 
@@ -78,13 +91,17 @@ export class EventStore implements IEventStore {
         this.eventTypes = new EventTypes(name.value, _connection, artifacts);
         this.constraints = new Constraints(name.value, _connection, artifacts);
         this.projections = new Projections(name.value, _connection, artifacts, defaultSinkTypeId);
-        this.reactors = new Reactors(artifacts, _connection, name.value, namespace.value, lifecycle);
+        this.reactors = new Reactors(artifacts, _connection, name.value, namespace.value, lifecycle, this.eventLog);
         this.reducers = new Reducers(artifacts, _connection, name.value, namespace.value, lifecycle, defaultSinkTypeId);
         this.readModels = new ReadModels(name.value, namespace.value, _connection, artifacts, defaultSinkTypeId);
         this.jobs = new Jobs(name.value, namespace.value, _connection);
         this.webhooks = new Webhooks(name.value, _connection, this.eventTypes, artifacts);
         this.subscriptions = new EventStoreSubscriptions(this.eventTypes, name.value, _connection);
         this.seeding = new EventSeeding(name.value, _connection, artifacts);
+        this.externalServices = new ExternalServices(name.value, _connection);
+        this.identities = new IdentityManager(name.value, namespace.value, _connection);
+        this.pii = new PIIManager(name.value, namespace.value, _connection);
+        this.failedPartitions = new FailedPartitions(name.value, namespace.value, _connection);
     }
 
     /**
@@ -147,8 +164,8 @@ export class EventStore implements IEventStore {
         return ChronicleTracer.startActiveSpan('chronicle.event_store.get_namespaces', async span => {
             span.setAttribute('chronicle.event_store', this.name.value);
             try {
-                const response = await this._connection.namespaces.getNamespaces({ EventStore: this.name.value });
-                const result = (response.items ?? []).map((namespace: string) => new EventStoreNamespaceName(namespace));
+                const response = await firstQueryResult('get namespaces', this._connection.namespaces.allNamespaces({ EventStore: this.name.value }));
+                const result = ensureQuerySuccess('get namespaces', response).map((namespace: string) => new EventStoreNamespaceName(namespace));
                 span.setStatus({ code: SpanStatusCode.OK });
                 return result;
             } catch (error) {

package/IEventStore.ts

@@ -17,6 +17,10 @@ import { IWebhooks } from './webhooks/IWebhooks';
 import { IEventSeeding } from './seeding/IEventSeeding';
 import { IEventStoreSubscriptions } from './eventStoreSubscriptions/IEventStoreSubscriptions';
 import { IReadModels } from './readModels/IReadModels';
+import { IExternalServices } from './externalServices/IExternalServices';
+import { IIdentityManager } from './identities/IIdentityManager';
+import { IPIIManager } from './compliance/IPIIManager';
+import { IFailedPartitions } from './observation/IFailedPartitions';
 
 /**
  * Defines the API surface for an event store.
@@ -65,6 +69,18 @@ export interface IEventStore {
     /** The event seeding manager for this event store. */
     readonly seeding: IEventSeeding;
 
+    /** The external services manager for this event store. */
+    readonly externalServices: IExternalServices;
+
+    /** The identities manager for this event store. */
+    readonly identities: IIdentityManager;
+
+    /** The PII (Personal Identifiable Information) compliance manager for this event store. */
+    readonly pii: IPIIManager;
+
+    /** The failed partitions manager for this event store. */
+    readonly failedPartitions: IFailedPartitions;
+
     /**
      * Gets an event sequence by its identifier.
      * @param id - The identifier of the event sequence to retrieve.

package/README.md

@@ -1,38 +1,42 @@
 # Chronicle TypeScript Client
 
-A TypeScript-idiomatic client for [Cratis Chronicle](https://github.com/Cratis/Chronicle) — the open source event-sourcing kernel.
+**Event sourcing for TypeScript and Node.js — the idiomatic client for [Cratis Chronicle](https://github.com/Cratis/Chronicle).**
+
+[![npm](https://img.shields.io/npm/v/@cratis/chronicle?label=npm&logo=npm)](https://www.npmjs.com/package/@cratis/chronicle)
+[![Build](https://github.com/Cratis/Chronicle.TypeScript/actions/workflows/build.yml/badge.svg)](https://github.com/Cratis/Chronicle.TypeScript/actions/workflows/build.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Cratis/Chronicle.TypeScript/blob/main/LICENSE)
+[![Discord](https://img.shields.io/discord/1182595891576717413?label=Discord&logo=discord&logoColor=white)](https://discord.gg/kt4AMpV8WV)
+
+Chronicle is an event-sourcing database and processing runtime with a first-class .NET SDK and additional TypeScript, Kotlin/Java (JVM), and Elixir clients — with a Python client coming soon — plus pluggable storage-provider implementations including MongoDB (default), PostgreSQL, SQL Server, and SQLite. This package is the **TypeScript client**.
 
 ## Overview
 
 `@cratis/chronicle` provides a clean, type-safe TypeScript API for interacting with the Chronicle Kernel. It builds on top of [`@cratis/chronicle.contracts`](https://www.npmjs.com/package/@cratis/chronicle.contracts) (the gRPC contracts package) and exposes idiomatic TypeScript constructs including:
 
-- **Decorators** — `@eventType`, `@eventTypeMigration`, `@readModel`, `@reactor`, `@reducer`, `@constraint`, `@projection`, and model-bound decorators such as `@fromEvent`
+- **Decorators** — `@eventType`, `@eventTypeMigration`, `@readModel`, `@reactor`, `@reducer`, `@seeder`, `@constraint`, `@projection`, and model-bound decorators such as `@fromEvent`
 - **Value objects** — `EventSequenceNumber`, `EventTypeId`, `EventStoreName`, etc.
 - **Fluent client** — `ChronicleClient` → `EventStore` → `EventLog` → `append()`
 
-## Structure
+Beyond appending and observing events, the client covers the full Chronicle surface:
 
-```
-Source/          ← @cratis/chronicle TypeScript library
-Documentation/   ← User-facing documentation
-Samples/
-  Console/       ← Plain Node.js console sample application
-```
+- **Transactions** — group appends into a unit of work with a single commit
+- **Jobs** — inspect and control long-running kernel jobs
+- **Webhooks** — push events to HTTP endpoints
+- **Compliance / PII** — classify event data and handle personally identifiable information
+- **OpenTelemetry** — built-in metrics and tracing instrumentation
 
-## Prerequisite: Chronicle Running
+## Installation
 
-You need a Chronicle Kernel available before running samples or application code.
+```bash
+npm install @cratis/chronicle reflect-metadata
+```
 
-The easiest local setup is the development Docker image:
+You need a Chronicle Kernel available. The easiest local setup is the development Docker image:
 
 ```bash
 docker run -p 35000:35000 cratis/chronicle:latest-development
 ```
 
-## Getting Started
-
-See [Documentation/getting-started.md](./Documentation/getting-started.md) for installation and usage instructions.
-
 ## Quick Example
 
 ```typescript
@@ -51,19 +55,27 @@ console.log(`Appended at sequence number ${result.sequenceNumber.value}`);
 client.dispose();
 ```
 
-## Building
+## Documentation
 
-```bash
-yarn install
-yarn workspace @cratis/chronicle compile
-```
+See the [getting started guide](https://github.com/Cratis/Chronicle.TypeScript/blob/main/Documentation/getting-started.md) and the rest of the [documentation](https://github.com/Cratis/Chronicle.TypeScript/tree/main/Documentation) for installation and usage instructions, or visit [cratis.io](https://www.cratis.io/chronicle/).
 
-## Running the Console Sample
+## The Cratis ecosystem
 
-```bash
-yarn install
-yarn workspace @cratis/chronicle-test-console build
-yarn workspace @cratis/chronicle-test-console start
-```
+This package is part of [Cratis](https://www.cratis.io) — free, MIT-licensed tools for building event-sourced and CQRS applications.
+
+- **[Chronicle](https://github.com/Cratis/Chronicle)** — event-sourcing database and runtime. Orleans-based kernel, pluggable storage (MongoDB default; PostgreSQL, SQL Server, SQLite, in-memory), language-agnostic gRPC contracts. [Docs](https://www.cratis.io/chronicle/)
+- **Chronicle clients** — first-class [.NET SDK](https://github.com/Cratis/Chronicle), plus [TypeScript](https://github.com/Cratis/Chronicle.TypeScript), [Kotlin/Java](https://github.com/Cratis/Chronicle.Kotlin), and [Elixir](https://github.com/Cratis/Chronicle.Elixir); [Python](https://github.com/Cratis/Chronicle.Python) coming soon (pre-alpha). AI agents connect through the [Chronicle MCP server](https://github.com/Cratis/Chronicle.Mcp).
+- **[Arc](https://github.com/Cratis/Arc)** — opinionated CQRS framework for ASP.NET Core with commands, queries, validation, authorization, and TypeScript proxy generation. Works without event sourcing. [Docs](https://www.cratis.io/arc/)
+- **[Components](https://github.com/Cratis/Components)** — React components aligned with Arc patterns. [Docs](https://www.cratis.io/components/)
+- **[CLI](https://github.com/Cratis/cli) + Workbench** — inspect and diagnose Chronicle from the terminal or the browser. [Docs](https://www.cratis.io/cli/)
+- **[Samples](https://github.com/Cratis/Samples)** — runnable event sourcing and CQRS samples for the whole stack
+
+Everything Cratis publishes today is MIT licensed and free to use.
+
+---
+
+<div align="center">
+
+*Part of the [Cratis](https://www.cratis.io) platform · Licensed under the [MIT license](https://github.com/Cratis/Chronicle.TypeScript/blob/main/LICENSE)*
 
-Set the `CHRONICLE_CONNECTION` environment variable to override the default connection string (`chronicle://localhost:35000`).
+</div>

package/auditing/CausationType.ts

@@ -25,6 +25,16 @@ export class CausationType {
      */
     static readonly appendManyEvents = new CausationType('TypeScriptClient.AppendMany');
 
+    /**
+     * Represents the causation type for redacting a single event via the TypeScript client.
+     */
+    static readonly redact = new CausationType('TypeScriptClient.Redact');
+
+    /**
+     * Represents the causation type for redacting all events for an event source via the TypeScript client.
+     */
+    static readonly redactForEventSource = new CausationType('TypeScriptClient.RedactForEventSource');
+
     /**
      * Initializes a new instance of the {@link CausationType} class.
      * @param name - The name of the causation type.

package/compliance/ComplianceContracts.ts

@@ -24,6 +24,20 @@ export interface ReleaseResponse {
     Error: string;
 }
 
+/**
+ * Request to delete the encryption key for a PII encryption key identifier (GDPR right-to-erasure).
+ */
+export interface DeleteEncryptionKeyRequest {
+    EventStore: string;
+    Namespace: string;
+    Identifier: string;
+}
+
+/**
+ * An empty protobuf message.
+ */
+export interface Empty {}
+
 type Builtin = Date | Function | Uint8Array | string | number | boolean | bigint | undefined;
 export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
     [K in keyof T]?: DeepPartial<T[K]>;
@@ -34,6 +48,7 @@ export type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<
  */
 export interface ComplianceClient<CallOptionsExt = {}> {
     release(request: DeepPartial<ReleaseRequest>, options?: CallOptions & CallOptionsExt): Promise<ReleaseResponse>;
+    deleteEncryptionKey(request: DeepPartial<DeleteEncryptionKeyRequest>, options?: CallOptions & CallOptionsExt): Promise<Empty>;
 }
 
 export const ReleaseRequest = {
@@ -126,6 +141,67 @@ export const ReleaseResponse = {
     }
 };
 
+export const DeleteEncryptionKeyRequest = {
+    encode(message: DeleteEncryptionKeyRequest, writer: BinaryWriter = new BinaryWriter()): BinaryWriter {
+        if (message.EventStore !== '') {
+            writer.uint32(10).string(message.EventStore);
+        }
+        if (message.Namespace !== '') {
+            writer.uint32(18).string(message.Namespace);
+        }
+        if (message.Identifier !== '') {
+            writer.uint32(26).string(message.Identifier);
+        }
+        return writer;
+    },
+
+    decode(input: BinaryReader | Uint8Array, length?: number): DeleteEncryptionKeyRequest {
+        const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+        const end = length === undefined ? reader.len : reader.pos + length;
+        const message: DeleteEncryptionKeyRequest = { EventStore: '', Namespace: '', Identifier: '' };
+        while (reader.pos < end) {
+            const tag = reader.uint32();
+            switch (tag >>> 3) {
+                case 1: message.EventStore = reader.string(); continue;
+                case 2: message.Namespace = reader.string(); continue;
+                case 3: message.Identifier = reader.string(); continue;
+            }
+            if ((tag & 7) === 4 || tag === 0) break;
+            reader.skip(tag & 7);
+        }
+        return message;
+    },
+
+    fromPartial(object: DeepPartial<DeleteEncryptionKeyRequest>): DeleteEncryptionKeyRequest {
+        return {
+            EventStore: object.EventStore ?? '',
+            Namespace: object.Namespace ?? '',
+            Identifier: object.Identifier ?? ''
+        };
+    }
+};
+
+export const Empty = {
+    encode(_: Empty, writer: BinaryWriter = new BinaryWriter()): BinaryWriter {
+        return writer;
+    },
+
+    decode(input: BinaryReader | Uint8Array, length?: number): Empty {
+        const reader = input instanceof BinaryReader ? input : new BinaryReader(input);
+        const end = length === undefined ? reader.len : reader.pos + length;
+        while (reader.pos < end) {
+            const tag = reader.uint32();
+            if ((tag & 7) === 4 || tag === 0) break;
+            reader.skip(tag & 7);
+        }
+        return {};
+    },
+
+    fromPartial(_: DeepPartial<Empty>): Empty {
+        return {};
+    }
+};
+
 /**
  * Compliance service definition for nice-grpc.
  */
@@ -140,6 +216,14 @@ export const ComplianceDefinition = {
             responseType: ReleaseResponse,
             responseStream: false as const,
             options: {}
+        },
+        deleteEncryptionKey: {
+            name: 'DeleteEncryptionKey',
+            requestType: DeleteEncryptionKeyRequest,
+            requestStream: false as const,
+            responseType: Empty,
+            responseStream: false as const,
+            options: {}
         }
     }
 } as const;

package/compliance/IPIIManager.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Defines a manager for working with Personal Identifiable Information (PII) compliance concerns.
+ */
+export interface IPIIManager {
+    /**
+     * Deletes the encryption key for a given PII encryption key identifier, effectively performing
+     * a GDPR right-to-erasure for all data encrypted with that key.
+     * @param identifier - The identifier of the encryption key to delete.
+     * @remarks
+     * Once the encryption key is deleted, any data encrypted with it can no longer be decrypted -
+     * this operation cannot be undone.
+     */
+    deleteEncryptionKey(identifier: string): Promise<void>;
+}

package/compliance/PIIManager.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ChronicleConnection } from '../connection';
+import { IPIIManager } from './IPIIManager';
+
+/**
+ * Implements {@link IPIIManager} by proxying to the Chronicle Kernel over the client connection.
+ */
+export class PIIManager implements IPIIManager {
+    /**
+     * Creates a new {@link PIIManager} instance.
+     * @param _eventStore - Event store name.
+     * @param _namespace - Event store namespace.
+     * @param _connection - Chronicle connection.
+     */
+    constructor(
+        private readonly _eventStore: string,
+        private readonly _namespace: string,
+        private readonly _connection: ChronicleConnection
+    ) {}
+
+    /** @inheritdoc */
+    async deleteEncryptionKey(identifier: string): Promise<void> {
+        await this._connection.compliance.deleteEncryptionKey({
+            EventStore: this._eventStore,
+            Namespace: this._namespace,
+            Identifier: identifier
+        });
+    }
+}

package/compliance/index.ts

@@ -5,3 +5,5 @@ export { ComplianceMetadataType } from './ComplianceMetadataType';
 export type { ComplianceMetadata } from './ComplianceMetadata';
 export { pii, getPIIMetadata, hasPIIMetadata, getTypePIIMetadata, isPII } from './pii';
 export { ComplianceMetadataResolver } from './ComplianceMetadataResolver';
+export type { IPIIManager } from './IPIIManager';
+export { PIIManager } from './PIIManager';

package/connection/ChronicleConnection.ts

@@ -29,6 +29,7 @@ import { createChannel, createClientFactory, waitForChannelReady } from 'nice-gr
 import type { ClientMiddleware } from 'nice-grpc-common';
 import { Metadata } from 'nice-grpc-common';
 import { EventStoreSubscriptionsDefinition } from '../eventStoreSubscriptions/contracts';
+import { ExternalServicesDefinition } from '../externalServices/ExternalServicesContracts';
 import { AuthenticationMode, ChronicleConnectionString } from './ChronicleConnectionString';
 import { ChronicleServerAddressResolver } from './ChronicleServerAddressResolver';
 import { ChronicleServices } from './ChronicleServices';
@@ -207,6 +208,10 @@ export class ChronicleConnection implements ChronicleServices {
         return this._services.compliance;
     }
 
+    get externalServices() {
+        return this._services.externalServices;
+    }
+
     get connections(): ConnectionServiceClient {
         return this._connections;
     }
@@ -286,7 +291,8 @@ export class ChronicleConnection implements ChronicleServices {
             webhooks: factory.create(WebhooksDefinition, this._channel),
             eventSeeding: factory.create(EventSeedingDefinition, this._channel),
             server: factory.create(ServerDefinition, this._channel),
-            compliance: factory.create(ComplianceDefinition as any, this._channel) as any
+            compliance: factory.create(ComplianceDefinition as any, this._channel) as any,
+            externalServices: factory.create(ExternalServicesDefinition, this._channel)
         };
         this._connections = factory.create(ConnectionServiceDefinition, this._channel);
     }

package/connection/ChronicleServices.ts

@@ -23,6 +23,7 @@ import type {
 } from '@cratis/chronicle.contracts';
 import type { ComplianceClient } from '../compliance/ComplianceContracts';
 import type { EventStoreSubscriptionsClient } from '../eventStoreSubscriptions/contracts';
+import type { ExternalServicesClient } from '../externalServices/ExternalServicesContracts';
 
 /**
  * Represents all Chronicle gRPC services.
@@ -48,4 +49,5 @@ export interface ChronicleServices {
     eventSeeding: EventSeedingClient;
     server: ServerClient;
     compliance: ComplianceClient;
+    externalServices: ExternalServicesClient;
 }

package/connection/Guid.ts

@@ -27,4 +27,22 @@ export function toContractsGuid(guid: FundamentalGuid): ContractsGuid {
         lo,
         hi
     };
+}
+
+/**
+ * Converts a protobuf-net bcl.Guid from the contracts package into a Chronicle Guid.
+ * The reverse of {@link toContractsGuid}.
+ */
+export function fromContractsGuid(guid: ContractsGuid | undefined): FundamentalGuid {
+    if (!guid) {
+        return FundamentalGuid.empty;
+    }
+
+    const bytes = new Array<number>(16).fill(0);
+    for (let index = 0; index < 8; index++) {
+        bytes[index] = Number((guid.lo >> BigInt(index * 8)) & 0xffn);
+        bytes[index + 8] = Number((guid.hi >> BigInt(index * 8)) & 0xffn);
+    }
+
+    return new FundamentalGuid(bytes);
 }

package/connection/callResults.spec.ts

@@ -0,0 +1,90 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { describe, expect, it } from 'vitest';
+import { ChronicleCallFailed, ensureCommandSuccess, ensureQuerySuccess, firstQueryResult, isCallSuccess } from './callResults';
+
+const successfulResult = {
+    ValidationResults: [],
+    ExceptionMessages: [],
+    AuthorizationFailureReason: ''
+};
+
+describe('callResults', () => {
+    describe('when checking a successful result', () => {
+        it('should report success', () => {
+            expect(isCallSuccess(successfulResult)).toBe(true);
+        });
+    });
+
+    describe('when checking a result with an authorization failure reason', () => {
+        it('should report failure', () => {
+            expect(isCallSuccess({ ...successfulResult, AuthorizationFailureReason: 'no access' })).toBe(false);
+        });
+    });
+
+    describe('when checking a result with validation results', () => {
+        it('should report failure', () => {
+            expect(isCallSuccess({ ...successfulResult, ValidationResults: [{ Message: 'invalid', Members: [] }] })).toBe(false);
+        });
+    });
+
+    describe('when checking a result with exception messages', () => {
+        it('should report failure', () => {
+            expect(isCallSuccess({ ...successfulResult, ExceptionMessages: ['boom'] })).toBe(false);
+        });
+    });
+
+    describe('when ensuring a successful command', () => {
+        it('should not throw', () => {
+            expect(() => ensureCommandSuccess('operation', successfulResult)).not.toThrow();
+        });
+    });
+
+    describe('when ensuring a failed command', () => {
+        it('should throw with the failure reasons', () => {
+            expect(() => ensureCommandSuccess('operation', { ...successfulResult, ExceptionMessages: ['boom'] }))
+                .toThrow(ChronicleCallFailed);
+            expect(() => ensureCommandSuccess('operation', { ...successfulResult, ExceptionMessages: ['boom'] }))
+                .toThrow(/operation.*boom/);
+        });
+    });
+
+    describe('when ensuring a successful query', () => {
+        it('should return the data', () => {
+            expect(ensureQuerySuccess('operation', { ...successfulResult, Data: ['a', 'b'] })).toEqual(['a', 'b']);
+        });
+    });
+
+    describe('when ensuring a failed query', () => {
+        it('should throw with the failure reasons', () => {
+            expect(() => ensureQuerySuccess('operation', { ...successfulResult, AuthorizationFailureReason: 'no access', Data: [] }))
+                .toThrow(/no access/);
+        });
+    });
+
+    describe('when taking the first result from a stream', () => {
+        it('should return the first item and cancel the stream', async () => {
+            let cleanedUp = false;
+            async function* stream() {
+                try {
+                    yield 'first';
+                    yield 'second';
+                } finally {
+                    cleanedUp = true;
+                }
+            }
+
+            const result = await firstQueryResult('operation', stream());
+            expect(result).toBe('first');
+            expect(cleanedUp).toBe(true);
+        });
+    });
+
+    describe('when taking the first result from an empty stream', () => {
+        it('should throw', async () => {
+            async function* stream() { /* produces nothing */ }
+            await expect(firstQueryResult('operation', stream())).rejects.toThrow(/completed without producing a result/);
+        });
+    });
+});