Class UsersData

Модель для работы с пользовательскими данными. Предоставляет единый интерфейс для работы с данными пользователей во всех поддерживаемых платформах.

Основные возможности:

Сохранение состояния пользователя между сессиями
Хранение метаданных (например, статистика использования)
Поддержка как файлового хранилища, так и БД
Автоматическая сериализация/десериализация данных

Example

Сохранение прогресса пользователя (через addCommand — колбэк фреймворк ожидает):

import { UsersData } from 'umbot';

interface IGameProgress {
    progress?: number;
}

bot.addCommand('progress', ['прогресс'], async (_text, ctx) => {
    // Загрузка данных пользователя
    const userData = new UsersData(ctx.appContext);
    userData.userId = ctx.userId;

    if (await userData.getOne()) {
        // data может быть string | Record<string,unknown> | null — сужаем тип
        const data = userData.data as IGameProgress | null;
        const progress = data?.progress ?? 0;
        ctx.text = `Ваш текущий прогресс: ${progress}%`;
    } else {
        userData.data = { progress: 0 };
        userData.meta = { firstVisit: new Date().toISOString() };
        await userData.save();
        ctx.text = 'Добро пожаловать в игру!';
    }
});

Example

Работа с разными платформами:

import { T_ALISA, T_TELEGRAM } from 'umbot/plugins';

const userData = new UsersData(appContext);

// Для Алисы
userData.platform = T_ALISA;

// Для Telegram
userData.platform = T_TELEGRAM;

Hierarchy (View Summary)

Model<IUserDataModelState>
- UsersData

Index

Accessors

data

get data(): TDataType
Основные данные пользователя. Содержит основное состояние пользователя, например:
- Прогресс в игре
- Сохраненные настройки
- История действий
- Другие пользовательские данные
Returns TDataType
Remarks
При сохранении в БД автоматически преобразуется в JSON строку
- Defined in models/UsersData.ts:218
set data(data: TDataType): void
Устанавливает основные данные пользователя.
Parameters
- data: TDataType
  Основные данные пользователя
Returns void
- Defined in models/UsersData.ts:226

platform

get platform(): string
Тип платформы пользователя. Определяет платформу, с которой работает пользователь.

Returns string
- Defined in models/UsersData.ts:242
set platform(platform: string): void
Тип платформы пользователя. Определяет платформу, с которой работает пользователь.
Parameters
- platform: string
Returns void
- Defined in models/UsersData.ts:234

userId

get userId(): string | number | null | undefined
Уникальный идентификатор пользователя. Может быть строкой или числом в зависимости от платформы.

Returns string | number | null | undefined
Example
```
"123456789" для Telegram (строка), 123456789 для VK (число)
```
- Defined in models/UsersData.ts:176
set userId(userId: string | number | null): void
Устанавливает уникальный идентификатор пользователя.
Parameters
- userId: string | number | null
  Идентификатор пользователя
Returns void
- Defined in models/UsersData.ts:184

Constructors

constructor

new UsersData(appContext: AppContext): UsersData
Создает экземпляр модели пользовательских данных. Предоставляет унифицированный интерфейс для хранения данных пользователя.
Parameters
- appContext: AppContext
  Контекст приложения
Returns UsersData
Example
```
const userData = new UsersData(appContext);
userData.userId = 'user123';
userData.platform = 'telegram';
```
Overrides Model.constructor
- Defined in models/UsersData.ts:145

Methods

add

add(): Promise<boolean>
Добавляет новую запись в базу данных

Returns Promise<boolean>
Promise с результатом операции
Example
```
model.state.name = 'John';
await model.add();
```
Inherited from Model.add
- Defined in models/db/Model.ts:447

attributeLabels

attributeLabels(): IUserDataModelState
Возвращает описания атрибутов модели. Используется для отображения понятных названий полей.

Returns IUserDataModelState
Описания атрибутов
Overrides Model.attributeLabels
- Defined in models/UsersData.ts:270

destroy

destroy(): void | Promise<void>
Закрывает соединение с базой данных

Returns void | Promise<void>
Example
```
model.destroy();
```
Inherited from Model.destroy
- Defined in models/db/Model.ts:572

escapeString

escapeString(text: string | number): string
Экранирует специальные символы в строке
Parameters
- text: string | number
  Строка или число для экранирования
Returns string
Экранированная строка
Example
```
const safe = model.escapeString("O'Connor");
```
Inherited from Model.escapeString
- Defined in models/db/Model.ts:229

