Sanity Library Reference Docs
    Preparing search index...

    Interface WorkflowSession

    interface WorkflowSession {
        discardFieldPreview: {
            (field?: EditableFieldEvaluation): void;
            (target?: EditFieldTarget): void;
        };
        editField: {
            (
                args: {
                    field: EditableFieldEvaluation;
                    mode?: EditMode;
                    value?: unknown;
                },
            ): Promise<OperationResult>;
            (
                args: { mode?: EditMode; target: EditFieldTarget; value?: unknown },
            ): Promise<OperationResult>;
        };
        error: {}
        | undefined;
        evaluation: WorkflowEvaluation | undefined;
        evaluationError: {} | undefined;
        fireAction: (
            args: {
                action: string;
                activity: string;
                params?: Record<string, unknown>;
            },
        ) => Promise<OperationResult>;
        guards: readonly MutationGuardDoc[] | undefined;
        invalid: InvalidDoc | undefined;
        previewField: {
            (
                args: {
                    field: EditableFieldEvaluation;
                    mode?: EditMode;
                    value?: unknown;
                },
            ): void;
            (
                args: { mode?: EditMode; target: EditFieldTarget; value?: unknown },
            ): void;
        };
        ready: boolean;
        tick: () => Promise<OperationResult>;
    }
    Index

    Properties

    discardFieldPreview editField error evaluation evaluationError fireAction guards invalid previewField ready tick

    Properties

    discardFieldPreview: {
        (field?: EditableFieldEvaluation): void;
        (target?: EditFieldTarget): void;
    }

    Drop staged previews for one target (or all), reverting the projection to committed state on the next evaluation.

    editField: {
        (
            args: {
                field: EditableFieldEvaluation;
                mode?: EditMode;
                value?: unknown;
            },
        ): Promise<OperationResult>;
        (
            args: { mode?: EditMode; target: EditFieldTarget; value?: unknown },
        ): Promise<OperationResult>;
    }

    Edit a declared-editable field against the held content (commits via the engine): reassign / reschedule / claim-by-hand / append-to-log. The editable fields and each one's edit verdict are on WorkflowSession.evaluation's editableFields.

    Caveat for inline-field UIs: each call is a discrete commit (a history entry, a guard refresh, a cascade that can move the instance, all under an ifRevisionId write), not a draft patch. Bind it to a deliberate boundary, never an onChange per keystroke: pickers (actor / date / boolean) fire one discrete change and are fine on change; free-text (string / note body) must debounce or confirm (blur / Enter / Save), or every keystroke writes history and races the revision check.

    error: {} | undefined

    Set when any observer stream feeding the session failed. The session is not ready until that stream recovers.

    evaluation: WorkflowEvaluation | undefined

    Latest projection against the held content; undefined until the first evaluation resolves (and the watch-set is ready). Recomputed as watched docs/guards emit and after each settled tick/fireAction/editField, so a commit updates the projection without waiting for a store echo. Resets to undefined when instanceId swaps: the previous instance's projection never carries over into the next instance's session.

    evaluationError: {} | undefined

    Set when the last WorkflowSession.evaluation attempt threw — a permanent failure, unlike the undefined-while-loading state. Clears on the next resolved attempt; doesn't affect WorkflowSession.ready.

    fireAction: (
        args: {
            action: string;
            activity: string;
            params?: Record<string, unknown>;
        },
    ) => Promise<OperationResult>

    Fire an activity action against the held content (commits via the engine).

    guards: readonly MutationGuardDoc[] | undefined

    The instance's live mutation guards: undefined until the first read resolves, then the resolved list (possibly empty), updating as guards are deployed on stage entry and deleted on exit. Through a guardScope-only resubscription the last-resolved list is held while the replacement query loads, so consolidation churn never reads as guard loss. Also fed into WorkflowSession.evaluation: a guard that denies the instance write flips action verdicts to mutation-guard-denied (advisory, from the engine's optimistic evaluation). undefined is not only "loading": a guard stream that resolved invalid also reads undefined here — check WorkflowSession.invalid and WorkflowSession.error before rendering a spinner.

    invalid: InvalidDoc | undefined

    Set when an engine-owned doc feeding this session failed read validation — the instance doc or a guard, from the first observation or a later live emission (InvalidDoc says which doc and why). Explicit state, not a throw: render the remediation (upgrade the engine for model-ahead; investigate the doc for shape-violation) instead of evaluating against a document the engine would misread. Clears by itself when a subsequent emission validates.

    previewField: {
        (
            args: {
                field: EditableFieldEvaluation;
                mode?: EditMode;
                value?: unknown;
            },
        ): void;
        (args: { mode?: EditMode; target: EditFieldTarget; value?: unknown }): void;
    }

    Stage an optimistic preview of a field edit — the per-keystroke half of inline editing. The next WorkflowSession.evaluation projects against the held instance with previews applied (values + the advisory verdicts derived from them move instantly); stage, activity statuses, and history stay committed by construction. Never persisted: commit the value at a deliberate boundary (blur / Enter / gesture) via WorkflowSession.editField, which drops the target's previews when it settles (success lands the reloaded value, failure reverts).

    ready: boolean

    True once the session exists, every watched doc has synced, and the guard stream has resolved — so the first evaluation already has the guards in hand and an action rendered allowed cannot flip to mutation-guard-denied just because guards landed late. Stays true through a guardScope-only resubscription (the last-resolved guard list is held while the replacement query loads; consolidation churn is not a data event). Never true while WorkflowSession.invalid is set.

    tick: () => Promise<OperationResult>

    Advance the instance against the held content (commits via the engine).

    Settings

    Member Visibility

    On This Page

    Properties