types_interface.go

package f8n

import (
	"bytes"
	"net/http"
	"net/url"

	"gorm.io/gorm"
)

// Interface Интерфейс пакета.
type Interface interface {
	// НАСТРОЙКИ

	// FieldSet Назначение списка обрабатываемых полей.
	// Если список не установлен или установлен пустым значением, обрабатываются все полня, переданные в запросе.
	// Если список установлен, но в запросе присутствует поле, отсутствующее в списке, будет возвращена ошибка.
	FieldSet(field ...string) Interface

	// FieldGet Возвращается список полей.
	// Если список полей был установлен, тогда возвращаются установленные поля.
	// Если список полей не был установлен, возвращаются поля, найденные в запросе.
	FieldGet() (ret []string)

	// FieldDatatype Назначение типа данных для поля.
	// Все поля по умолчанию имеют тип данных "строка".
	FieldDatatype(fieldName string, t FieldType) Interface

	// Redefinition Назначение переопределения названий полей или замены полей.
	// Назначенные или полученных из запроса поля, подменяются названиями полей используемых в базе данных.
	Redefinition(fieldName string, newFieldName string) Interface

	// ПОЛУЧЕНИЕ И СОХРАНЕНИ НАСТРОЕК ФИЛЬТРАЦИИ

	// ParseRequest Загрузка настроек фильтрации из http.Request запроса.
	// Если при разборе запроса возникает ошибка, она возвращается в качестве интерфейса error.
	// Если в функцию передан не равный нулю объект функции OnErrorFunc, тогда будет вызвана эта функция и в неё
	// будут переданы описания возникшей ошибки.
	ParseRequest(rq *http.Request, errorFn ...OnErrorFunc) (err error)

	// ExportJson Сохранение настроек фильтрации в формате JSON.
	// Экспортируются все разобранные поля запроса, а так же настройки переопределения и типов полей.
	// Параметры prefix и ident используются для формирования отформатированного человеко-читаемого JSON, но обычно
	// используются пустые значения форматирования.
	ExportJson(prefix string, ident string) (ret *bytes.Buffer)

	// ImportJson Загрузка настроек фильтрации из переданного в функцию JSON.
	// Импортируются все ранее разобранные настройки, а так же настройки переопределения и типов полей.
	ImportJson(buf []byte) (err error)

	// String Интерфейс Stringify, представляет разобранный запрос в виде строки.
	// В результат не попадают:
	// 1. Список имён обрабатываемых полей.
	// 2. Карта типов данных полей.
	// 3. Переопределение наименований полей.
	String() (ret string)

	// Query Возвращаются все разобранные значения в формате http.Request.Query().Values, тип данных url.Values.
	// В результат не попадают:
	// 1. Список имён обрабатываемых полей.
	// 2. Карта типов данных полей.
	// 3. Переопределение наименований полей.
	Query() (ret url.Values)

	// ImportString Импорт строки запроса.
	// Строка запроса может быть строкой ранее полученной через вызов функции String(), либо строкой полученной
	// из параметров URN запроса.
	ImportString(s string) (err error)

	// СБРОС

	// Reset Сброс всех загруженных или импортированных настроек, переопределений и типов полей.
	Reset() Interface

	// ResetLimit Сброс настроек лимитирования и постраничного вывода.
	ResetLimit() Interface

	// ResetBy Сброс настроек сортировки.
	ResetBy() Interface

	// ResetFilter Сброс настроек простой фильтрации.
	ResetFilter() Interface

	// ResetMap Сброс DOM дерева карты настроек сложной фильтрации.
	ResetMap() Interface

	// ResetRedefinition Сброс переопределения названий полей или замены полей.
	ResetRedefinition() Interface

	// ResetDatatype Сброс назначения типа данных для полей.
	ResetDatatype() Interface

	// ResetFieldSet Сброс списка обрабатываемых полей.
	ResetFieldSet() Interface

	// SQL И ОРМ

	// Gorm Добавление в ORM всех разобранных значений.
	Gorm(orm *gorm.DB) (ret *gorm.DB, err error)

	// GormSepFilter Добавление в ORM всех разобранных значений и возвращение фильтрации отдельным объектом.
	GormSepFilter(orm *gorm.DB) (ret *gorm.DB, filter *gorm.DB, err error)

	// Sql Создание SQL запроса с фильтрацией данных.
	// В функцию передаётся диалект базы данных, для правильного формирования SQL запроса с ориентировкой на
	// тип используемой базы банных.
	Sql(dialect SqlDialect) (ret string, err error)

	// ИНФОРМАЦИЯ

	// IsFiltration Информация о наличии фильтрации в запросе.
	IsFiltration() bool

	// ОШИБКИ

	// Errors Справочник ошибок.
	Errors() *Error
}