Classes · @purista/core
CommandDefinitionBuilder
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.
Signature
class CommandDefinitionBuilder<S, C>Constructors
1 entry
constructor
Constructor
new constructor<S, C>(commandName: string, commandDescription: string, eventName?: string, deprecated: boolean)Methods
33 entries
addOpenApiErrorStatusCodes
Method
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
Method
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
Method
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
Method
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
Method
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
Method
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
Method
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
Method
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
Method
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
Method
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
Method
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
Method
disableHttpSecurity(disabled: boolean): CommandDefinitionBuilder<S, C>enable or disable security for this endpoint
enableHttpSecurity
Method
enableHttpSecurity(enabled: boolean): CommandDefinitionBuilder<S, C>enable or disable security for this endpoint
exposeAsHttpEndpoint
Method
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
Method
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
Method
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
Method
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
Method
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
Method
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
Method
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
Method
getTransformInputFunction(): CommandTransformInputHook<S, InferIn<C["TransformInputPayloadSchema"]>, InferIn<C["TransformInputParamsSchema"]>, Infer<C["TransformInputPayloadSchema"]>, Infer<C["TransformInputParamsSchema"]>, InferIn<C["PayloadSchema"]>, InferIn<C["ParamsSchema"]>, C["Resources"]> | undefinedReturn the transform input function
getTransformOutputFunction
Method
getTransformOutputFunction(): CommandTransformOutputHook<S, GetMessagePayloadType<C["PayloadSchema"], C["TransformInputPayloadSchema"]>, GetMessageParamsType<C["ParamsSchema"], C["TransformInputParamsSchema"]>, Infer<C["OutputSchema"]>, Infer<C["ParamsSchema"]>, InferIn<C["TransformOutputSchema"]>, C["Resources"]> | undefinedReturn the transform output function
makeEndpointPublic
Method
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
Method
markAsDeprecated(): CommandDefinitionBuilder<S, C>Mark this endpoint/command as deprecated
markSchedulable
Method
markSchedulable(options: ScheduleOptions & { description: string; name: string }): CommandDefinitionBuilder<S, C>Mark this command as a short, idempotent schedule target.
setAfterGuardHooks
Method
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
Method
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
Method
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
Method
setOpenApiOperationId(operationId: string): CommandDefinitionBuilder<S, C>Set the operationId for openApi documentation
setOpenApiSummary
Method
setOpenApiSummary(summary: string): CommandDefinitionBuilder<S, C>Set the function summary text used for example in openApi documentation
setSuccessEventName
Method
setSuccessEventName<N>(eventName: NonEmptyString<N>): CommandDefinitionBuilder<S, C>setTransformInput
Method
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
Method
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.