StreamRoute
Reference for the StreamRoute namespace in @streamsy/core/protocol. A route owns the id grammar of a stream class and builds the address of each id.
import { StreamRoute } from "@streamsy/core/protocol";
import type { StreamAddress } from "@streamsy/core";
import type { Option, Schema } from "effect";A route owns an id grammar and builds the address of each id that it owns. Each stream class extends a route, so the class has template, match, parse, and address. Building a route acquires no service and no resource. The stream class factories on the Streamsy page call these functions. See Declare streams.
Functions
The template functions share these rules:
- A
templateis a relative path. Each segment is a literal or a:nameparam. paramshas one codec for each:namein the template, and no other codec. The compiler checks this throughExactTemplateParamswhentemplateis a string literal.- Each template function throws a
RangeErrorwhentemplateis empty, starts with/, or has an empty segment. It also throws for?,#, or*in the template, a param with no name, a repeated param, or a literal segment that is not a canonical id segment. - Each template function also throws a
RangeErrorwhen the params and the codecs differ. This check catches atemplatethat is typed as a plainstring, which the compiler cannot check.
A canonical id segment is not empty, is not . or .., and has no %, ?, #, /, or \.
StreamRoute.json
declare function json<
const Template extends string,
Codecs extends StreamRoute.ParamCodecs,
A,
I,
RD,
RE,
>(
template: Template,
options: {
readonly params: Codecs & StreamRoute.ExactTemplateParams<Template, Codecs>;
readonly schema: Schema.Codec<A, I, RD, RE>;
},
): StreamRoute.StreamRoute<StreamRoute.Params<Codecs>, A, RD, RE, Template> &
WithPathSchema<StreamRoute.Params<Codecs>>;
// WithPathSchema has no exported name. It makes paramSchema required.
type WithPathSchema<P> = { readonly paramSchema: StreamRoute.PathSchema<P> };
json returns a route whose addresses are JSON addresses with the codec schema.
StreamRoute.state
declare function state<
const Template extends string,
Codecs extends StreamRoute.ParamCodecs,
const C extends StreamAddress.Collections,
>(
template: Template,
options: {
readonly params: Codecs & StreamRoute.ExactTemplateParams<Template, Codecs>;
readonly collections: C & StreamAddress.ValidCollections<C>;
},
): StreamRoute.StateRoute<StreamRoute.Params<Codecs>, C, Template> &
WithPathSchema<StreamRoute.Params<Codecs>> &
WithParamCodecs<Codecs>;
// WithPathSchema has no exported name. It makes paramSchema required.
type WithPathSchema<P> = { readonly paramSchema: StreamRoute.PathSchema<P> };
// WithParamCodecs has no exported name. It keeps the codec record of `params`.
type WithParamCodecs<Codecs extends StreamRoute.ParamCodecs> = { readonly paramCodecs: Codecs };
state returns a route whose addresses are State addresses with the collections collections. The route keeps the params codec record as paramCodecs. StateTable.define reads it for the params of the table declaration.
StreamRoute.bytes
declare function bytes<const Template extends string, Codecs extends StreamRoute.ParamCodecs>(
template: Template,
options: {
readonly params: Codecs & StreamRoute.ExactTemplateParams<Template, Codecs>;
readonly contentType?: string;
},
): StreamRoute.StreamRoute<StreamRoute.Params<Codecs>, Uint8Array, never, never, Template> &
WithPathSchema<StreamRoute.Params<Codecs>>;
// WithPathSchema has no exported name. It makes paramSchema required.
type WithPathSchema<P> = { readonly paramSchema: StreamRoute.PathSchema<P> };
bytes returns a route whose addresses are bytes addresses with the content type contentType. The default content type is application/octet-stream.
StreamRoute.custom
declare function custom<RouteParams, A, RD, RE>(options: {
readonly parse: (id: string) => Option.Option<RouteParams>;
readonly address: (params: RouteParams) => StreamAddress.StreamAddress<A, RD, RE>;
}): StreamRoute.StreamRoute<RouteParams, A, RD, RE>;
custom returns a route for an id grammar that a template cannot express. The route owns an id when parse returns Some. Its template is the empty string, and it has no paramSchema. A group does not check a custom route for overlap with other routes.
address(params).id must parse back to params. custom does not check this.
Types
StreamRoute.StreamRoute
interface StreamRoute<RouteParams, A, RD = never, RE = never, Template extends string = string> {
readonly _tag: "StreamRoute";
readonly template: Template;
readonly paramSchema?: StreamRoute.PathSchema<RouteParams>;
readonly match: (id: string) => boolean;
readonly parse: (id: string) => Option.Option<RouteParams>;
readonly address: (params: RouteParams) => StreamAddress.StreamAddress<A, RD, RE>;
}
A StreamRoute is the id grammar of a stream class, with the params type RouteParams and the item type A.
| Member | Meaning |
|---|---|
template | The relative template, for example notes/:noteId. It is the empty string for a custom route |
paramSchema | The codec from the raw path params to RouteParams. A template route has it, and a custom route does not |
match | Returns true when the route owns id |
parse | Returns the params of id, or None when the id does not match or a param fails to decode |
address | Returns the address of the stream with the params params |
A template route matches an id when the id has the same number of segments, each literal segment is equal, each param segment is a canonical id segment, and each param decodes with its codec.
The address of a template route encodes each param with its codec. address throws a RangeError when a param cannot encode, or encodes to a segment that is not canonical.
StreamRoute.StateRoute
type StateRoute<P, C extends StreamAddress.Collections, Template extends string = string> = Omit<
StreamRoute.StreamRoute<
P,
StreamAddress.CollectionsEvent<C>,
StreamAddress.CollectionsDecodingServices<C>,
StreamAddress.CollectionsEncodingServices<C>,
Template
>,
"address"
> & {
readonly collections: C;
readonly address: (params: P) => StreamAddress.StateAddress<C>;
};
A StateRoute is a route of State events that keeps its collections. Its address returns a StateAddress, so DurableState.changes can read the key field of each collection.
StreamRoute.PathSchema
type PathSchema<P> = Schema.Codec<P, Readonly<Record<string, string | undefined>>>;
A PathSchema<P> decodes the raw path params of an HTTP route into the params P. A template route builds it as a Schema.Struct of its param codecs. @streamsy/serve decodes the params of its routes with it.
StreamRoute.Matcher
interface Matcher {
readonly match: (id: string) => boolean;
}
A Matcher is a route reduced to match, which is all that the group checks and HTTP dispatch need. Every route is a Matcher.
StreamRoute.ParamCodecs
type ParamCodecs = Readonly<Record<string, Schema.Codec<unknown, string>>>;
ParamCodecs is the record of param codecs, with one codec for each :name in the template. Each codec decodes from a string and needs no service.
StreamRoute.Params
type Params<Codecs extends StreamRoute.ParamCodecs> = {
readonly [Name in keyof Codecs]: Codecs[Name]["Type"];
};
Params<Codecs> is the record of decoded params. It has one field for each codec, with the decoded type of that codec.
StreamRoute.ExactTemplateParams
type Seat = { readonly seat: typeof Schema.String };
type Exact = StreamRoute.ExactTemplateParams<"games/:seat", Seat>;
// unknown
type MissingCodec = StreamRoute.ExactTemplateParams<"games/:seat/:round", Seat>;
// never
type ExtraCodec = StreamRoute.ExactTemplateParams<"games", Seat>;
// never
type WideTemplate = StreamRoute.ExactTemplateParams<string, Seat>;
// unknown
ExactTemplateParams<Template, Codecs> is unknown when the :name params of Template and the keys of Codecs are the same set, and never when they differ. The template functions intersect params with it, so a mismatch makes params a never and the compiler reports it. When Template is a plain string, the type is unknown and the run-time check applies.
Streams
Reference for the Streams namespace in @streamsy/core/protocol. Its functions run the stream operations on a StreamAddress over the generic protocol reader and writer.
Testing
Reference for the @streamsy/core/testing entry point. It has the storage contract tests, fault injection, and a protocol Layer for tests.