Skip to Content
Reference@streamsy/core

Stream records

Reference for the stream record types in @streamsy/core. A storage adapter stores and returns these records.

import {
  ChangeSnapshot,
  MessageWindow,
  ProducerState,
  RecordPatch,
  StoredMessage,
  StreamConfig,
  StreamLifecycle,
  StreamRecord,
  type Offset,
  type StreamId,
} from "@streamsy/core";

These types are the values that the storage contract reads and writes. An application does not use them. Each name exports an interface and an Effect Schema with the same name, and an adapter decodes stored values with the schema. StreamId and Offset are on the Ids and offsets page.

Records

StreamRecord

interface StreamRecord {
  readonly id: StreamId;
  readonly config: StreamConfig;
  readonly lifecycle: StreamLifecycle;
  readonly currentOffset: Offset;
}

StreamRecord is the stored state of a stream, without its messages. currentOffset is the tail of the stream. StorageShape.record returns it, and a Create operation stores it.

StreamConfig

interface StreamConfig {
  readonly contentType: string;
  readonly ttlSeconds?: number;
  readonly expiresAt?: string;
  readonly createdAt: number;
}

StreamConfig holds the configuration that create set.

FieldMeaning
contentTypeThe content type of the stream
ttlSecondsThe ttlSeconds option of create, when it was set
expiresAtThe expiresAt option of create, when it was set
createdAtThe time of the create, in milliseconds since the Unix epoch

StreamLifecycle

interface StreamLifecycle {
  readonly lastSeq?: string;
  readonly closed: boolean;
  readonly closedAt?: number;
  readonly forkedFrom?: StreamId;
  readonly forkOffset?: Offset;
  readonly forkSubOffset?: number;
  readonly softDeleted: boolean;
  readonly expiresAtMs?: number;
}

StreamLifecycle holds the state of a stream that its writes change.

FieldMeaning
lastSeqThe last Stream-Seq that an append sent. The next Stream-Seq must sort after it
closedtrue when the stream is closed and takes no more appends
closedAtThe time of the close, in milliseconds since the Unix epoch
forkedFromThe id of the source stream of a fork
forkOffsetThe offset in the source at which the fork starts
forkSubOffsetThe forkSubOffset option of the fork, when it was set
softDeletedtrue when the stream was deleted and the store keeps it for its forks
expiresAtMsThe expiry deadline, in milliseconds since the Unix epoch. An indexed adapter answers nextExpiry from it

StoredMessage

interface StoredMessage {
  readonly offset: Offset;
  readonly timestamp: number;
  readonly data: Uint8Array;
}

StoredMessage is a stored message. offset is its position in the stream, timestamp is the time of its append in milliseconds since the Unix epoch, and data holds its bytes.

ProducerState

interface ProducerState {
  readonly epoch: number;
  readonly lastSeq: number;
}

ProducerState is the last producer position that a stream accepted for a producerId. epoch is the producer epoch, and lastSeq is the last producerSeq in that epoch. See Producer.Position.

Reads and changes

MessageWindow

interface MessageWindow {
  readonly after?: Offset;
  readonly until?: Offset;
  readonly limit?: number;
}

MessageWindow selects the messages that StorageShape.messages returns. messages returns the messages after after, up to and including until, in offset order, and at most limit of them. A field that you leave out sets no bound.

ChangeSnapshot

interface ChangeSnapshot {
  readonly present: boolean;
  readonly currentOffset: Offset;
  readonly closed: boolean;
  readonly softDeleted: boolean;
}

ChangeSnapshot is the state of a stream that StorageShape.changes emits. present is false when no record has the id. currentOffset, closed, and softDeleted copy the fields of the record. A reader compares a snapshot with the state it saw before, because a snapshot with no change is valid.

Writes

RecordPatch

interface RecordPatch {
  readonly currentOffset?: Offset;
  readonly config?: { readonly ttlSeconds?: number; readonly expiresAt?: string };
  readonly lifecycle?: {
    readonly lastSeq?: string;
    readonly closed?: boolean;
    readonly closedAt?: number;
    readonly forkedFrom?: StreamId;
    readonly forkOffset?: Offset;
    readonly forkSubOffset?: number;
    readonly softDeleted?: boolean;
    readonly expiresAtMs?: number;
  };
  readonly clear?: ReadonlyArray<"ttlSeconds" | "expiresAt" | "expiresAtMs" | "lastSeq">;
}

RecordPatch is the change that an Append operation makes to the record of its stream. Each field that the patch sets replaces the field of the record, and each field that it leaves out keeps its value. clear removes each optional field that it names. Without currentOffset, the tail does not move.

On this page