Documentation
¶
Overview ¶
Package progression tracks an accumulating scalar (XP, points, score) against a tiered Curve and emits threshold-crossing events when the subject moves into a new tier.
Domain-agnostic; common applications:
- Game character XP / level systems.
- User reputation / karma tiers in apps.
- Loyalty / fee tiers in commerce or finance.
- Gamified onboarding (% complete → milestone band).
The package ships an in-memory Store; consumers needing durability supply a Postgres or Redis implementation of the same interface.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Curve ¶
Curve maps a cumulative total to a tier (level / band / rank) and returns the threshold at which the next tier is reached. Implementations must be monotone — LevelFor must never decrease as total grows.
type InMemoryStore ¶
type InMemoryStore struct {
// contains filtered or unexported fields
}
InMemoryStore is a concurrent-safe Store backed by a map. For tests and ephemeral use only.
func NewInMemoryStore ¶
func NewInMemoryStore() *InMemoryStore
type Linear ¶
type Linear struct {
Step int64
}
Linear curve: each tier requires `Step` more total than the previous. LevelFor(2*Step) == 2, NextThreshold(2) == 3*Step, etc.
func (Linear) NextThreshold ¶
type Steps ¶
type Steps struct {
Thresholds []int64
}
Steps curve: explicit cumulative thresholds. Index i represents the minimum cumulative total to be at level i. Element 0 is implicitly 0 (a fresh subject starts at level 0).
func (Steps) NextThreshold ¶
type Store ¶
type Store interface {
Total(ctx context.Context, subject SubjectID) (int64, error)
// Add atomically adds amount and returns (before, after).
Add(ctx context.Context, subject SubjectID, amount int64) (before, after int64, err error)
}
Store persists per-subject cumulative totals.
type SubjectID ¶
type SubjectID string
SubjectID is whatever the consumer treats as the bearer of progress.
type Tracker ¶
type Tracker struct {
// contains filtered or unexported fields
}
Tracker combines a Curve and a Store to award amounts and emit threshold-crossing events.
func NewTracker ¶
NewTracker constructs a Tracker.
func (*Tracker) Award ¶
func (t *Tracker) Award(ctx context.Context, subject SubjectID, amount int64, reason string) (*Crossed, error)
Award adds amount to subject's total. If the tier increases, returns a Crossed describing the transition; otherwise the Crossed pointer is nil. Reason is opaque metadata the caller passes through to the event.
Source Files