dom-mutation/com.j0y.joy.dom.mutation/MutationAction

MutationAction

A write against state: a verb, an RFC 6901 path, and whatever the verb needs.

Most verbs accept a selector that narrows the write to elements of the array at path rather than the path's own slot — index for one position, or key + equals for every element whose field matches. field narrows once more, to a pointer inside each selected element. So increment /cart key=id equals=A field=/qty bumps the quantity of the cart line with that id, in one action and without spelling out its position.

Value slots hold templates: a literal, or a {"$event": "/pointer"} read into the fired interaction's payload, possibly nested inside a literal object or array.

Inheritors

Types

Increment

data class Increment(val path: String, val by: <Error class: unknown class>? = null, val index: <Error class: unknown class>? = null, val key: String? = null, val equals: <Error class: unknown class>? = null, val field: String? = null) : MutationAction

Add to a number; by defaults to 1 and may be negative. An absent target is treated as 0.

Insert

data class Insert(val path: String, val value: <Error class: unknown class>? = null, val values: List<<Error class: unknown class>>? = null, val index: <Error class: unknown class>? = null) : MutationAction

Add to an array — exactly one of value (a single element) or values (several). Appends by default; index inserts before that position, clamped to the length. An absent target becomes a new array.

Merge

data class Merge(val path: String, val value: <Error class: unknown class>, val index: <Error class: unknown class>? = null, val key: String? = null, val equals: <Error class: unknown class>? = null, val field: String? = null) : MutationAction

Shallow-merge an object: named keys overwritten, the rest untouched. An absent target is created.

Move

data class Move(val path: String, val from: <Error class: unknown class>, val to: <Error class: unknown class>) : MutationAction

Reorder within an array. Out-of-range from is a no-op; to is clamped to the length.

Remove

data class Remove(val path: String, val index: <Error class: unknown class>? = null, val key: String? = null, val equals: <Error class: unknown class>? = null) : MutationAction

Delete the slot at path, or every element a selector picks. Absence is a no-op.

Set

data class Set(val path: String, val to: <Error class: unknown class>, val index: <Error class: unknown class>? = null, val key: String? = null, val equals: <Error class: unknown class>? = null, val field: String? = null) : MutationAction

Write one value. Missing object parents along the path are created.

Toggle

data class Toggle(val path: String, val index: <Error class: unknown class>? = null, val key: String? = null, val equals: <Error class: unknown class>? = null, val field: String? = null) : MutationAction

Flip a boolean. An absent target is treated as false, so the first toggle writes true.

Update

data class Update(val path: String, val set: <Error class: unknown class>, val index: <Error class: unknown class>? = null, val key: String? = null, val equals: <Error class: unknown class>? = null) : MutationAction

Write the fields of set onto every selected element. A selector is required — this is the verb for "adjust the matching rows" — and a selector matching nothing is a no-op, never an error.

Upsert

data class Upsert(val path: String, val key: String, val value: <Error class: unknown class>, val onConflict: <Error class: unknown class>? = null) : MutationAction

"Add it, or adjust the one that is already there." An existing match is merged with onConflict, or replaced by value outright when no onConflict is given; no match appends value. value must carry the key field, since that is what identifies it.

Properties

path

abstract val path: String

The literal RFC 6901 pointer this verb writes at.

verb

abstract val verb: String

The verb name as authored — used to label errors.