Документация

Главы

Подключение
Таблица
Типы
Ошибки

Подключение

Для подключение к базе данных библиотека предоставляется несколько функций: createConnection, createPool and createPoolCluster. With which you can get a connection.

Таблица

Конструктор

Конструктор таблицы ожидает конфигурацию таблицы, как обязательный параметр

import { Table } from "mariadb-table-wrapper";

const anyTable = new Table({
	table: "tableName",

	fields: {
		someField: {
			type: "BOOL",
			isPrimaryKey: true,
		},
	},
	safeCreation: true,
	foreignKeys: {
		someField: {
			tableName: "another table",
			field: "field from another table",
		},
	},
});

Также в TypeScript вы должны предоставить интерфейс таблицы. Каждое поле из передаваемого интерфейса должно быть описано в конфигурации

import { Table } from "mariadb-table-wrapper";

interface TableInterface {
	anyId: number;
	name: string;
}
const anyTable = new Table<TableInterface>({
	table: "tableName",

	fields: {
		anyId: {
			type: "SMALLINT",
			isPrimaryKey: true,
		},
		name: {
			type: "VARCHAR",
			stringLen: 64,
		},
	},
});

Параметры:

[Обязательный] config[TableConfig] - конфиг таблицы

Возвращает:

Экземпляр таблицы

Инициализация

Перед тем как вы сможете использовать таблицу, ее нужно инициализировать. Для этого нужно вызвать метод init с параметром типа connection

import { createConnection } from "mariadb-table-wrapper";

const connection = await createConnection({
	/* Опции подключения */
});
await anyTable.init(connection);

Во время вызова данного метода происходит создание таблицы в БД

Внесение

Для внесения данных в таблицу, экземпляр класса Table предоставляет метод insert

await anyTable.insert({
	/* Ваши вносимые данные */
});
// or
await anyTable.insert([/* Ваши вносимые данные */ {}, {}]);

В TypeScript вы можете передать интерфейс для вносимых данных

interface AnyInsertInterface {
	/* Описание интерфейса */
}

await anyTable.insert<AnyInsertInterface>({
	/* Ваши вносимые данные, соответствующие интерфейсу */
});
// or
await anyTable.insert<AnyInsertInterface>([
	{
		/* Ваши вносимые данные, соответствующие интерфейсу */
	},
	{
		/* Ваши вносимые данные, соответствующие интерфейсу */
	},
]);

Параметры:

[Обязательный] values[T | T[]] - данные, которые будут внесены в таблицу

Возвращает: Promise, разрешающийся в void

Выборка

Для выборки данных из таблицы предоставляется метод select

await anyTab.select({
	/* Конфиг выборки */
});

В TypeScript по умолчанию данные имеют интерфейс таблицы, но так же может быть передан другой интерфейс

/*  */
interface AnyAnotherResponse {
	/* Интерфейс ответа */
}
await anyTable.select<AnyAnotherResponse>({
	/* Конфиг выборки */
});

Для выборки только одной строки используется метод selectOne

await anyTab.selectOne({
	/* Конфиг выборки */
});

/*  */
interface AnyAnotherResponse {
	/* Интерфейс ответа */
}
await anyTable.selectOne<AnyAnotherResponse>({
	/* Конфиг выборки */
});

Параметры:

[Опциональный] config[SelectConfig] - конфиг выборки данных

Возвращает Promise разрешающийся в тип таблицы или переданный интерфейс. При использовании метода selectOne, возможен возврат undefined, если ни одна запись не была выбрана

Удаление

Для удаления записей из таблицы используется метод delete

await anyTab.delete({
	/* Конфигурация удаления */
});

Параметры:

[Опциональный] config[Query] - конфигурация запроса на удаление

Возвращает Promise, разрешающийся в void

Обновление

Для обновления данных в таблице используется метод update

await anyTable.update(
	{
		/* Новые значения */
	},
	{
		/* Конфиг запроса */
	}
);

В TypeScript вы должны передать интерфейс для вносимых данных

