RFC: `withDirtyCheck`

[Hypercubed]

Motivation

Add a new feature called withDirtyCheck that allows developers to deeply monitor dirty state in complex data structures. Unlike shallow dirty checks, this feature will track changes in nested objects and arrays, making it easier to determine if any part of the state has been modified. Unlike Angular forms' isDirty state, this fetaure will determine dirtiness based on structural changes rather than user interactions.

Part 1: Deep Dirty Signals (TBR)

In addition to the withDirtyCheck feature, this RFC proposes a new utility called deepDirtySignal. This utility will provide a way to create signals that can deeply track dirty state in nested data structures.

Note: I have a PoC of this utility available.

Usage Example

const source = signal({
  id: 1,
  name: 'Test',
  details: {
    age: 30,
    address: {
      city: 'New York',
      zip: '10001',
    },
  },
});

const isDirty = deepDirtySignal(source);
console.log(isDirty()); // false

source.update((obj) => {
  return {
    ...obj,
    name: 'Updated Test',
  };
});

console.log(isDirty()); // true
console.log(isDirty.name()); // true
console.log(isDirty.details()); // false
console.log(isDirty.details.address()); // false

Pros of deepDirtySignal:

• provides a type-safe way to track dirty state in nested objects
• signals are created lazily, so only accessed paths are tracked
• signals internal caching optimizes performance by avoiding redundant computations

Cons of deepDirtySignal:

• complex implementation
• may not support complex types well (e.g., partials)

Alternative APIs considered

Instead of lazily creating signals for each path using the fluent API, we could eagerly create signals on initialization. For example, isNameDirty = deepDirtySignal(() => source().address) would eagerly create a dirty check signal for the address. It would dirty check based on structural changes to the address property but would not provide a way to dirty check nested properties.

Part 2: withDirtyCheck Feature

The withDirtyCheck feature will be implemented as a store feature that adds deep dirty checking to the store state. This feature will leverage the deepDirtySignal utility to provide a way to monitor dirty state in complex store states.

Proposed API

type BookSearchState = {
  books: Book[];
  isLoading: boolean;
  filter: { query: string; order: 'asc' | 'desc' };
};

const initialState: BookSearchState = {
  books: [],
  isLoading: false,
  filter: { query: '', order: 'asc' },
};

export const BooksStore = signalStore(
  withState(initialState),
  withDirtyCheck(), // <-- Adds deep dirty checking as `isDirty`
);

const booksStore = inject(BooksStore);
const enableSaveButton = computed(() => !booksStore.isLoading() && booksStore.isDirty.books());

Alternatives considered

Instead of adding store wide dirty checking, the withDirtyCheck feature could create dirty check signals only for specific slices of state. For example, withDirtyCheck({ isNameDirty: (state) => state().books }) would only create dirty check signals for the books slice of state.

This may be equivalant to using deepDirtySignal within a withComputed store feature.

export const BooksStore = signalStore(
  withState(initialState),
  withComputed(({ books }) => ({
    isBooksDirty: deepDirtySignal(() => books()),
  }))
);

[rainerhahnekamp]

Hey, thanks for the RFC but please help me understanding its use case. You see dirty as something which is true, once a Signal's value is different than the original?

[Hypercubed]

Yes... exactly that. In angular forms, and (at least so far) in signal forms, dirty means a control has been modified. Even if the value is later return to the original value it is still "dirty" as far as FormControls are concerned. With this proposal the value would be "dirty" if it is different (deeply unequal) from the original value. The signal would return to false if the values return to the original.

I can see this playing nicely with withReset. resetState will only have an effect if isDirty is true.

The proposal in part 1 also has the benefit that a developer could check the dirty state of any part of the state tree.

[rainerhahnekamp]

Have you thought about something like this: https://stackblitz.com/edit/github-epr3fasx?file=src%2Fmain.ts

function isDirty<T>(value: Signal<T>) {
  return linkedSignal<T, boolean>({
    source: value,
    computation: (_, previous) => {
      if (previous === undefined) {
        return false;
      }
      return true;
    },
  }).asReadonly();
}

@Component({
  selector: 'app-root',
  template: `<h3>isDirty {{dirtyState()}}</h3><button (click)="changeState()">Change State</button>`,
})
export class App {
  state = signal({
    books: [],
    isLoading: false,
    counter: 1,
    filter: { query: '', order: 'asc' },
  });

  dirtyState = isDirty(this.state);

  changeState() {
    this.state.update((value) => ({ ...value, counter: value.counter + 1 }));
  }
}

[Hypercubed]

