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

package/src/Attachments_Rules.res

@@ -7,11 +7,37 @@ A host maps its own constructors onto `op` and `fact` and keeps the spec surface
 the variants, their annotations, its own refusals. Nothing here knows what an
 entity is. `Attachments_Conformance` asserts these rules through a host.
 */
-
 /** The stored file's reference. A `StorageRef` path today, so `string` carries it
     without a wrapper the host would have to unwrap on every arm. */
 type ref = string
 
+// `@schema` so `Attachments_Scaffold`'s config can take this very type rather
+// than a second spelling of it. A graft's config and the rule it selects being
+// the same value is the point: a config that could say `"single"` where the
+// rules say `Single` is a config that can be misspelled.
+
+/**
+How many members a host's set may hold.
+
+Not a runtime variation: a graft fixes this once, and every command the graft
+emits is shaped by the answer. It reaches `decide` as an argument rather than
+sitting on `t` so that `empty` stays one value and a host that never mentions
+cardinality gets the behaviour it has today.
+
+Exactly one rule reads it — `Attach` — and that is the whole of the difference:
+a bounded set replaces its member where an unbounded one appends beside it.
+Everything else is already cardinality-blind. `SetPrimary` on a one-member set
+resolves to a no-op through the rules it already has (the only member is already
+the effective primary), which is why `Single` needs no branch for it and why the
+scaffold simply declines to emit the command rather than the rules refusing it.
+*/
+@schema
+type cardinality =
+  /** An unbounded, ordered set: a gallery. */
+  | Many
+  /** At most one member, replaced rather than added to. */
+  | Single
+
 /** Refolded per decision, never stored — a StateChangeSlice's state is. */
 type t = {
   attached: array<ref>,
@@ -24,11 +50,28 @@ let empty = {attached: [], primary: None, altTexts: []}
 
 /** What a host asks the set to do. */
 type op =
-  | /** `altText` is the caption a host may supply with the file itself. */
-  Attach({ref: ref, altText: option<string>})
+  /** `altText` is the caption a host may supply with the file itself. */
+  | Attach({ref: ref, altText: option<string>})
   | Remove({ref: ref})
+  /** Empty the set, whatever it holds.
+
+        The op a bounded set's remove command maps onto: with one member there is
+        no ref for the caller to name, and naming it would be asking them to
+        repeat what the row already says. Well defined at either cardinality —
+        an unbounded host that wants a "remove them all" command gets it here
+        rather than by looping its own remove. */
+  | Clear
   | SetPrimary({ref: ref})
   | SetAltText({ref: ref, altText: string})
+  /** Caption whichever member is the primary, without naming it.
+
+        The counterpart of `Clear`, and the op a bounded set's caption command
+        maps onto — with one member there is nothing to name. It is not
+        bounded-only, though: the primary is the one image a reader actually
+        sees, so "caption the hero" is a command an unbounded host wants too,
+        and resolving it here through `effectivePrimary` is what keeps the
+        answer the same as the member a projection puts first. */
+  | SetPrimaryAltText({altText: string})
 
 /** What the set decided, for the host to name in its own event. */
 type fact =
@@ -36,6 +79,25 @@ type fact =
   | Removed({ref: ref})
   | PrimarySet({ref: ref})
   | AltTextSet({ref: ref, altText: string})
+  /** The member a reader should now show, or `None` where the set has none.
+
+        **A conclusion, not a decision.** `PrimarySet` records that somebody
+        chose; this records what the set resolved to, however it got there —
+        which is a different fact, and the one anything outside the set can act
+        on. The two coincide on an explicit choice and diverge everywhere else:
+        the first attachment stands in with nobody choosing, and removing the
+        one that stood in promotes the next.
+
+        Emitted at **both** cardinalities even though a `Single` host could
+        derive it from its own `Attached`/`Removed` pair, for the reason
+        `decide` gives below for not collapsing those two: a fact that only some
+        grafts emit makes a subscriber ask how many members the host allows,
+        which is not its business.
+
+        Optional because "there is no longer one to show" is as much a change as
+        any other, and a subscriber that cannot be told it keeps showing a file
+        the set no longer holds. */
+  | EffectiveChanged({ref: option<ref>})
 
 /** The primary a reader should show: the one chosen, else the first attached, so
     a set never shows no file while it holds one. The read model applies the same
@@ -50,6 +112,33 @@ let effectivePrimary = t => primaryOf(~chosen=t.primary, ~attached=t.attached)
 
 let altTextOf = (t, ref) => t.altTexts->Array.find(((r, _)) => r == ref)->Option.map(((_, t)) => t)
 
+/**
+The set with the chosen member first, for a read model projecting it onto a row.
+
+This is where `primaryOf`'s rule lands on a view. The view carries the set and
+nothing beside it, so *being first* is how the row says which member is the
+primary — and "the chosen one, else the first attached" then needs no second
+field to hold the answer and no rule to keep that field in step. Attach appends,
+remove filters, and both leave the head alone unless they moved it; only this
+reorders.
+
+Sound for a projection because the order is derived: the events fully determine
+it, so a replay reproduces it. What it costs is that attachment order stops being
+readable off the view — the log still has it, and a consumer that wanted it back
+would have to be given it deliberately.
+
+Parameterised on `~ref` rather than owning the member type, for the reason
+`primaryOf` takes two arrays: the member record is the host's own `@schema` type
+and the field holding its reference is named for the host's store. A `chosen` the
+set does not hold leaves the order alone — a `SetPrimary` naming a member a
+removal already took away must not empty the row.
+*/
+let primaryFirst = (~chosen: ref, ~members: array<'m>, ~ref: 'm => ref): array<'m> =>
+  switch members->Array.find(m => ref(m) == chosen) {
+  | Some(primary) => Array.concat([primary], members->Array.filter(m => ref(m) != chosen))
+  | None => members
+  }
+
 let evolve = (t, fact) =>
   switch fact {
   | Attached({ref, altText}) =>
@@ -69,33 +158,94 @@ let evolve = (t, fact) =>
       altTexts: t.altTexts->Array.filter(((r, _)) => r != ref),
     }
   | PrimarySet({ref}) => {...t, primary: Some(ref)}
+  // Carries no state of its own: it is what `effectivePrimary` already answers,
+  // said out loud. Folding it would be storing a derivation beside the values it
+  // derives from, which is the one way the two could disagree.
+  | EffectiveChanged(_) => t
   | AltTextSet({ref, altText}) => {
       ...t,
       altTexts: t.altTexts->Array.filter(((r, _)) => r != ref)->Array.concat([(ref, altText)]),
     }
   }
 