interface AnyNewValues {
	/* Интерфейс для новых значений */
}

await anyTable.update<AnyNewValues>(
	{
		/* Новые значения */
	},
	{
		/* Конфиг запроса */
	}
);

Параметры:

[Обязательный] newValues[AnyObject | AnyNewValues] - значения, на которые будут обновлены
[Опциональный] config[Query] - конфиг запроса, выбирающий записи для обновления

Возвращает: Promise, разрешающийся в void

Сброс

Для удаления всех данных из таблица используются два метода - drop и truncate

await anyTable.truncate();
await anyTable.drop();

Параметры: Нет параметров

Возвращает: Promise, разрешающийся в void

Описание

Для получения описания структура таблицы используется метод desc

await anyTable.describe();

Параметры: Нет параметров

Возвращает: Promise, разрешающийся в массив с типом Description

Структура

ДЛя изменения структуры таблицы используется метод alter

await anyTable.alter({
	/* Конфиг изменения структуры */
});

Параметры:

[Обязательный] params[AlterTableRequest|AlterTableRequest[]] - описание изменения структуры

Возвращает: Promise, разрешающийся в void

Типы

TableConfig

Это дженерик, описывающий конфиг таблицы

Поля:

[Обязательный] table[string] - название таблицы
[Обязательный] fields[Fields] - объект, описывающий поля таблицы
[Опциональный] safeCreation[boolean] - если значение true, то в методе init будет добавлена строка IF NOT EXISTS
[Опциональный] foreignKeys[ForeignKeys] - объект, описывающий внешние ключи

interface TableConfig<TF extends AnyObject> {
	readonly table: string;
	readonly fields: Fields<TF>;
	readonly safeCreating?: boolean;
	readonly foreignKeys?: ForeignKeys<TF>;
}

Fields

Это дженерик, описывающий поля таблицы

Поля:

[Обязательный] tableFieldName[FieldConfig] - конфиг поля

type Fields<TF> = {
	readonly [key in keyof TF]: FieldConfig<TF[key]>;
};

FieldConfig

Это дженерик, описывающий поле

Поля:

[Обязательный] type[SQLTypes] - тип поля
[Опциональный] isAutoIncrement[boolean] - автоинкремент
[Опциональный] isPrimaryKey[boolean] - первичный ключ
[Опциональный] isUnique[boolean] - только уникальные
[Опциональный] isUnsigned[boolean] - беззнаковое число
[Опциональный] isNotNull[boolean] - может ли быть нулем
[Опциональный] check[Expressions] - проверка перед внесением данных
[Опциональный] default[T] - значение по умолчанию
[Опциональный] stringLen[number] - длинна строки, если выбран тип VARCHAR или CHAR
[Опциональный] enumSetValues[T[]] - значения для ENUM или SET

interface FieldConfig<T extends ValidSQLType> {
	readonly type: SQLTypes;
	readonly isAutoIncrement?: boolean;
	readonly isPrimaryKey?: boolean;
	readonly isUnique?: boolean;
	readonly isUnsigned?: boolean;
	readonly isNotNull?: boolean;
	readonly check?: Expressions<T>;
	readonly default?: T;

	readonly stringLen?: number;
	readonly enumSetValues?: T[];
}

SQLTypes

Это элиас, содержащий поддерживаемые типы данных

type SQLTypes =
	/* NUMBERS */
	| "TINYINT"
	| "SMALLINT"
	| "MEDIUMINT"
	| "INT"
	| "BIGINT"
	| "DECIMAL"
	| "FLOAT"
	| "DOUBLE"
	| "BOOL"

	/* TEXT */
	| "VARCHAR"
	| "CHAR"
	| "TINYTEXT"
	| "TEXT"
	| "MEDIUMTEXT"
	| "LARGETEXT"

	/* DATE */
	| "DATE"
	| "TIME"
	| "DATETIME"
	| "YEAR"
	| "TIMESTAMP"

	/* COMPLEX */
	| "ENUM"
	| "NULL"
	| "SET"

	/* BIN */
	| "TINYBLOB"
	| "BLOB"
	| "MEDIUMBLOB"
	| "LARGEBLOB";

