@reventlessdev/reventless-spec 3.0.0-alpha.61

package/src/types/EventMapping.res

@@ -0,0 +1,100 @@
+/**
+The aggregate whose events will be mapped.
+Identifies the event topic to subscribe to via `name` and `Id`.
+*/
+module type Source = {
+  let name: string
+  module Id: Id.T
+  @schema
+  type event
+}
+
+/**
+The aggregate whose commands will be produced.
+Identifies the command topic to publish to via `name` and `Id`.
+*/
+module type Target = {
+  let name: string
+  module Id: Id.T
+  @schema
+  type command
+}
+
+/**
+The outcome of an event-to-command mapping.
+
+A `map` function returns an array of `action` values describing what should
+happen when a source event is observed.
+
+- `Publish(id, cmd)` — immediately publish a command to the target aggregate
+- `PublishDelayed(id, cmd, seconds)` — publish a command after a delay
+- `PublishAsync(promise)` — resolve a promise and publish all resulting commands
+- `AddToCounterTarget(target)` — register a counter threshold target
+- `Count(id)` — increment a counter by 1
+- `CountMulti(id, n)` — increment a counter by `n`
+
+@example
+```rescript
+// Route CategoryArchived to update the Products read model
+let map = (sourceId, event, _queryEngine) => switch event {
+  | CategoryArchived({categoryId}) =>
+    [EventMapping.Publish(categoryId, ArchiveProductsInCategory({categoryId}))]
+  | _ => []
+}
+```
+*/
+type action<'id, 'command> =
+  /** Immediately publish a command to the target aggregate. */
+  | Publish('id, 'command)
+  /** Publish a command after `int` seconds. */
+  | PublishDelayed('id, 'command, int)
+  /** Resolve a promise and publish all resulting `(id, command)` pairs. */
+  | PublishAsync(promise<array<('id, 'command)>>)
+  /** Register a counter threshold target (used with the Counter component). */
+  | AddToCounterTarget(Counter.counterTarget)
+  /** Increment a named counter by 1. */
+  | Count(Counter.counterId)
+  /** Increment a named counter by `n`. */
+  | CountMulti(Counter.counterId, int)
+
+/**
+Module type for an event-to-command mapping.
+
+Implement this to route events from one aggregate to commands on another.
+The `map` function is pure — use `PublishAsync` for async lookups.
+
+@example
+```rescript
+module CategoryToProduct: EventMapping.T = {
+  module Source = Category
+  module Target = Product
+  let map = (sourceId, event, _q) => switch event {
+    | CategoryArchived({categoryId}) =>
+      [Publish(categoryId, ArchiveProductsInCategory({categoryId}))]
+    | _ => []
+  }
+}
+```
+*/
+module type T = {
+  module Source: Source
+  module Target: Target
+  /**
+  Map a source event to zero or more target actions.
+
+  - `Source.Id.t` — the ID of the aggregate that emitted the event
+  - `Source.event` — the domain event payload
+  - `QueryEngine.operations` — read-only query engine for async lookups
+  */
+  let map: (
+    Source.Id.t,
+    Source.event,
+    QueryEngine.operations,
+  ) => array<action<Target.Id.t, Target.command>>
+}
+
+module Mappings = {
+  module Make = (Target: Target) => {
+    module type Mapping = T with module Target := Target
+  }
+}

package/src/types/EventMapping.res.mjs

@@ -0,0 +1,15 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function Make(Target) {
+  return {};
+}
+
+let Mappings = {
+  Make: Make
+};
+
+export {
+  Mappings,
+}
+/* No side effect */

package/src/types/Handler.res

@@ -0,0 +1,30 @@
+// Handler types for application developers.
+// These define the function signatures for handling commands, events, and errors.
+
+/** A generic async handler for any message type `'msg`. */
+type handler<'msg> = 'msg => promise<unit>
+
+/**
+Handler for a single typed command.
+
+@example
+```rescript
+let handleCategory: Handler.commandHandler<string, Category.command> = async msg => {
+  Console.log2("Handling command for", msg.id)
+}
+```
+*/
+type commandHandler<'id, 'command> = Message.command'<'id, 'command> => promise<unit>
+
+/**
+Handler for a batch of commands sharing the same aggregate ID.
+Batches arrive when multiple commands are enqueued for the same ID.
+*/
+type commandsHandler<'id, 'command> = ('id, array<Message.command'<'id, 'command>>) => promise<unit>
+
+/**
+Handler for a batch of events sharing the same aggregate ID.
+Used by read model projections and extension points.
+*/
+type eventsHandler<'id, 'event> = ('id, array<Message.event'<'id, 'event>>) => promise<unit>
+

package/src/types/Handler.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/types/Id.res

