DEV Community: Miha Mulec

Fun-grained Reactivity in Angular: Part 4 - NestedSignals()()

Miha Mulec — Mon, 26 May 2025 11:16:43 +0000

Hey everyone, been a while! :) This one will be short & hopefuly sweet. I'll be assuming a decent familiarity with Angular's change detection mechanics, so before we get into it, here's a great refresher on the topic, in case it's been a while ;)

Keeping it clean

As we all now know, change detection in angular refers to three operations. The first will mark various components as dirty & needing a check, the second checks the state for differences & the third calls the renderer to update the DOM where necessary. While these operations are highly performant, we'd still like to avoid operations, if they aren't required.

We've had the onPush strategy to solve parts of this for quite a while, and since Angular v18 we've had the new signal scheduler that skips quite a few operations when we only use signals, only marking parent as HasChildViewToRefresh instead of as dirty when a signal within a child component changes.

There are of course exceptions to this, for example unless we use the new ZonelessChangeDetection a button click will still mark all parent components as dirty. For the sake of this article, we will ignore these cases, as in my opinion this is a temporary state, which will get further optimized in the future as Angular slowly transitions towards a fully signal based future, we're seeing some of that with v20 marking zone.js as an optional peer dependency already & I can't wait to see what's comming down the pipe in the future :D!

Anyway let's get right into it.

In it

@Component({
  ...
})
export class ExampleComponent {
  protected readonly count = signal(0);

  protected inc() {
    this.count.update((cur) => cur++);
  }
}

So a component, like the one above (in a zoneless environment) really only triggers change detection for itself. Parents & it's children will not be checked...unless we add inputs into the mix.

@Component({
  ...
  template: `<app-example-child [count]="count()" />` // marks child as dirty on trigger
})
export class ExampleComponent {
  protected readonly count = model(0); // doesn't mark parents as dirty as it assumes that they already are

  protected inc() {
    this.count.update((cur) => cur++);
  }
}

This simple example wouldn't cause any issues, of course. But as we all know, any decently sized app will be passing around tons of state, lots of times several levels deep. More often than not, changes to that state unecessarily trigger intermediary components, as the changes really only apply to children. A common pattern to mitigate this is to externalize state into an injectable store. This prevents marking intermediary components as dirty, since we are no longer passing state through them.

@Injectable()
export class CountStore {
  readonly count = signal(0);

  inc() {
    this.count.update((cur) => cur++);
  }
}

@Component({
  ...
  template: `<app-example-child [count]="store.count()" />`
})
export class ExampleComponent {
  protected readonly store = inject(CountStore);
}

This pattern, while very useful, does however have some drawbacks. It adds complexity for re-use & decreases flexibility vs just an input. I won't get into it too much here, we all know that we have lots of examples of components in our apps where we've chosen not to do this for various reasons & have rather passed state through layers of inputs...so how do we square this circle, getting the perf. increase with inputs alone.

Well what we've started to use to "solve" this is use nested signals. There's a few variations on this pattern, but it all boils down to the same thing. Angular's change detector will only check for referential equality on inputs, if the object/function reference doesn't change it moves on. Since signals are really just a function/object this applies to them as well :) So if we pass a signal to a signal input, & use it in the template, we can rely that it will only "trigger" the components it's used in.

@Component({
  ...
  template: `{{count()()}}` // only this component re-renders
})
export class ExampleChildComponent {
  protected readonly count = input.required<Signal<number>>();

  protected inc() {
    this.count.update((cur) => cur++);
  }
}

@Component({
  ...
  template: `<app-example-child [count]="count" />`
})
export class ExampleComponent {
  protected readonly count = signal(0);

  protected inc() {
    this.count.update((cur) => cur++);
  }
}

In fact & I'm not sure exactly when this happened, but testing in v19, only the part of the template that uses the signal is actually re-rendered. So if we're calling the signal in say a span, only that span gets re-rendered. I wouldn't count on this just yet, but for sure it is the future of any signal based framework (SolidJS's renderer already works like this for example).

I'll fully admit that the double signal call "looks weird" though :) So another option is just wrapping it in an object, that doesn't really change. BTW this is how @mmstack/forms work :)


type CountState = {
  count: Signal<number>;
}

@Component({
  ...
  template: `{{state().count()}}`
})
export class ExampleChildComponent {
  protected readonly state = input.required<CountState>();

  protected inc() {
    this.count.update((cur) => cur++);
  }
}

@Component({
  ...
  template: `<app-example-child [state]="state" />`
})
export class ExampleComponent {
  protected readonly state = {
    count: signal(0)
  };

  protected inc() {
    this.count.update((cur) => cur++);
  }
}

A side benefit this provides is it allows us to use mutable signals. A problem those have is that angular checks referential equality of the value, since we're mutating those values in-line they never "update" the input.

import { mutable } from '@mmstack/primitives'

@Component({
  ...
  template: `
    <app-example-child [state]="state" /> // will update the content every time the signal value mutates
    <app-other-child [state]="state()" /> // never triggers

  `
})
export class ExampleComponent {
  protected readonly state = mutable({
    count: 0
  });


  protected inc() {
    this.state.mutate((cur) => {
      cur.count++;
      return cur;
    })
  }
}

Arrays

Finally, we should talk about arrays, the patterns above can be relatively easily implemented for a single object state, but arrays require some "work". Usually we'll get some array data from a server & just render it out to a list/table with one or more @for loops. While this is fine & Angular does some extra magic for us via the track method, more or less we will be re-rendering the entire list any time something changes.

What we'd want instead of an array of objects then is an array of signals of those objects. One that keeps the signals themselves stable, but updates their values as needed. Even better if we can keep existing signals through a lenght change. Luckily, with Angular's new linkedSignal we can make that pretty easily :)


type Note = {
  id: string;
  content: string;
}

const notes = signal<Note[]>([
  ...
]);

const length = computed(() => notes().length); // stabalize length

const noteContents = linkedSignal({
  source: () => length(),
  computation: (length, prev) => ({
    if (!prev) return Array.from({length}, (_, i) => computed(() => notes()[i].content));

    if (length === prev.value.length) return prev.value;

    if (length < prev.value.length>) {
      return prev.value.slice(0, length); // returns a new instance of the array as we want to notify angular of the "structure" changing as well
    } else {
      const next = [...prev.value]; // returns a new instance of the array as we want to notify angular of the "structure" changing as well
      for (let i = prev.value.length; i < length; i++) {
        next[i] = computed(() => notes()[i].content);
      }

      return next;
    }
  }),
  equal: (a, b) => a.length === b.length // not really necessary, but doesn't hurt :)
})

@Component({
  ...
  template: `{{content()()}}`
})
export class NoteContentComponent {
  readonly content = input.required<Signal<string>>();
}

@Component({
  ...
  template: `
    // we can simply track the signal's reference as it doesn't change. Or we could add an id param to the signal object if we want to be explicit
    @for (contentSig of noteContents(); track contentSig) {
      <app-note-content [content]="contentSig" />
    }
  `
})

As you can see, by both stabilizing the array & passing the signals through, only the parts of the UI that are bound to those content signals will update when those signals trigger. The rest stays stable. This allows us to really dial in performance for large tables/lists where we most need it. If you'd like a more generic version of what we did above @mmstack/primitives exposes a helper for it called mapArray. Which transforms a T[] into a Signal[] & then provides a map function so you can further transform it as needed :) Here's the code for that if you're curious mapArray.ts;

Outro

We'll that's about all I have for you this time :) I'm currently working on a datatable component using these methods to provide the best possible render performance. I'll hopefuly be launching it soon so look out for any posts about an @mmstack/table-x set of libraries in the future. Happy coding! 🚀

Fun-grained reactivity in Angular: Part 3 - Resources

Miha Mulec — Wed, 19 Mar 2025 11:23:16 +0000

Update: I've released a "spruced up" version of the primitives outlined bellow, I hope you find them useful :)

@mmstack/resource

In previous installments of this series, we explored building foundational signal-based primitives such (mutable, store, derived) and applied them to create reactive form controls. This time, we turn our attention to another critical aspect of modern web applications: client-side management of asynchronous data. Don't worry though we'll get to server-side (featuring Analog) soon enough! ;)

Why...just why?

Angular has long offered quite a robust suite of tools to manage HTTP communication/async state. Built in tools such as HttpClient, the AsyncPipe, interceptors etc. have allowed us to build very advanced & robust features throughout the years. But it seems times are shifting.

Angular is evolving these primitives with signal based alternatives such as httpResource, which allow us to better hook in to our new 'fine-grained' state, and honestly it's about time! RxJs Observables have long been something that most people need time to wrap their heads around & recently HttpClient has been the source of most (if not all) Observables in high-level parts of our codebase. Likewise the typical pattern of having a Service class whose function returns an Observable, which completes when the request finishes/errors, has always been slightly off to me...it makes sense for socket like subscriptions, but not for one-and-done requests. It's why I, personally, welcome all the new signal based primitives, such as httpResource, hopefuly they make our lives easier & our codebases more sane.

There are however...one or two more things to think about with our new reality as of Angular 19.2...httpResource isn't really meant for mutating server side data through say PATCH requests, you can do it, but what signal should you react to & how do you begin to set things up.

Likewise there is a bit of additional logic we tend to need in our modern client side applications, such as retry-ing on error, caching, request deduplication & more, it's one of the many reasons I and, (I assume) a lot of you have reached for libraries such as Tanstack Query's new Angular adapter. In fact, in v18 we replaced quite a decent chunk of our own http logic with Tanstack Query & we're very mostly loved the results :), so if you're looking for a battle tested library to handle these things for you, I'd say look no further, add the library & get back to coding feature's you're clients will love.

If, however, you want to join me on another deep dive, to build, understand, and control...keep reading! :)

Goals

Before we begin let's outline our feature goals, so that we can understand what we want to accomplish today & if we've actually done so. Here's my list, I hope it satisfies yours as well:

Utilize built-in Angular primitives such as httpResource under the hood, ensuring (as much as possible) we remain in-sync with the current vision of the Angular team.
Use signal-based primitives & computeds on the state itself, ensuring the reactive graph is maintained.
Keep the core interface similar to built-in primitives such as httpResource.
Provide a simple onError callback for handling errors and displaying notifications (e.g., using Angular Material's snackbar).
Add persistence to data between refreshes; httpResource and other such primitives set their values to undefined when refreshing.
Make refreshing on intervals and retrying on errors easy.
Add circuit breaker options so that APIs under a lot of pressure aren't overloaded.
Add cache and prefetch options, similar in behavior to TanStack Query (staleTime + ttl (time-to-live)). Stale data should be shown but immediately refreshed. Multiple resources connected to the same cache entry should reflect updates to that entry.
Allow for flexible mutations, with built-in support for optimistic updates.
Deduplicate requests that are in-flight to ensure more consistent behavior. - bonus

Keep in mind that the async part of signals is currently changing very quickly, with Angular sure to add new resource primitive & SolidJs exploring brand new ideas like createAsync, it's definitely an interesting time to be in the JS ecosystem. We'll keep an eye out on all of them & come up with new additions together as things evolve.

Alrighty, I think that should be more than enough for modern applications...Let's get started building our new primitives 1 step at a time, adding each feature to them as we go.

The "easy" stuff

Let's get a few quick and easy things out of the way, namely defining the base interface/types & adding retry, refetch, onError & value persistance. I've opted to define the interface of many if not all helper functions to take in the resource & return a new object with modified props so that we can more easily reason about what each helper is doing. Feel free to refactor the code if you prefer it all to live in one function. I've also split it up into multiple files/code snippets to again improve readability as much as possible.

// refresh.ts
import { HttpResourceRef } from '@angular/common/http';
import { DestroyRef } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { interval } from 'rxjs';

// refresh resource every n miliseconds or don't refresh if undefined provided. 0 also excluded, due to it not being a valid usecase
export function refresh<T>(resource: HttpResourceRef<T>, destroyRef: DestroyRef, refresh?: number): HttpResourceRef<T> {
  if (!refresh) return resource; // no refresh requested

  // we can use RxJs here as reloading the resource will always be a side effect & as such does not impact the reactive graph in any way.
  let sub = interval(refresh)
    .pipe(takeUntilDestroyed(destroyRef))
    .subscribe(() => resource.reload());

  let reload = (): boolean => {
    sub.unsubscribe(); // do not conflict with manual reload

    const hasReloaded = resource.reload();

    // resubscribe after manual reload
    sub = interval(refresh)
      .pipe(takeUntilDestroyed(destroyRef))
      .subscribe(() => resource.reload());

    return hasReloaded;
  };

  return {
    ...resource,
    reload,
    destroy: () => {
      sub.unsubscribe();
      resource.destroy();
    },
  };
}

// retry-on-error.ts
import { type HttpResourceRef } from '@angular/common/http';
import { effect, ResourceStatus } from '@angular/core';

export type RetryOptions =
  | number
  | {
      max?: number;
      backoff?: number;
    };

// Retry on error, if number is provided it will retry that many times with exponential backoff, otherwise it will use the options provided
export function retryOnError<T>(res: HttpResourceRef<T>, opt?: RetryOptions): HttpResourceRef<T> {
  const max = opt ? (typeof opt === 'number' ? opt : (opt.max ?? 0)) : 0;
  const backoff = typeof opt === 'object' ? (opt.backoff ?? 1000) : 1000;

  let retries = 0;

  let timeout: ReturnType<typeof setTimeout> | undefined;

  const onError = () => {
    if (retries >= max) return;
    retries++;

    if (timeout) clearTimeout(timeout);

    setTimeout(() => res.reload(), retries <= 0 ? 0 : backoff * Math.pow(2, retries - 1));
  };

  const onSuccess = () => {
    if (timeout) clearTimeout(timeout);
    retries = 0;
  };

  // same as refresh this can again be a simple side effect
  const ref = effect(() => {
    switch (res.status()) {
      case ResourceStatus.Error:
        return onError();
      case ResourceStatus.Resolved:
        return onSuccess();
    }
  });

  return {
    ...res,
    destroy: () => {
      ref.destroy(); // cleanup on manual destroy
      res.destroy();
    },
  };
}

// persist-values.ts
import { type HttpHeaders, type HttpResourceRef } from '@angular/common/http';
import { linkedSignal, type Signal, type ValueEqualityFn, type WritableSignal } from '@angular/core';

function presist<T>(value: WritableSignal<T>, usePrevious: Signal<boolean>, equal?: ValueEqualityFn<T>): WritableSignal<T>;

function presist<T>(value: Signal<T>, usePrevious: Signal<boolean>, equal?: ValueEqualityFn<T>): Signal<T>;

function presist<T>(value: WritableSignal<T> | Signal<T>, usePrevious: Signal<boolean>, equal?: ValueEqualityFn<T>): WritableSignal<T> | Signal<T> {
  // linkedSignal allows us to access previous source value
  const persisted = linkedSignal<
    {
      value: T;
      usePrevious: boolean;
    },
    T
  >({
    source: () => ({
      value: value(),
      usePrevious: usePrevious(),
    }),
    computation: (source, prev) => {
      if (source.usePrevious && prev) return prev.value;

      return source.value;
    },
    equal,
  });

  // if original value was WritableSignal then override linkedSignal methods to original...angular uses linkedSignal under the hood in ResourceImpl, this applies to that.
  if ('set' in value) {
    persisted.set = value.set;
    persisted.update = value.update;
    persisted.asReadonly = value.asReadonly;
  }

  return persisted;
}

export function persistResourceValues<T>(resource: HttpResourceRef<T>, persist = false, equal?: ValueEqualityFn<T>): HttpResourceRef<T> {
  if (!persist) return resource;

  return {
    ...resource,
    statusCode: presist<number | undefined>(resource.statusCode, resource.isLoading),
    headers: presist<HttpHeaders | undefined>(resource.headers, resource.isLoading),
    value: presist<T>(resource.value, resource.isLoading, equal),
  };
}

// extended-resource.ts
import { httpResource, type HttpResourceOptions, type HttpResourceRef, type HttpResourceRequest } from '@angular/common/http';
import { computed, DestroyRef, effect, inject } from '@angular/core';
import { createEqualRequest } from './equal-request';
import { persistResourceValues } from './persist-values';
import { refresh } from './refresh';
import { retryOnError, type RetryOptions } from './retry-on-error';

export type ExtendResourceOptions<TResult, TRaw = TResult> = HttpResourceOptions<TResult, TRaw> & {
  keepPrevious?: boolean; // Keep the previous value when refreshing
  refresh?: number; // Refresh the value every n milliseconds
  retry?: RetryOptions; // Retry on error options
  onError?: (err: unknown) => void; // Error handler, useful for say displaying a toast
};

export type ExtendedResourceRef<TResult> = HttpResourceRef<TResult>;

export function extendedResource<TResult, TRaw = TResult>(
  request: () => HttpResourceRequest | undefined,
  options: ExtendResourceOptions<TResult, TRaw> & {
    defaultValue: NoInfer<TResult>;
  },
): ExtendedResourceRef<TResult>;

export function extendedResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | undefined, options?: ExtendResourceOptions<TResult, TRaw>): ExtendedResourceRef<TResult | undefined>;

