@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/types/Authorization.res.mjs

@@ -0,0 +1,33 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+
+let permissionSchema = S.union([
+  S.schema(s => ({
+    TAG: "AllowGroups",
+    _0: s.m(S.array(S.string))
+  })),
+  S.literal("AllowAuthenticated"),
+  S.literal("AllowAnonymous"),
+  S.literal("DenyAll")
+]);
+
+function isAllowed(rule, identity) {
+  if (typeof rule === "object") {
+    return rule._0.some(group => identity.groups.includes(group));
+  }
+  switch (rule) {
+    case "AllowAuthenticated" :
+      return identity.userId !== "anonymous";
+    case "AllowAnonymous" :
+      return true;
+    case "DenyAll" :
+      return false;
+  }
+}
+
+export {
+  permissionSchema,
+  isAllowed,
+}
+/* permissionSchema Not a pure module */

package/src/types/Behavior.res

@@ -0,0 +1,86 @@
+// Behavior module type for aggregate business logic.
+// Lives in reventless-spec so application domain code can define behaviors
+// without importing the reventless implementation package.
+
+/**
+Module type that application code must implement to define aggregate business logic.
+
+A `Behavior.T` module contains the `Spec` (command / event / error types), the
+aggregate `state`, and two pure functions plus an initial state value:
+
+- `initialState` — the starting state before any events (represents "not yet created")
+- `evolve` — fold an event into the current state
+- `decide` — handle a command on the current state, returning `Ok(events)` or `Error(error)`
+
+@example
+```rescript
+// CategoryBehavior.res
+module Spec = Category
+
+@schema
+type state = NotCreated | Active({name: string}) | Archived
+
+let initialState = NotCreated
+
+let evolve = (state, event) => switch (state, event) {
+  | (NotCreated, CategoryAdded({name})) => Active({name})
+  | (Active(_), CategoryRenamed({name})) => Active({name})
+  | (Active(_), CategoryArchived(_)) => Archived
+  | _ => state
+}
+
+let decide = (state, cmd) => switch (state, cmd) {
+  | (NotCreated, AddCategory({categoryId, name})) => Ok([CategoryAdded({categoryId, name})])
+  | (NotCreated, _) => Error(CategoryNotFound)
+  | (Active(_), AddCategory(_)) => Error(CategoryAlreadyExists)
+  | (Active(_), RenameCategory({categoryId, name})) => Ok([CategoryRenamed({categoryId, name})])
+  | (Active(_), ArchiveCategory({categoryId})) => Ok([CategoryArchived({categoryId})])
+  | (Archived, _) => Error(CategoryAlreadyArchived)
+}
+```
+*/
+module type T = {
+  module Spec: {
+    /** The command type. Must carry a `@schema` attribute. */
+    @schema
+    type command
+
+    /** The event type. Must carry a `@schema` attribute. */
+    @schema
+    type event
+
+    /** The error type returned when business rules are violated. */
+    @schema
+    type error
+  }
+
+  /** The aggregate's internal state type. Not persisted; rebuilt by replaying events. */
+  type state
+
+  /** The starting state before any events have been applied. */
+  let initialState: state
+
+  /**
+  Fold one event into the current state. Called for every event during replay.
+  Must be a pure function — no side effects.
+  */
+  let evolve: (state, Spec.event) => state
+
+  /**
+  Handle a command on the current state.
+  Return `Ok(events)` to emit events, or `Error(error)` to reject the command.
+  */
+  let decide: (state, Spec.command) => result<array<Spec.event>, Spec.error>
+
+  /** Persisted-snapshot configuration (docs/plans/aggregate-snapshotting.md).
+      `None` — the default, auto-injected by `@@reventless.behavior` — keeps
+      full replay; `Some({interval, stateSchema})` writes a keep-one snapshot
+      every `interval` events and seeds cold replays from the latest one.
+      Enable with `@@reventless.snapshots(<interval>)` (requires
+      `@schema type state`) or a manual binding. */
+  let snapshot: option<Snapshot.config<state>>
+
+  /** File URL of this module (`import.meta.url`). Used by AWS builders to derive
+      the npm specifier for runtime dynamic imports. */
+  let moduleUrl: string
+}

package/src/types/Behavior.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/DateTime.res

@@ -0,0 +1,29 @@
+/**
+Marks a `string` state field as an ISO-8601 date-time.
+
+Sury has no string-typed datetime format (`S.datetime` transforms to `Js.Date.t`,
+changing the field's runtime type), so this mirrors the `DcbTag.string`
+precedent: a `S.t<string>` carrying sury metadata that downstream schema walkers
+detect. `SchemaType`/`SuryToJsonSchema` surface it as `format: "date-time"` on
+the field's JSON Schema, which the AutoUI date heuristics key off (CalendarView,
+TimelineView, date-axis charts).
+
+Use on a producer/storage timestamp a projection writes into its state — most
+commonly a `meta.time`-derived field such as `placedAt` / `shippedAt`:
+
+@example
+```rescript
+@schema
+type state = {
+  orderId: string,
+  placedAt: @s.matches(Reventless.DateTime.string) string,
+}
+```
+*/
+
+/** A sury string schema annotated as an ISO-8601 date-time field.
+    Use with `@s.matches(Reventless.DateTime.string)`. */
+let string: S.t<string> = S.string->Semantic.mark(~id=Semantic.Id.dateTime)
+
+/** Whether a field schema carries the date-time marker. */
+let isDateTime = (fieldSchema: S.t<unknown>) => fieldSchema->Semantic.has(~id=Semantic.Id.dateTime)

package/src/types/DateTime.res.mjs

@@ -0,0 +1,16 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
+
+let string = Semantic$Reventless.mark(S.string, Semantic$Reventless.Id.dateTime, undefined);
+
+function isDateTime(fieldSchema) {
+  return Semantic$Reventless.has(fieldSchema, Semantic$Reventless.Id.dateTime);
+}
+
+export {
+  string,
+  isDateTime,
+}
+/* string Not a pure module */

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 */