VariantSchema

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 Added in v4.0.0 Source

Accessors

fields

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Signature

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

Guards

isField

Added in v4.0.0 Source

Returns true when a value is a variant schema field.

Signature

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

isStruct

Added in v4.0.0 Source

Returns true when a value is a variant schema struct.

Signature

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

Models

Class interface

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Type-level helpers for variant schema fields.

Struct

Added in v4.0.0 Source

Type-level helpers for variant schema structs.

Union

Added in v4.0.0 Source

Type-level helpers for unions of variant schema structs.

Schemas

Overrideable

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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

Added in v4.0.0 Source

Runtime type identifier attached to variant schema structs.

Signature

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

Utility Types

Extract type

Added in v4.0.0 Source

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

Added in v4.0.0 Source

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 }