struct

Change::Changeset(T, U)

Inherits Struct < Value < Object

T is the type of the stored instance, inferrable from initialize. U is a union of the type of all managed fields on that instance. U does not need to (and generally should not) include Nil in the union, it will automatically be added where needed.

Constructors

new(instance : T)

Create a new changeset using instance as the base for defining changes.

Instance methods

add_error(field : String, message : String) : self

Add an error to this changeset. field is the field that the error applies to, and message is a description about the error. Errors will be coerced into a ChangesetError object.

Calling this method also implicitly marks this Changeset as invalid.

apply_changes(inst : T) : T

Like apply_changes/0, but instead applying the changes to the given instance.

apply_changes

Assign each changed value from this changeset onto the instance owned by this Changeset (in the instance property). Returns the updated instance directly.

This is considered a safe operation, as only validated changes are stored in the changeset.

cast(props, permitted : Array) : self

For each field in permitted, attempt to cast the value from props into the type of the corresponding field on the model.

If any field cannot be casted successfully, the changeset is marked as invalid, but all remaining casts will still be attempted.

nil is always permitted in casts.

changed?

Returns true if any field in this changeset has been marked as changed.

changes_hash

Returns a hash of changes currently stored in this changeset, including fields that have been changed to nil. Fields without changes are not included in this hash, meaning a changeset with no changes will return an empty hash.

each_change

Calls the given block once for every accepted change currently in the changeset. The block is passed the name of the changed field and its accepted value as arguments. Fields that have not been changed will not be yielded to the block.

If the changeset has no accepted changes, the block will not be called.

each_field

Calls the given block once for every field in the changeset, including fields that have not been changed. Fields with accepted changes will yield the changed value, while fields without changes will yield the value from the stored instance.

The block will always be called for every field managed by the changeset.

errors

errors=(errors : Array(ChangesetError))

get_change(field : String, default = nil) : U | Nil

Return the stored change for the given field from this changeset, or default if the field has not been changed.

Even if the value of the change is nil, as long as the field has been marked as changed, that value will be returned instead of default.

get_field(field : String, default = nil) : U | Nil

Similar to get_change but if no change is present, this method first checks the stored instance for a defined value, and only returns default if the instance's existing value is nil.

has_field?(field : String) : Bool

Returns true if field is a valid field name in this changeset.

instance

instance=(instance : T)

valid=(valid : Bool)

valid?

validate_required(field : String | Symbol) : self

Validates that the given field is present in this Changeset, either as a change, or as an existing value on the stored instance. Presence is defined as anything other than a value of nil.

If the field is not present, an error is added and the changeset is marked as invalid.

If the field is not a valid field for this changeset, it is ignored.

validate_required(fields : Array(String) | Array(Symbol)) : self

Validate the multiple fields are present in the Changeset. See validate_required(String) for more information.