Server-sent events (SSE) module for for-nest

View Source events-module/index.ts, line 2

Classes

DecafStreamModule: Creates a NestJS module that registers the EventsController (and, when subscription mode is enabled, the EventsSubscriptionController) under a given router path, together with the ObserverSubscriptionRegistry provider and the adapter flavours and options used to observe and stream events.
EventsController: Registers observers against all listening adapters and streams the events they emit back to the client over SSE. A single requester (identified by fingerprint) may hold only one SSE connection: claiming a connection when one is already active throws a ConflictError. When ObserverEventsOptions.subscriptionMode is enabled, events are filtered by the requester's topic subscriptions held in the ObserverSubscriptionRegistry.
EventsSubscriptionController: Exposes POST subscribe and POST unsubscribe endpoints that upsert or remove the requester's topic subscriptions in the ObserverSubscriptionRegistry. Both endpoints no-op with { enabled: false } when subscription mode is disabled.
ObserverSubscriptionRegistry: Tracks which requester fingerprint is subscribed to which webhook-style topics and enforces a single SSE client per fingerprint. Topics follow the webhook syntax: <model>.* (default) or the enhanced <model>.<action|*>.<item id/pk> form, matched with matchesTopic. The registry is the server-side state backing the SSE EventsController and EventsSubscriptionController.

Methods

# static eventTopicFor(model, event, idopt) → {string}

Builds the <model>.<action>.<id> topic consumed by the subscription matcher, dropping the id segment when the id is an array, null or absent.

Builds the webhook topic for an observed event

Parameters:

Name	Type	Attributes	Description
`model`	`string` \| `Constructor` \| `object` \| `undefined`		The model the event belongs to
`event`	`string`		The operation key (e.g. `create`, `update`, `delete`)
`id`	`*`	<optional>	The event id; arrays are ignored

View Source events-module/utils.ts, line 71

Returns:

The string <model>.<action> or <model>.<action>.<id> topic

Type: string

# static fingerprintLabel(fingerprint) → {string}

Truncates a fingerprint to its first eight characters so logs never leak the full identifier; returns <none> for empty input.

Stable, logged-safe prefix of a requester fingerprint

Parameters:

Name	Type	Description
`fingerprint`	`string`	The full requester fingerprint

View Source events-module/utils.ts, line 119

Returns:

The truncated label, or <none>

Type: string

# static fingerprintOfUser(identity) → {string|undefined}

Returns the identity itself when it is a non-empty string, or the value of the id/uuid/UUID/user property when the identity is an object. Returns undefined for null, numeric or unidentifiable identities.

Extracts a fingerprint from an authenticated user identity

Parameters:

Name	Type	Description
`identity`	`unknown`	The authenticated user identity

View Source events-module/utils.ts, line 94

Returns:

The user fingerprint, if resolvable

Type: string | undefined

# static nameOf(model) → {string}

Returns the model name when given a string, a class constructor (or an instance thereof) or an object carrying a name/constructor.name.

Resolves the name of a model

Parameters:

Name	Type	Description
`model`	`string` \| `Constructor` \| `object` \| `undefined`	The model to name

View Source events-module/utils.ts, line 51

Returns:

The model name, or an empty string when it cannot be resolved

Type: string

# static normalizeEventResponse(args) → {Array.<unknown>}

Maps the raw observer arguments — model reference, operation, id and payload — into a serializable tuple by resolving the model name and serializing the payload(s). Array payloads are serialized element-wise, dropping elements that cannot be serialized.

Normalizes an observer refresh payload for SSE delivery

sequenceDiagram participant Caller participant normalize as normalizeEventResponse Caller->>normalize: args [model, operation, id, payload] normalize->>normalize: resolve modelName alt payload is an array normalize->>normalize: serialize each element else payload is serializable normalize->>normalize: payload.serialize() else normalize->>normalize: JSON.stringify(payload) end normalize-->>Caller: [modelName, operation, id, serializedPayload]

Parameters:

Name	Type	Description
`args`	`Array.<any>`	The raw observer arguments `[model, operation, id, payload]`

