Project Information

Documentation

Official package documentation, guides, examples, and integration tutorials are available at:

• https://netlife.guru/docs/go/mapper

API reference is available on pkg.go.dev:

• https://pkg.go.dev/github.com/netlifeguru/mapper

Source code and issue tracking:

• https://github.com/netlifeguru/mapper

Practical examples are available in the official examples repository:

• https://github.com/netlifeguru/examples/mapper

---

Design Goals

The mapper package is designed around a few core principles:

• Simple and predictable row-to-struct mapping
• Database-agnostic scanning through a small Rows interface
• Mapping by column name instead of scan position
• Native support for db tags, json tags, and snake_case field names
• Support for structs, maps, custom row handlers, pointers, nullable values, and JSON fields
• Minimal dependencies and straightforward integration with existing Go database code
• Efficient repeated scanning through cached struct metadata and scan plans
• Clear error handling for empty results, duplicate rows, and unsupported assignments

Mapper is intentionally small and focused.

It does not manage database connections, transactions, migrations, schemas, or query building. Those responsibilities belong to database drivers or higher-level packages such as github.com/netlifeguru/db.

---

Performance

The mapper package is designed to keep repeated row scanning efficient.

It uses internal caches for struct metadata and scan plans so that repeated scans of the same result shape do not need to rebuild field mappings from scratch.

Performance-oriented behavior includes:

• cached struct field metadata
• cached scan plans for repeated column layouts
• optional named cache keys for hot paths
• workspace reuse for row scanning
• direct scanning for simple Go field types where possible
• assignment helpers for more complex values such as pointers, nullable structs, slices, maps, and JSON fields

Actual performance depends on:

• the database driver
• the number of returned rows
• the number of returned columns
• the target struct shape
• whether values can be scanned directly
• whether type conversion or JSON decoding is required
• whether named cache keys are used for repeated query shapes

For most applications, the default scanning functions are sufficient.

Use named cache keys only for stable, frequently repeated query shapes where scan-plan reuse is beneficial.

---

Versioning

This project follows Semantic Versioning.

See CHANGELOG.md for release history, version updates, and breaking changes.

---

Contributing

Community contributions, discussions, bug reports, and pull requests are welcome.

Please read CONTRIBUTING.md before submitting pull requests or opening issues.

---

Code of Conduct

This project follows the Contributor Covenant Code of Conduct.

Please read CODE_OF_CONDUCT.md before participating in discussions or contributing to the project.

---

Author

Created and maintained by NetLife Guru s.r.o.

Resources:

• Documentation: https://netlife.guru/docs
• GitHub: https://github.com/netlifeguru
• Contact: info@netlife.guru

---

License

This project is licensed under the MIT License.

See LICENSE for full license information.