sodium

Documentation

Overview

Package sodium provides a specification for the SODIUM standard database interface.

Index

• Variables
• type API
• type Calculation
• type Callback
• type Column
• type Database
• type Error
• type Expression
• type Job
• type Join
• type MatchExpression
• type Modification
• type OrderExpression
• type Patch
• type Query
• type Range
• type Result
• type Socket
• type Stats
• type Table
• type Transaction
• type Value
  • func (val Value) IsZero() bool
• type WhereExpression

Variables

var Calculations = xyz.AccessorFor(Calculation.Values)

var Errors = xyz.AccessorFor(Error.Values)

var Expressions = xyz.AccessorFor(Expression.Values)

var MatchExpressions = xyz.AccessorFor(MatchExpression.Values)

var Modifications = xyz.AccessorFor(Modification.Values)

var OrderExpressions = xyz.AccessorFor(OrderExpression.Values)

var Values = xyz.AccessorFor(Value.Values)

var WhereExpressions = xyz.AccessorFor(WhereExpression.Values)

Types

type API

type API struct {
	api.Specification `
		for communicating with a SODIUM database host.`

	Socket func(context.Context) (Socket, error) `rest:"GET /" sock:"websocket"`
}

type Calculation

type Calculation xyz.Tagged[any, struct {
	Add Calculation
	Sum xyz.Case[Calculation, Column]
	Avg xyz.Case[Calculation, Column]
	Top xyz.Case[Calculation, Column]
	Min xyz.Case[Calculation, Column]
	Max xyz.Case[Calculation, Column]
}]

type Callback

type Callback func() error

Callback should be called for each result within a search.

type Column

type Column struct {
	Name string
	Type xyz.TypeOf[Value]
	Tags reflect.StructTag
	// contains filtered or unexported fields
}

type Database

type Database interface {
	// Search the specified [Table] for [Value]s that match the given [Query].
	// Whenever a result is found, it is sent to the specified channel, which
	// is closed when the search is complete. The search will be cancelled if
	// the managed context is cancelled. The sends are non-blocking, so ensure
	// that the channel is buffered appropriately to avoid errors.
	Search(Table, Query, chan<- []Value) Job
	// Output calculates the requested [Stats] for the given table and
	// returns them to the specified channel, which is closed when the
	// output is complete. The output will be cancelled if the managed
	// context is cancelled.
	Output(Table, Query, Stats, chan<- []Value) Job
	// Delete should remove any records that match the given query from
	// the table. A finite [Range] must be specified, if the [Range] is
	// empty, the operation will fail. Cannot be cancelled.
	Delete(Table, Query) Job
	// Insert a [Value] into the table. If the value already exists, the
	// flag determines whether the operation should fail (false) or overwrite
	// the existing value (true). Cannot be cancelled. The resulting keys and
	// values will be written into the provided slices.
	Insert(Table, []Value, bool, []Value) Job
	// Update should apply the given patch to each [Value]s in
	// the table that matches the given [Query]. A finite [Range]
	// must be specified, if the [Range] is empty, the operation will fail.
	//  Cannot be cancelled.
	Update(Table, Query, Patch) Job
	// Manage returns a channel that will manage the execution of the given jobs
	// within the transaction level specified by the given [Transaction]. Close
	// the channel to commit the transaction, or send a nil [Job] (or cancel the
	// context) to rollback the transaction.
	Manage(context.Context, Transaction) (chan<- Job, error)
}

Database that supports the SODIUM interface.

type Error

type Error xyz.Tagged[any, struct {
	Internal Error `txt:"internal" xyz:"0"`
}]

type Expression

type Expression xyz.Tagged[any, struct {
	Value xyz.Case[Expression, bool]
	Index xyz.Case[Expression, xyz.Pair[Column, Value]]
	Where xyz.Case[Expression, WhereExpression]
	Match xyz.Case[Expression, MatchExpression]
	Order xyz.Case[Expression, OrderExpression]
	Range xyz.Case[Expression, Range]
	Empty xyz.Case[Expression, Column]
	Avoid xyz.Case[Expression, Expression]
	Cases xyz.Case[Expression, []Expression]
	Group xyz.Case[Expression, []Expression]
}]

Expression within a Query.

type Job

type Job interface {
	Wait(context.Context) (int, error)
}

Job of SQL job.

type Join

type Join struct {
	On    xyz.Pair[Column, Column]
	Table Table
	// contains filtered or unexported fields
}

Join relationship.

