Refactored repository structure.

This commit is contained in:
Jay
2026-03-03 13:34:10 -05:00
parent 96f1ceb362
commit e9e153c9a1
15 changed files with 159 additions and 144 deletions

374
graph/graph.go Normal file
View File

@@ -0,0 +1,374 @@
// This module defines types and functions for working with Neo4j graph
// entities.
package graph
import (
"fmt"
"sort"
"strings"
)
// ========================================
// Types
// ========================================
// Properties represents a map of node or relationship props.
type Properties map[string]any
// ========================================
// Match Key Provider
// ========================================
// MatchKeysProvider defines methods for querying a mapping of node labels and
// the property keys used to match nodes with them.
type MatchKeysProvider interface {
// GetLabels returns the array of node labels in the mapping.
GetLabels() []string
// GetKeys returns the node property keys used to match nodes with the
// given label and a boolean indicating the success of the lookup.
GetKeys(label string) ([]string, bool)
}
// MatchKeys is a simple implementation of the MatchKeysProvider interface.
type MatchKeys struct {
Keys map[string][]string
}
func (p *MatchKeys) GetLabels() []string {
labels := []string{}
for l := range p.Keys {
labels = append(labels, l)
}
return labels
}
func (p *MatchKeys) GetKeys(label string) ([]string, bool) {
if keys, exists := p.Keys[label]; exists {
return keys, exists
} else {
return nil, exists
}
}
// ========================================
// Nodes
// ========================================
// Node represents a Neo4j node entity, encapsulating its labels and
// properties.
type Node struct {
// Set of labels on the node.
Labels Set[string]
// Mapping of properties on the node.
Props Properties
}
// NewNode creates a new node with the given label and properties.
func NewNode(label string, props Properties) *Node {
if props == nil {
props = make(Properties)
}
return &Node{
Labels: NewSet(label),
Props: props,
}
}
// MatchProps returns the node label and the property values to match it in the
// database.
func (n *Node) MatchProps(
matchProvider MatchKeysProvider) (string, Properties, error) {
// Iterate over each label on the node, checking whether each has match
// keys associated with it.
labels := n.Labels.ToArray()
sort.Strings(labels)
for _, label := range labels {
if keys, exists := matchProvider.GetKeys(label); exists {
props := make(Properties)
// Get the property values associated with each match key.
for _, key := range keys {
if value, exists := n.Props[key]; exists {
props[key] = value
} else {
// If any match property values are missing, return an
// error.
return label, nil,
fmt.Errorf(
"missing property %s for label %s", key, label)
}
}
// Return the label and match properties
return label, props, nil
}
}
// If none of the node labels have defined match keys, return an error.
return "", nil, fmt.Errorf("no recognized label found in %v", n.Labels)
}
type SerializedNode = Properties
func (n *Node) Serialize() *SerializedNode {
return &n.Props
}
// ========================================
// Relationships
// ========================================
// Relationship represents a Neo4j relationship between two nodes, including
// its type and properties.
type Relationship struct {
// The relationship type.
Type string
// The start node for the relationship.
Start *Node
// The end node for the relationship.
End *Node
// Mapping of properties on the relationship
Props Properties
}
// NewRelationship creates a new relationship with the given type, start node,
// end node, and properties
func NewRelationship(
rtype string, start *Node, end *Node, props Properties) *Relationship {
if props == nil {
props = make(Properties)
}
return &Relationship{
Type: rtype,
Start: start,
End: end,
Props: props,
}
}
type SerializedRel = map[string]Properties
func (r *Relationship) Serialize() *SerializedRel {
srel := make(map[string]Properties)
srel["props"] = r.Props
srel["start"] = r.Start.Props
srel["end"] = r.End.Props
return &srel
}
// ========================================
// Simple Subgraph
// ========================================
// Subgraph represents a simple collection of nodes and relationships.
type Subgraph struct {
// The nodes in the subgraph.
nodes []*Node
// The relationships in the subgraph.
rels []*Relationship
}
// NewSubgraph creates an empty subgraph.
func NewSubgraph() *Subgraph {
return &Subgraph{
nodes: []*Node{},
rels: []*Relationship{},
}
}
// AddNode adds a node to the subgraph
func (s *Subgraph) AddNode(node *Node) {
s.nodes = append(s.nodes, node)
}
// AddRel adds a relationship to the subgraph.
func (s *Subgraph) AddRel(rel *Relationship) {
s.rels = append(s.rels, rel)
}
func (s *Subgraph) Nodes() []*Node {
return s.nodes
}
func (s *Subgraph) Rels() []*Relationship {
return s.rels
}
func (s *Subgraph) NodesByLabel(label string) []*Node {
nodes := []*Node{}
for _, node := range s.nodes {
if node.Labels.Contains(label) {
nodes = append(nodes, node)
}
}
return nodes
}
// ========================================
// Structured Subgraph
// ========================================
// StructuredSubgraph is a structured collection of nodes and relationships for
// the purpose of conducting batch operations.
type StructuredSubgraph struct {
// A map of grouped nodes, sorted by their label combinations.
nodes map[string][]*Node
// A map of grouped relationships, sorted by their type and related node
// labels.
rels map[string][]*Relationship
// Provides node property keys used to match nodes with given labels in the
// database.
matchProvider MatchKeysProvider
}
// NewStructuredSubgraph creates an empty structured subgraph with the given
// match keys provider.
func NewStructuredSubgraph(matchProvider MatchKeysProvider) *StructuredSubgraph {
return &StructuredSubgraph{
nodes: make(map[string][]*Node),
rels: make(map[string][]*Relationship),
matchProvider: matchProvider,
}
}
// AddNode sorts a node into the subgraph.
func (s *StructuredSubgraph) AddNode(node *Node) error {
// Verify that the node has defined match property values.
matchLabel, _, err := node.MatchProps(s.matchProvider)
if err != nil {
return fmt.Errorf("invalid node: %s", err)
}
// Determine the node's sort key.
sortKey := createNodeSortKey(matchLabel, node.Labels.ToArray())
if _, exists := s.nodes[sortKey]; !exists {
s.nodes[sortKey] = []*Node{}
}
// Add the node to the subgraph.
s.nodes[sortKey] = append(s.nodes[sortKey], node)
return nil
}
// AddRel sorts a relationship into the subgraph.
func (s *StructuredSubgraph) AddRel(rel *Relationship) error {
// Verify that the start node has defined match property values.
startLabel, _, err := rel.Start.MatchProps(s.matchProvider)
if err != nil {
return fmt.Errorf("invalid start node: %s", err)
}
// Verify that the end node has defined match property values.
endLabel, _, err := rel.End.MatchProps(s.matchProvider)
if err != nil {
return fmt.Errorf("invalid end node: %s", err)
}
// Determine the relationship's sort key.
sortKey := createRelSortKey(rel.Type, startLabel, endLabel)
if _, exists := s.rels[sortKey]; !exists {
s.rels[sortKey] = []*Relationship{}
}
// Add the relationship to the subgraph.
s.rels[sortKey] = append(s.rels[sortKey], rel)
return nil
}
// GetNodes returns the nodes grouped under the given sort key.
func (s *StructuredSubgraph) GetNodes(nodeKey string) []*Node {
return s.nodes[nodeKey]
}
// GetRels returns the rels grouped under the given sort key.
func (s *StructuredSubgraph) GetRels(relKey string) []*Relationship {
return s.rels[relKey]
}
func (s *StructuredSubgraph) MatchProvider() MatchKeysProvider {
return s.matchProvider
}
// NodeCount returns the number of nodes in the subgraph.
func (s *StructuredSubgraph) NodeCount() int {
count := 0
for l := range s.nodes {
count += len(s.nodes[l])
}
return count
}
// RelCount returns the number of relationships in the subgraph.
func (s *StructuredSubgraph) RelCount() int {
count := 0
for t := range s.rels {
count += len(s.rels[t])
}
return count
}
// NodeKeys returns the list of node sort keys in the subgraph.
func (s *StructuredSubgraph) NodeKeys() []string {
keys := []string{}
for l := range s.nodes {
keys = append(keys, l)
}
return keys
}
// RelKeys returns the list of relationship sort keys in the subgraph.
func (s *StructuredSubgraph) RelKeys() []string {
keys := []string{}
for t := range s.rels {
keys = append(keys, t)
}
return keys
}
// createNodeSortKey returns the serialized node labels for sorting.
func createNodeSortKey(matchLabel string, labels []string) string {
sort.Strings(labels)
serializedLabels := strings.Join(labels, ",")
return fmt.Sprintf("%s:%s", matchLabel, serializedLabels)
}
// createRelSortKey returns the serialized relationship type and start/end node
// labels for sorting.
func createRelSortKey(
rtype string, startLabel string, endLabel string) string {
return strings.Join([]string{rtype, startLabel, endLabel}, ",")
}
// DeserializeNodeKey returns the list of node labels from the serialized sort
// key.
func DeserializeNodeKey(sortKey string) (string, []string, error) {
parts := strings.Split(sortKey, ":")
if len(parts) != 2 {
return "", nil, fmt.Errorf("invalid node sort key: %s", sortKey)
}
matchLabel, serializedLabels := parts[0], parts[1]
labels := strings.Split(serializedLabels, ",")
return matchLabel, labels, nil
}
// DeserializeRelKey returns the relationship type, start node label, and end
// node label from the serialized sort key. Panics if the sort key is invalid.
func DeserializeRelKey(sortKey string) (string, string, string, error) {
parts := strings.Split(sortKey, ",")
if len(parts) != 3 {
return "", "", "", fmt.Errorf("invalid relationship sort key: %s", sortKey)
}
rtype, startLabel, endLabel := parts[0], parts[1], parts[2]
return rtype, startLabel, endLabel, nil
}

