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.
| Field | Meaning |
|---|---|
initial | The function that returns the start value of the fold. Each call of the method calls initial once |
fold | The function that returns the state after one more item |
decide | The function that returns a value and the items to append. at.offset is the tail that state includes |
retry | The 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.