Documentation
¶
Overview ¶
Package convert maps values across an API boundary: EnumMapper pairs a proto enum with a domain enum from one table, ParseUUID parses a request id as invalid input when malformed, and Int32OrPanic / CountToInt32 narrow counts to a proto int32.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CountToInt32 ¶
CountToInt32 clamps a non-negative count into the int32 range used by proto count fields. Unlike Int32OrPanic it NEVER panics — it is the policy for counts that can legitimately be large (document/word/page/passage counts, unread-item counts), where clamping to MaxInt32 degrades a displayed number rather than crashing the request. A negative count clamps to 0.
func Int32OrPanic ¶
Int32OrPanic converts a signed integer to int32 for proto count/index fields whose value is invariant-guaranteed to fit int32 (e.g. a per-tenant count, a chunk index). It PANICS if the value is out of range — a deliberate loud failure for a "cannot happen" invariant, never a silent truncation that would corrupt a displayed count/index and mask the upstream bug.
⚠️ This is NOT interchangeable with CountToInt32. Use Int32OrPanic only when the value cannot legitimately exceed int32; for counts that CAN be large (document/word/page counts), use CountToInt32, which clamps instead of crashing. It is generic so both int and int64 callers share it.
Types ¶
type EnumMapper ¶
type EnumMapper[P comparable, D comparable] struct { // contains filtered or unexported fields }
EnumMapper bidirectionally maps a proto enum P to a domain enum D from a single forward table, so a value's proto↔domain correspondence is declared once instead of being re-encoded in a to-domain switch, a to-proto switch, and a filter switch. The reverse (domain→proto) table is derived at construction. It serves the three conversion shapes the RPC converters need:
- ToDomainOrError — validating: a proto value absent from the table is rejected as InvalidInput (used where the proto has no valid unspecified peer, or where an explicit unspecified→domain mapping is a table entry).
- ToProtoValue — total: a domain value absent from the reverse table maps to the protoZero fallback (the proto UNSPECIFIED value).
- ToDomainFilter — filter: the protoZero (unspecified) value means "no filter" and returns ok=false; any other known value maps through.
P and D are the proto and domain enum types (both comparable — proto enums are int32-based, domain enums string-based here).
func NewEnumMapper ¶
func NewEnumMapper[P, D comparable]( label string, protoZero P, domainZero D, toDomain map[P]D, ) EnumMapper[P, D]
NewEnumMapper builds a mapper from the forward (proto→domain) table, deriving the reverse table. protoZero is the proto UNSPECIFIED value and domainZero is the domain value the validating conversion returns on an unknown proto value.
It panics if two proto values map to the same domain value: the derived reverse (domain→proto) table requires unique domain values, and a collision would make ToProtoValue a silent last-writer-wins under Go's randomized map iteration. The mappers are constructed at package init, so a violation fails loudly at startup.
func (EnumMapper[P, D]) ToDomainEntries ¶
func (m EnumMapper[P, D]) ToDomainEntries() map[P]D
ToDomainEntries returns the forward (proto→domain) table for derived projections (e.g. building a filter-token→value map from the same source of truth). The returned map is the mapper's own table — read-only; callers must not mutate it.
func (EnumMapper[P, D]) ToDomainFilter ¶
func (m EnumMapper[P, D]) ToDomainFilter(p P) (D, bool)
ToDomainFilter maps a proto value into a domain value for filtering: the unspecified (protoZero) value means "no filter" and returns ok=false, as does any value absent from the table. The zero domain value is returned when ok is false.
func (EnumMapper[P, D]) ToDomainOK ¶
func (m EnumMapper[P, D]) ToDomainOK(p P) (D, bool)
ToDomainOK returns the mapped domain value and whether the proto value was present in the table, without allocating an error — for callers that reject an unknown value with their own message rather than the mapper's generic one.
func (EnumMapper[P, D]) ToDomainOrError ¶
func (m EnumMapper[P, D]) ToDomainOrError(p P) (D, error)
ToDomainOrError returns the mapped domain value, or (domainZero, InvalidInput) for a proto value absent from the table.
func (EnumMapper[P, D]) ToProtoValue ¶
func (m EnumMapper[P, D]) ToProtoValue(d D) P
ToProtoValue returns the mapped proto value, or protoZero for a domain value absent from the reverse table.
Source Files