172
graph/graph_test.go Normal file
View File

@@ -0,0 +1,172 @@
package graph
import (
"github.com/stretchr/testify/assert"
"testing"
)
func TestMatchKeys(t *testing.T) {
matchKeys := &MatchKeys{
Keys: map[string][]string{
"User": {"pubkey"},
"Event": {"id"},
"Tag": {"name", "value"},
},
}
t.Run("get labels", func(t *testing.T) {
expectedLabels := []string{"Event", "Tag", "User"}
labels := matchKeys.GetLabels()
assert.ElementsMatch(t, expectedLabels, labels)
})
t.Run("get keys", func(t *testing.T) {
expectedKeys := []string{"id"}
keys, exists := matchKeys.GetKeys("Event")
assert.True(t, exists)
assert.ElementsMatch(t, expectedKeys, keys)
})
t.Run("unknown key", func(t *testing.T) {
keys, exists := matchKeys.GetKeys("Unknown")
assert.False(t, exists)
assert.Nil(t, keys)
})
}
func TestNodeSortKey(t *testing.T) {
matchLabel := "Event"
labels := []string{"Event", "AddressableEvent"}
// labels should be sorted by key generator
expectedKey := "Event:AddressableEvent,Event"
// Test Serialization
sortKey := createNodeSortKey(matchLabel, labels)
assert.Equal(t, expectedKey, sortKey)
// Test Deserialization
returnedMatchLabel, returnedLabels, err := DeserializeNodeKey(sortKey)
assert.NoError(t, err)
assert.Equal(t, matchLabel, returnedMatchLabel)
assert.ElementsMatch(t, labels, returnedLabels)
}
func TestRelSortKey(t *testing.T) {
rtype, startLabel, endLabel := "SIGNED", "User", "Event"
expectedKey := "SIGNED,User,Event"
// Test Serialization
sortKey := createRelSortKey(rtype, startLabel, endLabel)
assert.Equal(t, expectedKey, sortKey)
// Test Deserialization
returnedRtype, returnedStartLabel, returnedEndLabel, err := DeserializeRelKey(sortKey)
assert.NoError(t, err)
assert.Equal(t, rtype, returnedRtype)
assert.Equal(t, startLabel, returnedStartLabel)
assert.Equal(t, endLabel, returnedEndLabel)
}
func TestMatchProps(t *testing.T) {
matchKeys := &MatchKeys{
Keys: map[string][]string{
"User": {"pubkey"},
"Event": {"id"},
},
}
cases := []struct {
name string
node *Node
wantMatchLabel string
wantMatchProps Properties
wantErr bool
wantErrText string
}{
{
name: "matching label, all props present",
node: NewEventNode("abc123"),
wantMatchLabel: "Event",
wantMatchProps: Properties{"id": "abc123"},
},
{
name: "matching label, required prop missing",
node: NewNode("Event", Properties{}),
wantErr: true,
wantErrText: "missing property",
},
{
name: "no recognized label",
node: NewNode("Tag", Properties{"name": "e", "value": "abc"}),
wantErr: true,
wantErrText: "no recognized label",
},
{
name: "multiple labels, one matches",
node: &Node{
Labels: NewSet("Event", "Unknown"),
Props: Properties{
"id": "abc123",
},
},
wantMatchLabel: "Event",
wantMatchProps: Properties{"id": "abc123"},
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
matchLabel, props, err := tc.node.MatchProps(matchKeys)
if tc.wantErr {
assert.Error(t, err)
if tc.wantErrText != "" {
assert.ErrorContains(t, err, tc.wantErrText)
}
return
}
assert.NoError(t, err)
assert.Equal(t, tc.wantMatchLabel, matchLabel)
assert.Equal(t, tc.wantMatchProps, props)
})
}
}
func TestStructuredSubgraphAddNode(t *testing.T) {
matchKeys := NewMatchKeys()
subgraph := NewStructuredSubgraph(matchKeys)
node := NewEventNode("abc123")
err := subgraph.AddNode(node)
assert.NoError(t, err)
assert.Equal(t, 1, subgraph.NodeCount())
assert.Equal(t, []*Node{node}, subgraph.GetNodes("Event:Event"))
}
func TestStructuredSubgraphAddNodeInvalid(t *testing.T) {
matchKeys := NewMatchKeys()
subgraph := NewStructuredSubgraph(matchKeys)
node := NewNode("Event", Properties{})
err := subgraph.AddNode(node)
assert.ErrorContains(t, err, "invalid node: missing property id")
assert.Equal(t, 0, subgraph.NodeCount())
}
func TestStructuredSubgraphAddRel(t *testing.T) {
matchKeys := NewMatchKeys()
subgraph := NewStructuredSubgraph(matchKeys)
userNode := NewUserNode("pubkey1")
eventNode := NewEventNode("abc123")
rel := NewSignedRel(userNode, eventNode, nil)
err := subgraph.AddRel(rel)
assert.NoError(t, err)
assert.Equal(t, 1, subgraph.RelCount())
assert.Equal(t, []*Relationship{rel}, subgraph.GetRels("SIGNED,User,Event"))
}

