dyna-record
    Preparing search index...

    Interface DiscriminatedUnionFieldDef

    A schema field definition for a discriminated union type.

    The discriminator names the key used to distinguish variants, and variants maps each discriminator value to an ObjectSchema describing that variant's fields. The discriminator key is automatically added to each variant's inferred type as a string literal.

    Update semantics: Discriminated union fields always use full replacement on update (SET #field = :value), never document path merging. This is because:

    • Different variants have different field sets — a partial document path update could leave orphaned fields from a previous variant leaking through when variants change.
    • Avoiding orphaned fields without full replacement would require a read-before-write to determine the current discriminator value.
    • This matches array update semantics (also full replacement).

    Unlike ObjectFieldDef, discriminated union fields can be nullable because they always use full replacement on update rather than document path expressions, so there is no risk of DynamoDB failing on a missing parent path.

    Scoping constraints:

    • Supported at the ObjectAttribute root level, as fields within an ObjectSchema, and as array items
    • Not supported nested inside other discriminated unions
    const schema = {
      shape: {
        type: "discriminatedUnion",
        discriminator: "kind",
        variants: {
          circle: { radius: { type: "number" } },
          square: { side: { type: "number" } }
        }
      }
    } as const satisfies ObjectSchema;

    type T = InferObjectSchema<typeof schema>;
    // { shape: { kind: "circle"; radius: number } | { kind: "square"; side: number } }
    interface DiscriminatedUnionFieldDef {
        discriminator: string;
        nullable?: boolean;
        type: "discriminatedUnion";
        variants: Readonly<Record<string, NonUnionObjectSchema>>;
    }
    Index

    Properties

    discriminator nullable? type variants

    Properties

    discriminator: string

    The key name used to discriminate between variants.

    nullable?: boolean

    When true, the field becomes optional (T | undefined).

    type: "discriminatedUnion"

    Must be "discriminatedUnion" to indicate a discriminated union field.

    variants: Readonly<Record<string, NonUnionObjectSchema>>

    A record mapping each discriminator value to a NonUnionObjectSchema describing that variant's fields (excluding the discriminator itself). Discriminated unions cannot be nested inside other discriminated unions.

    Settings

    Member Visibility

    On This Page

    Properties