feat(devtools): add branded Action type and asAction helper

Author: sqrter

docs/docs/community.md

@@ -0,0 +1,42 @@
+---
+title: Community
+---
+
+We are thankful for the community surrounding the Toolkit.
+
+Here are some links with respect to two types of community involvement:
+
+1. Addons to the code
+1. Content about the Toolkit
+1. Discord
+
+## Addons
+
+### ngrx-toolkit-openapi-gen
+
+[Murat Sari](https://github.com/wolfmanfx) created an OpenAPI generator that creates:
+
+✅ an NgRx Signal Store
+
+✅ with Resources
+
+✅ and Mutations
+
+✅ based on a Zod schema
+
+[Check it out here](https://www.npmjs.com/package/ngrx-toolkit-openapi-gen)
+
+## Content
+
+- Zoaib Khan
+  - [Blog post: "Use withResource to seamlessly combine Resources with Ngrx Signals Store!"](https://zoaibkhan.com/blog/use-withresource-to-seamlessly-combine-resources-with-ngrx/)
+  - [YouTube short: "Local Storage Sync with Ngrx Signal Store"](https://www.youtube.com/shorts/wbRxCCUrGvk)
+- Angular Space livestreams
+  - [Rainer's appearance](https://youtu.be/UUhZm52tigQ?t=2930), taking general Toolkit questions from Angular Space host Armen Vardanyan
+  - [Michael Small's appearance](https://youtu.be/X59d8GJnNhE?t=603), speaking about Mutations when they were being RFC'd, and `withResource`.
+- [Jason Warner (@xocomil) speaks about `withResource/withMutations` on a livestream](https://www.youtube.com/watch?v=kitcmXNj5K0&t=6344s)
+  - Michael Small is an active chat member on Jason's streams, so Jason has talked about the Toolkit a lot on stream, and probably will in the future if he keeps humoring Michael.
+
+## Discord
+
+Community contributions are sometimes shared on our Discord. [Link to join the NgRx Toolkit Discord](https://discord.gg/xnkSWDmpXZ). Feel free to share your Toolkit related content there, as well as any general discussion that may not fit cleanly under a GitHub issue or discussion post.

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)

docs/docusaurus.config.ts

@@ -94,6 +94,12 @@ const config: Config = {
           position: 'left',
           label: 'Team',
         },
+        {
+          type: 'docSidebar',
+          sidebarId: 'communitySidebar',
+          position: 'left',
+          label: 'Community',
+        },
         {
           href: 'https://github.com/angular-architects/ngrx-toolkit',
           label: 'GitHub',

docs/sidebars.ts

@@ -38,6 +38,7 @@ const sidebars: SidebarsConfig = {
     },
   ],
   teamSidebar: ['team'],
+  communitySidebar: ['community'],
 
   // But you can create a sidebar manually
   /*

libs/ngrx-toolkit/src/lib/devtools/with-tracked-reducer.ts

@@ -15,7 +15,7 @@ import {
 } from '@ngrx/signals/events';
 import { tap } from 'rxjs/operators';
 import { GLITCH_TRACKING_FEATURE } from './features/with-glitch-tracking';
-import { updateState, asAction } from './update-state';
+import { asAction, updateState } from './update-state';
 import { DEVTOOL_FEATURE_NAMES } from './with-devtools';
 
 export function withTrackedReducer<State extends object>(

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;
 };