@reventlessdev/reventless-spec

⚠️ Alpha. APIs and on-disk formats can change without notice between releases. Pin exact versions and expect breaking changes.

The specification layer of Reventless — a spec-driven, event-sourced CQRS framework written in ReScript. This package holds the type specifications and module-type interfaces that the rest of the framework is built on: the contracts application domain code implements (commands, events, behaviors, projections) and the component-kind vocabulary the whole framework shares. It has no runtime, cloud, or storage dependency, so domain code can declare its shape against reventless-spec without pulling in an implementation. Modules are exposed under the Reventless namespace.

What it provides

ReScript modules, consumed by adding the package to your rescript.json dependencies.

Domain contracts (types/)

• Message — the envelope metadata carried by every event and command (meta, event'<>, command'<>), used for audit, correlation, tracing, and routing.
• Behavior — the module type application code implements to define aggregate business logic: initialState, evolve(state, event), and decide(command, state).
• Projection — Source / Target module types describing a read model projected from an aggregate's events.
• Handler — function signatures for handling commands, events, and errors.
• SideEffect — module type for an imperative side effect triggered by aggregate events (read-only access to the query engine; emits no events).
• StoredEvent — the logical envelope for an event as it lives in storage; single source of truth for the on-disk event shape.
• Authorization / Identity — provider-agnostic permission rules evaluated against a resolved identity.
• QueryEngine — typed filter values and operations for read-model queries.
• Id, EventMapping, ReadConsistency, Schedule, Visibility — supporting spec types for identifiers, event translation, consistency, scheduling, and exposure.

Component vocabulary (components/)

• ComponentKind — the single source of truth for the Reventless component-kind vocabulary (aggregates, read models, tasks, extension points, DCB slices), including every accepted folder spelling and body-file suffix.
• Per-kind spec modules: Aggregate, ReadModel, Task, ExtensionPoint, Plugin, and the DCB slices (StateChangeSlice, StateViewSlice, AutomationSlice, InboundTranslationSlice, OutboundTranslationSlice), plus DCB tagging/validation helpers.

generate-plugin CLI

reventless-spec ships a generate-plugin binary that auto-generates src/Plugin.res from a plugin's folder structure, classifying .res files by their parent folder name — no hand-authored composition root required.

generate-plugin src/          # generate src/Plugin.res from the src/ folder

Wire it into your build via a prebuild script so it runs before rescript build. The generated Plugin.res is committed to git, so CI compiles it directly.

Where it fits

reventless-spec is the foundation package in the Reventless framework:

reventless-spec (specifications)  ← this package
  ↓
reventless-core (provider-agnostic framework)
  ↓
reventless-aws / reventless-postgres / reventless-local (storage & deployment adapters)

• @reventlessdev/reventless-core builds on these specs to provide the runtime building blocks.
• @reventlessdev/reventless-infra layers deploy-time infrastructure types on top of the same specs.

You normally obtain reventless-spec transitively by scaffolding an app rather than installing it on its own.

Install

pnpm add @reventlessdev/reventless-spec

Then register it as a ReScript dependency in rescript.json:

{
  "dependencies": ["@reventlessdev/reventless-spec"]
}

Requires ReScript ^12.3.0 (peer dependency).

Links

• 📚 Documentation — docs.reventless.dev
• 📦 Repository — ReventlessDev/reventless-core
• 📋 Changelog

License

Apache-2.0