introspection/doc.go at main · aretw0/introspection · 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
/*
Package introspection provides a domain-agnostic observation layer for Go applications.
It enables components to expose their internal state for visualization, monitoring, and debugging
without coupling to specific domain concepts.

# Core Concepts

The library is built around three pillars:

 1. State Exposure:
    Components implement simple interfaces to expose their state without domain-specific terminology.

    type Introspectable interface {
        State() any
    }

    type Component interface {
        ComponentType() string
    }

 2. Type-Safe Watching:
    Components can publish state changes through type-safe channels using Go generics.

    type TypedWatcher[S any] interface {
        State() S
        Watch(ctx context.Context) <-chan StateChange[S]
    }

 3. Automatic Visualization:
    Generate Mermaid diagrams from component state with full customization.

    config := &DiagramConfig{
        SecondaryID: "components",
    }
    diagram := TreeDiagram(state, config)

# Key Interfaces

The package defines minimal interfaces for maximum flexibility:

  - Introspectable: Exposes component state
  - Component: Identifies component type
  - TypedWatcher[S]: Type-safe state change notifications
  - EventSource: Event-based notifications

# Visualization

The package includes powerful Mermaid diagram generation:

  - TreeDiagram: Hierarchical component structures
  - ComponentDiagram: Relationships between component types
  - StateMachineDiagram: Component lifecycle and transitions

All visualization is fully customizable through configuration:

	config := &DiagramConfig{
		PrimaryID:        "scheduler",
		PrimaryLabel:     "Task Scheduler",
		PrimaryNodeLabel: "🗓️ Scheduler",
		SecondaryID:      "tasks",
		SecondaryLabel:   "Active Tasks",
		ConnectionLabel:  "schedules",
	}

# State Aggregation

Combine state changes from multiple components:

	watchers := []TypedWatcher[MyState]{component1, component2, component3}
	snapshots := AggregateWatchers(ctx, watchers...)
	for snapshot := range snapshots {
		// Process state changes
	}

# Design Philosophy

The package emphasizes:

  - Domain Agnostic: No hardcoded terminology - you define your domain
  - Type Safety: Leverage Go generics for compile-time safety
  - Composability: Small, focused interfaces that compose well
  - Zero Dependencies: Standard library only
  - Backward Compatible: Legacy APIs remain available

# Examples

See the examples directory for complete working examples:

  - examples/basic: Legacy worker/signal domain
  - examples/generic: Domain-agnostic task scheduler

# Documentation

For detailed documentation:

  - docs/TECHNICAL.md: Architecture and design
  - docs/PRODUCT.md: Vision and use cases
  - docs/DECISIONS.md: Design rationale
  - docs/CONFIGURATION.md: Configuration philosophy
  - docs/RECIPES.md: Common usage patterns
*/
package introspection