Merge pull request #363 from hjotha/submit/change-object-refresh-modifier

feat: preserve change object refresh modifier

Author: ako

.claude/skills/mendix/write-microflows.md

@@ -378,6 +378,9 @@ $NewProduct = create Test.Product (
 change $Product (
   Name = $NewName,
   ModifiedDate = [%CurrentDateTime%]);
+
+-- Refresh the changed object in the client
+change $Product (Name = $NewName) refresh;
 ```
 
 **Note**: Only specify attributes you want to change. Syntax aligned with CREATE.

docs/01-project/MDL_QUICK_REFERENCE.md

@@ -218,7 +218,7 @@ authentication basic, session
 | List declaration | `declare $list list of Module.Entity = empty;` | |
 | Assignment | `set $Var = expression;` | Variable must be declared first |
 | Create object | `$Var = create Module.Entity (attr = value);` | |
-| Change object | `change $entity (attr = value);` | |
+| Change object | `change $entity (attr = value) [refresh];` | `refresh` updates the changed object in the client |
 | Commit | `commit $entity [with events] [refresh];` | |
 | Delete | `delete $entity;` | |
 | Rollback | `rollback $entity [refresh];` | Reverts uncommitted changes |

docs/11-proposals/PROPOSAL_microflow_change_refresh_modifier.md

@@ -0,0 +1,28 @@
+# Proposal: Microflow CHANGE Refresh Modifier
+
+Status: Draft
+
+## Summary
+
+Allow `change` microflow statements to explicitly preserve the Mendix `RefreshInClient` flag:
+
+```mdl
+change $Customer (Name = 'Jane') refresh;
+change $Customer refresh;
+```
+
+## Motivation
+
+Mendix change-object actions can refresh the changed object in the client independently from committing the object. MDL previously had no syntax for that flag, so a describe/exec round-trip could rewrite `RefreshInClient = true` to `false` for change actions with member assignments.
+
+## Semantics
+
+The `refresh` modifier maps directly to `ChangeObjectAction.RefreshInClient`. Omitting it preserves the existing default behavior. The modifier is accepted both with member assignments and on a memberless change action.
+
+## Tests And Examples
+
+`mdl-examples/doctype-tests/change_refresh_modifier.test.mdl` demonstrates both forms. Go tests cover formatter output, parser behavior, and builder serialization.
+
+## Open Questions
+
+- Should a memberless `change $Object;` continue to infer refresh in separate validity-focused fixes, or should the explicit `refresh` modifier be the only authoring form?

docs/11-proposals/README.md

@@ -49,6 +49,7 @@ BSON schema Registry ◄──── multi-version Support
 | [Page Styling Support](page-styling-support.md) | Partial | CSS classes, inline styles, dynamic classes, design properties. Phase 1 (Class/Style) done | — |
 | [Page Composition](proposal_page_composition.md) | Proposed | Fragment definitions and ALTER PAGE for partial page editing | Page Syntax V2, Page Styling |
 | [XPath Gaps](xpath-gaps-proposal.md) | Partial | XPath constraint support gap analysis. ~85% complete, association paths and nested predicates remain | — |
+| [Microflow CHANGE Refresh Modifier](PROPOSAL_microflow_change_refresh_modifier.md) | Draft | Preserve `RefreshInClient` on change-object actions | — |
 | [LLM MDL Assistance](PROPOSAL_llm_mdl_assistance.md) | Proposed | Enhanced error messages with examples, reorganized skills by use case | — |
 
 ### Testing & Evaluation

mdl-examples/doctype-tests/change_refresh_modifier.test.mdl

@@ -0,0 +1,17 @@
+create module ChangeRefreshExample;
+
+create persistent entity ChangeRefreshExample.Customer (
+  Name: string
+);
+/
+
+create microflow ChangeRefreshExample.RefreshChangedCustomer (
+  $Customer: ChangeRefreshExample.Customer
+)
+returns boolean
+begin
+  change $Customer (Name = 'Jane') refresh;
+  change $Customer refresh;
+  return true;
+end;
+/

mdl/ast/ast_microflow.go

@@ -192,9 +192,10 @@ func (s *CreateObjectStmt) isMicroflowStatement() {}
 
 // ChangeObjectStmt represents: CHANGE $Var (assignments)
 type ChangeObjectStmt struct {
-	Variable    string               // Variable name
-	Changes     []ChangeItem         // SET assignments
-	Annotations *ActivityAnnotations // Optional @position, @caption, @color, @annotation
+	Variable        string               // Variable name
+	Changes         []ChangeItem         // SET assignments
+	RefreshInClient bool                 // Whether to refresh in client
+	Annotations     *ActivityAnnotations // Optional @position, @caption, @color, @annotation
 }
 
 func (s *ChangeObjectStmt) isMicroflowStatement() {}

mdl/executor/cmd_microflows_builder_actions.go

@@ -239,14 +239,13 @@ func (fb *flowBuilder) addRollbackAction(s *ast.RollbackStmt) model.ID {
 
 // addChangeObjectAction creates a CHANGE statement.
 func (fb *flowBuilder) addChangeObjectAction(s *ast.ChangeObjectStmt) model.ID {
+	// Empty non-committing changes need RefreshInClient to satisfy Studio Pro
+	// consistency checks; explicit `refresh` keeps the same flag for all changes.
 	action := &microflows.ChangeObjectAction{
-		BaseElement:    model.BaseElement{ID: model.ID(types.GenerateID())},
-		ChangeVariable: s.Variable,
-		Commit:         microflows.CommitTypeNo,
-		// Studio Pro rejects an empty non-committing change action unless it
-		// refreshes in client. The CE0032 message mentions only items/commit,
-		// but mx check accepts RefreshInClient=true as the third valid escape.
-		RefreshInClient: len(s.Changes) == 0,
+		BaseElement:     model.BaseElement{ID: model.ID(types.GenerateID())},
+		ChangeVariable:  s.Variable,
+		Commit:          microflows.CommitTypeNo,
+		RefreshInClient: s.RefreshInClient || len(s.Changes) == 0,
 	}
 
 	// Look up entity type from variable scope

mdl/executor/cmd_microflows_builder_change_refresh_test.go

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+)
+
+func TestChangeObjectBuilderWritesRefreshInClient(t *testing.T) {
+	fb := &flowBuilder{}
+
+	fb.addChangeObjectAction(&ast.ChangeObjectStmt{
+		Variable:        "Customer",
+		RefreshInClient: true,
+		Changes: []ast.ChangeItem{
+			{Attribute: "Name", Value: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "Jane"}},
+		},
+	})
+
+	action := lastChangeObjectAction(t, fb)
+	if !action.RefreshInClient {
+		t.Fatal("Expected builder to write RefreshInClient")
+	}
+}
+
+func lastChangeObjectAction(t *testing.T, fb *flowBuilder) *microflows.ChangeObjectAction {
+	t.Helper()
+
+	if len(fb.objects) == 0 {
+		t.Fatal("Expected builder to create an action activity")
+	}
+	activity, ok := fb.objects[len(fb.objects)-1].(*microflows.ActionActivity)
+	if !ok {
+		t.Fatalf("Last object = %T, want ActionActivity", fb.objects[len(fb.objects)-1])
+	}
+	action, ok := activity.Action.(*microflows.ChangeObjectAction)
+	if !ok {
+		t.Fatalf("Action = %T, want ChangeObjectAction", activity.Action)
+	}
+	return action
+}

mdl/executor/cmd_microflows_format_action.go

@@ -241,8 +241,14 @@ func formatAction(
 				}
 				members = append(members, fmt.Sprintf("%s = %s", memberName, escapeExpressionValue(m.Value)))
 			}
+			if a.RefreshInClient {
+				return fmt.Sprintf("change $%s (%s) refresh;", varName, strings.Join(members, ", "))
+			}
 			return fmt.Sprintf("change $%s (%s);", varName, strings.Join(members, ", "))
 		}
+		if a.RefreshInClient {
+			return fmt.Sprintf("change $%s refresh;", varName)
+		}
 		return fmt.Sprintf("change $%s;", varName)
 
 	case *microflows.CommitObjectsAction:

mdl/executor/cmd_microflows_format_action_test.go

@@ -96,6 +96,30 @@ func TestFormatAction_ChangeObject_NoChanges(t *testing.T) {
 	}
 }
 
+func TestFormatAction_ChangeObject_WithRefresh(t *testing.T) {
+	e := newTestExecutor()
+	action := &microflows.ChangeObjectAction{
+		ChangeVariable:  "Customer",
+		RefreshInClient: true,
+		Changes: []*microflows.MemberChange{
+			{AttributeQualifiedName: "MyModule.Customer.Name", Value: "'Jane'"},
+		},
+	}
+	got := e.formatAction(action, nil, nil)
+	if got != "change $Customer (Name = 'Jane') refresh;" {
+		t.Errorf("got %q", got)
+	}
+}
+
+func TestFormatAction_ChangeObject_NoChangesWithRefresh(t *testing.T) {
+	e := newTestExecutor()
+	action := &microflows.ChangeObjectAction{ChangeVariable: "Obj", RefreshInClient: true}
+	got := e.formatAction(action, nil, nil)
+	if got != "change $Obj refresh;" {
+		t.Errorf("got %q", got)
+	}
+}
+
 func TestFormatAction_DeleteObject(t *testing.T) {
 	e := newTestExecutor()
 	action := &microflows.DeleteObjectAction{DeleteVariable: "Customer"}