Declarations and state
Reference for the declaration and state types in @streamsy/projection. A declaration binds params into a projection, and a state definition sets the value that a projection keeps.
import type {
CurrentProjection,
DecideSpec,
Declaration,
Emits,
Initial,
Snapshot,
StateDefinition,
StateSchema,
Step,
} from "@streamsy/projection";
import type { Decision, OffsetMismatch } from "@streamsy/core";
import type { StreamRoute } from "@streamsy/core/protocol";
import type { Effect, Option, Schedule, Schema } from "effect";The constructors return a Declaration, and take these state and step types. See Define and run and State.
Declarations
Declaration
interface Declaration<Codecs extends StreamRoute.ParamCodecs, Bound, HE = never, HR = never> {
readonly retry?:
| {
readonly schedule?: import("effect").Schedule.Schedule<unknown>;
readonly maxAttempts?: number;
readonly onExhausted?: (
unit: import("@streamsy/projection").Unit<StreamRoute.Params<Codecs>>,
failure: import("@streamsy/projection").RunnerFailure,
) => import("effect").Effect.Effect<void, HE, HR>;
}
| undefined;
readonly id: string;
readonly version: number;
readonly generation: number;
readonly params: Codecs;
readonly inputs: Inputs;
readonly at: (params: StreamRoute.Params<Codecs>) => Bound;
readonly parse: (id: string) => Option.Option<Partial<StreamRoute.Params<Codecs>>>;
}
// Inputs has no exported name. It is the record of input stream declarations and
// fixed addresses, by name. See /docs/reference/projection/constructors.
type Inputs = Readonly<Record<string, Input>>;
A Declaration is the inert value that a constructor returns. It reads no stream and holds no resource. Bound is the bound projection that at returns, which the runners take.
| Field | Meaning |
|---|---|
id | The projection name |
version | The declared version, 1 when the definition leaves it out |
generation | The declared generation, 1 when the definition leaves it out |
params | The param codecs, by name |
retry | Optional binding retry policy, used by both attach hosts |
inputs | The declared inputs, before at binds them |
at | The method that binds the params and returns the bound projection |
parse | The method that returns the params of a stream id that one of the inputs owns |
at encodes each param with its codec, and throws a RangeError when a param does not encode. For a declaration with outputs, at also checks the outputs. See Projection.emit.
parse tries the stream declarations in inputs in order, and returns the params from the first one whose route parses id. An input that declares fewer params than the projection gives only its own params. parse skips fixed addresses, and returns None when no input parses id.
CurrentProjection
interface CurrentProjection<Inputs extends InputMap, S, E, R, Q> extends Identity {
readonly inputs: Inputs;
readonly state: BoundState<S>;
readonly commit: Pick<Commit.Commit<never, never, Q>, "load">;
readonly process: (
batch: Slices<Inputs>,
unit: Unit,
encoded?: string,
) => Effect.Effect<{ readonly value: S; readonly encoded: string }, E, R>;
}
// BoundState has no exported name. It is the state of a bound projection, with the
// params already passed to `initial`.
interface BoundState<A> {
readonly schema: StateSchema<A>;
readonly initial: () => A;
}
A CurrentProjection is a bound projection that has a state: definition. Projection.current and Projection.decide take it. A projection from fold, mapAccum, or mapAccumBatch fits. A projection with no state: does not, and the compiler reports it. current drops the output items of the handler. Its handlers receive the same slices and entries: local slices have per-item offsets, and a read from entry.offset resumes after that entry. Non-empty HTTP slices have offsets undefined and entries omit offset; every empty slice has offsets: [].
DecideSpec
interface DecideSpec<Inputs extends InputMap, K extends keyof Inputs, S, B, E, R> {
readonly input: K;
readonly decide: (
snapshot: Snapshot<S, Inputs>,
) => Effect.Effect<Decision<B, ItemOf<Inputs[K]>>, E, R>;
readonly retry?: Schedule.Schedule<unknown, OffsetMismatch>;
}
A DecideSpec tells Projection.decide which input to append to, how to decide, and when to retry.
| Field | Meaning |
|---|---|
input | The name of the input to append to. Its offset in the snapshot is the expectedOffset of the append |
decide | The function that returns the answer and the items to append. It must not write |
retry | The schedule for a retry after the append fails with OffsetMismatch. The default is Schedule.recurs(3) |
The items of the Decision have the item type of the input that input names.
State
StateDefinition
interface StateDefinition<A, I = unknown, P = Record<string, string>> {
readonly schema: StateSchema<A, I>;
readonly initial: Initial<A, P>;
}
A StateDefinition is the state: field of fold, mapAccum, and mapAccumBatch. The runner keeps one value for each projection key, in the checkpoint record with the input offsets. Each save replaces the value, and the record keeps no history.
schema encodes the value to JSON for the record. A change to the encoded form needs a new generation. initial gives the value before the first unit, and the runner calls it only when no state is stored. P is the type of the decoded params.
StateSchema
type StateSchema<A, I = unknown> = Schema.Codec<A, I>;
StateSchema is the codec of a state value. It needs no services to decode or encode. The runner stores the value as Schema.fromJsonString(schema) encodes it. A stored value that does not decode fails the run with a ProjectionFault with phase load and reason invalid-record.
Initial
type Initial<A, P = Record<string, string>> = A | ((params: P) => A);
Initial is the initial state value, or a function of the decoded params that returns it. When initial is a function, the runner calls it with the params, so a state value cannot be a function.
Steps
Step
type Step<X, E = never, R = never> = X | Effect.Effect<X, E, R>;
Step is the return type of the fold, emit, mapAccum, and mapAccumBatch handlers: the value, or an Effect of it. The runner runs an Effect, and uses a plain value as it is.
Emits
type Emits<O extends RoutedMap> = {
readonly [K in keyof O]?: ReadonlyArray<Item<O[K]>>;
};
// RoutedMap and Item have no exported name. RoutedMap is the record of output
// stream declarations and fixed addresses, by name. Item is the item type of one
// output: a DurableState.Entry for a State stream, or the decoded item of a JSON
// stream. See /docs/reference/projection/constructors.
Emits is the object that an output handler returns: an array of items for each output name. A missing name emits nothing, and an empty array uses no producer sequence. The items of a State output are DurableState.Entry values: changes, and State control messages such as StreamAddress.reset(). The items of a JSON output have its item type.
StateTable and FoldByKey
Reference for StateTable, FoldByKey and FoldByKeyError in @streamsy/projection. A State table keeps the rows of a Durable State stream in SQL, and a keyed fold writes rows into it.
Units and progress
Reference for the unit, batch, and result types in @streamsy/projection. A unit is one slice of each input that a projection reads, handles, and commits together.