@reventlessdev/reventless-spec 3.0.0-alpha.61

package/src/LogPrefix.res.mjs

@@ -0,0 +1,148 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
+import * as AnsiStyle$Reventless from "./AnsiStyle.res.mjs";
+
+let currentPluginName = {
+  contents: undefined
+};
+
+let componentPluginRegistry = {
+  contents: {}
+};
+
+function registerComponentPlugin(componentName, pluginName) {
+  componentPluginRegistry.contents[componentName] = pluginName;
+}
+
+function hashStr(s) {
+  let h = 0;
+  for (let i = 0, i_finish = s.length; i < i_finish; ++i) {
+    let code = Stdlib_Option.getOr(Stdlib_String.charCodeAt(s, i), 0);
+    h = h + (code * (i + 1 | 0) | 0) | 0;
+  }
+  return h;
+}
+
+let pluginColors = [
+  "\x1b[32m",
+  "\x1b[34m",
+  "\x1b[35m",
+  "\x1b[92m",
+  "\x1b[94m",
+  "\x1b[95m"
+];
+
+function pluginColor(name) {
+  return pluginColors[Primitive_int.mod_(hashStr(name), pluginColors.length)];
+}
+
+function extractInnerName(comp) {
+  let openIdx = comp.indexOf("(");
+  let closeIdx = comp.lastIndexOf(")");
+  if (openIdx > 0 && closeIdx > (openIdx + 1 | 0)) {
+    return comp.slice(openIdx + 1 | 0, closeIdx);
+  }
+}
+
+function stripAtVersion(s) {
+  let idx = s.indexOf("@");
+  if (idx > 0) {
+    return s.slice(0, idx);
+  }
+}
+
+function stripPluginSuffix(s) {
+  let suffix = "Plugin";
+  if (s.endsWith(suffix) && s.length > suffix.length) {
+    return s.slice(0, s.length - suffix.length | 0);
+  }
+}
+
+function firstDotSegment(s) {
+  let idx = s.indexOf(".");
+  if (idx > 0) {
+    return s.slice(0, idx);
+  }
+}
+
+function lastDotSegment(s) {
+  let idx = s.lastIndexOf(".");
+  if (idx > 0 && (idx + 1 | 0) < s.length) {
+    return s.slice(idx + 1 | 0, s.length);
+  }
+}
+
+function lookup(name) {
+  return componentPluginRegistry.contents[name];
+}
+
+function resolvePlugin(comp, param) {
+  if (comp === undefined) {
+    return currentPluginName.contents;
+  }
+  let inner = extractInnerName(comp);
+  if (inner === undefined) {
+    return currentPluginName.contents;
+  }
+  let p = componentPluginRegistry.contents[inner];
+  if (p !== undefined) {
+    return p;
+  }
+  let p$1 = currentPluginName.contents;
+  if (p$1 !== undefined) {
+    return p$1;
+  }
+  let candidates = [
+    stripAtVersion(inner),
+    stripPluginSuffix(inner),
+    lastDotSegment(inner),
+    firstDotSegment(inner)
+  ];
+  return Stdlib_Array.reduce(candidates, undefined, (acc, candidate) => {
+    if (acc !== undefined) {
+      return acc;
+    } else {
+      return Stdlib_Option.flatMap(candidate, lookup);
+    }
+  });
+}
+
+function fmtPlainPrefix(comp, param) {
+  let p = resolvePlugin(comp, undefined);
+  let plugin = p !== undefined ? `[` + p + `]` : "";
+  let c = comp !== undefined ? `[` + comp + `] ` : "";
+  return plugin + c;
+}
+
+function fmtComp(comp, param) {
+  if (!AnsiStyle$Reventless.useAnsi()) {
+    return fmtPlainPrefix(comp, undefined);
+  }
+  let p = resolvePlugin(comp, undefined);
+  let plugin = p !== undefined ? pluginColor(p) + AnsiStyle$Reventless.bold(`[` + p + `]`) : "";
+  let c = comp !== undefined ? AnsiStyle$Reventless.bold(`[` + comp + `]`) + ` ` : "";
+  return plugin + c;
+}
+
+export {
+  currentPluginName,
+  componentPluginRegistry,
+  registerComponentPlugin,
+  hashStr,
+  pluginColors,
+  pluginColor,
+  extractInnerName,
+  stripAtVersion,
+  stripPluginSuffix,
+  firstDotSegment,
+  lastDotSegment,
+  lookup,
+  resolvePlugin,
+  fmtPlainPrefix,
+  fmtComp,
+}
+/* AnsiStyle-Reventless Not a pure module */