View Source events-module/utils.ts, line 2

Returns:

The tuple [modelName, operation, id, serializedPayload]

Type: Array.<unknown>

# static resolveRequesterFingerprint(context, fallback) → {RequesterFingerprint}

Resolves the caller identity in priority order: an authenticated user, then the x-correlation-id header, and finally the supplied fallback (typically a freshly generated id) which is classified as a connection fingerprint.

Resolves the requester fingerprint for an incoming request

sequenceDiagram participant Caller participant resolve as resolveRequesterFingerprint Caller->>resolve: context, fallback alt authenticated user present resolve-->>Caller: { kind: user } else x-correlation-id header present resolve-->>Caller: { kind: correlationId } else resolve-->>Caller: { kind: connection, value: fallback } end

Parameters:

Name	Type	Attributes	Description
`context`	`Object`		The request context used for resolution
`getOrUndefined`	`function`	<optional>	Context lookup keyed by name (e.g. `user`)
`headers`	`Object`	<optional>	Raw request headers
`fallback`	`string`		Fallback value when no identity nor correlation header exists

View Source events-module/utils.ts, line 160

Returns:

The resolved fingerprint, with its resolution kind

Type: RequesterFingerprint

# static sanitizeTopics(topics) → {Array.<string>}

Trims each topic, drops empty topics, topics longer than 512 characters, topics with more than 8 dot-separated segments and duplicate entries.

Sanitizes a set of requested webhook topics

Parameters:

Name	Type	Description
`topics`	`Iterable.<string>`	The raw requested topics

View Source events-module/utils.ts, line 135

Returns:

The deduplicated, validated topics

Type: Array.<string>

Type Definitions

Type: Object

# ObserverSubscriptionRecord

Captures the webhook-style topics a requester is subscribed to and the last time that subscription was (re)registered. Topics follow the webhook syntax: <model>.* (default) or the enhanced <model>.<action|*>.<item id/pk> form, where * matches anything.

A subscription record for a single requester fingerprint

Properties:

Name	Type	Description
`fingerprint`	`string`	The requester fingerprint this subscription belongs to
`topics`	`Array.<string>`	The webhook topics the requester is subscribed to
`updatedAt`	`Date`	Timestamp of the last upsert for this subscription
`fingerprint`	`string`
`topics`	`Array`
`updatedAt`	`Date`

View Source events-module/ObserverSubscriptionRegistry.ts, line 127

Type: Object

# RequesterFingerprint

Carries the value that identifies a requester, together with how that value was resolved: an authenticated user, the x-correlation-id header, or a fallback connection id.

Identity resolved for a requester for topic-scoped SSE

Properties:

Name	Type	Description
`value`	`string`	The resolved fingerprint value
`kind`	`'user'` \| `'correlationId'` \| `'connection'`	How the fingerprint was resolved
`value`	`string`
`kind`	`"user"` \| `"correlationId"` \| `"connection"`

View Source events-module/utils.ts, line 249

Type: Object

# SubscriptionPayload

The request body accepted by the subscribe endpoint: an optional list of webhook-style topic patterns.

REST payload for subscribing an SSE client to topics

Properties:

Name	Type	Attributes	Description
`topics`	`Array.<string>`	<optional>	The topics to subscribe the requester to
`topics`	`Array`	<optional>

View Source events-module/EventsSubscriptionController.ts, line 123

ts-template

events

for-nest.events

Classes

Methods

# static eventTopicFor(model, event, idopt) → {string}

Parameters:

# static fingerprintLabel(fingerprint) → {string}

Parameters:

# static fingerprintOfUser(identity) → {string|undefined}

Parameters:

# static nameOf(model) → {string}

Parameters:

# static normalizeEventResponse(args) → {Array.<unknown>}

Parameters:

# static resolveRequesterFingerprint(context, fallback) → {RequesterFingerprint}

Parameters:

# static sanitizeTopics(topics) → {Array.<string>}

Parameters:

Type Definitions

# ObserverSubscriptionRecord

Properties:

# RequesterFingerprint

Properties:

# SubscriptionPayload

Properties: