@angular-architects/ngrx-toolkit 19.2.3 → 19.4.0

package/src/lib/storage-sync/with-storage-sync.ts

@@ -0,0 +1,233 @@
+import { isPlatformServer } from '@angular/common';
+import { computed, effect, inject, PLATFORM_ID, signal } from '@angular/core';
+import {
+  EmptyFeatureResult,
+  getState,
+  signalStoreFeature,
+  SignalStoreFeature,
+  SignalStoreFeatureResult,
+  watchState,
+  withHooks,
+  withMethods,
+  withProps,
+} from '@ngrx/signals';
+import {
+  withLocalStorage,
+  withSessionStorage,
+} from './features/with-local-storage';
+import {
+  AsyncFeatureResult,
+  AsyncStorageStrategy,
+  SYNC_STATUS,
+  SyncFeatureResult,
+  SyncStorageStrategy,
+} from './internal/models';
+
+export type SyncConfig<State> = {
+  /**
+   * The key which is used to access the storage.
+   */
+  key: string;
+  /**
+   * Flag indicating if the store should read from storage on init and write to storage on every state change.
+   *
+   * `true` by default
+   */
+  autoSync?: boolean;
+  /**
+   * Function to select that portion of the state which should be stored.
+   *
+   * Returns the whole state object by default
+   */
+  select?: (state: State) => unknown;
+  /**
+   * Function used to parse the state coming from storage.
+   *
+   * `JSON.parse()` by default
+   */
+  parse?: (stateString: string) => State;
+  /**
+   * Function used to transform the state into a string representation.
+   *
+   * `JSON.stringify()` by default
+   */
+  stringify?: (state: State) => string;
+
+  /**
+   * @deprecated Use {@link withSessionStorage} instead.
+   * Factory function used to switch to sessionStorage.
+   *
+   * `localStorage` by default
+   */
+  storage?: () => Storage;
+};
+
+// only key
+export function withStorageSync<Input extends SignalStoreFeatureResult>(
+  key: string,
+): SignalStoreFeature<Input, SyncFeatureResult>;
+
+// key + indexeddb
+export function withStorageSync<Input extends SignalStoreFeatureResult>(
+  key: string,
+  storageStrategy: AsyncStorageStrategy<Input['state']>,
+): SignalStoreFeature<Input, AsyncFeatureResult>;
+
+// key + localStorage(or sessionStorage)
+export function withStorageSync<Input extends SignalStoreFeatureResult>(
+  key: string,
+  storageStrategy: SyncStorageStrategy<Input['state']>,
+): SignalStoreFeature<Input, SyncFeatureResult>;
+
+// config + localStorage
+export function withStorageSync<Input extends SignalStoreFeatureResult>(
+  config: SyncConfig<Input['state']>,
+): SignalStoreFeature<Input, SyncFeatureResult>;
+
+// config + indexeddb
+export function withStorageSync<Input extends SignalStoreFeatureResult>(
+  config: SyncConfig<Input['state']>,
+  storageStrategy: AsyncStorageStrategy<Input['state']>,
+): SignalStoreFeature<Input, AsyncFeatureResult>;
+
+// config + localStorage(or sessionStorage)
+export function withStorageSync<Input extends SignalStoreFeatureResult>(
+  config: SyncConfig<Input['state']>,
+  storageStrategy: SyncStorageStrategy<Input['state']>,
+): SignalStoreFeature<Input, SyncFeatureResult>;
+
+export function withStorageSync<Input extends SignalStoreFeatureResult>(
+  configOrKey: SyncConfig<Input['state']> | string,
+  storageStrategy?:
+    | AsyncStorageStrategy<Input['state']>
+    | SyncStorageStrategy<Input['state']>,
+): SignalStoreFeature<
+  Input,
+  EmptyFeatureResult & (SyncFeatureResult | AsyncFeatureResult)
+> {
+  if (
+    typeof configOrKey !== 'string' &&
+    configOrKey.storage &&
+    storageStrategy
+  ) {
+    throw new Error(
+      'You can either pass a storage strategy or a config with storage, but not both.',
+    );
+  }
+  const config: Required<SyncConfig<Input['state']>> = {
+    autoSync: true,
+    select: (state: Input['state']) => state,
+    parse: JSON.parse,
+    stringify: JSON.stringify,
+    storage: () => localStorage,
+    ...(typeof configOrKey === 'string' ? { key: configOrKey } : configOrKey),
+  };
+
+  const factory =
+    storageStrategy ??
+    (config.storage() === localStorage
+      ? withLocalStorage()
+      : withSessionStorage());
+
+  if (factory.type === 'sync') {
+    return createSyncStorageSync(factory, config);
+  } else {
+    return createAsyncStorageSync(factory, config);
+  }
+}
+
+function createSyncStorageSync<Input extends SignalStoreFeatureResult>(
+  factory: SyncStorageStrategy<Input['state']>,
+  config: Required<SyncConfig<Input['state']>>,
+) {
+  return signalStoreFeature(
+    withMethods((store, platformId = inject(PLATFORM_ID)) => {
+      return factory(config, store, isPlatformServer(platformId));
+    }),
+    withHooks({
+      onInit(store, platformId = inject(PLATFORM_ID)) {
+        if (isPlatformServer(platformId)) {
+          return;
+        }
+
+        if (config.autoSync) {
+          store.readFromStorage();
+          watchState(store, () => store.writeToStorage());
+        }
+      },
+    }),
+  ) satisfies SignalStoreFeature<EmptyFeatureResult, SyncFeatureResult>;
+}
+
+function createAsyncStorageSync<Input extends SignalStoreFeatureResult>(
+  factory: AsyncStorageStrategy<Input['state']>,
+  config: Required<SyncConfig<Input['state']>>,
+) {
+  return signalStoreFeature(
+    withProps(() => {
+      const props = {
+        /*
+        // we need to have that as property (and not state)
+        // Otherwise the state watcher fires when updating the sync status
+        */
+        [SYNC_STATUS]: signal<'idle' | 'syncing' | 'synced'>('idle'),
+      };
+
+      const resolves = [] as (() => void)[];
+
+      effect(() => {
+        const syncStatus = props[SYNC_STATUS]();
+        if (syncStatus === 'synced') {
+          resolves.forEach((resolve) => resolve());
+          resolves.splice(0, resolves.length);
+        }
+      });
+
+      return {
+        ...props,
+        isSynced: computed(() => props[SYNC_STATUS]() === 'synced'),
+        whenSynced: () =>
+          new Promise<void>((resolve) => {
+            if (props[SYNC_STATUS]() === 'synced') {
+              resolve();
+            } else {
+              resolves.push(resolve);
+            }
+          }),
+      };
+    }),
+    withMethods((store, platformId = inject(PLATFORM_ID)) => {
+      return factory(config, store, isPlatformServer(platformId));
+    }),
+    withHooks({
+      async onInit(store, platformId = inject(PLATFORM_ID)) {
+        if (isPlatformServer(platformId)) {
+          return;
+        }
+
+        const initialState = getState(store);
+        if (config.autoSync) {
+          let startWatching = false;
+          watchState(store, () => {
+            if (!startWatching) {
+              if (getState(store) === initialState) {
+                return;
+              }
+
+              console.warn(
+                `Writing to Store (${config.key}) happened before the state was initially read from storage.`,
+                'Please ensure that the store is not in syncing state via `store.whenSynced()` before writing to the state.',
+                'Alternatively, you can disable autoSync by passing `autoSync: false` in the config.',
+              );
+              return;
+            }
+            return store.writeToStorage();
+          });
+
+          await store.readFromStorage();
+          startWatching = true;
+        }
+      },
+    }),
+  ) satisfies SignalStoreFeature<EmptyFeatureResult, AsyncFeatureResult>;
+}

