API: Модели

Документация API для работы с моделями данных.

Создание модели

const Model = kodzero.createModel<T, M>(options)

Типовые параметры

Параметр	Описание
T	Интерфейс данных. Должен содержать _id: string | null
M	Интерфейс кастомных методов (опционально)

Параметры options

Параметр	Тип	Обязательный	Описание
collection	string	✅	Название коллекции
schema	object	❌	Схема валидации

Статические методы

Model.get(id)

Получает документ по ID и возвращает экземпляр модели.

static get(id: string): Promise<ModelInstance<T, M>>

Параметр	Тип	Описание
id	string	ID документа

Возвращает: Экземпляр модели с данными.

const user = await User.get('user_id')
user.set('name', 'Новое имя')
await user.save()

---

Model.find(id)

Получает документ по ID и возвращает простой объект.

static find(id: string): Promise<T>

Возвращает: Объект с данными документа.

const userData = await User.find('user_id')
console.log(userData.name)

---

Model.findMany(options?)

Получает список документов.

static findMany(options?: FindManyOptions): Promise<T[]>

FindManyOptions

Параметр	Тип	Описание
page	number	Номер страницы
perPage	number	Документов на страницу
search	string	Поисковый запрос
sort	string	Сортировка (префикс - для DESC)
fields	string[]	Поля для возврата

const users = await User.findMany({
  page: 1,
  perPage: 10,
  sort: '-createdAt'
})

---

Model.findManyPaginated(options?, page?, perPage?)

Получает список с информацией о пагинации.

static findManyPaginated(
  options?: FindManyOptions | {},
  page?: number,
  perPage?: number
): Promise<PaginatedResult<T>>

Возвращает: Объект PaginatedResult. См. API: Пагинация.

const result = await User.findManyPaginated({}, 1, 25)
console.log(result.data)        // массив документов
console.log(result.state.total) // всего документов

---

Model.create(data)

Создаёт новый документ.

static create(data: T): Promise<T>

Возвращает: Созданный документ с присвоенным _id.

const newUser = await User.create({
  _id: null,
  name: 'Иван',
  email: 'ivan@example.com'
})
console.log(newUser._id) // 'generated_id'

---

Model.createMany(records)

Создаёт несколько документов.

static createMany(records: T[]): Promise<T[]>

const users = await User.createMany([
  { _id: null, name: 'Иван', email: 'ivan@example.com' },
  { _id: null, name: 'Мария', email: 'maria@example.com' }
])

---

Model.update(id, data)

Обновляет документ по ID.

static update(id: string, data: Partial<T>): Promise<T>

const updated = await User.update('user_id', {
  name: 'Новое имя'
})

---

Model.updateMany(updates)

Обновляет несколько документов.

static updateMany(updates: Partial<T>[]): Promise<T[]>

Требуется _id

Каждый объект должен содержать _id.

const updated = await User.updateMany([
  { _id: 'id1', name: 'Имя 1' },
  { _id: 'id2', name: 'Имя 2' }
])

---

Model.delete(id)

Удаляет документ по ID.

static delete(id: string): Promise<boolean>

const deleted = await User.delete('user_id')
// deleted: true

---

Model.deleteMany(ids)

Удаляет несколько документов.

static deleteMany(ids: string[]): Promise<Record<string, boolean>>

const results = await User.deleteMany(['id1', 'id2', 'id3'])
// { 'id1': true, 'id2': true, 'id3': true }

---

Model.registerMethod(name, fn)

Регистрирует кастомный метод.

static registerMethod<K extends keyof M>(name: K, fn: M[K]): void

interface UserMethods {
  getFullName: () => string
}

const User = kodzero.createModel<User, UserMethods>({
  collection: 'users'
})

User.registerMethod('getFullName', function() {
  return `${this.data().firstName} ${this.data().lastName}`
})

Методы экземпляра

instance.data()

Возвращает данные модели.

data(): T

const user = new User({ _id: null, name: 'Иван' })
console.log(user.data().name) // 'Иван'

---

instance.set(key, value) или instance.set(data)

Устанавливает значения полей.

set(key: string, value: any): T
set(data: Record<string, any>): T

// Одно поле
user.set('name', 'Пётр')

// Несколько полей
user.set({
  name: 'Пётр',
  email: 'petr@example.com'
})

// Вложенные поля
user.set('address.city', 'Москва')

---

instance.save()

Сохраняет документ. Создаёт новый или обновляет существующий.

save(): Promise<T>

const user = new User({ _id: null, name: 'Иван' })
await user.save()  // создаёт документ

user.set('name', 'Пётр')
await user.save()  // обновляет документ

---

instance.create()

Создаёт новый документ.

create(): Promise<T>

---

instance.update()

Обновляет существующий документ.

update(): Promise<T>

Требуется _id

Документ должен иметь _id для обновления.

---

instance.delete()

Удаляет документ.

delete(): Promise<boolean>

await user.delete()

---

instance.validate()

Валидирует данные по схеме.

validate(): ValidationResult

interface ValidationResult {
  ok: boolean
  errors: string[]
  joinErrors: () => string
}

const result = user.validate()

if (!result.ok) {
  console.log(result.errors)       // ['name is required']
  console.log(result.joinErrors()) // 'name is required'
}

Статические свойства

Свойство	Тип	Описание
Model.host	string	URL бэкенда
Model.collection	string	Название коллекции

Свойства экземпляра

Свойство	Тип	Описание
instance.id	string | null	ID документа
instance.modelData	T	Данные модели
instance.schema	Schema | null	Схема валидации