API reference

realtime(options) creates a Layeron module for rooms, channels, presence, history, snapshots, authorization, and CRDT rooms.

Import

import { realtime } from "@layeron/modules"

realtime

Create a Layeron realtime module.

realtime(options: RealtimeModuleOptions): RealtimeModule

RealtimeModuleOptions

Options accepted by realtime(options).

Field	Type	Description
name	string	Stable Realtime instance name inside the Layeron app.
namespace	string | undefined	Platform namespace for the instance. Defaults to default.
databaseName	string | undefined	Database product name used for Realtime state. Omit this unless you need a custom internal state store name.
binding	string | undefined	Custom binding name for advanced runtime access.
historyLimit	int32 | undefined	Default page size for room history and CRDT document updates. Defaults to 100.
presenceTtlSeconds	int32 | undefined	Presence freshness window in seconds. Defaults to 60.
lifecycle	RealtimeLifecycleOptions | undefined	Room lifecycle behavior for idle cleanup and destroyed room handling.
autoResolveUser	boolean | undefined	Whether Realtime should resolve the actor from request context headers. Defaults to true.
allowAnonymous	boolean | undefined	Whether anonymous actors are allowed when no user or explicit actor is available. Defaults to false.
observability	Layeron.Observability.ObservabilityConfig | undefined	Observability settings for the Realtime module.
placement	Layeron.Common.Placement.LayeronPlacement | undefined	Placement overrides for this Realtime product instance.

RealtimeLifecycleOptions

Lifecycle options accepted by realtime({ lifecycle }).

Field	Type	Description
idleTtlSeconds	int32 | undefined	Seconds after the last activity before the Durable Object can mark the room idle. Defaults to 300.
destroyTtlSeconds	int32 | undefined	Seconds after destroy before hot Durable Object state can be fully cleared. Defaults to 86400.
allowRecreate	boolean | undefined	Whether writes can recreate a destroyed room. Defaults to false.

RealtimeModule

Layeron Realtime module returned by realtime(options).

Field	Type	Description
name	”realtime”	Module name.
config	RealtimeModuleOptions	Normalized module configuration.
observability	Layeron.Observability.ObservabilityConfig | undefined	Effective observability policy recorded on the module declaration.

RealtimePrincipal

Actor attached to a Realtime write.

Field	Type	Description
kind	”anonymous” | “user”	Actor kind.
id	string | undefined	Stable actor id when available.
userId	string | undefined	Authenticated user id when the actor is a user.
sessionId	string | undefined	Session id associated with the write.
tenantId	string | undefined	Tenant id associated with the write.
email	string | undefined	User email when available.
displayName	string | undefined	Display name when available.

RealtimeRoomIdentity

Room or channel identity.

Field	Type	Description
kind	”room” | “channel”	Realtime target kind.
name	string	Room or channel name.

RealtimeMessageInput

Message input accepted by room.publish(), room.broadcast(), channel.publish(), and channel.broadcast().

Field	Type	Description
type	string	Client-visible event type.
data	unknown | undefined	JSON event payload.
metadata	Record<unknown> | undefined	JSON metadata associated with the event.
idempotencyKey	string | undefined	Retry-safe idempotency key for duplicate publish protection.
actor	RealtimePrincipal | undefined	Explicit actor for this write. Omit to use automatic identity resolution.

RealtimePublishInput

Internal publish payload with room identity.

Field	Type	Description
type	string	Client-visible event type.
data	unknown | undefined	JSON event payload.
metadata	Record<unknown> | undefined	JSON metadata associated with the event.
idempotencyKey	string | undefined	Retry-safe idempotency key for duplicate publish protection.
actor	RealtimePrincipal | undefined	Explicit actor for this write. Omit to use automatic identity resolution.

RealtimePublishResult

Result returned by publish and broadcast.

Field	Type	Description
room	string	Room or channel name.
kind	”room” | “channel”	Realtime target kind.
messageId	string	Generated message id.
publishedAt	string	Publish timestamp.
actor	RealtimePrincipal | undefined	Actor attached to the message.

RealtimeJoinOptions

Input accepted by room.join().

Field	Type	Description
memberId	string | undefined	Stable member id. Omit to derive from the actor.
actor	RealtimePrincipal | undefined	Explicit actor for this join.
metadata	Record<unknown> | undefined	Member metadata such as role or client information.
presence	Record<unknown> | undefined	Initial live presence state.

RealtimeJoinInput

Internal join payload with room identity.

Field	Type	Description
memberId	string | undefined	Stable member id. Omit to derive from the actor.
actor	RealtimePrincipal | undefined	Explicit actor for this join.
metadata	Record<unknown> | undefined	Member metadata such as role or client information.
presence	Record<unknown> | undefined	Initial live presence state.

