Skip to Content
Reference@streamsy/core

Ids and offsets

Reference for the id and offset exports in @streamsy/core. A stream id names a stream, and an offset is a position in it.

import { Offset, ProducerId, StreamId, ZERO_OFFSET, compare } from "@streamsy/core";
import type { Brand } from "effect";

A stream id names a stream, and an offset is a position in a stream. StreamId, Offset, and ProducerId each export a type and a value with the same name. The type is a branded string. The value is an Effect Schema that checks a string and brands it. See Offsets.

ZERO_OFFSET

declare const ZERO_OFFSET: Offset;

ZERO_OFFSET is the position before the first message, 0000000000000000_0000000000000000. A new stream has this offset as its tail. When you pass it as expectedOffset, the append succeeds only on an empty stream. See Conditional writes.

compare

declare function compare(a: string, b: string): number;

compare returns -1 when a is before b, 0 when they are equal, and 1 when a is after b. It compares the two strings by UTF-16 code unit. All offsets of one stream have the same width, so this order is the order of the messages in the stream. Offsets of two different streams have no defined order, so compare only offsets of the same stream.

StreamId

type StreamId = string & Brand.Brand<"StreamId">;

StreamId is the id of a stream, such as drafts/main. Results and errors carry it, for example StreamNotFound.id. A stream class makes ids for you with at(params). To brand a string yourself, call StreamId.make:

import { StreamId } from "@streamsy/core";

const id: StreamId = StreamId.make("drafts/main");

The StreamId schema accepts any string. A stream class applies stricter id rules, which Templates and addresses lists.

Offset

type Offset = string & Brand.Brand<"Offset">;

Offset is a position in a stream. The Offset schema accepts 16 digits, an underscore, and 16 more digits. Offset.make throws for any other value.

Most results and options type an offset as a plain string, for example Batch.nextOffset and expectedOffset. Treat an offset as an opaque value. Pass on the offset that a result gave you, and do not build one from parts.

ProducerId

type ProducerId = string & Brand.Brand<"ProducerId">;

ProducerId is the branded id of a producer in storage, and the Storage contract keys producer state by it. An application does not need it. It sends the plain producerId string of Producer.Position.

On this page