Rename enrichInvocation to attachFact

lib/api/dsl/goalContribution.ts

@@ -36,46 +36,46 @@ import {
     GoalComponent,
     toGoals,
 } from "./GoalComponent";
+import { computeShaOf } from "../../api-helper/misc/sha";
 
 export interface GoalContribution<F> extends Mapping<F, GoalComponent>, Predicated<F> {
 
 }
 
-export interface InvocationState {
-    [key: string]: any;
-}
-
 /**
  * Add state to an invocation. Only available in memory.
+ * @param S type of the fact to add.
  */
-export interface StatefulInvocation extends SdmContext {
+export interface StatefulInvocation<S> extends SdmContext {
 
-    state?: InvocationState;
+    facts?: S;
 }
 
 /**
  * Within evaluation of push rules we can manage state on a push.
  * This interface allows state. This state will not be persisted.
  */
-export interface StatefulPushListenerInvocation extends PushListenerInvocation, StatefulInvocation {
+export interface StatefulPushListenerInvocation<S> extends PushListenerInvocation, StatefulInvocation<S> {
 
 }
 
 /**
- * Enrich the invocation, enhancing its state
- * @param {(f: (F & StatefulInvocation)) => Promise<InvocationState>} compute additional state
+ * Enrich the invocation, attaching some facts.
+ * The returned object will be merged with any facts already on the invocation.
+ * @param {(f: (StatefulInvocation<FACT>)) => Promise<FACT>} compute additional facts. 
  * @return {GoalContribution<F>}
  */
-export function enrichInvocation<F extends SdmContext>(compute: (f: (F & StatefulInvocation)) => Promise<InvocationState>): GoalContribution<F> {
+export function attachFacts<FACT, F extends SdmContext = PushListenerInvocation>(compute: (f: F) => Promise<FACT>): GoalContribution<F> {
     return {
-        name: "enrichInvocation",
+        name: "attachFacts-" + computeShaOf(compute.toString()),
         mapping: async f => {
-            const withState = f as F & StatefulInvocation;
-            if (!withState.state) {
-                withState.state = {};
+            const withAdditionalFact = f as F & StatefulInvocation<FACT>;
+            if (!withAdditionalFact.facts) {
+                withAdditionalFact.facts = {} as FACT;
             }
-            const additionalState = await compute(withState);
-            _.merge(withState.state, additionalState);
+            const additionalState = await compute(withAdditionalFact);
+            _.merge(withAdditionalFact.facts, additionalState);
+            // The GoalContribution itself will be ignored
             return undefined;
         },
     };
@@ -148,7 +148,7 @@ class AdditiveGoalSetter<F extends SdmContext> implements GoalSetter<F>, GoalSet
  * @param {GoalContribution<F>} contributors
  * @return a mapping to goals
  */
-export function goalContributors<F extends SdmContext = StatefulPushListenerInvocation>(
+export function goalContributors<F extends SdmContext = StatefulPushListenerInvocation<any>>(
     contributor: GoalContribution<F>,
     ...contributors: Array<GoalContribution<F>>): Mapping<F, Goals> {
     if (contributors.length === 0) {
@@ -164,7 +164,7 @@ export function goalContributors<F extends SdmContext = StatefulPushListenerInvo
  * @param {GoalContribution<F extends SdmContext>} contributors
  * @return {Mapping<F extends SdmContext, Goals>}
  */
-export function enrichGoalSetters<F extends SdmContext = StatefulPushListenerInvocation>(
+export function enrichGoalSetters<F extends SdmContext = StatefulPushListenerInvocation<any>>(
     mapping: GoalContribution<F>,
     contributor: GoalContribution<F>,
     ...contributors: Array<GoalContribution<F>>): Mapping<F, Goals> & GoalSettingStructure<F, Goals> {

test/api/dsl/goalContribution.test.ts

@@ -23,8 +23,8 @@ import { isGitHubRepoRef } from "@atomist/automation-client/lib/operations/commo
 import * as assert from "power-assert";
 import { fakePush } from "../../../lib/api-helper/testsupport/fakePush";
 import {
+    attachFacts,
     enrichGoalSetters,
-    enrichInvocation,
     goalContributors,
     StatefulPushListenerInvocation,
 } from "../../../lib/api/dsl/goalContribution";
@@ -177,11 +177,18 @@ describe("goalContribution", () => {
             assert.deepEqual(barGoals.goals, SomeGoalSet.goals.concat(mg1));
         });
 
-        it("should allow state", async () => {
+        it("should uniquely name attachFacts", async () => {
+            const af = attachFacts<{ name: string}>(async pu => ({ name: pu.push.id }));
+            assert(af.name.startsWith("attachFacts-"));
+            assert(af.name.length > "attachFacts-".length);
+        });
+
+        it("should attach facts", async () => {
+            type Named = { name: string };
             const mg = suggestAction({ message: "sendSomeMessage", displayName: "Sending message" });
             let gs = goalContributors(
-                enrichInvocation(async pu => ({ name: "tony" })),
-                whenPushSatisfies<StatefulPushListenerInvocation>(async pu => pu.state.name === "tony").setGoals(mg));
+                attachFacts<Named>(async pu => ({ name: "tony" })),
+                whenPushSatisfies<StatefulPushListenerInvocation<Named>>(async pu => pu.facts.name === "tony").setGoals(mg));
             gs = enrichGoalSetters(gs,
                 onAnyPush().setGoals(FingerprintGoal));
             const p = fakePush();