Options and results
Reference for the protocol options and results in @streamsy/core. The stream methods take these options and succeed with these results.
import {
AppendResult,
CreateResult,
type AppendCallOptions,
type AppendOptions,
type CreateOptions,
type HeadResult,
type ProducerOptions,
type ReadMessage,
type ReadNextOptions,
type ReadNextResult,
type ReadOptions,
type ReadResult,
} from "@streamsy/core";The methods of a stream class take these options and succeed with these results. CreateResult and AppendResult are also values, with a constructor and a matcher for each case. For the failures, see Toolkit types and Errors.
Create
CreateOptions
interface CreateOptions {
readonly contentType?: string;
readonly ttlSeconds?: number;
readonly expiresAt?: string;
readonly closed?: boolean;
readonly forkedFrom?: string;
readonly forkOffset?: string;
readonly forkSubOffset?: number;
readonly initialData?: Uint8Array;
}
| Option | Meaning |
|---|---|
contentType | The content type of the stream. A stream class sets it from the address |
ttlSeconds | The time to live, in seconds. Each append and each read restarts it |
expiresAt | A fixed expiry time |
closed | true to create the stream already closed |
forkedFrom | The id of the source stream of a fork. fork sets it from source |
forkOffset | The fork copies every source message up to and including this offset |
forkSubOffset | The fork also copies the start of the next source message. For a JSON stream it counts messages, otherwise bytes |
initialData | The first messages, written in the same operation as the create |
Set ttlSeconds or expiresAt, not both. create and fork fail with InvalidCreateRequest when both are set, including when ttlSeconds is 0, or when DateTime.make cannot parse expiresAt. The local protocol checks these options before storage access. The remote Layer checks them before sending a request. A fork that sets neither keeps the expiry of its source.
initialData takes raw bytes and bypasses the stream codec. For a new JSON stream, an array becomes one message per element, and another JSON value becomes one message. Invalid JSON fails with InvalidCreateRequest for a plain create and InvalidForkRequest for a fork. Streamsy does not check these messages against the stream schema.
When a stream with the id already exists, create succeeds with Exists if the options match that stream. If they do not match, create fails with CreateConflict. See Create and fork.
CreateResult
type CreateResult =
| {
readonly _tag: "Created";
readonly nextOffset: string;
readonly contentType: string;
readonly closed: boolean;
}
| {
readonly _tag: "Exists";
readonly nextOffset: string;
readonly contentType: string;
readonly closed: boolean;
};
create returns Created when it made a new stream, and Exists when a stream with the same id and options was already there. In both cases nextOffset is the tail of the stream.
The value CreateResult is an Effect Data.taggedEnum. To handle both cases, call its matcher:
import { CreateResult } from "@streamsy/core";
declare const result: CreateResult;
const isNew = CreateResult.$match(result, {
Created: () => true,
Exists: () => false,
});Append
AppendCallOptions
type AppendCallOptions = Omit<AppendOptions, "data" | "contentType">;
AppendCallOptions is the options argument of append on a stream class. It has seq, producer, close, and expectedOffset. The stream class encodes the body and takes the content type from the address, so it omits data and contentType.
AppendOptions
interface AppendOptions {
readonly data: Uint8Array;
readonly contentType: string;
readonly seq?: string;
readonly producer?: ProducerOptions;
readonly close?: boolean;
readonly expectedOffset?: string;
}
AppendOptions holds the options of an append on the protocol writer.
| Option | Meaning |
|---|---|
data | The encoded body |
contentType | The content type of the body. It must match the content type of the stream |
seq | The Stream-Seq of the writer. Each seq must sort after the previous one, compared as strings |
producer | The producer position. The server accepts each position once |
close | true to close the stream after this append. With an empty body, the append only closes the stream |
expectedOffset | The append succeeds only when the tail is this offset |
The append fails with AppendConflict when the content type differs from the stream, or when seq does not sort after the previous one. When expectedOffset differs from the tail, the append fails with OffsetMismatch and changes nothing: it writes no messages, does not close the stream, and does not update the producer state. expectedOffset is a Streamsy extension to the Durable Streams protocol. See Conditional writes.
ProducerOptions
interface ProducerOptions {
readonly producerId: string;
readonly producerEpoch: number;
readonly producerSeq: number;
}
ProducerOptions has the same fields as Producer.Position, and that page gives the rules for each field.
AppendResult
type AppendResult =
| {
readonly _tag: "Appended";
readonly offset: string;
readonly producerEpoch?: number;
readonly producerSeq?: number;
readonly closed: boolean;
}
| {
readonly _tag: "Duplicate";
readonly offset: string;
readonly producerEpoch: number;
readonly producerSeq: number;
readonly closed: boolean;
};
| Case | When | offset |
|---|---|---|
Appended | The append wrote its items | The tail after this append |
Duplicate | The server had already accepted this producer position | The current tail, at or after the first write |
Appended has producerEpoch and producerSeq when the append sent a producer. Duplicate has the current epoch of the producer and the last sequence number that the server accepted. In both cases closed is true when the stream is closed after the call.
Like CreateResult, the value AppendResult is a Data.taggedEnum with $is and $match.
Read
ReadOptions
interface ReadOptions {
offset?: string;
}
A read starts after offset, so the first message it returns is the one after offset.
offset | Reads from |
|---|---|
Not set, or -1 | The start of the stream |
now | The current tail |
| An offset | The message after this offset |
A read with any other value fails with InvalidReadRequest.
ReadNextOptions
interface ReadNextOptions {
offset: string;
cursor?: string;
}
ReadNextOptions holds the options of a long-poll wait, which session makes. offset takes the same values as in ReadOptions. Set cursor to the cursor of the previous ReadNextResult. The cursor lets a CDN collapse the waits of many readers into one request to the origin. See Session.
ReadResult
interface ReadResult {
readonly contentType: string;
readonly messages: ReadonlyArray<ReadMessage>;
readonly nextOffset: string;
readonly upToDate: boolean;
readonly closed: boolean;
}
ReadResult is a batch from the protocol reader, before the codec decodes it.
| Field | Meaning |
|---|---|
messages | The stored messages after the read offset |
nextOffset | The offset of the last message in the batch, or the tail when the batch is empty. The next read starts from this offset |
upToDate | true when nextOffset is the tail of the stream |
closed | true when the stream is closed and this batch reached the tail |
A stream class decodes each ReadResult into a Batch.
ReadNextResult
interface ReadNextResult extends ReadResult {
readonly cursor: string;
readonly timedOut: boolean;
}
ReadNextResult is the result of a long-poll wait. timedOut is true when the wait ended without new messages. Pass cursor in the next ReadNextOptions.
ReadMessage
interface ReadMessage {
readonly data: Uint8Array;
}
ReadMessage is a stored message, as bytes. Storage also keeps the offset and the write time of each message, but a read does not return them.
HeadResult
interface HeadResult {
readonly contentType: string;
readonly nextOffset: string;
readonly ttlSeconds?: number;
readonly expiresAt?: string;
readonly closed: boolean;
}
head returns a HeadResult: the tail of the stream as nextOffset, and its configuration, without any messages. Unlike a read, a head does not restart the time to live.
DurableState
Reference for the DurableState namespace in @streamsy/core. It builds the change events of a Durable State stream.
Toolkit types
Reference for the toolkit types in @streamsy/core. The methods of a stream class succeed with these batches and fold results, and fail with these failure unions.