Skip to content

Quick Start

Logo

Welcome to it-happened, a Go library that simplifies event-driven application development. This guide will get you up and running with basic event publishing and subscription in just a few minutes.

Prerequisites

  • Go 1.25 or higher
  • Basic familiarity with Go syntax

Installation

go get github.com/thomas-marquis/it-happened

Your First Event

Let's create a simple application that publishes and receives events.

Step 1: Define Your Event Payload

First, create a payload type that implements the event.Payload interface:

package main

import (
    "fmt"
    "github.com/thomas-marquis/it-happened/event"
    "github.com/thomas-marquis/it-happened/inmemory"
)

type MyEventPayload struct {
    Message string
}

func (p MyEventPayload) EventType() event.Type {
    return "my.event"
}

Step 2: Create the Event Bus

Initialize an in-memory event bus:

func main() {
    // Create a done channel to control bus lifetime
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    // Create the bus with the done channel
    bus := inmemory.NewBus(ctx)

Step 3: Subscribe to Events

Create a subscriber that listens for your event type:

    // Create a subscriber
    sub := bus.Subscribe()

    // Register a callback for your event type
    sub.On(event.Is("my.event"), func(e event.Event) {
        // Extract the payload
        if payload, ok := e.Payload().(MyEventPayload); ok {
            fmt.Printf("Received event: %s\n", payload.Message)
        }
    })

    // Start listening with 1 worker
    sub.ListenWithWorkers(1)

Step 4: Publish an Event

Publish your event to the bus:

    // Create and publish an event
    evt := event.New(MyEventPayload{Message: "Hello, World!"})
    bus.Publish(evt)

    // Wait a moment for the event to be processed
    // In a real application, you would use proper synchronization
}

Complete Example

Here's the complete code in one place:

package main

import (
    "fmt"
    "time"
    "github.com/thomas-marquis/it-happened/event"
    "github.com/thomas-marquis/it-happened/inmemory"
)

type MyEventPayload struct {
    Message string
}

func (p MyEventPayload) EventType() event.Type {
    return "my.event"
}

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    bus := inmemory.NewBus(ctx)

    sub := bus.Subscribe()
    sub.On(event.Is("my.event"), func(e event.Event) {
        if payload, ok := e.Payload().(MyEventPayload); ok {
            fmt.Printf("Received: %s\n", payload.Message)
        }
    })
    sub.ListenWithWorkers(1)

    evt := event.New(MyEventPayload{Message: "Hello, World!"})
    bus.Publish(evt)

    // Wait for event processing
    time.Sleep(100 * time.Millisecond)
}

Run It

Save the code to a file (e.g., main.go) and run:

go run main.go

You should see output similar to:

Received: Hello, World!

Next Steps

Now that you have the basics working, explore these next:

  1. Concepts - Understand the core library abstractions
  2. Tutorials - Practical examples for common use cases
  3. References - API documentation

Need Help?