RealtimeLeaveOptions

Input accepted by room.leave().

Field	Type	Description
memberId	string | undefined	Member id to mark as left. Omit to derive from the actor.

RealtimeLeaveResult

Result returned by room.leave().

Field	Type	Description
room	string	Room or channel name.
kind	”room” | “channel”	Realtime target kind.
memberId	string	Member id that left.
leftAt	string	Leave timestamp.

RealtimeMember

Room member record returned by join() and members().

Field	Type	Description
memberId	string	Stable member id inside the room.
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
joinedAt	string	Join timestamp.
lastSeenAt	string	Last seen timestamp.
leftAt	string | undefined	Leave timestamp when the member has left.
actor	RealtimePrincipal | undefined	Actor associated with the member.
metadata	Record<unknown>	Member metadata such as role or client information.
presence	Record<unknown>	Latest live presence state.

RealtimeMembersOptions

Options accepted by room.members().

Field	Type	Description
limit	int32 | undefined	Maximum members to return.

RealtimePresenceOptions

Input accepted by room.presence().

Field	Type	Description
memberId	string | undefined	Member id to update. Omit to derive from the actor.
presence	Record<unknown> | undefined	Live presence state.

RealtimePresenceInput

Internal presence payload with room identity.

Field	Type	Description
memberId	string | undefined	Member id to update. Omit to derive from the actor.
presence	Record<unknown> | undefined	Live presence state.

RealtimePresenceResult

Result returned by room.presence().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
memberId	string	Member id that was updated.
updatedAt	string	Presence update timestamp.
presence	Record<unknown>	Latest live presence state.

RealtimeMetadataOptions

Input accepted by room.metadata().

Field	Type	Description
metadata	Record<unknown> | undefined	Shared room metadata.

RealtimeMetadataResult

Result returned by room.metadata().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
metadata	Record<unknown>	Latest shared room metadata.
updatedAt	string	Metadata update timestamp.

RealtimeHistoryOptions

Options accepted by room.history() and channel.history().

Field	Type	Description
limit	int32 | undefined	Maximum messages to return.
cursor	string | undefined	Cursor returned by a previous history call.

RealtimeHistoryMessage

History message record.

Field	Type	Description
messageId	string	Generated message id.
room	string	Room or channel name.
kind	”room” | “channel”	Realtime target kind.
type	string	Client-visible event type.
data	unknown | undefined	JSON event payload.
metadata	Record<unknown>	JSON metadata associated with the event.
actor	RealtimePrincipal | undefined	Actor attached to the message.
publishedAt	string	Publish timestamp.

RealtimeHistoryResult

Result returned by history().

Field	Type	Description
room	string	Room or channel name.
kind	”room” | “channel”	Realtime target kind.
items	RealtimeHistoryMessage[]	History messages in result order.
cursor	string | undefined	Cursor for fetching older messages.

RealtimeSnapshotResult

Result returned by snapshot().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
snapshotId	string	Generated snapshot id.
createdAt	string	Snapshot creation timestamp.
state	Record<unknown>	Snapshot state payload.

RealtimeRestoreResult

Result returned by restore().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
snapshotId	string	Snapshot id that was restored.
restoredAt	string	Restore timestamp.

RealtimeAuthorizeOptions

Input accepted by room.authorize().

Field	Type	Description
memberId	string | undefined	Member id attached to the websocket connection.
clientId	string | undefined	Client or device id attached to the websocket connection.
presence	Record<unknown> | undefined	Initial presence state attached to the websocket connection.
actor	RealtimePrincipal | undefined	Explicit actor for the token. Omit to use automatic identity resolution.
ttlSeconds	int32 | undefined	Token lifetime in seconds.

RealtimeAuthorizeResult

Result returned by room.authorize().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
token	string	Short-lived authorization token.
expiresAt	string	Token expiration timestamp.
url	string	WebSocket URL used by browser clients.
protocols	string[]	WebSocket protocols used by browser clients.
actor	RealtimePrincipal | undefined	Actor associated with the token.
memberId	string | undefined	Member id attached to the websocket connection.
clientId	string | undefined	Client or device id attached to the websocket connection.
presence	Record<unknown> | undefined	Initial presence state attached to the websocket connection.

RealtimeStats

Realtime instance stats.

Field	Type	Description
rooms	int32	Number of rooms tracked by the Realtime instance.
members	int32	Number of active members tracked by the Realtime instance.
messages	int32	Number of messages tracked by the Realtime instance.

RealtimeLifecycleResult

