@reventlessdev/trait-attachments 1.0.0-alpha.1 → 1.0.0-alpha.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/trait-attachments",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.10",
   "description": "Attachments domain trait: rules, host contract, conformance suite and emitter for an ordered set of stored files on an entity, with a primary and captions",
   "license": "Apache-2.0",
   "files": [
@@ -13,8 +13,8 @@
   "dependencies": {
     "sury": "11.0.0-rc.2",
     "sury-ppx": "11.0.0-rc.2",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.199",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.125"
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.208",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.134"
   },
   "devDependencies": {
     "rescript": "12.3.0"

package/src/Attachments.res

@@ -6,7 +6,6 @@ contract is over that slice. The rules live in `Attachments_Rules` and are asser
 through a host by `Attachments_Conformance`; the spec surface the host maps onto
 them is written by `Attachments_Scaffold`.
 */
-
 /**
 This trait's own account of itself — see `AddressGeocoding.declaration` for why the
 version is read rather than written.
@@ -43,13 +42,27 @@ module type Binding = {
   module Spec: ReventlessGwt.Behavior_GWT.BehaviorSpec
   module Behavior: ReventlessGwt.Behavior_GWT.Behavior with module Spec = Spec
 
-  /** History that brings the entity into existence with an empty set. */
-  let created: array<Spec.consumedEvent>
-  /** The set's own facts, as the slice consumes them. */
-  let attachedC: ref => Spec.consumedEvent
-  let removedC: ref => Spec.consumedEvent
-  let primarySetC: ref => Spec.consumedEvent
-  let altTextSetC: (ref, string) => Spec.consumedEvent
+  /** The same facts as the slice **consumes** them, for building history.
+
+      A slice declares `consumedEvent` and `event` separately and they differ —
+      the consumed form carries no entity id, because the partition already
+      says which entity it belongs to. So a suite needs both spellings of the
+      same fact: one to lay down history, one to assert what was emitted.
+
+      Grouped rather than suffixed. The pairs used to read `attachedC` against
+      `attached`, which said "consumed" only to someone who already knew — and
+      in a codebase where every binding also carries commands, a bare `C` reads
+      just as naturally as one. */
+  module Consumed: {
+    /** History that brings the entity into existence with an empty set. */
+    let created: array<Spec.consumedEvent>
+    let attached: ref => Spec.consumedEvent
+    let removed: ref => Spec.consumedEvent
+    let primarySet: ref => Spec.consumedEvent
+    /** The conclusion — see `Attachments_Rules.fact`. */
+    let effectiveChanged: option<ref> => Spec.consumedEvent
+    let altTextSet: (ref, string) => Spec.consumedEvent
+  }
 
   let attach: ref => Spec.command
   let remove: ref => Spec.command
@@ -60,7 +73,69 @@ module type Binding = {
   let attached: ref => Spec.event
   let removed: ref => Spec.event
   let primarySet: ref => Spec.event
+  /** The member a reader should now show, or `None` where the set has none.
+      Every graft declares it, whatever its cardinality: a subscriber reading it
+      must not have to know how many members the host allows. */
+  let effectiveChanged: option<ref> => Spec.event
   let altTextSet: (ref, string) => Spec.event
   /** The refusal for a primary or caption on a ref that is not in the set. */
   let notAttached: Spec.error
 }
+
+/**
+One host of the **bounded** cardinality, bound.
+
+A separate contract rather than optional members on {!Binding}, because what
+`Attachments_Rules.Single` changes is the host's command surface and not just a
+rule: there is no primary to choose between one member, so the graft declares no
+such command, and there is no ref for a remove to name, so it declares none.
+Both absences are facts a module type states better than a test does — a
+`Single` graft that grew a `SetPrimary` command would fail to satisfy this
+signature, which is the check, and it happens at compile time.
+
+Everything the two contracts share is spelled identically on purpose: a reader
+comparing them should find the difference in what is missing, not in how the
+common half is phrased.
+*/
+module type SingleBinding = {
+  type ref
+  /** Two refs that differ — the second is what replaces the first. */
+  let refA: ref
+  let refB: ref
+
+  module Spec: ReventlessGwt.Behavior_GWT.BehaviorSpec
+  module Behavior: ReventlessGwt.Behavior_GWT.Behavior with module Spec = Spec
+
+  /** The facts as the slice **consumes** them — see `Binding.Consumed`. No
+      `primarySet`: at this cardinality nothing emits one. */
+  module Consumed: {
+    /** History that brings the entity into existence with an empty set. */
+    let created: array<Spec.consumedEvent>
+    let attached: ref => Spec.consumedEvent
+    let removed: ref => Spec.consumedEvent
+    let altTextSet: (ref, string) => Spec.consumedEvent
+    /** Declared at this cardinality too even though `attached`/`removed` imply
+        it here: a subscriber must not have to know how many members a host
+        allows to know what to read. */
+    let effectiveChanged: option<ref> => Spec.consumedEvent
+  }
+
+  let attach: ref => Spec.command
+  /** Remove whatever is held. Takes no ref — there is only one, and asking the
+      caller to name it is asking them to repeat what the row already says. */
+  let clear: Spec.command
+  /** Caption whatever is held. Ref-less for `clear`'s reason, and there is a
+      second one here: a bounded host's view carries the reference as a scalar
+      and no collection at all, so there is no field for a selection to be a
+      member *of*. */
+  let setAltText: string => Spec.command
+
+  /** The set's facts, as the slice emits them. */
+  let attached: ref => Spec.event
+  let removed: ref => Spec.event
+  let altTextSet: (ref, string) => Spec.event
+  /** The member a reader should now show, or `None` where nothing is held. */
+  let effectiveChanged: option<ref> => Spec.event
+  /** The refusal for a caption on a ref that is not held. */
+  let notAttached: Spec.error
+}

package/src/Attachments_Conformance.res

@@ -2,23 +2,29 @@
 The conformance suite, run by a host against its own graft. `Make(Binding).register()`
 inside a Jest test file registers one `describe` block over the binding.
 */
-
 /** 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. */
+    other's prose.
+
+    One title for both cardinalities: a host conforms to this trait or it does
+    not, and which of the two suites established that is not a fact a
+    certificate should have to know. `MakeSingle` registers under the same
+    name. */
 let suiteName = (host: string) => `${host} conforms to the attachments trait`
 
 module Make = (B: Attachments.Binding) => {
   module G = ReventlessGwt.Behavior_GWT.Make(B.Spec, B.Behavior)
 
-  let withA = Array.concat(B.created, [B.attachedC(B.refA)])
-  let withAB = Array.concat(withA, [B.attachedC(B.refB)])
+  let withA = Array.concat(B.Consumed.created, [B.Consumed.attached(B.refA)])
+  let withAB = Array.concat(withA, [B.Consumed.attached(B.refB)])
 
   let register = () =>
     G.describe(suiteName(B.Spec.name), () => {
       G.test("the first attachment is appended", () =>
-        G.givenEvents(B.created)->G.whenCmd(B.attach(B.refA))->G.thenEvent(B.attached(B.refA))
+        G.givenEvents(B.Consumed.created)
+        ->G.whenCmd(B.attach(B.refA))
+        ->G.thenEvents([B.attached(B.refA), B.effectiveChanged(Some(B.refA))])
       )
 
       G.test("attaching a ref already in the set is a no-op", () =>
@@ -30,7 +36,9 @@ module Make = (B: Attachments.Binding) => {
       )
 
       G.test("removing an attached ref is appended", () =>
-        G.givenEvents(withA)->G.whenCmd(B.remove(B.refA))->G.thenEvent(B.removed(B.refA))
+        G.givenEvents(withA)
+        ->G.whenCmd(B.remove(B.refA))
+        ->G.thenEvents([B.removed(B.refA), B.effectiveChanged(None)])
       )
 
       G.test("removing a ref not in the set is a no-op", () =>
@@ -38,9 +46,9 @@ module Make = (B: Attachments.Binding) => {
       )
 
       G.test("a removed ref can be attached again", () =>
-        G.givenEvents(Array.concat(withA, [B.removedC(B.refA)]))
+        G.givenEvents(Array.concat(withA, [B.Consumed.removed(B.refA)]))
         ->G.whenCmd(B.attach(B.refA))
-        ->G.thenEvent(B.attached(B.refA))
+        ->G.thenEvents([B.attached(B.refA), B.effectiveChanged(Some(B.refA))])
       )
 
       G.test("the primary must be in the set", () =>
@@ -52,27 +60,50 @@ module Make = (B: Attachments.Binding) => {
       )
 
       G.test("choosing another primary is appended", () =>
-        G.givenEvents(withAB)->G.whenCmd(B.setPrimary(B.refB))->G.thenEvent(B.primarySet(B.refB))
+        G.givenEvents(withAB)
+        ->G.whenCmd(B.setPrimary(B.refB))
+        ->G.thenEvents([B.primarySet(B.refB), B.effectiveChanged(Some(B.refB))])
       )
 
       G.test("choosing the current primary is a no-op", () =>
-        G.givenEvents(Array.concat(withAB, [B.primarySetC(B.refB)]))
+        G.givenEvents(Array.concat(withAB, [B.Consumed.primarySet(B.refB)]))
         ->G.whenCmd(B.setPrimary(B.refB))
         ->G.thenNoEvent
       )
 
       G.test("removing the chosen primary lets the first remaining stand in", () =>
-        G.givenEvents(Array.concat(withAB, [B.primarySetC(B.refB), B.removedC(B.refB)]))
+        G.givenEvents(
+          Array.concat(withAB, [B.Consumed.primarySet(B.refB), B.Consumed.removed(B.refB)]),
+        )
         ->G.whenCmd(B.setPrimary(B.refA))
         ->G.thenNoEvent
       )
 
+      // The two moves nobody decides. Neither produces a fact of its own — the
+      // set simply resolves differently afterwards — which is why anything
+      // outside it could not follow the primary before this was announced.
+      G.test("removing the member that stood in promotes the next, and says so", () =>
+        G.givenEvents(withAB)
+        ->G.whenCmd(B.remove(B.refA))
+        ->G.thenEvents([B.removed(B.refA), B.effectiveChanged(Some(B.refB))])
+      )
+
+      G.test("removing the chosen primary announces the one that stands in", () =>
+        G.givenEvents(Array.concat(withAB, [B.Consumed.primarySet(B.refB)]))
+        ->G.whenCmd(B.remove(B.refB))
+        ->G.thenEvents([B.removed(B.refB), B.effectiveChanged(Some(B.refA))])
+      )
+
       G.test("a caption needs its ref in the set", () =>
         G.givenEvents(withA)
         ->G.whenCmd(B.setAltText(B.refB, "side"))
         ->G.thenError(B.notAttached)
       )
 
+      // One fact and no second one: a caption moves no file, so the conclusion
+      // is unchanged and must not be announced. This is what stops an
+      // implementation appending it after every command rather than after the
+      // ones that move it.
       G.test("a caption is appended", () =>
         G.givenEvents(withA)
         ->G.whenCmd(B.setAltText(B.refA, "front"))
@@ -80,9 +111,97 @@ module Make = (B: Attachments.Binding) => {
       )
 
       G.test("repeating the caption is a no-op", () =>
-        G.givenEvents(Array.concat(withA, [B.altTextSetC(B.refA, "front")]))
+        G.givenEvents(Array.concat(withA, [B.Consumed.altTextSet(B.refA, "front")]))
         ->G.whenCmd(B.setAltText(B.refA, "front"))
         ->G.thenNoEvent
       )
     })
 }
+
+/**
+The suite for a host of the bounded cardinality.
+
+Smaller than `Make`'s, and smaller for a reason worth reading: most of what the
+larger suite asserts is about choosing between members, and a set that holds one
+member has nothing to choose. Those assertions are not skipped here — they are
+unreachable, because {!Attachments.SingleBinding} does not admit the commands
+that would reach them. The absent primary is checked by the compiler.
+
+What is left is the one rule cardinality actually changes — a second attachment
+replaces rather than joins — plus the ref-less remove and the captions, which a
+single image wants exactly as much as a gallery member does.
+*/
+module MakeSingle = (B: Attachments.SingleBinding) => {
+  module G = ReventlessGwt.Behavior_GWT.Make(B.Spec, B.Behavior)
+
+  let withA = Array.concat(B.Consumed.created, [B.Consumed.attached(B.refA)])
+
+  let register = () =>
+    G.describe(suiteName(B.Spec.name), () => {
+      G.test("the first attachment is appended", () =>
+        G.givenEvents(B.Consumed.created)
+        ->G.whenCmd(B.attach(B.refA))
+        ->G.thenEvents([B.attached(B.refA), B.effectiveChanged(Some(B.refA))])
+      )
+
+      G.test("attaching the ref already held is a no-op", () =>
+        G.givenEvents(withA)->G.whenCmd(B.attach(B.refA))->G.thenNoEvent
+      )
+
+      // The assertion the cardinality exists for. Two facts, in order: what was
+      // there leaves before what replaces it arrives, so a reader replaying the
+      // log never sees the set hold both.
+      G.test("a second ref replaces the first rather than joining it", () =>
+        G.givenEvents(withA)
+        ->G.whenCmd(B.attach(B.refB))
+        ->G.thenEvents([B.removed(B.refA), B.attached(B.refB), B.effectiveChanged(Some(B.refB))])
+      )
+
+      G.test("clearing a held set removes what it holds", () =>
+        G.givenEvents(withA)
+        ->G.whenCmd(B.clear)
+        ->G.thenEvents([B.removed(B.refA), B.effectiveChanged(None)])
+      )
+
+      G.test("clearing an empty set is a no-op", () =>
+        G.givenEvents(B.Consumed.created)->G.whenCmd(B.clear)->G.thenNoEvent
+      )
+
+      G.test("a replaced ref can be attached again", () =>
+        G.givenEvents(
+          Array.concat(withA, [B.Consumed.removed(B.refA), B.Consumed.attached(B.refB)]),
+        )
+        ->G.whenCmd(B.attach(B.refA))
+        ->G.thenEvents([B.removed(B.refB), B.attached(B.refA), B.effectiveChanged(Some(B.refA))])
+      )
+
+      // The caption names no ref either, so what it lands on is whatever is
+      // held — and the assertion is that it lands on the *right* ref, which is
+      // the only thing a ref-less command can get wrong.
+      G.test("a caption lands on the ref that is held", () =>
+        G.givenEvents(withA)
+        ->G.whenCmd(B.setAltText("front"))
+        ->G.thenEvent(B.altTextSet(B.refA, "front"))
+      )
+
+      G.test("a caption follows a replacement onto the new ref", () =>
+        G.givenEvents(
+          Array.concat(withA, [B.Consumed.removed(B.refA), B.Consumed.attached(B.refB)]),
+        )
+        ->G.whenCmd(B.setAltText("side"))
+        ->G.thenEvent(B.altTextSet(B.refB, "side"))
+      )
+
+      G.test("captioning an empty set is refused", () =>
+        G.givenEvents(B.Consumed.created)
+        ->G.whenCmd(B.setAltText("front"))
+        ->G.thenError(B.notAttached)
+      )
+
+      G.test("repeating the caption is a no-op", () =>
+        G.givenEvents(Array.concat(withA, [B.Consumed.altTextSet(B.refA, "front")]))
+        ->G.whenCmd(B.setAltText("front"))
+        ->G.thenNoEvent
+      )
+    })
+}

package/src/Attachments_Conformance.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Behavior_GWT$ReventlessGwt from "@reventlessdev/reventless-gwt/src/Behavior_GWT.res.mjs";
 
 function suiteName(host) {
@@ -13,26 +14,46 @@ function Make(B) {
     evolve: $$let.evolve,
     decide: $$let.decide
   });
-  let withA = B.created.concat([B.attachedC(B.refA)]);
-  let withAB = withA.concat([B.attachedC(B.refB)]);
+  let withA = B.Consumed.created.concat([B.Consumed.attached(B.refA)]);
+  let withAB = withA.concat([B.Consumed.attached(B.refB)]);
   let register = () => G.describe(suiteName(B.Spec.name), () => {
-    G.test("the first attachment is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(B.created), B.attach(B.refA)), B.attached(B.refA)));
+    G.test("the first attachment is appended", () => G.thenEvents(G.whenCmd(G.givenEvents(B.Consumed.created), B.attach(B.refA)), [
+      B.attached(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
     G.test("attaching a ref already in the set is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA), B.attach(B.refA))));
     G.test("a second ref extends the set rather than replacing it", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.attach(B.refB)), B.attached(B.refB)));
-    G.test("removing an attached ref is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.remove(B.refA)), B.removed(B.refA)));
+    G.test("removing an attached ref is appended", () => G.thenEvents(G.whenCmd(G.givenEvents(withA), B.remove(B.refA)), [
+      B.removed(B.refA),
+      B.effectiveChanged(undefined)
+    ]));
     G.test("removing a ref not in the set is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA), B.remove(B.refB))));
-    G.test("a removed ref can be attached again", () => G.thenEvent(G.whenCmd(G.givenEvents(withA.concat([B.removedC(B.refA)])), B.attach(B.refA)), B.attached(B.refA)));
+    G.test("a removed ref can be attached again", () => G.thenEvents(G.whenCmd(G.givenEvents(withA.concat([B.Consumed.removed(B.refA)])), B.attach(B.refA)), [
+      B.attached(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
     G.test("the primary must be in the set", () => G.thenError(G.whenCmd(G.givenEvents(withA), B.setPrimary(B.refB)), B.notAttached));
     G.test("the first attached is the primary until one is chosen", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withAB), B.setPrimary(B.refA))));
-    G.test("choosing another primary is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(withAB), B.setPrimary(B.refB)), B.primarySet(B.refB)));
-    G.test("choosing the current primary is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withAB.concat([B.primarySetC(B.refB)])), B.setPrimary(B.refB))));
+    G.test("choosing another primary is appended", () => G.thenEvents(G.whenCmd(G.givenEvents(withAB), B.setPrimary(B.refB)), [
+      B.primarySet(B.refB),
+      B.effectiveChanged(Primitive_option.some(B.refB))
+    ]));
+    G.test("choosing the current primary is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withAB.concat([B.Consumed.primarySet(B.refB)])), B.setPrimary(B.refB))));
     G.test("removing the chosen primary lets the first remaining stand in", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withAB.concat([
-      B.primarySetC(B.refB),
-      B.removedC(B.refB)
+      B.Consumed.primarySet(B.refB),
+      B.Consumed.removed(B.refB)
     ])), B.setPrimary(B.refA))));
+    G.test("removing the member that stood in promotes the next, and says so", () => G.thenEvents(G.whenCmd(G.givenEvents(withAB), B.remove(B.refA)), [
+      B.removed(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refB))
+    ]));
+    G.test("removing the chosen primary announces the one that stands in", () => G.thenEvents(G.whenCmd(G.givenEvents(withAB.concat([B.Consumed.primarySet(B.refB)])), B.remove(B.refB)), [
+      B.removed(B.refB),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
     G.test("a caption needs its ref in the set", () => G.thenError(G.whenCmd(G.givenEvents(withA), B.setAltText(B.refB, "side")), B.notAttached));
     G.test("a caption is appended", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.setAltText(B.refA, "front")), B.altTextSet(B.refA, "front")));
-    G.test("repeating the caption is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA.concat([B.altTextSetC(B.refA, "front")])), B.setAltText(B.refA, "front"))));
+    G.test("repeating the caption is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA.concat([B.Consumed.altTextSet(B.refA, "front")])), B.setAltText(B.refA, "front"))));
   });
   return {
     G: G,
@@ -42,8 +63,56 @@ function Make(B) {
   };
 }
 
+function MakeSingle(B) {
+  let $$let = B.Behavior;
+  let G = Behavior_GWT$ReventlessGwt.Make(B.Spec)({
+    initialState: $$let.initialState,
+    evolve: $$let.evolve,
+    decide: $$let.decide
+  });
+  let withA = B.Consumed.created.concat([B.Consumed.attached(B.refA)]);
+  let register = () => G.describe(suiteName(B.Spec.name), () => {
+    G.test("the first attachment is appended", () => G.thenEvents(G.whenCmd(G.givenEvents(B.Consumed.created), B.attach(B.refA)), [
+      B.attached(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
+    G.test("attaching the ref already held is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA), B.attach(B.refA))));
+    G.test("a second ref replaces the first rather than joining it", () => G.thenEvents(G.whenCmd(G.givenEvents(withA), B.attach(B.refB)), [
+      B.removed(B.refA),
+      B.attached(B.refB),
+      B.effectiveChanged(Primitive_option.some(B.refB))
+    ]));
+    G.test("clearing a held set removes what it holds", () => G.thenEvents(G.whenCmd(G.givenEvents(withA), B.clear), [
+      B.removed(B.refA),
+      B.effectiveChanged(undefined)
+    ]));
+    G.test("clearing an empty set is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(B.Consumed.created), B.clear)));
+    G.test("a replaced ref can be attached again", () => G.thenEvents(G.whenCmd(G.givenEvents(withA.concat([
+      B.Consumed.removed(B.refA),
+      B.Consumed.attached(B.refB)
+    ])), B.attach(B.refA)), [
+      B.removed(B.refB),
+      B.attached(B.refA),
+      B.effectiveChanged(Primitive_option.some(B.refA))
+    ]));
+    G.test("a caption lands on the ref that is held", () => G.thenEvent(G.whenCmd(G.givenEvents(withA), B.setAltText("front")), B.altTextSet(B.refA, "front")));
+    G.test("a caption follows a replacement onto the new ref", () => G.thenEvent(G.whenCmd(G.givenEvents(withA.concat([
+      B.Consumed.removed(B.refA),
+      B.Consumed.attached(B.refB)
+    ])), B.setAltText("side")), B.altTextSet(B.refB, "side")));
+    G.test("captioning an empty set is refused", () => G.thenError(G.whenCmd(G.givenEvents(B.Consumed.created), B.setAltText("front")), B.notAttached));
+    G.test("repeating the caption is a no-op", () => G.thenNoEvent(G.whenCmd(G.givenEvents(withA.concat([B.Consumed.altTextSet(B.refA, "front")])), B.setAltText("front"))));
+  });
+  return {
+    G: G,
+    withA: withA,
+    register: register
+  };
+}
+
 export {
   suiteName,
   Make,
+  MakeSingle,
 }
 /* Behavior_GWT-ReventlessGwt Not a pure module */