fix: narrow NamedMutationMethods to just fn signature (#305)

Author: michael-small

docs/docs/mutations.md

@@ -218,12 +218,16 @@ const save = await store.save({...}); if (inc.status === 'error')
 ### Signal values
 
 ```ts
-// Signals
+// value: Signal<Result | undefined>;
+// status: Signal<MutationStatus>;
+// isPending: Signal<boolean>;
+// isSuccess: Signal<boolean>;
+// error: Signal<unknown>;
 
-// via store
-store.increment.value; // also status/error/isPending/status/hasValue;
+// via store in `withMutation`
+store.incrementValue;
 
-// via member variable
+// via member variable if defined outside of `withMutation`
 mutationName.value; // ^^^
 ```
 
@@ -288,9 +292,8 @@ export type Mutation<Parameter, Result> = {
   hasValue(): this is Mutation<Exclude<Parameter, undefined>, Result>; // type narrows `.value()`
 };
 
-// Accessed from store or variable
-storeName.mutationName.value; // or other signals
-mutationName.value; // ^^^
+storeName.mutationNameValue; // `withMutations`
+mutationName.value; // no `withMutations`
 ```
 
 #### Callbacks: `onSuccess` and `onError` (optional)

libs/ngrx-toolkit/src/lib/with-mutations.spec.ts

@@ -2,7 +2,9 @@ import { fakeAsync, TestBed, tick } from '@angular/core/testing';
 import { patchState, signalStore, withState } from '@ngrx/signals';
 import { delay, Observable, of, Subject, switchMap, throwError } from 'rxjs';
 import { concatOp, exhaustOp, mergeOp, switchOp } from './flattening-operator';
+import { Mutation, MutationResult } from './mutation/mutation';
 import { rxMutation } from './mutation/rx-mutation';
+import { Assert, AssertNot, IsEqual } from './test-utils/types';
 import { withMutations } from './with-mutations';
 
 type Param =
@@ -534,4 +536,53 @@ describe('withMutations with rxMutation', () => {
       error: 'Test-Error',
     });
   });
+
+  it('does not expose mutation properties directly, only the method', async () => {
+    // Test case for https://github.com/angular-architects/ngrx-toolkit/issues/286
+    const testSetup = createTestSetup(switchOp);
+    const store = testSetup.store;
+
+    expect(typeof store.increment).toEqual('function');
+    // @ts-expect-error Should not expose properties, only the method
+    expect(store.increment.isPending).toBeUndefined();
+  });
+
+  it('types mutation method as plain callable Promise signature and returns nothing else from a mutation', () => {
+    // Test case for https://github.com/angular-architects/ngrx-toolkit/issues/286
+    const testSetup = createTestSetup();
+    const store = testSetup.store;
+
+    // Only the method is exposed
+    type _T1 = Assert<
+      IsEqual<
+        typeof store.increment,
+        (params: Param) => Promise<MutationResult<number>>
+      >
+    >;
+
+    // Other mutation properties not present
+    type _T2 = AssertNot<
+      IsEqual<typeof store.increment, Mutation<Param, number>>
+    >;
+
+    // _T2 in other words:
+
+    // CAN...
+    // Still can call mutation function
+    store.increment(0);
+
+    // CANNOT...
+    // @ts-expect-error should not expose properties, only method call
+    const status = store.increment.status;
+    // @ts-expect-error should not expose properties, only method call
+    const value = store.increment.value;
+    // @ts-expect-error should not expose properties, only method call
+    const isPending = store.increment.isPending;
+    // @ts-expect-error should not expose properties, only method call
+    const isSuccess = store.increment.isSuccess;
+    // @ts-expect-error should not expose properties, only method call
+    const error = store.increment.error;
+    // @ts-expect-error should not expose properties, only method call
+    const hasValue = store.increment.hasValue;
+  });
 });

libs/ngrx-toolkit/src/lib/with-mutations.ts

@@ -10,7 +10,7 @@ import {
   withMethods,
   WritableStateSource,
 } from '@ngrx/signals';
-import { Mutation, MutationStatus } from './mutation/mutation';
+import { Mutation, MutationResult, MutationStatus } from './mutation/mutation';
 
 // NamedMutationMethods below will infer the actual parameter and return types
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -33,7 +33,7 @@ type NamedMutationMethods<T extends MutationsDictionary> = {
     infer P,
     infer R
   >
-    ? Mutation<P, R>
+    ? (params: P) => Promise<MutationResult<R>>
     : never;
 };