Current lifecycle state for a room or CRDT room.

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
status	”active” | “idle” | “destroyed”	Lifecycle status.
activeConnections	int32	Current live WebSocket connections held by the room Durable Object.
lastActivityAt	string | undefined	Last activity timestamp when known.
idleSince	string | undefined	Timestamp when the room became idle.
destroyedAt	string | undefined	Timestamp when the room was destroyed.

RealtimeDestroyOptions

Options accepted by room.destroy() and crdtRoom.destroy().

Field	Type	Description
deleteHistory	boolean | undefined	Delete message history for this room.
deleteSnapshots	boolean | undefined	Delete snapshots for this room.
deleteCrdtUpdates	boolean | undefined	Delete CRDT updates and awareness records for this room.

RealtimeDestroyResult

Result returned by room.destroy() and crdtRoom.destroy().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
destroyedAt	string	Destroy timestamp.
deletedHistory	boolean	Whether message history was deleted.
deletedSnapshots	boolean	Whether snapshots were deleted.
deletedCrdtUpdates	boolean	Whether CRDT updates and awareness records were deleted.

RealtimeCrdtUpdateOptions

Input accepted by crdtRoom.applyUpdate().

Field	Type	Description
update	unknown	JSON update payload produced by the client.
clientId	string | undefined	Client or device id that produced the update.
clock	int32 | undefined	Optional client clock used for ordered reads.
actor	RealtimePrincipal | undefined	Explicit actor for this update.

RealtimeCrdtUpdateInput

Internal CRDT update payload with room identity.

Field	Type	Description
update	unknown	CRDT update payload.
clientId	string | undefined	Client id that produced the update.
clock	int32 | undefined	Optional client clock used for ordered reads.
actor	RealtimePrincipal | undefined	Explicit actor for this update.

RealtimeCrdtUpdateResult

Result returned by crdtRoom.applyUpdate().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
updateId	string	Generated update id.
appliedAt	string	Update application timestamp.
actor	RealtimePrincipal | undefined	Actor attached to the update.

RealtimeCrdtAwarenessOptions

Input accepted by crdtRoom.awareness().

Field	Type	Description
clientId	string | undefined	Client or device id whose awareness is being updated.
state	Record<unknown> | undefined	JSON awareness state such as cursor, selection, tool, or display details.
actor	RealtimePrincipal | undefined	Explicit actor for this awareness update.

RealtimeCrdtAwarenessResult

Result returned by crdtRoom.awareness().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
clientId	string	Client or device id whose awareness was updated.
updatedAt	string	Awareness update timestamp.
state	Record<unknown>	Latest awareness state.
actor	RealtimePrincipal | undefined	Actor attached to the awareness update.

RealtimeCrdtDocumentOptions

Options accepted by crdtRoom.document().

Field	Type	Description
sinceClock	int32 | undefined	Return updates after this client clock.
limit	int32 | undefined	Maximum updates to return.

RealtimeCrdtDocumentUpdate

CRDT update record returned by crdtRoom.document().

Field	Type	Description
updateId	string	Generated update id.
update	unknown	JSON update payload.
clientId	string | undefined	Client or device id that produced the update.
clock	int32 | undefined	Client clock used for ordered reads.
actor	RealtimePrincipal | undefined	Actor attached to the update.
appliedAt	string	Update application timestamp.

RealtimeCrdtDocumentResult

Result returned by crdtRoom.document().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
updates	RealtimeCrdtDocumentUpdate[]	Ordered document updates.
awareness	RealtimeCrdtAwarenessResult[]	Current awareness records.
cursor	string | undefined	Cursor for reading additional updates.

RealtimeYjsUpdateOptions

Input accepted by crdtRoom.applyYjsUpdate().

Field	Type	Description
updateBase64	string	Yjs update encoded as base64.
clientId	string | undefined	Client or device id that produced the update.
clock	int32 | undefined	Optional client clock used for ordered reads.
actor	RealtimePrincipal | undefined	Explicit actor for this update.

RealtimeYjsUpdateResult

Result returned by crdtRoom.applyYjsUpdate().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
updateId	string	Generated update id.
appliedAt	string	Update application timestamp.
updateBase64	string	Yjs update encoded as base64.
stateVectorBase64	string | undefined	Current Yjs state vector encoded as base64 when available.
actor	RealtimePrincipal | undefined	Actor attached to the update.

RealtimeYjsSyncOptions

Options accepted by crdtRoom.syncYjs().

Field	Type	Description
stateVectorBase64	string | undefined	Client state vector encoded as base64. Omit to receive the current merged update.
limit	int32 | undefined	Maximum historical update records included beside the merged update.