@@ -0,0 +1,75 @@
+/**
+Module type for aggregate and read model identifiers.
+
+Every Reventless component declares its own `Id` module satisfying this type.
+The abstract `type t` prevents accidentally mixing identifiers from different
+aggregates at compile time.
+
+@example
+```rescript
+// Category.res
+module Id = Id.String
+```
+*/
+module type T = {
+  /** The opaque identity type. Sealed so IDs from different aggregates cannot be mixed. */
+  @schema
+  type t
+
+  /** The input form accepted by `make` (e.g. `string`, `int`, or a record). */
+  type input
+
+  /** Construct a typed ID from its input representation. */
+  let make: input => t
+
+  /** Construct a typed ID from a plain string (used by adapters and routing layers). */
+  let makeFromString: string => t
+
+  /** Convert a typed ID back to its string representation. */
+  let toString: t => string
+
+  /** Compare two IDs. Required for sorted data structures and range queries. */
+  let cmp: (t, t) => Ordering.t
+}
+
+/**
+A transparent string-based `Id.T` implementation.
+
+`StringPure.t = string`, so IDs can be written as plain string literals in
+test code without casting. Use `Id.String` (the sealed version) in production
+module specs.
+
+@example
+```rescript
+// In test specs where literal strings are convenient:
+module TestCategorySpec = {
+  module Id = Id.StringPure
+  let name = "Category"
+  // Id.make("cat-1") == "cat-1"
+}
+```
+*/
+module StringPure = {
+  @schema
+  type t = string
+  type input = string
+  external make: t => t = "%identity"
+  external makeFromString: string => t = "%identity"
+  external toString: t => t = "%identity"
+  let cmp: (t, t) => Ordering.t = String.compare
+}
+
+/**
+A sealed string-based `Id.T` implementation for use in production aggregate specs.
+
+Unlike `StringPure`, the `t` type is abstract, preventing accidental cross-aggregate
+ID mixing. Use `Id.StringPure` in tests when string literals are needed.
+
+@example
+```rescript
+// Category.res
+module Id = Id.String
+let name = "Category"
+```
+*/
+module String: T = StringPure

package/src/types/Id.res.mjs

@@ -0,0 +1,37 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+
+let cmp = Primitive_string.compare;
+
+let StringPure = {
+  schema: S.string,
+  cmp: cmp
+};
+
+function String_make(prim) {
+  return prim;
+}
+
+function String_makeFromString(prim) {
+  return prim;
+}
+
+function String_toString(prim) {
+  return prim;
+}
+
+let $$String = {
+  schema: S.string,
+  make: String_make,
+  makeFromString: String_makeFromString,
+  toString: String_toString,
+  cmp: cmp
+};
+
+export {
+  StringPure,
+  $$String,
+}
+/* S Not a pure module */

package/src/types/Identity.res

@@ -0,0 +1,46 @@
+S.enableJson()
+
+/** Identity provider that authenticated the user. */
+@schema
+type provider = Cognito | InMemory | Custom(string)
+
+/**
+Per-request identity carried through RequestContext.
+
+NOT persisted in events — only `userId` is stored as `meta.user`.
+Full identity lives in-memory for the duration of a single request.
+*/
+@schema
+type t = {
+  userId: string,
+  username: string,
+  groups: array<string>,
+  claims?: dict<string>,
+  provider: provider,
+}
+
+let anonymous: t = {
+  userId: "anonymous",
+  username: "anonymous",
+  groups: [],
+  provider: InMemory,
+}
+
+let hasGroup = (identity: t, group: string): bool =>
+  identity.groups->Array.includes(group)
+
+let getClaim = (identity: t, key: string): option<string> =>
+  switch identity.claims {
+  | Some(claims) => claims->Dict.get(key)
+  | None => None
+  }
+
+/**
+Outcome of a single `Auth_Adapter.Provider.authenticate` call.
+`AuthError` carries a short human-readable reason (logged, not returned
+verbatim to clients) — useful for diagnosing failed bearer-token validation.
+*/
+type authResult =
+  | Authenticated(t)
+  | Anonymous
+  | AuthError(string)

package/src/types/Identity.res.mjs

@@ -0,0 +1,51 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+
+S.enableJson();
+
+let providerSchema = S.union([
+  S.literal("Cognito"),
+  S.literal("InMemory"),
+  S.schema(s => ({
+    TAG: "Custom",
+    _0: s.m(S.string)
+  }))
+]);
+
+let schema = S.schema(s => ({
+  userId: s.m(S.string),
+  username: s.m(S.string),
+  groups: s.m(S.array(S.string)),
+  claims: s.m(S.option(S.dict(S.string))),
+  provider: s.m(providerSchema)
+}));
+
+let anonymous_groups = [];
+
+let anonymous = {
+  userId: "anonymous",
+  username: "anonymous",
+  groups: anonymous_groups,
+  provider: "InMemory"
+};
+
+function hasGroup(identity, group) {
+  return identity.groups.includes(group);
+}
+
+function getClaim(identity, key) {
+  let claims = identity.claims;
+  if (claims !== undefined) {
+    return claims[key];
+  }
+}
+
+export {
+  providerSchema,
+  schema,
+  anonymous,
+  hasGroup,
+  getClaim,
+}
+/*  Not a pure module */

