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

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:143

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'

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

Accessors

data

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

platform

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

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

userId

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

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

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:413

attributeLabels

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

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

destroy

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

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

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:222

`Protected`getId

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

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

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('Пользователь не найден');
}

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:353

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:204

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:528

remove

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

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

rules

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

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

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:375

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:318

tableName

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

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

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:394

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:319

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:468

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:496

Class UsersData

Example

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns UsersData

Example

Properties

Protected_appContext

queryData

startIndex

state

Example

Static ReadonlyTABLE_NAME

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

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

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

`Protected`_appContext

`Static` `Readonly`TABLE_NAME

`Protected`getId