RealtimeYjsUpdateRecord

Yjs update record returned by crdtRoom.syncYjs().

Field	Type	Description
updateId	string	Generated update id.
updateBase64	string	Yjs update encoded as base64.
clientId	string | undefined	Client or device id that produced the update.
clock	int32 | undefined	Client clock used for ordered reads.
actor	RealtimePrincipal | undefined	Actor attached to the update.
appliedAt	string	Update application timestamp.

RealtimeYjsSyncResult

Result returned by crdtRoom.syncYjs().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
updateBase64	string | undefined	Merged Yjs update encoded as base64.
stateVectorBase64	string | undefined	Current Yjs state vector encoded as base64.
updates	RealtimeYjsUpdateRecord[]	Historical Yjs update records included for inspection or replay.
awareness	RealtimeCrdtAwarenessResult[]	Current awareness records.

RealtimeCrdtCompactResult

Result returned by crdtRoom.compact().

Field	Type	Description
room	string	Room name.
kind	”room” | “channel”	Realtime target kind.
compactedAt	string	Compaction timestamp.
updatesCompacted	int32	Number of Yjs updates represented by the checkpoint.
checkpointUpdateBase64	string | undefined	Merged checkpoint update encoded as base64.
stateVectorBase64	string | undefined	Yjs state vector encoded as base64.

Operations

realtimeRoom

Create a room handle.

realtimeRoom(name: string): RealtimeRoomIdentity

realtimeChannel

Create a channel handle.

realtimeChannel(name: string): RealtimeRoomIdentity

realtimeCrdtRoom

Create a CRDT room handle.

realtimeCrdtRoom(name: string): RealtimeRoomIdentity

realtimePublish

Publish and record a room or channel message.

realtimePublish(input: RealtimeMessageInput): RealtimePublishResult

realtimeBroadcast

Broadcast and record a room or channel message.

realtimeBroadcast(input: RealtimeMessageInput): RealtimePublishResult

realtimeJoin

Join or refresh membership in a room.

realtimeJoin(input?: RealtimeJoinOptions): RealtimeMember

realtimeLeave

Mark a member as left.

realtimeLeave(input?: RealtimeLeaveOptions): RealtimeLeaveResult

realtimeMembers

List active room members.

realtimeMembers(options?: RealtimeMembersOptions): RealtimeMember[]

realtimePresence

Update live presence state.

realtimePresence(input?: RealtimePresenceOptions): RealtimePresenceResult

realtimeMetadata

Update shared room metadata.

realtimeMetadata(input?: RealtimeMetadataOptions): RealtimeMetadataResult

realtimeHistory

Read room or channel history.

realtimeHistory(options?: RealtimeHistoryOptions): RealtimeHistoryResult

realtimeSnapshot

Create a room snapshot.

realtimeSnapshot(): RealtimeSnapshotResult

realtimeRestore

Restore a room snapshot.

realtimeRestore(snapshotId: string): RealtimeRestoreResult

realtimeAuthorize

Create a short-lived room authorization token.

realtimeAuthorize(input?: RealtimeAuthorizeOptions): RealtimeAuthorizeResult

realtimeLifecycle

Read the lifecycle state for a room.

realtimeLifecycle(): RealtimeLifecycleResult

realtimeDestroy

Destroy a room and optionally delete stored history, snapshots, and CRDT updates.

realtimeDestroy(input?: RealtimeDestroyOptions): RealtimeDestroyResult

realtimeCrdtApplyUpdate

Record a collaborative document update.

realtimeCrdtApplyUpdate(input: RealtimeCrdtUpdateOptions): RealtimeCrdtUpdateResult

realtimeCrdtAwareness

Update collaborative document awareness state.

realtimeCrdtAwareness(input?: RealtimeCrdtAwarenessOptions): RealtimeCrdtAwarenessResult

realtimeCrdtDocument

Read ordered document updates and current awareness state.

realtimeCrdtDocument(options?: RealtimeCrdtDocumentOptions): RealtimeCrdtDocumentResult

realtimeYjsApplyUpdate

Apply a binary Yjs update encoded as base64.

realtimeYjsApplyUpdate(input: RealtimeYjsUpdateOptions): RealtimeYjsUpdateResult

realtimeYjsSync

Synchronize a Yjs document using a base64 state vector.

realtimeYjsSync(options?: RealtimeYjsSyncOptions): RealtimeYjsSyncResult

realtimeCrdtCompact

Compact Yjs updates into a Durable Object checkpoint.

realtimeCrdtCompact(): RealtimeCrdtCompactResult

realtimeStats

Read Realtime instance stats.

realtimeStats(): RealtimeStats