@reventlessdev/reventless-spec 3.0.0-alpha.61

package/src/components/DcbValidation.res.mjs

@@ -0,0 +1,360 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as DcbTag$Reventless from "./DcbTag.res.mjs";
+
+function extractVariantInfo(variantSchema) {
+  if (variantSchema.type !== "object") {
+    return;
+  }
+  let properties = variantSchema.properties;
+  let tagName = Stdlib_Option.flatMap(variantSchema.items.find(item => item.location === "TAG"), item => {
+    let match = item.schema;
+    if (match.type !== "string") {
+      return;
+    }
+    let $$const = match.const;
+    if ($$const !== undefined) {
+      return $$const;
+    }
+  });
+  return Stdlib_Option.map(tagName, tagName => {
+    let taggedFields = Stdlib_Array.filterMap(Object.entries(properties), param => {
+      if (DcbTag$Reventless.isTagged(param[1])) {
+        return param[0];
+      }
+    });
+    return {
+      tagName: tagName,
+      fields: properties,
+      taggedFields: taggedFields
+    };
+  });
+}
+
+function extractAllVariants(schema) {
+  switch (schema.type) {
+    case "string" :
+      let name = schema.const;
+      if (name !== undefined) {
+        return [{
+            tagName: name,
+            fields: {},
+            taggedFields: []
+          }];
+      } else {
+        return [];
+      }
+    case "object" :
+      let info = extractVariantInfo(schema);
+      if (info !== undefined) {
+        return [info];
+      } else {
+        return [];
+      }
+    case "union" :
+      return Stdlib_Array.filterMap(schema.anyOf, extractVariantInfo);
+    default:
+      return [];
+  }
+}
+
+function isPayloadLess(info) {
+  return Object.entries(info.fields).length === 0;
+}
+
+function schemasAreCompatible(_a, _b) {
+  while (true) {
+    let b = _b;
+    let a = _a;
+    switch (a.type) {
+      case "string" :
+        return b.type === "string";
+      case "number" :
+        return b.type === "number";
+      case "bigint" :
+        return b.type === "bigint";
+      case "boolean" :
+        return b.type === "boolean";
+      case "array" :
+        let aItem = a.additionalItems;
+        if (aItem === "strip" || aItem === "strict") {
+          return false;
+        }
+        if (b.type !== "array") {
+          return false;
+        }
+        let bItem = b.additionalItems;
+        if (bItem === "strip" || bItem === "strict") {
+          return false;
+        }
+        _b = bItem;
+        _a = aItem;
+        continue;
+      case "object" :
+        return b.type === "object";
+      case "union" :
+        return b.type === "union";
+      default:
+        return false;
+    }
+  };
+}
+
+function schemaTypeName(schema) {
+  switch (schema.type) {
+    case "never" :
+      return "never";
+    case "string" :
+      return "string";
+    case "number" :
+      return "float";
+    case "bigint" :
+      return "bigint";
+    case "boolean" :
+      return "bool";
+    case "array" :
+      return "array";
+    case "object" :
+      return "object";
+    case "union" :
+      return "union";
+    case "ref" :
+      return "ref";
+    default:
+      return "unknown";
+  }
+}
+
+function dedupeKeys(keys) {
+  let seen = new Set();
+  return keys.filter(k => {
+    if (seen.has(k)) {
+      return false;
+    } else {
+      seen.add(k);
+      return true;
+    }
+  });
+}
+
+function validateCompositeReads(slices, producedTagKeys) {
+  let warnings = [];
+  slices.forEach(param => {
+    let commandSchema = param[1];
+    let sliceName = param[0];
+    if (DcbTag$Reventless.hasTaggedArrayFields(commandSchema)) {
+      return;
+    }
+    let commandTagKeysByVariant = DcbTag$Reventless.extractTagKeysByEventType(commandSchema);
+    let consumedTypes = DcbTag$Reventless.extractVariantNames(param[2]);
+    Object.values(commandTagKeysByVariant).forEach(cmdKeys => {
+      let querySet = dedupeKeys(cmdKeys);
+      if (querySet.length >= 2) {
+        consumedTypes.forEach(consumedType => {
+          let producedKeys = producedTagKeys[consumedType];
+          if (producedKeys === undefined) {
+            return;
+          }
+          let producedSet = dedupeKeys(producedKeys);
+          let isSuperset = querySet.every(k => producedSet.includes(k));
+          if (!(isSuperset && producedSet.length > querySet.length)) {
+            return;
+          }
+          let extra = producedSet.filter(k => !querySet.includes(k));
+          warnings.push({
+            sliceName: sliceName,
+            message: `composite read on tags [` + querySet.join(", ") + `] will silently miss '` + consumedType + `', which also carries [` + extra.join(", ") + `] — the tag_composite key includes ALL of an event's tags, so a composite query matches only events tagged exactly [` + querySet.join(", ") + `]. Align the event's tag set with the query, or read '` + consumedType + `' via a single-tag clause.`
+          });
+        });
+        return;
+      }
+    });
+  });
+  return warnings;
+}
+
+function validateProducedAndConsumed(produced, consumed) {
+  let errors = [];
+  let producerMap = {};
+  produced.forEach(param => {
+    let sliceName = param[0];
+    let variants = extractAllVariants(param[1]);
+    variants.forEach(variant => {
+      let existing = Stdlib_Option.getOr(producerMap[variant.tagName], []);
+      producerMap[variant.tagName] = existing.concat([{
+          sliceName: sliceName,
+          variant: variant
+        }]);
+    });
+  });
+  Object.entries(producerMap).forEach(param => {
+    let entries = param[1];
+    if (entries.length <= 1) {
+      return;
+    }
+    let tagName = param[0];
+    let first = entries[0];
+    let firstFields = Object.keys(first.variant.fields).toSorted(Primitive_string.compare);
+    let firstTagged = first.variant.taggedFields.toSorted(Primitive_string.compare);
+    entries.forEach((entry, idx) => {
+      if (idx <= 0) {
+        return;
+      }
+      let entryFields = Object.keys(entry.variant.fields).toSorted(Primitive_string.compare);
+      let entryTagged = entry.variant.taggedFields.toSorted(Primitive_string.compare);
+      if (firstFields.length !== entryFields.length || firstFields.some(f => !entryFields.includes(f))) {
+        let missingInEntry = firstFields.filter(f => !entryFields.includes(f));
+        let extraInEntry = entryFields.filter(f => !firstFields.includes(f));
+        let parts = [];
+        if (missingInEntry.length !== 0) {
+          parts.push(`'` + first.sliceName + `' has fields [` + missingInEntry.join(", ") + `] which '` + entry.sliceName + `' is missing`);
+        }
+        if (extraInEntry.length !== 0) {
+          parts.push(`'` + entry.sliceName + `' has fields [` + extraInEntry.join(", ") + `] which '` + first.sliceName + `' is missing`);
+        }
+        errors.push({
+          sliceName: entry.sliceName,
+          message: `Producers '` + first.sliceName + `' and '` + entry.sliceName + `' both produce '` + tagName + `' but with different fields: ` + parts.join("; ")
+        });
+      } else {
+        firstFields.forEach(fieldName => {
+          let firstSchema = first.variant.fields[fieldName];
+          let entrySchema = entry.variant.fields[fieldName];
+          if (!schemasAreCompatible(firstSchema, entrySchema)) {
+            errors.push({
+              sliceName: entry.sliceName,
+              message: `Producers '` + first.sliceName + `' and '` + entry.sliceName + `' both produce '` + tagName + `' but field '` + fieldName + `' has type '` + schemaTypeName(firstSchema) + `' in '` + first.sliceName + `' and '` + schemaTypeName(entrySchema) + `' in '` + entry.sliceName + `'`
+            });
+            return;
+          }
+        });
+      }
+      if (!(firstTagged.length !== entryTagged.length || firstTagged.some(f => !entryTagged.includes(f)))) {
+        return;
+      }
+      let untaggedInEntry = firstTagged.filter(f => !entryTagged.includes(f));
+      let untaggedInFirst = entryTagged.filter(f => !firstTagged.includes(f));
+      let parts$1 = [];
+      if (untaggedInEntry.length !== 0) {
+        parts$1.push(`[` + untaggedInEntry.join(", ") + `] tagged in '` + first.sliceName + `' but not in '` + entry.sliceName + `'`);
+      }
+      if (untaggedInFirst.length !== 0) {
+        parts$1.push(`[` + untaggedInFirst.join(", ") + `] tagged in '` + entry.sliceName + `' but not in '` + first.sliceName + `'`);
+      }
+      errors.push({
+        sliceName: entry.sliceName,
+        message: `Producers '` + first.sliceName + `' and '` + entry.sliceName + `' both produce '` + tagName + `' but tag annotations differ: ` + parts$1.join("; ")
+      });
+    });
+  });
+  consumed.forEach(param => {
+    let sliceName = param[0];
+    let variants = extractAllVariants(param[1]);
+    variants.forEach(variant => {
+      let producers = producerMap[variant.tagName];
+      if (producers !== undefined) {
+        let producer = producers[0];
+        if (!isPayloadLess(variant)) {
+          Object.entries(variant.fields).forEach(param => {
+            let consumedFieldSchema = param[1];
+            let fieldName = param[0];
+            let producedFieldSchema = producer.variant.fields[fieldName];
+            if (producedFieldSchema !== undefined) {
+              if (!schemasAreCompatible(consumedFieldSchema, producedFieldSchema)) {
+                errors.push({
+                  sliceName: sliceName,
+                  message: `Slice '` + sliceName + `' consumes '` + variant.tagName + `.` + fieldName + `' as ` + schemaTypeName(consumedFieldSchema) + ` but producer declares it as ` + schemaTypeName(producedFieldSchema)
+                });
+                return;
+              } else {
+                return;
+              }
+            } else {
+              errors.push({
+                sliceName: sliceName,
+                message: `Slice '` + sliceName + `' consumes '` + variant.tagName + `.` + fieldName + `' (` + schemaTypeName(consumedFieldSchema) + `) but produced '` + variant.tagName + `' has no field '` + fieldName + `'`
+              });
+              return;
+            }
+          });
+          return;
+        } else {
+          return;
+        }
+      }
+      errors.push({
+        sliceName: sliceName,
+        message: `Slice '` + sliceName + `' consumes '` + variant.tagName + `' but no slice produces it`
+      });
+    });
+  });
+  if (errors.length !== 0) {
+    return {
+      TAG: "Error",
+      _0: errors
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: undefined
+    };
+  }
+}
+
+function validateCrossPartitionScope(producers) {
+  let perProducer = producers.map(param => {
+    let schema = param[1];
+    let cpSet = new Set();
+    DcbTag$Reventless.extractCrossPartitionTagKeys(schema).forEach(k => {
+      cpSet.add(k);
+    });
+    let carried = new Set();
+    Object.values(DcbTag$Reventless.extractTagKeysByEventType(schema)).forEach(ks => {
+      ks.forEach(k => {
+        carried.add(k);
+      });
+    });
+    return [
+      param[0],
+      cpSet,
+      carried
+    ];
+  });
+  let globalCp = new Set();
+  perProducer.forEach(param => {
+    Array.from(param[1].values()).forEach(k => {
+      globalCp.add(k);
+    });
+  });
+  let warnings = [];
+  perProducer.forEach(param => {
+    let cpSet = param[1];
+    let name = param[0];
+    Array.from(param[2].values()).toSorted(Primitive_string.compare).forEach(k => {
+      if (globalCp.has(k) && !cpSet.has(k)) {
+        warnings.push({
+          sliceName: name,
+          message: `tag '` + k + `' is declared @crossPartition by another producer but is partition-scoped here — DCB tag scope must agree across every event type that carries the tag (read-scope and fence-scope follow one global per-key flag). Add @crossPartition to '` + k + `' here, or remove it from the other producer.`
+        });
+        return;
+      }
+    });
+  });
+  return warnings;
+}
+
+export {
+  extractVariantInfo,
+  extractAllVariants,
+  isPayloadLess,
+  schemasAreCompatible,
+  schemaTypeName,
+  dedupeKeys,
+  validateCompositeReads,
+  validateProducedAndConsumed,
+  validateCrossPartitionScope,
+}
+/* DcbTag-Reventless Not a pure module */

