PURISTA API / @purista/core / ServiceBuilder

Class: ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:103

This class is used to build a service.

Type Parameters

S

S extends ServiceBuilderTypes<any, any, any, any, any> = ServiceBuilderTypes

Constructors

Constructor

new ServiceBuilder<S>(info): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:135

Parameters

info

ServiceInfoType

Returns

ServiceBuilder<S>

Properties

info

info: ServiceInfoType

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:135

SClass

SClass: Newable<S["ServiceClassType"], ServiceClassTypes<S["ConfigType"], S["Resources"], S["Metrics"]>> = Service

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:132

Methods

addAgentDefinition()

addAgentDefinition<Definition>(...definitions): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:239

Add one or more attached agent definitions to this service.

The attached agent is expanded into normal queue, queue worker, command, and stream definitions so the rest of core can treat it like any other declared PURISTA boundary.

Type Parameters

Definition

Definition extends AttachedAgentDefinition<any>

Parameters

definitions

...Definition[]

Returns

ServiceBuilder<S>

Example

const triage = await service
  .getAgentQueueBuilder('triageTicket', 'Triage a support ticket')
  .setRunFunction(async context => ({ priority: 'normal' }))
  .getDefinition()

service.addAgentDefinition(triage)

addCommandDefinition()

addCommandDefinition(...commands): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:167

Parameters

commands

...CommandDefinitionList<S["ServiceClassType"]>

Returns

ServiceBuilder<S>

addQueueDefinition()

addQueueDefinition(...queues): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:200

Parameters

queues

...QueueDefinitionList<S["ServiceClassType"]>

Returns

ServiceBuilder<S>

addQueueWorkerDefinition()

addQueueWorkerDefinition(...workers): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:211

Parameters

workers

...QueueWorkerDefinitionList<S["ServiceClassType"]>

Returns

ServiceBuilder<S>

addScheduleDefinition()

addScheduleDefinition(...schedules): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:259

Parameters

schedules

...ScheduleDefinition[]

Returns

ServiceBuilder<S>

addStreamDefinition()

addStreamDefinition(...streams): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:189

Parameters

streams

...StreamDefinitionList<S["ServiceClassType"]>

Returns

ServiceBuilder<S>

addSubscriptionDefinition()

addSubscriptionDefinition(...subscription): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:178

Parameters

subscription

...SubscriptionDefinitionList<S["ServiceClassType"]>

Returns

ServiceBuilder<S>

bindEventToQueue()

bindEventToQueue(eventName, queueName, options?): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:280

Bind a custom event to a durable queue job through a generated bounded subscription.

Parameters

eventName

string

queueName

string

options?

Omit<EventToQueueBindingDefinition, "eventName" | "queueName" | "idempotencyMode"> & object = {}

Returns

ServiceBuilder<S>

Example

service.bindEventToQueue('billing.monthlyCycleDue', 'billing.monthlyClosing', {
  idempotencyKey: event => `billing-cycle:${event.cycleId}`,
})

defineMetric()

defineMetric<MetricName, Definition>(name, definition): ServiceBuilder<SetNewTypeValues<S, { Metrics: Metrics; ServiceClassType: Service<ServiceClassTypes<S["ConfigType"], S["Resources"], Metrics>>; }>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:365

Declare a custom application metric available in every service handler.

Type Parameters

MetricName

MetricName extends string

Definition

Definition extends PuristaMetricDefinition<any>

Parameters

name

MetricName

definition

Definition

Returns

ServiceBuilder<SetNewTypeValues<S, { Metrics: Metrics; ServiceClassType: Service<ServiceClassTypes<S["ConfigType"], S["Resources"], Metrics>>; }>>

Example

const service = new ServiceBuilder(serviceInfo).defineMetric('app.orders.created', {
  kind: 'counter',
  unit: '{order}',
  description: 'Created orders',
})

defineResource()

