resourceeventbus

resource-eventbus

A minimal, type-safe in-process pub/sub for Go. Built on top of asaskevich/EventBus. Two usage modes:

• Lightweight — declare TypedEvent[T] inline, no codegen.
• Full DSL + codegen — write a DSL, run eventbus-gen, get a generated events package with metadata-aware Publish(data, opts...).

Both modes share the same underlying Bus interface, so they interoperate.

Install

# library
go get github.com/NameOfGoy/resource-eventbus

# generator CLI (only if you want codegen)
go install github.com/NameOfGoy/resource-eventbus/cmd/eventbus-gen@latest

Requires Go 1.23+ (generics + any alias).

Mode 1: Lightweight (no codegen)

Declare an event once, reuse it everywhere with full type safety:

package events

import resbus "github.com/NameOfGoy/resource-eventbus"

type UserCreated struct {
    ID   uint
    Name string
}

var UserCreatedEvent = &resbus.TypedEvent[UserCreated]{Topic: "user.created"}

// publisher
events.UserCreatedEvent.PublishAsync(events.UserCreated{ID: 1, Name: "alice"})

// subscriber (registered once at startup)
err := events.UserCreatedEvent.SubscribeAsync(func(u events.UserCreated) {
    // handle...
}, false)

SubscribeAsync(handler, transactional):

• transactional=false — handler can run concurrently with others on the same topic.
• transactional=true — handlers on this topic are serialized.

Mode 2: DSL + codegen

Write a dsl.go declaring an EventsDSL() function (see _examples/dsl.go):

package events

import (
    "github.com/NameOfGoy/resource-eventbus/generator"
    "your-project/models"
)

func EventsDSL() []generator.ResourceDef {
    return []generator.ResourceDef{
        {
            Resource: "device",
            Operations: []generator.OpDef{
                {Op: "created", Struct: models.Device{}},
                {Op: "updated", Struct: models.Device{}},
                {Op: "status_changed", Struct: models.DeviceStatus{}},
            },
        },
        {
            Resource: "alarm",
            Operations: []generator.OpDef{
                {Op: "triggered", Struct: models.Alarm{}},
                {Op: "resolved",  Struct: models.Alarm{}},
            },
        },
    }
}

Run the generator:

eventbus-gen -dsl=./events/dsl.go
# emits events/events.go (topic constants) + events/typed.go (TypedEvent[T] + factories)

Use the generated API (note: this TypedEvent[T] carries metadata):

import (
    "your-project/events"
    "your-project/models"
    "github.com/NameOfGoy/resource-eventbus/generator"
)

// publish, with metadata via functional options
events.Device().Created().Publish(
    models.Device{ID: "d-1", Name: "rack-a-cell-3"},
    generator.WithSource("device-service"),
    generator.WithTraceID("trace-abc"),
)

// async publish (returns immediately)
events.Device().Updated().PublishAsync(models.Device{ID: "d-1", Name: "renamed"})

// subscribe, handler also receives metadata
events.Device().Created().SubscribeAsync(
    func(d models.Device, meta *generator.EventMetadata) {
        fmt.Printf("[%s] from=%s id=%s\n", meta.TraceID, meta.Source, d.ID)
    },
    false,
)

CLI flags:

eventbus-gen -dsl=./events/dsl.go            # generate
eventbus-gen -dsl=./events/dsl.go -verbose   # show DSL info + stats
eventbus-gen -dsl=./events/dsl.go -dry-run   # stats only, no files written

Naming conventions:

• DSL: snake_case (device_cell, status_changed)
• Generated: UpperCamelCase (DeviceCellStatusChanged = "device_cell.status_changed")

Conflict handling: if a resource's UpperCamel name matches a struct already defined in the DSL file's package, the factory function is renamed ResourceFoo() instead of Foo() to avoid shadowing the struct.

Add the generated files to .gitignore:

events/events.go
events/typed.go

Testing

Replace the singleton bus per test for isolation:

import (
    resbus "github.com/NameOfGoy/resource-eventbus"
    asaskbus "github.com/asaskevich/EventBus"
)

func TestMyHandler(t *testing.T) {
    resbus.SetBus(asaskbus.New())
    // ... your test ...
}

Why this exists

Most projects end up either:

• Reaching for a heavyweight message broker for in-process work.
• Hand-rolling chan + sync.Map and getting subscription lifecycle wrong.

resource-eventbus stays small: one Bus interface, one generic TypedEvent[T], plus an optional DSL/codegen flow for teams that want metadata-rich events without writing the boilerplate by hand.

License

MIT — see LICENSE.