Skip to Content
Reference@streamsy/core

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>;
}
FieldMeaning
_tagJson when the server stores each item as one message. Bytes when an append concatenates its items into one message
idThe stream id
contentTypeThe content type that create sends
codecEncodes 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.

On this page