package/src/components/DisplayName.res

@@ -0,0 +1,40 @@
+/**
+Spec for a composite display-name derivation.
+
+`fields` names the source fields in declaration order; `separator` is inserted
+between successive non-empty parts when `computeLabel` is applied.
+
+The ppx attaches this spec to a state schema whenever one or more fields carry
+the `@displayName` attribute. The projection runtime reads the spec at write
+time and composes the label into a synthetic `displayName` field on state.
+*/
+type displayNameSpec = {
+  fields: array<string>,
+  separator: string,
+}
+
+/** Sury metadata ID used to attach a `displayNameSpec` to a state schema. */
+let displayNameId: S.Metadata.Id.t<displayNameSpec> =
+  S.Metadata.Id.make(~namespace="reventless", ~name="displayName")
+
+/** Returns the spec attached to a state schema, if any. */
+let getSpec = (schema: S.t<unknown>): option<displayNameSpec> =>
+  S.Metadata.get(schema, ~id=displayNameId)
+
+/**
+Composes a display-name label from a state dict and a spec.
+
+Reads each source field by name from the dict. Entries that are absent,
+`null`, or empty strings are skipped. Remaining string values are joined
+with `spec.separator`. The result never has a leading, trailing, or
+doubled separator.
+*/
+let computeLabel = (spec: displayNameSpec, state: dict<JSON.t>): string =>
+  spec.fields
+  ->Array.filterMap(fieldName =>
+    switch state->Dict.get(fieldName) {
+    | Some(JSON.String(s)) if s != "" => Some(s)
+    | _ => None
+    }
+  )
+  ->Array.join(spec.separator)

