/**
 * file: types/datasource.go
 * author: Theo Technicguy
 * license: Apache 2.0
 *
 * Data source interface
 */

// Package types implements all types used in the Hoffman server
package types

import "errors"

// Datasource global errors
var (
	ErrDuplicateUniqueIdentifier = errors.New("duplicate unique identifier")
)

// Connect creates a new connection to the data source located at
// string. If the data source has not been initialized, it
// initializes it to be able to persist the data.
type Connect func(string) (Datasource, error)

// A Datasource is the connector to the real persistant data and the
// server.
//
// Every function is expected to interact with the persistant storage,
// which is considered the single source of truth for the entire system.
// Therefor, it is primordial that it ensures ACID properties are always
// verifed.
// These functions are moslty straight forward low-level interactions,
// however some are more high-level, requiering transactions to keep
// ACID properties.
//
// The Datasource MUST be able to perform full CRUD actions for all
// types in this types package.
type Datasource interface {

	// Disconnect severs the connection to the data source.
	// After disconnection, the data source cannot be used to correctly
	// fulfil any actions requested.
	Disconnect() error

	// InsertProduct creates a new entry in the product segment of the
	// data source persistant storage. Products have a unique ID, set
	// by the data source, and a unique EAN code. Duplicates are
	// rejected. Product taggings are also saved.
	// InsertProduct also updates the ID of the product to match the
	// unique ID attributed.
	InsertProduct(*Product) error

	// SelectAllProducts returns all products from the product segment
	// of the data source persistant storage. If there are none, returns
	// an empty array of products and a nil error.
	SelectAllProducts() ([]*Product, error)

	// SelectProductById returns the only product with that ID from
	// the product segment of the data source persistant storage.
	// If the ID does not exist, SelectProductById returns an empty
	// product (without any values) and a nil error.
	SelectProductById(uint) (*Product, error)

	// SelectProductLike returns all possible products from the product
	// segment of the data source persistant storage matching the
	// search. If there are none, returns an empty array of products and
	// a nil error.
	SelectProductsLike(*ProductSearch) ([]*Product, error)

	// UpdateProduct updates the product in the product segment of the
	// data source persistant storage to match the passed product.
	// This means that taggings also have to be updated. The updated
	// product is then returned.
	// The ID can never be updated.
	UpdateProduct(*Product) (*Product, error)

	// DeleteProduct completely removes the product from the product
	// segment of the data source persistant storage. This means that
	// taggings are also deleted. It returns the deleted product in
	// full afterwards.
	DeleteProduct(uint) (*Product, error)

	// InsertProuctTag creates a new entry in the product tag segment
	// of the data source persistant storage. Product tags have a
	// unique ID, set by the data source, and name. Duplicates are
	// rejected.
	// InsertProductTag also updates the ID of the tag to match the
	// unique ID attributed.
	InsertProductTag(*Tag) error

	// SelectAllProductTags returns all possible product tags from the
	// product tag segment of the data source persistant storage. If
	// there are none, returns an empty array of produt tags.
	SelectAllProductTags() ([]*Tag, error)

	// SelectProductTagById returns the only product tag with that ID
	// from the product tag segment of the data source persistant
	// storage. If the ID does not exist, returns an emtpy product tag
	// and a nil error.
	SelectProductTagById(uint) (*Tag, error)

	// SelectProductTagByName returns the only product tag with that
	// name from the product tag segment of the data source persistant
	// storage. If none are found, returns an emtpy product tag and a
	// nil error.
	SelectProductTagByName(string) (*Tag, error)

	// SelectProductTagsLikeName returns all possible product tags
	// matching the name. If there are none, returns an empty array
	// of product tags and no error.
	SelectProductTagsLikeName(string) ([]*Tag, error)

	// UpdateProductTag updates the product tag in the product segment
	// of the data source peristant storage to match the passed product
	// tag.
	// The ID can never be updated.
	// Product tags have unique names. Duplicates are expected to be
	// rejected.
	UpdateProductTag(*Tag) (*Tag, error)

	// DeleteProductTag completely removes the product tag from the
	// product tag segment of the data source persistant storage.
	// This means that taggings are also deleted. After that, it
	// returns the deleted tag.
	DeleteProductTag(uint) (*Tag, error)
}