package/src/types/Message.res

@@ -0,0 +1,197 @@
+S.enableJson()
+
+/** Identifies the service that produced or is addressed by a message. */
+@schema
+type service = string
+
+/**
+Envelope metadata attached to every event and command.
+
+Every message that flows through Reventless carries this metadata so that
+audit trails, correlation, distributed tracing, and routing are available
+without inspecting the domain payload.
+
+Shared by both `event'<>` and `command'<>` envelopes — fields are kept
+generic so they apply equally to commands and events.
+
+@example
+```rescript
+let meta: Message.meta = {
+  service: "CatalogService",
+  time: "2024-01-01T00:00:00Z",
+  msgId: "msg-abc",
+  correlationId: "cmd-xyz",
+  user: "alice",
+}
+```
+*/
+@schema
+type meta = {
+  /** Name of the service that created or is addressed by this message. */
+  service: service,
+  /** ISO-8601 timestamp of when the message was created (producer time). */
+  time: string,
+  /** IP address of the service instance that created the message. Absent when unknown
+      (e.g. serverless contexts without a caller IP). */
+  ip?: string,
+  /** Identity of the actor who initiated the action. Absent for system-initiated messages. */
+  user?: string,
+  /** Unique identifier for this message. */
+  msgId: string,
+  /** Identifier of the root message of the correlation chain. Always present;
+      defaults to `msgId` when this is the root. */
+  correlationId: string,
+  /** Identifier of the *direct* parent message that caused this one. Absent at the chain root. */
+  causationId?: string,
+  /** W3C Trace Context `traceparent` header value (opaque pass-through).
+      Intentionally all-lowercase: matches the HTTP header name, OpenTelemetry SDKs,
+      and the CloudEvents distributed-tracing extension. */
+  traceparent?: string,
+  /** Schema version stamp for this message's payload variant. Absent = unversioned. */
+  schemaVersion?: string,
+  /** Extensible header bag for cross-cutting context (tenantId, feature flags, etc.).
+      Absent when empty — consumers normalise with `->Option.getOr(Dict.make())`. */
+  headers?: dict<string>,
+}
+
+/**
+Context passed into command handlers, carrying the aggregate ID and envelope metadata.
+
+Passed as the second argument to `Behavior.T.create` and `Behavior.T.execute`
+so business logic can read the caller identity or propagate correlation IDs.
+*/
+@schema
+type context = {
+  id: string,
+  meta: meta,
+}
+
+/**
+A domain event envelope pairing an aggregate ID with the event payload and metadata.
+
+The generic parameters `'id` and `'event` are fixed by each aggregate's `Spec`:
+- `'id` comes from `Spec.Id.t`
+- `'event` comes from `Spec.event`
+
+@example
+```rescript
+let ev: Message.event'<string, Category.event> = {
+  id: "cat-1",
+  meta,
+  event: CategoryAdded({categoryId: "cat-1", name: "Electronics"}),
+}
+```
+*/
+type event'<'id, 'event> = {
+  id: 'id,
+  meta: meta,
+  event: 'event,
+}
+
+/**
+Records who changed a resource's status and when.
+Useful in audit-trail projections (e.g. "approved by bob at 2024-01-15").
+*/
+@schema
+type statusChange = {
+  at: string,
+  by: string,
+}
+
+/**
+A command envelope pairing an aggregate ID with the command payload and metadata.
+
+@example
+```rescript
+let cmd: Message.command'<string, Category.command> = {
+  id: "cat-1",
+  meta,
+  command: AddCategory({categoryId: "cat-1", name: "Electronics"}),
+}
+```
+*/
+type command'<'id, 'command> = {
+  id: 'id,
+  meta: meta,
+  command: 'command,
+}
+
+/**
+A serialized command envelope used when routing commands across service boundaries.
+
+`commandJson` holds the raw JSON payload encoded by sury. The optional `delay`
+field specifies a delivery delay in seconds (used by the scheduler).
+
+@example
+```rescript
+let queued: Message.commandJson = {
+  id: "cat-1",
+  meta,
+  commandJson: json,
+  delay: Some(5),
+}
+```
+*/
+@schema
+type commandJson = {
+  id: string,
+  meta: meta,
+  commandJson: JSON.t,
+  delay?: int,
+}
+
+/**
+Decode a JSON value into `'a` using a sury schema. Throws on parse failure.
+
+@example
+```rescript
+let event = json->Message.decode(Category.eventSchema)
+```
+*/
+let decode = (json, schema: S.t<'a>) => json->S.parseJsonOrThrow(schema)
+
+/**
+Encode a value to JSON using a sury schema.
+
+@example
+```rescript
+let json = event->Message.encode(Category.eventSchema)
+```
+*/
+let encode = (value, schema: S.t<'a>) => value->S.reverseConvertToJsonOrThrow(schema)
+
+/** Raised by adapters when an incoming event JSON cannot be matched to a known event variant. */
+exception InvalidEvent(JSON.t)
+
+let toEventSchema' = (idSchema, eventSchema) =>
+  S.object(s => {
+    id: s.field("id", idSchema),
+    meta: s.field("meta", metaSchema),
+    event: s.field("event", eventSchema),
+  })
+
+/** Decode a raw event JSON envelope into a typed `event'<'id, 'event>`. */
+let decodeEvent' = (json, idSchema, eventSchema) =>
+  json->S.parseJsonOrThrow(toEventSchema'(idSchema, eventSchema))
+
+/** Extract the variant constructor name from a sury-encoded variant JSON. */
+let variantNameOfJson = json =>
+  switch json {
+  | JSON.String(str) => str
+  | Object(dict) =>
+    switch dict->Dict.get("TAG") {
+    | Some(String(tag)) => tag
+    | _ => "unknown"
+    }
+  | _ => "unknown"
+  }
+
+/** Compose a raw event JSON envelope from id, meta, and event JSON. */
+let composeEventJson' = (id, meta, eventJson) =>
+  [
+    ("id", id->JSON.Encode.string),
+    ("meta", meta->S.reverseConvertToJsonOrThrow(metaSchema)),
+    ("event", eventJson),
+  ]
+  ->Dict.fromArray
+  ->JSON.Encode.object

package/src/types/Message.res.mjs

@@ -0,0 +1,108 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+
+S.enableJson();
+
+let metaSchema = S.schema(s => ({
+  service: s.m(S.string),
+  time: s.m(S.string),
+  ip: s.m(S.option(S.string)),
+  user: s.m(S.option(S.string)),
+  msgId: s.m(S.string),
+  correlationId: s.m(S.string),
+  causationId: s.m(S.option(S.string)),
+  traceparent: s.m(S.option(S.string)),
+  schemaVersion: s.m(S.option(S.string)),
+  headers: s.m(S.option(S.dict(S.string)))
+}));
+
+let contextSchema = S.schema(s => ({
+  id: s.m(S.string),
+  meta: s.m(metaSchema)
+}));
+
+let statusChangeSchema = S.schema(s => ({
+  at: s.m(S.string),
+  by: s.m(S.string)
+}));
+
+let commandJsonSchema = S.schema(s => ({
+  id: s.m(S.string),
+  meta: s.m(metaSchema),
+  commandJson: s.m(S.json),
+  delay: s.m(S.option(S.int))
+}));
+
+let decode = S.parseJsonOrThrow;
+
+let encode = S.reverseConvertToJsonOrThrow;
+
+let InvalidEvent = /* @__PURE__ */Primitive_exceptions.create("Message-Reventless.InvalidEvent");
+
+function toEventSchema$p(idSchema, eventSchema) {
+  return S.object(s => ({
+    id: s.f("id", idSchema),
+    meta: s.f("meta", metaSchema),
+    event: s.f("event", eventSchema)
+  }));
+}
+
+function decodeEvent$p(json, idSchema, eventSchema) {
+  return S.parseJsonOrThrow(json, toEventSchema$p(idSchema, eventSchema));
+}
+
+function variantNameOfJson(json) {
+  if (json === null || Array.isArray(json)) {
+    return "unknown";
+  }
+  switch (typeof json) {
+    case "string" :
+      return json;
+    case "object" :
+      let match = json["TAG"];
+      if (typeof match === "string") {
+        return match;
+      } else {
+        return "unknown";
+      }
+    default:
+      return "unknown";
+  }
+}
+
+function composeEventJson$p(id, meta, eventJson) {
+  return Object.fromEntries([
+    [
+      "id",
+      id
+    ],
+    [
+      "meta",
+      S.reverseConvertToJsonOrThrow(meta, metaSchema)
+    ],
+    [
+      "event",
+      eventJson
+    ]
+  ]);
+}
+
+let serviceSchema = S.string;
+
+export {
+  serviceSchema,
+  metaSchema,
+  contextSchema,
+  statusChangeSchema,
+  commandJsonSchema,
+  decode,
+  encode,
+  InvalidEvent,
+  toEventSchema$p,
+  decodeEvent$p,
+  variantNameOfJson,
+  composeEventJson$p,
+}
+/*  Not a pure module */