Skip to main content

JetstreamRecordBuilder<TData>

@horizon-republic/nestjs-jetstream

@horizon-republic/nestjs-jetstream / JetstreamRecordBuilder

JetstreamRecordBuilder<TData>

Defined in: src/client/jetstream.record.ts:60

Fluent builder for constructing JetstreamRecord instances.

Protected headers (correlation-id, reply-to, error) cannot be set by the user; attempting to do so throws an error at build time.

Type Parameters​

TData​

TData = unknown

Constructors​

Constructor​

new JetstreamRecordBuilder<TData>(data?): JetstreamRecordBuilder<TData>

Defined in: src/client/jetstream.record.ts:68

Parameters​

data?​

TData

Returns​

JetstreamRecordBuilder<TData>

Methods​

build()​

build(): JetstreamRecord<TData>

Defined in: src/client/jetstream.record.ts:206

Build the immutable JetstreamRecord.

Returns​

JetstreamRecord<TData>

A frozen record ready to pass to client.send() or client.emit().

scheduleAt()​

scheduleAt(date): this

Defined in: src/client/jetstream.record.ts:155

Schedule one-shot delayed delivery.

The message is held by NATS and delivered to the event consumer at the specified time. Requires NATS >= 2.12 and allow_msg_schedules: true on the event stream (via events: { stream: { allow_msg_schedules: true } }).

Applies to events (client.emit()) only. If used with RPC (client.send()), a warning is logged and the schedule is ignored.

Parameters​

date​

Date

Delivery time. Must be in the future.

Returns​

this

Throws​

Error if the date is not in the future.

setData()​

setData(data): this

Defined in: src/client/jetstream.record.ts:77

Set the message payload.

Parameters​

data​

TData

Payload to serialize via the configured Codec.

Returns​

this

setHeader()​

setHeader(key, value): this

Defined in: src/client/jetstream.record.ts:89

Set a single custom header.

Parameters​

key​

string

Header name (e.g. 'x-tenant').

value​

string

Header value.

Returns​

this

Throws​

Error if the header name is reserved by the transport.

setHeaders()​

setHeaders(headers): this

Defined in: src/client/jetstream.record.ts:101

Set multiple custom headers at once.

Parameters​

headers​

Record<string, string>

Key-value pairs to set as headers.

Returns​

this

Throws​

Error if any header name is reserved by the transport.

setMessageId()​

setMessageId(id): this

Defined in: src/client/jetstream.record.ts:127

Set a custom message ID for JetStream deduplication.

NATS JetStream uses this ID to detect duplicate publishes within the stream's duplicate_window. If two messages with the same ID arrive within the window, the second is silently dropped.

When not set, a random UUID is generated automatically.

Parameters​

id​

string

Unique message identifier (e.g. order ID, idempotency key).

Returns​

this

Example​

new JetstreamRecordBuilder(data)
  .setMessageId(`order-${order.id}`)
  .build();

setTimeout()​

setTimeout(ms): this

Defined in: src/client/jetstream.record.ts:137

Set per-request RPC timeout.

Parameters​

ms​

number

Timeout in milliseconds. Overrides the global RPC timeout for this request only.

Returns​

this

ttl()​

ttl(nanos): this

Defined in: src/client/jetstream.record.ts:191

Set per-message TTL (time-to-live).

The message expires individually after the specified duration, independent of the stream's max_age. Requires NATS >= 2.11 and allow_msg_ttl: true on the stream.

Applies to events (client.emit()) only. If used with RPC (client.send()), a warning is logged and the TTL is ignored.

Parameters​

nanos​

number

TTL in nanoseconds. Use toNanos for human-readable values.

Returns​

this

Example​

import { toNanos } from '@horizon-republic/nestjs-jetstream';

new JetstreamRecordBuilder(payload).ttl(toNanos(30, 'minutes')).build();
new JetstreamRecordBuilder(payload).ttl(toNanos(24, 'hours')).build();