Skip to Content
Reference@streamsy/core

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;
}
OptionMeaning
contentTypeThe content type of the stream. A stream class sets it from the address
ttlSecondsThe time to live, in seconds. Each append and each read restarts it
expiresAtA fixed expiry time
closedtrue to create the stream already closed
forkedFromThe id of the source stream of a fork. fork sets it from source
forkOffsetThe fork copies every source message up to and including this offset
forkSubOffsetThe fork also copies the start of the next source message. For a JSON stream it counts messages, otherwise bytes
initialDataThe 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.

OptionMeaning
dataThe encoded body
contentTypeThe content type of the body. It must match the content type of the stream
seqThe Stream-Seq of the writer. Each seq must sort after the previous one, compared as strings
producerThe producer position. The server accepts each position once
closetrue to close the stream after this append. With an empty body, the append only closes the stream
expectedOffsetThe 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;
    };
CaseWhenoffset
AppendedThe append wrote its itemsThe tail after this append
DuplicateThe server had already accepted this producer positionThe 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.

offsetReads from
Not set, or -1The start of the stream
nowThe current tail
An offsetThe 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.

FieldMeaning
messagesThe stored messages after the read offset
nextOffsetThe offset of the last message in the batch, or the tail when the batch is empty. The next read starts from this offset
upToDatetrue when nextOffset is the tail of the stream
closedtrue 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.

On this page