VariantSchema unstable

Builds related schemas for named variants from shared field definitions.

make fixes the variant names and default variant, then lets callers define fields that are shared by all variants or specific to some variants. From those definitions it can create schema classes, unions, extracted struct schemas, and helpers for changing fields across variants.

17 exports Since v4.0.0 Source

Accessors

fields

unstable

Since v4.0.0

Returns the original field definitions stored on a variant schema struct.

Signature

declare function fields<A extends Struct<any>>(self: A): A["~effect/schema/VariantSchema"]

Constructors

make

unstable

Since v4.0.0

Creates a variant schema toolkit for a fixed set of variant names and a default variant.

Signature

declare function make<Variants extends readonly Array<string>, Default extends string>(options: {
  readonly defaultVariant: Default;
  readonly variants: Variants;
}): {
  readonly Class: <Self = never>(identifier: string) => <Fields extends Fields>(fields: Fields & Validate<Fields, Variants[number]>, annotations?: Declaration<Self, readonly [Struct<ExtractFields<Default, Fields, true>>]>) => [Self] extends [never] ? "Missing `Self` generic - use `class Self extends Class<Self>()({ ... })`" : Class<Self, Fields, Struct<ExtractFields<Default, Fields, true>>> & { [V in string]: Struct<{ [K in string | number | symbol]: ExtractFields<V, Fields, false>[K] }> };
  readonly extract: {
    <V extends string>(variant: V): <A extends Struct<any>>(self: A) => Extract<V, A, V extends Default ? true : false>;
    <V extends string, A extends Struct<any>>(self: A, variant: V): Extract<V, A, V extends Default ? true : false>;
  };
  readonly Field: <A extends ConfigWithKeys<Variants[number]>>(config: A & { [K in string | number | symbol]: never }) => Field<A>;
  readonly fieldEvolve: {
    <Self extends Top | Field<any>, Mapping extends { [K in string]: (variant: Top) => Top } | {
      [key: string]: (variant: any) => Top | undefined;
    }>(f: Mapping): (self: Self) => Field<Self extends Field<S> ? { [K in string | number | symbol]: K extends keyof Mapping ? Mapping[K] extends (arg: any) => any ? ReturnType<any[any]> : S[K] : S[K] } : { [K in string]: K extends keyof Mapping ? Mapping[K] extends (arg: any) => any ? ReturnType<any[any]> : Self : Self }>;
    <Self extends Top | Field<any>, Mapping extends { [K in string]: (variant: Top) => Top } | {
      [key: string]: (variant: any) => Top | undefined;
    }>(self: Self, f: Mapping): Field<Self extends Field<S> ? { [K in string | number | symbol]: K extends keyof Mapping ? Mapping[K] extends (arg: any) => any ? ReturnType<any[any]> : S[K] : S[K] } : { [K in string]: K extends keyof Mapping ? Mapping[K] extends (arg: any) => any ? ReturnType<any[any]> : Self : Self }>;
  };
  readonly FieldExcept: <Keys extends readonly Array<Variants[number]>>(keys: Keys) => <S extends Top>(schema: S) => Field<{ [K in string]: S }>;
  readonly FieldOnly: <Keys extends readonly Array<Variants[number]>>(keys: Keys) => <S extends Top>(schema: S) => Field<{ [K in string]: S }>;
  readonly Struct: <A extends Fields>(fields: A & Validate<A, Variants[number]>) => Struct<A>;
  readonly Union: <Members extends readonly Array<Struct<any>>>(members: Members) => Union<Members, Default> & Variants<Members, Variants[number]>;
}

Override

unstable

Since v4.0.0

Marks a value as an explicit override for an Overrideable schema default.

Signature

declare function Override<A>(value: A): A & Brand<"Override">

Guards

isField

unstable

Since v4.0.0

Returns true when a value is a variant schema field.

Signature

declare function isField(u: unknown): u is Field<any>

isStruct

unstable

Since v4.0.0

Returns true when a value is a variant schema struct.

Signature

declare function isStruct(u: unknown): u is Struct<any>

Models

Class

interface unstable

Since v4.0.0

Schema class type returned by variant class constructors, combining the default variant schema with access to the original variant fields.

Signature

