Skip to Content
Reference@streamsy/core

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.

import type {
  AppendFailure,
  Batch,
  Collected,
  CreateFailure,
  DecideSpec,
  Decided,
  Decision,
  Folded,
  FollowFailure,
  HeadFailure,
  OffsetMismatch,
  ReadFailure,
  RemoveFailure,
} from "@streamsy/core";
import type { Effect, Function, Schedule } from "effect";

The methods of a stream class return decoded items and fold results in these types, and they fail with the failure unions at the end of this page. The Streamsy.Api section lists the methods. The protocol options and results are on Options and results.

Results

Batch

interface Batch<A> {
  readonly items: ReadonlyArray<A>;
  readonly nextOffset: string;
  readonly upToDate: boolean;
  readonly closed: boolean;
}

A Batch holds decoded items and the read position after them. read and follow return a stream of batches. nextOffset, upToDate, and closed mean the same as in ReadResult. To continue reading later, pass nextOffset as the offset of the next read.

follow emits no empty batches, with one exception: the last batch of a closed stream can be empty.

Collected

interface Collected<A> {
  readonly items: ReadonlyArray<A>;
  readonly offset: string;
}

collect returns a Collected: every item up to the tail, and the tail that the read reached as offset. Pass offset as expectedOffset to make a conditional write, or as the offset of a later read.

Folded

interface Folded<S> {
  readonly state: S;
  readonly offset: string;
}

fold returns a Folded: the folded value as state, and the tail that the read reached as offset. To continue the fold later, pass state as initial and offset as offset in the options of the next fold. See Fold.

DecideSpec

interface DecideSpec<A, S, B, E, R> {
  readonly initial: Function.LazyArg<S>;
  readonly fold: (state: S, item: A) => S;
  readonly decide: (
    state: S,
    at: { readonly offset: string },
  ) => Effect.Effect<Decision<B, NoInfer<A>>, E, R>;
  readonly retry?: Schedule.Schedule<unknown, OffsetMismatch>;
}

A DecideSpec is the input of the decide method. The method folds the stream into a state, calls your decide function on that state, and appends the items that it returns.

FieldMeaning
initialThe function that returns the start value of the fold. Each call of the method calls initial once
foldThe function that returns the state after one more item
decideThe function that returns a value and the items to append. at.offset is the tail that state includes
retryThe schedule for retries after another writer appends first. The default is Schedule.recurs(3)

Your decide function must not write to the stream, and it must not mutate state. After a lost race, the method passes the state that it already has to fold together with the new items.

The append sets expectedOffset to the tail that the fold reached. When another writer appended first, the append fails with OffsetMismatch. The method then reads the new items, folds them, and calls decide again, for as long as retry allows. When retry stops, the method fails with the last OffsetMismatch. With the default schedule, one call makes at most four appends.

The method does not retry a fault, because a lost reply can hide an append that was written. See Read, fold, append.

Decision

interface Decision<B, A> {
  readonly value: B;
  readonly items: ReadonlyArray<A>;
}

Your decide function returns a Decision. The method returns value to its caller and appends items. When items is empty, the method returns without an append and without a check of the tail.

Decided

interface Decided<B> {
  readonly value: B;
  readonly offset: string;
  readonly appended: boolean;
}

The decide method returns a Decided. appended is true when the method wrote items. offset is then the new tail. When the method wrote nothing, offset is the tail that the fold reached.

Failures

Each failure type is the union of the protocol errors and the faults that a method can fail with. The protocol errors are on Errors, and the faults are on Faults.

ReadFailure

type ReadFailure = StreamNotFound | StreamGone | InvalidReadRequest | StreamsFault | DecodeFault;

read, collect, and fold fail with ReadFailure.

FollowFailure

type FollowFailure = ReadFailure | NotSupported;

follow fails with FollowFailure. It adds NotSupported to ReadFailure, because a remote host can refuse a live read. session fails with the same union minus DecodeFault, because session does not decode items.

AppendFailure

type AppendFailure<O = AppendCallOptions> = AppendErrorFor<O> | StreamsFault | EncodeFault;

An append with options of type O fails with AppendFailure<O>. The union depends on the options through AppendErrorFor. It includes OffsetMismatch only when O has expectedOffset, and it includes StaleEpoch and ProducerGap only when O has producer.

type Plain = Extract<AppendFailure<{}>, OffsetMismatch>;
// never

type Conditional = Extract<AppendFailure<{ expectedOffset: string }>, OffsetMismatch>;
// OffsetMismatch

If a host answers with a rejection that the options rule out, the host has a bug, and the append dies with a defect.

CreateFailure

type CreateFailure = CreateError | StreamsFault;

create and fork fail with CreateFailure.

HeadFailure

type HeadFailure = HeadError | StreamsFault;

head fails with HeadFailure.

RemoveFailure

type RemoveFailure = RemoveError | StreamsFault;

remove fails with RemoveFailure.

On this page