events/api.go at main · goforj/events · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
package events

import (
	"context"

	"github.com/goforj/events/eventscore"
)

// API is the root application-facing bus contract.
// @group Core
//
// Example: keep an API-typed bus reference
//
//	api, _ := events.NewSync()
//	var bus events.API = api
//	fmt.Println(bus.Driver())
//	// Output: sync
type API interface {
	// Driver reports the active bus backend.
	// @group Core
	//
	// Example: inspect the active backend through the interface
	//
	//	api, _ := events.NewSync()
	//	var bus events.API = api
	//	fmt.Println(bus.Driver())
	//	// Output: sync
	Driver() eventscore.Driver
	// Ready performs a background-context readiness check.
	// @group Core
	//
	// Example: check readiness through the interface
	//
	//	api, _ := events.NewSync()
	//	var bus events.API = api
	//	fmt.Println(bus.Ready() == nil)
	//	// Output: true
	Ready() error
	// ReadyContext performs a readiness check with the provided context.
	// @group Core
	//
	// Example: check readiness with a caller context
	//
	//	api, _ := events.NewSync()
	//	var bus events.API = api
	//	fmt.Println(bus.ReadyContext(context.Background()) == nil)
	//	// Output: true
	ReadyContext(ctx context.Context) error
	// Publish dispatches an event with the background context.
	// @group Core
	//
	// Example: publish a typed event through the interface
	//
	//	type UserCreated struct {
	//		ID string `json:"id"`
	//	}
	//
	//	api, _ := events.NewSync()
	//	var bus events.API = api
	//	_, _ = bus.Subscribe(func(event UserCreated) {
	//		fmt.Println(event.ID)
	//	})
	//	_ = bus.Publish(UserCreated{ID: "123"})
	//	// Output: 123
	Publish(event any) error
	// PublishContext dispatches an event with the provided context.
	// @group Core
	//
	// Example: publish with a caller context
	//
	//	type UserCreated struct {
	//		ID string `json:"id"`
	//	}
	//
	//	api, _ := events.NewSync()
	//	var bus events.API = api
	//	_, _ = bus.Subscribe(func(ctx context.Context, event UserCreated) error {
	//		fmt.Println(event.ID, ctx != nil)
	//		return nil
	//	})
	//	_ = bus.PublishContext(context.Background(), UserCreated{ID: "123"})
	//	// Output: 123 true
	PublishContext(ctx context.Context, event any) error
	// Subscribe registers a typed handler using the background context.
	// @group Core
	//
	// Example: subscribe through the interface
	//
	//	type UserCreated struct {
	//		ID string `json:"id"`
	//	}
	//
	//	api, _ := events.NewSync()
	//	var bus events.API = api
	//	sub, _ := bus.Subscribe(func(ctx context.Context, event UserCreated) error {
	//		_ = ctx
	//		_ = event
	//		return nil
	//	})
	//	defer sub.Close()
	Subscribe(handler any) (Subscription, error)
	// SubscribeContext registers a typed handler with the provided context.
	// @group Core
	//
	// Example: subscribe with a caller context through the interface
	//
	//	type UserCreated struct {
	//		ID string `json:"id"`
	//	}
	//
	//	api, _ := events.NewSync()
	//	var bus events.API = api
	//	sub, _ := bus.SubscribeContext(context.Background(), func(ctx context.Context, event UserCreated) error {
	//		_ = ctx
	//		_ = event
	//		return nil
	//	})
	//	defer sub.Close()
	SubscribeContext(ctx context.Context, handler any) (Subscription, error)
}

// Subscription releases a subscription when closed.
// @group Subscribe
//
// Example: unsubscribe from a typed event
//
//	type UserCreated struct {
//		ID string `json:"id"`
//	}
//
//	bus, _ := events.NewSync()
//	sub, _ := bus.Subscribe(func(event UserCreated) {
//		fmt.Println("received", event.ID)
//	})
//	_ = bus.Publish(UserCreated{ID: "123"})
//	_ = sub.Close()
//	_ = bus.Publish(UserCreated{ID: "456"})
//	// Output: received 123
type Subscription = eventscore.Subscription