export function extendedResource<TResult, TRaw = TResult>(request: () => HttpResourceRequest | undefined, options?: ExtendResourceOptions<TResult, TRaw>): ExtendedResourceRef<TResult | undefined> {
  const stableRequest = computed(() => request(), {
    equal: createEqualRequest(options?.equal),
  });

  const destroyRef = options?.injector ? options.injector.get(DestroyRef) : inject(DestroyRef);

  let resource = httpResource<TResult>(stableRequest, {
    ...options,
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    parse: options?.parse as any, // Not my favorite thing to do, but here it is completely safe.
  }) as HttpResourceRef<TResult>; // type cast due to TS infering that it could also be TResult | undefined. This inference is not correct as function overloading prevents it.

  resource = refresh(resource, destroyRef, options?.refresh);
  resource = retryOnError(resource, options?.retry);
  resource = persistResourceValues<TResult>(resource, options?.keepPrevious, options?.equal);

  const onError = options?.onError; // Put in own variable to ensure value remains even if options are somehow mutated in-line
  if (onError) {
    const onErrorRef = effect(() => {
      const err = resource.error();
      if (err) onError(err);
    });

    // cleanup on manual destroy, I'm comfortable setting these props in-line as we have yet to 'release' the object out of this lexical scope
    const destroyRest = resource.destroy;
    resource.destroy = () => {
      onErrorRef.destroy();
      destroyRest();
    };
  }

  return resource;
}

So there we have it, our initial version of extendedResource :) I hope the code & comments make it all self explanatory.

One thing I'd like to expand on is that I've consciously restricted the main interface so that it only accepts a request function instead of the many variations httpResource provides such as a simple string. This is because I believe all this additional logic is not really necessary if you have an immutable piece of state, fetched at say the top level of your application & even if you wanted some particular feature such as refresh/retry for that, you could simply just pass that into this signature & it would work perfectly. Likewise we don't really require .blob/.text in our apps, if you do it would be simple enough to add this functionality or create a separate resource extension for that following the same patterns/code. The point I'm trying to make, in a very roundabout way, is...let's keep it simple.

The circuit breaker

This one also isn't hard to do, since we're using a single threaded language. We're going to build a very basic circuit breaker with the basic three states: 'CLOSED', 'OPEN' & 'HALF_OPEN'. If an api responds with an error n times, we will close the circuit & open it half-way after a set timeout so that we give the server time to restore itself. The resource should re-attempt a request automatically (without additional high-level code) if the state changes from closed to open/half-open.

Since changes to an api's circuit do directly impact values/resources & aren't simple reloads, we should manage our state with signals as far as possible. Anyway that's enough of an 'outline'...let's get implementing!

// circuit-breaker.ts
import { computed, effect, Signal, signal, untracked } from '@angular/core';

type CircuitBreakerState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';

export type CircuitBreaker = {
  isClosed: Signal<boolean>;
  status: Signal<CircuitBreakerState>;
  fail: () => void;
  success: () => void;
  halfOpen: () => void;
  destroy: () => void;
};

// false allows for opt out of circuit breaker, full CircuitBreaker allows sharing between multiple resources
export type CircuitBreakerOptions = false | CircuitBreaker | { treshold?: number; timeout?: number };

// allow for top level creation (for example in a service)
function internalCeateCircuitBreaker(treshold = 5, resetTimeout = 30000): CircuitBreaker {
  const halfOpen = signal(false);
  const failureCount = signal(0);

  const status = computed<CircuitBreakerState>(() => {
    if (failureCount() >= treshold) return 'CLOSED';
    return halfOpen() ? 'HALF_OPEN' : 'OPEN';
  });

  const isClosed = computed(() => status() === 'CLOSED');

  const success = () => {
    failureCount.set(0);
    halfOpen.set(false);
  };

  const tryOnce = () => {
    if (!untracked(isClosed)) return;
    halfOpen.set(true);
    failureCount.set(treshold - 1);
  };

  const effectRef = effect((cleanup) => {
    if (!isClosed()) return;

    const timeout = setTimeout(tryOnce, resetTimeout);

    return cleanup(() => clearTimeout(timeout));
  });

  const fail = () => {
    failureCount.set(failureCount() + 1);
    halfOpen.set(false);
  };

  return {
    status,
    isClosed,
    fail,
    success,
    halfOpen: tryOnce,
    destroy: () => effectRef.destroy(),
  };
}

function createNeverBrokenCircuitBreaker(): CircuitBreaker {
  return {
    isClosed: computed(() => false),
    status: computed(() => 'OPEN'),
    fail: () => {
      // noop
    },
    success: () => {
      // noop
    },
    halfOpen: () => {
      // noop
    },
    destroy: () => {
      // noop
    },
  };
}

export function createCircuitBreaker(opt?: CircuitBreakerOptions): CircuitBreaker {
  if (opt === false) return createNeverBrokenCircuitBreaker();

  if (opt && 'isClosed' in opt) return opt;

  return internalCeateCircuitBreaker(opt?.treshold, opt?.timeout);
}

// We add CircuitBreaker options to our options type

export type ExtendedResourceOptions<TResult, TRaw = TResult> = {
  ...rest
  circuitBreaker?: CircuitBreakerOptions
}


// We also finaly use our type extension to add a disabled signal, this allows us to react to CircutBreaker closing within our UI, by say disabling buttons
export type ExtendedResourceRef<TResult> = HttpResourceRef<TResult> & {
  disabled: Signal<boolean>;
};

// And we integrate it within the function itself.


export function extendedResource<TResult, TRaw = TResult>(
  request: () => HttpResourceRequest | undefined,
  options?: ExtendResourceOptions<TResult, TRaw>
): ExtendedResourceRef<TResult | undefined> {
  const cb = createCircuitBreaker(options?.circuitBreaker);

  const stableRequest = computed(
    () => {
      // returning undefined disables this resource
      if (cb.isClosed()) return undefined;
      return request();
    },
    {
      equal: createEqualRequest(options?.equal),
    }
  );

  ...other resource code


  // iterate circuit breaker state, using an effect since, again, this is inherently a side effect
  const cbEffectRef = effect(() => {
    const status = resource.status();
    if (status === ResourceStatus.Error) cb.fail();
    else if (status === ResourceStatus.Resolved) cb.success();
  });

  return {
    ...resource,
    disabled: computed(() => cb.isClosed() || stableRequest() === undefined), // also disabled if the returned request is undefined
    reload: () => {
      cb.halfOpen(); // open the circuit for manual reload
      return resource.reload();
    },
    destroy: () => {
      cbEffectRef.destroy();
      cb.destroy();
      resource.destroy();
    },
  };

Caching - the "hard" stuff

Again, rather luckily, we are using a single-threaded language, so we can create a simple cache without too much difficulty. You can replace this with any cache implementation really such as unstorage or even tanstack's QueryCache...as long as it has a way of communicating changes to certain keys, it should be fine. For best results we should however stick with signals. I've also used the mutable primitive from Part 1 for performance reasons, feel free to replace it with a normal signal & destructure if you feel more comfortable with that :).

As we know, cache invalidation is always tricky, but I've personally found Tanstack's approach of a default 0 staleTime, but larger TTL to be quite appropriate for most of our usecases. This will result in the stale data being displayed so that the app feels fast, but also refreshes that data in the background.

// cache.ts
import type { HttpResponse } from '@angular/common/http';
import { computed, inject, InjectionToken, Injector, type Provider, type Signal, untracked } from '@angular/core';
import { v7 } from 'uuid';
import { mutable } from './mutable';

type LRUCleanupType = {
  type: 'lru';
  checkInterval: number;
  maxSize: number;
};

type OldsetCleanupType = {
  type: 'oldest';
  checkInterval: number;
  maxSize: number;
};

type CacheEntry<T> = {
  value: T;
  created: number;
  stale: number;
  useCount: number;
  expiresAt: number;
  timeout: ReturnType<typeof setTimeout>;
};

export type CleanupType = LRUCleanupType | OldsetCleanupType;

const ONE_DAY = 1000 * 60 * 60 * 24;
const ONE_HOUR = 1000 * 60 * 60;

const DEFAULT_CLEANUP_OPT = {
  type: 'lru',
  maxSize: 200,
  checkInterval: ONE_HOUR,
} satisfies LRUCleanupType;

export class Cache<T> {
  private readonly internal = mutable(new Map<string, CacheEntry<T>>());
  private readonly cleanupOpt: CleanupType;

  constructor(
    private readonly ttl: number = ONE_DAY,
    private readonly staleTime: number = ONE_HOUR,
    cleanupOpt: Partial<CleanupType> = {
      type: 'lru',
      maxSize: 1000,
      checkInterval: ONE_HOUR,
    },
  ) {
    this.cleanupOpt = {
      ...DEFAULT_CLEANUP_OPT,
      ...cleanupOpt,
    };
    if (this.cleanupOpt.maxSize <= 0) throw new Error('maxSize must be greater than 0');

    // cleanup cache based on provided options regularly
    const cleanupInterval = setInterval(() => {
      this.cleanup();
    }, cleanupOpt.checkInterval);

    const destroyId = v7();

    // cleanup if object is garbage collected, this is because the cache can be quite large from a memory standpoint & we dont want all that floating garbage
    const registry = new FinalizationRegistry((id: string) => {
      if (id === destroyId) {
        clearInterval(cleanupInterval);
      }
    });

    registry.register(this, destroyId);
  }

  private getInternal(key: () => string | null): Signal<(CacheEntry<T> & { isStale: boolean }) | null> {
    const keySignal = computed(() => key());

    return computed(() => {
      const key = keySignal();
      if (!key) return null;
      const found = this.internal().get(key);

      const now = Date.now();

      if (!found || found.expiresAt <= now) return null;
      found.useCount++;
      return {
        ...found,
        isStale: found.stale <= now,
      };
    });
  }

  getUntracked(key: string): (CacheEntry<T> & { isStale: boolean }) | null {
    return untracked(this.getInternal(() => key));
  }

  get(key: () => string | null): Signal<(CacheEntry<T> & { isStale: boolean }) | null> {
    return this.getInternal(key);
  }

  store(key: string, value: T, staleTime = this.staleTime, ttl = this.ttl) {
    const entry = this.getUntracked(key);
    if (entry) {
      clearTimeout(entry.timeout); // stop invalidation
    }

    const prevCount = entry?.useCount ?? 0;

    // ttl cannot be less than staleTime
    if (ttl < staleTime) staleTime = ttl;

    const now = Date.now();

    this.internal.mutate((map) => {
      map.set(key, {
        value,
        created: entry?.created ?? now,
        useCount: prevCount + 1,
        stale: now + staleTime,
        expiresAt: now + ttl,
        timeout: setTimeout(() => this.invalidate(key), ttl),
      });
      return map;
    });
  }

  invalidate(key: string) {
    const entry = this.getUntracked(key);
    if (!entry) return;
    clearTimeout(entry.timeout);
    this.internal.mutate((map) => {
      map.delete(key);
      return map;
    });
  }