package/src/PackageVersion.res

@@ -0,0 +1,73 @@
+@module("node:fs") external readFileSync: (string, string) => string = "readFileSync"
+@module("node:fs") external existsSync: string => bool = "existsSync"
+@module("node:url") external fileURLToPath: string => string = "fileURLToPath"
+@module("node:path") external dirname: string => string = "dirname"
+@module("node:path") external join: (string, string) => string = "join"
+
+let readVersion = (path: string) =>
+  readFileSync(path, "utf8")
+  ->JSON.parseOrThrow
+  ->JSON.Decode.object
+  ->Option.flatMap(o => o->Dict.get("version"))
+  ->Option.flatMap(JSON.Decode.string)
+  ->Option.getOr("0.0.0")
+
+let fromCwd = () => readVersion("./package.json")
+
+let findVersion = dir => {
+  let rec find = dir => {
+    let candidate = join(dir, "package.json")
+    if existsSync(candidate) {
+      readVersion(candidate)
+    } else {
+      let parent = dirname(dir)
+      if parent == dir {
+        "0.0.0"
+      } else {
+        find(parent)
+      }
+    }
+  }
+  find(dir)
+}
+
+let fromModuleUrl = (url: string) => findVersion(url->fileURLToPath->dirname)
+
+/** Detect the caller's file via V8 Structured Stack Trace API and read the
+    version from the nearest package.json. Skips frames from framework packages
+    (reventless-spec, reventless-core, reventless-infra, reventless-local,
+    reventless-aws, reventless-interop). Falls back to CWD's package.json. */
+let callerFile: unit => option<string> = %raw(`
+  function() {
+    var frameworkMarkers = [
+      '/reventless/reventless-',
+      '/@reventlessdev/reventless-',
+    ];
+    var oldPrepare = Error.prepareStackTrace;
+    Error.prepareStackTrace = function(_, stack) { return stack; };
+    var err = new Error();
+    var stack = err.stack;
+    Error.prepareStackTrace = oldPrepare;
+    for (var i = 0; i < stack.length; i++) {
+      var file = stack[i].getFileName();
+      if (!file) continue;
+      var isFramework = false;
+      for (var j = 0; j < frameworkMarkers.length; j++) {
+        if (file.indexOf(frameworkMarkers[j]) !== -1) { isFramework = true; break; }
+      }
+      if (!isFramework) return file;
+    }
+    return undefined;
+  }
+`)
+
+let fromCaller = () =>
+  switch callerFile() {
+  | Some(file) =>
+    if file->String.startsWith("file://") {
+      findVersion(file->fileURLToPath->dirname)
+    } else {
+      findVersion(file->dirname)
+    }
+  | None => fromCwd()
+  }

package/src/PackageVersion.res.mjs

@@ -0,0 +1,81 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Nodefs from "node:fs";
+import * as Nodeurl from "node:url";
+import * as Nodepath from "node:path";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function readVersion(path) {
+  return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(JSON.parse(Nodefs.readFileSync(path, "utf8"))), o => o["version"]), Stdlib_JSON.Decode.string), "0.0.0");
+}
+
+function fromCwd() {
+  return readVersion("./package.json");
+}
+
+function findVersion(dir) {
+  let _dir = dir;
+  while (true) {
+    let dir$1 = _dir;
+    let candidate = Nodepath.join(dir$1, "package.json");
+    if (Nodefs.existsSync(candidate)) {
+      return readVersion(candidate);
+    }
+    let parent = Nodepath.dirname(dir$1);
+    if (parent === dir$1) {
+      return "0.0.0";
+    }
+    _dir = parent;
+    continue;
+  };
+}
+
+function fromModuleUrl(url) {
+  return findVersion(Nodepath.dirname(Nodeurl.fileURLToPath(url)));
+}
+
+let callerFile = (function() {
+    var frameworkMarkers = [
+      '/reventless/reventless-',
+      '/@reventlessdev/reventless-',
+    ];
+    var oldPrepare = Error.prepareStackTrace;
+    Error.prepareStackTrace = function(_, stack) { return stack; };
+    var err = new Error();
+    var stack = err.stack;
+    Error.prepareStackTrace = oldPrepare;
+    for (var i = 0; i < stack.length; i++) {
+      var file = stack[i].getFileName();
+      if (!file) continue;
+      var isFramework = false;
+      for (var j = 0; j < frameworkMarkers.length; j++) {
+        if (file.indexOf(frameworkMarkers[j]) !== -1) { isFramework = true; break; }
+      }
+      if (!isFramework) return file;
+    }
+    return undefined;
+  });
+
+function fromCaller() {
+  let file = callerFile();
+  if (file !== undefined) {
+    if (file.startsWith("file://")) {
+      return findVersion(Nodepath.dirname(Nodeurl.fileURLToPath(file)));
+    } else {
+      return findVersion(Nodepath.dirname(file));
+    }
+  } else {
+    return readVersion("./package.json");
+  }
+}
+
+export {
+  readVersion,
+  fromCwd,
+  findVersion,
+  fromModuleUrl,
+  callerFile,
+  fromCaller,
+}
+/* node:fs Not a pure module */

