hecks 3.4.2 → 3.6.0

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "fields/definitions"
+require_relative "fields/readers"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        # The TypeScript that ties a Payload collection to an aggregate: the collection's field
+        # definitions, one per attribute, and the function that reads a saved document back into the
+        # aggregate's input.
+        #
+        # Both come from the attribute's shape and, where the editor needs something the shape
+        # cannot
+        # say (a date picker, a choice list, an upload, a relation), from a `PayloadField` row.
+        # They are
+        # produced together so a field and the code that reads it cannot disagree.
+        module Fields
+          BANNER = "// Generated by hecks site site_projection.project_site. Do not edit."
+
+          # The kinds a row may name, with the Payload field type each is.
+          KINDS = { "text" => "text", "textarea" => "textarea", "select" => "select", "date" => "date", "day" => "date",
+                    "number" => "number", "upload" => "upload", "relationship" => "relationship" }.freeze
+
+          module_function
+
+          # @param aggregates [Array<Model::Aggregate>] the aggregates to drive
+          # @param rows [Array<Hash{Symbol => Object}>] the checked `PayloadField` rows
+          # @param specs [String] the import path of the generated specs module
+          # @param helpers [String] the import path of the module that holds `nonBlank` and its kin
+          # @return [String] the module
+          # @raise [ArgumentError] when a row names an aggregate or an attribute the domain lacks
+          def render(aggregates, rows:, specs:, helpers:)
+            check(aggregates, rows)
+            body = aggregates.map { |agg| aggregate(agg, rows.select { |row| row[:aggregate] == agg.noun }) }
+            [BANNER, header(aggregates, specs, helpers), shared, *body].join("\n\n") << "\n"
+          end
+
+          def check(aggregates, rows)
+            rows.each do |row|
+              agg = aggregates.find { |candidate| candidate.noun == row[:aggregate] }
+              raise ArgumentError, "PayloadField names #{row[:aggregate]}, which it does not drive" unless agg
+
+              check_attribute(agg, row)
+              check_kind(row)
+            end
+          end
+
+          def check_attribute(agg, row)
+            top, part = row[:attribute].split(".", 2)
+            attr = agg.attrs.find { |candidate| candidate.name == top }
+            where = "PayloadField #{row[:aggregate]}.#{row[:attribute]}"
+            raise ArgumentError, "#{where} is not an attribute" unless attr
+            raise ArgumentError, "#{where} is not a part" if part && !attr.parts&.any? { |each| each.name == part }
+          end
+
+          def check_kind(row)
+            kind = row[:kind]
+            if kind && !KINDS.key?(kind)
+              raise ArgumentError,
+                    "PayloadField kind #{kind.inspect} is one of #{KINDS.keys.join(", ")}"
+            end
+            return unless %w[upload relationship].include?(kind) && !row[:relation]
+
+            raise ArgumentError, "PayloadField #{row[:attribute]} is #{kind} and needs a relation"
+          end
+
+          def header(aggregates, specs, helpers)
+            types = aggregates.map { |agg| "type #{agg.noun}Input" }.join(", ")
+            <<~TS.chomp
+              import type { Field, PayloadRequest } from "payload";
+
+              import { isoOrNull, nonBlank, related, type Doc } from #{helpers.to_json};
+              import { #{types} } from #{specs.to_json};
+            TS
+          end
+
+          def shared
+            <<~TS.chomp
+              const valuesOf = (value: unknown, pick: (raw: unknown) => string | null): string[] =>
+                (Array.isArray(value) ? value : []).map((row) => pick((row as Doc)?.value)).filter((item): item is string => !!item);
+            TS
+          end
+
+          def aggregate(agg, rows)
+            var = "#{agg.noun[0].downcase}#{agg.noun[1..]}"
+            <<~TS.chomp
+              // ---- #{agg.noun} ----
+
+              export const #{var}Fields = {
+              #{fields_block(agg, rows)}
+              } satisfies Record<string, Field>;
+
+              export const #{var}FromDoc = async (req: PayloadRequest, doc: Doc): Promise<#{agg.noun}Input> => ({
+              #{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 } || {}
+          end
+
+          def fields_of(agg, rows)
+            agg.attrs.map do |attr|
+              row = row_for(rows, attr.name)
+              [field_name(attr, row), field(agg, attr, row, rows)]
+            end
+          end
+
+          def field_name(attr, row) = row[:field] || attr.ts
+
+          def field(_agg, attr, row, rows)
+            name = field_name(attr, row)
+            return Definitions.composite(attr, row, name, rows) if attr.shape == :composite
+            return Definitions.array(attr, row, name) if attr.list
+
+            Definitions.literal(Definitions.base(attr, row, name, !attr.optional))
+          end
+
+          def kind_of(attr, row)
+            row[:kind] || (attr.shape == :integer ? "number" : "text")
+          end
+        end
+      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

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "lifecycle/text"
+require_relative "lifecycle/text_tail"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        # The module that turns a spec and a saved document into the commands between the host's
+        # state and the wanted one. It is the same for every project but for the role its commands
+        # declare and the path of the module that talks to the host.
+        module Lifecycle
+          BANNER = "// Generated by hecks site site_projection.project_site. Do not edit."
+
+          # The whole module, with `__ROLE__` and `__HECKS__` standing for the role and the path of
+          # the module that talks to the host.
+          TEXT = (HEAD + TAIL).freeze
+
+          module_function
+
+          # @param role [String, nil] the role every driven command declares
+          # @param hecks [String] the import path of the module that talks to the host
+          # @return [String] the module
+          def render(role:, hecks:)
+            [BANNER, TEXT.sub("__ROLE__", role.to_json).sub("__HECKS__", hecks.to_json)].join("\n\n")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        # What the generators read from a domain chapter about one aggregate the content system
+        # drives: its attributes with the shape each takes over the wire, the command that creates
+        # it, the lifecycle edges, and the role its commands declare.
+        #
+        # The model is pure data. It refuses an aggregate it cannot drive, naming why, so a project
+        # learns at generation time rather than from a runtime refusal.
+        class Model
+          # One attribute: `name` is the domain's (snake case), `ts` the camel case the content
+          # system uses, `shape` one of :value, :url, :address, :integer or :composite, and `parts`
+          # the attributes of a composite value object.
+          Attr = Struct.new(:name, :ts, :shape, :wire_key, :optional, :list, :type, :parts, keyword_init: true)
+
+          # One aggregate: `noun` ("Event"), `fqn` ("Club::Event"), `create` ({verb:, status:}),
+          # `edges` (status => { verb => status }) and `attrs` (the identity first).
+          Aggregate = Struct.new(:noun, :fqn, :create, :edges, :attrs, :identity, :role, keyword_init: true)
+
+          # The single attribute names a one-attribute value object may carry, with the shape
+          # each is.
+          SINGLE = { "value" => :value, "url" => :url, "address" => :address }.freeze
+
+          # @param chapter [Bluebook::Chapter] the domain chapter
+          # @param skip [Array<String>] aggregates to leave out
+          # @return [Array<Aggregate>] each aggregate with a lifecycle and a creating command
+          # @raise [ArgumentError] when such an aggregate cannot be driven
+          def self.read(chapter, skip: [])
+            chapter.aggregates.select { |agg| agg.lifecycle && !skip.include?(agg.hecks_name) }
+                   .map { |agg| new(chapter, agg).aggregate }
+          end
+
+          # @return [Aggregate] the aggregate's model
+          attr_reader :aggregate
+
+          def initialize(chapter, agg)
+            @chapter = chapter
+            @agg = agg
+            @aggregate = Aggregate.new(noun: agg.hecks_name, fqn: "#{chapter.name}::#{agg.hecks_name}", create: create,
+                                       edges: edges, attrs: attrs, identity: agg.identified_by.to_s, role: role)
+          end
+
+          private
+
+          def create
+            command = @agg.commands.find(&:creates?)
+            raise ArgumentError, "#{@agg.hecks_name} has no command that creates it" unless command
+            raise ArgumentError, "#{@agg.hecks_name}'s lifecycle has no default status" unless @agg.lifecycle.default
+
+            { verb: command.hecks_name, status: @agg.lifecycle.default }
+          end
+
+          def edges
+            creating = @agg.commands.select(&:creates?).map(&:hecks_name)
+            map = Hash.new { |hash, key| hash[key] = {} }
+            @agg.lifecycle.transitions.each { |verb, move| add_edges(map, verb, move) unless creating.include?(verb) }
+            map.transform_values(&:dup)
+          end
+
+          # Records the edge from each of the move's states, and makes sure its target has a key.
+          def add_edges(map, verb, move)
+            Array(move.from).each { |from| map[from][verb] = move.target }
+            map[move.target]
+          end
+
+          def role
+            roles = @agg.commands.filter_map { |command| command.role if command.respond_to?(:role) }.uniq
+            if roles.size > 1
+              raise ArgumentError,
+                    "#{@agg.hecks_name}'s commands declare #{roles.size} roles; the driver acts as one"
+            end
+
+            roles.first
+          end
+
+          def attrs
+            @agg.attributes.reject { |attribute| attribute.name == @agg.lifecycle.field }.map { |attribute| attr(attribute) }
+          end
+
+          def attr(attribute)
+            object = value_object(attribute.type)
+            unless object
+              raise ArgumentError,
+                    "#{@agg.hecks_name}.#{attribute.name} is a #{attribute.type}; the driver needs a value object"
+            end
+
+            members = object.attributes
+            shape, key, parts = shape_of(attribute, members)
+            Attr.new(name: attribute.name.to_s, ts: camel(attribute.name), shape: shape, wire_key: key,
+                     optional: attribute.optional?, list: attribute.list?, type: attribute.type, parts: parts)
+          end
+
+          def shape_of(attribute, members)
+            return single_shape(members.first) if members.size == 1 && SINGLE.key?(members.first.name.to_s)
+            return [:composite, nil, members.map { |member| part(member) }] if attribute.list? && members.size > 1
+
+            raise ArgumentError, "#{@agg.hecks_name}.#{attribute.name} is #{attribute.type}, which the driver cannot carry"
+          end
+
+          def single_shape(member)
+            key = member.name.to_s
+            [member.type.to_s == "Integer" ? :integer : SINGLE.fetch(key), key, nil]
+          end
+
+          def part(member)
+            unless member.type.to_s == "String"
+              raise ArgumentError, "#{@agg.hecks_name}'s #{member.name} is a #{member.type}; a composite carries text only"
+            end
+
+            Attr.new(name: member.name.to_s, ts: camel(member.name), shape: :value, type: member.type.to_s, optional: false)
+          end
+
+          def value_object(type)
+            @agg.value_objects.find { |object| object.hecks_name == type.to_s }
+          end
+
+          def camel(name)
+            first, *rest = name.to_s.split("_")
+            first + rest.map(&:capitalize).join
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/payload/specs/wire.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  module Projections
+    module Site
+      module Payload
+        module Specs
+          # The TypeScript for how an aggregate's attributes cross the wire: the lines that read
+          # each one from the host's state, and the lines that write each one from an input.
+          module Wire
+            module_function
+
+            def others(agg) = agg.attrs.reject { |attr| attr.name == agg.identity }
+
+            def reads(agg)
+              others(agg).map { |attr| "      #{attr.ts}: #{read(agg, attr)}," }.join("\n")
+            end
+
+            def read(agg, attr)
+              return "#{Specs.reader(agg, attr)}(s.#{attr.name})" if attr.shape == :composite
+              return "unwrapList(s.#{attr.name})" if attr.list
+              return "whole(s.#{attr.name}, #{attr.wire_key.to_json})" if attr.shape == :integer
+
+              attr.optional ? "orNull(s.#{attr.name})" : "orNull(s.#{attr.name}) ?? \"\""
+            end
+
+            def writes(agg)
+              others(agg).map { |attr| "    #{write(attr)}," }.join("\n")
+            end
+
+            def write(attr)
+              name = attr.name
+              case attr.shape
+              when :composite then composite_write(attr)
+              when :integer then optional_write(attr, "{ #{attr.wire_key}: input.#{attr.ts} }", "input.#{attr.ts} != null")
+              else
+                return "#{name}: list(input.#{attr.ts})" if attr.list
+
+                scalar_write(attr)
+              end
+            end
+
+            def composite_write(attr)
+              parts = attr.parts.map { |part| "#{part.name}: item.#{part.ts}" }.join(", ")
+              "#{attr.name}: input.#{attr.ts}.map((item) => ({ #{parts} }))"
+            end
+
+            def scalar_write(attr)
+              if attr.wire_key == "value"
+                return "#{attr.name}: wrapped(input.#{attr.ts})" unless attr.optional
+
+                return "...optionalValue(#{attr.name.to_json}, input.#{attr.ts})"
+              end
+              optional_write(attr, "{ #{attr.wire_key}: input.#{attr.ts} }", "input.#{attr.ts}")
+            end
+
+            def optional_write(attr, wire, present)
+              return "#{attr.name}: #{wire}" unless attr.optional
+
+              "...(#{present} ? { #{attr.name}: #{wire} } : {})"
+            end
+          end
+        end
+      end
+    end
+  end
+end