  private cleanup() {
    if (untracked(this.internal).size <= this.cleanupOpt.maxSize) return;

    const sorted = Array.from(untracked(this.internal).entries()).toSorted((a, b) => {
      if (this.cleanupOpt.type === 'lru') {
        return a[1].useCount - b[1].useCount; // least used first
      } else {
        return a[1].created - b[1].created; // oldest first
      }
    });

    const keepCount = Math.floor(this.cleanupOpt.maxSize / 2);

    const removed = sorted.slice(0, sorted.length - keepCount);
    const keep = sorted.slice(removed.length, sorted.length);

    removed.forEach(([, e]) => {
      clearTimeout(e.timeout);
    });

    this.internal.set(new Map(keep));
  }
}

type CacheOptions = {
  ttl?: number;
  staleTime?: number;
  cleanup?: Partial<CleanupType>;
};

const CLIENT_CACHE_TOKEN = new InjectionToken<Cache<HttpResponse<unknown>>>('INTERNAL_CLIENT_CACHE');

export function provideCache(opt?: CacheOptions): Provider {
  return {
    provide: CLIENT_CACHE_TOKEN,
    useValue: new Cache(opt?.ttl, opt?.staleTime, opt?.cleanup),
  };
}

export function injectCache(injector?: Injector) {
  return injector ? injector.get(CLIENT_CACHE_TOKEN) : inject(CLIENT_CACHE_TOKEN);
}

// cache.interceptor.ts
import { HttpContext, HttpContextToken, type HttpEvent, type HttpHandlerFn, type HttpInterceptorFn, type HttpRequest, HttpResponse } from '@angular/common/http';
import { map, Observable, of, tap } from 'rxjs';
import { injectCache } from './cache';

type CacheEntryOptions = {
  key?: string;
  ttl?: number;
  staleTime?: number;
  cache: boolean;
};

const CACHE_CONTEXT = new HttpContextToken<CacheEntryOptions>(() => ({
  cache: false,
}));

export function setCacheContext(
  ctx = new HttpContext(),
  opt: Omit<CacheEntryOptions, 'cache' | 'key'> & {
    key: Required<CacheEntryOptions>['key'];
  },
) {
  return ctx.set(CACHE_CONTEXT, { ...opt, cache: true });
}

function getCacheContext(ctx: HttpContext): CacheEntryOptions {
  return ctx.get(CACHE_CONTEXT);
}

type ResolvedCacheControl = {
  noStore: boolean;
  noCache: boolean;
  mustRevalidate: boolean;
  immutable: boolean;
  maxAge: number | null;
  staleWhileRevalidate: number | null;
};

function parseCacheControlHeader(req: HttpResponse<unknown>): ResolvedCacheControl {
  const header = req.headers.get('Cache-Control');

  let sMaxAge: number | null = null;
  const directives: ResolvedCacheControl = {
    noStore: false,
    noCache: false,
    mustRevalidate: false,
    immutable: false,
    maxAge: null,
    staleWhileRevalidate: null,
  };

  if (!header) return directives;

  const parts = header.split(',');

  for (const part of parts) {
    const [unparsedKey, value] = part.trim().split('=');
    const key = unparsedKey.trim().toLowerCase();

    switch (key) {
      case 'no-store':
        directives.noStore = true;
        break;
      case 'no-cache':
        directives.noCache = true;
        break;
      case 'must-revalidate':
      case 'proxy-revalidate':
        directives.mustRevalidate = true;
        break;
      case 'immutable':
        directives.immutable = true;
        break;
      case 'max-age':
        if (!value) break;
        const parsedValue = parseInt(value, 10);
        if (!isNaN(parsedValue)) directives.maxAge = parsedValue;
        break;
      case 's-max-age': {
        if (!value) break;
        const parsedValue = parseInt(value, 10);
        if (!isNaN(parsedValue)) sMaxAge = parsedValue;
        break;
      }
      case 'stale-while-revalidate': {
        if (!value) break;
        const parsedValue = parseInt(value, 10);
        if (!isNaN(parsedValue)) directives.staleWhileRevalidate = parsedValue;
        break;
      }
    }
  }

  // s-max-age takes precedence over max-age
  if (sMaxAge !== null) directives.maxAge = sMaxAge;

  // if no store nothing else is relevant
  if (directives.noStore)
    return {
      noStore: true,
      noCache: false,
      mustRevalidate: false,
      immutable: false,
      maxAge: null,
      staleWhileRevalidate: null,
    };

  // max age does not apply to immutable resources
  if (directives.immutable)
    return {
      ...directives,
      maxAge: null,
    };

  return directives;
}

function resolveTimings(cacheControl: ResolvedCacheControl, staleTime?: number, ttl?: number): { staleTime?: number; ttl?: number } {
  const timings = {
    staleTime,
    ttl,
  };

  if (cacheControl.immutable)
    return {
      staleTime: Infinity,
      ttl: Infinity,
    };

  // if no-cache is set, we must always revalidate
  if (cacheControl.noCache || cacheControl.mustRevalidate) timings.staleTime = 0;

  if (cacheControl.staleWhileRevalidate !== null) timings.staleTime = cacheControl.staleWhileRevalidate;

  if (cacheControl.maxAge !== null) timings.ttl = cacheControl.maxAge * 1000;

  // if stale-while-revalidate is set, we must revalidate after that time at the latest, but we can still serve the stale data
  if (cacheControl.staleWhileRevalidate !== null) {
    const ms = cacheControl.staleWhileRevalidate * 1000;
    if (timings.staleTime === undefined || timings.staleTime > ms) timings.staleTime = ms;
  }

  return timings;
}

export function createCacheInterceptor(allowedMethods = ['GET', 'HEAD', 'OPTIONS']): HttpInterceptorFn {
  const CACHE_METHODS = new Set<string>(allowedMethods);

  return (req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> => {
    const cache = injectCache();

    if (!CACHE_METHODS.has(req.method)) return next(req);
    const opt = getCacheContext(req.context);

    if (!opt.cache) return next(req);

    const key = opt.key ?? req.urlWithParams;
    const entry = cache.getUntracked(key); // null if expired or not found

    // If the entry is not stale, return it
    if (entry && !entry.isStale) return of(entry.value);

    // resource itself handles case of showing stale data...the request must process as this will "refresh said data"

    const eTag = entry?.value.headers.get('ETag');
    const lastModified = entry?.value.headers.get('Last-Modified');

    if (eTag) {
      req = req.clone({ setHeaders: { 'If-None-Match': eTag } });
    }

    if (lastModified) {
      req = req.clone({ setHeaders: { 'If-Modified-Since': lastModified } });
    }

    return next(req).pipe(
      tap((event) => {
        if (event instanceof HttpResponse && event.ok) {
          const cacheControl = parseCacheControlHeader(event);
          if (cacheControl.noStore) return;

          const { staleTime, ttl } = resolveTimings(cacheControl, opt.staleTime, opt.ttl);

          cache.store(key, event, staleTime, ttl);
        }
      }),
      map((event) => {
        // handle 304 responses due to eTag/last-modified
        if (event instanceof HttpResponse && event.status === 304 && entry) {
          return entry.value;
        }

        return event;
      }),
    );
  };
}

// has-slow-connection.ts

// check if user on slow mobile connection
export function hasSlowConnection() {
  if ('connection' in window.navigator && typeof window.navigator.connection === 'object' && !!window.navigator.connection && 'effectiveType' in window.navigator.connection && typeof window.navigator.connection.effectiveType === 'string') return window.navigator.connection.effectiveType.endsWith('2g');

  return false;
}

// extended-resource.ts

// first we add the new configuration options
type ResourceCacheOptions =
  | true
  | {
      ttl?: number;
      staleTime?: number;
      hash?: (req: HttpResourceRequest) => string;
    };

export type ExtendResourceOptions<
  TResult,
  TRaw = TResult
> = HttpResourceOptions<TResult, TRaw> & {
  ...rest
  cache?: ResourceCacheOptions; // Cache options, undefined = no cache
};

// add prefetch to Ref
export type ExtendedResourceRef<TResult> = HttpResourceRef<TResult> & {
  disabled: Signal<boolean>;
  prefetch: (req?: Partial<HttpResourceRequest>) => Promise<void>;
};

export function extendedResource<TResult, TRaw = TResult>(
  request: () => HttpResourceRequest | undefined,
  options?: ExtendResourceOptions<TResult, TRaw>
): ExtendedResourceRef<TResult | undefined> {
  const cache = injectCache(options?.injector);


  ...otherCode


  const hashFn =
    typeof options?.cache === 'object'
      ? options.cache.hash ?? urlWithParams
      : urlWithParams;

  const staleTime =
    typeof options?.cache === 'object' ? options.cache.staleTime : 0;
  const ttl =
    typeof options?.cache === 'object' ? options.cache.ttl : undefined;

  const cacheKey = computed(() => {
    const r = stableRequest();
    if (!r) return null;
    return hashFn(r);
  });

  const cachedRequest = options?.cache
    ? computed(() => {
        const r = stableRequest();
        if (!r) return r;

        return {
          ...r,
          context: setCacheContext(r.context, {
            staleTime,
            ttl,
            key: cacheKey() ?? hashFn(r),
          }),
        };
      })
    : stableRequest;

  // we now use the request, with the added cache context for our http call, so that the interceptor can update it
  let resource = httpResource<TResult>(cachedRequest, {
    ...options,
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    parse: options?.parse as any, // Not my favorite thing to do, but here it is completely safe.
  }) as HttpResourceRef<TResult>;



  // get full HttpResonse from Cache
  const cachedEvent = cache.get(cacheKey);

  const parse = options?.parse ?? ((val: TRaw) => val as unknown as TResult);

  const actualCacheValue = computed((): TResult | undefined => {
    const ce = cachedEvent();
    if (!ce || !(ce instanceof HttpResponse)) return;
    return parse(ce.body as TRaw);
  });

  // retains last cache value after it is invalidated for lifetime of resource
  const cachedValue = linkedSignal<TResult | undefined, TResult | undefined>({
    source: () => actualCacheValue(),
    computation: (source, prev) => {
      if (!source && prev) return prev.value;
      return source;
    },
  });

  // value is updated every time cachedValue changes (due to other resources), falls back to resource.value (defaultValue if provided)
  const value = options?.cache
    ? toWritable(
        computed((): TResult => {
          return cachedValue() ?? resource.value();
        }),
        resource.value.set,
        resource.value.update
      )
    : resource.value;

  ...otherCode

  ...otherCode


  // we override the set function so that the cache is also updated when manually setting (propagating any state changes throughout our app)
  const set = (value: TResult) => {
    resource.set(value);
    const k = untracked(cacheKey);
    if (options?.cache && k)
      cache.store(
        k,
        new HttpResponse({
          body: value,
          status: 200,
          statusText: 'OK',
        })
      );
  };

  const update = (updater: (value: TResult) => TResult) => {
    set(updater(untracked(resource.value)));
  };

  const client = options?.injector
    ? options.injector.get(HttpClient)
    : inject(HttpClient);

  return {
    ...resource,
    value,
    set,
    update,
    disabled: computed(() => cb.isClosed() || stableRequest() === undefined),
    reload: () => {
      cb.halfOpen(); // open the circuit for manual reload
      return resource.reload();
    },
    destroy: () => {
      cbEffectRef.destroy();
      cb.destroy();
      resource.destroy();
    },
    prefetch: async (partial) => {
      // do not prefetch if no cache or if on slow mobile connection
      if (!options?.cache || hasSlowConnection()) return Promise.resolve();

      const request = untracked(cachedRequest);
      if (!request) return Promise.resolve();

      const prefetchRequest = {
        ...request,
        ...partial,
      };

      try {
        // no need to store response to variable, it is stored in cache due to interceptor
        await firstValueFrom(
          client.request<TRaw>(
            prefetchRequest.method ?? 'GET',
            prefetchRequest.url,
            {
              ...prefetchRequest,
              headers: prefetchRequest.headers as HttpHeaders,
              observe: 'response',
            }
          )
        );

        return;
      } catch (err) {
        if (isDevMode()) console.error('Prefetch failed: ', err);
        return;
      }
    },
  };
}

Well that was quite the chunk of code :) As you can see we're doing a few things here:

We're setting HttpResponse objects in the cache for valid requests
If we make a request and we find an entry that is not expired and not stale, we return it
If we find a value that is stale, we return it, but also make a request so that it is refreshed behind the hood
If we dont find a value, we, of course, just make a request & fill the cache for next time
If multiple resources are listening to the same key, they are all updated to the latest value, when a new resource is instantiated/reloaded/manually set
We can pre-fill the cache by calling prefetch(), which can be useful when say hovering over a link, or fetching the next page for the table. This is disabled if the resource doesn't have a cache option (as we can't store the response anywhere), or if the user is on a slow mobile connection, to not overload it.
We're using signals thorughout the core state, so the reactive graph's dependencies are solidly set & the scheduler can figure it all out.

One thing...we had to split some logic between the interceptor (fresh data & setting cache) and the resource itself (stale data & cache subscription), this is due to the .isLoading/status sigals within the resource. If we simply returned the stale data from the interceptor the status of the resource would no longer be loading, as the request would have been completed, as far as it's concerned. It would still update when the request actually comppletes, but I feel that a loading state is very appropriate for this scenario. This is why we separated this logic. I'll admit it's not the cleanest approach, but sometimes we just have to get our hands dirty :).

Mutations

Since we now have a solid foundation for fetching data to our client, let's start thinking about how we're going to mutate that state. Personally I like Tanstack's approach here, where a mutation is setup with various callbacks, such as onError, & returns a function which is called with the next request whenever needed. So far this has proven quite robust in our production & honestly what I find to be the easiest way of managing complexity. I propose we setup 4 callbacks:

onMutate: will be called when the function is called (before request)
onError: will be called when an error happens
onSuccess: will be called when the request is resolved
onSettled: will be called when the request is finished (error or success)

Additionally onMutate should enable us to set up a context variable, which is then passed to the other functions, this allows us to create logic to reset state on failure and such. Anywhere let's get into it, this one is pretty straightforward, since we setup extendedResource so well.

