hecks 3.5.0 → 3.7.0

data/lib/hecks/projections/site/payload/fields/definitions.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        module Fields
+          # The TypeScript literals of a collection's field definitions: one `{ name, type, ... }`
+          # for a scalar, an array field for a list, and an array of sub-fields for a composite.
+          module Definitions
+            module_function
+
+            # @return [Array<Array<String>>] the `[key, value]` pairs of a scalar field's literal
+            def base(attr, row, name, required)
+              kind = Fields.kind_of(attr, row)
+              required = row[:required] if row.key?(:required)
+              pairs = [["name", name.to_json], ["type", KINDS.fetch(kind).to_json]]
+              pairs << ["required", "true"] if required
+              pairs << ["unique", "true"] if attr.name == "slug"
+              pairs << ["defaultValue", row[:default].to_json] if row[:default]
+              pairs.concat(extras(kind, row))
+            end
+
+            def extras(kind, row, describe: true)
+              pairs = []
+              pairs << ["options", options(row[:options])] if kind == "select" && row[:options]
+              pairs << ["relationTo", row[:relation].to_json] if row[:relation]
+              admin = admin_pairs(kind, row, describe)
+              pairs << ["admin", "{ #{admin.map { |key, value| "#{key}: #{value}" }.join(", ")} }"] if admin.any?
+              pairs
+            end
+
+            def admin_pairs(kind, row, describe)
+              admin = []
+              admin << ["description", row[:description].to_json] if describe && row[:description]
+              if KINDS[kind] == "date"
+                admin << ["date",
+                          "{ pickerAppearance: #{(kind == "day" ? "dayOnly" : "dayAndTime").to_json} }"]
+              end
+              admin
+            end
+
+            def options(text)
+              items = text.split(",").map(&:strip).reject(&:empty?).map do |item|
+                value, label = item.split("=", 2)
+                label ? "{ label: #{label.to_json}, value: #{value.to_json} }" : value.to_json
+              end
+              "[#{items.join(", ")}]"
+            end
+
+            def literal(pairs) = "{ #{pairs.map { |key, value| "#{key}: #{value}" }.join(", ")} }"
+
+            def array(_attr, row, name)
+              kind = row[:kind] || "text"
+              element = literal([["name", '"value"'], ["type", KINDS.fetch(kind).to_json], ["required", "true"],
+                                 *extras(kind, row, describe: false)])
+              array_literal(name, row, "[#{element}]")
+            end
+
+            def composite(attr, row, name, rows)
+              subs = attr.parts.map { |part| sub_field(attr, part, rows) }
+              array_literal(name, row, "[#{subs.join(", ")}]")
+            end
+
+            def sub_field(attr, part, rows)
+              part_row = Fields.row_for(rows, attr.name, part.name)
+              literal(base(part, part_row.merge(required: part_row.fetch(:required, true)), part.ts, true))
+            end
+
+            # An array field named `name`, with the labels and description its row gives.
+            def array_literal(name, row, fields)
+              pairs = [["name", name.to_json], ["type", '"array"']]
+              pairs << ["labels", labels(row[:label])] if row[:label]
+              pairs << ["admin", "{ description: #{row[:description].to_json} }"] if row[:description]
+              pairs << ["fields", fields]
+              literal(pairs)
+            end
+
+            def labels(text)
+              singular, plural = text.split("|", 2)
+              "{ singular: #{singular.to_json}, plural: #{(plural || "#{singular}s").to_json} }"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/payload/fields/readers.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        module Fields
+          # The TypeScript expressions that read one saved document field back into the aggregate's
+          # input: a scalar, a list, a related document, a date or a composite's rows.
+          module Readers
+            module_function
+
+            def input(attr, row, rows)
+              return composite_input(attr, rows) if attr.shape == :composite
+
+              name = row[:field] || attr.ts
+              kind = Fields.kind_of(attr, row)
+              return list_input(name, kind) if attr.list
+
+              scalar_input(attr, row, name, kind)
+            end
+
+            def list_input(name, kind) = "valuesOf(doc.#{name}, #{kind == "date" ? "isoOrNull" : "nonBlank"})"
+
+            def scalar_input(attr, row, name, kind)
+              case kind
+              when "upload", "relationship" then related_input(row, name, kind)
+              when "date", "day" then date_input(attr, name, kind)
+              when "number" then number_input(attr, name)
+              else attr.optional ? "nonBlank(doc.#{name})" : "String(doc.#{name})"
+              end
+            end
+
+            def related_input(row, name, kind)
+              via = row[:via] || (kind == "upload" ? "url" : "slug")
+              "await related(req, #{row[:relation].to_json}, doc.#{name}, #{via.to_json})"
+            end
+
+            def number_input(attr, name)
+              attr.optional ? "doc.#{name} == null ? null : Number(doc.#{name})" : "Number(doc.#{name})"
+            end
+
+            def date_input(attr, name, kind)
+              return "isoOrNull(doc.#{name})#{' ?? ""' unless attr.optional}" unless attr.shape == :integer || kind == "day"
+
+              stamp = "doc.#{name} ? new Date(doc.#{name} as string).getTime() : Date.now()"
+              "Math.floor((#{stamp}) / 1000)"
+            end
+
+            def composite_input(attr, rows)
+              parts = attr.parts.map do |part|
+                "#{part.ts}: #{part_input(part, Fields.row_for(rows, attr.name, part.name))}"
+              end.join(", ")
+              "(Array.isArray(doc.#{attr.ts}) ? doc.#{attr.ts} : []).map((raw) => { const s = raw as Doc; return { #{parts} }; })"
+            end
+
+            def part_input(part, row)
+              return "isoOrNull(s.#{part.ts}) ?? \"\"" if KINDS[row[:kind]] == "date"
+
+              "nonBlank(s.#{part.ts}) ?? \"\""
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/payload/fields.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "fields/definitions"
+require_relative "fields/readers"
 
 module Hecks
   module Projections
@@ -58,7 +60,7 @@ module Hecks
             kind = row[:kind]
             if kind && !KINDS.key?(kind)
               raise ArgumentError,
-                    "PayloadField kind #{kind.inspect} is one of #{KINDS.keys.join(', ')}"
+                    "PayloadField kind #{kind.inspect} is one of #{KINDS.keys.join(", ")}"
             end
             return unless %w[upload relationship].include?(kind) && !row[:relation]
 
@@ -84,21 +86,25 @@ module Hecks
 
           def aggregate(agg, rows)
             var = "#{agg.noun[0].downcase}#{agg.noun[1..]}"
-            fields = fields_of(agg, rows).map { |name, text| "  #{name}: #{text}," }.join("\n")
-            inputs = agg.attrs.map { |attr| "  #{attr.ts}: #{input(attr, row_for(rows, attr.name), rows)}," }.join("\n")
             <<~TS.chomp
               // ---- #{agg.noun} ----
 
               export const #{var}Fields = {
-              #{fields}
+              #{fields_block(agg, rows)}
               } satisfies Record<string, Field>;
 
               export const #{var}FromDoc = async (req: PayloadRequest, doc: Doc): Promise<#{agg.noun}Input> => ({