package/src/components/DisplayName.res.mjs

@@ -0,0 +1,26 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+
+let displayNameId = S.Metadata.Id.make("reventless", "displayName");
+
+function getSpec(schema) {
+  return S.Metadata.get(schema, displayNameId);
+}
+
+function computeLabel(spec, state) {
+  return Stdlib_Array.filterMap(spec.fields, fieldName => {
+    let match = state[fieldName];
+    if (typeof match === "string" && match !== "") {
+      return match;
+    }
+  }).join(spec.separator);
+}
+
+export {
+  displayNameId,
+  getSpec,
+  computeLabel,
+}
+/* displayNameId Not a pure module */

package/src/components/ExtensionPoint.res

@@ -0,0 +1,27 @@
+/**
+Module type for an extension point's identity and schema specification.
+
+An extension point is a bidirectional protocol boundary: it exposes a
+command topic for extensions to publish to, and an event topic that
+extensions subscribe to. The `directive` type is used for internal
+routing signals that are not exposed as public events.
+
+Note: `module Id = Id.String` is fixed — extension points always use string IDs.
+*/
+module type Spec = {
+  module Id = Id.String
+
+  /** Logical extension point name (used as a topic name prefix). */
+  let name: string
+
+  /** Commands that extensions can send to this extension point. Must carry `@schema`. */
+  @schema
+  type command
+  /** Events that this extension point emits to subscribed extensions. Must carry `@schema`. */
+  @schema
+  type event
+  /** Internal routing directives (not exposed externally). Must carry `@schema`. */
+  @schema
+  type directive
+}
+

