DurableState
Reference for the DurableState namespace in @streamsy/core. It builds the change events of a Durable State stream.
import { DurableState, StreamAddress } from "@streamsy/core";
import type { Array } from "effect";DurableState builds the items that you append to a Streamsy.state stream. upsert and remove each describe one change. changes turns a list of changes into change events: it adds the key and the headers, and the compiler checks each change against the collections of the address. For a worked example, see Write changes.
DurableState.upsert
declare function upsert<const Type extends string, A>(
type: Type,
value: A,
options?: { readonly headers?: DurableState.ChangeHeaders },
): DurableState.Upsert<A, Type>;
upsert describes an insert or an update of value in the collection type. It takes no key, because changes reads the key from the key field of value.
DurableState.remove
declare function remove<const Type extends string, A = never>(
type: Type,
key: string | number,
options?: { readonly oldValue?: A; readonly headers?: DurableState.ChangeHeaders },
): DurableState.Delete<NoInfer<A>, Type>;
remove describes the delete of the row key from the collection type. To also write the deleted row to the event as old_value, pass it as oldValue.
DurableState.changes
declare function changes<C extends StreamAddress.Collections, RD, RE>(
address: StreamAddress.StateAddress<C, RD, RE>,
options: { readonly offset?: string },
entries: Array.NonEmptyReadonlyArray<DurableState.Entry<C>>,
): Array.NonEmptyReadonlyArray<StreamAddress.CollectionsEvent<C>>;
declare function changes<C extends StreamAddress.Collections, RD, RE>(
address: StreamAddress.StateAddress<C, RD, RE>,
options: { readonly offset?: string },
entries: ReadonlyArray<DurableState.Entry<C>>,
): ReadonlyArray<StreamAddress.CollectionsEvent<C>>;
changes turns entries into the events that you append to address, in the same order. When entries is a non-empty array, the result type is a non-empty array too.
For each change, changes does four things:
- It sets
keyfrom the key field of an upserted value, or from the key passed toremove. - It sets
headers.offsettooptions.offset, when you pass one. - It sets
headers.txidto${offset}:${index}, unless the change sets its owntxid. Withoutoptions.offset, the event has no defaulttxid. - It copies
timestampandfromfrom the headers of the change.
A control message in entries, such as StreamAddress.reset(), passes through unchanged, except that it gets options.offset when it has no offset of its own.
A change to a collection that the address does not declare does not compile. At run time, changes throws a TypeError when a key is null, undefined, or empty.
DurableState.materialized
declare function materialized<C extends StreamAddress.Collections>(address: {
readonly collections: C;
}): DurableState.Materialized<C>;
materialized returns the empty state for the collections of address: one empty map for each collection, and no open snapshot. Pass a State address or a State stream class, because both have collections. Start a materialize fold from this value.
DurableState.materialize
declare function materialize<C extends StreamAddress.Collections>(
state: DurableState.Materialized<C>,
events: Iterable<StreamAddress.CollectionsEvent<C>>,
): DurableState.Materialized<C>;
materialize folds events into state and returns the new state. It applies the rules of the Durable State protocol:
- An upsert sets the row of its key, and a delete removes it.
- A
resetcontrol message clears every collection and closes an open snapshot. - A
snapshot-startcontrol message opens a snapshot. Thesnapshot-endcontrol message that closes it removes each row that no upsert named sincesnapshot-start.
A snapshot can span several calls, because the returned snapshot carries it to the next call. A snapshot-end with no open snapshot changes nothing. materialize drops a change to a collection that state.rows does not hold.
materialize does not change state. It copies only the maps of the collections that events change, and the returned state shares every other map with state.
import { Effect } from "effect";
import { DurableState } from "@streamsy/core";
import { Workspace } from "./streams.ts";
const issues = Effect.gen(function* () {
const workspace = yield* Workspace;
const { items } = yield* workspace.collect({ workspaceId: "w1" });
return DurableState.materialize(DurableState.materialized(Workspace), items).rows.issue;
});DurableState.ChangeHeaders
interface ChangeHeaders {
readonly txid?: string;
readonly timestamp?: string;
readonly from?: string;
}
ChangeHeaders holds the headers that a change can set for itself. changes sets operation and offset, and a change cannot override them.
DurableState.Upsert
type Upsert<A, Type extends string = string> = {
readonly _tag: "Upsert";
readonly type: Type;
readonly value: A;
readonly headers?: DurableState.ChangeHeaders;
};
upsert returns an Upsert. Pass it to changes, which adds the key and the headers.
DurableState.Delete
type Delete<A, Type extends string = string> = {
readonly _tag: "Delete";
readonly type: Type;
readonly key: string | number;
readonly oldValue?: A;
readonly headers?: DurableState.ChangeHeaders;
};
remove returns a Delete. Pass it to changes, which checks the key and adds the headers.
DurableState.Change
type Change<C extends StreamAddress.Collections> = {
[K in keyof C & string]:
DurableState.Upsert<C[K]["schema"]["Type"], K> | DurableState.Delete<C[K]["schema"]["Type"], K>;
}[keyof C & string];
Change<C> is an Upsert or a Delete for any collection of C. The union pairs each collection type with the value type of its schema, so an upsert must carry a value of the collection that it names.
DurableState.Entry
type Entry<C extends StreamAddress.Collections> =
DurableState.Change<C> | StreamAddress.StateControl;
Entry<C> is an item of the entries list of changes: a change, or a State control message.
DurableState.Materialized
interface Materialized<C extends StreamAddress.Collections> {
readonly rows: DurableState.Rows<C>;
readonly snapshot: ReadonlySet<string> | undefined;
}
Materialized<C> is the state that materialized returns and materialize folds: the latest row for each key of each collection of C. snapshot holds the rows that upserts named since an open snapshot-start, and is undefined when no snapshot is open. Treat snapshot as opaque, and pass it on unchanged.
DurableState.Rows
type Rows<C extends StreamAddress.Collections> = {
readonly [K in keyof C & string]: ReadonlyMap<string, C[K]["schema"]["Type"]>;
};
Rows<C> holds one map for each collection of C, from the State key to the value of the row. A State key is a string, so a row with the number key 7 is under "7".