defineResource<ResourceName, ResourcesType>(): ServiceBuilder<SetNewTypeValue<S, "Resources", S["Resources"] & { [K in string]: InstanceOrType<ResourcesType> }>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:346

Type Parameters

ResourceName

ResourceName extends string

ResourcesType

ResourcesType

Returns

ServiceBuilder<SetNewTypeValue<S, "Resources", S["Resources"] & { [K in string]: InstanceOrType<ResourcesType> }>>

getAgentQueueBuilder()

getAgentQueueBuilder<AgentName>(agentName, description): AgentQueueBuilder<AgentQueueBuilderTypes<Schema, Schema, Schema, S["Resources"] extends Record<string, unknown> ? any[any] : Record<string, never>, Record<never, never>, Record<never, never>, Record<never, never>, undefined, S["Metrics"]>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:592

Create a native core builder for a queue-backed PURISTA agent.

The returned builder preserves this service builder's resource type and cascades payload, parameter, output, model, command-tool, and child-agent declarations into the agent handler context.

Type Parameters

AgentName

AgentName extends string

Parameters

agentName

NonEmptyString<AgentName>

description

string

Returns

AgentQueueBuilder<AgentQueueBuilderTypes<Schema, Schema, Schema, S["Resources"] extends Record<string, unknown> ? any[any] : Record<string, never>, Record<never, never>, Record<never, never>, Record<never, never>, undefined, S["Metrics"]>>

Example

const triage = service
  .getAgentQueueBuilder('triageTicket', 'Triage a support ticket')
  .addModel('primary', { model: 'gpt-4.1-mini', capabilities: ['object'] })

getCommandBuilder()

getCommandBuilder<T, N>(commandName, description, eventName?): CommandDefinitionBuilder<S["ServiceClassType"], CommandDefinitionBuilderTypes<Schema, Schema, Schema, Schema, Schema, Schema, S["Resources"], InvokeList, StreamInvokeList, Record<string, Schema>, QueueInvokeList>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:497

Type Parameters

T

T extends string

N

N extends string

Parameters

commandName

NonEmptyString<T>

description

string

eventName?

NonEmptyString<N>

Returns

CommandDefinitionBuilder<S["ServiceClassType"], CommandDefinitionBuilderTypes<Schema, Schema, Schema, Schema, Schema, Schema, S["Resources"], InvokeList, StreamInvokeList, Record<string, Schema>, QueueInvokeList>>

getCommandDefinitions()

getCommandDefinitions(): CommandDefinitionListResolved<S["ServiceClassType"]>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:613

Returns

CommandDefinitionListResolved<S["ServiceClassType"]>

getCustomClass()

getCustomClass(): Newable<S["ServiceClassType"], ServiceClassTypes<S["ConfigType"], S["Resources"], S["Metrics"]>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:389

Returns

Newable<S["ServiceClassType"], ServiceClassTypes<S["ConfigType"], S["Resources"], S["Metrics"]>>

getEventToQueueBindings()

getEventToQueueBindings(): EventToQueueBindingDefinition[]

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:685

Returns

EventToQueueBindingDefinition[]

getFullServiceDefinition()

getFullServiceDefinition(): Promise<{ commands: CommandDefinitionListResolved<S["ServiceClassType"]>; deprecated: boolean; eventToQueueBindings: EventToQueueBindingDefinition[]; queues: QueueDefinitionListResolved<S["ServiceClassType"]>; queueWorkers: QueueWorkerDefinitionListResolved<S["ServiceClassType"]>; schedules: ScheduleDefinition[]; serviceDescription: string; serviceName: string; serviceVersion: string; streams: StreamDefinitionListResolved<S["ServiceClassType"]>; subscriptions: SubscriptionDefinitionListResolved<S["ServiceClassType"]>; }>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:782

Returns

