StreamAddress
Reference for the StreamAddress namespace in @streamsy/core. An address names one stream and holds its codec.
import { StreamAddress, type StreamId } from "@streamsy/core";
import type { Schema } from "effect";An address names one stream and holds the codec of its items. An address is a plain value: building one needs no service and opens no resource. A stream class builds its addresses with at(params), so most code does not call these functions. See Templates and addresses.
The State types follow the Durable State protocol. Most writers build State changes with DurableState instead of these types.
Addresses
StreamAddress.json
declare function json<A, I, RD, RE>(
id: string,
options: { readonly schema: Schema.Codec<A, I, RD, RE> },
): StreamAddress.StreamAddress<A, RD, RE>;
json returns the address of a JSON stream, with the content type application/json. Its codec encodes each item with schema and then serializes it to a JSON string.
StreamAddress.bytes
declare function bytes(
id: string,
options?: { readonly contentType?: string },
): StreamAddress.StreamAddress<Uint8Array>;
bytes returns the address of a byte stream. The default content type is application/octet-stream. An append concatenates its Uint8Array items into one request body, and the server stores that body as one message.
StreamAddress.state
declare function state<const C extends StreamAddress.Collections>(
id: string,
options: { readonly collections: C & StreamAddress.ValidCollections<C> },
): StreamAddress.StateAddress<C>;
state returns the address of a Durable State stream, which is a JSON address that also keeps collections. Each key of collections is the type of a collection on the wire. The codec encodes and decodes the changes of every collection and the three State control messages.
StreamAddress.StreamAddress
interface StreamAddress<A, RD = never, RE = never> {
readonly _tag: "Json" | "Bytes";
readonly id: StreamId;
readonly contentType: string;
readonly codec: Schema.Codec<A, string | Uint8Array, RD, RE>;
}
| Field | Meaning |
|---|---|
_tag | Json when the server stores each item as one message. Bytes when an append concatenates its items into one message |
id | The stream id |
contentType | The content type that create sends |
codec | Encodes an item to its wire form, and decodes the wire form back to an item |
RD is the set of services that the codec needs to decode, and RE is the set of services that it needs to encode.
StreamAddress.StateAddress
interface StateAddress<
C extends StreamAddress.Collections,
RD = StreamAddress.CollectionsDecodingServices<C>,
RE = StreamAddress.CollectionsEncodingServices<C>,
> extends StreamAddress.StreamAddress<StreamAddress.CollectionsEvent<C>, RD, RE> {
readonly collections: C;
}
A StateAddress is a JSON address that also keeps its collections. DurableState.changes reads the key field of each collection from collections.
Collections
StreamAddress.Collection
interface Collection<
A,
I,
RD,
RE,
Key extends StreamAddress.StateKey<A> = StreamAddress.StateKey<A>,
> {
readonly schema: Schema.Codec<A, I, RD, RE>;
readonly key: Key;
}
A Collection describes a collection of a State stream. schema is the codec of its values, and key names the value field that gives each change its key.
StreamAddress.Collections
type Collections = Record<string, StreamAddress.Collection<any, any, any, any, any>>;
Collections is the record of the collections of a State stream. Each key is the type that names the collection on the wire.
StreamAddress.ValidCollections
type ValidCollections<C extends StreamAddress.Collections> = {
readonly [K in keyof C]: C[K]["key"] extends StreamAddress.StateKey<C[K]["schema"]["Type"]>
? C[K]
: { readonly key: StreamAddress.StateKey<C[K]["schema"]["Type"]> };
};
ValidCollections checks at compile time that each key names a string or number field of its own collection. It maps a valid collection to itself, and it maps a collection with a wrong key to a type that allows only valid keys. The compiler then reports the error on the key of that collection, and not on the whole record.
StreamAddress.StateKey
type StateKey<A> = {
[K in keyof A]-?: A[K] extends string | number ? K : never;
}[keyof A];
StateKey<A> is the union of the fields of A that can be a State key. A field qualifies when its type is string or number. An optional field does not qualify.
StreamAddress.CollectionsEvent
type CollectionsEvent<C extends StreamAddress.Collections> =
StreamAddress.CollectionsChange<C> | StreamAddress.StateControl;
CollectionsEvent<C> is the item type of a State stream: a change to any collection of C, or a State control message.
StreamAddress.CollectionsChange
type CollectionsChange<C extends StreamAddress.Collections> = {
[K in keyof C & string]: StreamAddress.StateChange<C[K]["schema"]["Type"], K>;
}[keyof C & string];
CollectionsChange<C> is the union of the changes to every collection of C. type discriminates the union, so a check of type narrows value to the value type of that collection.
StreamAddress.CollectionsEncodedEvent
type CollectionsEncodedEvent<C extends StreamAddress.Collections> =
StreamAddress.CollectionsEncodedChange<C> | StreamAddress.StateControl;
CollectionsEncodedEvent<C> is the wire form of CollectionsEvent.
StreamAddress.CollectionsEncodedChange
type CollectionsEncodedChange<C extends StreamAddress.Collections> = {
[K in keyof C & string]: StateEncodedChange<C[K]["schema"]["Encoded"], K>;
}[keyof C & string];
// StateEncodedChange has no exported name. It is the wire form of one change.
type StateEncodedChange<A, Type extends string = string> =
| (Omit<StreamAddress.StateUpsert<A, Type>, "headers"> & {
readonly headers: Omit<StreamAddress.StateHeaders, "operation"> & {
readonly operation: "insert" | "update" | "upsert";
};
})
| StreamAddress.StateDelete<A, Type>;
CollectionsEncodedChange<C> is the wire form of CollectionsChange. On the wire, an upsert can have the operation insert, update, or upsert. A read decodes all three as upsert.
StreamAddress.CollectionsDecodingServices
type CollectionsDecodingServices<C extends StreamAddress.Collections> =
C[keyof C]["schema"]["DecodingServices"];
CollectionsDecodingServices<C> is the union of the services that the collection schemas of C need to decode.
StreamAddress.CollectionsEncodingServices
type CollectionsEncodingServices<C extends StreamAddress.Collections> =
C[keyof C]["schema"]["EncodingServices"];
CollectionsEncodingServices<C> is the union of the services that the collection schemas of C need to encode.
Changes and controls
StreamAddress.isChange
declare function isChange<E extends StreamAddress.StateEvent<unknown>>(
event: E,
): event is Exclude<E, StreamAddress.StateControl>;
isChange returns true for an upsert or a delete, and narrows event to a change. Call it before you read the type or the key of a State item, because a control message has neither.
StreamAddress.isUpsert
declare function isUpsert<E extends StreamAddress.StateEvent<unknown>>(
event: E,
): event is Extract<E, StreamAddress.StateUpsert<unknown>>;
isUpsert returns true for an upsert, and narrows event to a StateUpsert so that you can read its value. It returns false for a delete and for a control message. The State codec decodes the wire operations insert and update to upsert, so isUpsert returns true for them too.
StreamAddress.isControl
declare function isControl<E extends StreamAddress.StateEvent<unknown>>(
event: E,
): event is Extract<E, StreamAddress.StateControl>;
isControl returns true for a control message, and narrows event to a StateControl. A control message has headers.control, and a change has headers.operation.
StreamAddress.reset
declare function reset(options?: { readonly offset?: string }): StreamAddress.StateControl;
reset returns a reset control message. A reader that receives it clears its materialized state, then applies the items that follow. See Control messages.
StreamAddress.snapshotStart
declare function snapshotStart(options?: { readonly offset?: string }): StreamAddress.StateControl;
snapshotStart returns a snapshot-start control message. The changes between it and the next snapshot-end form a complete snapshot.
StreamAddress.snapshotEnd
declare function snapshotEnd(options?: { readonly offset?: string }): StreamAddress.StateControl;
snapshotEnd returns a snapshot-end control message, which closes the snapshot that snapshot-start opened.
When you call one of the three control functions without offset, the control message has no headers.offset key:
import { StreamAddress } from "@streamsy/core";
const controls = [StreamAddress.snapshotStart(), StreamAddress.snapshotEnd({ offset: "42" })];controls[0].headers is { control: "snapshot-start" }, and controls[1].headers is { control: "snapshot-end", offset: "42" }.
StreamAddress.stateChange
declare function stateChange<A, I, RD, RE, const Type extends string>(options: {
readonly schema: Schema.Codec<A, I, RD, RE>;
readonly type: Type;
}): Schema.Codec<StreamAddress.StateChange<A, Type>, StateEncodedChange<I, Type>, RD, RE>;
// StateEncodedChange has no exported name. It is the wire form of one change.
type StateEncodedChange<A, Type extends string = string> =
| (Omit<StreamAddress.StateUpsert<A, Type>, "headers"> & {
readonly headers: Omit<StreamAddress.StateHeaders, "operation"> & {
readonly operation: "insert" | "update" | "upsert";
};
})
| StreamAddress.StateDelete<A, Type>;
stateChange returns the codec for the upserts and deletes of one collection. state builds one of these codecs for each collection. When an optional header has no value, leave its key out. The codec rejects a header that is set to undefined.
StreamAddress.stateControl
declare const stateControl: Schema.Codec<StreamAddress.StateControl>;
stateControl is the codec for the State control messages. It needs no services to encode or decode.
StreamAddress.StateEvent
type StateEvent<A, Type extends string = string> =
StreamAddress.StateChange<A, Type> | StreamAddress.StateControl;
StateEvent<A, Type> is a change to the collection Type with values of type A, or a control message.
StreamAddress.StateChange
type StateChange<A, Type extends string = string> =
StreamAddress.StateUpsert<A, Type> | StreamAddress.StateDelete<A, Type>;
StateChange is an upsert or a delete in a collection. headers.operation discriminates the two.
StreamAddress.StateUpsert
interface StateUpsert<A, Type extends string = string> {
readonly type: Type;
readonly key: string;
readonly value: A;
readonly headers: StreamAddress.StateHeaders & { readonly operation: "upsert" };
}
StateUpsert inserts or updates the row key in the collection type, and value is the new row.
StreamAddress.StateDelete
interface StateDelete<A, Type extends string = string> {
readonly type: Type;
readonly key: string;
readonly old_value?: A;
readonly headers: StreamAddress.StateHeaders & { readonly operation: "delete" };
}
StateDelete deletes the row key from the collection type. When the writer sent the deleted row, old_value holds it.
StreamAddress.StateHeaders
interface StateHeaders {
readonly operation: "upsert" | "delete";
readonly offset?: string;
readonly txid?: string;
readonly timestamp?: string;
readonly from?: string;
}
StateHeaders holds the headers of a change. When offset or txid has no value, leave its key out instead of setting it to undefined.
StreamAddress.StateControl
interface StateControl {
readonly headers: {
readonly control: StreamAddress.StateControlName;
readonly offset?: string;
};
}
StateControl is a control message. It has no type and no key.
StreamAddress.StateControlName
type StateControlName = "snapshot-start" | "snapshot-end" | "reset";
StateControlName is the name of a State control message. Section 4.2 of the Durable State protocol defines the three names.