type MatchExpression

type MatchExpression xyz.Tagged[any, struct {
	Contains  xyz.Case[MatchExpression, xyz.Pair[Column, string]]
	HasPrefix xyz.Case[MatchExpression, xyz.Pair[Column, string]]
	HasSuffix xyz.Case[MatchExpression, xyz.Pair[Column, string]]
}]

MatchExpression within a Query.

type Modification

type Modification xyz.Tagged[any, struct {
	Set xyz.Case[Modification, xyz.Pair[Column, Value]]
	Arr xyz.Case[Modification, []Modification]
}]

type OrderExpression

type OrderExpression xyz.Tagged[any, struct {
	Increasing xyz.Case[OrderExpression, Column]
	Decreasing xyz.Case[OrderExpression, Column]
}]

OrderExpression within a Query.

type Patch

type Patch []Modification

type Query

type Query []Expression

type Range

type Range struct {
	From int
	Upto int
}

Range is an half open range (or slice) on the data to be operated on. Index starts at 0. Range{0,1} means the first element, Range{0,2} means the first two elements, etc.

type Result

type Result struct {
	Number int `txt:"number" xyz:"0"
		is the Nth command from the socket
		that this result corresponds to.`
	Closed bool `txt:"closed" xyz:"1"
		indicates that the there are no
		more future results for this number.`
	Values []Value `txt:"values" xyz:"2"
		are the current set of results.`
	Errors []Error `txt:"errors" xyz:"3"
		are any errors that occurred during
		the execution of the command.`
}

type Socket

type Socket struct {
	api.Specification

	Read func(context.Context) (Result, error) `txt:"SYNC" xyz:"0"
		waits for a result and returns it.`

	Search func(context.Context, Table, Query) error `txt:"SEARCH(table,query)" xyz:"1(1,2)"
		starts the execution of a search query.`
	Output func(context.Context, Table, Query, Stats) error `txt:"OUTPUT(table,query,stats)" xyz:"2(1,2,3)"
		starts the execution of an output query.`
	Delete func(context.Context, Table, Query) error `txt:"DELETE(table,query)" xyz:"3(1,2)"
		starts the execution of a delete query.`
	Insert func(context.Context, Table, []Value, bool, []Value) error `txt:"INSERT(table,index,flag,value)" xyz:"4(1,2,3,4)"
		starts the execution of an insert query.`
	Update func(context.Context, Table, Query, Patch) error `txt:"UPDATE(table,query,patch)" xyz:"3(1,2,3)"
		starts the execution of an update query.`
	Manage func(context.Context, Transaction) error `` /* 127-byte string literal not displayed */

}

type Stats

type Stats []Calculation

type Table

type Table struct {
	Name string

	Index []Column
	Value []Column

	Joins []Join
	// contains filtered or unexported fields
}

Table represents a distinct collection of structured data within a database.

type Transaction

type Transaction uint64

Transaction flags.

const (
	DirtyReads Transaction = 1 << iota // means the transaction can read uncommitted data.
	ReadWrites                         // means the transaction can read after it writes.
	LockWrites                         // means that all writes will be locked until the transaction ends.
	GlobalLock                         // means that the database will be locked until the transaction ends.
)

type Value

type Value xyz.Tagged[any, struct {
	Bool    xyz.Case[Value, bool]
	Int8    xyz.Case[Value, int8]
	Int16   xyz.Case[Value, int16]
	Int32   xyz.Case[Value, int32]
	Int64   xyz.Case[Value, int64]
	Uint8   xyz.Case[Value, uint8]
	Uint16  xyz.Case[Value, uint16]
	Uint32  xyz.Case[Value, uint32]
	Uint64  xyz.Case[Value, uint64]
	Float32 xyz.Case[Value, float32]
	Float64 xyz.Case[Value, float64]
	String  xyz.Case[Value, string]
	Bytes   xyz.Case[Value, []byte]
	Time    xyz.Case[Value, time.Time]
}]

func (Value) IsZero

func (val Value) IsZero() bool

type WhereExpression

type WhereExpression xyz.Tagged[any, struct {
	Min xyz.Case[WhereExpression, xyz.Pair[Column, Value]]
	Max xyz.Case[WhereExpression, xyz.Pair[Column, Value]]

	MoreThan xyz.Case[WhereExpression, xyz.Pair[Column, Value]]
	LessThan xyz.Case[WhereExpression, xyz.Pair[Column, Value]]
}]

WhereExpression within a Query.