101
graph/schema.go Normal file
View File

@@ -0,0 +1,101 @@
// This module provides methods for creating nodes and relationships according
// to a defined schema.
package graph
import (
"fmt"
)
// ========================================
// Schema Match Keys
// ========================================
func NewMatchKeys() *MatchKeys {
return &MatchKeys{
Keys: map[string][]string{
"User": {"pubkey"},
"Relay": {"url"},
"Event": {"id"},
"Tag": {"name", "value"},
},
}
}
// ========================================
// Node Constructors
// ========================================
func NewUserNode(pubkey string) *Node {
return NewNode("User", Properties{"pubkey": pubkey})
}
func NewRelayNode(url string) *Node {
return NewNode("Relay", Properties{"url": url})
}
func NewEventNode(id string) *Node {
return NewNode("Event", Properties{"id": id})
}
func NewTagNode(name string, value string) *Node {
return NewNode("Tag", Properties{
"name": name,
"value": value})
}
// ========================================
// Relationship Constructors
// ========================================
func NewSignedRel(
start *Node, end *Node, props Properties) *Relationship {
return NewRelationshipWithValidation(
"SIGNED", "User", "Event", start, end, props)
}
func NewTaggedRel(
start *Node, end *Node, props Properties) *Relationship {
return NewRelationshipWithValidation(
"TAGGED", "Event", "Tag", start, end, props)
}
func NewReferencesEventRel(
start *Node, end *Node, props Properties) *Relationship {
return NewRelationshipWithValidation(
"REFERENCES", "Tag", "Event", start, end, props)
}
func NewReferencesUserRel(
start *Node, end *Node, props Properties) *Relationship {
return NewRelationshipWithValidation(
"REFERENCES", "Tag", "User", start, end, props)
}
// ========================================
// Relationship Constructor Helpers
// ========================================
func validateNodeLabel(node *Node, role string, expectedLabel string) {
if !node.Labels.Contains(expectedLabel) {
panic(fmt.Errorf(
"expected %s node to have label %q. got %v",
role, expectedLabel, node.Labels.ToArray(),
))
}
}
func NewRelationshipWithValidation(
rtype string,
startLabel string,
endLabel string,
start *Node,
end *Node,
props Properties) *Relationship {
validateNodeLabel(start, "start", startLabel)
validateNodeLabel(end, "end", endLabel)
return NewRelationship(rtype, start, end, props)
}