import { type HttpResourceRequest } from '@angular/common/http';
import { computed, DestroyRef, inject, ResourceStatus, Signal, signal } from '@angular/core';
import { takeUntilDestroyed, toObservable } from '@angular/core/rxjs-interop';
import { combineLatestWith, filter, map } from 'rxjs';
import { createEqualRequest } from './equal-request';
import { extendedResource, type ExtendedResourceRef, type ExtendResourceOptions } from './extended-resource';

type StatusResult<TResult> =
  | {
      status: ResourceStatus.Error;
      error: unknown;
    }
  | {
      status: ResourceStatus.Resolved;
      value: TResult;
    };

export type MutationResourceOptions<TResult, TRaw = TResult, TCTX = void> = Omit<
  ExtendResourceOptions<TResult, TRaw>,
  'onError' | 'keepPrevious' | 'refresh' | 'cache' // we can't keep previous values, refresh or cache mutations as they are meant to be one-off operations
> & {
  onMutate?: (value: NoInfer<TResult>) => TCTX;
  onError?: (error: unknown, ctx: NoInfer<TCTX>) => void;
  onSuccess?: (value: NoInfer<TResult>, ctx: NoInfer<TCTX>) => void;
  onSettled?: (ctx: NoInfer<TCTX>) => void;
};

export type MutationResourceRef<TResult> = Omit<
  ExtendedResourceRef<TResult>,
  'prefetch' | 'value' | 'hasValue' | 'set' | 'update' // we don't allow manually viewing the returned data or updating it manually, prefetching a mutation also doesn't make any sense
> & {
  mutate: (value: Omit<HttpResourceRequest, 'body'> & { body: TResult }) => void;
  current: Signal<(Omit<HttpResourceRequest, 'body'> & { body: TResult }) | null>;
};

export function mutationResource<TResult, TRaw = TResult, TCTX = void>(request: () => Omit<Partial<HttpResourceRequest>, 'body'> | undefined, options: MutationResourceOptions<TResult, TRaw, TCTX>): MutationResourceRef<TResult> {
  const equal = createEqualRequest(options.equal);

  const baseRequest = computed(() => request(), {
    equal,
  });

  const nextRequest = signal<(Omit<HttpResourceRequest, 'body'> & { body: TResult }) | null>(null, {
    equal: (a, b) => {
      if (!a && !b) return true;
      if (!a || !b) return false;
      return equal(a, b);
    },
  });

  const req = computed((): HttpResourceRequest | undefined => {
    const nr = nextRequest();
    if (!nr) return;

    const base = baseRequest();

    const url = base?.url ?? nr.url;
    if (!url) return;

    return {
      ...base,
      ...nr,
      url,
    };
  });

  const { onMutate, onError, onSuccess, onSettled, ...rest } = options;

  const resource = extendedResource<TResult, TRaw>(req, {
    ...rest,
    defaultValue: null as TResult, // doesnt matter since .value is not accessible
  });

  let ctx: TCTX = undefined as TCTX;

  const destroyRef = options.injector ? options.injector.get(DestroyRef) : inject(DestroyRef);

  const error$ = toObservable(resource.error);
  const value$ = toObservable(resource.value);

  const statusSub = toObservable(resource.status)
    .pipe(
      combineLatestWith(error$, value$),
      map(([status, error, value]): StatusResult<TResult> | null => {
        if (status === ResourceStatus.Error && error) {
          return {
            status: ResourceStatus.Error,
            error,
          };
        }

        if (status === ResourceStatus.Resolved && value !== null) {
          return {
            status: ResourceStatus.Resolved,
            value,
          };
        }

        return null;
      }),
      filter((v) => v !== null),
      takeUntilDestroyed(destroyRef),
    )
    .subscribe((result) => {
      if (result.status === ResourceStatus.Error) onError?.(result.error, ctx);
      else onSuccess?.(result.value, ctx);

      onSettled?.(ctx);
      ctx = undefined as TCTX;
      nextRequest.set(null);
    });

  return {
    ...resource,
    destroy: () => {
      statusSub.unsubscribe();
      resource.destroy();
    },
    mutate: (value) => {
      ctx = onMutate?.(value.body as TResult) as TCTX;
      nextRequest.set(value);
    },
    current: nextRequest,
  };
}

Optimistic updates

As you can see the above interface allows for easy updates to other existing resources, as such we can also provide a helper option (it could also be a separate function if you prefer) to optimistically update another resource of the same type (say we have a getById resource & a patch mutation resource in a store).

export type MutationResourceOptions<
  TResult,
  TRaw = TResult,
  TCTX = void
> = Omit<
  ExtendResourceOptions<TResult, TRaw>,
  'onError' | 'keepPrevious' | 'refresh' | 'cache' // we can't keep previous values, refresh or cache mutations as they are meant to be one-off operations
> & {
  ...rest
  optimisticlyUpdate?: HttpResourceRef<TResult>;
};



export function mutationResource<TResult, TRaw = TResult, TCTX = void>(
  request: () => Omit<Partial<HttpResourceRequest>, 'body'> | undefined,
  options: MutationResourceOptions<TResult, TRaw, TCTX>
): MutationResourceRef<TResult> {

  ...rest

 const {
    onMutate: providedOnMutate,
    onError: providedOnError,
    onSuccess: providedOnSuccess,
    onSettled,
    ...rest
  } = options;

  let prevOptimisticValue: TResult | null = null;

  const optimisticResource = options.optimisticlyUpdate;

  const onMutate = optimisticResource
    ? (val: TResult) => {
        prevOptimisticValue = untracked(optimisticResource.value);
        optimisticResource.set(val);
        return providedOnMutate?.(val);
      }
    : providedOnMutate;

  const onError = optimisticResource
    ? (err: unknown, ctx: TCTX) => {
        if (prevOptimisticValue !== null)
          optimisticResource.set(prevOptimisticValue);

        providedOnError?.(err, ctx);
      }
    : providedOnError;

  const onSuccess = optimisticResource
    ? (val: TResult, ctx: TCTX) => {
        optimisticResource.set(val);
        providedOnSuccess?.(val, ctx);
      }
  ...rest
}

Personally I prefer to be slightly more manual about these things, so I'd leave the interface as it's outlined originally & simple use the provided callbacks to update state as I see fit. After all, we save very little code this way. Here's an example which is slightly more advanced (although it uses slightly different primitives, they are conceptually similar enough); event-definition.store.ts.

I'm also highlighting it, because it contains an interesting solution to an optimistic update issue; loss of state. Specifically it contains it's forms in dialog components, which are optimistically closed when the user confirms. If we just reverted the state on error, their work would be lost forever. The solution is quite simple though, we pass the form state into our mutationResource's context & re-open that state on error (+ display a message), this allows the user to potentially fix what went wrong.

Bonus - Deduplication

Alright time for a bit of a bonus feature: request deduplication. If for some reason, we make a request to an url (+ params), while another to the same one is still in flight...let's not call the server twice. This allows us to use our resources in a more worry-free manner, just like Tanstack.

Originally this interceptor was inspired by this article Request Deduplication in Angular. In fact the code is still quite similar, since it works well. I thought I'd add it here as well, since it roundes out our feature set nicely.

// Heavily inpsired by: https://dev.to/kasual1/request-deduplication-in-angular-3pd8
import { HttpContext, HttpContextToken, HttpInterceptorFn, type HttpEvent, type HttpHandlerFn, type HttpRequest } from '@angular/common/http';
import { finalize, shareReplay, type Observable } from 'rxjs';

const NO_DEDUPE = new HttpContextToken<boolean>(() => false);

export function noDedupe(ctx: HttpContext = new HttpContext()) {
  return ctx.set(NO_DEDUPE, true);
}

export function createDedupeRequestsInterceptor(allowed = ['GET', 'DELETE', 'HEAD', 'OPTIONS']): HttpInterceptorFn {
  const inFlight = new Map<string, Observable<HttpEvent<unknown>>>();

  const DEDUPE_METHODS = new Set<string>(allowed);

  return (req: HttpRequest<unknown>, next: HttpHandlerFn): Observable<HttpEvent<unknown>> => {
    if (!DEDUPE_METHODS.has(req.method) || req.context.get(NO_DEDUPE)) return next(req);

    const found = inFlight.get(req.urlWithParams);

    if (found) return found;

    const request = next(req).pipe(
      finalize(() => inFlight.delete(req.urlWithParams)),
      shareReplay(),
    );
    inFlight.set(req.urlWithParams, request);

    return request;
  };
}

Sign off

Well, that's all for now. I hope you find these helpers as useful as we do!

I'll be taking a short break from this series for now, but I have a few cool things in the oven such as a typesafe & modular localization library sneak preview & a very nice data table component, which I can't wait to share with you all. :) Other than that, see you in the next article, happy coding! 🚀

Fun-grained reactivity in Angular: Part 2 – Forms

Miha Mulec — Thu, 13 Mar 2025 10:50:00 +0000

Update: I've released a "spruced up" version of the primitives outlined bellow, as well as Angular Material bindings for them, as libraries. I hope you find them useful :)

@mmstack/form-core
@mmstack/form-material

It's been a while since Part 1 - Primitives, where we played around with some basic signal building blocks like mutable, store, and resource. Life happens, Angular updates happen, and now we've got model... but some problems just stick around. And in the world of forms, that problem is, well, forms.

While angular 17 allowed us to bind signals to ngModel, which was supposed to be the answer to all our two-way binding woes. And it sort of works... until you start dealing with objects or arrays. Then things get a little weird.

See, ngModel, bound to a property of an object within a signal, has this habit of mutating your data inline. Like this:

@Component({
  selector: 'app-root',
  imports: [FormsModule],
  template: `
    <input [(ngModel)]="user().name" />
    <p>Hello, {{ user().name }}!</p>
    <!-- updates -->
    <p>Hello, {{ userName() }}</p>
    <!-- doesn't update -->
    <button (click)="force()">Force change detection</button>
  `,
})
export class AppComponent {
  protected readonly user = signal({ name: 'Initial Name' });
  protected readonly userName = computed(() => this.user().name);

  protected force() {
    this.user.update((cur) => ({ ...cur }));
  }
}

You type in the input, and user().name changes. Great! Except... the user signal itself didn't technically update. The object inside it did. Which means any computed or effect watching user will not notice a thing. You've successfully mutated your data under the radar, and your carefully crafted reactive graph is now out of sync. Not ideal. Even more weird, the angular renderer sometimes detects these changes "correctly" (when using zone.js change detection). When using zoneless, or by using a computed like "userName" above the changes arent detected until the user object is destructured, at which point data will "snap" to the value actually set within the input. Since we're moving to a zoneless & signal based future, this simply isn't good enough.

If you need a quick fix to this problem, you can force change detection on ngModelChange emission, by either directly updating the value or using a generic trigger function:

// Option 1: Destructure on update
<input [ngModel]="user().name" (ngModelChange)="updateName($event)" />

updateName(newName: string) {
  this.user.update(currentUser => ({ ...currentUser, name: newName }));
}
// Option 2: If you have multiple props, this might be easier
<input [(ngModel)]="user().name" (ngModelChange)="triggerChange()" />

triggerChange() {
   this.user.update((cur) => ({...cur}));
}

If all you're looking for here is a quick solution to this problem, there you go...but I think we can do better...much better ;). So, in this article we're going to ditch workarounds like this and build our own reactive form primitives, replacing ngModel almost fully. Our goals with this re-work:

Predictability: No undetectable mutations
Render performance: Only update the parts of the dom that need to update
Type safety: This isn't an issue with ngModel, but rather the ControlValueAccessor interface, which doesn't verify the types.
Extensibility: Allow relatively easy enchancements
& most importantly...full reactivity: Changes to properties cause signal updates, so that dependent computeds/effects fire as expected

Core primitives

Before we begin working on the form control signal & its derivatives, we need to quickly discuss a few core concepts & create some primitives that our solution will use. The first thing I'd like you to take a look at is nested computeds, I think this was not allowed in angular 17, but I could be wrong there..it definitely works with ng18+.

Here's a bit of an upcoming part (tables) which uses this, it's a very simplified/contrived example, but it shows where we can use this. Specifically when working with paginated data we can render the rows (and calculate everything related to them) once..or rather only if the "length" of the page changes. The cells however need to be dynamic as data on another page will be different. Doing it like this causes minimal re-renders. Don't worry we'll show the full data table code when thats finished in an upcoming article, look forward to it! :)

function equalsUser(a: User, b: User) {
  return a.id === b.id;
}

function accessName(u: User) {
  return u.name;
}

const data = signal([
  { id: 1, name: "John" },
  { id: 2, name: "Peter" },
]);

const length = computed(() => data().length); // stabilize so that rows are only re-rendered if the length of the paginated data changes

const rows = computed(() =>
  Array.from({ length: length() }).map((_, i) => {
    const value = computed(() => data()[i], { equal: equalsUser });
    return {
      value,
      cells: [createCell(value, accessName)], // many columns but in this contrived example only one
    };
  })
); // create row signals

function createCell(data: Signal<User>, accessor: (value: T) => string) {
  const;
  return computed(() => accessor(data())); // change cell when data changes
}

The key takeaway here is that the rows computed creates an array of objects, each containing a value signal (representing a row) and an array of cells. Each cell is its own computed. This means that if we update the name of a single user in the data signal, only the corresponding cell computed for that user's name will re-evaluate. The rows computed might re-evaluate (if the page size changes), but thanks to the nested structure, we avoid unnecessary calculations/re-renders.

If you'd like to go more in depth Ryan Carniato wrote a great series related to this topic: Derivations in Reactivity

Two-Way Binding with Signals: The derived Primitive

Alright...knowing that, we need to create a system where data flows in both directions (two way binding), but, in a stable way. Angular has only one requirement we need to satisfy here...to allow two-way binding it expects a WritableSignal, which it reads and calls .set on.

We could create a signal with internal signals, like so signal({name: signal('John')}), that will allow us to change the name, sure, but it completely breaks the reactive graph because now the name signal is not aware it depends on the user signal, making any framework/scheduler level optimizations impossible.

