@reventlessdev/trait-address-geocoding 1.0.0-alpha.1

package/src/AddressGeocoding_Conformance.res

@@ -0,0 +1,185 @@
+/**
+The conformance suite, run by a host against its own graft. `Make(Binding).register()`
+inside a Jest test file registers one `describe` block; every assertion is written
+over the binding, never over a host's constructors.
+*/
+
+// Warning 23 flags the spread in `geocoder` as redundant today; it is there for
+// the day `Capabilities.t` grows a field.
+@@warning("-23")
+
+module Outcome = ReventlessGwt.Outcome
+
+/** The suite's title, composed once and read twice: the suite registers it,
+    and `certify-trait` computes the same string to find the run's assertions in
+    a test report. Exported rather than inlined so neither side parses the
+    other's prose. */
+let suiteName = (host: string) => `${host} conforms to the address-geocoding trait`
+
+module Make = (B: AddressGeocoding.Binding) => {
+  module A = ReventlessGwt.Behavior_GWT.MakeFromAggregate(B.Spec, B.Behavior)
+  module S = ReventlessGwt.OutboundTranslation_GWT.Make(B.Slice)
+
+  let vienna: Reventless.GeoPoint.t = {lat: 48.2082, lng: 16.3738}
+  let bruges: Reventless.GeoPoint.t = {lat: 51.2093, lng: 3.2247}
+  let entityId = "entity-1"
+  let todoKey = subject => `${entityId}:${B.subjectText(subject)}`
+
+  let geocoder = (answer): Reventless.Capabilities.t => {
+    ...Reventless.Capabilities.none,
+    geocode: (~text as _) => Promise.resolve(answer),
+  }
+  let translateWith = answer => (id, item) => B.translate(id, item, ~capabilities=geocoder(answer))
+
+  let describeCommand = cmd =>
+    cmd->Reventless.Message.encode(B.Slice.inboundCommandSchema)->JSON.stringify
+
+  let thenReports = async (pending: promise<S.attempt>, ~expected, predicate) => {
+    let {result, _} = await pending
+    switch result {
+    | Ok(Some((_, cmd))) if predicate(cmd) => Outcome.pass
+    | Ok(Some((_, cmd))) =>
+      Outcome.fail(TranslateError({expected, actual: Some(describeCommand(cmd))}))
+    | Ok(None) => Outcome.fail(TranslateError({expected, actual: Some("no command")}))
+    | Error(why) => Outcome.fail(TranslateError({expected, actual: Some(why)}))
+    }
+  }
+
+  let sorted = names => names->Array.toSorted(String.compare)
+  let strings = names => names->Array.map(JSON.Encode.string)
+
+  let consumedSetMatchesTriggers = () => {
+    let consumed = Reventless.DcbDecode.makeDecoder(B.Slice.consumedEventSchema).eventTypes->sorted
+    let triggers =
+      B.triggers(B.subjectA)
+      ->Array.map(e =>
+        e->Reventless.Message.encode(B.Slice.consumedEventSchema)->Reventless.Message.variantNameOfJson
+      )
+      ->sorted
+    // Encoded through the aggregate's own schema, so a stand-down event is a
+    // constructor the compiler checked rather than a name that merely looks like
+    // one. Compared on variant names because that is what a consumed set holds.
+    let standsDownOn =
+      B.standsDownOn->Array.map(e =>
+        e->Reventless.Message.encode(B.Spec.eventSchema)->Reventless.Message.variantNameOfJson
+      )
+    let widened = consumed->Array.some(t => standsDownOn->Array.includes(t))
+    if consumed == triggers && !widened {
+      Outcome.pass
+    } else {
+      Outcome.fail(
+        StateMismatch({
+          key: "consumedEvent",
+          expected: Some(JSON.Encode.array(strings(triggers))),
+          actual: Some(JSON.Encode.array(strings(consumed))),
+        }),
+      )
+    }
+  }
+
+  let register = () =>
+    A.describe(suiteName(B.Spec.name), () => {
+      switch B.posture {
+      | Observes =>
+        A.test("posture: Observes is not supported by this runner", () =>
+          Outcome.fail(
+            Throw({error: "the runner checks a write-back graft; bind one, or wait", stack: ""}),
+          )
+        )
+      | WritesBack => ()
+      }
+
+      // Aggregate: the graft rules.
+      A.test("an answer for the current subject is applied", () =>
+        A.givenEvents(B.created(B.subjectA))
+        ->A.whenCmd(B.setLocation(~point=vienna, ~resolvedFrom=B.subjectA))
+        ->A.thenEvent(B.located(~point=vienna, ~resolvedFrom=B.subjectA))
+      )
+
+      A.test("a verdict for the current subject is recorded", () =>
+        A.givenEvents(B.created(B.subjectA))
+        ->A.whenCmd(B.markUnresolvable(~subject=B.subjectA, ~reason="no match"))
+        ->A.thenEvent(B.unresolvable(~subject=B.subjectA, ~reason="no match"))
+      )
+
+      A.test("an answer for a superseded subject is dropped as stale", () =>
+        A.givenEvents(Array.concat(B.created(B.subjectA), [B.subjectChanged(B.subjectB)]))
+        ->A.whenCmd(B.setLocation(~point=vienna, ~resolvedFrom=B.subjectA))
+        ->A.thenNoEvent
+      )
+
+      A.test("a verdict for a superseded subject is dropped as stale", () =>
+        A.givenEvents(Array.concat(B.created(B.subjectA), [B.subjectChanged(B.subjectB)]))
+        ->A.whenCmd(B.markUnresolvable(~subject=B.subjectA, ~reason="no match"))
+        ->A.thenNoEvent
+      )
+
+      A.test("a redelivered answer is a no-op", () =>
+        A.givenEvents(
+          Array.concat(B.created(B.subjectA), [B.located(~point=vienna, ~resolvedFrom=B.subjectA)]),
+        )
+        ->A.whenCmd(B.setLocation(~point=vienna, ~resolvedFrom=B.subjectA))
+        ->A.thenNoEvent
+      )
+
+      A.test("a redelivered verdict is a no-op", () =>
+        A.givenEvents(
+          Array.concat(B.created(B.subjectA), [B.unresolvable(~subject=B.subjectA, ~reason="no match")]),
+        )
+        ->A.whenCmd(B.markUnresolvable(~subject=B.subjectA, ~reason="no match"))
+        ->A.thenNoEvent
+      )
+
+      A.test("a subject change reopens the question", () =>
+        A.givenEvents(
+          Array.concat(
+            B.created(B.subjectA),
+            [B.located(~point=vienna, ~resolvedFrom=B.subjectA), B.subjectChanged(B.subjectB)],
+          ),
+        )
+        ->A.whenCmd(B.setLocation(~point=bruges, ~resolvedFrom=B.subjectB))
+        ->A.thenEvent(B.located(~point=bruges, ~resolvedFrom=B.subjectB))
+      )
+
+      // Slice: the binding surface.
+      A.test("the slice consumes exactly its triggers and stands down on a supplied pair", () =>
+        consumedSetMatchesTriggers()
+      )
+
+      B.triggers(B.subjectA)->Array.forEachWithIndex((trigger, i) =>
+        S.testSync(`trigger ${Int.toString(i + 1)} queues one TODO keyed by entity and subject`, () =>
+          S.givenEvent(trigger)
+          ->S.whenCollect(~sourceId=entityId)
+          ->S.thenTodos([(todoKey(B.subjectA), B.item(~entityId, ~subject=B.subjectA))])
+        )
+      )
+
+      S.test("a confident answer reports the point", () =>
+        S.givenTodo(todoKey(B.subjectA), B.item(~entityId, ~subject=B.subjectA))
+        ->S.whenTranslateMocked(
+          translateWith(
+            Ok([
+              {
+                Reventless.Geocoding.label: B.subjectText(B.subjectA),
+                point: vienna,
+                relevance: Some(0.995),
+              },
+            ]),
+          ),
+        )
+        ->thenReports(~expected="a location", B.isLocation)
+      )
+
+      S.test("a no-match completes the TODO with a verdict", () =>
+        S.givenTodo(todoKey(B.subjectA), B.item(~entityId, ~subject=B.subjectA))
+        ->S.whenTranslateMocked(translateWith(Error(Reventless.Geocoding.NoMatch)))
+        ->thenReports(~expected="a verdict", B.isVerdict)
+      )
+
+      S.test("an outage leaves the TODO pending", () =>
+        S.givenTodo(todoKey(B.subjectA), B.item(~entityId, ~subject=B.subjectA))
+        ->S.whenTranslateMocked(translateWith(Error(Reventless.Geocoding.Unavailable("502"))))
+        ->S.thenTodoStatus(todoKey(B.subjectA), #Pending)
+      )
+    })
+}

package/src/AddressGeocoding_Conformance.res.mjs

@@ -0,0 +1,156 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as Message$Reventless from "@reventlessdev/reventless-spec/src/types/Message.res.mjs";
+import * as DcbDecode$Reventless from "@reventlessdev/reventless-spec/src/components/DcbDecode.res.mjs";
+import * as Outcome$ReventlessGwt from "@reventlessdev/reventless-gwt/src/Outcome.res.mjs";
+import * as Capabilities$Reventless from "@reventlessdev/reventless-spec/src/semantic/Capabilities.res.mjs";
+import * as Behavior_GWT$ReventlessGwt from "@reventlessdev/reventless-gwt/src/Behavior_GWT.res.mjs";
+import * as OutboundTranslation_GWT$ReventlessGwt from "@reventlessdev/reventless-gwt/src/OutboundTranslation_GWT.res.mjs";
+
+function suiteName(host) {
+  return host + ` conforms to the address-geocoding trait`;
+}
+
+function Make(B) {
+  let A = Behavior_GWT$ReventlessGwt.MakeFromAggregate(B.Spec)(B.Behavior);
+  let S = OutboundTranslation_GWT$ReventlessGwt.Make(B.Slice);
+  let vienna = {
+    lat: 48.2082,
+    lng: 16.3738
+  };
+  let bruges = {
+    lat: 51.2093,
+    lng: 3.2247
+  };
+  let entityId = "entity-1";
+  let todoKey = subject => entityId + `:` + B.subjectText(subject);
+  let geocoder = answer => ({
+    geocode: param => Promise.resolve(answer),
+    messaging: Capabilities$Reventless.none.messaging
+  });
+  let translateWith = answer => ((id, item) => B.translate(id, item, geocoder(answer)));
+  let describeCommand = cmd => JSON.stringify(Message$Reventless.encode(cmd, B.Slice.inboundCommandSchema));
+  let thenReports = async (pending, expected, predicate) => {
+    let match = await pending;
+    let result = match.result;
+    if (result.TAG !== "Ok") {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "TranslateError",
+        expected: expected,
+        actual: result._0
+      });
+    }
+    let match$1 = result._0;
+    if (match$1 === undefined) {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "TranslateError",
+        expected: expected,
+        actual: "no command"
+      });
+    }
+    let cmd = match$1[1];
+    if (predicate(cmd)) {
+      return Outcome$ReventlessGwt.pass;
+    } else {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "TranslateError",
+        expected: expected,
+        actual: describeCommand(cmd)
+      });
+    }
+  };
+  let sorted = names => names.toSorted(Primitive_string.compare);
+  let strings = names => names.map(prim => prim);
+  let consumedSetMatchesTriggers = () => {
+    let consumed = sorted(DcbDecode$Reventless.makeDecoder(B.Slice.consumedEventSchema).eventTypes);
+    let triggers = sorted(B.triggers(B.subjectA).map(e => Message$Reventless.variantNameOfJson(Message$Reventless.encode(e, B.Slice.consumedEventSchema))));
+    let standsDownOn = B.standsDownOn.map(e => Message$Reventless.variantNameOfJson(Message$Reventless.encode(e, B.Spec.eventSchema)));
+    let widened = consumed.some(t => standsDownOn.includes(t));
+    if (Primitive_object.equal(consumed, triggers) && !widened) {
+      return Outcome$ReventlessGwt.pass;
+    } else {
+      return Outcome$ReventlessGwt.fail({
+        TAG: "StateMismatch",
+        key: "consumedEvent",
+        expected: triggers.map(prim => prim),
+        actual: consumed.map(prim => prim)
+      });
+    }
+  };
+  let register = () => A.describe(suiteName(B.Spec.name), () => {
+    if (B.posture !== "WritesBack") {
+      A.test("posture: Observes is not supported by this runner", () => Outcome$ReventlessGwt.fail({
+        TAG: "Throw",
+        error: "the runner checks a write-back graft; bind one, or wait",
+        stack: ""
+      }));
+    }
+    A.test("an answer for the current subject is applied", () => A.thenEvent(A.whenCmd(A.givenEvents(B.created(B.subjectA)), B.setLocation(vienna, B.subjectA)), B.located(vienna, B.subjectA)));
+    A.test("a verdict for the current subject is recorded", () => A.thenEvent(A.whenCmd(A.givenEvents(B.created(B.subjectA)), B.markUnresolvable(B.subjectA, "no match")), B.unresolvable(B.subjectA, "no match")));
+    A.test("an answer for a superseded subject is dropped as stale", () => A.thenNoEvent(A.whenCmd(A.givenEvents(B.created(B.subjectA).concat([B.subjectChanged(B.subjectB)])), B.setLocation(vienna, B.subjectA))));
+    A.test("a verdict for a superseded subject is dropped as stale", () => A.thenNoEvent(A.whenCmd(A.givenEvents(B.created(B.subjectA).concat([B.subjectChanged(B.subjectB)])), B.markUnresolvable(B.subjectA, "no match"))));
+    A.test("a redelivered answer is a no-op", () => A.thenNoEvent(A.whenCmd(A.givenEvents(B.created(B.subjectA).concat([B.located(vienna, B.subjectA)])), B.setLocation(vienna, B.subjectA))));
+    A.test("a redelivered verdict is a no-op", () => A.thenNoEvent(A.whenCmd(A.givenEvents(B.created(B.subjectA).concat([B.unresolvable(B.subjectA, "no match")])), B.markUnresolvable(B.subjectA, "no match"))));
+    A.test("a subject change reopens the question", () => A.thenEvent(A.whenCmd(A.givenEvents(B.created(B.subjectA).concat([
+      B.located(vienna, B.subjectA),
+      B.subjectChanged(B.subjectB)
+    ])), B.setLocation(bruges, B.subjectB)), B.located(bruges, B.subjectB)));
+    A.test("the slice consumes exactly its triggers and stands down on a supplied pair", () => consumedSetMatchesTriggers());
+    B.triggers(B.subjectA).forEach((trigger, i) => S.testSync(`trigger ` + (i + 1 | 0).toString() + ` queues one TODO keyed by entity and subject`, () => S.thenTodos(S.whenCollect(S.givenEvent(trigger), entityId), [[
+        todoKey(B.subjectA),
+        B.item(entityId, B.subjectA)
+      ]])));
+    S.test("a confident answer reports the point", undefined, () => thenReports(S.whenTranslateMocked(S.givenTodo(todoKey(B.subjectA), B.item(entityId, B.subjectA)), translateWith({
+      TAG: "Ok",
+      _0: [{
+          label: B.subjectText(B.subjectA),
+          point: vienna,
+          relevance: 0.995
+        }]
+    })), "a location", B.isLocation));
+    S.test("a no-match completes the TODO with a verdict", undefined, () => thenReports(S.whenTranslateMocked(S.givenTodo(todoKey(B.subjectA), B.item(entityId, B.subjectA)), (id, item) => B.translate(id, item, {
+      geocode: param => Promise.resolve({
+        TAG: "Error",
+        _0: "NoMatch"
+      }),
+      messaging: Capabilities$Reventless.none.messaging
+    })), "a verdict", B.isVerdict));
+    S.test("an outage leaves the TODO pending", undefined, () => S.thenTodoStatus(S.whenTranslateMocked(S.givenTodo(todoKey(B.subjectA), B.item(entityId, B.subjectA)), (id, item) => B.translate(id, item, {
+      geocode: param => Promise.resolve({
+        TAG: "Error",
+        _0: {
+          TAG: "Unavailable",
+          _0: "502"
+        }
+      }),
+      messaging: Capabilities$Reventless.none.messaging
+    })), todoKey(B.subjectA), "Pending"));
+  });
+  return {
+    A: A,
+    S: S,
+    vienna: vienna,
+    bruges: bruges,
+    entityId: entityId,
+    todoKey: todoKey,
+    geocoder: geocoder,
+    translateWith: translateWith,
+    describeCommand: describeCommand,
+    thenReports: thenReports,
+    sorted: sorted,
+    strings: strings,
+    consumedSetMatchesTriggers: consumedSetMatchesTriggers,
+    register: register
+  };
+}
+
+let Outcome;
+
+export {
+  Outcome,
+  suiteName,
+  Make,
+}
+/* Message-Reventless Not a pure module */

