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.

@purista/core Source

Signature

CommandDefinitionBuilder.ts typescript 
class CommandDefinitionBuilder<S, C>

Constructors

1 entry

constructor

Constructor

Source
constructor.ts typescript 
new constructor<S, C>(commandName: string, commandDescription: string, eventName?: string, deprecated: boolean)

Methods

33 entries

addOpenApiErrorStatusCodes

Method

Source
addOpenApiErrorStatusCodes.ts typescript 
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

Source
addOpenApiTags.ts typescript 
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

Source
addOutputSchema.ts typescript 
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

Source
addParameterSchema.ts typescript 
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

Source
addPayloadSchema.ts typescript 
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

Source
addQueryParameters.ts typescript 
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

Source
adviceAutoacknowledgeMessages.ts typescript 
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

Source
canConsumeStream.ts typescript 
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

Source
canEmit.ts typescript 
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

Source
canEnqueue.ts typescript 
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

Source
canInvoke.ts typescript 
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

Source
disableHttpSecurity.ts typescript 
disableHttpSecurity(disabled: boolean): CommandDefinitionBuilder<S, C>

enable or disable security for this endpoint

enableHttpSecurity

Method

Source
enableHttpSecurity.ts typescript 
enableHttpSecurity(enabled: boolean): CommandDefinitionBuilder<S, C>

enable or disable security for this endpoint

exposeAsHttpEndpoint

Method

Source
exposeAsHttpEndpoint.ts typescript 
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

Source
getAfterGuardHook.ts typescript 
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

Source
getBeforeGuardHook.ts typescript 
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

Source
getCommandFunction.ts typescript 
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

Source
getCommandFunctionPlain.ts typescript 
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

Source
getCommandTransformContextMock.ts typescript 
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

Source
getDefinition.ts typescript 
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

Source
getTransformInputFunction.ts typescript 
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

Method

Source
getTransformOutputFunction.ts typescript 
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

Method

Source
makeEndpointPublic.ts typescript 
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

Source
markAsDeprecated.ts typescript 
markAsDeprecated(): CommandDefinitionBuilder<S, C>

Mark this endpoint/command as deprecated

markSchedulable

Method

Source
markSchedulable.ts typescript 
markSchedulable(options: ScheduleOptions & { description: string; name: string }): CommandDefinitionBuilder<S, C>

Mark this command as a short, idempotent schedule target.

setAfterGuardHooks

Method

Source
setAfterGuardHooks.ts typescript 
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

Source
setBeforeGuardHooks.ts typescript 
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

Source
setCommandFunction.ts typescript 
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

Source
setOpenApiOperationId.ts typescript 
setOpenApiOperationId(operationId: string): CommandDefinitionBuilder<S, C>

Set the operationId for openApi documentation

setOpenApiSummary

Method

Source
setOpenApiSummary.ts typescript 
setOpenApiSummary(summary: string): CommandDefinitionBuilder<S, C>

Set the function summary text used for example in openApi documentation

setSuccessEventName

Method

Source
setSuccessEventName.ts typescript 
setSuccessEventName<N>(eventName: NonEmptyString<N>): CommandDefinitionBuilder<S, C>

setTransformInput

Method

Source
setTransformInput.ts typescript 
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

Source
setTransformOutput.ts typescript 
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.