Ideally we'd simply derive the value from the user signal. Considering that, we could try the new linkedSignal primitive for this like so const user = signal({name: 'John'}); const name = linkedSignal(() => user().name), this will ensure that changes to the user object flow down to the name signal, but changes to the name signal don't "trigger" the user signal, so even though the value of "user" has changed when we change name, no computeds/effects depending on the user signal will "detect" that change. We could of course use an effect to change the user signal every time name changes, but that again completely breaks the reactive graph, as angular, or really any signal based framework, can't track signal dependencies when setting a value from an effect.

To solve these conundrums, we need to create our own primitives, something which reacts to changes in the parent signal, but also triggers the parent when it itself changes. In essence, what we really want is a computed, which has a set function that applies changes to the parents state. On that change the value part of the computed is re-calculated, which in turn updates the DOM. Here are two primitives that make this easier:

import { computed, untracked, type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';

// Makes a computed writable.
export function toWritable<T>(signal: Signal<T>, set: (value: T) => void, update?: (updater: (value: T) => T) => void): WritableSignal<T> {
  const internal = signal as WritableSignal<T>;
  internal.asReadonly = () => signal; // just returns the value, as it's already a computed
  internal.set = set; // "fakes" the setter function of a WritableSignal
  internal.update = update ?? ((updater) => set(updater(untracked(internal)))); // "fakes" the update function of a WritableSignal

  return internal;
}

type CreateDerivedOptions<T, U> = CreateSignalOptions<U> & {
  from: (v: T) => U;
  onChange: (newValue: U) => void;
};

export type DerivedSignal<T, U> = WritableSignal<U> & {
  from: (v: T) => U;
};

// Creates a signal for a parent-child relationship
export function derived<T, U>(source: WritableSignal<T>, { from, onChange, ...rest }: CreateDerivedOptions<T, U>): DerivedSignal<T, U> {
  const sig = toWritable<U>(
    computed(() => from(source()), rest),
    (newVal) => {
      onChange(newVal);
    },
  ) as DerivedSignal<T, U>;

  sig.from = from;

  return sig;
}

export function isDerivedSignal<T, U>(sig: WritableSignal<U>): sig is DerivedSignal<T, U> {
  return 'from' in sig;
}

export function toFakeDerived<T, U>(initial: WritableSignal<U>): DerivedSignal<T, U> {
  const sig = initial as DerivedSignal<T, U>;
  sig.from = () => untracked(initial);
  return sig;
}

These two primitives allow us to perfectly describe the relationship between user and name, thus creating two WritableSignals, which remain in perfect sync like so:

const user = signal({name: 'John', age: 30});
// only fires when name changes, but checks every time user changes. Triggers user on changes
const name = derived(user, {
    from: (u) => u.name,
    onChange: (next) => user.update((cur) => ({...cur, name: next}));
});
// only fires when age changes, but checks every time user changes. Triggers user on changes
const age = derived(user, {
    from: (u) => u.age,
    onChange: (next) => user.update((cur) => ({...cur, age: next}));
});

Since we're leaving "other" properties alone..even if those are sub-objects, the equality check of each derived signals internal computed wont re-fire if something else changes. If we want to stabilize it even more, we can provide our own equality function. The stability of those change propagations along with Angular's lazy computed evaluation & batch scheduling ensures a highly performant reactive system.

There is however one big tradeoff here, the immutable data structures require us to destructure objects/arrays all over the state. In comparison to ngModel we lose on performance here as we're both doing a much more expensive property "set" & creating more work for the GC.

As most modern frameworks & patterns (such as most state management in React) rely on this these operations are already highly optimized in browsers. If we want to futher optimize this we could achieve that by simply using mutable signals described in Part 1, since they allow for both in-line mutation but also track changes as any other signal would. This way we can have the best of both worlds performance wise, but we might make the code a bit "trickier" to manage as we now need to consider mutable objects in our codebase.

Alright, I think we're now ready for forms :)

Form Control (finally!)

Lets start by looking at the type we're outlining here. I've added quite a few features here, keep/remove them as necessary within your codebase.

Please note that while we're creating a lot of computeds here, the actual functions that calculate their values are never triggered until that computed (or its parent) is subscribed to at least once. So we can _almost freely create as many as we want, unused things simply wont affect performance in any meaningful way._

import { type Signal, type WritableSignal } from '@angular/core';
import { type DerivedSignal } from './primitives';
import { v7 } from 'uuid';

export const CONTROL_SYMBOL = Symbol.for('INTERNAL_CLIENT_FORM_CONTROL');

export type ControlType = 'control' | 'array' | 'group';

export type FormControlSignal<T, TParent = undefined, TControlType extends ControlType = 'control', TPartialValue = T | undefined> = {
  id: string; // unique identifier meant for tracking in @for/ngFor loops
  value: WritableSignal<T>; // the main value signal
  dirty: Signal<boolean>; // True when the value has been changed, false if reverted back
  touched: Signal<boolean>; // Triggered when the control has been interacted with, for example blur on an input
  error: Signal<string>; // Error message to be displayed
  disabled: Signal<boolean>; // True when the control is disabled
  readonly: Signal<boolean>; // True when the control is readonly
  required: Signal<boolean>; // True when the control is required, used to add * to the label
  label: Signal<string>; // Label to be displayed
  hint: Signal<string>; // Hint to be displayed
  markAsTouched: () => void; // Marks the control as touched
  markAllAsTouched: () => void; // Marks the control and child controls as touched
  markAsPristine: () => void; // Sets touched to false
  markAllAsPristine: () => void; // Sets touched to false on self and all child controls
  reconcile: (newValue: T) => void; // Resets the control to a new value & new initial value, meant for new data comming from the server, only sets if the value is not dirty. This retains changes the user has made to the form
  forceReconcile: (newValue: T) => void; // Same as reconcile, but also resets if the value is dirty
  reset: () => void; // Resets the field to the initial value
  resetWithInitial: (initial: T) => void; // Resets the field to the initial value & sets initial
  from?: DerivedSignal<TParent, T>['from']; // Used in form groups & arrays to reconcile the data
  equal: (a: T, b: T) => boolean; // Provided equality function, defaults to Object.is
  [CONTROL_SYMBOL]: true; // Symbol for internal type checking
  controlType: TControlType; // Control type for type checking & reconciliation
  partialValue: Signal<TPartialValue>; // Value that is used when "patching" the state on the server, is a deep partial of the value
};

As you can see we've created quite the interface there, I'll leave some things for later such as the "from" property, as that'll be obvious once we get to form groups, but there are a few things id like to ellaborate on:

We're using a primitive id for @for tracking, due to some very weird behavior when using signals in the tracking function, I won't get into it now but @for(...;track obj.value()) simply won't work as expected.
These control signals are relatively expensive to create, but they should only really be constructed "once" in the case of a singular form. In our user signal example, we'd construct only one signal for each property & keep it for the lifetime of the form, what gets changed are sub-signals such as value, dirty, error etc. In fact if you really want to go far with it, you could simply construct it once when needed, store that state graph in a global store & then reconcile it every time you need to re-use it (for example any time a user opens a screen). This way the performance cost of constructing a forms reactive graph becomes truly neglibile.
I'd also like to re-iterate that while we're creating quite a few computeds angular will not fire the functions within them until they are subscribed to. I explain this in depth in Part 1 - Primitives, so we don't have to worry about how expensive functions are unless we call them. There is an insignificant expense paid to create new computeds, but as said in point 2, this can be made to happen only once/only when needed.
Reconciliation is something we require in our system, since we have data that can change during the lifetime of a form through an SSE subscription triggering when another user changes the same entity & to re-use structures in an object pool. I've included it, because it's a cool feature, but feel free to remove it.
Similarly to reconciliation, partial patches are something we use to optimize the data going upstream over the network, if your server/s don't support it, you can remove it, or simply not call it anywhere (see point 3).
Errors are always strings, validators either return an error message such as "Name is required" or an empty string "", an empty string is considered a valid state. The system assumes synchronous validation, but can easily be extended to support async validators if you require them, just make the validator return a string while pending and then either an empty string/message depending on if its valid.

export type CreateFormControlOptions<T, TControlType extends ControlType = ControlType> = CreateSignalOptions<T> & {
  validator?: () => (value: T) => string;
  onTouched?: () => void;
  disable?: () => boolean;
  readonly?: () => boolean;
  required?: () => boolean;
  label?: () => string;
  id?: () => string;
  hint?: () => string;
  dirtyEquality?: ValueEqualityFn<T>;
  onReset?: () => void;
  controlType?: TControlType;
  overrideValidation?: () => string;
};

export function formControl<T, TParent = undefined, TControlType extends ControlType = 'control', TPartialValue = T | undefined>(initial: DerivedSignal<TParent, T> | T, opt?: CreateFormControlOptions<T, TControlType>): FormControlSignal<T, TParent, TControlType, TPartialValue> {
  const value = isSignal(initial) ? initial : signal(initial, opt);
  const initialValue = signal(untracked(value));
  const eq = opt?.equal ?? Object.is;

  const dirtyEq = opt?.dirtyEquality ?? eq;

  const disabled = computed(() => opt?.disable?.() ?? false);
  const readonly = computed(() => opt?.readonly?.() ?? false);

  const dirty = computed(() => !dirtyEq(value(), initialValue()));

  const touched = signal(false);

  const validator = computed(() => opt?.validator?.() ?? (() => ''));

  const error = computed(() => {
    if (opt?.overrideValidation) return opt.overrideValidation();
    if (disabled() || readonly()) return '';
    return validator()(value());
  });

  const markAsTouched = () => {
    touched.set(true);
    opt?.onTouched?.();
  };
  const markAllAsTouched = markAsTouched;

  const markAsPristine = () => touched.set(false);
  const markAllAsPristine = markAsPristine;

  const label = computed(() => opt?.label?.() ?? '');

  const patchValue = computed(() => (dirty() ? value() : undefined));

  const internalReconcile = (newValue: T, force = false) => {
    const isDirty = untracked(dirty);

    if (!isDirty || force) {
      // very dangerous use of untracked here, don't do this everywhere :)
      // thanks to  u/synalx for the idea to use untracked here
      untracked(() => {
        initialValue.set(newValue);
        value.set(newValue);
      });
    }
  };

  return {
    id: opt?.id?.() ?? v7(),
    value,
    dirty,
    touched,
    error,
    label,
    required: computed(() => opt?.required?.() ?? false),
    disabled,
    readonly,
    hint: computed(() => opt?.hint?.() ?? ''),
    markAsTouched,
    markAllAsTouched,
    markAsPristine,
    markAllAsPristine,
    from: (isSignal(initial) ? initial.from : undefined) as FormControlSignal<T, TParent, TControlType>['from'],
    reconcile: (newValue: T) => internalReconcile(newValue),
    forceReconcile: (newValue: T) => internalReconcile(newValue, true),
    reset: () => {
      opt?.onReset?.();
      value.set(untracked(initialValue));
    },
    resetWithInitial: (initial: T) => {
      opt?.onReset?.();
      initialValue.set(initial);
      value.set(initial);
    },
    equal: eq,
    [CONTROL_SYMBOL]: true,
    controlType: (opt?.controlType ?? 'control') as TControlType,
    partialValue: patchValue as Signal<TPartialValue>,
  };
}

Ok we now have the implementation of the core formControl signal...as you can see it's basically what we specified in the type, with some typecasting required to make TS happy, this isn't a problem as it's only internal, the function signature guarentees type safety even with the casts. The provided value is either a derivation or a direct value if the formControl is being used standalone.

We've also made pretty much every property the user can provide a function, this allows us to say pass a signal (like another formControl.value) to the disable option & have the formControl react to that signal.

One thing of note is the use of untracked in the reconcile function, this is a very dangerous one so don't use it this way unless you know exactly when/why ;). Since untracked also opts out of any reactive context, this allows us to set signals from within a computed/linkedSignal computation. Using this could potentially cause infinite loops or unexpected change detection behavior, but the current implementation is safe in this specific case. But there is a good reason the Angular team decided to otherwise throw errors when doing that. :) Thanks to u/synalx for pointing this use of untracked out!

Form Group

Next up let's work on the form group, this is meant to be used to provide a control layer where we have a parent and controls that bind to child properties of that parent (just like a FormGroup), as such it requires derived signals to work.

As you can see bellow the form group is pretty much just a formControl, but also adds the children signal property so that we can access child controls & bind them to various inputs. Various properties such as .error, .touched, .markAllAsTouched read/write to itself and its children.

This is quite similar to Angulars internal FormGroup's purpose, but due to the ability to provide a reactive child function it also functions as a typesafe FormRecord replacement. Lets take a look, since I think the code will be more-or-less self-explanatory.

import { computed, isSignal, signal, untracked, type Signal, type WritableSignal } from '@angular/core';
import { formControl, type CreateFormControlOptions, type FormControlSignal } from './form-control';
import { isDerivedSignal, toFakeDerived, type DerivedSignal } from './primitives';

type SignalValue<T> = T extends Signal<infer U> ? U : never;

type DerivationPartialValues<TDerivations extends Record<string, FormControlSignal<any, any, any, any>>> = {
  [K in keyof TDerivations]: Exclude<SignalValue<TDerivations[K]['partialValue']>, undefined>;
};

export type FormGroupSignal<T, TDerivations extends Record<string, FormControlSignal<any, T, any, any>>, TParent = undefined> = FormControlSignal<T, TParent, 'group', Partial<DerivationPartialValues<TDerivations>>> & {
  children: Signal<TDerivations>; // typesafe signal of child controls
  ownError: Signal<string>; // the error signal holds an INVALID state if the group or its children are invalid, this only returns the validation results of the group, so that they can be displayed
};

type UnknownObject = Record<PropertyKey, unknown>;

function entries<T extends UnknownObject>(obj: T): [keyof T, T[keyof T]][] {
  return Object.entries(obj) as [keyof T, T[keyof T]][];
}

function values<T extends UnknownObject>(obj: T): T[keyof T][] {
  return Object.values(obj) as T[keyof T][];
}

export type CreateFormGroupOptions<T, TDerivations extends Record<string, FormControlSignal<any, T, any, any>>> = CreateFormControlOptions<T, 'group'> & {
  createBasePartialValue?: (value: T) => Partial<DerivationPartialValues<TDerivations>>;
};

export function formGroup<T, TDerivations extends Record<string, FormControlSignal<any, T, any, any>>, TParent = undefined>(initial: DerivedSignal<TParent, T> | T | WritableSignal<T>, providedChildren: (() => TDerivations) | TDerivations, opt?: CreateFormGroupOptions<T, TDerivations>): FormGroupSignal<T, TDerivations, TParent> {
  const valueSignal = isSignal(initial) ? initial : signal(initial);
  // we fake a derivation if not present, so that .from is present on the signal
  const value = isDerivation<TParent, T>(valueSignal) ? valueSignal : toFakeSignalDerivation<TParent, T>(valueSignal);

  // we allow for a function/signal to be passed, this case should only be used if the child controls change dependent upon something, say if a formControl is flipped into a formGroup.
  const children = typeof providedChildren === 'function' ? computed(() => providedChildren()) : computed(() => providedChildren);

  // array allows for easier handling
  const derivationsArray = computed(() => values(children()));

  const childrenDirty = computed(() => !!derivationsArray().length && derivationsArray().some((d) => d.dirty()));

  // by default dont compare object references, just use childrenDirtySignal
  const baseDirtyEq = opt?.dirtyEquality ?? opt?.equal ?? (() => true);

  // function which calls a signal becomes a signal
  const dirtyEquality = (a: T, b: T) => {
    return baseDirtyEq(a, b) && !childrenDirty();
  };

  // group control
  const ctrl = formControl<T, TParent, 'group'>(value, {
    ...opt,
    dirtyEquality,
    controlType: 'group',
    readonly: () => {
      // readonly if is readonly or all children are readonly
      if (opt?.readonly?.()) return true;
      return !!derivationsArray().length && derivationsArray().every((d) => d.readonly());
    },
    disable: () => {
      if (opt?.disable?.()) return true;
      return !!derivationsArray().length && derivationsArray().every((d) => d.disabled());
    },
  }) satisfies FormControlSignal<T, TParent, 'group'>;

  const childrenTouched = computed(() => !!derivationsArray().length && derivationsArray().some((d) => d.touched()));

  const touched = computed(() => ctrl.touched() || childrenTouched());

  const dirty = computed(() => ctrl.dirty() || childrenDirty());

  const childError = computed(() => {
    if (!derivationsArray().length) return '';
    return derivationsArray()
      .map((d) => d.error())
      .join('\n');
  });

  const error = computed(() => {
    const ownError = ctrl.error();
    if (ownError) return ownError;
    return childError() ? 'INVALID' : '';
  });

  const markAllAsTouched = () => {
    ctrl.markAllAsTouched();
    for (const ctrl of untracked(derivationsArray)) {
      ctrl.markAllAsTouched();
    }
  };

  const markAllAsPristine = () => {
    ctrl.markAllAsPristine();
    for (const ctrl of untracked(derivationsArray)) {
      ctrl.markAllAsPristine();
    }
  };

  const reconcile = (newValue: T) => {
    // set the children values based on the derivation of the new value
    for (const ctrl of untracked(derivationsArray)) {
      const from = ctrl.from;
      if (!from) continue;
      ctrl.reconcile(from(newValue));
    }
    ctrl.reconcile(newValue);
  };

  const forceReconcile = (newValue: T) => {
    for (const ctrl of untracked(derivationsArray)) {
      const from = ctrl.from;
      if (!from) continue;
      ctrl.forceReconcile(from(newValue));
    }
    ctrl.forceReconcile(newValue);
  };

  const createBaseValueFn = opt?.createBasePartialValue;

  const basePartialValue: Signal<Partial<DerivationPartialValues<TDerivations>>> = createBaseValueFn ? computed(() => createBaseValueFn(ctrl.value())) : computed(() => ({}));

  const partialValue = computed(() => {
    const obj: Partial<DerivationPartialValues<TDerivations>> = basePartialValue();
    if (!dirty()) return obj;

    for (const [key, ctrl] of entries(children())) {
      const pv = ctrl.partialValue();
      if (pv === undefined) continue;
      obj[key] = pv;
    }

    return obj;
  });

  return {
    ...ctrl,
    children,
    partialValue,
    reconcile,
    forceReconcile,
    ownError: ctrl.error,
    touched,
    dirty,
    error,
    markAllAsPristine,
    markAllAsTouched,
    reset: () => {
      for (const ctrl of untracked(derivationsArray)) {
        ctrl.reset();
      }
      ctrl.reset();
    },
    resetWithInitial: (initial: T) => {
      for (const ctrl of untracked(derivationsArray)) {
        const from = ctrl.from;
        from ? ctrl.resetWithInitial(from(initial)) : ctrl.reset();
      }
      ctrl.resetWithInitial(initial);
    },
  };
}

Form Array

While the basic formControl & formGroup should handle most usecases there is an edge case covered by angulars FormArray, this is where we need an array of controls instead of just an array of values, which we add/remove controls from.

If your're working with just an array of something, where the values don't require child controls, you should just use a basic formControl of type T[].

We've also added built-in reconciliation of child formControls. This allows us to react to value changes, but save on compute by skiping the creation for existing control. This is not necessary so you can replace it with a simple computed if you want to remove reconciliation, but I do think it's pretty cool. ;)