Unless I am misunderstaning, this linked signal becomes "dirty" if it has changed and then never becomes clean. What I am proposing is checking the state vs the initial value (not previous). If the state changes to something else then back, so that it is deeply equal to the original (like Lodash's isEqual), then it is considered not dirty (clean or prestine).

An example use case include using it with ngrx-toolkit's withReset. withReset's resetState will have no visible effect if the state is deeply equal to the original state. The state could have changes but was later changed back. If you want to indicate to a user that "reset" will have some effect you need to test for deep structural equality.

[rainerhahnekamp]

Got it, then it should be even easier:

function isDirty<T>(value: Signal<T>) {
  const initialValue = value();
  return computed(() => value() !== initialValue)
}

To me the question is, if it would provide enough benefit to be a feature on its own.

[Hypercubed]

Not eactly... that only works for premitives; the main goal here is checking the dirtiness of the store state object. Here is a simple version that works as I expect using fast-deep-equals:

export function isDirty<T>(value: () => T): Signal<boolean> {
  const snapshot = untracked(computation);
  return computed(() => !fastDeepEqual(computation(), snapshot));
}

fastDeepEqual returns true if the values are strictly equal (===) OR deeply structurally equal. Node also as util.isDeepStrictEqual().

That, by itself, may be somewhat useful, but hardly worth addition to ngrx-toolkit. The intinteseting peice, IMO, is being able to not just ask if the current store state is dirty but if any slice of the state is dirty.

My original RFC was proposing a fluent API for checking dirtiness of the store state... for example:

store.isDirty() // <!-- tests if the current store state is deeply equal to the inital value
store.isDirty.books() // <!-- tests if the current state.books array is deeply equal to the inital value
store.isDirty.filter.query() // <!-- tests if the current state.filter.query string is equal to the inital value

[rainerhahnekamp]

I still don't understand the use cases. When would you need that? We have deep signals and when we want to be notified by a Signal change, we should rely on the existing functions.

[Hypercubed]

Hi @rainerhahnekamp I'm sorry I am doing an bad job explaining. Here is a SatckBlitz of one use case https://stackblitz.com/edit/stackblitz-starters-5skjkfku?file=src%2Fmain.ts

Here you will see that there are two field sets. If any of the inputs in a field set is changed the fieldset's outline changes color indicating that a value within the field sets is dirty. If you then manually change the input back to the original value the outline changes back. This is different from the way dirty works in Angular forms in that formControls become dirty when changed and do not return to prestine when modified back to the original value (i'd argue that dirty in Angular forms is very close to touched).

You will see in this example I have also included withReset from @angular-architects/ngrx-toolkit. This is triggered by the Reset button. The Reset button is only enabled if the state/form is dirty. Again this is different from Angular forms that treat "dirty" as touched.

This RFC proposes a withDirtyCheck feature that would enable users to easily create dirty signals (as I've done in the component lines 76-78) and provide a reset (as shown in the markAsPrestine method, lines 80-85).

[Hypercubed]

Here is a stackblitz showing the withDirtyCheck feature: https://stackblitz.com/edit/stackblitz-starters-hswkwmwf?file=src%2Fstore.ts

[michael-small]

I've been experimenting with the withDirtyCheck and I think it is a cool concept. As it is now seems to be a concrete way of providing this functionality at the top level for dirty/pristine of the store and then per piece of state. I made another layer of nesting than the example by doing s.address.city and it predictably applied. And I could see potential use cases for this for some people.

Implementation wise: I haven't looked at the code as thorough as if this were a PR, but it seems evident and not as tricky as I assumed at first. Other than the weight pulled by pulling in import { circularDeepEqual } from 'fast-equals', it seems evident in what the implementation is doing. If we added something, I am not sure what Rainer's/Manfred's take on adding a dependency would be, so in that respect, I defer to them if this spins into a full feature.

I just have a few concerns, mostly about overlap with existing concepts of forms

1. Broader interest to add this to the API surface. Personally, I think this is cool. However, adjacent to my second point...
2. Potential confusion/overlap with forms. The dirty/pristine made sense immediately to me, but:
   • The slight nuance that this is not technically a form, when this is tied heavily to form language. Especially as form behavior in the Angular signals ecosystem is currently being hashed out in the open with the current state of signals, and form assumptions vs the ongoing experimental signal forms stage.
   • The behavior of state reset and dirty/pristine of withDirtyCheck considering reset state itself to once again be pristine, vs forms not becoming pristine just due to state reset alone. I am used to the form behavior and it makes more sense to me, but I can see the argument for reset state under withDirtyCheck becoming pristine.
   • Overall, the dirty/pristine naming of this proposed feature makes sense for the most part, and if it were renamed to not be in the same headspace as form dirty/pristine, then I'm not sure what an alternative could be which is nearly as precise.

Overall, I can see the usecase for this feature and it looks straightforward, but I am just concerned with some overlap with existing form concepts.

[Hypercubed]

@michael-small Thank you for your feedback on this. I've had some of the same concerns. Specifically:

• I tried to eliminate the dependency on fast-equals by using nested signals. But the performance was not good. It would not be that hard to implement our own version of fast-equals, but it would basically do the same.

• I'm also concerned with using the same nomenclature as forms. I've been considering using changed and/or unchanged instead. A little concerned that this doesn't explicitly suggest structurally identical as opposed to touched/untouched.

[michael-small]

Personally I wouldn't be opposed if we just pulled that fast-equals part of the source in, considering that library is MIT. From a casual perusing of the function's source, I think that would be viable. I'll defer to the others, like @rainerhahnekamp if that is a sound idea or not.

As for naming, I have been weighing that in the meantime since you responded. I agree that changed/unchanged is a decent contender but it does lack the structural aspect. I have some half baked alternative idea that I'll drop when they are worth throwing in, or if more interest/work solidifies around considering this as a feature, whatever may come first.

[Hypercubed]

@rainerhahnekamp Any additional thoughts on this? I havea working implementation and could publish it on my own... but think it could make a nice addition to ngrx-toolkit.

[rainerhahnekamp]

I've thought about this more, and I'm still uncertain whether this belongs in ngrx-toolkit. My concern is that it feels misplaced to add a feature specifically for performing value equality checks on state objects.

Angular's Signal API already provides the ability to pass a custom equal function. Perhaps we should focus on enabling support for this native capability instead. This would allow you to use deepEqual or any other comparison function that suits your needs.

If this approach seems viable, I'd suggest the first step is to propose adding this functionality to SignalStore itself, making it more of a question for the @ngrx/signals team rather than ngrx-toolkit.

That would mean that withState gets somehow the possibility to accept equal like https://angular.dev/api/core/CreateSignalOptions

What are your thoughts on this direction?