# CommandDefinitionBuilder API

Command definition builder is a helper to create and define a command for a service.
It helps to set all needed information like schemas and hooks.
With these information, the types are automatically set and extended.

---
Canonical: /handbook/api/classes/_purista_core.CommandDefinitionBuilder/
Source: CommandDefinitionBuilder/CommandDefinitionBuilder.impl.ts
Format: Markdown for agents
---

Command definition builder is a helper to create and define a command for a service.
It helps to set all needed information like schemas and hooks.
With these information, the types are automatically set and extended.

Package: `@purista/core`

## Signature

```typescript
class CommandDefinitionBuilder<S, C>
```

## Members

### Constructors

- `new constructor<S, C>(commandName: string, commandDescription: string, eventName?: string, deprecated: boolean)`

### Methods

- `addOpenApiErrorStatusCodes(...codes: StatusCode[]): CommandDefinitionBuilder<S, C>` — If a function can return other status codes, than the default ones, you should add them to openApi definition.
By default, 200, 204, 400, 401 and 500 can be autogenerated in most cases.
Special cases or different status codes should be added with this function.
- `addOpenApiTags(...tags: string[]): CommandDefinitionBuilder<S, C>` — Add tags for openApi definition for given function.
It is recommended to use some enum for tags to avoid typo issues.
- `addOutputSchema<OutputSchema>(outputSchema: OutputSchema, outputContentType?: string, outputContentEncoding?: string): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], OutputSchema, C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>>` — Add a schema for output payload validation.
Types for payload of message and function payload output are generated from given schema.
- `addParameterSchema<ParamsSchema>(parameterSchema: ParamsSchema): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<C["PayloadSchema"], ParamsSchema, C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>>` — Add a schema for output parameter validation.
Types for parameter of message and function parameter output are generated from given schema.
- `addPayloadSchema<PayloadSchema>(inputSchema: PayloadSchema, inputContentType?: string, inputContentEncoding?: string): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<PayloadSchema, C["ParamsSchema"], C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>>` — Add a schema for input payload validation.
Types for payload of message and function payload input are generated from given schema.
- `addQueryParameters(...queryParams: QueryParameter<Infer<C["ParamsSchema"]>>[]): CommandDefinitionBuilder<S, C>` — Define query parameters if you expose the function as http endpoint.
Query parameters are add to openApi definition.
Query parameters are add to input parameters.
- `adviceAutoacknowledgeMessages(acknowledge: boolean): CommandDefinitionBuilder<S, C>` — Instruct the event bridge message broker to autoacknowledge commands as soon as they arrive.
This means, a message will not be resent, if the command execution fails unexpected.
- `canConsumeStream<Chunk, Final, Payload, Parameter, SName, Version, Fname>(serviceName: SName, serviceVersion: Version, serviceTarget: Fname, chunkSchema?: Chunk, payloadSchema?: Payload, parameterSchema?: Parameter, finalSchema?: Final, validateChunk: boolean, validateFinal: boolean): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"] & Record<SName, Record<unknown, unknown>>, C["EmitList"], C["QueueInvokes"]>>` — Declare a stream this command handler may consume through its typed stream proxy.
- `canEmit<EventName, T>(eventName: EventName, schema: T): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"] & Record<EventName, InferIn<unknown>>>>` — Define which custom events the command can emit.
- `canEnqueue<Payload, Parameter, QueueName>(queueName: QueueName, payloadSchema?: Payload, parameterSchema?: Parameter): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"] & Record<QueueName, { parameterSchema: unknown; payloadSchema: unknown }>>>` — Declare a queue this command handler may enqueue through its typed queue proxy.
- `canInvoke<Output, Payload, Parameter, SName, Version, Fname>(serviceName: SName, serviceVersion: Version, serviceTarget: Fname, outputSchema?: Output, payloadSchema?: Payload, parameterSchema?: Parameter): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"] & Record<SName, Record<unknown, unknown>>, C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>>` — Define a command which can be invoked by the current command
- `disableHttpSecurity(disabled: boolean): CommandDefinitionBuilder<S, C>` — enable or disable security for this endpoint
- `enableHttpSecurity(enabled: boolean): CommandDefinitionBuilder<S, C>` — enable or disable security for this endpoint
- `exposeAsHttpEndpoint(method: SupportedHttpMethod, path: string, contentTypeRequest?: string, contentEncodingRequest?: string, contentTypeResponse?: string, contentEncodingResponse?: string, options?: HttpExposureOptions): CommandDefinitionBuilder<S, C>` — Mark the function to be exposed as http endpoint.
- `getAfterGuardHook(name: string): CommandAfterGuardHook<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, Infer<C["OutputSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>` — Returns the after guard hook corresponding to the provided name.
- `getBeforeGuardHook(name: string): CommandBeforeGuardHook<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>` — Get the before guard hook for this command.
- `getCommandFunction<T>(input?: { beforeGuards: Partial<T> }): CommandFunction<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, InferIn<C["PayloadSchema"]>, InferIn<C["ParamsSchema"]>, InferIn<C["OutputSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>` — Get the function implementation including input and output validation.
Also, before hooks are triggered during execution.
Before guards can be optional overwritten by optional input parameter.
- `getCommandFunctionPlain(): CommandFunction<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, InferIn<C["OutputSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>` — Get the function implementation without input and output validation.
No hooks are triggered during execution.
- `getCommandTransformContextMock(input: { parameter: GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>; payload: GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>; resources: Partial<C["Resources"]>; sandbox: SinonSandbox }): { mock: { configs: { getConfig: ConfigGetterFunction; removeConfig: ConfigDeleteFunction; setConfig: ConfigSetterFunction }; logger: Logger; message: Readonly<Command<PayloadType, ParameterType>>; metrics: PuristaMetricContext<Metrics>; queue: QueueContext; resources: C["Resources"]; ... }; stubs: { enqueue: SinonStub<any[], any>; getConfig: SinonStub<any[], any>; getSecret: SinonStub<any[], any>; getState: SinonStub<any[], any>; logger: { debug: SinonStub<unknown[], any>; error: SinonStub<unknown[], any>; fatal: SinonStub<unknown[], any>; info: SinonStub<unknown[], any>; trace: SinonStub<unknown[], any>; warn: SinonStub<unknown[], any> }; removeConfig: SinonStub<any[], any>; ... } }` — Returns a mocked transform function context, which can be used in unit tests.
- `getDefinition(): Promise<Complete<CommandDefinition<S, GetMessagePayloadType<unknown[unknown], unknown[unknown]>, GetMessageParamsType<unknown[unknown], unknown[unknown]>, Infer<unknown[unknown]>, Infer<unknown[unknown]>, Infer<unknown[unknown]>, Infer<unknown[unknown]>, InferIn<unknown[unknown]>, Infer<unknown[unknown]>, InferIn<unknown[unknown]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], CommandDefinitionMetadataBase, C["QueueInvokes"]>>>` — Creates and returns the CommandDefinition used as input for the service.
- `getTransformInputFunction(): CommandTransformInputHook<S, InferIn<C["TransformInputPayloadSchema"]>, InferIn<C["TransformInputParamsSchema"]>, Infer<C["TransformInputPayloadSchema"]>, Infer<C["TransformInputParamsSchema"]>, InferIn<C["PayloadSchema"]>, InferIn<C["ParamsSchema"]>, C["Resources"]> | undefined` — Return the transform input function
- `getTransformOutputFunction(): CommandTransformOutputHook<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["OutputSchema"]>, Infer<C["ParamsSchema"]>, InferIn<C["TransformOutputSchema"]>, C["Resources"]> | undefined` — Return the transform output function
- `makeEndpointPublic(): CommandDefinitionBuilder<S, C>` — Mark the endpoint to be public available.
No security check like bearer token or basic auth is required to access the endpoint.
- `markAsDeprecated(): CommandDefinitionBuilder<S, C>` — Mark this endpoint/command as deprecated
- `markSchedulable(options: ScheduleOptions & { description: string; name: string }): CommandDefinitionBuilder<S, C>` — Mark this command as a short, idempotent schedule target.
- `setAfterGuardHooks(afterGuards: Record<string, CommandAfterGuardHook<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, Infer<C["OutputSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>>): CommandDefinitionBuilder<S, C>` — Set one or more after guard hook(s).
If there are multiple after guard hooks, they are executed in parallel
- `setBeforeGuardHooks(beforeGuards: Record<string, CommandBeforeGuardHook<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>>): CommandDefinitionBuilder<S, C>` — Set one or more before guard hook(s).
If there are multiple before guard hooks, they are executed in parallel
- `setCommandFunction(fn: CommandFunction<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, InferIn<C["OutputSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>): CommandDefinitionBuilder<S, C>` — Required: Set the function implementation.
The types should be automatically set as soon as schemas previously defined.
As the function will be a a function of a service class you need to implement as function declaration.
Arrow functions do not have access to the `this` scope.
- `setOpenApiOperationId(operationId: string): CommandDefinitionBuilder<S, C>` — Set the operationId for openApi documentation
- `setOpenApiSummary(summary: string): CommandDefinitionBuilder<S, C>` — Set the function summary text used for example in openApi documentation
- `setSuccessEventName<N>(eventName: NonEmptyString<N>): CommandDefinitionBuilder<S, C>`
- `setTransformInput<TransformInputPayloadSchema, TransformInputParamsSchema>(transformInputSchema: TransformInputPayloadSchema, transformParameterSchema: TransformInputParamsSchema, transformFunction: CommandTransformInputHook<S, InferIn<TransformInputPayloadSchema>, InferIn<TransformInputParamsSchema>, Infer<TransformInputPayloadSchema>, Infer<TransformInputParamsSchema>, InferIn<C["PayloadSchema"]>, InferIn<C["ParamsSchema"]>, C["Resources"]>, inputContentType?: string, inputContentEncoding?: string): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], C["OutputSchema"], TransformInputPayloadSchema, TransformInputParamsSchema, C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>>` — Set a transform input hook which will encode or transform the input payload and parameters.
Will be executed as first step before input validation, before guard and the function itself.
This will change the type of input message payload and input message parameter.
- `setTransformOutput<TransformOutputSchema>(transformOutputSchema: TransformOutputSchema, transformFunction: CommandTransformOutputHook<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["OutputSchema"]>, Infer<C["ParamsSchema"]>, InferIn<TransformOutputSchema>, C["Resources"]>, outputContentType?: string, outputContentEncoding?: string): CommandDefinitionBuilder<S, CommandDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], TransformOutputSchema, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>>` — Set a transform output hook which will encode or transform the response payload.
Will be executed at very last step after function execution, output validation and after guard hooks.
This will change the type of output message payload.