Skip to Content
Reference@streamsy/core

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 template is a relative path. Each segment is a literal or a :name param.
  • params has one codec for each :name in the template, and no other codec. The compiler checks this through ExactTemplateParams when template is a string literal.
  • Each template function throws a RangeError when template is 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 RangeError when the params and the codecs differ. This check catches a template that is typed as a plain string, 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.

MemberMeaning
templateThe relative template, for example notes/:noteId. It is the empty string for a custom route
paramSchemaThe codec from the raw path params to RouteParams. A template route has it, and a custom route does not
matchReturns true when the route owns id
parseReturns the params of id, or None when the id does not match or a param fails to decode
addressReturns 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.

On this page