Expressions

Дженерик элиас, описывающий логические выражения. Это может быть одно выражение(объект), массив(его элементы будут объединены оператором и) или матрица(внутренние элементы объединяются с помощью и, а внешние через или)

type Expressions<T extends ValidSQLType> =
	| Expression<T>
	| Expression<T>[]
	| Expression<T>[][];

ForeignKeys

Дженерик, описывающий внешнюю связь в таблице

Поля:

[Опциональный] FieldName[Reference] - ссылка на таблицу

type ForeignKeys<TF extends AnyObject> = {
	readonly [key in keyof TF]?: Reference;
};

Expression

Дженерик, описывающий логическое выражение

Значения:

[Обязательный] operator[Operators] - оператор выражения
[Опциональный] value[T] - правый операнд
[Опциональный] not[boolean] - инверсия
[Опциональный] template[string]] - шаблон для регулярного выражения

interface Expression<T extends ValidSQLType> {
	readonly operator: Operators;
	readonly value?: T | T[];
	readonly not?: boolean;
	readonly template?: string;
}

Operators

Это элиаc допустимых операторов

type Operators =
	| "="
	| "<"
	| "<="
	| ">"
	| ">="
	| "!="
	| "between"
	| "in"
	| "like"
	| "regExp"
	| "is null";

Reference

Объект, описывающий ссылку на внешнюю таблицу

Поля:

[Обязательный] tableName[string] - имя внешней таблицы
[Обязательный] field[string] - поле внешней таблицы
[Опциональный] onUpdate[string] - поведение на обновление
[Опциональный] onDelete[string] - поведение на удаление

interface Reference {
	readonly tableName: string;
	readonly field: string;
	readonly onUpdate?: ChangeType;
	readonly onDelete?: ChangeType;
}

ChangeType

Элиас, содержащий допустимое поведение

type ChangeType =
	| "CASCADE"
	| "SET NULL"
	| "RESTRICT"
	| "NO ACTION"
	| "SET DEFAULT";

Query

Дженерик, описывающий базовый запрос

Поля:

[Опциональный] filters[TableFilters] - фильтры
[Опциональный] orderBy[Ordering] - порядок сортировки
[Опциональный] limit[TablePage] - предел выборки
[Опциональный] groupBy[Ordering] - группировка

interface Query<TF extends AnyObject> {
	readonly filters?: TableFilters<TF> | TableFilters<TF>[];
	readonly orderBy?: OrderBy<TF>;
	readonly limit?: Limit;
	readonly groupBy?: GroupBy<TF> | MappedObject<GroupBy<AnyObject>>;
}

TableFilters

Объект фильтров запроса

Поля:

[Опциональный] FieldName[Expressions] - фильтр конкретного поля

type TableFilters<TF extends AnyObject> = {
	readonly [key in keyof TF]?: Expressions<TF[key]>;
};

Limit

Объект, описывающий предел выборки

Поля:

[Обязательный] page[number] - страница смещения
[Обязательный] countOnPage[number] - количество строк на странице

interface Limit {
	readonly page: number;
	readonly countOnPage: number;
}

GroupBy

Элиас, описывающий поля для группировки

type GroupBy<TF extends AnyObject> = Array<keyof TF>

OrderBy

Объект, описывающий сортировку в запросе

type OrderBy<TF extends AnyObject> = {
	readonly [key in keyof TF]?: OrderDirection;
};

OrderingDirection

Элиас, содержащий допустимые значения направления сортировки

Значения

DESC - от большего к меньшему ASC - от меньшего к большему

type OrderingDirection = "DESC" | "ASC";

SelectQuery

Производный тип от [Query], описывающий параметры запроса для выборки

Поля:

[Опциональный] joinedTable[JoinTable] - таблицы, которые нужно присоединить
[Опциональный] excludes[ExcludeFields|MappedObject<ExcludeFields>] - поля, которые будут исключены из запроса
[Опциональный] includes[IncludesFields|MappedObject<IncludesFields>] - только эти поля будут включены в запрос