interface Class<Self, Fields extends Struct.Fields, S extends Schema.Top & {
  readonly fields: Schema.Struct.Fields;
}> extends Class<Self, S, {}>, Struct<Struct_.Simplify<Fields>> {
  constructor(props: S["~type.make.in"], options?: {
    readonly disableChecks?: boolean;
  });
  constructor(...args: {} extends S["~type.make.in"] ? [props?: S["~type.make.in"], options?: MakeOptions] : [props: S["~type.make.in"], options?: MakeOptions]);
  readonly "~type.make": Self;
  readonly "~type.make.in": S["~type.make.in"];
  readonly DecodingServices: S["DecodingServices"];
  readonly Encoded: S["Encoded"];
  readonly EncodingServices: S["EncodingServices"];
  readonly fields: S["fields"];
  readonly Iso: S["Iso"];
  readonly Type: Self;
  make<Args extends Array<any>, X>(this: (...args: Args) => X, ...args: Args): X;
}

Field

interface unstable

Since v4.0.0

Pipeable collection of variant-specific schemas for a single logical field.

Signature

interface Field<in out A extends Field.Config> extends Pipeable {
  readonly "~effect/schema/VariantSchema/Field": "~effect/schema/VariantSchema/Field";
  readonly schemas: A;
}

Struct

interface unstable

Since v4.0.0

Pipeable container of schema fields that can be extracted into per-variant Schema.Struct schemas.

Signature

interface Struct<in out A extends Field.Fields> extends Pipeable {
  readonly "~effect/schema/VariantSchema": A;
}

Union

interface unstable

Since v4.0.0

Union schema over the default schemas of a list of variant schema structs.

Signature

interface Union<Members extends ReadonlyArray<Struct<any>>, Default extends string = string> extends Union<{ [K in keyof Members]: Extract<Default, Members[K], true> }> {
  constructor(_: never);
}

Other

Field

unstable

Since v4.0.0

Type-level helpers for variant schema fields.

Struct

unstable

Since v4.0.0

Type-level helpers for variant schema structs.

Union

unstable

Since v4.0.0

Type-level helpers for unions of variant schema structs.

Schemas

Overrideable

unstable

Since v4.0.0

Wraps a schema with an effectful constructor default while allowing explicit values to be marked with Override.

Signature

declare const Overrideable: <S extends Top & WithoutConstructorDefault>(schema: S, options: {
  readonly defaultValue: Effect<S["~type.make.in"]>;
}) => Overrideable<S>

Overrideable

interface unstable

Since v4.0.0

Schema type whose constructor can use an effectful default unless a value is explicitly branded with Override.

Signature

interface Overrideable<S extends Schema.Top & Schema.WithoutConstructorDefault> extends BottomLazy<S["ast"], Overrideable<S>, S["~type.parameters"], S["~type.mutability"], "required", "with-default", S["~encoded.mutability"], S["~encoded.optionality"]> {
  constructor(_: never);
  readonly "~type.make": S["Type"] & Brand<"Override"> | undefined;
  readonly "~type.make.in": S["~type.make.in"];
  readonly DecodingServices: S["DecodingServices"];
  readonly Encoded: S["Encoded"];
  readonly EncodingServices: S["EncodingServices"];
  readonly Iso: S["Type"] & Brand<"Override"> | undefined;
  readonly Type: S["Type"] & Brand<"Override">;
}

Type IDs

TypeId

unstable

Since v4.0.0

Runtime type identifier attached to variant schema structs.

Signature

declare const TypeId: "~effect/schema/VariantSchema"

Utility Types

Extract

type unstable

Since v4.0.0

Computes the schema type produced by extracting a single variant from a variant schema struct.

Signature

type Extract<V extends string, A extends Struct<any>, IsDefault = false> = [A] extends [Struct<infer Fields>] ? IsDefault extends true ? [A] extends [Schema.Top] ? A : Schema.Struct<Struct_.Simplify<ExtractFields<V, Fields>>> : Schema.Struct<Struct_.Simplify<ExtractFields<V, Fields>>> : never

ExtractFields

type unstable

Since v4.0.0

Computes the Schema.Struct field map for a variant by selecting matching field schemas and recursively extracting nested structs.

Signature

type ExtractFields<V extends string, Fields extends Struct.Fields, IsDefault = false> = { [K in keyof Fields]: [Fields[K]] extends [Struct<infer _>] ? Extract<V, Fields[K], IsDefault> : [Fields[K]] extends [Field<infer Config>] ? [Config[V]] extends [Schema.Top] ? Config[V] : never : [Fields[K]] extends [Schema.Top] ? Fields[K] : never }