package/src/lib/with-call-state.spec.ts

@@ -0,0 +1,42 @@
+import { patchState, signalStore } from '@ngrx/signals';
+import { setLoaded, setLoading, withCallState } from './with-call-state';
+
+describe('withCallState', () => {
+  it('should use and update a callState', () => {
+    const DataStore = signalStore({ protectedState: false }, withCallState());
+    const dataStore = new DataStore();
+
+    patchState(dataStore, setLoading());
+
+    expect(dataStore.callState()).toBe('loading');
+    expect(dataStore.loading()).toBe(true);
+  });
+
+  it('should use the callState for a collection', () => {
+    const DataStore = signalStore(
+      { protectedState: false },
+      withCallState({ collection: 'entities' }),
+    );
+    const dataStore = new DataStore();
+
+    patchState(dataStore, setLoaded('entities'));
+
+    expect(dataStore.entitiesCallState()).toBe('loaded');
+    expect(dataStore.entitiesLoaded()).toBe(true);
+  });
+
+  it('should use the callState for multiple collections with an array', () => {
+    const DataStore = signalStore(
+      { protectedState: false },
+      withCallState({ collections: ['entities', 'products'] }),
+    );
+    const dataStore = new DataStore();
+
+    patchState(dataStore, setLoaded('entities'), setLoaded('products'));
+
+    expect(dataStore.entitiesCallState()).toBe('loaded');
+    expect(dataStore.productsCallState()).toBe('loaded');
+    expect(dataStore.entitiesLoaded()).toBe(true);
+    expect(dataStore.productsLoaded()).toBe(true);
+  });
+});