-/** `Ok(None)` is the no-op a retried command must produce; the one refusal the set
-    owns is a primary or a caption on a ref it does not hold. */
-let decide = (t, op): result<option<fact>, [#NotAttached]> =>
+// Shared by the two captioning ops, which differ only in how they arrive at a
+// ref. Spelled once so a named caption and the primary's caption cannot end up
+// with different ideas of what a repeat is.
+let setAltText = (t, ~ref, ~altText): result<array<fact>, [#NotAttached]> =>
+  if !(t.attached->Array.includes(ref)) {
+    Error(#NotAttached)
+  } else if altTextOf(t, ref) == Some(altText) {
+    Ok([])
+  } else {
+    Ok([AltTextSet({ref, altText})])
+  }
+
+/**
+What the set decided, as facts in the order they happened.
+
+`Ok([])` is the no-op a retried command must produce; the one refusal the set
+owns is a primary or a caption on a ref it does not hold.
+
+An array rather than one optional fact, because a bounded set replacing its
+member decides two things at once — the old one leaves and the new one arrives —
+and an event log records both. Collapsing them into a single "replaced" fact
+would make a host declare an event that only bounded hosts have, which is one
+more way the two cardinalities' emitted surfaces could diverge.
+*/
+let decideFacts = (t, ~cardinality: cardinality=Many, op): result<array<fact>, [#NotAttached]> =>
   switch op {
   | Attach({ref, altText}) =>
-    t.attached->Array.includes(ref) ? Ok(None) : Ok(Some(Attached({ref, altText})))
-  | Remove({ref}) => t.attached->Array.includes(ref) ? Ok(Some(Removed({ref: ref}))) : Ok(None)
+    if t.attached->Array.includes(ref) {
+      Ok([])
+    } else {
+      switch cardinality {
+      | Many => Ok([Attached({ref, altText})])
+      // The whole of what `Single` changes. The members that leave are named
+      // individually rather than through `Clear` so the facts read the same
+      // whether one was there or (through some history nothing produces) more.
+      | Single =>
+        Ok(Array.concat(t.attached->Array.map(r => Removed({ref: r})), [Attached({ref, altText})]))
+      }
+    }
+  | Remove({ref}) => t.attached->Array.includes(ref) ? Ok([Removed({ref: ref})]) : Ok([])
+  | Clear => Ok(t.attached->Array.map(r => Removed({ref: r})))
   | SetPrimary({ref}) =>
     if !(t.attached->Array.includes(ref)) {
       Error(#NotAttached)
     } else if effectivePrimary(t) == Some(ref) {
-      Ok(None)
+      Ok([])
     } else {
-      Ok(Some(PrimarySet({ref: ref})))
+      Ok([PrimarySet({ref: ref})])
     }
-  | SetAltText({ref, altText}) =>
-    if !(t.attached->Array.includes(ref)) {
-      Error(#NotAttached)
-    } else if altTextOf(t, ref) == Some(altText) {
-      Ok(None)
-    } else {
-      Ok(Some(AltTextSet({ref, altText})))
+  | SetAltText({ref, altText}) => setAltText(t, ~ref, ~altText)
+  // An empty set has no primary, so there is nothing to caption — the same
+  // refusal a named ref the set does not hold gets, and for the same reason.
+  | SetPrimaryAltText({altText}) =>
+    switch effectivePrimary(t) {
+    | Some(ref) => setAltText(t, ~ref, ~altText)
+    | None => Error(#NotAttached)
     }
   }
+
+/**
+The set's own facts, followed by `EffectiveChanged` when those facts moved which
+member a reader should show.
+
+Appended rather than woven into each arm because the question is the same one
+after every op: fold what was decided, ask `effectivePrimary` again, and say so
+if the answer differs. An arm that had to remember to announce would eventually
+be an arm that forgot — and the ops where it moves without anybody choosing (a
+first attachment, a removal that promotes the next) are exactly the ones where
+forgetting is easiest.
+*/
+let decide = (t, ~cardinality: cardinality=Many, op): result<array<fact>, [#NotAttached]> =>
+  switch decideFacts(t, ~cardinality, op) {
+  | Error(_) as e => e
+  | Ok(facts) =>
+    let after = facts->Array.reduce(t, evolve)
+    Ok(
+      effectivePrimary(t) == effectivePrimary(after)
+        ? facts
+        : facts->Array.concat([EffectiveChanged({ref: effectivePrimary(after)})]),
+    )
+  }

package/src/Attachments_Rules.res.mjs

@@ -1,7 +1,15 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Sury from "sury";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+
+let cardinalitySchema = Sury.union([
+  Sury.literal("Many"),
+  Sury.literal("Single")
+]);
 
 let empty_attached = [];
 
@@ -29,6 +37,15 @@ function altTextOf(t, ref) {
   return Stdlib_Option.map(t.altTexts.find(param => param[0] === ref), param => param[1]);
 }
 
+function primaryFirst(chosen, members, ref) {
+  let primary = members.find(m => ref(m) === chosen);
+  if (primary !== undefined) {
+    return [Primitive_option.valFromOption(primary)].concat(members.filter(m => ref(m) !== chosen));
+  } else {
+    return members;
+  }
+}
+
 function evolve(t, fact) {
   switch (fact.TAG) {
     case "Attached" :
@@ -68,26 +85,77 @@ function evolve(t, fact) {
             fact.altText
           ]])
       };
+    case "EffectiveChanged" :
+      return t;
+  }
+}
+
+function setAltText(t, ref, altText) {
+  if (t.attached.includes(ref)) {
+    if (Primitive_object.equal(altTextOf(t, ref), altText)) {
+      return {
+        TAG: "Ok",
+        _0: []
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: [{
+            TAG: "AltTextSet",
+            ref: ref,
+            altText: altText
+          }]
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: "NotAttached"
+    };
   }
 }
 
-function decide(t, op) {
+function decideFacts(t, cardinalityOpt, op) {
+  let cardinality = cardinalityOpt !== undefined ? cardinalityOpt : "Many";
+  if (typeof op !== "object") {
+    return {
+      TAG: "Ok",
+      _0: t.attached.map(r => ({
+        TAG: "Removed",
+        ref: r
+      }))
+    };
+  }
   switch (op.TAG) {
     case "Attach" :
       let ref = op.ref;
       if (t.attached.includes(ref)) {
         return {
           TAG: "Ok",
-          _0: undefined
+          _0: []
+        };
+      }
+      let altText = op.altText;
+      if (cardinality === "Many") {
+        return {
+          TAG: "Ok",
+          _0: [{
+              TAG: "Attached",
+              ref: ref,
+              altText: altText
+            }]
         };
       } else {
         return {
           TAG: "Ok",
-          _0: {
-            TAG: "Attached",
-            ref: ref,
-            altText: op.altText
-          }
+          _0: t.attached.map(r => ({
+            TAG: "Removed",
+            ref: r
+          })).concat([{
+              TAG: "Attached",
+              ref: ref,
+              altText: altText
+            }])
         };
       }
     case "Remove" :
@@ -95,15 +163,15 @@ function decide(t, op) {
       if (t.attached.includes(ref$1)) {
         return {
           TAG: "Ok",
-          _0: {
-            TAG: "Removed",
-            ref: ref$1
-          }
+          _0: [{
+              TAG: "Removed",
+              ref: ref$1
+            }]
         };
       } else {
         return {
           TAG: "Ok",
-          _0: undefined
+          _0: []
         };
       }
     case "SetPrimary" :
@@ -112,15 +180,15 @@ function decide(t, op) {
         if (Primitive_object.equal(effectivePrimary(t), ref$2)) {
           return {
             TAG: "Ok",
-            _0: undefined
+            _0: []
           };
         } else {
           return {
             TAG: "Ok",
-            _0: {
-              TAG: "PrimarySet",
-              ref: ref$2
-            }
+            _0: [{
+                TAG: "PrimarySet",
+                ref: ref$2
+              }]
           };
         }
       } else {
@@ -130,38 +198,47 @@ function decide(t, op) {
         };
       }
     case "SetAltText" :
-      let ref$3 = op.ref;
-      if (!t.attached.includes(ref$3)) {
+      return setAltText(t, op.ref, op.altText);
+    case "SetPrimaryAltText" :
+      let ref$3 = effectivePrimary(t);
+      if (ref$3 !== undefined) {
+        return setAltText(t, ref$3, op.altText);
+      } else {
         return {
           TAG: "Error",
           _0: "NotAttached"
         };
       }
-      let altText = op.altText;
-      if (Primitive_object.equal(altTextOf(t, ref$3), altText)) {
-        return {
-          TAG: "Ok",
-          _0: undefined
-        };
-      } else {
-        return {
-          TAG: "Ok",
-          _0: {
-            TAG: "AltTextSet",
-            ref: ref$3,
-            altText: altText
-          }
-        };
-      }
   }
 }
 
+function decide(t, cardinalityOpt, op) {
+  let cardinality = cardinalityOpt !== undefined ? cardinalityOpt : "Many";
+  let e = decideFacts(t, cardinality, op);
+  if (e.TAG !== "Ok") {
+    return e;
+  }
+  let facts = e._0;
+  let after = Stdlib_Array.reduce(facts, t, evolve);
+  return {
+    TAG: "Ok",
+    _0: Primitive_object.equal(effectivePrimary(t), effectivePrimary(after)) ? facts : facts.concat([{
+          TAG: "EffectiveChanged",
+          ref: effectivePrimary(after)
+        }])
+  };
+}
+
 export {
+  cardinalitySchema,
   empty,
   primaryOf,
   effectivePrimary,
   altTextOf,
+  primaryFirst,
   evolve,
+  setAltText,
+  decideFacts,
   decide,
 }
-/* No side effect */
+/* cardinalitySchema Not a pure module */