[Опциональный] count[Count|MappedObject<Count>] - описание функции count
[Опциональный] distinct[boolean] - только уникальные записи

interface SelectQuery<TF extends AnyObject> extends Query<TF> {
	readonly joinedTable?: JoinTable;
	readonly excludes?:
		| ExcludeFields<TF>
		| MappedObject<ExcludeFields<AnyObject>>;
	readonly includes?:
		| IncludeFields<TF>
		| MappedObject<IncludeFields<AnyObject>>;
	readonly count?: Count<TF> | MappedObject<Count<AnyObject>>;
	readonly distinct?: boolean;
}

JoinTable

Интерфейс, описывающий соединение таблиц

Поля:

[Обязательный] enable[boolean] - включено ли соединение
[Опциональный] joinTable[Array<Join|string>] - список включаемых таблиц
[Опциональный] recurseInclude[boolean] - должны ли таблицы соединяться рекурсивно

interface JoinTable {
	readonly enable: boolean;
	readonly joinTable?: Array<Join | string>;
	readonly recurseInclude?: boolean;
}

Join

Тип, описывающий включение таблицы

Поля:

[Обязательный] table[string] - имя таблицы
[Опциональный] invert[boolean] - инвертирована ли связь(является ли подсоединяемая таблица подчиненной)

ExcludeFields

Тип, описывающий исключаемые из запроса поля

type ExcludeFields<TF extends AnyObject> = Array<keyof TF>;

IncludeFields

Тип описывающий включаемые в запрос поля. Так же есть возможность переименовать поля

type IncludeFields<TF extends AnyObject> = Array<AssociateField<TF> | keyof TF>;

AssociateField

Кортеж, содержащий табличное и новое название поля

type AssociateField<TF extends AnyObject> = [keyof TF, string];

Count

Массив, описывающий, что нужно считать в запросе

type Count<TF extends AnyObject> = Array<AssociateField<TF, "*">>;

MappedObject

Обычный объект, где строка - ключ, а переданный тип - значение

type MappedObject<T> = {
	[key: string]: T;
};

AlterTableRequest

Элиас дженерик, соединяющий все запросы на изменение структуры таблицы: AddColumn, DropColumn, ModifyColumn, AlterColumn, AddForeignKey, DropForeignKey, AddPrimaryKey and DropPrimaryKey

type AlterTableRequest<T extends ValidSQLType, TF extends AnyObject> =
	| AddColumn<T>
	| DropColumn<TF>
	| ModifyColumn<TF, T>
	| AlterColumn<TF, T>
	| AddForeignKey<TF>
	| DropForeignKey<TF>
	| AddPrimaryKey<TF>
	| DropPrimaryKey;

AddColumn

Дженерик, описывающий запрос на добавление поля

Поля:

[Обязательный] type[ADD COLUMN] - тип запроса на ихменение структуры
[Обязательный] fieldName[string] - имя поля
[Обязательный] field[AlterFieldConfig] - конфиг нового поля

interface AddColumn<T extends ValidSQLType> {
	readonly type: "ADD COLUMN";
	readonly fieldName: string;
	readonly field: AlterFieldConfig<T>;
}

DropColumn

Дженерик, описывающий запрос на удаление поля

Поля:

[Обязательный] type[DROP COLUMN] - тип запроса на ихменение структуры
[Обязательный] fieldName[string] - имя поля

interface DropColumn<TF extends AnyObject> {
	readonly type: "DROP COLUMN";
	readonly fieldName: keyof TF;
}

ModifyColumn

Дженерик, описывающий запрос на изменение поля

Поля:

[Обязательный] type[MODIFY COLUMN] - тип запроса на ихменение структуры
[Обязательный] fieldName[string] - имя поля
[Обязательный] field[AlterFieldConfig] - новый конфиг поля