-              #{inputs}
+              #{inputs_block(agg, rows)}
               });
             TS
           end
 
+          def fields_block(agg, rows) = fields_of(agg, rows).map { |name, text| "  #{name}: #{text}," }.join("\n")
+
+          def inputs_block(agg, rows)
+            agg.attrs.map { |attr| "  #{attr.ts}: #{Readers.input(attr, row_for(rows, attr.name), rows)}," }.join("\n")
+          end
+
           def row_for(rows, attribute, part = nil)
             wanted = part ? "#{attribute}.#{part}" : attribute
             rows.find { |row| row[:attribute] == wanted } || {}
@@ -115,118 +121,15 @@ module Hecks
 
           def field(_agg, attr, row, rows)
             name = field_name(attr, row)
-            return composite(attr, row, name, rows) if attr.shape == :composite
-            return array(attr, row, name) if attr.list
+            return Definitions.composite(attr, row, name, rows) if attr.shape == :composite
+            return Definitions.array(attr, row, name) if attr.list
 
-            literal(base(attr, row, name, !attr.optional))
+            Definitions.literal(Definitions.base(attr, row, name, !attr.optional))
           end
 
           def kind_of(attr, row)
             row[:kind] || (attr.shape == :integer ? "number" : "text")
           end
-
-          def base(attr, row, name, required)
-            kind = kind_of(attr, row)
-            required = row[:required] if row.key?(:required)
-            pairs = [["name", name.to_json], ["type", KINDS.fetch(kind).to_json]]
-            pairs << ["required", "true"] if required
-            pairs << ["unique", "true"] if attr.name == "slug"
-            pairs << ["defaultValue", row[:default].to_json] if row[:default]
-            pairs.concat(extras(kind, row))
-          end
-
-          def extras(kind, row, describe: true)
-            pairs = []
-            pairs << ["options", options(row[:options])] if kind == "select" && row[:options]
-            pairs << ["relationTo", row[:relation].to_json] if row[:relation]
-            admin = []
-            admin << ["description", row[:description].to_json] if describe && row[:description]
-            if KINDS[kind] == "date"
-              admin << ["date",
-                        "{ pickerAppearance: #{(kind == 'day' ? 'dayOnly' : 'dayAndTime').to_json} }"]
-            end
-            pairs << ["admin", "{ #{admin.map { |key, value| "#{key}: #{value}" }.join(', ')} }"] if admin.any?
-            pairs
-          end
-
-          def options(text)
-            items = text.split(",").map(&:strip).reject(&:empty?).map do |item|
-              value, label = item.split("=", 2)
-              label ? "{ label: #{label.to_json}, value: #{value.to_json} }" : value.to_json
-            end
-            "[#{items.join(', ')}]"
-          end
-
-          def literal(pairs) = "{ #{pairs.map { |key, value| "#{key}: #{value}" }.join(', ')} }"
-
-          def array(_attr, row, name)
-            kind = row[:kind] || "text"
-            element = literal([["name", '"value"'], ["type", KINDS.fetch(kind).to_json], ["required", "true"],
-                               *extras(kind, row, describe: false)])
-            pairs = [["name", name.to_json], ["type", '"array"']]
-            pairs << ["labels", labels(row[:label])] if row[:label]
-            pairs << ["admin", "{ description: #{row[:description].to_json} }"] if row[:description]
-            pairs << ["fields", "[#{element}]"]
-            literal(pairs)
-          end
-
-          def labels(text)
-            singular, plural = text.split("|", 2)
-            "{ singular: #{singular.to_json}, plural: #{(plural || "#{singular}s").to_json} }"
-          end
-
-          def composite(attr, row, name, rows)
-            subs = attr.parts.map do |part|
-              part_row = row_for(rows, attr.name, part.name)
-              literal(base(part, part_row.merge(required: part_row.fetch(:required, true)), part.ts, true))
-            end
-            pairs = [["name", name.to_json], ["type", '"array"']]
-            pairs << ["labels", labels(row[:label])] if row[:label]
-            pairs << ["admin", "{ description: #{row[:description].to_json} }"] if row[:description]
-            pairs << ["fields", "[#{subs.join(', ')}]"]
-            literal(pairs)
-          end
-
-          def input(attr, row, rows)
-            return composite_input(attr, rows) if attr.shape == :composite
-
-            name = row[:field] || attr.ts
-            kind = kind_of(attr, row)
-            return list_input(name, kind) if attr.list
-
-            scalar_input(attr, row, name, kind)
-          end
-
-          def list_input(name, kind) = "valuesOf(doc.#{name}, #{kind == 'date' ? 'isoOrNull' : 'nonBlank'})"
-
-          def scalar_input(attr, row, name, kind)
-            case kind
-            when "upload", "relationship"
-              via = row[:via] || (kind == "upload" ? "url" : "slug")
-              "await related(req, #{row[:relation].to_json}, doc.#{name}, #{via.to_json})"
-            when "date", "day" then date_input(attr, name, kind)
-            when "number" then attr.optional ? "doc.#{name} == null ? null : Number(doc.#{name})" : "Number(doc.#{name})"
-            else attr.optional ? "nonBlank(doc.#{name})" : "String(doc.#{name})"
-            end
-          end
-
-          def date_input(attr, name, kind)
-            return "isoOrNull(doc.#{name})#{' ?? ""' unless attr.optional}" unless attr.shape == :integer || kind == "day"
-
-            stamp = "doc.#{name} ? new Date(doc.#{name} as string).getTime() : Date.now()"
-            "Math.floor((#{stamp}) / 1000)"
-          end
-
-          def composite_input(attr, rows)
-            parts = attr.parts.map { |part| "#{part.ts}: #{part_input(part, row_for(rows, attr.name, part.name))}" }.join(", ")
-            "(Array.isArray(doc.#{attr.ts}) ? doc.#{attr.ts} : []).map((raw) => { const s = raw as Doc; return { #{parts} }; })"
-          end
-
-          def part_input(part, row)
-            return "isoOrNull(s.#{part.ts}) ?? \"\"" if KINDS[row[:kind]] == "date"
-
-            "nonBlank(s.#{part.ts}) ?? \"\""
-          end
         end
       end
     end

data/lib/hecks/projections/site/payload/lifecycle/text.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        module Lifecycle
+          # The first half of the TypeScript module every driven project shares, up to the plan.
+          # `__ROLE__` and `__HECKS__` stand for the role and the host module's import path.
+          HEAD = <<~TS
+            // Driving one aggregate from a save: what every driven collection shares.
+            //
+            // An editor's save says what the document should look like and where it should
+            // be (live, withdrawn, cancelled). The domain answers with where the aggregate
+            // is now. This works out the commands between the two: create it if the domain
+            // has never seen it, Revise when its facts differ, then walk its lifecycle to
+            // the wanted status along the shortest path the bluebook allows.
+            //
+            // The pure parts (the plan) are separate from `drive`, the one function that
+            // talks to the domain, so the decisions test without a network.
+            import { domain, instancesOf, refusalOf, type Answer } from __HECKS__;
+
+            /** The role every driven command declares; the host compares the role as a plain string. */
+            const ROLE = __ROLE__;
+
+            export type Wire = Record<string, unknown>;
+
+            export interface Command<S> {
+              verb: string;
+              to?: string;
+              with: Wire;
+              /** True when the instances that came back show the command took effect. */
+              confirm: (after: S[]) => boolean;
+            }
+
+            export interface Instance {
+              slug: string;
+              status: string;
+            }
+
+            export interface Spec<S extends Instance, I extends { slug: string }> {
+              /** The aggregate as the host names it, chapter first: "Club::Event". */
+              aggregate: string;
+              /** Its instances in an answer, keyed by slug. */
+              read: (answer: Answer) => S[];
+              /** What the host holds, in the shape a save produces, so the two compare. */
+              toInput: (state: S) => Omit<I, "status">;
+              /** Every attribute but the slug, as `Revise` takes it. */
+              fields: (input: Omit<I, "status">) => Wire;
+              /** The command that creates one (it takes the slug and the fields) and the status it leaves it in. */
+              create: { verb: string; status: string };
+              /** The lifecycle: from a status, the commands that leave it and where they lead. */
+              edges: Record<string, Record<string, string>>;
+            }
+
+            /** A refusal-free plan: nothing is sent for a status the domain cannot reach from where it is. */
+            export class UnreachableStatus extends Error {}
+
+            export const wrapped = (value: string) => ({ value });
+            export const optionalValue = (name: string, value: string | null | undefined) => (value ? { [name]: wrapped(value) } : {});
+
+            /** The text inside a one-attribute value object (`{value}`, `{url}`, `{address}`), or null. */
+            export function unwrap(value: unknown): string | null {
+              if (typeof value === "string") return value || null;
+              if (value && typeof value === "object") {
+                for (const key of ["value", "url", "address"]) {
+                  const inner = (value as Record<string, unknown>)[key];
+                  if (typeof inner === "string" && inner) return inner;
+                }
+              }
+              return null;
+            }
+
+            export const unwrapList = (value: unknown): string[] =>
+              Array.isArray(value) ? value.map(unwrap).filter((item): item is string => !!item) : [];
+
+            export const statusOf = (state: Record<string, unknown>): string => (typeof state.status === "string" ? state.status : "");
+
+          TS
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/payload/lifecycle/text_tail.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        module Lifecycle
+          # The second half of the TypeScript module: the plan, and the function that drives it.
+          TAIL = <<~TS
+            /** The verbs, in order, that take an aggregate from one status to another; null when none does. */
+            export function pathBetween(edges: Record<string, Record<string, string>>, from: string, to: string): string[] | null {
+              if (from === to) return [];
+              const seen = new Set([from]);
+              let frontier: { status: string; verbs: string[] }[] = [{ status: from, verbs: [] }];
+              while (frontier.length) {
+                const next: typeof frontier = [];
+                for (const { status, verbs } of frontier) {
+                  for (const [verb, target] of Object.entries(edges[status] ?? {})) {
+                    if (seen.has(target)) continue;
+                    if (target === to) return [...verbs, verb];
+                    seen.add(target);
+                    next.push({ status: target, verbs: [...verbs, verb] });
+                  }
+                }
+                frontier = next;
+              }
+              return null;
+            }
+
+            const stateOf = <S extends Instance>(after: S[], slug: string) => after.find((s) => s.slug === slug);
+
+            /**
+             * The commands that make the domain's aggregate match `input` and sit in
+             * `desired`. `desired` null means "not on the site": a document the domain has
+             * never seen sends nothing; one it holds is walked to `withdrawn`.
+             */
+            export function planCommands<S extends Instance, I extends { slug: string }>(
+              spec: Spec<S, I>,
+              current: S | undefined,
+              input: Omit<I, "status">,
+              desired: string,
+            ): Command<S>[] {
+              const slug = input.slug;
+              const fields = spec.fields(input);
+              const commands: Command<S>[] = [];
+              let status = current?.status;
+
+              if (!current) {
+                if (spec.create.status !== desired && !pathBetween(spec.edges, spec.create.status, desired)) {
+                  throw new UnreachableStatus(`${spec.aggregate} cannot reach "${desired}" from "${spec.create.status}".`);
+                }
+                commands.push({
+                  verb: spec.create.verb,
+                  with: { slug: wrapped(slug), ...fields },
+                  confirm: (after) => stateOf(after, slug)?.status === spec.create.status,
+                });
+                status = spec.create.status;
+              } else if (JSON.stringify(spec.fields(spec.toInput(current))) !== JSON.stringify(fields)) {
+                commands.push({
+                  verb: "Revise",
+                  to: slug,
+                  with: fields,
+                  confirm: (after) => {
+                    const now = stateOf(after, slug);
+                    return !!now && JSON.stringify(spec.fields(spec.toInput(now))) === JSON.stringify(fields);
+                  },
+                });
+              }
+
+              const path = pathBetween(spec.edges, status ?? "", desired);
+              if (path === null) throw new UnreachableStatus(`${spec.aggregate} "${slug}" cannot go from "${status}" to "${desired}".`);
+              let at = status ?? "";
+              for (const verb of path) {
+                const to = spec.edges[at][verb];
+                commands.push({ verb, to: slug, with: {}, confirm: (after) => stateOf(after, slug)?.status === to });
+                at = to;
+              }
+              return commands;
+            }
+
+            /** Runs the plan against the domain; a command whose result does not show it took effect throws the domain's own words. */
+            export async function drive<S extends Instance, I extends { slug: string }>(
+              spec: Spec<S, I>,
+              input: Omit<I, "status">,
+              desired: string | null,
+              /** The status that means "off the site", used when `desired` is null and the domain holds the aggregate. */
+              offSite: string,
+            ): Promise<void> {
+              const current = spec.read(await domain().read()).find((s) => s.slug === input.slug);
+              // Not on the site and never was (a draft): the domain hears nothing about it.
+              if (desired === null && !current) return;
+              for (const command of planCommands(spec, current, input, desired ?? offSite)) {
+                const verb = `${spec.aggregate.split("::")[1]}.${command.verb}`;
+                const answer = await domain().dispatch(verb, command.with, command.to, ROLE);
+                if (!command.confirm(spec.read(answer))) throw refusalOf(answer, verb);
+              }
+            }
+
+            /** Reads an aggregate's instances, slug first, from an answer. */
+            export const instancesBySlug = (answer: Answer, aggregate: string) => instancesOf(answer, aggregate);
+          TS
+        end
+      end
+    end
+  end
+end