`Protected`getId

getId(): TKey
Первичный ключ таблицы — userId.

Returns TKey
Overrides Model.getId
- Defined in models/UsersData.ts:158

getOne

getOne(): Promise<boolean>

Ищет одну запись в хранилище по первичному ключу userId (platform/meta в поиске не участвуют — фильтруйте результат сами при необходимости).

Returns Promise<boolean>

true, если запись найдена

Example

const userData = new UsersData(appContext);
userData.userId = 'user123';
if (await userData.getOne()) {
  // data может быть string | Record<string,unknown> | null | undefined:
  // сужаем тип перед чтением полей
  const progress = (userData.data as Record<string, unknown>)?.progress;
  console.log('Пользователь найден, прогресс:', progress);
} else {
  console.log('Пользователь не найден');
}

`Protected`getUniqueKeys

getUniqueKeys(): string[]
userId уникален только в пределах платформы: пользователь Telegram 42 и пользователь VK 42 — разные люди, поэтому платформа входит в ключ записи.

Returns string[]
Поле платформы как часть ключа записи
Overrides Model.getUniqueKeys
- Defined in models/UsersData.ts:167

init

init(data: IDbResult<unknown> | IDbResult<unknown>[] | null): void
Инициализирует модель данными. Преобразует JSON строки meta и data в объекты при загрузке из БД.
Parameters
- data: IDbResult<unknown> | IDbResult<unknown>[] | null
  Данные для инициализации
Returns void
Remarks
- При парсинге data, ошибки игнорируются для обеспечения обратной совместимости
- meta парсится только если это JSON-строка, начинающаяся с "{" или "["; data парсируется всегда, когда это строка (без проверки первого символа)
Example
```
const userData = new UsersData(appContext);
userData.init({
  userId: 'user123',
  meta: '{"lastVisit":"2024-03-20T12:00:00Z"}',
  data: '{"progress":75}',
  platform: T_TELEGRAM
});
// init() распарсила JSON-строки meta и data в объекты
console.log((userData.meta as { lastVisit?: string }).lastVisit); // строка '2024-03-20T12:00:00Z' (JSON.parse не создаёт Date)
console.log(userData.data.progress); // 75
```
Overrides Model.init
- Defined in models/UsersData.ts:364

isConnected

isConnected(): boolean | Promise<boolean>
Проверяет состояние подключения к базе данных

Returns boolean | Promise<boolean>
true если подключение активно (синхронно false без адаптера БД, иначе Promise от адаптера)
Example
```
const isConnected = await model.isConnected();
if (isConnected) {
  // Выполнение операций с базой данных
}
```
Inherited from Model.isConnected
- Defined in models/db/Model.ts:211

query

query(callback: TQueryCb): unknown
Выполняет произвольный запрос к базе данных

Типы client/db зависят от подключённого адаптера БД — для MongoAdapter это MongoClient и Db из драйвера mongodb. Для FileAdapter _query не реализован — метод вернёт null.
Parameters
- callback: TQueryCb
  Функция обратного вызова для выполнения запроса
Returns unknown
Результат выполнения запроса
Example
```
import type { MongoClient, Db } from 'mongodb';

const result = await model.query(async (client: MongoClient, db: Db) => {
  const collection = db.collection('users');
  return await collection.aggregate([
    { $match: { age: { $gt: 18 } } },
    { $group: { _id: '$city', count: { $sum: 1 } } }
  ]).toArray();
});
```
Inherited from Model.query
- Defined in models/db/Model.ts:557

remove

remove(): Promise<boolean>
Удаляет запись из базы данных

Returns Promise<boolean>
Promise - true если удаление успешно
Example
```
await model.remove();
```
Inherited from Model.remove
- Defined in models/db/Model.ts:471

rules

rules(): IModelRules[]
Определяет правила валидации полей модели.

Returns IModelRules[]
Массив правил валидации
Overrides Model.rules
- Defined in models/UsersData.ts:260

save

save(isNew?: boolean): Promise<boolean>
Сохраняет данные модели в базу данных Если запись существует - обновляет, иначе создает новую
Parameters
- isNew: boolean = false
  Флаг создания новой записи
Returns Promise<boolean>
Promise с результатом операции
Example
```
model.state.name = 'John';
await model.save(); // Обновление существующей записи
await model.save(true); // Создание новой записи
```
Inherited from Model.save
- Defined in models/db/Model.ts:409