package/src/components/Aggregate.res

@@ -0,0 +1,64 @@
+/**
+Module type for an aggregate's identity and schema specification.
+
+Every aggregate defines a `Spec` module satisfying this type. The `Spec` is
+used by `Platform.Aggregate.Make` and by `Behavior.T` to fix the aggregate's
+command, event, and error types.
+
+@example
+```rescript
+// Category.res
+module Id = Id.String
+let name = "Category"
+
+@schema
+type command =
+  | AddCategory({categoryId: string, name: string})
+  | RenameCategory({categoryId: string, name: string})
+  | ArchiveCategory({categoryId: string})
+
+@schema
+type event =
+  | CategoryAdded({categoryId: string, name: string})
+  | CategoryRenamed({categoryId: string, name: string})
+  | CategoryArchived({categoryId: string})
+
+@schema
+type error =
+  | CategoryAlreadyExists
+  | CategoryNotFound
+  | CategoryAlreadyArchived
+```
+*/
+module type Spec = {
+  module Id: Id.T
+
+  /** Logical aggregate name used as a prefix for infrastructure resource names. */
+  let name: string
+
+  /** Commands this aggregate accepts. Must carry `@schema`. */
+  @schema
+  type command
+
+  /** Events this aggregate emits. Must carry `@schema`. */
+  @schema
+  type event
+
+  /** Business rule violation errors. Must carry `@schema`. */
+  @schema
+  type error
+
+  /** Sury schema for the command type — generated automatically by `@schema`. */
+  let commandSchema: S.t<command>
+
+  /** File URL of this module (`import.meta.url`). Used by AWS builders to derive
+      the npm specifier for runtime dynamic imports. */
+  let moduleUrl: string
+
+  /** Authorization rule evaluated at the GraphQL resolver entry before any
+      command is dispatched. Auto-injected by `@@reventless.spec` and on
+      structurally-detected inline spec modules — defaults to
+      `AllowAuthenticated`; override at the file/module level with
+      `@@reventless.authorize(<rule>)`. */
+  let commandAuthorization: command => Authorization.permission
+}

package/src/components/Aggregate.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/AutomationSlice.res

