@othree.io/chisel-forge 1.0.1

package/README.md

@@ -0,0 +1,234 @@
+# @othree.io/chisel-forge
+
+Integration testing utilities for the [Chisel](https://www.npmjs.com/package/@othree.io/chisel) CQRS/Event Sourcing framework. Provides a fluent API to send commands against deployed AWS infrastructure and validate triggered events and aggregate state.
+
+## Install
+
+```bash
+npm install @othree.io/chisel-forge
+```
+
+### Peer Dependencies
+
+- `@othree.io/awsome` ^4.0.0
+- `@othree.io/chisel` ^5.0.0
+- `@othree.io/optional` ^2.3.2
+- `vitest` ^3.2.4
+
+## Quick Start~
+
+```typescript
+import { when } from '@othree.io/chisel-forge'
+import { Empty } from '@othree.io/optional'
+
+type PersonState = Readonly<{
+    name: string
+    lastName: string
+}>
+
+const configuration = {
+    boundedContext: 'Person',
+    commandHandlerArn: 'arn:aws:lambda:us-east-1:123456789:function:PersonCommandHandler',
+    eventsTable: 'PersonEvents',
+    topicArn: 'arn:aws:sns:us-east-1:123456789:PersonEventsTopic',
+    testName: 'CreatePerson',
+    subscriptionAwaitTime: 3000,
+    loadStateLambdaArn: Empty(),
+}
+
+it('should create a person', async () => {
+    await when<PersonState>(configuration)({
+        type: 'CreatePerson',
+        body: { name: 'Chuck', lastName: 'Norris' },
+    })
+        .expectState({ name: 'Chuck', lastName: 'Norris' })
+        .expectEvent({
+            contextId: expect.any(String),
+            type: 'PersonCreated',
+            body: { name: 'Chuck', lastName: 'Norris' },
+        })
+        .toPass()
+}, 30000)
+```
+
+## Command Handler Modes
+
+The `when()` function supports three command delivery modes, determined by the configuration type.
+
+### Synchronous Lambda
+
+Invokes the command handler Lambda directly and receives the `CommandResult` in the response.
+
+```typescript
+const configuration = {
+    boundedContext: 'Person',
+    commandHandlerArn: 'arn:aws:lambda:...:PersonCommandHandler',
+    eventsTable: 'PersonEvents',
+    topicArn: 'arn:aws:sns:...:PersonEventsTopic',
+    testName: 'CreatePerson',
+    subscriptionAwaitTime: 3000,
+    loadStateLambdaArn: Empty(),
+}
+```
+
+### Async SQS
+
+Sends the command to an SQS queue. The command handler processes it asynchronously.
+
+```typescript
+const configuration = {
+    boundedContext: 'Person',
+    commandQueueUrl: 'https://sqs.us-east-1.amazonaws.com/.../PersonCommandQueue.fifo',
+    commandDLQUrl: 'https://sqs.us-east-1.amazonaws.com/.../PersonCommandDLQ.fifo',
+    eventsTable: 'PersonEvents',
+    topicArn: 'arn:aws:sns:...:PersonEventsTopic.fifo',
+    testName: 'CreatePerson',
+    subscriptionAwaitTime: 3000,
+    loadStateLambdaArn: Empty(),
+    extractMessageGroupId: (command) => command.contextId,
+    extractMessageDeduplicationId: (command) => `${command.type}-${command.contextId}`,
+}
+```
+
+### Async SNS
+
+Sends the command to an SNS topic. The command handler subscribes and processes it asynchronously.
+
+```typescript
+const configuration = {
+    boundedContext: 'Person',
+    commandTopicArn: 'arn:aws:sns:...:PersonCommandTopic.fifo',
+    commandDLQUrl: 'https://sqs.us-east-1.amazonaws.com/.../PersonCommandDLQ.fifo',
+    eventsTable: 'PersonEvents',
+    topicArn: 'arn:aws:sns:...:PersonEventsTopic.fifo',
+    testName: 'CreatePerson',
+    subscriptionAwaitTime: 3000,
+    loadStateLambdaArn: Empty(),
+    extractMessageGroupId: (command) => command.contextId,
+    extractMessageDeduplicationId: (command) => `${command.type}-${command.contextId}`,
+}
+```
+
+## Fluent API
+
+### `when<State>(configuration)(command)`
+
+Entry point. Accepts a configuration and returns a function that takes a `Command` and returns a test builder.
+
+### `.and(getCommand)`
+
+Chains a subsequent command. The `getCommand` callback receives the `contextId` from the first command's result as an `Optional<string>`.
+
+```typescript
+await when<PersonState>(configuration)({
+    type: 'CreatePerson',
+    body: { name: 'Chuck', lastName: 'Norris' },
+})
+    .and((contextId) => ({
+        contextId: contextId.get(),
+        type: 'UpdatePerson',
+        body: { name: 'Bruce', lastName: 'Lee' },
+    }))
+    .expectState({ name: 'Bruce', lastName: 'Lee' })
+    .toPass()
+```
+
+### `.expectEvent(event)`
+
+Asserts that a specific `ChiselEvent` was triggered. Can be called multiple times for multiple expected events.
+
+```typescript
+.expectEvent({
+    contextId: expect.any(String),
+    type: 'PersonCreated',
+    body: { name: 'Chuck', lastName: 'Norris' },
+})
+```
+
+### `.expectState(state)`
+
+Asserts the final aggregate state matches the expected value. When `loadStateLambdaArn` is configured, also validates the state returned by the load-state Lambda.
+
+### `.toPass()`
+
+Executes the command(s), validates events and state, and returns the `CommandResult` array. Automatically cleans up temporary SQS queues, subscriptions, and events.
+
+### `.toFail(errorMsg?)`
+
+Asserts the command fails with a `CommandExecutionError`. Optionally validates the error message.
+
+```typescript
+const error = await when<PersonState>(configuration)({
+    type: 'CreatePerson',
+    body: { name: '', lastName: '' },
+}).toFail('Validation failed')
+
+expect(error.name).toEqual('CommandExecutionError')
+```
+
+## AWS Credentials
+
+Pass optional AWS credentials as the second argument to `when()`:
+
+```typescript
+import { fromSSO } from '@aws-sdk/credential-providers'
+
+const credentials = fromSSO({ profile: 'my-profile' })
+
+await when<PersonState>(configuration, credentials)({
+    type: 'CreatePerson',
+    body: { name: 'Chuck', lastName: 'Norris' },
+}).toPass()
+```
+
+## Low-Level API
+
+For advanced use cases, the low-level functions are available under the `lowLevel` namespace:
+
+```typescript
+import { lowLevel } from '@othree.io/chisel-forge'
+
+const {
+    when,
+    runAndValidate,
+    runAndValidateAsync,
+    cleanUp,
+    createQueueAndSubscribe,
+    receiveMessages,
+} = lowLevel
+```
+
+These accept explicit dependency objects, making them fully testable in isolation.
+
+## How It Works
+
+1. Creates a temporary SQS queue and subscribes it to the bounded context's SNS events topic
+2. Sends the command(s) to the command handler (Lambda, SQS, or SNS depending on config)
+3. Receives triggered event messages from the temporary queue
+4. Validates events and state against expectations
+5. Cleans up: deletes the temporary queue, unsubscribes from the topic, and removes events from the events table
+
+## Configuration Reference
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `boundedContext` | `string` | All | Bounded context name (matched against event message attributes) |
+| `topicArn` | `string` | All | SNS topic ARN where the bounded context publishes events |
+| `eventsTable` | `string` | All | DynamoDB events table name (for cleanup) |
+| `subscriptionAwaitTime` | `number` | All | Milliseconds to wait after subscribing before sending commands |
+| `testName` | `string` | All | Used to name the temporary SQS queue |
+| `loadStateLambdaArn` | `Optional<string>` | All | Lambda ARN for loading aggregate state (optional validation) |
+| `commandHandlerArn` | `string` | Sync | Lambda ARN for the command handler |
+| `commandQueueUrl` | `string` | Async SQS | SQS queue URL for commands |
+| `commandTopicArn` | `string` | Async SNS | SNS topic ARN for commands |
+| `commandDLQUrl` | `string` | Async | SQS DLQ URL for failed commands |
+| `extractMessageGroupId` | `(command) => string` | Async | FIFO message group ID extractor (optional) |
+| `extractMessageDeduplicationId` | `(command) => string` | Async | FIFO deduplication ID extractor (optional) |
+
+## Scripts
+
+```bash
+npm test          # Run tests
+npm run build     # Compile TypeScript
+npm run docs      # Generate JSDoc documentation
+```

package/lib/cjs/index.d.ts

@@ -0,0 +1,13 @@
+import { TestConfiguration } from './utils';
+import { Command } from '@othree.io/chisel';
+import { AwsCredentialIdentity, Provider } from '@aws-sdk/types';
+export * as lowLevel from './utils';
+/**
+ * Initializes a testing environment for Chisel framework.
+ * @function
+ * @param {ChiselTestConfiguration} configuration - The configuration for the Chisel test.
+ * @param {TestConfiguration} [credentials] - The optional AWS credentials.
+ * @returns A function that initializes a testing environment and returns a low-level when function.
+ */
+export declare const when: <State>(configuration: TestConfiguration, credentials?: AwsCredentialIdentity | Provider<AwsCredentialIdentity>) => (command: Command) => import("./utils").CommandChiselTest<State>;
+//# sourceMappingURL=index.d.ts.map

package/lib/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAWH,iBAAiB,EAEpB,MAAM,SAAS,CAAA;AAIhB,OAAO,EAAC,OAAO,EAAwC,MAAM,mBAAmB,CAAA;AAGhF,OAAO,EAAC,qBAAqB,EAAE,QAAQ,EAAC,MAAM,gBAAgB,CAAA;AAG9D,OAAO,KAAK,QAAQ,MAAM,SAAS,CAAA;AAEnC;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GAAI,KAAK,EAAE,eAAe,iBAAiB,EAAE,cAAc,qBAAqB,GAAG,QAAQ,CAAC,qBAAqB,CAAC,qEAiIlI,CAAA"}

package/lib/cjs/index.js

@@ -0,0 +1,167 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.when = exports.lowLevel = void 0;
+const utils_1 = require("./utils");
+const client_lambda_1 = require("@aws-sdk/client-lambda");
+const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
+const awsome_1 = require("@othree.io/awsome");
+const client_sqs_1 = require("@aws-sdk/client-sqs");
+const client_sns_1 = require("@aws-sdk/client-sns");
+const optional_1 = require("@othree.io/optional");
+exports.lowLevel = __importStar(require("./utils"));
+/**
+ * Initializes a testing environment for Chisel framework.
+ * @function
+ * @param {ChiselTestConfiguration} configuration - The configuration for the Chisel test.
+ * @param {TestConfiguration} [credentials] - The optional AWS credentials.
+ * @returns A function that initializes a testing environment and returns a low-level when function.
+ */
+const when = (configuration, credentials) => {
+    const sqsClient = new client_sqs_1.SQSClient({
+        credentials: credentials
+    });
+    const createQueueFn = awsome_1.sqs.createQueue({ client: sqsClient });
+    const deleteQueueFn = awsome_1.sqs.deleteQueue({ client: sqsClient });
+    const snsClient = new client_sns_1.SNSClient({
+        credentials: credentials
+    });
+    const snsConfiguration = {
+        BatchSize: 10,
+        Parallelism: 10,
+        TopicArn: configuration.topicArn
+    };
+    const subscribeSqsFn = awsome_1.sns.subscribeSqs({ snsClient, sqsClient, configuration: snsConfiguration });
+    const unsubscribeFn = awsome_1.sns.unsubscribe({ snsClient });
+    const dynamoClient = new client_dynamodb_1.DynamoDBClient({
+        credentials: credentials
+    });
+    const dynamoConfiguration = {
+        TableName: configuration.eventsTable
+    };
+    const deleteByFn = awsome_1.dynamo.deleteBy({ dynamoDb: dynamoClient, configuration: dynamoConfiguration });
+    const queryFn = awsome_1.dynamo.query({ dynamoDb: dynamoClient, configuration: dynamoConfiguration });
+    const getByFn = awsome_1.dynamo.getBy({ query: queryFn });
+    const cleanUpFn = (0, utils_1.cleanUp)({
+        getBy: getByFn,
+        deleteBy: deleteByFn,
+        deleteQueue: deleteQueueFn,
+        unsubscribe: unsubscribeFn,
+    });
+    const loadState = configuration.loadStateLambdaArn.map(lambdaArn => {
+        const lambdaClient = new client_lambda_1.LambdaClient({
+            credentials: credentials
+        });
+        return awsome_1.lambda.query({ lambda: lambdaClient, functionName: lambdaArn });
+    }).orElse(async (payload) => (0, optional_1.Empty)());
+    const createQueueAndSubscribeFn = (0, utils_1.createQueueAndSubscribe)({
+        now: () => new Date().getTime(),
+        createQueue: createQueueFn,
+        cleanUp: cleanUpFn,
+        subscribeSqs: subscribeSqsFn,
+    });
+    const receiveMessagesFn = (0, utils_1.receiveMessages)({
+        sqsClient: sqsClient,
+        receive: awsome_1.sqs.receiveMessages,
+    });
+    if ((0, utils_1.isChiselTestConfiguration)(configuration)) {
+        const lambdaClient = new client_lambda_1.LambdaClient({
+            credentials: credentials
+        });
+        const commandHandlerClient = awsome_1.lambda.command({ lambda: lambdaClient, functionName: configuration.commandHandlerArn });
+        return (0, utils_1.when)((0, utils_1.runAndValidate)({
+            sendCommand: commandHandlerClient,
+            createQueueAndSubscribe: createQueueAndSubscribeFn,
+            receiveMessages: receiveMessagesFn,
+            cleanUp: cleanUpFn,
+            configuration,
+            loadState,
+        }));
+    }
+    else {
+        const receiveDLQMessages = awsome_1.sqs.receiveMessages({
+            client: sqsClient,
+            configuration: {
+                QueueUrl: configuration.commandDLQUrl,
+                maxNumberOfMessages: 10,
+                waitTimeSeconds: 5,
+                autoAcknowledgeMessages: true,
+            },
+            transformMessage: (message) => {
+                return JSON.parse((0, optional_1.Optional)(message.Body).orElse('{}'));
+            },
+        });
+        if ((0, utils_1.isAsyncSqsChiselTestConfiguration)(configuration)) {
+            const sendCommand = awsome_1.sqs.send({
+                client: sqsClient,
+                configuration: { QueueUrl: configuration.commandQueueUrl },
+                withMessageGroupId: configuration.extractMessageGroupId,
+                withDeduplicationId: configuration.extractMessageDeduplicationId,
+            });
+            return (0, utils_1.when)((0, utils_1.runAndValidateAsync)({
+                sendCommand,
+                createQueueAndSubscribe: createQueueAndSubscribeFn,
+                receiveMessages: receiveMessagesFn,
+                cleanUp: cleanUpFn,
+                receiveErrorMessages: receiveDLQMessages,
+                configuration,
+                loadState,
+            }));
+        }
+        else {
+            const sendCommand = awsome_1.sns.send({
+                client: snsClient,
+                configuration: {
+                    TopicArn: configuration.commandTopicArn,
+                    Parallelism: 10,
+                    BatchSize: 10,
+                },
+                withMessageGroupId: configuration.extractMessageGroupId,
+                withMessageDeduplicationId: configuration.extractMessageDeduplicationId,
+            });
+            return (0, utils_1.when)((0, utils_1.runAndValidateAsync)({
+                sendCommand,
+                createQueueAndSubscribe: createQueueAndSubscribeFn,
+                receiveMessages: receiveMessagesFn,
+                cleanUp: cleanUpFn,
+                receiveErrorMessages: receiveDLQMessages,
+                configuration,
+                loadState,
+            }));
+        }
+    }
+};
+exports.when = when;
+//# sourceMappingURL=index.js.map

package/lib/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ChiselTestConfiguration,\n    cleanUp,\n    createQueueAndSubscribe,\n    DLQMessage,\n    isAsyncSqsChiselTestConfiguration,\n    isChiselTestConfiguration,\n    LoadStateQuery,\n    receiveMessages,\n    runAndValidate,\n    runAndValidateAsync,\n    TestConfiguration,\n    when as lowLevelWhen\n} from './utils'\nimport {LambdaClient} from '@aws-sdk/client-lambda'\nimport {DynamoDBClient} from '@aws-sdk/client-dynamodb'\nimport {lambda, sns, sqs, dynamo} from '@othree.io/awsome'\nimport {Command, CommandResult, InternalTriggeredEvent} from '@othree.io/chisel'\nimport {Message, SQSClient} from '@aws-sdk/client-sqs'\nimport {SNSClient} from '@aws-sdk/client-sns'\nimport {AwsCredentialIdentity, Provider} from '@aws-sdk/types'\nimport {Empty, Optional} from '@othree.io/optional'\n\nexport * as lowLevel from './utils'\n\n/**\n * Initializes a testing environment for Chisel framework.\n * @function\n * @param {ChiselTestConfiguration} configuration - The configuration for the Chisel test.\n * @param {TestConfiguration} [credentials] - The optional AWS credentials.\n * @returns A function that initializes a testing environment and returns a low-level when function.\n */\nexport const when = <State>(configuration: TestConfiguration, credentials?: AwsCredentialIdentity | Provider<AwsCredentialIdentity>) => {\n    const sqsClient = new SQSClient({\n        credentials: credentials\n    })\n\n    const createQueueFn = sqs.createQueue({client: sqsClient})\n    const deleteQueueFn = sqs.deleteQueue({client: sqsClient})\n\n    const snsClient = new SNSClient({\n        credentials: credentials\n    })\n\n    const snsConfiguration: sns.SNSConfiguration = {\n        BatchSize: 10,\n        Parallelism: 10,\n        TopicArn: configuration.topicArn\n    }\n\n    const subscribeSqsFn = sns.subscribeSqs({snsClient, sqsClient, configuration: snsConfiguration})\n\n    const unsubscribeFn = sns.unsubscribe({snsClient})\n\n    const dynamoClient = new DynamoDBClient({\n        credentials: credentials\n    })\n\n    const dynamoConfiguration: dynamo.DynamoConfiguration = {\n        TableName: configuration.eventsTable\n    }\n\n    const deleteByFn = dynamo.deleteBy({dynamoDb: dynamoClient, configuration: dynamoConfiguration})\n\n    const queryFn = dynamo.query<InternalTriggeredEvent>({dynamoDb: dynamoClient, configuration: dynamoConfiguration})\n    const getByFn = dynamo.getBy<InternalTriggeredEvent>({query: queryFn})\n\n    const cleanUpFn = cleanUp({\n        getBy: getByFn,\n        deleteBy: deleteByFn,\n        deleteQueue: deleteQueueFn,\n        unsubscribe: unsubscribeFn,\n    })\n\n    const loadState = configuration.loadStateLambdaArn.map(lambdaArn => {\n        const lambdaClient = new LambdaClient({\n            credentials: credentials\n        })\n        return lambda.query<LoadStateQuery, State>({lambda: lambdaClient, functionName: lambdaArn})\n    }).orElse(async (payload: LoadStateQuery) => Empty())\n\n    const createQueueAndSubscribeFn = createQueueAndSubscribe({\n        now: () => new Date().getTime(),\n        createQueue: createQueueFn,\n        cleanUp: cleanUpFn,\n        subscribeSqs: subscribeSqsFn,\n    })\n    const receiveMessagesFn = receiveMessages({\n        sqsClient: sqsClient,\n        receive: sqs.receiveMessages,\n    })\n\n    if (isChiselTestConfiguration(configuration)) {\n        const lambdaClient = new LambdaClient({\n            credentials: credentials\n        })\n        const commandHandlerClient = lambda.command<Command, CommandResult<State>>({lambda: lambdaClient, functionName: configuration.commandHandlerArn})\n\n        return lowLevelWhen(runAndValidate<State>({\n            sendCommand: commandHandlerClient,\n            createQueueAndSubscribe: createQueueAndSubscribeFn,\n            receiveMessages: receiveMessagesFn,\n            cleanUp: cleanUpFn,\n            configuration,\n            loadState,\n        }))\n    } else {\n        const receiveDLQMessages = sqs.receiveMessages<DLQMessage>({\n            client: sqsClient,\n            configuration: {\n                QueueUrl: configuration.commandDLQUrl,\n                maxNumberOfMessages: 10,\n                waitTimeSeconds: 5,\n                autoAcknowledgeMessages: true,\n            },\n            transformMessage: (message: Message) => {\n                return JSON.parse(Optional(message.Body).orElse('{}')) as DLQMessage\n            },\n        })\n\n        if (isAsyncSqsChiselTestConfiguration(configuration)) {\n            const sendCommand = sqs.send<Command>({\n                client: sqsClient,\n                configuration: {QueueUrl: configuration.commandQueueUrl},\n                withMessageGroupId: configuration.extractMessageGroupId,\n                withDeduplicationId: configuration.extractMessageDeduplicationId,\n            })\n\n            return lowLevelWhen(runAndValidateAsync<State>({\n                sendCommand,\n                createQueueAndSubscribe: createQueueAndSubscribeFn,\n                receiveMessages: receiveMessagesFn,\n                cleanUp: cleanUpFn,\n                receiveErrorMessages: receiveDLQMessages,\n                configuration,\n                loadState,\n            }))\n        } else {\n            const sendCommand = sns.send<Command>({\n                client: snsClient,\n                configuration: {\n                    TopicArn: configuration.commandTopicArn,\n                    Parallelism: 10,\n                    BatchSize: 10,\n                },\n                withMessageGroupId: configuration.extractMessageGroupId,\n                withMessageDeduplicationId: configuration.extractMessageDeduplicationId,\n            })\n\n            return lowLevelWhen(runAndValidateAsync<State>({\n                sendCommand,\n                createQueueAndSubscribe: createQueueAndSubscribeFn,\n                receiveMessages: receiveMessagesFn,\n                cleanUp: cleanUpFn,\n                receiveErrorMessages: receiveDLQMessages,\n                configuration,\n                loadState,\n            }))\n        }\n    }\n\n}\n"]}

