Errors
Reference for the protocol errors in @streamsy/core. Each error is a tagged class, and you catch it by its tag.
import { OffsetMismatch, StaleEpoch, isProtocolError, type AppendErrorFor } from "@streamsy/core";The stream operations fail with these errors when the protocol rejects a request. Each error is a Schema.TaggedError, so it is an Error with a _tag that you can yield* in Effect.gen. To handle a specific error, catch it by its tag:
import { Effect } from "effect";
import { Notes } from "./streams.ts";
const write = Effect.flatMap(Notes, (notes) =>
notes.append({}, [{ id: "n1", text: "hello" }]),
).pipe(Effect.catchTag("StreamClosed", (error) => Effect.succeed(error.offset)));Each block below shows the _tag and the fields of an error. Every error also has message, name, and stack. The id field is a StreamId, which is a branded string.
Failures of the store, the network, or the codec are faults, such as StorageFault and EncodeFault. They are on the Faults page.
Error classes
StreamNotFound
interface StreamNotFound {
readonly _tag: "StreamNotFound";
readonly id: StreamId;
}
An operation fails with StreamNotFound when no stream has the id id.
StreamGone
interface StreamGone {
readonly _tag: "StreamGone";
readonly id: StreamId;
}
An operation fails with StreamGone when the stream id existed and was deleted.
StreamClosed
interface StreamClosed {
readonly _tag: "StreamClosed";
readonly id: StreamId;
readonly offset: string;
}
An append fails with StreamClosed when the stream is closed. offset is the tail at which the stream was closed.
OffsetMismatch
interface OffsetMismatch {
readonly _tag: "OffsetMismatch";
readonly id: StreamId;
readonly expected: string;
readonly actual: string;
}
An append fails with OffsetMismatch when the tail of the stream is not its expectedOffset. expected is the offset that the append sent, and actual is the current tail. The append writes nothing. See Conditional writes.
AppendConflict
interface AppendConflict {
readonly _tag: "AppendConflict";
readonly id: StreamId;
}
An append fails with AppendConflict in two cases: its content type differs from the content type of the stream, or its Stream-Seq does not sort after the previous one. message says which case applies.
StreamBusy
interface StreamBusy {
readonly _tag: "StreamBusy";
readonly id: StreamId;
}
An append fails with StreamBusy when other writers keep committing to the stream first. The append plans its write again after each lost commit, and it gives up after 64 attempts. The request is safe to send again. Over HTTP, the server answers StreamBusy with a 503.
StaleEpoch
interface StaleEpoch {
readonly _tag: "StaleEpoch";
readonly id: StreamId;
readonly currentEpoch: number;
}
An append fails with StaleEpoch when its producer epoch is lower than the last epoch that the stream accepted for the same producerId. currentEpoch is that last epoch. See Producer.Position.
ProducerGap
interface ProducerGap {
readonly _tag: "ProducerGap";
readonly id: StreamId;
readonly expectedSeq: number;
readonly receivedSeq: number;
}
An append fails with ProducerGap when its producerSeq skips a number. expectedSeq is the next number that the server accepts, and receivedSeq is the number that the append sent.
InvalidEpochSeq
interface InvalidEpochSeq {
readonly _tag: "InvalidEpochSeq";
readonly id: StreamId;
}
The protocol append fails with InvalidEpochSeq when the producer epoch or sequence is not valid, for example a new epoch that does not start at producerSeq 0. The append method of a stream class does not list this error in its type. When a host returns it, the append dies with a defect.
InvalidAppendRequest
interface InvalidAppendRequest {
readonly _tag: "InvalidAppendRequest";
readonly id: StreamId;
}
The protocol append fails with InvalidAppendRequest when the request is not valid, for example an append with no items and no close. message says why. The append method of a stream class does not list this error in its type. When a host returns it, the append dies with a defect.
InvalidCreateRequest
interface InvalidCreateRequest {
readonly _tag: "InvalidCreateRequest";
readonly id: StreamId;
}
create and fork fail with InvalidCreateRequest when both ttlSeconds and expiresAt are set, including when ttlSeconds is 0. They also fail when DateTime.make cannot parse expiresAt. The local protocol checks these options before storage access. The remote client checks them before sending a request.
A plain create also fails with InvalidCreateRequest when a new JSON stream has invalid initialData. The remote client returns InvalidCreateRequest for a plain create HTTP 400 response without stream-not-supported. message says why. Typed stream create and fork methods surface InvalidCreateRequest as a typed failure.
CreateConflict
interface CreateConflict {
readonly _tag: "CreateConflict";
readonly id: StreamId;
readonly reason?:
"config-mismatch" | "soft-deleted" | "fork-content-type" | "fork-source-soft-deleted";
}
A create or a fork fails with CreateConflict when its options do not match the stream that already has the id. reason says why, and message describes the conflict. An HTTP response does not carry the reason, so the remote client leaves reason out.
ForkSourceNotFound
interface ForkSourceNotFound {
readonly _tag: "ForkSourceNotFound";
readonly id: StreamId;
readonly source: StreamId;
}
A fork fails with ForkSourceNotFound when its source stream does not exist. id is the stream that the fork would create, and source is the missing source.
InvalidForkRequest
interface InvalidForkRequest {
readonly _tag: "InvalidForkRequest";
readonly id: StreamId;
}
A fork fails with InvalidForkRequest when its fork offset is not a valid offset, when the offset is past the tail of the source, or when a new JSON fork has invalid initialData. The remote client also returns this error for a fork HTTP 400 response without stream-not-supported. message says why.
NotSupported
interface NotSupported {
readonly _tag: "NotSupported";
readonly id: StreamId;
readonly feature: string;
}
An operation fails with NotSupported when the host or the remote client does not support feature, for example fork, producer, or expected-offset. An append on the memory host or a storage host never fails with NotSupported.
InvalidReadRequest
interface InvalidReadRequest {
readonly _tag: "InvalidReadRequest";
readonly id: StreamId;
}
A read fails with InvalidReadRequest when the request is not valid, for example when the offset has the wrong format. message says why.
CreateConflictReason
type CreateConflictReason =
"config-mismatch" | "soft-deleted" | "fork-content-type" | "fork-source-soft-deleted";
CreateConflictReason is the type of CreateConflict.reason.
| Reason | Meaning |
|---|---|
config-mismatch | A stream with this id exists with another configuration |
soft-deleted | The id belongs to a deleted stream |
fork-content-type | The fork asked for a content type that differs from the source |
fork-source-soft-deleted | The source of the fork was deleted |
Errors by operation
Each protocol operation fails with one of these unions. The methods of a stream class add faults to them, as listed under Failures.
HeadError
type HeadError = StreamNotFound | StreamGone;
head fails with HeadError.
ReadError
type ReadError = StreamNotFound | StreamGone | InvalidReadRequest;
read fails with ReadError.
ReadNextError
type ReadNextError = StreamNotFound | StreamGone | InvalidReadRequest | NotSupported;
readNext fails with ReadNextError. readNext is the protocol read that can wait for new data, and it adds NotSupported to ReadError.
CreateError
type CreateError =
CreateConflict | InvalidCreateRequest | ForkSourceNotFound | InvalidForkRequest | NotSupported;
create and fork fail with CreateError.
AppendBaseError
type AppendBaseError =
StreamNotFound | StreamGone | StreamClosed | StreamBusy | AppendConflict | NotSupported;
An append can fail with any AppendBaseError, whatever its options.
AppendError
type AppendError =
| AppendBaseError
| InvalidAppendRequest
| OffsetMismatch
| StaleEpoch
| ProducerGap
| InvalidEpochSeq;
AppendError lists every error that the protocol append can fail with.
AppendErrorFor
type NoOptions = AppendErrorFor<{}>;
// AppendBaseError
type Conditional = AppendErrorFor<{ expectedOffset: string }>;
// AppendBaseError | OffsetMismatch
type WithProducer = AppendErrorFor<{ producer: Producer.Position }>;
// AppendBaseError | StaleEpoch | ProducerGap
AppendErrorFor<O> lists the errors that an append with options of type O can fail with. It includes OffsetMismatch only when O has expectedOffset, and it includes StaleEpoch and ProducerGap only when O has producer. An optional property counts as set, so AppendErrorFor<AppendCallOptions> includes all three.
RemoveError
type RemoveError = StreamNotFound | StreamGone | StreamBusy;
remove fails with RemoveError.
ProtocolError
type ProtocolError = HeadError | ReadNextError | CreateError | AppendError | RemoveError;
ProtocolError is the union of every protocol error.
Guards
isProtocolError
declare function isProtocolError(error: { readonly _tag: string }): error is ProtocolError;
isProtocolError returns true when the _tag of error is the tag of a protocol error. The HTTP handlers use it to map every protocol error to its HTTP response in one place.
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.
Faults
Reference for the faults in @streamsy/core. A fault reports a failure of the store, the network, or the codec, and a protocol error reports a rejected request.