I also included some of our array validators, to make adding specific validation easy & integration with UI elements easier.

import { computed, linkedSignal, untracked, type Signal, type WritableSignal } from '@angular/core';
import { formControl, type CreateFormControlOptions, type FormControlSignal } from './form-control';
import { type SignalValue } from './form-group';
import { derived, type DerivedSignal } from './primitives';

function minArrayLengthMsg(min: number, elementLabel: string) {
  return `Min ${min} ${elementLabel}`;
}

function maxArrayLengthMsg(max: number, elementLabel: string) {
  return `Max ${max} ${elementLabel}`;
}

function minArrayLengthValidator(min: number, elementLabel: string) {
  const msg = minArrayLengthMsg(min, elementLabel);
  return (val: any[]) => (val.length >= min ? '' : msg);
}

function maxArrayLengthValidator(max: number, elementLabel: string) {
  const msg = maxArrayLengthMsg(max, elementLabel);
  return (val: any[]) => (val.length <= max ? '' : msg);
}

export type ArrayValidatorOpt = {
  min?: number;
  max?: number;
  elementLabel?: string;
};

export function arrayValidator<T extends any[]>(opt: ArrayValidatorOpt = {}) {
  const min = opt.min ?? 0;
  const max = opt.max ?? Number.MAX_SAFE_INTEGER;
  const elementLabel = opt.elementLabel ?? 'items';

  const minVal = minArrayLengthValidator(min, elementLabel);
  const maxVal = maxArrayLengthValidator(max, elementLabel);

  return (val: T) => minVal(val) || maxVal(val);
}

export type FormArraySignal<T, TIndividualState extends FormControlSignal<T, any, any, any> = FormControlSignal<T, any, any, any>, TParent = undefined> = FormControlSignal<T[], TParent, 'array', Exclude<SignalValue<TIndividualState['partialValue']>, null | undefined>[] | undefined> & {
  ownError: Signal<string>;
  children: Signal<TIndividualState[]>;
  push: (value: T) => void; // add new control with value
  remove: (index: number) => void; // remove at index
  min: Signal<number>; // for display purposes
  max: Signal<number>; // for display purposes
  canAdd: Signal<boolean>; // disable add button if false
  canRemove: Signal<boolean>; // disable remove buttons if false
};

export type CreateFormArraySignalOptions<T, TIndividualState extends FormControlSignal<T, any, any, any>> = CreateFormControlOptions<T> & {
  min?: () => number;
  max?: () => number;
  elementLabel?: () => string;
  toPartialValue?: (v: T) => Exclude<SignalValue<TIndividualState['partialValue']>, null | undefined>;
};

function createReconcileChildren<T, TIndividualState extends FormControlSignal<T, any, any, any>>(factory: (val: DerivedSignal<T[], T>, idx: number, opt?: CreateFormControlOptions<T>) => TIndividualState, opt?: CreateFormControlOptions<T>) {
  return (length: number, source: WritableSignal<T[]>, prev?: TIndividualState[]): TIndividualState[] => {
    if (!prev) {
      const nextControls = [];

      for (let i = 0; i < length; i++) {
        nextControls.push(
          factory(
            derived(source, {
              from: (v) => v[i],
              onChange: (next) => source.update((cur) => cur.map((v, idx) => (idx === i ? next : v))),
            }),
            i,
            opt,
          ),
        );
      }

      return nextControls;
    }

    const next = [...prev];

    if (length < prev.length) {
      next.splice(length);
    } else if (length > prev.length) {
      for (let i = prev.length; i < length; i++) {
        next.push(
          factory(
            derived(source, {
              from: (v) => v[i],
              onChange: (next) => source.update((cur) => cur.map((v, idx) => (idx === i ? next : v))),
            }),
            i,
            opt,
          ),
        );
      }
    }

    return next;
  };
}

export function formArray<T, TIndividualState extends FormControlSignal<T, any, any, any> = FormControlSignal<T, any, any, any>, TParent = undefined>(initial: T[] | DerivedSignal<TParent, T[]>, factory: (val: DerivedSignal<T[], T>, idx: number, opt?: CreateFormControlOptions<T>) => TIndividualState, opt?: CreateFormArraySignalOptions<T, TIndividualState>): FormArraySignal<T, TIndividualState, TParent> {
  const eq = opt?.equal ?? Object.is;

  const arrayEqual = (a: T[], b: T[]) => {
    if (a.length !== b.length) return false;
    if (!a.length) return true;

    return a.every((v, i) => eq(v, b[i]));
  };

  const min = computed(() => opt?.min?.() ?? 0);
  const max = computed(() => opt?.max?.() ?? Number.MAX_SAFE_INTEGER);
  const elementLabel = computed(() => opt?.elementLabel?.() ?? 'items');

  const validator = () =>
    arrayValidator<T[]>({
      min: min(),
      max: max(),
      elementLabel: elementLabel(),
    });

  const arrayOptions: CreateFormControlOptions<T[], 'array'> = {
    ...opt,
    equal: arrayEqual,
    validator,
    dirtyEquality: (a, b) => a.length === b.length,
    controlType: 'array',
  };

  const ctrl = formControl<T[], TParent, 'array'>(initial, arrayOptions) satisfies FormControlSignal<T[], TParent, 'array'>;

  const length = computed(() => ctrl.value().length);

  const reconcileChildren = createReconcileChildren<T, TIndividualState>(factory, opt);

  // linkedSignal used to re-use previous value so that only length changes are affected and existing controls are kept, but updated
  const children = linkedSignal<number, TIndividualState[]>({
    source: () => length(),
    computation: (len, prev) => reconcileChildren(len, ctrl.value, prev?.value),
  });

  const ownError = computed(() => validator()(ctrl.value()));

  const error = computed((): string => {
    if (ownError()) return ownError();
    if (!children().length) return '';
    return children().some((c) => c.error()) ? 'INVALID' : '';
  });

  const dirty = computed(() => {
    if (ctrl.dirty()) return true;
    if (!children().length) return false;
    return children().some((c) => c.dirty());
  });

  const markAllAsTouched = () => {
    ctrl.markAllAsTouched();
    for (const c of untracked(children)) {
      c.markAllAsTouched();
    }
  };
  const markAllAsPristine = () => {
    ctrl.markAllAsPristine();
    for (const c of untracked(children)) {
      c.markAllAsPristine();
    }
  };

  const toPartialValue = opt?.toPartialValue ?? ((v: T) => v);
  const partialValue = computed(() => {
    if (!dirty()) return undefined;
    return children().map((c) => {
      const pv = c.partialValue();
      if (pv) return pv;
      if (c.controlType === 'control') return undefined;

      // return full value for  child objects/arrays as this cannot be partially patched without idx
      return toPartialValue(c.value());
    });
  });

  const touched = computed(() => ctrl.touched() || !!(children().length && children().some((c) => c.touched())));

  const reconcile = (newValue: T[]) => {
    const ctrls = untracked(children);

    for (let i = 0; i < newValue.length; i++) {
      ctrls.at(i)?.reconcile(newValue[i]); // reconcile existing controls that are relevant addition/removal will be handled after ctrl.reconcile through linkedSignal
    }

    ctrl.reconcile(newValue);
  };

  const forceReconcile = (newValue: T[]) => {
    const ctrls = untracked(children);

    for (let i = 0; i < newValue.length; i++) {
      ctrls.at(i)?.forceReconcile(newValue[i]);
    }

    ctrl.forceReconcile(newValue);
  };

  return {
    ...ctrl,
    ownError,
    error,
    touched,
    children,
    dirty,
    markAllAsTouched,
    markAllAsPristine,
    min,
    max,
    partialValue,
    canAdd: computed(() => !ctrl.disabled() && !ctrl.readonly() && length() < max()),
    canRemove: computed(() => !ctrl.disabled() && !ctrl.readonly() && length() > min()),
    reconcile,
    forceReconcile,
    reset: () => {
      for (const c of untracked(children)) {
        c.reset();
      }
      ctrl.reset();
    },
    resetWithInitial: (initial: T[]) => {
      const ctrls = untracked(children);
      for (let i = 0; i < initial.length; i++) {
        ctrls.at(i)?.resetWithInitial(initial[i]);
      }
      ctrl.resetWithInitial(initial);
    },
    push: (next) => ctrl.value.update((cur) => [...cur, next]),
    remove: (idx) => ctrl.value.update((cur) => cur.filter((_, i) => i !== idx)),
  };
}

Angular material & NgModel

With the form primitives we've created, you can now create any form and bind directly to say an inputs value property.

If you however want/need to use ngModel under the hood, as you would due to say Angular Material's form-field being tightly coupled to NgModel, you'll need to propagate the touched state separately as well as creating a validation directive. This can easily be done with an effect within the control component for example:

import { computed, Directive, effect, input } from '@angular/core';
import { NG_VALIDATORS, type Validator } from '@angular/forms';

@Directive({
  selector: '[ngModel][appProvidedError]',
  standalone: true,
  providers: [
    {
      provide: NG_VALIDATORS,
      useExisting: ProvidedErrorValidator,
      multi: true,
    },
  ],
})
export class ProvidedErrorValidator implements Validator {
  readonly appProvidedError = input('');
  private onChange = () => {
    // noop
  };

