discriminatedUnion - API reference

API reference › @evolu/common › Type › discriminatedUnion

Call Signature

function discriminatedUnion<Members>(
  ...members: Members & DiscriminatedUnionValidation<"type", Members>
): DiscriminatedUnionType<"type", Members>;

Defined in: packages/common/src/Type.ts:12196

Discriminated union Type.

With no explicit key, the conventional type property created by typed is used. Pass a key first to discriminate Object Types using a different property.

Every member must be an Object Type with a unique required string, number, bigint, or boolean LiteralType at the discriminator key. Unlike union, only the selected member is decoded, checked, or encoded. The Discriminated Union Input therefore narrows each member's discriminator from its widened Input to the exact literal that selects that member. Use fromUnknown when a value does not yet have that correlated Input type.

Example

import { assertOk, String, discriminatedUnion, typed } from "@evolu/common";

const Created = typed("Created", { id: String });
const Deleted = typed("Deleted", { id: String });
const Event = discriminatedUnion(Created, Deleted);

assertOk(Event.fromUnknown({ type: "Created", id: "id" }), {
  type: "Created",
  id: "id",
});

Call Signature

function discriminatedUnion<Key, Members>(
  key: ValidateDiscriminatedUnionKey<Key>,
  ...members: Members & DiscriminatedUnionValidation<Key, Members>
): DiscriminatedUnionType<Key, Members>;

Defined in: packages/common/src/Type.ts:12231

Creates a Discriminated Union Type with an explicit discriminator key.

Example

import {
  assertOk,
  Number,
  String,
  discriminatedUnion,
  literal,
  object,
} from "@evolu/common";

const Added = object({ kind: literal("added"), value: String });
const Removed = object({ kind: literal("removed"), id: Number });
const Event = discriminatedUnion("kind", Added, Removed);

assertOk(Event.fromUnknown({ kind: "added", value: "Evolu" }), {
  kind: "added",
  value: "Evolu",
});
assertOk(Event.fromUnknown({ kind: "removed", id: 1 }), {
  kind: "removed",
  id: 1,
});