Promise<{ commands: CommandDefinitionListResolved<S["ServiceClassType"]>; deprecated: boolean; eventToQueueBindings: EventToQueueBindingDefinition[]; queues: QueueDefinitionListResolved<S["ServiceClassType"]>; queueWorkers: QueueWorkerDefinitionListResolved<S["ServiceClassType"]>; schedules: ScheduleDefinition[]; serviceDescription: string; serviceName: string; serviceVersion: string; streams: StreamDefinitionListResolved<S["ServiceClassType"]>; subscriptions: SubscriptionDefinitionListResolved<S["ServiceClassType"]>; }>

getInstance()

getInstance(eventBridge, options?): Promise<S["ServiceClassType"]>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:393

Parameters

eventBridge

EventBridge

options?

{ [K in string | number | symbol]: ({ ai?: AgentRuntimeOptions<Record<string, AgentModelBinding>>; configStore?: ConfigStore; logger?: Logger; logLevel?: LogLevelName; metrics?: PuristaMetricsRuntimeOptions; metricsRecorder?: PuristaMetricsRecorderInterface; queueBridge?: QueueBridge; queueJobStore?: QueueJobStore; secretStore?: SecretStore; spanProcessor?: SpanProcessor; stateStore?: StateStore } & (keyof S["Resources"] extends never ? { resources?: undefined } : { resources: S["Resources"] }) & (keyof S["ConfigInputType"] extends never ? { serviceConfig?: undefined } : { serviceConfig?: S["ConfigInputType"] }))[K] }

Returns

Promise<S["ServiceClassType"]>

getQueueBuilder()

getQueueBuilder<T>(queueName, description): QueueDefinitionBuilder

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:643

Type Parameters

T

T extends string

Parameters

queueName

NonEmptyString<T>

description

string

Returns

QueueDefinitionBuilder

getQueueDefinitions()

getQueueDefinitions(): QueueDefinitionListResolved<S["ServiceClassType"]>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:655

Returns

QueueDefinitionListResolved<S["ServiceClassType"]>

getQueueWorkerBuilder()

getQueueWorkerBuilder<T>(queueName, workerName): QueueWorkerBuilder

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:647

Type Parameters

T

T extends string

Parameters

queueName

NonEmptyString<T>

workerName

string

Returns

QueueWorkerBuilder

getQueueWorkerDefinitions()

getQueueWorkerDefinitions(): QueueWorkerDefinitionListResolved<S["ServiceClassType"]>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:665

Returns

QueueWorkerDefinitionListResolved<S["ServiceClassType"]>

getScheduleBuilder()

getScheduleBuilder<T>(scheduleName, description): ScheduleDefinitionBuilder

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:651

Type Parameters

T

T extends string

Parameters

scheduleName

NonEmptyString<T>

description

string

Returns

ScheduleDefinitionBuilder

getScheduleDefinitions()

getScheduleDefinitions(): ScheduleDefinition[]

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:675

Returns

ScheduleDefinition[]

getStreamBuilder()

getStreamBuilder<T, N>(streamName, description, finalEventName?): StreamDefinitionBuilder<S["ServiceClassType"], StreamDefinitionBuilderTypes<Schema, Schema, Schema, Schema, S["Resources"], InvokeList, StreamInvokeList, Record<string, Schema>, QueueInvokeList>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:557

Type Parameters

T

T extends string

N

N extends string

Parameters

streamName

NonEmptyString<T>

description

string

finalEventName?

NonEmptyString<N>

Returns

StreamDefinitionBuilder<S["ServiceClassType"], StreamDefinitionBuilderTypes<Schema, Schema, Schema, Schema, S["Resources"], InvokeList, StreamInvokeList, Record<string, Schema>, QueueInvokeList>>

getStreamDefinitions()

getStreamDefinitions(): StreamDefinitionListResolved<S["ServiceClassType"]>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:633

Returns

StreamDefinitionListResolved<S["ServiceClassType"]>

getSubscriptionBuilder()