  private readonly valid = computed(() => {
    return !this.appProvidedError();
  });

  constructor() {
    effect(() => {
      this.valid();
      this.onChange();
    });
  }

  validate() {
    return !this.valid() ? { providedError: this.appProvidedError() } : null;
  }

  registerOnValidatorChange(fn: () => void) {
    this.onChange = fn;
  }
}

@Component({
  selector: 'app-text-input',
  imports: [FormsModule, ProvidedErrorValidator],
  template: `
<!-- value example -->
<input [(value)]="state().value" [disabled]="state().disabled()" [readonly]="state().readonly()" [required]="state().required()" [class.error]="state().touched() && state().error()" (blur)="state().markAsTouched()" />

<!-- ngModel example -->
<input [(ngModel)]="state().value" [disabled]="state().disabled()" [readonly]="state().readonly()" [required]="state().required()" [appProvidedError]="state().error()" (blur)="state().markAsTouched()" />


@if (state().touched() && state().error() {
 <span class="error">{{state().error()}}</span>
}
`,
})
export class TextInputComponent<TParent = undefined> {
  readonly state = input.required<FormControl<string | null, TParent>>();

  private readonly model = viewChild.required(NgModel);
  constructor() {
    /* We could destroy this effect in some other cases where state the   
    "state control" never changes, in this case, since it's an input we 
    keep it so that the component is more re-usable */
    effect(() => {
      if (!this.state().touched()) return;
      this.model().control.markAsTouched();
    });
  }
}

In our case we abstract it a bit more so that it's easier to construct forms with reactive state, here's our string field component:

export type StringValidatorOpt = {
  required?: boolean;
  minLength?: number;
  maxLength?: number;
  pattern?: string;
  not?: string[];
  blanks?: boolean;
  exact?: string | null;
  oneOf?: string[];
};

export type StringStateOpt = Omit<CreateFormControlOptions<string | null, 'control'>, 'validator' | 'required'> & {
  validation?: () => StringValidatorOpt;
  autocomplete?: () => AutoFill;
  placeholder?: () => string;
};

export function createStringState<TParent = undefined>(value: string | null | DerivedSignal<TParent, string | null>, opt?: StringStateOpt): StringState<TParent> {
  const validation = computed(() => opt?.validation?.() ?? {});

  // for the sake of brevity I've only provided the StringValidatorOpt interface, not the validators themselves
  const validator = () => stringValidator(validation());

  const state = formControl<string | null, TParent, 'control'>(value, {
    ...opt,
    validator,
    required: () => validation().required ?? false,
  }) as FormControlSignal<string | null, TParent, 'control'>;

  return {
    ...state,
    autocomplete: computed(() => opt?.autocomplete?.() ?? 'off'),
    placeholder: computed(() => opt?.placeholder?.() ?? ''),
    type: 'string',
  };
}

@Component({
  selector: 'app-string-field',
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [FormsModule, MatFormFieldModule, MatInputModule, ProvidedErrorValidator, MatIcon],
  encapsulation: ViewEncapsulation.None,
  host: {
    '[class.app-string-field]': 'true',
  },
  template: `
    <mat-form-field [appearance]="appearance()" [floatLabel]="floatLabel()" [subscriptSizing]="subscriptSizing()" [hideRequiredMarker]="hideRequiredMarker()">
      <mat-label>{{ state().label() }}</mat-label>

      @if (iconPrefix()) {
        <mat-icon matPrefix>{{ iconPrefix() }}</mat-icon>
      }

      <input matInput [(ngModel)]="state().value" [autocomplete]="state().autocomplete()" [disabled]="state().disabled()" [readonly]="state().readonly()" [required]="state().required()" (blur)="state().markAsTouched()" [placeholder]="state().placeholder()" [appProvidedError]="state().error()" />

      <mat-error>{{ state().error() }}</mat-error>

      @if (state().hint()) {
        <mat-hint>{{ state().hint() }}</mat-hint>
      }

      <ng-content />
    </mat-form-field>
  `,
  styles: `
    .app-string-field {
      display: contents;
    }
  `,
})
export class StringFieldComponent<TParent = undefined> {
  readonly appearance = input<MatFormFieldAppearance>(inject(MAT_FORM_FIELD_DEFAULT_OPTIONS, { optional: true })?.appearance ?? 'outline');
  readonly floatLabel = input<FloatLabelType>(inject(MAT_FORM_FIELD_DEFAULT_OPTIONS, { optional: true })?.floatLabel ?? 'auto');
  readonly subscriptSizing = input<SubscriptSizing>(inject(MAT_FORM_FIELD_DEFAULT_OPTIONS, { optional: true })?.subscriptSizing ?? 'fixed');
  readonly hideRequiredMarker = input<boolean>(inject(MAT_FORM_FIELD_DEFAULT_OPTIONS, { optional: true })?.hideRequiredMarker ?? false);

  readonly iconPrefix = input<string>();

  readonly state = input.required<StringState<TParent>>();

  private readonly model = viewChild.required(NgModel);

  constructor() {
    effect(() => {
      if (!this.state().touched()) return;
      this.model().control.markAsTouched();
    });
  }
}

Conclusion

So we now have a great way of modeling reactive state & integrating it with forms.

We've been using these primitives & abstractions internally for a few months now and after a bit of explanation to the team on what the purposes of derivations are, they've really started to love this approach in form state management.

If you decide to give it a shot & have some input, or if you have any questions feel free to reach out :).

Before I go I'd like to share an example of using these primitives fully, just so you can visualize how it integrates. Please note that the github project linked uses a "beta" version of these primitives, so there are some minor differences. The ones in the article are more refined :).

Other than that I'll see you in the next article (hopefully less than a year from now), happy coding! 🚀

Fun-grained reactivity in Angular: Part 1 – Primitives

Miha Mulec — Thu, 13 Mar 2025 07:32:53 +0000

This post was originally made on our company's blog in May 2024. I'm reposting it here, so that the series can be continued seamlessly :)

In the ancient past of 2023 Angular’s v16 brought signal primitives to the framework, starting the path towards a future of fine-grained reactivity. I won’t waste either of our times here by explaining the benefits of signal-based reactivity as there’s already a bunch of great articles on that topic, needless to say, we’re fully on-board with this change here at Marand.
In this series we’ll endeavor to evolve several existing parts of angular, namely forms (NgModel/FormControl) & http (HttpClient) into a more signal-y future. To start that journey, we’ll first need to develop some core primitives that will help us along the way.

Mutability & Recycling

Back in the dev. preview version of Signals they had 3 main functions that allowed us to change the value (set, update & mutate).
We found mutate very useful, since one of the main benefits of signals is the aspect of their increased performance. Of course, immutability tends to be easier to reason about & is why most frameworks have focused on it so much, but there are lots of occasions where say de-structuring an array is just needlessly creating GC calls, never mind that under the hood things like memcpy still have a cost. Also, and this may just be me, but I've seen too many videos by ThePrimeagen to not get a "funny" feeling whenever I destructure an array or re-build a set just to force a re-render. :)

Sadly, this was removed in ng17 with the full release of signals, enforcing immutability, likewise the optional equality function was of no help since if the object was mutated in-line both a & b were the same when the function was called & angular even through an error if you force returned true within it for the same object reference. We we’re able to “hack” by messing around with epochs and whatnot hidden within the SIGNAL symbol but it wasn’t a good solution. Lucky for us they removed that error somewhere around 17.0.6, I assume due to the at-the-time upcoming model signal. This allows us to cleanly add this functionality back in. :)

import { ValueEqualityFn, WritableSignal, signal } from "@angular/core";

const { is } = Object;

export type MutableSignal<T> = WritableSignal<T> & {
  mutate: WritableSignal<T>["update"];
};

export function mutable<T>(initial: T, opts?: { equal?: ValueEqualityFn<T> }) {
  const baseEqual = opts?.equal ?? is;
  let trigger = false;

  const equal: ValueEqualityFn<T> = (a, b) => {
    if (trigger) return false;
    return baseEqual(a, b);
  };

  const sig = signal(initial, { equal }) as MutableSignal<T>;
  sig.mutate = (fn: (v: T) => T) => {
    trigger = true;
    sig.update(fn);
    trigger = false;
  };

  return sig;
}

This allows us to mutate objects in-line & will serve as the core building block we build upon. It's easy enough to test out if we compare the outputs of an effect that triggers when its value changes:

import { mutable } from "./mutable";
import { signal, effect } from "@angular/core";

const base = signal([1, 2, 3]);
const mut = mutable([1, 2, 3]);

setTimeout(() => {
  base.update((cur) => {
    cur.push(4);
    return cur;
  });
  mut.mutate((cur) => {
    cur.push(4);
    return cur;
  });
});

effect(() => {
  console.log(base()); // logs [1, 2, 3]
});

effect(() => {
  console.log(mut()); // logs [1, 2, 3] then [1, 2, 3, 4]
});

As with everything mutability/immutability have their places, we're just giving ourselves back that choice. :)

Stores

Now we're going to start looking for inspiration from other frameworks & libraries like SolidJS, it is after all the most mature signal-based framework out there & can serve as a great source of inspiration for what the future of Angular's fine-grained reactivity will look like. First up, we'll look at stores.

You can check out Solid's version of stores here. Essentially, they are a way to encapsulate more complex state like objects.

import { ValueEqualityFn, WritableSignal } from "@angular/core";
import { mutable } from "./mutable";

type StoreKey<T> = T extends object ? keyof T : never;

type StorePath<T> = T extends object
  ? [StoreKey<T>, ...StorePath<T[StoreKey<T>]>]
  : [];

type ResolvePathType<T, Path extends StorePath<T>> = Path extends []
  ? T // Base case:  Empty path, type is just T itself
  : Path extends [infer K, ...infer Rest]
  ? K extends keyof T
    ? Rest extends StorePath<T[K]> // Recurse if K is a key of T
      ? ResolvePathType<T[K], Rest>
      : never
    : never // Handle keys invalid for T
  : never;

type SignalStore<T> = WritableSignal<T> & {
  updateProp<K extends StorePath<T>>(
    path: K,
    value: ResolvePathType<T, K>
  ): void;
};

export function store<T>(
  value: T,
  opt?: { equal: ValueEqualityFn<T> }
): SignalStore<T> {
  const sig = mutable(value, opt);

  (sig as WritableSignal<T> as SignalStore<T>).updateProp = (path, value) => {
    sig.mutate((state) => {
      let obj = state as any;
      for (let i = 0; i < path.length - 1; i++) {
        obj = obj[path[i]];
      }
      obj[path.at(-1)] = value;

      return state;
    });
  };

  return sig as WritableSignal<T> as SignalStore<T>;
}

Due to our use of mutable under the hood we can modify the state in-place, while triggering the signal to update. We could also create a completely immutable version of this that destructures every object in the path, but I like to keep things as performant as possible. :)

There's also a bit of complicated typescript there but it just serves for accurate type inference when using the stores updateProp method. Here's how we could use it:

import { store } from "./store";

const test = store({ a: { b: 1 }, c: 2 });

effect(() => {
  console.log(test().a.b); // logs 1 & will log every time any attribute or the object itself changes
});

This is nice, but it has a problem, the effect will trigger even when c changes, which is fine if we want that, but we should allow for more granular control. To achieve this we need to introduce store slices to the mix.

import { ValueEqualityFn, WritableSignal, computed } from "@angular/core";
import { MutableSignal, mutable } from "./mutable";

type StoreKey<T> = T extends object ? keyof T : never;

type StorePath<T> = T extends object
  ? [StoreKey<T>, ...StorePath<T[StoreKey<T>]>]
  : [];

type ResolvePathType<T, Path extends StorePath<T>> = Path extends []
  ? T // Base case:  Empty path, type is just T itself
  : Path extends [infer K, ...infer Rest]
  ? K extends keyof T
    ? Rest extends StorePath<T[K]>
      ? ResolvePathType<T[K], Rest>
      : never
    : never // Handle keys invalid for T
  : never;

type AssignableSignalStore<T> = MutableSignal<T> & {
  updateProp<K extends StorePath<T>>(
    path: K,
    value: ResolvePathType<T, K>
  ): void;
};

export type SignalStore<T> = WritableSignal<T> & {
  updateProp<K extends StorePath<T>>(
    path: K,
    value: ResolvePathType<T, K>
  ): void;
};

function createPropUpdater<T>(sig: MutableSignal<T>) {
  return <K extends StorePath<T>>(
    path: StorePath<T>,
    value: ResolvePathType<T, K>
  ) => {
    sig.mutate((state) => {
      let obj = state as any;
      for (let i = 0; i < path.length - 1; i++) {
        obj = obj[path[i]];
      }
      obj[path.at(-1)] = value;
      return state;
    });
  };
}

function createStore<T>(value: T, opt?: { equal: ValueEqualityFn<T> }) {
  const sig = mutable(value, opt) as AssignableSignalStore<T>;
  sig.updateProp = createPropUpdater(sig);
  return sig;
}

export function store<T>(
  value: T,
  opt?: { equal: ValueEqualityFn<T> }
): SignalStore<T> {
  return createStore(value, opt);
}

export type SlicedStore<T> = SignalStore<T> & {
  slices: {
    [K in keyof T]: Slice<T[K]>;
  };
};

type AssignableSlicedStore<T> = AssignableSignalStore<T> & {
  slices: {
    [K in keyof T]: AssignableSlice<T[K]>;
  };
};

type Slice<T> = T extends object
  ? T extends null
    ? WritableSignal<T>
    : SlicedStore<T>
  : WritableSignal<T>;
type AssignableSlice<T> = T extends object
  ? T extends null
    ? MutableSignal<T>
    : AssignableSlicedStore<T>
  : MutableSignal<T>;

function keys<T extends object>(obj: T): (keyof T)[] {
  if (!obj) return [];
  return Object.keys(obj) as (keyof T)[];
}