package/src/lib/with-call-state.ts

@@ -0,0 +1,195 @@
+import { Signal, computed } from '@angular/core';
+import {
+  EmptyFeatureResult,
+  SignalStoreFeature,
+  signalStoreFeature,
+  withComputed,
+  withState,
+} from '@ngrx/signals';
+
+export type CallState = 'init' | 'loading' | 'loaded' | { error: string };
+
+export type CallStateSlice = {
+  callState: CallState;
+};
+
+export type NamedCallStateSlice<Collection extends string> = {
+  [K in keyof CallStateSlice as Collection extends ''
+    ? `${Collection}${K}`
+    : `${Collection}${Capitalize<K>}`]: CallStateSlice[K];
+};
+
+export type CallStateSignals = {
+  loading: Signal<boolean>;
+  loaded: Signal<boolean>;
+  error: Signal<string | null>;
+};
+
+export type NamedCallStateSignals<Prop extends string> = {
+  [K in keyof CallStateSignals as Prop extends ''
+    ? `${Prop}${K}`
+    : `${Prop}${Capitalize<K>}`]: CallStateSignals[K];
+};
+
+export type SetCallState<Prop extends string | undefined> = Prop extends string
+  ? NamedCallStateSlice<Prop>
+  : CallStateSlice;
+
+export function deriveCallStateKeys<Collection extends string>(
+  collection?: Collection,
+) {
+  return {
+    callStateKey: collection ? `${collection}CallState` : 'callState',
+    loadingKey: collection ? `${collection}Loading` : 'loading',
+    loadedKey: collection ? `${collection}Loaded` : 'loaded',
+    errorKey: collection ? `${collection}Error` : 'error',
+  };
+}
+
+export function getCallStateKeys(config?: { collection?: string }) {
+  const prop = config?.collection;
+  return deriveCallStateKeys(prop);
+}
+
+export function getCollectionArray(
+  config: { collection?: string } | { collections?: string[] },
+) {
+  return 'collections' in config
+    ? config.collections
+    : 'collection' in config && config.collection
+      ? [config.collection]
+      : undefined;
+}
+
+export function withCallState<Collection extends string>(config: {
+  collections: Collection[];
+}): SignalStoreFeature<
+  EmptyFeatureResult,
+  EmptyFeatureResult & {
+    state: NamedCallStateSlice<Collection>;
+    props: NamedCallStateSignals<Collection>;
+  }
+>;
+export function withCallState<Collection extends string>(config: {
+  collection: Collection;
+}): SignalStoreFeature<
+  EmptyFeatureResult,
+  EmptyFeatureResult & {
+    state: NamedCallStateSlice<Collection>;
+    props: NamedCallStateSignals<Collection>;
+  }
+>;
+export function withCallState(): SignalStoreFeature<
+  EmptyFeatureResult,
+  EmptyFeatureResult & {
+    state: CallStateSlice;
+    props: CallStateSignals;
+  }
+>;
+export function withCallState<Collection extends string>(
+  config?:
+    | {
+        collection: Collection;
+      }
+    | {
+        collections: Collection[];
+      },
+): SignalStoreFeature {
+  return signalStoreFeature(
+    withState(() => {
+      if (!config) {
+        return { callState: 'init' };
+      }
+      const collections = getCollectionArray(config);
+      if (collections) {
+        return collections.reduce(
+          (acc, cur) => ({
+            ...acc,
+            ...{ [cur ? `${cur}CallState` : 'callState']: 'init' },
+          }),
+          {},
+        );
+      }
+
+      return { callState: 'init' };
+    }),
+    withComputed((state: Record<string, Signal<unknown>>) => {
+      if (config) {
+        const collections = getCollectionArray(config);
+        if (collections) {
+          return collections.reduce<Record<string, Signal<unknown>>>(
+            (acc, cur: string) => {
+              const { callStateKey, errorKey, loadedKey, loadingKey } =
+                deriveCallStateKeys(cur);
+              const callState = state[callStateKey] as Signal<CallState>;
+              return {
+                ...acc,
+                [loadingKey]: computed(() => callState() === 'loading'),
+                [loadedKey]: computed(() => callState() === 'loaded'),
+                [errorKey]: computed(() => {
+                  const v = callState();
+                  return typeof v === 'object' ? v.error : null;
+                }),
+              };
+            },
+            {},
+          );
+        }
+      }
+      const { callStateKey, errorKey, loadedKey, loadingKey } =
+        deriveCallStateKeys();
+      const callState = state[callStateKey] as Signal<CallState>;
+      return {
+        [loadingKey]: computed(() => callState() === 'loading'),
+        [loadedKey]: computed(() => callState() === 'loaded'),
+        [errorKey]: computed(() => {
+          const v = callState();
+          return typeof v === 'object' ? v.error : null;
+        }),
+      };
+    }),
+  );
+}
+
+export function setLoading<Prop extends string | undefined = undefined>(
+  prop?: Prop,
+): SetCallState<Prop> {
+  if (prop) {
+    return { [`${prop}CallState`]: 'loading' } as SetCallState<Prop>;
+  }
+
+  return { callState: 'loading' } as SetCallState<Prop>;
+}
+
+export function setLoaded<Prop extends string | undefined = undefined>(
+  prop?: Prop,
+): SetCallState<Prop> {
+  if (prop) {
+    return { [`${prop}CallState`]: 'loaded' } as SetCallState<Prop>;
+  } else {
+    return { callState: 'loaded' } as SetCallState<Prop>;
+  }
+}
+
+export function setError<Prop extends string | undefined = undefined>(
+  error: unknown,
+  prop?: Prop,
+): SetCallState<Prop> {
+  let errorMessage: string;
+
+  if (!error) {
+    errorMessage = '';
+  } else if (typeof error === 'object' && 'message' in error) {
+    errorMessage = String(error.message);
+  } else {
+    errorMessage = String(error);
+  }
+
+  if (prop) {
+    return {
+      [`${prop}CallState`]: { error: errorMessage },
+    } as SetCallState<Prop>;
+  } else {
+    return { callState: { error: errorMessage } } as SetCallState<Prop>;
+  }
+}