selectOne

selectOne(): Promise<ISelectOneModelRes>
Выполняет поиск записи по первичному ключу

Returns Promise<ISelectOneModelRes>
Promise с результатом запроса
Example
```
const result = await model.selectOne();
if (result.status) {
  model.init(result.data ?? null); // data опционален, init() допускает null
}
```
Inherited from Model.selectOne
- Defined in models/db/Model.ts:361

tableName

tableName(): string
Возвращает название таблицы/файла для хранения данных.

Returns string
Название таблицы для хранения данных пользователей
Overrides Model.tableName
- Defined in models/UsersData.ts:251

update

update(): Promise<boolean>
Обновляет существующую запись в базе данных

Returns Promise<boolean>
Promise с результатом операции
Example
```
model.state.name = 'John';
await model.update();
```
Inherited from Model.update
- Defined in models/db/Model.ts:428

validate

validate(): void
Валидирует значения перед сохранением. Преобразует объекты meta и data в JSON при сохранении в БД.

Returns void
Remarks
Не выбрасывает исключений: циклические ссылки в meta/data автоматически заменяются на '[Circular]'.
Example
```
userData.meta = { lastVisit: new Date() };
userData.data = { progress: 75 };
userData.validate(); // meta и data будут преобразованы в JSON
```
Overrides Model.validate
- Defined in models/UsersData.ts:330

where

where(
where?: string | IQueryData,
isOne?: boolean,
): Promise<IModelRes<IDataValue>>
Выполняет произвольный запрос к базе данных
Parameters
- where: string | IQueryData = '1'
  Условия запроса
- isOne: boolean = false
  Флаг выборки одной записи
Returns Promise<IModelRes<IDataValue>>
Promise с результатом запроса
Example
```
// Объект условий — точные значения полей
const res = await model.where({ age: 25 });

// Строка условий формата getQueryData
const res2 = await model.where('`age`=25 `status`="active"');
```
Inherited from Model.where
- Defined in models/db/Model.ts:497

whereOne

whereOne(where?: string | IQueryData): Promise<boolean>
Выполняет запрос с выборкой одной записи
Parameters
- where: string | IQueryData = '1'
  Условия запроса
Returns Promise<boolean>
Promise - true если запись найдена
Example
```
const found = await model.whereOne({ id: 1 });
if (found) {
  console.log('Запись найдена');
}
```
Inherited from Model.whereOne
- Defined in models/db/Model.ts:525

Properties

`Protected`_appContext

_appContext: AppContext

Контекст приложения.

queryData

queryData: IQuery

Объект для хранения параметров запроса. Содержит условия поиска и данные для обновления

startIndex

startIndex: number = 0

Начальный индекс для итерации по данным. Используется при инициализации модели из массива

state

state: Partial<TState> = {}

Состояние модели. Содержит текущие значения всех атрибутов

Example

// Установка значений
this.state.username = 'John';
this.state.age = 25;

// Получение значений
console.log(this.state.username);

`Static` `Readonly`TABLE_NAME

TABLE_NAME: "UsersData" = 'UsersData'

Название таблицы для хранения данных пользователей.

Class UsersData

Example

Example

Hierarchy (View Summary)

Index

Accessors

Constructors

Methods

Properties

Accessors

data

Returns TDataType

Remarks

Parameters

Returns void

meta

Returns TMetaType

Remarks

Parameters

Returns void

platform

Returns string

Parameters

Returns void

userId

Returns string | number | null | undefined

Example

Parameters

Returns void

Constructors

constructor

Parameters

Returns UsersData

Example

Methods

add

Returns Promise<boolean>

Example

attributeLabels

Returns IUserDataModelState

destroy

Returns void | Promise<void>

Example

escapeString

Parameters

Returns string

Example

ProtectedgetId

Returns TKey

getOne

Returns Promise<boolean>

Example

ProtectedgetUniqueKeys

Returns string[]

init

Parameters

Returns void

Remarks

Example

isConnected

Returns boolean | Promise<boolean>

Example

query

Parameters

Returns unknown

Example

remove

Returns Promise<boolean>

Example

rules

Returns IModelRules[]

save

Parameters

Returns Promise<boolean>

Example

selectOne

Returns Promise<ISelectOneModelRes>

Example

tableName

Returns string

`Protected`getId

`Protected`getUniqueKeys

`Protected`_appContext

`Static` `Readonly`TABLE_NAME