package/src/components/ExtensionPoint.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

package/src/components/InboundTranslationSlice.res

@@ -0,0 +1,79 @@
+/**
+Module types for a DCB inbound translation slice.
+
+An `InboundTranslationSlice` receives external input (webhooks, API calls) and
+translates it into domain commands via an anti-corruption layer.
+
+Unlike outbound slices, inbound slices are triggered externally via
+`operations.receive` rather than by subscribing to domain events.
+
+```
+External Input -> Anti-Corruption Layer (translate) -> Command
+```
+
+Plan 02 splits the merged spec into two module types:
+
+- `Spec` — types, identity, schemas, target name. (No state — translation is
+  a pure function of external input.)
+- `Translation` — the single `translate` function.
+
+@example
+```rescript
+// PaymentWebhook.res
+let name = "PaymentWebhook"
+
+@schema type externalInput = {paymentId: string, orderId: string, status: string}
+@schema type command = ConfirmPayment({orderId: @s.matches(DcbTag.string) string, paymentId: string})
+
+let translate = input => switch input.status {
+  | "completed" => Ok([(input.orderId, ConfirmPayment({orderId: input.orderId, paymentId: input.paymentId}))])
+  | _ => Error("Unknown payment status: " ++ input.status)
+}
+```
+*/
+
+/**
+The lean Spec for an InboundTranslationSlice — types, identity, schemas.
+*/
+module type Spec = {
+  /** Logical name of this inbound translation slice (used as a component prefix). */
+  let name: string
+  let moduleUrl: string
+
+  /** The external input type received from the outside world. Must carry `@schema`. */
+  @schema
+  type externalInput
+
+  /** The command type produced by the anti-corruption layer. Must carry `@schema`. */
+  @schema
+  type command
+
+  /** Name of the aggregate or StateChangeSlice that receives the produced command. */
+  let targetName: string
+
+  /** Authorization rule evaluated at the GraphQL resolver entry before any
+      external input is translated. Auto-injected by `@@reventless.spec` and
+      on structurally-detected inline spec modules — defaults to
+      `AllowAuthenticated`. */
+  let commandAuthorization: command => Authorization.permission
+}
+
+/**
+The Translation — the synchronous translate function.
+*/
+module type Translation = {
+  module Spec: Spec
+
+  /**
+  Translate: convert external input into domain commands.
+  Returns:
+  - `Ok([(targetId, cmd), ...])` to publish one or more commands
+  - `Ok([])` for idempotent no-ops (nothing to publish)
+  - `Error(msg)` to reject the input
+  */
+  let translate: Spec.externalInput => result<array<(string, Spec.command)>, string>
+
+  /** File URL of this Translation module (`import.meta.url`). */
+  let moduleUrl: string
+}
+

