Lazy deserialization — deserialize event payload on demand #55

New issue

Closed

opened 2026-02-21 22:42:29 +00:00 by ash · 0 comments

ash commented

2026-02-21 22:42:29 +00:00

Owner

Problem

Every loaded event is fully deserialized immediately, even if the handler skips it. Combined with type filtering (#54), this doubles down on wasted work.

Proposal

Return a lazy envelope with metadata available immediately (type, stream, version, timestamp). The Data field is only deserialized when .Data() is called.

type LazyEvent[E any] struct {
    ID, StreamID, EventType string
    Version                 int
    GlobalSequence          uint64
    Timestamp               time.Time
    Metadata                Metadata
    rawBytes                []byte
    resolved                *E
    resolver                func([]byte) (E, error)
}

func (e *LazyEvent[E]) Data() (E, error) {
    if e.resolved != nil { return *e.resolved, nil }
    v, err := e.resolver(e.rawBytes)
    if err != nil { return v, err }
    e.resolved = &v
    return v, nil
}

Benchmark Target

Load 1000 events, handler accesses only 100
Measure allocs saved from skipping 900 deserializations
Compare eager vs lazy path

Considerations

This changes the Event type or adds a parallel type — needs careful API design
Could be opt-in via LoadLazy() vs Load()
Works with both standard ES and DCB

## Problem Every loaded event is fully deserialized immediately, even if the handler skips it. Combined with type filtering (#54), this doubles down on wasted work. ## Proposal Return a lazy envelope with metadata available immediately (type, stream, version, timestamp). The `Data` field is only deserialized when `.Data()` is called. ```go type LazyEvent[E any] struct { ID, StreamID, EventType string Version int GlobalSequence uint64 Timestamp time.Time Metadata Metadata rawBytes []byte resolved *E resolver func([]byte) (E, error) } func (e *LazyEvent[E]) Data() (E, error) { if e.resolved != nil { return *e.resolved, nil } v, err := e.resolver(e.rawBytes) if err != nil { return v, err } e.resolved = &v return v, nil } ``` ## Benchmark Target - Load 1000 events, handler accesses only 100 - Measure allocs saved from skipping 900 deserializations - Compare eager vs lazy path ## Considerations - This changes the Event type or adds a parallel type — needs careful API design - Could be opt-in via `LoadLazy()` vs `Load()` - Works with both standard ES and DCB