pnwkit 3.0 - v4.3.0
    Preparing search index...

    Class MutationBuilder<TFields, TArgs, F, I>Abstract

    Abstract base class for building and executing type-safe GraphQL mutations.

    Standalone — it does not depend on the query builder. A mutation is "call name(args) and select fields off the object it returns", so this class provides:

    • set for the mutation's input arguments;
    • select for choosing scalar payload fields to return;
    • include for selecting nested relations on the payload;
    • its own GraphQL value serialization with input sanitization and size limits.

    Only the selected fields/relations are returned, exactly like the query builder. Concrete mutations extend this class and are exposed as factory methods on pnwkit.mutations.

    await pnwkit.mutations.bankWithdraw()
        .set({ receiver: 738355, receiver_type: 1, money: 1_000_000 })
        .select("id", "date", "money")
        .include("receiver", n => n.select("id", "nation_name"))
        .execute();
    // -> { id, date, money, receiver: { id, nation_name } }

    Type Parameters

    • TFields

      The fields available on the mutation payload (a *Fields type)

    • TArgs

      The mutation's input-argument shape

    • F extends Exclude<keyof TFields, "__typename"> = never

      The union of selected scalar field keys (tracked through chaining)

    • I extends Record<string, any> = {}

      The included relations (tracked through chaining)

    Hierarchy (View Summary)

    Index
    apiKeyOverride? args includes kit mutationName selectedFields
    apiKey execute include select set
    apiKeyOverride?: string

    Per-call API key override, set via apiKey.

    args: Partial<TArgs> = {}

    Root input arguments, set via set.

    includes: Map<string, MutationSubqueryConfig<any>> = ...

    Included relations, set via include.

    kit: PnwKitApi

    The PnWKit instance owning the API key and GraphQL service.

    mutationName: string

    The GraphQL mutation field name (e.g. 'bankWithdraw').

    selectedFields: Exclude<keyof TFields, "__typename">[] = []

    Selected scalar payload fields, set via select.

    • Use a specific API key for this call instead of the client's default key. The acting nation is the one that owns the provided key.

      Parameters

      • key: string

        The Politics & War API key to authenticate this mutation with.

      Returns this

      This builder instance for method chaining.

    • Execute the mutation and return the selected payload.

      The result contains only the selected fields and included relations. The call bypasses the response cache (a mutation must never be served or populate a cached result).

      Returns Promise<MutationResult<TFields, F, I>>

      The mutation payload, typed to the selection.

      Error if nothing was selected, or the mutation fails / returns no data.

    • Include a nested relation on the payload, with full recursive type inference (mirrors the query builder's include).

      Type Parameters

      • K extends string | number | symbol
      • TConfig extends MutationSubqueryConfig<GetRelationsFor<TFields>[K]>
      • TNested = InferMutationSubquery<ReturnType<TConfig>>
      • TWrapped = GetRelationsFor<TFields>[K] extends any[] ? TNested[] : TNested

      Parameters

      • relation: K

        The relation name to include (a key of the payload's relations).

      • config: TConfig

        A builder function configuring the nested selection.

      Returns MutationBuilder<TFields, TArgs, F, I & Record<K, TWrapped>>

      This builder, with the included relation tracked in the return type.

      .include('receiver', n => n.select('id', 'nation_name'))

    • Set the mutation's input arguments.

      Parameters

      • args: TArgs

        The fully-typed input arguments for this mutation.

      Returns this

      This builder instance for method chaining.

    Settings
    Member Visibility

    On This Page
    Properties
    Methods