function slicedStoreWithParent<T extends object, K extends keyof T>(
  parentStore: AssignableSlicedStore<T>,
  key: K
) {
  const value = parentStore()[key];
  if (typeof value !== "object" || value === null) return null;

  const sig = computed(() => parentStore()[key]) as AssignableSlicedStore<
    typeof value
  >;

  sig.set = (value) => {
    parentStore.mutate((state) => {
      state[key] = value;
      return state;
    });
  };

  sig.update = (fn) => sig.set(fn(sig()));
  sig.mutate = (fn) => sig.set(fn(sig()));
  sig.updateProp = createPropUpdater(sig);

  sig.slices = keys(value).reduce((acc, key) => {
    const sigVal = sig()[key];

    if (typeof sigVal === "object" && sigVal !== null) {
      const subStore = slicedStoreWithParent(sig, key);
      if (subStore) acc[key] = subStore as typeof acc[typeof key];
      return acc;
    }

    const propSig = computed(() => sig()[key]) as AssignableSlice<
      typeof sigVal
    >;
    propSig.set = (value: typeof sigVal) => {
      sig.mutate((state) => {
        state[key] = value;
        return state;
      });
    };
    propSig.update = (fn: any) => propSig.set(fn(propSig()));
    propSig.mutate = (fn: any) => propSig.set(fn(propSig()));
    acc[key] = propSig as typeof acc[typeof key];

    return acc;
  }, {} as typeof sig.slices);

  return sig;
}

export function slicedStore<T extends object>(
  value: T,
  opt?: { equal: ValueEqualityFn<T> }
): SlicedStore<T> {
  const sig = mutable(value, opt) as AssignableSlicedStore<T>;
  sig.updateProp = createPropUpdater(sig);

  sig.slices = keys(value).reduce((acc, key) => {
    const sigVal = sig()[key];

    if (typeof sigVal === "object" && sigVal !== null) {
      const subStore = slicedStoreWithParent(sig, key);
      if (subStore) acc[key] = subStore as typeof acc[typeof key];
      return acc;
    }

    const propSig = computed(() => sig()[key]) as AssignableSlice<
      typeof sigVal
    >;
    propSig.set = (value: typeof sigVal) => {
      sig.mutate((state) => {
        state[key] = value;
        return state;
      });
    };
    propSig.update = (fn: any) => propSig.set(fn(propSig()));
    propSig.mutate = (fn: any) => propSig.set(fn(propSig()));
    acc[key] = propSig as typeof acc[typeof key];

    return acc;
  }, {} as typeof sig.slices);

  return sig;
}

The main diference to the "core" code of the store here is some additional abstraction to avoid code duplication, we've however now added slices to the mix by creating computeds & mapping their set/update/mutate methods so that they correctly update the parent store. This will still therefore trigger the parents effect as seen above but we can now access specific computed values, that only trigger when their equality check changes. As we're modifying stuff in-place, these should change when we update a specific slice. Adding set/update/mutate to the slices may seem weird now, since we dont really need them, but they will be useful when we start building signal based forms. If you sort-of squint, you can maybe see how a sliced store could replace a FormGroup in the future, or at least provide a building block for it.

import { store } from "./store";

const test = store({ a: { b: 1 }, c: 2 });

effect(() => {
  console.log(test().c); // same as above logs any time anything changes
});

effect(() => {
  console.log(test.slices.c()); // only logs when c changes
});

Creating a lot of computed values up-front may seem like a waste, but beyond some added cost when instantiating the store it shouldn't affect anything since unlike Solid, Angular's computeds are evaluated lazily (when they are subscribed to). Here's a quick example:

// Solid
function App() {
  const [count, setCount] = createSignal(1)
  const double = createMemo(() => {
    console.log('computing') // logs even though it's never used
    return count() * 2
  })

  return (
    <>
      {count()}
    </>
  )
}
// Angular
@Component({
  ...,
  template: `{{count()}}`
})
export class AppComponent {
  count = signal(1);
  double = computed(() => {
    console.log('computing'); // never logs
    return this.count() * 2;
  });
}

Resources & Suspense

Resources are a core SolidJS primitive used for asynchronous data. While Angular already has a way of handling async data through RxJs Observables, we can still do some cool stuff by taking inspiration from Solid. Ideally we'd want to have an easy-to-use primitive so that we can soften the learning curve for new Angular developers. Anyway here's a basic implementation:

import { Signal, ValueEqualityFn, WritableSignal, signal } from "@angular/core";
import {
  BehaviorSubject,
  Observable,
  catchError,
  from,
  isObservable,
  of,
  switchMap,
  tap,
} from "rxjs";
import { MutableSignal, mutable } from "./mutable";

type AssignableResource<T, F = void> = MutableSignal<T | F> & {
  loading: WritableSignal<boolean>;
  error: WritableSignal<string | null>;
  refetch: () => void;
};

export type Resource<T, F = void> = Signal<T | F> & {
  loading: Signal<boolean>;
  error: Signal<string | null>;
  refetch: () => void;
  mutate: MutableSignal<T | F>["mutate"];
};

type CreateResourceOptions<T, F = void> = {
  equal?: ValueEqualityFn<T | F>;
  fallback?: F;
};

const { is } = Object;

export function resource<T, F = void>(
  source: () => Promise<T> | Observable<T>,
  opts?: CreateResourceOptions<T, F>
): Resource<T, F> {
  const equal = (opts?.equal ?? is) as ValueEqualityFn<T | F>;
  const fallback = opts?.fallback as F;

  const trigger$ = new BehaviorSubject<void>(undefined);

  const state = mutable<T | F>(fallback, { equal }) as AssignableResource<T, F>;

  state.loading = signal(false);
  state.error = signal(null);

  const connection = source();
  const source$ = isObservable(connection) ? connection : from(connection);

  trigger$
    .pipe(
      tap(() => state.loading.set(true)),
      switchMap(() => source$),
      catchError(() => {
        state.error.set("Error fetching data");
        return of(fallback);
      }),
      tap(() => state.loading.set(false))
    )
    .subscribe((value) => state.set(value));

  state.refetch = () => trigger$.next(undefined);

  return state;
}

I've added support for both fetch based sources & observables so that the implementer can either use HttpClient with all its bells & whistles, or just use a simple fetch call if they don't need it. While this does handle the basic concept it leaves a lot to be desired. We can improve upon various things like error handling, but any other improvements like caching, optimistic updates or pagination should be their own primitive that builds upon this one, as we did with stores & slices. There is however one thing I'd like the very core resource primitive to handle, and that's suspense.

The React team released Suspense back in version 16.6, I honestly haven't taken a look at it for a while, but I do remember some weirdness with it by throwing promises? That may have been a fever dream though, not sure... Anyway, I'll let the code do most of the talking, here's what a basic implementation of Suspense could look like in Angular:

import { NgTemplateOutlet } from "@angular/common";
import {
  ChangeDetectionStrategy,
  Component,
  Directive,
  InjectionToken,
  NgModule,
  TemplateRef,
  computed,
  contentChild,
  inject,
} from "@angular/core";
import { mutable } from "./mutable";
import { Resource } from "./resource";

const SUSPENSE_TOKEN = new InjectionToken<SuspenseComponent>("APP_SUSPENSE");

export const provideSuspense = () => inject(SUSPENSE_TOKEN, { optional: true });

@Directive({
  selector: "[onSuspenseLoading]",
  standalone: true,
})
export class SuspenseLoadingDirective {}

@Directive({
  selector: "[onSuspenseError]",
  standalone: true,
})
export class SuspenseErrorDirective {}

@Component({
  selector: "app-suspense",
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  imports: [NgTemplateOutlet],
  // We're providing the component itself, due to how Angular handles DI this will ensure that resources will grab the nearest parent Suspense boundry if it exists.
  providers: [{ provide: SUSPENSE_TOKEN, useExisting: SuspenseComponent }],
  // As the content is rendered initially i.e. when no resources have been registered all resources are instatiated and begin calling at the same time (unless some other @if/ngIf prevents it).
  template: `
        @if (!loading() && !error()) {
            <ng-content />
        } @else if (loading()) {
            <ng-container [ngTemplateOutlet]="loadingTemplate() || null" />
        } @else {
            <ng-container [ngTemplateOutlet]="errorTemplate() || null" />
        }
    `,
})
export class SuspenseComponent {
  protected readonly resources = mutable<Resource<any>[]>([]);
  protected readonly loading = computed(
    () => !this.resources().every((r) => !r.loading())
  );
  protected readonly error = computed(
    () => !this.resources().every((r) => !r.error())
  );

  protected readonly loadingTemplate = contentChild(SuspenseLoadingDirective, {
    read: TemplateRef,
  });
  protected readonly errorTemplate = contentChild(SuspenseErrorDirective, {
    read: TemplateRef,
  });

  // Both register and unregister can be handled within the resource creation function through DI.
  register(resource: Resource<any>) {
    const len = this.resources().length;
    this.resources.mutate((cur) => {
      cur.push(resource);
      return cur;
    });
    return len;
  }

  // cleanup for when the component containing the resource is destroyed
  deregister(index: number) {
    this.resources.mutate((cur) => {
      cur.splice(index, 1);
      return cur;
    });
  }
}

@NgModule({
  imports: [
    SuspenseComponent,
    SuspenseErrorDirective,
    SuspenseLoadingDirective,
  ],
  exports: [
    SuspenseComponent,
    SuspenseErrorDirective,
    SuspenseLoadingDirective,
  ],
})
export class SuspenseModule {}

This is a pretty basic implementation but I like that it gives us a new way to compose async data while preventing waterfalls. I've also added error handling to it because I couldn't come up with a reason to have a separate "ErrorBoundry" like React does. To finish up let's add the integration to the resource function as well as some other "nice-to-haves":

import {
    DestroyRef,
    Signal,
    ValueEqualityFn,
    WritableSignal,
    inject,
    signal,
} from '@angular/core';
import {
    Observable,
    Subject,
    Subscription,
    catchError,
    first,
    isObservable,
    of,
    switchMap,
    takeUntil,
    tap,
} from 'rxjs';
import { MutableSignal } from '../mutable';
import { provideSuspense } from '../suspense';
import {
    createEquals,
    createErrorResolver,
    createFallback,
    createStorage,
} from './util';

type AssignableResource<
    T,
    F = void,
    S extends MutableSignal<T | F> = MutableSignal<T | F>,
> = S & {
    loading: WritableSignal<boolean>;
    error: WritableSignal<string | null>;
    refetch: () => void;
    destroy: () => void;
};

export type Resource<
    T,
    F = void,
    S extends MutableSignal<T | F> = MutableSignal<T | F>,
> = S & {
    loading: Signal<boolean>;
    error: Signal<string | null>;
    refetch: () => void;
    destroy: () => void;
};

export type CreateResourceOptions<
    T,
    F = void,
    SIGNAL extends MutableSignal<T | F> = MutableSignal<T | F>,
    E = any,
> = {
    equal?: ValueEqualityFn<T | F>;
    fallback?: F | (() => F);
    storage?: (
        initial: T | F,
        opts?: { equal?: ValueEqualityFn<T | F> }
    ) => SIGNAL;
    defer?: true;
    resolveError?: (error: E) => string;
    onError?: (error: E) => void;
};

export function resource<
    T,
    F = void,
    S extends MutableSignal<T | F> = MutableSignal<T | F>,
    E = any,
>(
    source: () => Promise<T> | Observable<T>,
    opts?: CreateResourceOptions<T, F, S, E>
): Resource<T, F, S> {
    const destroyRef = inject(DestroyRef);
    const boundry = provideSuspense();
    const equal = createEquals(opts?.equal);
    const fallback = createFallback(opts?.fallback);
    const storage = createStorage(opts?.storage);
    const resolveError = createErrorResolver(opts?.resolveError);

    const destroy$ = new Subject<void>();

    const state = storage(fallback(), { equal }) as AssignableResource<T, F, S>;

    state.loading = signal(false);
    state.error = signal(null);

    let source$: Observable<T> | null = null;

    let sub = new Subscription();

    const fetchFromSource = () => {
        return of(null)
            .pipe(
                tap(() => state.loading.set(true)),
                switchMap(() => {
                    if (source$) return source$;
                    const connection = source();
                    if (isObservable(connection)) {
                        source$ = connection;
                        return source$;
                    } else {
                        source$ = null;
                    }
                    return connection;
                }),
                catchError((err) => {
                    state.error.set(resolveError(err));
                    opts?.onError?.(err);
                    return of(fallback());
                }),
                tap(() => state.loading.set(false)),
                first(),
                takeUntil(destroy$)
            )
            .subscribe((value) => state.set(value));
    };

    if (!opts?.defer) {
        sub = fetchFromSource();
    }

    state.refetch = () => {
        sub.unsubscribe();
        sub = fetchFromSource();
    };
    let index = -1;

    state.destroy = () => {
        boundry?.deregister(index);
        index = -1;
        destroy$.next();
        destroy$.complete();
    };

    index = boundry?.register(state) ?? -1;

    destroyRef.onDestroy(() => {
        boundry?.deregister(index);
    });

    return state;
}

As you can see we inject the boundry (optionally) & if one exists we bind/unbind with it when required. I've also added a few quality of life features like defering the first call to the source, a way to resolve errors & a way to provide your own storage signal or at least create it yourself. This allows for some basic storage functionality like saving the value in localStorage for example:

type Todo = {
    id: string;
    name: string;
};

function fetchTodos(): Promise<Todo[]> {
    return fetch('https://jsonplaceholder.typicode.com/todos')
        .then((r) => r.json())
        .catch(() => []);
}

function storeTodos(todos: Todo[]) {
    localStorage.setItem('todos', JSON.stringify(todos));
}

function getStoredTodos(): Todo[] {
    const found = localStorage.getItem('todos');
    return found ? JSON.parse(found) : [];
}

@Component({
  ...
})
export class AppComponent {
    readonly state = resource(fetchTodos, {
        fallback: getStoredTodos,
        storage: (initial, opts) => {
            const sig = mutable(initial, opts);
            effect(() => storeTodos(sig()));
            return sig;
        },
    });
}

Conclusion

This is an ongoing experiment in evolving common Angular patterns using a signal-based methodology. If these concepts resonate with you, I encourage you to try out these primitives and share your feedback. :) Look out for the future articles where we'll further explore how these primitives can be used to build more complex form & http building blocks. Until then, happy coding! 🚀