getSubscriptionBuilder<T>(subscriptionName, description): SubscriptionDefinitionBuilder<S["ServiceClassType"], SubscriptionDefinitionBuilderTypes<any, any, any, any, any, any, S["Resources"], InvokeList, StreamInvokeList, Record<string, Schema>, QueueInvokeList>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:520

Type Parameters

T

T extends string

Parameters

subscriptionName

NonEmptyString<T>

description

string

Returns

SubscriptionDefinitionBuilder<S["ServiceClassType"], SubscriptionDefinitionBuilderTypes<any, any, any, any, any, any, S["Resources"], InvokeList, StreamInvokeList, Record<string, Schema>, QueueInvokeList>>

getSubscriptionDefinitions()

getSubscriptionDefinitions(): SubscriptionDefinitionListResolved<S["ServiceClassType"]>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:623

Returns

SubscriptionDefinitionListResolved<S["ServiceClassType"]>

markAsDeprecated()

markAsDeprecated(): ServiceBuilder<S>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:162

Returns

ServiceBuilder<S>

resolveDefinitions()

resolveDefinitions(): Promise<{ commands: CommandDefinitionListResolved<S["ServiceClassType"]>; eventToQueueBindings: EventToQueueBindingDefinition[]; queues: QueueDefinitionListResolved<S["ServiceClassType"]>; queueWorkers: QueueWorkerDefinitionListResolved<S["ServiceClassType"]>; schedules: ScheduleDefinition[]; streams: StreamDefinitionListResolved<S["ServiceClassType"]>; subscriptions: SubscriptionDefinitionListResolved<S["ServiceClassType"]>; }>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:305

Returns

Promise<{ commands: CommandDefinitionListResolved<S["ServiceClassType"]>; eventToQueueBindings: EventToQueueBindingDefinition[]; queues: QueueDefinitionListResolved<S["ServiceClassType"]>; queueWorkers: QueueWorkerDefinitionListResolved<S["ServiceClassType"]>; schedules: ScheduleDefinition[]; streams: StreamDefinitionListResolved<S["ServiceClassType"]>; subscriptions: SubscriptionDefinitionListResolved<S["ServiceClassType"]>; }>

setConfigSchema()

setConfigSchema<T>(schema): ServiceBuilder<SetNewTypeValues<S, { ConfigInputType: InferIn<T> extends Record<string, unknown> ? InferIn : NeverObject; ConfigType: Infer<T> extends Record<string, unknown> ? Infer : NeverObject; ServiceClassType: Service<ServiceClassTypes<Infer<T> extends Record<string, unknown> ? Infer : EmptyObject, S["Resources"], S["Metrics"]>>; }>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:137

Type Parameters

T

T extends Schema

Parameters

schema

T

Returns

ServiceBuilder<SetNewTypeValues<S, { ConfigInputType: InferIn<T> extends Record<string, unknown> ? InferIn : NeverObject; ConfigType: Infer<T> extends Record<string, unknown> ? Infer : NeverObject; ServiceClassType: Service<ServiceClassTypes<Infer<T> extends Record<string, unknown> ? Infer : EmptyObject, S["Resources"], S["Metrics"]>>; }>>

setCustomClass()

setCustomClass<T>(customClass): ServiceBuilder<SetNewTypeValue<S, "ServiceClassType", T>>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:382

Type Parameters

T

T extends Service<ServiceClassTypes<S["ConfigType"], S["Resources"], S["Metrics"]>>

Parameters

customClass

Newable<T, ServiceClassTypes<S["ConfigType"], S["Resources"], S["Metrics"]>>

Returns

ServiceBuilder<SetNewTypeValue<S, "ServiceClassType", T>>

setDefaultConfig()

setDefaultConfig(config): this

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:157

Parameters

config

Complete<S["ConfigType"]>

Returns

this

testServiceSetup()

