Add support for UnmarshalMaxMinDB

Author: oschwald

CHANGELOG.md

@@ -6,6 +6,13 @@
 - `IncludeNetworksWithoutData` and `IncludeAliasedNetworks` now return a
   `NetworksOption` rather than being one themselves. This was done to improve
   the documentation organization.
+- Added `Unmarshaler` interface to allow custom decoding implementations for
+  performance-critical applications. Types implementing
+  `UnmarshalMaxMindDB(d *Decoder) error` will automatically use custom
+  decoding logic instead of reflection, following the same pattern as
+  `json.Unmarshaler`.
+- Added public `Decoder` type with methods for manual decoding including
+  `DecodeMap()`, `DecodeSlice()`, `DecodeString()`, `DecodeUInt32()`, etc.
 
 ## 2.0.0-beta.3 - 2025-02-16
 

decoder.go

@@ -0,0 +1,47 @@
+package maxminddb
+
+import "github.com/oschwald/maxminddb-golang/v2/internal/decoder"
+
+// Decoder provides methods for decoding MaxMind DB data values.
+// This interface is passed to UnmarshalMaxMindDB methods to allow
+// custom decoding logic that avoids reflection for performance-critical applications.
+//
+// Types implementing Unmarshaler will automatically use custom decoding logic
+// instead of reflection when used with Reader.Lookup, providing better performance
+// for performance-critical applications.
+//
+// Example:
+//
+//	type City struct {
+//		Names     map[string]string `maxminddb:"names"`
+//		GeoNameID uint              `maxminddb:"geoname_id"`
+//	}
+//
+//	func (c *City) UnmarshalMaxMindDB(d *maxminddb.Decoder) error {
+//		for key, err := range d.DecodeMap() {
+//			if err != nil { return err }
+//			switch string(key) {
+//			case "names":
+//				names := make(map[string]string)
+//				for nameKey, nameErr := range d.DecodeMap() {
+//					if nameErr != nil { return nameErr }
+//					value, valueErr := d.DecodeString()
+//					if valueErr != nil { return valueErr }
+//					names[string(nameKey)] = value
+//				}
+//				c.Names = names
+//			case "geoname_id":
+//				geoID, err := d.DecodeUInt32()
+//				if err != nil { return err }
+//				c.GeoNameID = uint(geoID)
+//			default:
+//				if err := d.SkipValue(); err != nil { return err }
+//			}
+//		}
+//		return nil
+//	}
+type Decoder = decoder.Decoder
+
+// Unmarshaler is implemented by types that can unmarshal MaxMind DB data.
+// This follows the same pattern as json.Unmarshaler and other Go standard library interfaces.
+type Unmarshaler = decoder.Unmarshaler

internal/decoder/decoder.go

@@ -382,3 +382,16 @@ func (d *Decoder) DecodeSlice() iter.Seq[error] {
 		d.reset(currentOffset)
 	}
 }
+
+// SkipValue skips over the current value without decoding it.
+// This is useful in custom decoders when encountering unknown fields.
+// The decoder will be positioned after the skipped value.
+func (d *Decoder) SkipValue() error {
+	// We can reuse the existing nextValueOffset logic by jumping to the next value
+	nextOffset, err := d.d.nextValueOffset(d.offset, 1)
+	if err != nil {
+		return err
+	}
+	d.reset(nextOffset)
+	return nil
+}