package/lib/cjs/utils.d.ts

@@ -0,0 +1,233 @@
+import { Command, CommandResult, InternalTriggeredEvent, ChiselEvent } from '@othree.io/chisel';
+import { Optional } from '@othree.io/optional';
+import { sqs, sns, dynamo } from '@othree.io/awsome';
+import { Message, SQSClient } from '@aws-sdk/client-sqs';
+/**
+ * Custom error class for representing errors that occur during command execution.
+ * @class
+ * @extends {Error}
+ */
+export declare class CommandExecutionError extends Error {
+    static ERROR: string;
+    command: Command;
+    constructor(command: Command, message?: string);
+}
+/**
+ * Represents an error message related to a command placed in a dead-letter queue (DLQ).
+ * @typedef DLQMessage
+ */
+export type DLQMessage = Readonly<{
+    request: Command;
+    error: Readonly<{
+        name: string;
+        message: string;
+        stack?: string;
+    }>;
+}>;
+/**
+ * Represents a query for loading the state using a context identifier.
+ * @typedef LoadStateQuery
+ */
+export type LoadStateQuery = Readonly<{
+    contextId: string;
+}>;
+/**
+ * Represents a Chisel test builder that configures expected events and states for a command.
+ * @typedef ChiselTest
+ * @template State - The type representing the state.
+ */
+export type ChiselTest<State> = Readonly<{
+    /**
+     * Specifies an expected event that should be produced by the command.
+     * @param {ChiselEvent} event - The expected event.
+     * @returns {ChiselTest<State>} The ChiselTest instance with the expected event.
+     */
+    expectEvent: (event: ChiselEvent) => ChiselTest<State>;
+    /**
+     * Specifies an expected state that the system should be in after the command execution.
+     * @param {State} state - The expected state.
+     * @returns {ChiselTest<State>} The ChiselTest instance with the expected state.
+     */
+    expectState: (state: State) => ChiselTest<State>;
+    /**
+     * Executes the command and validates the expected results.
+     * @returns {Promise<CommandResult<State>>} A promise that resolves to the command(s) results.
+     */
+    toPass: () => Promise<Array<CommandResult<State>>>;
+}>;
+export type GetCommand = (contextId: Optional<string>) => Command;
+/**
+ * A specialized extension of the `ChiselTest` type tailored for testing command execution.
+ * @typedef CommandChiselTest
+ * @template State - The type representing the state used in the test.
+ */
+export type CommandChiselTest<State> = Readonly<{
+    and: (getCommand: GetCommand) => CommandChiselTest<State>;
+    toFail: (errorMsg?: string) => Promise<Error>;
+}> & ChiselTest<State>;
+/**
+ * Creates a Chisel test builder based on a given run and validate function.
+ * @template State - The type representing the state.
+ * @param {RunAndValidate<State>} runAndValidate - The function to run and validate a command.
+ * @returns A function that accepts a command and returns a ChiselTest instance.
+ */
+export declare const when: <State>(runAndValidate: RunAndValidate<State>) => (command: Command) => CommandChiselTest<State>;
+/**
+ * Represents the configuration for all types of tests
+ * @typedef BaseTestConfiguration
+ */
+export type BaseTestConfiguration = Readonly<{
+    boundedContext: string;
+    topicArn: string;
+    eventsTable: string;
+    subscriptionAwaitTime: number;
+    testName: string;
+    loadStateLambdaArn: Optional<string>;
+}>;
+/**
+ * Configuration options for a Chisel test.
+ * @typedef ChiselTestConfiguration
+ */
+export type ChiselTestConfiguration = Readonly<{
+    commandHandlerArn: string;
+}> & BaseTestConfiguration;
+/**
+ * Configuration options for an Async SQS Chisel test.
+ * @typedef AsyncSqsChiselTestConfiguration
+ */
+export type AsyncSqsChiselTestConfiguration = Readonly<{
+    commandQueueUrl: string;
+    extractMessageGroupId?: (command: Command) => string;
+    extractMessageDeduplicationId?: (command: Command) => string;
+    commandDLQUrl: string;
+}> & BaseTestConfiguration;
+/**
+ * Configuration options for an Async SNS Chisel test.
+ * @typedef AsyncSnsChiselTestConfiguration
+ */
+export type AsyncSnsChiselTestConfiguration = Readonly<{
+    commandTopicArn: string;
+    extractMessageGroupId?: (command: Command) => string;
+    extractMessageDeduplicationId?: (command: Command) => string;
+    commandDLQUrl: string;
+}> & BaseTestConfiguration;
+/**
+ * Represents the possible configurations for different types of tests.
+ * @typedef {ChiselTestConfiguration | AsyncSqsChiselTestConfiguration | AsyncSnsChiselTestConfiguration} TestConfiguration
+ */
+export type TestConfiguration = ChiselTestConfiguration | AsyncSqsChiselTestConfiguration | AsyncSnsChiselTestConfiguration;
+/**
+ * Determines if the configuration is an ChiselTestConfiguration
+ * @param configuration Test configuration
+ * @returns {boolean} True is configuration is of type ChiselTestConfiguration
+ */
+export declare const isChiselTestConfiguration: (configuration: TestConfiguration) => configuration is ChiselTestConfiguration;
+/**
+ * Determines if the configuration is an AsyncSqsChiselTestConfiguration
+ * @param configuration Test configuration
+ * @returns {boolean} True is configuration is of type AsyncSqsChiselTestConfiguration
+ */
+export declare const isAsyncSqsChiselTestConfiguration: (configuration: TestConfiguration) => configuration is AsyncSqsChiselTestConfiguration;
+/**
+ * Represents a Chisel event message containing attributes, an event, and a state.
+ * @typedef ChiselEventMessage
+ * @template State - The type representing the state.
+ */
+export type ChiselEventMessage<State> = Readonly<{
+    messageAttributes: Readonly<{
+        bc: string;
+        eventType: string;
+    }>;
+    event: InternalTriggeredEvent;
+    state: State;
+}>;
+/**
+ * Function type for cleanup operations including deleting a queue, events, and data.
+ * @typedef {Function} CleanUp
+ */
+export type CleanUp = <State>(queue: SubscribedSqsQueue | sqs.SqsQueue, maybeCommandResults: Optional<Array<CommandResult<State>>>) => Promise<true>;
+/**
+ * Performs cleanup operations including deleting a queue, events, and data.
+ * @function
+ * @param deps - Dependencies for cleanup operations.
+ * @returns {CleanUp} A function that performs cleanup operations.
+ */
+export declare const cleanUp: (deps: {
+    getBy: (keys: dynamo.Keys) => Promise<Optional<Array<InternalTriggeredEvent>>>;
+    deleteBy: (keys: dynamo.Keys) => Promise<Optional<boolean>>;
+    deleteQueue: (request: sqs.DeleteQueueRequest) => Promise<Optional<boolean>>;
+    unsubscribe: (subscription: sns.Subscription) => Promise<Optional<true>>;
+}) => CleanUp;
+/**
+ * Representation of a queue subscribed to a topic
+ * @typedef SubscribedSqsQueue
+ */
+export type SubscribedSqsQueue = Readonly<{
+    subscriptionArn: string;
+}> & sqs.SqsQueue;
+/**
+ * Creates and subscribes to an SQS queue.
+ * @typedef {Function} CreateQueueAndSubscribe
+ */
+export type CreateQueueAndSubscribe = (configuration: TestConfiguration) => Promise<SubscribedSqsQueue | sqs.SqsQueue>;
+/**
+ * Creates and subscribes to an SQS queue.
+ * @function
+ * @param deps - Dependencies for queue creation and subscription.
+ * @returns {CreateQueueAndSubscribe} A function that creates and subscribes to an SQS queue.
+ */
+export declare const createQueueAndSubscribe: (deps: {
+    now: () => number;
+    createQueue: (request: sqs.CreateQueueRequest) => Promise<Optional<sqs.SqsQueue>>;
+    cleanUp: CleanUp;
+    subscribeSqs: (request: sns.SubscribeQueueRequest) => Promise<Optional<sns.Subscription>>;
+}) => CreateQueueAndSubscribe;
+/**
+ * Asynchronous function for receiving messages from an SQS queue.
+ * @function
+ * @param deps - Dependencies for receiving messages.
+ * @returns A function that receives messages from a specified queue URL.
+ */
+export declare const receiveMessages: (deps: {
+    sqsClient: SQSClient;
+    receive: <T>(deps: Readonly<{
+        client: SQSClient;
+        configuration: sqs.ReceiveMessagesConfiguration;
+        transformMessage: (message: Message) => T;
+    }>) => () => Promise<Optional<Array<T>>>;
+}) => (queueUrl: string) => Promise<Array<Message>>;
+/**
+ * A function that runs a command, validates the results, and performs cleanup operations.
+ * @typedef {Function} RunAndValidate
+ */
+export type RunAndValidate<State> = (command: Command, getCommands: Array<GetCommand>, maybeExpectedState: Optional<State>, expectedEvents: Array<ChiselEvent>) => Promise<Array<CommandResult<State>>>;
+/**
+ * Runs a command, validates the results, and performs cleanup operations.
+ * @function
+ * @param deps - Dependencies for running and validating commands.
+ * @returns {RunAndValidate<State>} The run and validate function.
+ */
+export declare const runAndValidate: <State>(deps: {
+    sendCommand: (command: Command) => Promise<Optional<CommandResult<State>>>;
+    createQueueAndSubscribe: CreateQueueAndSubscribe;
+    receiveMessages: (queueUrl: string) => Promise<Array<Message>>;
+    cleanUp: CleanUp;
+    configuration: ChiselTestConfiguration;
+    loadState: (query: LoadStateQuery) => Promise<Optional<State>>;
+}) => RunAndValidate<State>;
+/**
+ * Sends a command to a queue and validates the command events and state.
+ * @function
+ * @param deps - Dependencies for running and validating async commands.
+ * @returns {RunAndValidate<State>} The run and validate function.
+ */
+export declare const runAndValidateAsync: <State>(deps: {
+    sendCommand: (command: Command) => Promise<Optional<boolean>>;
+    createQueueAndSubscribe: CreateQueueAndSubscribe;
+    receiveMessages: (queueUrl: string) => Promise<Array<Message>>;
+    cleanUp: CleanUp;
+    receiveErrorMessages: () => Promise<Optional<Array<DLQMessage>>>;
+    configuration: AsyncSqsChiselTestConfiguration | AsyncSnsChiselTestConfiguration;
+    loadState: (query: LoadStateQuery) => Promise<Optional<State>>;
+}) => RunAndValidate<State>;
+//# sourceMappingURL=utils.d.ts.map