errors

README

🛑 Entiqon DB Errors

Part of Entiqon / Database

The db/errors package defines sentinel errors used throughout Entiqon’s SQL builder (table, field, join, condition).

These sentinels provide a consistent way to classify and detect common failure modes across constructors and validators.

---

📌 Overview

Two error values are currently exported:

• UnsupportedTypeError
  Returned when a constructor (e.g. table.New) receives a type that is not supported.
  Example:

  table.New(table.New("users"))
  // → error: unsupported type; if you want to create a copy, use Clone() instead
  

• InvalidIdentifierError
  Returned when an identifier fails validation (e.g. contains invalid characters).
  Example:

  table.New("???")
  // → error: invalid table identifier
  

---

🔍 Usage with errors.Is

Sentinel errors are intended to be checked with the Go standard library errors.Is:

t := table.New("???")
if errors.Is(t.Error(), dberrors.InvalidIdentifierError) {
    log.Printf("invalid identifier: %v", t.Error())
}

This allows constructors (table.New, field.New) to wrap errors with context-specific messages while still preserving the ability to detect the underlying cause.

---

✅ Testing

The package includes errors_test.go, which provides both examples and table-driven tests to ensure that wrapped errors can be matched with errors.Is.

Run tests with:

go test ./db/errors

---

Documentation

Overview

Package errors defines sentinel errors used across Entiqon’s SQL builder tokens (tables, fields, joins, conditions).

These errors provide consistent classification for common failure modes such as unsupported constructor types or invalid identifier names.

Overview

The package exposes sentinel error values that can be used with errors.Is for robust error handling:

• UnsupportedTypeError is returned by constructors (e.g. table.New) when an input type is not allowed. For example:

  table.New(table.New("users")) // → error: unsupported type; if you want to create a copy, use Clone() instead

• InvalidIdentifierError is returned when an identifier fails validation (e.g. invalid characters or format). For example:

  table.New("???") // → error: invalid table identifier

Usage

Callers should prefer errors.Is to detect sentinel values:

if errors.Is(err, errors.InvalidIdentifierError) {
    log.Printf("invalid identifier: %v", err)
}

This allows context-specific constructors (table, field, etc.) to wrap the base sentinel with their own diagnostic messages while preserving consistent error typing.

Example

package main

import (
	stdErrors "errors"
	"fmt"

	"github.com/entiqon/db/errors"
)

func main() {
	// Simulate an identifier validation failure
	err := fmt.Errorf("%w: name contains invalid characters", errors.InvalidIdentifierError)

	if stdErrors.Is(err, errors.InvalidIdentifierError) {
		fmt.Println("invalid identifier caught")
	}

	// Simulate passing unsupported type into constructor
	err = fmt.Errorf("%w: got int", errors.UnsupportedTypeError)

	if stdErrors.Is(err, errors.UnsupportedTypeError) {
		fmt.Println("unsupported type caught")
	}

}

Output:
invalid identifier caught
unsupported type caught

Index

• Variables

Examples

• Package

Variables

var (
	// UnsupportedTypeError is returned by helpers.ValidateType when the input
	// is not a raw string, but instead a token or another unsupported type.
	//
	// For example:
	//   table.New(table.New("users"))
	// will return this error, suggesting the caller use Clone() instead
	// of nesting tokens directly.
	UnsupportedTypeError = errors.New("unsupported type")

	// InvalidIdentifierError is a sentinel error returned when an identifier
	// (table name, field name, alias, etc.) fails validation.
	//
	// This error is wrapped with context-specific messages, allowing callers
	// to distinguish identifier validation failures using errors.Is:
	//
	//   if errors.Is(err, errors.InvalidIdentifierError) {
	//       // Handle invalid identifier error
	//   }
	//
	// Example failures:
	//   - table.New("???")   → invalid table identifier
	//   - field.New("1abc") → invalid field identifier
	InvalidIdentifierError = errors.New("invalid identifier")
)