Class SubscriptionBuilder<TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing>

Immutable, fluent builder for WebSocket subscription endpoint definitions.

All methods return a new builder instance — the original is never mutated. Use endpoint.subscription() to obtain the first builder in the chain.

Example

const ChatRoom = endpoint
    .subscription('/ws/chat')
    .incoming(object({ text: string() }))
    .outgoing(object({ user: string(), text: string(), timestamp: number() }))
    .authorize(PrincipalSchema)
    .summary('Real-time chat room');

Type Parameters

TParams = {}
TQuery = {}
THeaders = {}
TServices = {}
TPrincipal = undefined
TRoles extends string = string
TIncoming = undefined
TOutgoing = undefined

Index

Constructors

constructor

Methods

authorize deprecated description externalDocs headers incoming inject introspect operationId outgoing query summary tags

Constructors

constructor

new SubscriptionBuilder<
    TParams = {},
    TQuery = {},
    THeaders = {},
    TServices = {},
    TPrincipal = undefined,
    TRoles extends string = string,
    TIncoming = undefined,
    TOutgoing = undefined,
>(
    basePath: string,
    pathTemplate?: RoutePath,
    incomingSchema?: SchemaBuilder<any, any, any, any, any> | null,
    outgoingSchema?: SchemaBuilder<any, any, any, any, any> | null,
    querySchema?: ObjectSchemaBuilder<any, any, any, any, any, any, any> | null,
    headerSchema?:
        | ObjectSchemaBuilder<any, any, any, any, any, any, any>
        | null,
    serviceSchemas?:
        | Record<string, SchemaBuilder<any, any, any, any, any>>
        | null,
    authRoles?: readonly string[] | null,
    summary?: string | null,
    description?: string | null,
    tags?: readonly string[],
    operationId?: string | null,
    deprecated?: boolean,
    externalDocs?: { description?: string; url: string } | null,
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
Type Parameters
- TParams = {}
- TQuery = {}
- THeaders = {}
- TServices = {}
- TPrincipal = undefined
- TRoles extends string = string
- TIncoming = undefined
- TOutgoing = undefined
Parameters
- basePath: string
- pathTemplate: RoutePath = '/'
- incomingSchema: SchemaBuilder<any, any, any, any, any> | null = null
- outgoingSchema: SchemaBuilder<any, any, any, any, any> | null = null
- querySchema: ObjectSchemaBuilder<any, any, any, any, any, any, any> | null = null
- headerSchema: ObjectSchemaBuilder<any, any, any, any, any, any, any> | null = null
- serviceSchemas: Record<string, SchemaBuilder<any, any, any, any, any>> | null = null
- authRoles: readonly string[] | null = null
- summary: string | null = null
- description: string | null = null
- tags: readonly string[] = []
- operationId: string | null = null
- deprecated: boolean = false
- externalDocs: { description?: string; url: string } | null = null
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:322

Methods

authorize

authorize<TSchema extends SchemaBuilder<any, any, any, any, any>>(
    principalSchema: TSchema,
    ...roles: TRoles[],
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    InferType<TSchema>,
    TRoles,
    TIncoming,
    TOutgoing,
>
Mark this subscription as requiring authorization.

Overloads:
- authorize(principalSchema, ...roles) — typed principal, optional role requirements
- authorize(...roles) — untyped principal (unknown), optional role requirements
Type Parameters
- TSchema extends SchemaBuilder<any, any, any, any, any>
Parameters
- principalSchema: TSchema
- ...roles: TRoles[]
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    InferType<TSchema>,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:547
authorize(
    ...roles: TRoles[],
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    unknown,
    TRoles,
    TIncoming,
    TOutgoing,
>
Mark this subscription as requiring authorization.

Overloads:
- authorize(principalSchema, ...roles) — typed principal, optional role requirements
- authorize(...roles) — untyped principal (unknown), optional role requirements
Parameters
- ...roles: TRoles[]
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    unknown,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:560

deprecated

deprecated(): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
Mark this subscription as deprecated in documentation.

Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:664

description

description(
    text: string,
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
Longer description for documentation. Supports Markdown.
Parameters
- text: string
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:616

externalDocs

externalDocs(
    url: string,
    description?: string,
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
Link external documentation.
Parameters
- url: string
- Optionaldescription: string
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:678

headers

headers<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(
    schema: TSchema,
): SubscriptionBuilder<
    TParams,
    TQuery,
    InferType<TSchema>,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
Define expected headers on the WebSocket upgrade request.
Type Parameters
- TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>
Parameters
- schema: TSchema
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    InferType<TSchema>,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:505

incoming

incoming<TSchema extends SchemaBuilder<any, any, any, any, any>>(
    schema: TSchema,
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TSchema,
    TOutgoing,
>
Define the schema for client→server messages. Messages that do not match this schema are rejected with an error frame.
Type Parameters
- TSchema extends SchemaBuilder<any, any, any, any, any>
Parameters
- schema: TSchema
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TSchema,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:452

inject

inject<TSchemas extends Record<string, SchemaBuilder<any, any, any, any, any>>>(
    schemas: TSchemas,
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TSchemas,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
Declare DI services to be resolved per-connection and passed as the second handler argument.
Type Parameters
- TSchemas extends Record<string, SchemaBuilder<any, any, any, any, any>>
Parameters
- schemas: TSchemas
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TSchemas,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:523

introspect

introspect(): SubscriptionMetadata
Return an immutable snapshot of this builder's configuration as SubscriptionMetadata.

Returns SubscriptionMetadata
- Defined in libs/server/src/Subscription.ts:695

operationId

operationId(
    id: string,
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
A unique, stable identifier for documentation.
Parameters
- id: string
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:648

outgoing

outgoing<TSchema extends SchemaBuilder<any, any, any, any, any>>(
    schema: TSchema,
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TSchema,
>
Define the schema for server→client events. All yielded values are validated against this schema before sending.
Type Parameters
- TSchema extends SchemaBuilder<any, any, any, any, any>
Parameters
- schema: TSchema
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TSchema,
>
- Defined in libs/server/src/Subscription.ts:471

query

query<TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>>(
    schema: TSchema,
): SubscriptionBuilder<
    TParams,
    InferType<TSchema>,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
Define the query string schema for the WebSocket upgrade URL.
Type Parameters
- TSchema extends ObjectSchemaBuilder<any, any, any, any, any, any, any>
Parameters
- schema: TSchema
Returns SubscriptionBuilder<
    TParams,
    InferType<TSchema>,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:487

summary

summary(
    text: string,
): SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
Short, human-readable summary for documentation.
Parameters
- text: string
Returns SubscriptionBuilder<
    TParams,
    TQuery,
    THeaders,
    TServices,
    TPrincipal,
    TRoles,
    TIncoming,
    TOutgoing,
>
- Defined in libs/server/src/Subscription.ts:600

Class SubscriptionBuilder<TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing>

Example

Type Parameters

Index

Constructors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

Methods

authorize

Type Parameters

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, InferType<TSchema>, TRoles, TIncoming, TOutgoing,>

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, unknown, TRoles, TIncoming, TOutgoing,>

deprecated

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

description

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

externalDocs

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

headers

Type Parameters

Parameters

Returns SubscriptionBuilder< TParams, TQuery, InferType<TSchema>, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

incoming

Type Parameters

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TSchema, TOutgoing,>

inject

Type Parameters

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TSchemas, TPrincipal, TRoles, TIncoming, TOutgoing,>

introspect

Returns SubscriptionMetadata

operationId

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

outgoing

Type Parameters

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TSchema,>

query

Type Parameters

Parameters

Returns SubscriptionBuilder< TParams, InferType<TSchema>, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

summary

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

tags

Parameters

Returns SubscriptionBuilder< TParams, TQuery, THeaders, TServices, TPrincipal, TRoles, TIncoming, TOutgoing,>

Settings

On This Page

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
InferType<TSchema>,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
unknown,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
InferType<TSchema>,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TSchema,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TSchemas,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TSchema,
>

Returns SubscriptionBuilder<
TParams,
InferType<TSchema>,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>

Returns SubscriptionBuilder<
TParams,
TQuery,
THeaders,
TServices,
TPrincipal,
TRoles,
TIncoming,
TOutgoing,
>