interface ModifyColumn<TF extends AnyObject, T extends ValidSQLType> {
	readonly type: "MODIFY COLUMN";
	readonly fieldName: keyof TF;
	readonly field: AlterFieldConfig<T>;
}

AlterColumn

Дженерик, описывающий запрос на изменения значения по умолчанию

Поля:

[Обязательный] type[ALTER COLUMN] - тип запроса на ихменение структуры
[Обязательный] fieldName[string] - имя поля
[Обязательный] default[T] - новое значение по умолчанию

interface AlterColumn<TF extends AnyObject, T extends ValidSQLType> {
	readonly type: "ALTER COLUMN";
	readonly fieldName: keyof TF;
	readonly default: T;
}

AddForeignKey

Дженерик, описывающий запрос на добавление внешнего ключа

Поля:

[Обязательный] type[ADD FOREIGN KEY] - тип запроса на ихменение структуры
[Обязательный] fieldName[string] - имя поля
[Обязательный] reference[Reference] - описание ссылки на таблицу

interface AddForeignKey<TF extends AnyObject> {
	readonly type: "ADD FOREIGN KEY";
	readonly fieldName: keyof TF;
	readonly reference: Reference;
}

DropForeignKey

Дженерик, описывающий запрос на сброс внешнего ключа

Поля:

[Обязательный] type[DROP FOREIGN KEY] - тип запроса на ихменение структуры
[Обязательный] fieldName[string] - имя поля

interface DropForeignKey<TF extends AnyObject> {
	readonly type: "DROP FOREIGN KEY";
	readonly fieldName: keyof TF;
}

AddPrimaryKey

Дженерик, описывающий запрос на добавление первичного(ых) ключей

Поля:

[Обязательный] type[ADD PRIMARY KEY] - тип запроса на ихменение структуры
[Обязательный] fieldName[string] - имя поля(ей)

interface AddPrimaryKey<TF extends AnyObject> {
	readonly type: "ADD PRIMARY KEY";
	readonly fieldNames: keyof TF[];
}

DropPrimaryKey

Дженерик, описывающий запрос на сброс первичного ключа

Поля:

[Обязательный] type[DROP PRIMARY KEY] - тип запроса на ихменение структуры

interface DropPrimaryKey {
	readonly type: "DROP PRIMARY KEY";
}

AlterFieldConfig

Элиас, описывающий тип поля в изменении структуры

type AlterFieldConfig<T extends ValidSQLType> = Omit<
	FieldConfig<T>,
	"isPrimaryKey" | "default"
>;

Description

Дженерик, описывающий поле, возвращаемое из метода describe

Поля:

[Обязательный] Field[string] - имя поля
[Обязательный] Type[string] - тип поля
[Обязательный] Null[Yes|No] - может ли быть null
[Обязательный] Key[string] - тип ключа
[Обязательный] Default[ValidSQLType] - значение по умолчанию
[Обязательный] Extra[string] - экстра модификаторы

interface Description<TF extends AnyObject> {
	readonly Field: keyof TF;
	readonly Type: string;
	readonly Null: "YES" | "NO";
	readonly Key: "PRI" | "";
	readonly Default: ValidSQLType | null;
	readonly Extra: string;
}

Ошибки

В процессе

Files

ru.md

Latest commit

History

ru.md

File metadata and controls

Документация

Главы

Подключение

Таблица

Конструктор

Инициализация

Внесение

Выборка

Удаление

Обновление

Сброс

Описание

Структура

Типы

TableConfig

Fields

FieldConfig

SQLTypes

Expressions

ForeignKeys

Expression

Operators

Reference

ChangeType

Query

TableFilters

Limit

GroupBy

OrderBy

OrderingDirection

SelectQuery

JoinTable

Join

ExcludeFields

IncludeFields

AssociateField

Count

MappedObject

AlterTableRequest

AddColumn

DropColumn

ModifyColumn

AlterColumn

AddForeignKey

DropForeignKey

AddPrimaryKey

DropPrimaryKey

AlterFieldConfig

Description

Ошибки