44
graph/schema_test.go Normal file
View File

@@ -0,0 +1,44 @@
package graph
import (
"github.com/stretchr/testify/assert"
"testing"
)
func TestNewRelationshipWithValidation(t *testing.T) {
cases := []struct {
name string
start *Node
end *Node
wantPanic bool
wantPanicText string
}{
{
name: "valid start and end nodes",
start: NewUserNode("pubkey1"),
end: NewEventNode("abc123"),
},
{
name: "mismatched start node label",
start: NewEventNode("abc123"),
end: NewEventNode("abc123"),
wantPanic: true,
wantPanicText: "expected start node to have label \"User\". got [Event]",
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
if tc.wantPanic {
assert.PanicsWithError(t, tc.wantPanicText, func() {
NewSignedRel(tc.start, tc.end, nil)
})
return
}
rel := NewSignedRel(tc.start, tc.end, nil)
assert.Equal(t, "SIGNED", rel.Type)
assert.Contains(t, rel.Start.Labels.ToArray(), "User")
assert.Contains(t, rel.End.Labels.ToArray(), "Event")
})
}
}

54
graph/set.go Normal file
View File

@@ -0,0 +1,54 @@
package graph
// Sets
type Set[T comparable] struct {
inner map[T]struct{}
}
func NewSet[T comparable](items ...T) Set[T] {
set := Set[T]{
inner: make(map[T]struct{}),
}
for _, i := range items {
set.Add(i)
}
return set
}
func (s Set[T]) Add(item T) {
s.inner[item] = struct{}{}
}
func (s Set[T]) Remove(item T) {
delete(s.inner, item)
}
func (s Set[T]) Contains(item T) bool {
_, exists := s.inner[item]
return exists
}
func (s Set[T]) Equal(other Set[T]) bool {
if len(s.inner) != len(other.inner) {
return false
}
for item := range s.inner {
if !other.Contains(item) {
return false
}
}
return true
}
func (s Set[T]) Length() int {
return len(s.inner)
}
func (s Set[T]) ToArray() []T {
array := []T{}
for i := range s.inner {
array = append(array, i)
}
return array
}