package/src/AddressGeocoding_Guards.res

@@ -0,0 +1,58 @@
+/**
+The graft's decision rules, compiled once and called by every host: an answer for
+a subject the entity has moved off is stale, a redelivered answer is a no-op, and
+a verdict already recorded for the current subject is not recorded twice.
+
+The host keeps its own state — an aggregate's is snapshotted, so a trait-owned
+record in it would make every release that reshapes it a migration — and builds a
+`resolution` per call from the fields it already holds. What comes back is a
+verdict on one command, which the host names in its own event.
+*/
+
+/** The three fields the rules read, as the host holds them. Its invariant, which
+    every host arm must preserve: `resolvedFrom` is `None` or equal to `subject`. */
+type resolution = {
+  subject: string,
+  location: option<Reventless.GeoPoint.t>,
+  resolvedFrom: option<string>,
+}
+
+type verdict = Append | Ignore
+
+/** A subject the entity already has changes nothing; a different one reopens the
+    question, because the host's fold drops what was resolved for the old one. */
+let onSubjectUpdate = (r, ~subject) => subject == r.subject ? Ignore : Append
+
+/**
+A client supplying both halves. Idempotent only when *both* already match: the
+same subject with a different point is a pin correction, and swallowing it would
+lose the one edit a human came to make.
+*/
+let onSuppliedPair = (r, ~subject, ~location) =>
+  subject == r.subject && r.location == Some(location) ? Ignore : Append
+
+/**
+A point reported by the geocoder. Stale when it answers a subject since changed —
+applying it would pin the new subject at the old one's point with nothing to say
+the two disagree. Redelivery matters because commands arrive at least once and the
+slice re-publishes on every heartbeat until its TODO clears.
+*/
+let onLocationReport = (r, ~location, ~resolvedFrom) =>
+  if resolvedFrom != r.subject {
+    Ignore
+  } else if r.location == Some(location) && r.resolvedFrom == Some(resolvedFrom) {
+    Ignore
+  } else {
+    Append
+  }
+
+/** The same two guards for the verdict: `resolvedFrom` already naming the subject
+    is the record that it was tried and found wanting. */
+let onUnresolvableReport = (r, ~subject) =>
+  if subject != r.subject {
+    Ignore
+  } else if r.resolvedFrom == Some(subject) {
+    Ignore
+  } else {
+    Append
+  }

package/src/AddressGeocoding_Guards.res.mjs

@@ -0,0 +1,43 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+
+function onSubjectUpdate(r, subject) {
+  if (subject === r.subject) {
+    return "Ignore";
+  } else {
+    return "Append";
+  }
+}
+
+function onSuppliedPair(r, subject, location) {
+  if (subject === r.subject && Primitive_object.equal(r.location, location)) {
+    return "Ignore";
+  } else {
+    return "Append";
+  }
+}
+
+function onLocationReport(r, location, resolvedFrom) {
+  if (resolvedFrom !== r.subject || Primitive_object.equal(r.location, location) && Primitive_object.equal(r.resolvedFrom, resolvedFrom)) {
+    return "Ignore";
+  } else {
+    return "Append";
+  }
+}
+
+function onUnresolvableReport(r, subject) {
+  if (subject !== r.subject || Primitive_object.equal(r.resolvedFrom, subject)) {
+    return "Ignore";
+  } else {
+    return "Append";
+  }
+}
+
+export {
+  onSubjectUpdate,
+  onSuppliedPair,
+  onLocationReport,
+  onUnresolvableReport,
+}
+/* No side effect */