testServiceSetup(): Promise<boolean>

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:695

Returns

Promise<boolean>

validateCommandDefinitions()

validateCommandDefinitions(): void

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:795

Returns

void

Deprecated

Use testServiceSetup() instead

validateCommands()

protected validateCommands(commandDefinitions): void

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:707

Parameters

commandDefinitions

CommandDefinitionListResolved<any>

Returns

void

validateQueues()

protected validateQueues(queueDefinitions): void

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:752

Parameters

queueDefinitions

QueueDefinitionListResolved<any>

Returns

void

validateQueueWorkers()

protected validateQueueWorkers(queueWorkers, queues): void

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:763

Parameters

queueWorkers

QueueWorkerDefinitionListResolved<any>

queues

QueueDefinitionListResolved<any>

Returns

void

validateStreams()

protected validateStreams(streamDefinitions): void

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:741

Parameters

streamDefinitions

StreamDefinitionListResolved<any>

Returns

void

validateSubscriptionDefinitions()

validateSubscriptionDefinitions(): void

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:803

Returns

void

Deprecated

Use testServiceSetup() instead

validateSubscriptions()

protected validateSubscriptions(subscriptionDefinitions): void

Defined in: ServiceBuilder/ServiceBuilder.impl.ts:729

Parameters

subscriptionDefinitions

SubscriptionDefinitionListResolved<any>

Returns

void

Class: ServiceBuilder<S> ​

Type Parameters ​

S ​

Constructors ​

Constructor ​

Parameters ​

info ​

Returns ​

Properties ​

info ​

SClass ​

Methods ​

addAgentDefinition() ​

Type Parameters ​

Definition ​

Parameters ​

definitions ​

Returns ​

Example ​

addCommandDefinition() ​

Parameters ​

commands ​

Returns ​

addQueueDefinition() ​

Parameters ​

queues ​

Returns ​

addQueueWorkerDefinition() ​

Parameters ​

workers ​

Returns ​

addScheduleDefinition() ​

Parameters ​

schedules ​

Returns ​

addStreamDefinition() ​

Parameters ​

streams ​

Returns ​

addSubscriptionDefinition() ​

Parameters ​

subscription ​

Returns ​

bindEventToQueue() ​

Parameters ​

eventName ​

queueName ​

options? ​

Returns ​

Example ​

defineMetric() ​

Type Parameters ​

MetricName ​

Definition ​

Parameters ​

name ​

definition ​

Returns ​

Example ​

defineResource() ​

Type Parameters ​

ResourceName ​

ResourcesType ​

Returns ​

getAgentQueueBuilder() ​

Type Parameters ​

AgentName ​

Parameters ​

agentName ​

description ​

Returns ​

Example ​

getCommandBuilder() ​

Type Parameters ​

T ​

N ​

Parameters ​

commandName ​

description ​

eventName? ​

Class: ServiceBuilder<S>

Type Parameters

S

Constructors

Constructor

Parameters

info

Returns

Properties

info

SClass

Methods

addAgentDefinition()

Type Parameters

Definition

Parameters

definitions

Returns

Example

addCommandDefinition()

Parameters

commands

Returns

addQueueDefinition()

Parameters

queues

Returns

addQueueWorkerDefinition()

Parameters

workers

Returns

addScheduleDefinition()

Parameters

schedules

Returns

addStreamDefinition()

Parameters

streams

Returns

addSubscriptionDefinition()

Parameters

subscription

Returns

bindEventToQueue()

Parameters

eventName

queueName

options?

Returns

Example

defineMetric()

Type Parameters

MetricName

Definition

Parameters

name

definition

Returns

Example

defineResource()

Type Parameters

ResourceName

ResourcesType

Returns

getAgentQueueBuilder()

Type Parameters

AgentName

Parameters

agentName

description

Returns

Example

getCommandBuilder()

Type Parameters

T

N

Parameters

commandName

description

eventName?