add documentation

backend/v3/storage/cache/doc.go

@@ -0,0 +1,2 @@
+// this package is copy pasted from the internal/cache package
+package cache

backend/v3/storage/database/change.go

@@ -1,5 +1,7 @@
 package database
 
+// Change represents a change to a column in a database table.
+// Its written in the SET clause of an UPDATE statement.
 type Change interface {
 	Write(builder *StatementBuilder)
 }

backend/v3/storage/database/column.go

@@ -12,6 +12,7 @@ func (m Columns) Write(builder *StatementBuilder) {
 	}
 }
 
+// Column represents a column in a database table.
 type Column interface {
 	Write(builder *StatementBuilder)
 }
@@ -31,6 +32,8 @@ func (c column) Write(builder *StatementBuilder) {
 
 var _ Column = (*column)(nil)
 
+// ignoreCaseColumn represents two database columns, one for the
+// original value and one for the lower case value.
 type ignoreCaseColumn interface {
 	Column
 	WriteIgnoreCase(builder *StatementBuilder)

backend/v3/storage/database/condition.go

@@ -1,5 +1,7 @@
 package database
 
+// Condition represents a SQL condition.
+// Its written after the WHERE keyword in a SQL statement.
 type Condition interface {
 	Write(builder *StatementBuilder)
 }
@@ -22,6 +24,7 @@ func (a *and) Write(builder *StatementBuilder) {
 	}
 }
 
+// And combines multiple conditions with AND.
 func And(conditions ...Condition) *and {
 	return &and{conditions: conditions}
 }
@@ -46,6 +49,7 @@ func (o *or) Write(builder *StatementBuilder) {
 	}
 }
 
+// Or combines multiple conditions with OR.
 func Or(conditions ...Condition) *or {
 	return &or{conditions: conditions}
 }
@@ -62,6 +66,7 @@ func (i *isNull) Write(builder *StatementBuilder) {
 	builder.WriteString(" IS NULL")
 }
 
+// IsNull creates a condition that checks if a column is NULL.
 func IsNull(column Column) *isNull {
 	return &isNull{column: column}
 }
@@ -78,6 +83,7 @@ func (i *isNotNull) Write(builder *StatementBuilder) {
 	builder.WriteString(" IS NOT NULL")
 }
 
+// IsNotNull creates a condition that checks if a column is NOT NULL.
 func IsNotNull(column Column) *isNotNull {
 	return &isNotNull{column: column.(Column)}
 }
@@ -86,18 +92,21 @@ var _ Condition = (*isNotNull)(nil)
 
 type valueCondition func(builder *StatementBuilder)
 
+// NewTextCondition creates a condition that compares a text column with a value.
 func NewTextCondition[V Text](col Column, op TextOperation, value V) Condition {
 	return valueCondition(func(builder *StatementBuilder) {
 		writeTextOperation(builder, col, op, value)
 	})
 }
 
+// NewDateCondition creates a condition that compares a numeric column with a value.
 func NewNumberCondition[V Number](col Column, op NumberOperation, value V) Condition {
 	return valueCondition(func(builder *StatementBuilder) {
 		writeNumberOperation(builder, col, op, value)
 	})
 }
 
+// NewDateCondition creates a condition that compares a boolean column with a value.
 func NewBooleanCondition[V Boolean](col Column, value V) Condition {
 	return valueCondition(func(builder *StatementBuilder) {
 		writeBooleanOperation(builder, col, value)

backend/v3/storage/database/config.go

@@ -4,6 +4,7 @@ import (
 	"context"
 )
 
+// Connector abstracts the database driver.
 type Connector interface {
 	Connect(ctx context.Context) (Pool, error)
 }

backend/v3/storage/database/database.go

@@ -4,15 +4,7 @@ import (
 	"context"
 )
 
-var (
-	db *database
-)
-
-type database struct {
-	connector Connector
-	pool      Pool
-}
-
+// Pool is a connection pool. e.g. pgxpool
 type Pool interface {
 	Beginner
 	QueryExecutor
@@ -21,6 +13,7 @@ type Pool interface {
 	Close(ctx context.Context) error
 }
 
+// Client is a single database connection which can be released back to the pool.
 type Client interface {
 	Beginner
 	QueryExecutor
@@ -28,33 +21,37 @@ type Client interface {
 	Release(ctx context.Context) error
 }
 
+// Querier is a database client that can execute queries and return rows.
 type Querier interface {
 	Query(ctx context.Context, stmt string, args ...any) (Rows, error)
 	QueryRow(ctx context.Context, stmt string, args ...any) Row
 }
 
+// Executor is a database client that can execute statements.
 type Executor interface {
 	Exec(ctx context.Context, stmt string, args ...any) error
 }
 
+// QueryExecutor is a database client that can execute queries and statements.
 type QueryExecutor interface {
 	Querier
 	Executor
 }
 
+// Scanner scans a single row of data into the destination.
 type Scanner interface {
 	Scan(dest ...any) error
 }
 
+// Row is an abstraction of sql.Row.
 type Row interface {
 	Scanner
 }
 
+// Rows is an abstraction of sql.Rows.
 type Rows interface {
 	Row
 	Next() bool
 	Close() error
 	Err() error
 }
-
-type Query[T any] func(querier Querier) (result T, err error)

backend/v3/storage/database/dialect/postgres/doc.go

@@ -0,0 +1,2 @@
+// pgxpool v5 implementation of the interfaces defined in the database package.
+package postgres

backend/v3/storage/database/operators.go

@@ -18,6 +18,7 @@ type Text interface {
 	~string | ~[]byte
 }
 
+// TextOperation are operations that can be performed on text values.
 type TextOperation uint8
 
 const (
@@ -89,6 +90,7 @@ type Number interface {
 	constraints.Integer | constraints.Float | constraints.Complex | time.Time | time.Duration
 }
 
+// NumberOperation are operations that can be performed on number values.
 type NumberOperation uint8
 
 const (
@@ -125,6 +127,7 @@ type Boolean interface {
 	~bool
 }
 
+// BooleanOperation are operations that can be performed on boolean values.
 type BooleanOperation uint8
 
 const (

backend/v3/storage/database/repository/doc.go

@@ -0,0 +1,5 @@
+// Package implements the repositories defined in the domain package.
+// The repositories are used by the domain package to access the database.
+// the inheritance.sql file is me over-engineering table inheritance.
+// I would create a user table which is inherited by human_user and machine_user and the same for objects like idps.
+package repository

backend/v3/storage/database/tx.go

@@ -2,6 +2,7 @@ package database
 
 import "context"
 
+// Transaction is an SQL transaction.
 type Transaction interface {
 	Commit(ctx context.Context) error
 	Rollback(ctx context.Context) error
@@ -12,6 +13,7 @@ type Transaction interface {
 	QueryExecutor
 }
 
+// Beginner can start a new transaction.
 type Beginner interface {
 	Begin(ctx context.Context, opts *TransactionOptions) (Transaction, error)
 }