package/src/components/InboundTranslationSlice.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

package/src/components/OutboundTranslationSlice.res

@@ -0,0 +1,108 @@
+/**
+Module types for a DCB outbound translation slice.
+
+An `OutboundTranslationSlice` listens to the shared `DcbEventLog` event topic,
+collects outbound items (TODO list), and calls an external service for each one.
+The translate function may optionally return a command to publish back into the
+system, closing the loop.
+
+Replaces fire-and-forget `SideEffectHandler` with tracked, retryable external calls.
+
+```
+Event(s) -> TODO List (read model) -> Translator -> External Service
+                                                  -> Command (optional)
+```
+
+Plan 02 splits the merged spec into two module types:
+
+- `Spec` — types, identity, schemas, sweep config. Per D2, `outboundItem`
+  lives here (persisted TODO state with schema).
+- `Translation` — `collect` (sync, observable in tests) and `translate`
+  (async, mocked in tests via `whenTranslateMocked`).
+
+@example
+```rescript
+// SendTrackingEmail.res
+let name = "SendTrackingEmail"
+
+@schema type outboundItem = {orderId: string, email: string}
+@schema type inboundCommand = unit
+
+let collect = event => switch event {
+  | OrderShipped({orderId, email}) => [(orderId, {orderId, email})]
+  | _ => []
+}
+
+let translate = async (_id, item) => {
+  await EmailService.send(item.email, ~orderId=item.orderId)
+  Ok(None) // fire-and-forget: no command back
+}
+
+let maxRetries = 3
+let heartbeatInterval = 60
+```
+*/
+
+/**
+The lean Spec for an OutboundTranslationSlice — types, identity, schemas, sweep config.
+*/
+module type Spec = {
+  /** Logical name of this outbound translation slice (used as a component prefix). */
+  let name: string
+  let moduleUrl: string
+
+  /**
+  Events this outbound translation slice consumes for collect.
+  Only needs the fields required — no tag annotations needed.
+  Must carry `@schema`.
+  */
+  @schema
+  type consumedEvent
+
+  /** The outbound item state — what data is accumulated for each pending external call. Must carry `@schema`. */
+  @schema
+  type outboundItem
+
+  /** The command type optionally produced after a successful translate call. Must carry `@schema`. */
+  @schema
+  type inboundCommand
+
+  /** Maximum number of retries for a failed translate attempt. */
+  let maxRetries: int
+
+  /** Heartbeat interval in seconds for sweeping pending/failed items. */
+  let heartbeatInterval: int
+
+  /** Name of the aggregate or StateChangeSlice that receives the inbound command, or None for fire-and-forget. */
+  let targetName: option<string>
+}
+
+/**
+The Translation — `collect` and async `translate`. Both functions are
+distinguished from the Inbound shape (which has only a sync `translate`).
+*/
+module type Translation = {
+  module Spec: Spec
+
+  /**
+  Collect: map an incoming event to zero or more new outbound items.
+  Each item has an `id` (deduplication key) and the `outboundItem` payload.
+  Returns empty array if this event is not relevant.
+  */
+  let collect: Spec.consumedEvent => array<(string, Spec.outboundItem)>
+
+  /**
+  Translate: call the external service for a single outbound item.
+  Returns:
+  - `Ok(Some((targetId, cmd)))` to publish a command back into the system
+  - `Ok(None)` for fire-and-forget (no command back)
+  - `Error(msg)` on failure (item will be retried up to maxRetries)
+  */
+  let translate: (string, Spec.outboundItem) => promise<
+    result<option<(string, Spec.inboundCommand)>, string>,
+  >
+
+  /** File URL of this Translation module (`import.meta.url`). */
+  let moduleUrl: string
+}
+

package/src/components/OutboundTranslationSlice.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */