Change Tracking

FdcDataSet tracks inserted, modified, and deleted records. This allows application code and adapters to work with changes rather than resending an entire dataset.

Record change states

A record can be:

State	Meaning
unchanged	No pending local change
inserted	Newly inserted and not yet accepted
modified	One or more values differ from accepted values
deleted	Marked for deletion

Normal application code rarely needs to manage these states directly. They are maintained by dataset edit operations.

Check for pending changes

if (dataSet.hasUpdates) {
  // Persistent inserts, updates, or deletes are pending.
}

hasUpdates reflects persistent changes. An edit limited to non-persistent or calculated fields does not make the dataset report persistent updates.

Inspect the change set

changeSet returns a fresh immutable snapshot:

final changes = dataSet.changeSet;

print(changes.inserts.length);
print(changes.updates.length);
print(changes.deletes.length);

Each entry includes:

• the dataset recordId used for result correlation;
• current values;
• originalValues;
• changedFields.

For most applications, adapters and dataset APIs consume this model internally. Reading it directly is useful for review screens, diagnostics, audit previews, or custom workflow UI.

Immediate updates are the default

The default update mode is:

FdcUpdateMode.immediate

With an adapter-backed dataset, post() and delete() commit the local operation and schedule persistence through the adapter.

Use dataset error and work callbacks to observe asynchronous persistence outcomes.

Cached updates

Choose cached updates when the user should make several changes and explicitly save or discard them as a group:

final dataSet = FdcDataSet(
  fields: fields,
  adapter: adapter,
  updateMode: FdcUpdateMode.cachedUpdates,
);

Edit normally:

dataSet.edit();
dataSet['company'] = 'Northstar Systems';
dataSet.post();

dataSet.append();
dataSet['company'] = 'BluePeak Logistics';
dataSet.post();

Then apply all persistent changes:

final result = await dataSet.applyUpdates();

Cancel cached updates

dataSet.cancelUpdates();

cancelUpdates() reverts unapplied cached inserts, edits, and deletes and rebuilds the active view from accepted record state.

This operation is different from cancel():

• cancel() discards the current active edit or insert buffer;
• cancelUpdates() reverts all unapplied cached changes.

Backend-confirmed values

When adapter apply succeeds, the dataset can merge backend-confirmed values into affected records. This matters for generated keys, server timestamps, normalized values, and other persistence-side results.

The adapter contract and apply result model are covered in the adapter documentation.

Persistence boundaries

A useful mental model is:

edit buffer
   ↓ post()
dataset tracked change
   ↓ applyUpdates() or immediate apply
adapter/storage

This separation allows the same editing UI model to support local data, immediate persistence, and explicit batch-save workflows.

Next: Data Binding