# SubscriptionDefinitionBuilder API

Subscription definition builder is a helper to create and define a subscriptions for a service.
It helps to set all needed filters.

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

Subscription definition builder is a helper to create and define a subscriptions for a service.
It helps to set all needed filters.

Package: `@purista/core`

## Signature

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

## Members

### Constructors

- `new constructor<S, C>(subscriptionName: string, subscriptionDescription: string, deprecated: boolean)`

### Methods

- `addOutputSchema<OutputSchema>(eventName: string, outputSchema: OutputSchema, outputContentType: string, outputContentEncoding: string): SubscriptionDefinitionBuilder<S, SubscriptionDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], OutputSchema, C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"]>>` — 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): SubscriptionDefinitionBuilder<S, SubscriptionDefinitionBuilderTypes<C["PayloadSchema"], ParamsSchema, C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"]>>` — 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): SubscriptionDefinitionBuilder<S, SubscriptionDefinitionBuilderTypes<PayloadSchema, C["ParamsSchema"], C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"]>>` — Add a schema for input payload validation.
Types for payload of message and function payload input are generated from given schema.
- `adviceAutoacknowledgeMessage(acknowledge: boolean): SubscriptionDefinitionBuilder<S, C>` — Instruct the event bridge message broker to autoacknowledge messages as soon as they arrive.
This means, a message will not be resent, if the subscription execution fails unexpected.
- `adviceConsumerFailureHandling(config: DefinitionEventBridgeConsumerFailureHandling): SubscriptionDefinitionBuilder<S, C>` — Advise retry and dead-letter handling for this subscription.
- `adviceDurable(durable: boolean): SubscriptionDefinitionBuilder<S, C>` — False: defines the subscription as a live-subscription, which is only able to process messages while the subscription itself is running.
- `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): SubscriptionDefinitionBuilder<S, SubscriptionDefinitionBuilderTypes<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"]>>`
- `canEmit<EventName, T>(eventName: EventName, schema: T): SubscriptionDefinitionBuilder<S, SubscriptionDefinitionBuilderTypes<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 subscription can emit.
- `canInvoke<Output, Payload, Parameter, SName, Version, Fname>(serviceName: SName, serviceVersion: Version, serviceTarget: Fname, outputSchema?: Output, payloadSchema?: Payload, parameterSchema?: Parameter): SubscriptionDefinitionBuilder<S, SubscriptionDefinitionBuilderTypes<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"]>>` — Define a command which can be invoked by the current subscription
- `filterForMessageType(messageType: EBMessageType): SubscriptionDefinitionBuilder<S, C>` — Adds a filter to match specific message type.
- `filterPrincipalId<T>(principalId: NonEmptyString<T>): SubscriptionDefinitionBuilder<S, C>` — Filter messages only for principalId
- `filterReceivedBy<N, V, T, I>(serviceName: NonEmptyString<N> | undefined, serviceVersion: NonEmptyString<V> | undefined, serviceTarget: NonEmptyString<T> | undefined, instanceId: NonEmptyString<I> | undefined): SubscriptionDefinitionBuilder<S, C>` — Add filter to only match messages received by given service function & version.
Set one or more parameters to undefined means "do not filter by this criteria".
For example:
- `filterSentFrom<N, V, T, I>(serviceName: NonEmptyString<N> | undefined, serviceVersion: NonEmptyString<V> | undefined, serviceTarget: NonEmptyString<T> | undefined, instanceId: NonEmptyString<I> | undefined): SubscriptionDefinitionBuilder<S, C>` — Add filter to only match messages send by given service function & version.
Set one or more parameters to undefined means "do not filter by this criteria".
For example:
- `filterTenantId<T>(tenantId: NonEmptyString<T>): SubscriptionDefinitionBuilder<S, C>` — Filter messages only for tenantId
- `getDefinition(): Promise<Complete<SubscriptionDefinition<S, 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"], SubscriptionDefinitionMetadataBase, C["QueueInvokes"]>>>` — Returns the final subscription definition which will be passed into the service class.
- `getSubscriptionFunction(): SubscriptionFunction<S, 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 and after hooks are triggered during execution.
- `getSubscriptionFunctionPlain(): SubscriptionFunction<S, 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.
- `getSubscriptionTransformContextMock(input: { message: EBMessage; resources: C["Resources"]; sandbox: SinonSandbox }): { mock: { configs: { getConfig: ConfigGetterFunction; removeConfig: ConfigDeleteFunction; setConfig: ConfigSetterFunction }; logger: Logger; message: Readonly<EBMessage>; metrics: PuristaMetricContext<Metrics>; queue: QueueContext; resources: EmptyObject; ... }; 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.
- `getTransformInputFunction(): SubscriptionTransformInputHook<S, Infer<C["TransformInputPayloadSchema"]>, Infer<C["TransformInputParamsSchema"]>, InferIn<C["PayloadSchema"]>, InferIn<C["ParamsSchema"]>> | undefined` — Return the transform input function
- `getTransformOutputFunction(): SubscriptionTransformOutputHook<S, Infer<C["OutputSchema"]>, Infer<C["ParamsSchema"]>, InferIn<C["TransformOutputSchema"]>> | undefined` — Return the transform output function
- `markAsDeprecated(): SubscriptionDefinitionBuilder<S, C>` — Mark this subscription as deprecated
- `receiveMessageOnEveryInstance(enforce: boolean): SubscriptionDefinitionBuilder<S, C>` — Instruct the event bridge message broker to send the matching message to every running instance.
The underlaying message broker must support this functionality.
- `setAfterGuardHooks(afterGuards: Record<string, SubscriptionAfterGuardHook<S, Infer<C["OutputSchema"]>, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"]>>): SubscriptionDefinitionBuilder<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, SubscriptionBeforeGuardHook<S, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"]>>): SubscriptionDefinitionBuilder<S, C>` — Set one or more before guard hook(s).
If there are multiple before guard hooks, they are executed in parallel
- `setSubscriptionFunction(fn: SubscriptionFunction<S, Infer<C["PayloadSchema"]>, Infer<C["ParamsSchema"]>, InferIn<C["OutputSchema"]>, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"], C["QueueInvokes"]>): SubscriptionDefinitionBuilder<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.
- `setTransformInput<TransformInputPayloadSchema, TransformInputParamsSchema>(transformInputSchema: TransformInputPayloadSchema, transformParameterSchema: TransformInputParamsSchema, transformFunction: SubscriptionTransformInputHook<S, Infer<TransformInputPayloadSchema>, Infer<TransformInputParamsSchema>, InferIn<C["PayloadSchema"]>, InferIn<C["ParamsSchema"]>>, inputContentType?: string, inputContentEncoding?: string): SubscriptionDefinitionBuilder<S, SubscriptionDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], C["OutputSchema"], TransformInputPayloadSchema, TransformInputParamsSchema, C["TransformOutputSchema"], C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"]>>` — 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: SubscriptionTransformOutputHook<S, Infer<C["OutputSchema"]>, Infer<C["ParamsSchema"]>, InferIn<TransformOutputSchema>>, outputContentType?: string, outputContentEncoding?: string): SubscriptionDefinitionBuilder<S, SubscriptionDefinitionBuilderTypes<C["PayloadSchema"], C["ParamsSchema"], C["OutputSchema"], C["TransformInputPayloadSchema"], C["TransformInputParamsSchema"], TransformOutputSchema, C["Resources"], C["Invokes"], C["StreamInvokes"], C["EmitList"]>>` — 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.
- `subscribeToEvent<N, V>(eventName: NonEmptyString<N>, serviceVersion?: NonEmptyString<V>): SubscriptionDefinitionBuilder<S, C>` — Add a filter to only subscribe to messages with matching event name