# Golang

> GraphStructManager Go 1.25 + Gremlin guidelines Use when this capability is needed.

- Skill: `tomevault-io/golang-14` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/golang-14`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/golang-14/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/golang-14

---


# Overview

You are maintaining GraphStructManager, a type-safe, chainable Gremlin query builder for Go.
Prioritize correctness, predictable API behavior, and clear mapping between Go structs and
Gremlin traversals.

## Inspiration

- The API is inspired by GORM, but adapted for graph databases and Gremlin traversals rather
  than SQL.

## Repository Context

- Go version: 1.25 (module `github.com/jbrusegaard/graph-struct-manager`)
- Gremlin: Apache TinkerPop `gremlin-go` v3.7.4
- Core packages: `gremlin/driver`, `gsmtypes`, `comparator`, `log`
- Public surface: generic query builder (`Query[T gsmtypes.VertexType]`) and helper APIs

## Graph Model Conventions

- Vertex structs must embed `gsmtypes.Vertex` anonymously; `Create`/`Update` validate this.
- Edge structs (when used) embed `gsmtypes.Edge` and implement `gsmtypes.EdgeType`.
- Use `gremlin:"field_name"` tags for properties; `gremlin:"field_name,omitempty"` skips
  zero values and nil pointers during create/update.
- Use `gremlinSubTraversal:"alias"` for subtraversal projections; the alias must match
  `AddSubTraversal` usage.
- Label resolution: `Label() string` wins; empty label defaults to snake_case struct name.

## Query Builder Design

- Keep methods chainable and consistent with existing behavior (mutate query, return `*Query[T]`).
- Use `comparator` constants for predicates; map them to Gremlin `P`/`TextP` consistently.
- Preserve debug string building and `GSM_DEBUG` behavior when adding query steps.
- `Range` is ignored when `Offset` is set; maintain this behavior and warnings.
- `Take()` returns the first result; `ID()` performs fast ID lookup using `HasLabel`.

## Struct Mapping and Tags

- `structToMap` drives create/update; it ignores `gremlinSubTraversal` tags.
- `UnloadGremlinResultIntoStruct` maps Gremlin results to tagged fields, including anonymous
  embedded structs and subtraversal aliases.
- When changing mapping rules, update tests under `gremlin/driver/*_test.go`.

## Logging and Diagnostics

- Logging uses `log.InitializeLogger()` and `GSM_LOG_LEVEL`.
- Query debugging uses `GSM_DEBUG=true` to emit generated traversal strings.

## Error Handling

- Return explicit errors; wrap with context (`fmt.Errorf("context: %w", err)`).
- Avoid panics and hidden behavior changes; align error messages with existing usage.

## Testing and Docs

- Prefer table-driven tests and cover exported behavior.
- If you change public API or query semantics, update `README.md` examples to match.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jbrusegaard) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->