event_engine-event_definition 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d4fd0fd21eecd6b764d2c91c230bff8733c055148918fdcc3dc027b80cecddb3
+  data.tar.gz: 39a989288b99eb7fbe86777f787c357bfedee66e36f1800ce9432915ec92ea93
+SHA512:
+  metadata.gz: 0b245cffa43807384cc64d41ae50cca49a967636dd08156766ba5af768dc2c456191bc9eadf886cac8db40c1d57ede617275124fa4da4f906998b01d988b2755
+  data.tar.gz: e1c634fe59d2e0afe642c65057939c3123513586ad1402e273bcb1352e38e630148d51a148f9404b537240c5fd55443548d7bd485c755c57d2964857387e420e

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this gem are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-07-20
+
+First published release of `event_engine-event_definition`, the plain-Ruby
+event-definition contract for the EventEngine pipeline.
+
+### Added
+- EventDefinition DSL and shared schema-contract value objects (`Schema`,
+  `EventSchema`, `SchemaRegistry`, `SubjectRegistry`, `LifecycleDefinition`,
+  `DslCompiler`), with no Rails dependency.
+- Configurable publisher port (`EventEngine::Definition.publisher`), defaulting
+  to a `NullPublisher` that fails loudly until a real adapter is assigned.
+- Generated namespaced singleton helper methods that publish domain and input
+  payloads through the publisher port.
+- `DomainPackBuild`, which writes a flat helper file alongside its `schema.json`
+  for a domain pack and exposes a `schema_path` accessor in the generated helper.
+- `DefinitionLoader.load!` to require a pack's definition files, including
+  lifecycle-generated events.
+- `EventEngine::Definition.configure` for pack-generation settings.
+- `event_engine:definition:dump` rake task to generate a pack without Rails.
+
+[0.2.0]: https://github.com/DYB-Development/event_engine-event_definition/releases/tag/v0.2.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 tylercschneider
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,203 @@
+# EventEngine::Definition
+
+The plain-Ruby event-definition contract for the [EventEngine](https://github.com/DYB-Development/event_engine) pipeline.
+
+EventEngine is a schema-first event pipeline: domain events are **declared** with a Ruby DSL, **compiled** into a canonical schema, and **emitted** through generated helper methods that hand each event to a publisher. This gem holds the plain-Ruby foundation of that pipeline — the `EventEngine::EventDefinition` DSL, the shared schema value objects, and the build step that turns a set of definitions into a committed helper file — with **no Rails dependency**.
+
+Lightweight domain-pack gems depend on this contract; the full dispatch, registry, and Rails-engine machinery lives in [`event_engine`](https://github.com/DYB-Development/event_engine) and is wired in at runtime.
+
+## Installation
+
+Requires Ruby `>= 3.2.0`.
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "event_engine-event_definition"
+```
+
+Then run `bundle install`, and require it:
+
+```ruby
+require "event_engine/definition"
+```
+
+## A worked example
+
+### The data you want to capture
+
+Say a lead just signed up in your Rails app. You have the record in hand:
+
+```ruby
+lead = Lead.create!(
+  email:   "ada@example.com",
+  name:    "Ada Lovelace",
+  company: "Analytical Engines",
+  source:  "webinar"
+)
+# => #<Lead id: 42, email: "ada@example.com", name: "Ada Lovelace",
+#           company: "Analytical Engines", source: "webinar", created_at: …>
+```
+
+You want to announce that a lead was created so the rest of the system — analytics, CRM sync, a welcome email — can react. Done ad hoc, every place that raises this "event" builds its own hash: one sends `{ email: … }`, another `{ email_address: …, lead: 42 }`, a third forgets `source`. The keys drift, fields go missing, and every consumer has to defend against all of it.
+
+Defining the event fixes the shape **once**, so every producer emits the same data in the same format and every consumer can rely on it — with the names checked and the shape fingerprinted so it can't change silently.
+
+### Declare the event
+
+```ruby
+class LeadCreated < EventEngine::EventDefinition
+  event_name :lead_created   # the event's identity
+  event_type :domain         # how you classify it
+  domain     :marketing      # the bounded context it belongs to
+
+  input :lead                # the object the event is built from
+
+  required_payload :lead_id, from: :lead, attr: :id
+  required_payload :email,   from: :lead, attr: :email
+  required_payload :name,    from: :lead, attr: :name
+  optional_payload :company, from: :lead, attr: :company
+  optional_payload :source,  from: :lead, attr: :source
+end
+```
+
+Read each payload line as: *"the event carries `lead_id`, and its value comes from `lead.id`."* The `input :lead` names the object you hand in; each `from:` points back at that input, and each `attr:` is the attribute read off it.
+
+### Generate the pack (a build step)
+
+The helper doesn't exist until you generate it. `event_engine-event_definition` ships a rake task for that. Configure it once, then run it whenever a definition changes:
+
+```ruby
+# Rakefile (in your domain pack)
+require "event_engine/definition"
+load "tasks/event_engine_definition.rake"
+
+EventEngine::Definition.configure do |config|
+  config.definitions_path = "app/event_definitions"             # where your EventDefinitions live
+  config.helper_path      = "lib/generated/marketing_events.rb" # where to write the helper
+  config.root_module      = "MarketingEvents"                   # the module that wraps the helpers
+end
+```
+
+```sh
+$ rake event_engine:definition:dump
+```
+
+The task loads every definition under `definitions_path` — **no Rails required** — and writes two files you commit:
+
+- a `MarketingEvents` module with one typed method per event, and
+- a `schema.json` alongside it — the committed contract downstream consumers read.
+
+This is a build-time step; your app never runs it while serving requests. If your events declare a `subject`, register them too: `config.subject_registry = EventEngine::SubjectRegistry.define { subject :lead }`.
+
+### Emit the event (at runtime)
+
+With the helper generated, producing the event anywhere in your app is one call. You hand it the whole `lead`; the contract decides what is captured off it:
+
+```ruby
+MarketingEvents.lead_created(lead: lead)
+```
+
+Every `lead_created` event, from anywhere in the app, carries exactly the shape you declared:
+
+```ruby
+{
+  lead_id: 42,
+  email:   "ada@example.com",
+  name:    "Ada Lovelace",
+  company: "Analytical Engines",
+  source:  "webinar"
+}
+```
+
+> **Where the work happens:** this gem *records* the `from:`/`attr:` mapping and forwards the raw `lead` under `inputs:`. Reading `lead.id`, `lead.email`, … to build that payload is done by the publisher the `event_engine` runtime supplies — see [How it fits](#how-it-fits-with-event_engine). Until one is configured the default publisher raises, so wire it once at boot:
+>
+> ```ruby
+> EventEngine::Definition.publisher = my_publisher   # any object with #publish(event_name, **envelope)
+> ```
+
+### More examples
+
+See **[docs/examples.md](docs/examples.md)** for an event built from **multiple inputs** (an order and its customer) and a **lifecycle** that generates one event per step (started / completed / failed).
+
+## The DSL reference
+
+### Declarations, field by field
+
+| Declaration | Required to be valid? | What it does |
+|---|---|---|
+| `event_name :x` | **Yes** — `schema` raises without it | The event's unique, snake_case identity. |
+| `event_type :x` | **Yes** — `schema` raises without it | A classification symbol you choose (e.g. `:domain`, `:product`). Not enumerated by this gem. |
+| `domain :x` | No | The bounded context the event belongs to. Keys the event in the registry and scopes the generated helpers. |
+| `subject :x` | No | The aggregate the event is about. If set, it must be registered in a `SubjectRegistry` when the definitions are compiled. |
+| `input :x` | — | Declares an **input** the event is built from. |
+| `optional_input :x` | — | Same, but the input may be omitted at the call site. |
+| `required_payload :name, from:, attr:` | — | Declares a **payload field** in the emitted event. |
+| `optional_payload :name, from:, attr:` | — | Same, but the field is not a guaranteed part of the payload. |
+
+### Inputs vs. payload
+
+These are two different layers:
+
+- **Inputs are the arguments you hand the event** — the whole objects your code already has. Each becomes a keyword argument on the generated helper.
+  - `input :lead` → `lead:` is **required** at the call site.
+  - `optional_input :campaign` → `campaign:` **defaults to `nil`** and may be omitted.
+
+- **Payload fields are the flat data the event carries**, described as a mapping *off* those inputs (`from:` = which input, `attr:` = which attribute on it).
+  - `required_payload` → the field is a **guaranteed** part of the payload.
+  - `optional_payload` → the field may be absent.
+  - The `required` flag is stored in the schema and is part of the event's **fingerprint**, so changing it changes the contract.
+
+### Reserved names
+
+Compilation rejects definitions that use names owned by the event envelope:
+
+- **Payload field names** may not be any of:
+  `event_name`, `event_type`, `event_version`, `occurred_at`, `created_at`, `updated_at`, `published_at`, `metadata`, `idempotency_key`, `attempts`, `dead_lettered_at`, `aggregate_type`, `aggregate_id`, `aggregate_version`.
+- **Input names** may not collide with the envelope keys:
+  `event_version`, `occurred_at`, `metadata`, `idempotency_key`, `aggregate_type`, `aggregate_id`, `aggregate_version`.
+
+A payload field must also have a `from:` that references a declared input, and each event name must be snake_case.
+
+### Inspecting the compiled schema
+
+Every definition compiles to a `Schema` value object:
+
+```ruby
+schema = LeadCreated.schema
+
+schema.event_name       # => :lead_created
+schema.required_inputs  # => [:lead]
+schema.fingerprint      # => "…sha256 of the event's structure…"
+schema.to_h             # => plain data hash (JSON-safe)
+schema.to_ruby          # => a Ruby source string that rebuilds the Schema
+```
+
+The fingerprint is a stable hash of the event's **structure** (name, type, inputs, payload fields) — incidental fields like `domain` don't change it, so a matching fingerprint means a matching contract.
+
+## How it fits with `event_engine`
+
+This gem defines and generates; `event_engine` runs. The seam between them is the **publisher port** (`EventEngine::Definition.publisher`):
+
+```
+this gem                                    event_engine (host runtime)
+────────────────────────────────           ──────────────────────────────
+EventDefinition DSL                          registers as the publisher
+        │ compile                            ────────────────────►
+        ▼                                    reads the raw inputs via the
+generated helper  ──publish(event)──►        schema's from:/attr: mapping,
++ committed schema.json                       then dispatches, persists, brokers…
+```
+
+A domain pack depends only on `event_engine-event_definition` to declare its events and build its helper file. In an app that also has `event_engine` installed, `event_engine` provides a real publisher adapter and assigns it to `EventEngine::Definition.publisher`, so calling a generated helper hands the event to the full runtime. Nothing in this gem knows how events are dispatched — that decision lives entirely in `event_engine`.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then:
+
+- `rake test` — run the test suite
+- `bin/console` — an interactive prompt with the gem loaded
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/docs/examples.md

@@ -0,0 +1,96 @@
+# EventEngine::Definition — examples
+
+Each example follows the same three beats: the **data** you already have, the **event** you define, and the **call** you make. For the full DSL reference and how this plugs into `event_engine`, see the [README](../README.md).
+
+The `SalesEvents` / `ProductEvents` modules below are the helpers produced by generating the pack — the `rake event_engine:definition:dump` build step in the README. These examples assume that step has already run, so they focus on defining the event and calling it.
+
+## An event built from multiple inputs
+
+You have an order and the customer who placed it — and maybe a coupon:
+
+```ruby
+order    = Order.create!(total_cents: 4_200)   # => #<Order id: 100, total_cents: 4200, …>
+customer = order.customer                       # => #<Customer id: 7, email: "ada@example.com", …>
+coupon   = Coupon.find_by(code: "WELCOME")     # optional — may be nil
+```
+
+Define an event that captures a consistent slice of each input:
+
+```ruby
+class OrderPlaced < EventEngine::EventDefinition
+  event_name :order_placed
+  event_type :domain
+  domain     :sales
+
+  input :order
+  input :customer
+  optional_input :coupon
+
+  required_payload :order_id,       from: :order,    attr: :id
+  required_payload :total_cents,    from: :order,    attr: :total_cents
+  required_payload :customer_id,    from: :customer, attr: :id
+  required_payload :customer_email, from: :customer, attr: :email
+  optional_payload :coupon_code,    from: :coupon,   attr: :code
+end
+```
+
+Emit it — pass each input; optional ones you can leave off:
+
+```ruby
+SalesEvents.order_placed(order: order, customer: customer, coupon: coupon)
+# or, with no coupon:
+SalesEvents.order_placed(order: order, customer: customer)
+```
+
+Captured:
+
+```ruby
+{
+  order_id:       100,
+  total_cents:    4200,
+  customer_id:    7,
+  customer_email: "ada@example.com",
+  coupon_code:    "WELCOME"
+}
+```
+
+## A lifecycle: one definition, an event per step
+
+You have a long-running job:
+
+```ruby
+export = Export.create!(format: "csv")   # => #<Export id: 9, format: "csv", …>
+```
+
+`LifecycleDefinition` stamps out one event per verb from a shared base, and `on` layers extra data onto a single step:
+
+```ruby
+class ExportCsv < EventEngine::LifecycleDefinition
+  subject    :export_csv
+  event_type :product
+
+  input :export
+  required_payload :format, from: :export, attr: :format
+
+  lifecycle :started, :completed, :failed
+
+  on :failed do
+    input :error
+    required_payload :error_class, from: :error, attr: :class
+  end
+end
+```
+
+That gives you three events — `export_csv_started`, `export_csv_completed`, and `export_csv_failed` — each carrying `format`, and the failed one also carrying `error_class`.
+
+Once the pack is generated, emit the step that happened:
+
+```ruby
+ProductEvents.export_csv_failed(export: export, error: some_error)
+```
+
+Captured:
+
+```ruby
+{ format: "csv", error_class: "Timeout::Error" }
+```

data/lib/event_engine/definition/configuration.rb

@@ -0,0 +1,14 @@
+require "event_engine/subject_registry"
+
+module EventEngine
+  module Definition
+    class Configuration
+      attr_accessor :definitions_path, :helper_path, :root_module
+      attr_writer :subject_registry
+
+      def subject_registry
+        @subject_registry ||= SubjectRegistry.new
+      end
+    end
+  end
+end

data/lib/event_engine/definition/null_publisher.rb

@@ -0,0 +1,13 @@
+module EventEngine
+  module Definition
+    class PublisherNotConfigured < Error; end
+
+    class NullPublisher
+      def publish(_event_name, **_envelope)
+        raise PublisherNotConfigured,
+              "No EventEngine::Definition.publisher configured. Wire a publisher " \
+              "adapter (e.g. event_engine) before emitting events."
+      end
+    end
+  end
+end

data/lib/event_engine/definition/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module EventEngine
+  module Definition
+    VERSION = "0.2.0"
+  end
+end

data/lib/event_engine/definition.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "definition/version"
+
+require "event_engine/subject_registry"
+require "event_engine/event_definition"
+require "event_engine/definition_loader"
+require "event_engine/event_schema"
+require "event_engine/schema_registry"
+require "event_engine/lifecycle_definition"
+require "event_engine/dsl_compiler"
+require "event_engine/definition/configuration"
+
+module EventEngine
+  module Definition
+    class Error < StandardError; end
+
+    class << self
+      attr_writer :publisher
+
+      def publisher
+        @publisher ||= NullPublisher.new
+      end
+
+      def reset_publisher!
+        @publisher = nil
+      end
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = nil
+      end
+    end
+  end
+end
+
+require "event_engine/definition/null_publisher"
+require "event_engine/event_engine_helpers_writer"
+require "event_engine/domain_pack_build"

data/lib/event_engine/definition_loader.rb

@@ -0,0 +1,23 @@
+require "event_engine/event_definition"
+require "event_engine/lifecycle_definition"
+
+module EventEngine
+  module DefinitionLoader
+    def self.load!(path)
+      before_events = EventEngine::EventDefinition.subclasses
+      before_lifecycles = EventEngine::LifecycleDefinition.subclasses
+      require_ruby_files(path)
+
+      declared_events = EventEngine::EventDefinition.subclasses - before_events
+      new_lifecycles = EventEngine::LifecycleDefinition.subclasses - before_lifecycles
+
+      declared_events + new_lifecycles.flat_map(&:generated_events)
+    end
+
+    def self.require_ruby_files(path)
+      Dir.glob(File.join(path, "**", "*.rb")).sort.each do |file|
+        require File.expand_path(file)
+      end
+    end
+  end
+end

data/lib/event_engine/domain_pack_build.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+require "event_engine/dsl_compiler"
+require "event_engine/subject_registry"
+require "event_engine/event_engine_helpers_writer"
+
+module EventEngine
+  class DomainPackBuild
+    PORT_EMIT = "EventEngine::Definition.publisher.publish"
+
+    SCHEMA_FILENAME = "schema.json"
+
+    HEADER = <<~RUBY.freeze
+      # This file is authoritative in production.
+      # It is generated from this pack's EventDefinitions.
+      # Do not edit manually.
+
+    RUBY
+
+    def self.run(definitions, helper_path:, root_module:, header: HEADER,
+                 subject_registry: SubjectRegistry.new)
+      new(
+        definitions,
+        helper_path: helper_path,
+        root_module: root_module,
+        header: header,
+        subject_registry: subject_registry
+      ).run
+    end
+
+    def initialize(definitions, helper_path:, root_module:, header:, subject_registry:)
+      @definitions = definitions
+      @helper_path = helper_path
+      @root_module = root_module
+      @header = header
+      @subject_registry = subject_registry
+    end
+
+    def run
+      event_schema = compile
+      write_helper(event_schema)
+      write_schema_json(event_schema)
+      self
+    end
+
+    def schema_path
+      File.join(File.dirname(@helper_path), SCHEMA_FILENAME)
+    end
+
+    private
+
+    def compile
+      DslCompiler.compile(@definitions, subject_registry: @subject_registry).event_schema
+    end
+
+    def write_schema_json(event_schema)
+      File.write(schema_path, JSON.pretty_generate(schemas(event_schema)))
+    end
+
+    def schemas(event_schema)
+      event_schema.schemas_by_event.values.flat_map(&:values).map(&:to_h)
+    end
+
+    def write_helper(event_schema)
+      EventEngineHelpersWriter.write(
+        @helper_path,
+        event_schema,
+        root_module: @root_module,
+        emit: PORT_EMIT,
+        header: @header,
+        group_by_domain: false,
+        schema_filename: SCHEMA_FILENAME
+      )
+    end
+  end
+end

data/lib/event_engine/dsl_compiler.rb

@@ -0,0 +1,79 @@
+module EventEngine
+  class DslCompiler
+    class InvalidEventNameError < StandardError; end
+    class ReservedInputNameError < StandardError; end
+
+    SNAKE_CASE = /\A[a-z][a-z0-9_]*\z/
+
+    RESERVED_INPUT_NAMES = %i[
+      event_version
+      occurred_at
+      metadata
+      idempotency_key
+      aggregate_type
+      aggregate_id
+      aggregate_version
+    ].freeze
+
+    def self.compile(definitions, subject_registry: SubjectRegistry.new)
+      registry = SchemaRegistry.new
+      subject_violations = []
+      name_violations = []
+      reserved_violations = []
+
+      Array(definitions).each do |definition|
+        schema = definition.schema
+        record_subject_violation(schema, subject_violations, subject_registry)
+        record_name_violation(schema, name_violations)
+        record_reserved_input_violation(schema, reserved_violations)
+        registry.register(schema)
+      end
+
+      raise_invalid_event_names(name_violations)
+      raise_reserved_input_names(reserved_violations)
+      raise_unknown_subjects(subject_violations)
+
+      registry
+    end
+
+    def self.record_name_violation(schema, violations)
+      return if schema.event_name.to_s.match?(SNAKE_CASE)
+
+      violations << schema.event_name.inspect
+    end
+
+    def self.raise_invalid_event_names(violations)
+      return if violations.empty?
+
+      raise InvalidEventNameError, "event names must be snake_case: #{violations.join(", ")}"
+    end
+
+    def self.record_reserved_input_violation(schema, violations)
+      inputs = schema.required_inputs + schema.optional_inputs
+      collisions = inputs & RESERVED_INPUT_NAMES
+      return if collisions.empty?
+
+      violations << "#{schema.event_name}: #{collisions.join(", ")}"
+    end
+
+    def self.raise_reserved_input_names(violations)
+      return if violations.empty?
+
+      raise ReservedInputNameError,
+            "input names collide with reserved envelope keys: #{violations.join("; ")}"
+    end
+
+    def self.record_subject_violation(schema, violations, subject_registry)
+      return if schema.subject.nil?
+      return if subject_registry.registered?(schema.subject)
+
+      violations << "#{schema.event_name}: unknown subject #{schema.subject.inspect}"
+    end
+
+    def self.raise_unknown_subjects(violations)
+      return if violations.empty?
+
+      raise SubjectRegistry::UnknownSubjectError, violations.join(", ")
+    end
+  end
+end

data/lib/event_engine/event_definition/inputs.rb

@@ -0,0 +1,31 @@
+module EventEngine
+  class EventDefinition
+    module Inputs
+      def self.included(base)
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        def input(name)
+          name = name.to_sym
+          if inputs.key?(name)
+            raise ArgumentError, "duplicate input: #{name}"
+          end
+          inputs[name] = :required
+        end
+
+        def optional_input(name)
+          name = name.to_sym
+          if inputs.key?(name)
+            raise ArgumentError, "duplicate input: #{name}"
+          end
+          inputs[name] = :optional
+        end
+
+        def inputs
+          @inputs ||= {}
+        end
+      end
+    end
+  end
+end