package/src/lib/with-conditional.spec.ts

@@ -0,0 +1,125 @@
+import { inject, InjectionToken } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import {
+  getState,
+  patchState,
+  signalStore,
+  signalStoreFeature,
+  withHooks,
+  withMethods,
+  withState,
+} from '@ngrx/signals';
+import { withDevtools } from './devtools/with-devtools';
+import { emptyFeature, withConditional } from './with-conditional';
+
+describe('withConditional', () => {
+  const withUser = signalStoreFeature(
+    withState({ id: 0, name: '' }),
+    withHooks((store) => ({
+      onInit() {
+        patchState(store, { id: 1, name: 'Konrad' });
+      },
+    })),
+  );
+
+  const withFakeUser = signalStoreFeature(
+    withState({ id: 0, name: 'Tommy Fake' }),
+  );
+
+  for (const isReal of [true, false]) {
+    it(`should ${isReal ? '' : 'not '} enable withUser`, () => {
+      const REAL_USER_TOKEN = new InjectionToken('REAL_USER', {
+        providedIn: 'root',
+        factory: () => isReal,
+      });
+      const UserStore = signalStore(
+        { providedIn: 'root' },
+        withConditional(() => inject(REAL_USER_TOKEN), withUser, withFakeUser),
+      );
+      const userStore = TestBed.inject(UserStore);
+
+      if (isReal) {
+        expect(getState(userStore)).toEqual({ id: 1, name: 'Konrad' });
+      } else {
+        expect(getState(userStore)).toEqual({ id: 0, name: 'Tommy Fake' });
+      }
+    });
+  }
+
+  it(`should access the store`, () => {
+    const UserStore = signalStore(
+      { providedIn: 'root' },
+      withMethods(() => ({
+        useRealUser: () => true,
+      })),
+      withConditional((store) => store.useRealUser(), withUser, withFakeUser),
+    );
+    const userStore = TestBed.inject(UserStore);
+
+    expect(getState(userStore)).toEqual({ id: 1, name: 'Konrad' });
+  });
+
+  it('should be used inside a signalStoreFeature', () => {
+    const withConditionalUser = (activate: boolean) =>
+      signalStoreFeature(
+        withConditional(() => activate, withUser, withFakeUser),
+      );
+
+    const UserStore = signalStore(
+      { providedIn: 'root' },
+      withConditionalUser(true),
+    );
+    const userStore = TestBed.inject(UserStore);
+
+    expect(getState(userStore)).toEqual({ id: 1, name: 'Konrad' });
+  });
+
+  it('should ensure that both features return the same type', () => {
+    const withUser = signalStoreFeature(
+      withState({ id: 0, name: '' }),
+      withHooks((store) => ({
+        onInit() {
+          patchState(store, { id: 1, name: 'Konrad' });
+        },
+      })),
+    );
+
+    const withFakeUser = signalStoreFeature(
+      withState({ id: 0, firstname: 'Tommy Fake' }),
+    );
+
+    // @ts-expect-error withFakeUser has a different state shape
+    signalStore(withConditional(() => true, withUser, withFakeUser));
+  });
+
+  it('should also work with empty features', () => {
+    signalStore(
+      withConditional(
+        () => true,
+        withDevtools('dummy'),
+        signalStoreFeature(withState({})),
+      ),
+    );
+  });
+
+  it('should work with `emptyFeature` if falsy is skipped', () => {
+    signalStore(
+      withConditional(
+        () => true,
+        signalStoreFeature(withState({})),
+        emptyFeature,
+      ),
+    );
+  });
+
+  it('should not work with `emptyFeature` if feature is not empty', () => {
+    signalStore(
+      withConditional(
+        () => true,
+        // @ts-expect-error feature is not empty
+        () => signalStoreFeature(withState({ x: 1 })),
+        emptyFeature,
+      ),
+    );
+  });
+});