@@ -0,0 +1,279 @@
+/**
+Module types for a DCB automation slice (TODO List Pattern).
+
+An `AutomationSlice` listens to the shared `DcbEventLog` event topic, accumulates
+pending work items (TODO list), and processes them exactly once by issuing commands.
+Completion events mark TODO items as done, closing the automation loop.
+
+```
+Event(s) → TODO List (read model) → Processor → Command → Event(s)
+```
+
+Plan 02 splits the merged spec into two module types:
+
+- `Spec` — types, identity, schemas, configuration constants. Per D2,
+  `todoItem` lives here (the persisted TODO state has a schema queried for
+  sweeping pending items — externally-observable, like ReadModel state).
+- `Automation` — the three pure functions `collect`, `resolve`, `process`.
+
+@example
+```rescript
+// ShipOrder.res
+let name = "ShipOrder"
+
+@schema type todoItem = {orderId: string, shippingAddress: string}
+@schema type command = CreateShipment({orderId: @s.matches(DcbTag.string) string, address: string})
+
+let collect = event => switch event {
+  | OrderPlaced({orderId, shippingAddress}) =>
+    [(orderId, {orderId, shippingAddress})]
+  | _ => []
+}
+
+let resolve = event => switch event {
+  | ShipmentCreated({orderId}) => Some(orderId)
+  | _ => None
+}
+
+let process = (id, item) =>
+  Some((id, CreateShipment({orderId: item.orderId, address: item.shippingAddress})))
+
+let maxRetries = 3
+let heartbeatInterval = 60
+```
+*/
+
+/**
+The lean Spec for an AutomationSlice — types, identity, schemas, sweep config.
+
+Plan 04 dropped `consumedEvent` from the Spec — the framework now derives the
+consumed-event set from each per-source Mapping's `sourceEventSchema`, so a
+manually-declared union is no longer necessary. Single-source slices have one
+`Mapping` whose `sourceEventSchema` IS the consumed-event schema; multi-source
+slices have several Mappings and the framework walks all of them.
+*/
+module type Spec = {
+  /** Logical name of this automation slice (used as a component prefix). */
+  let name: string
+  let moduleUrl: string
+
+  /** The TODO item state — what data is accumulated for each pending work item. Must carry `@schema`. */
+  @schema
+  type todoItem
+
+  /** The command type produced by the processor. Must carry `@schema`. */
+  @schema
+  type command
+
+  /** Maximum number of retries for a failed processing 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 produced command. */
+  let targetName: string
+}
+
+// ── Plan 04: Mixed-source mappings ───────────────────────────────────────────
+//
+// An AutomationSlice can declare per-source mappings that consume Aggregate
+// events alongside the slice's own DcbEventLog events. Each mapping carries its
+// own `collect`/`resolve` (over the source's `event` type) plus a `toTags`
+// validation step run before each command publish. `process` remains shared in
+// the slice's `Automation` module since it operates on `todoItem` regardless of
+// the originating source.
+
+/**
+Ambient deployment context plumbed to every mapping function.
+
+`Plugin_Builder` constructs this from its existing `~environment`, `~name` and
+related parameters. `collect` and `resolve` use it to complete partial event
+payloads (e.g. when a DCB tag field is supplied by deployment metadata rather
+than the source event); `toTags` uses it to validate that all tag fields on the
+target command will be populated.
+
+The record is intentionally narrow — extending it is a deliberate framework
+change, not an open-dict escape hatch. Runtime registry lookups are out of
+scope (see Plan 04 / decision 3).
+*/
+type context = {
+  environment: string,
+  platformName: string,
+  pluginName: string,
+  sliceName: string,
+}
+
+/**
+A compiled per-source-to-AutomationSlice mapping.
+
+Created by `AutomationSlice.Mapping.Make(Source, Target, Impl)`. The mapping
+binds `sourceEvent` (decode target) plus `collect`/`resolve` to the slice's
+`todoItem` type. `process` remains in the slice's `Automation` module — it is
+source-agnostic.
+
+Validation belongs upstream of the mapping: `collect` should return `[]` for
+events that shouldn't enter the TODO list, and the command schema's
+`@compositePartitionTag` / `@s.matches(DcbTag.string)` annotations enforce
+DCB-tag invariants at encode time (failures mark the item Failed → retry).
+*/
+module type Mapping = {
+  module SourceId: Id.T
+  @schema
+  type sourceEvent
+  type todoItem
+  type command
+  let sourceEventSchema: S.t<sourceEvent>
+  let sourceName: string
+  let collect: (sourceEvent, context) => array<(string, todoItem)>
+  let resolve: sourceEvent => option<string>
+}
+
+/**
+The Automation — the source-agnostic processing function.
+
+Plan 04 moved `collect` and `resolve` to per-source `Mapping` modules (where
+they switch over the source's own `event` type). `process` stays here because
+it operates on `todoItem`, which is uniform across sources.
+
+The "close PPX gaps" plan merged the previous `Mappings` shape into this type:
+the same module that exposes `process` also exposes the per-source `mappings`
+array and the inner `module type Mapping`. This collapses the Plan 04 3-arg
+`AutomationSlice.Make(Spec, Automation, Mappings)` into a 2-arg
+`Make(Spec, Automation)` and lets the merged `_Automation.res` file (process +
+per-source `Mapping.Make` + `let mappings`) live as a single source file.
+*/
+module type Automation = {
+  module Spec: Spec
+
+  /**
+  Process: given a pending TODO item, produce a command.
+  The processor calls this for each pending item. Returns the target ID and command.
+  May return `None` to skip processing (e.g., wait for more data).
+  */
+  let process: (string, Spec.todoItem) => option<(string, Spec.command)>
+
+  /** File URL of this Automation module (`import.meta.url`). */
+  let moduleUrl: string
+
+  /**
+  The per-source `Mapping` type — substituted onto the slice's `Spec`. The
+  PPX-injected `module M = Reventless.AutomationSlice.Mappings.Make(Spec)`
+  + `module type Mapping = M.Mapping` produces exactly this shape; legacy
+  3-file files re-export it via `module type Mapping = <Stem>_Mappings.Mapping`.
+  */
+  module type Mapping = Mapping
+    with type todoItem = Spec.todoItem
+    and type command = Spec.command
+
+  /**
+  The per-source mappings registered with this slice. Each entry is a first-class
+  module satisfying `Mapping`. The framework walks these to discover source
+  topics and dispatch decoded events to the matching `collect`/`resolve`.
+  */
+  let mappings: array<module(Mapping)>
+}
+
+/**
+The implementation passed to `AutomationSlice.Mapping.Make`. Caller-supplied
+`collect`/`resolve` are bound to source/target types via destructive
+substitution in the functor.
+*/
+module type MappingImpl = {
+  type sourceEvent
+  type todoItem
+  type command
+  let collect: (sourceEvent, context) => array<(string, todoItem)>
+  let resolve: sourceEvent => option<string>
+}
+
+/**
+A collection of `Mapping` modules for a single AutomationSlice target.
+
+Pass a `Mappings` module to the AutomationSlice plugin builder to register all
+source-to-slice mappings. The shape mirrors `Projection.Mappings` for
+ReadModels.
+
+@example
+```rescript
+// AutoFulfillment_Mappings.res
+module M = Reventless.AutomationSlice.Mappings.Make(AutoFulfillmentSpec)
+module type Mapping = M.Mapping
+
+let mappings: array<module(Mapping)> = [
+  module(FromOrderShipped),
+  module(FromStockReserved),
+]
+```
+*/
+module type Mappings = {
+  module Target: Spec
+  module type Mapping = Mapping
+    with type todoItem = Target.todoItem
+    and type command = Target.command
+  let moduleUrl: string
+  let mappings: array<module(Mapping)>
+}
+
+/**
+Builds an `AutomationSlice.Mapping` from a `Source`, the slice's `Spec`, and a
+`MappingImpl`.
+
+@example
+```rescript
+// AutoFulfillment/FromOrderShipped.res
+module FromOrderShipped = Reventless.AutomationSlice.Mapping.Make(
+  OrderSpec,                    // Source: Aggregate spec module
+  AutoFulfillmentSpec,          // Target: this slice's spec
+  {
+    let collect = (event, _ctx) =>
+      switch event {
+      | OrderSpec.OrderShipped({orderId, productId}) =>
+        [(orderId ++ ":" ++ productId, {AutoFulfillmentSpec.orderId, productId})]
+      | _ => []
+      }
+
+    let resolve = event =>
+      switch event {
+      | OrderSpec.OrderRefunded({orderId, productId}) =>
+        Some(orderId ++ ":" ++ productId)
+      | _ => None
+      }
+  },
+)
+```
+*/
+module Mapping = {
+  module Make = (
+    Source: Projection.Source,
+    Target: Spec,
+    Impl: MappingImpl
+      with type sourceEvent := Source.event
+      and type todoItem := Target.todoItem
+      and type command := Target.command,
+  ): (
+    Mapping
+      with type sourceEvent = Source.event
+      and type todoItem = Target.todoItem
+      and type command = Target.command
+      and module SourceId = Source.Id
+  ) => {
+    module SourceId = Source.Id
+    @schema
+    type sourceEvent = Source.event
+    type todoItem = Target.todoItem
+    type command = Target.command
+    let sourceName = Source.name
+    let collect = Impl.collect
+    let resolve = Impl.resolve
+  }
+}
+
+module Mappings = {
+  module Make = (Target: Spec) => {
+    module type Mapping = Mapping
+      with type todoItem = Target.todoItem
+      and type command = Target.command
+  }
+}
+

package/src/components/AutomationSlice.res.mjs

@@ -0,0 +1,30 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function Make(Source) {
+  return Target => (Impl => ({
+    SourceId: Source.Id,
+    sourceEventSchema: Source.eventSchema,
+    sourceName: Source.name,
+    collect: Impl.collect,
+    resolve: Impl.resolve
+  }));
+}
+
+let Mapping = {
+  Make: Make
+};
+
+function Make$1(Target) {
+  return {};
+}
+
+let Mappings = {
+  Make: Make$1
+};
+
+export {
+  Mapping,
+  Mappings,
+}
+/* No side effect */

package/src/components/Counter.res

@@ -0,0 +1,24 @@
+/**
+A named counter (e.g. `"ProductCount"`). Used as a key in the counts database.
+Multiple counters can exist within the same `Counter` component.
+*/
+type counterId = string
+
+/**
+An opaque reference string that de-duplicates counter increments.
+
+Each unique `reference` is counted at most once per `counterId`.
+Typically set to the event's message ID to make increments idempotent.
+*/
+type reference = string
+
+/**
+A counter threshold target.
+
+When the count for `counterId` reaches `target`, the event mapping
+framework fires the associated command.
+*/
+type counterTarget = {
+  counterId: counterId,
+  target: int,
+}