package/{lib/with-conditional.d.ts → src/lib/with-conditional.ts}

@@ -1,4 +1,11 @@
-import { SignalStoreFeature, SignalStoreFeatureResult, StateSignals } from '@ngrx/signals';
+import {
+  signalStoreFeature,
+  SignalStoreFeature,
+  SignalStoreFeatureResult,
+  StateSignals,
+  withState,
+} from '@ngrx/signals';
+
 /**
  * `withConditional` activates a feature based on a given condition.
  *
@@ -42,9 +49,26 @@ import { SignalStoreFeature, SignalStoreFeatureResult, StateSignals } from '@ngr
  * @param featureIfFalse - The feature to activate if the condition evaluates to `false`.
  * @returns A `SignalStoreFeature` that applies the selected feature based on the condition.
  */
-export declare function withConditional<Input extends SignalStoreFeatureResult, Output extends SignalStoreFeatureResult>(condition: (store: StateSignals<Input['state']> & Input['props'] & Input['methods']) => boolean, featureIfTrue: SignalStoreFeature<NoInfer<Input>, Output>, featureIfFalse: SignalStoreFeature<NoInfer<Input>, NoInfer<Output>>): SignalStoreFeature<Input, Output>;
-export declare const emptyFeature: SignalStoreFeature<import("@ngrx/signals").EmptyFeatureResult, {
-    state: {};
-    props: {};
-    methods: {};
-}>;
+export function withConditional<
+  Input extends SignalStoreFeatureResult,
+  Output extends SignalStoreFeatureResult,
+>(
+  condition: (
+    store: StateSignals<Input['state']> & Input['props'] & Input['methods'],
+  ) => boolean,
+  featureIfTrue: SignalStoreFeature<NoInfer<Input>, Output>,
+  featureIfFalse: SignalStoreFeature<NoInfer<Input>, NoInfer<Output>>,
+): SignalStoreFeature<Input, Output> {
+  return (store) => {
+    const conditionStore = {
+      ...store['stateSignals'],
+      ...store['props'],
+      ...store['methods'],
+    };
+    return condition(conditionStore)
+      ? featureIfTrue(store)
+      : featureIfFalse(store);
+  };
+}
+
+export const emptyFeature = signalStoreFeature(withState({}));