@cuboapp/api-backend 1.0.38 → 3.0.1

package/src/crdt/index.ts

@@ -0,0 +1,110 @@
+import type {
+  CuboCrdtServer,
+  CuboCrdtServerDocumentOrigin,
+  CuboCrdtServerSubscribe,
+  CuboCrdtSocketClient
+} from '@cuboapp/crdt'
+import { CuboApiEntitiesMap, CuboEntity } from '@cuboapp/types'
+import type { WsServer, WsServerSocket } from '@cuboapp/ws'
+
+import type { CuboBackendApi } from '../core'
+
+/** Тип фабрики, импортируемый только как тип (рантайм-зависимость опциональна). */
+type CreateCrdtServer = typeof import('@cuboapp/crdt')['createCrdtServer']
+
+/**
+ * Встроенный адаптер cubo-crdt. Инкапсулирует всю обвязку, которую раньше
+ * приходилось писать в каждом приложении руками (old.ts):
+ *  - fetchRows: подписка тянет строки через api.getMany
+ *  - storeRow: дебаунс-сохранение состояния дока обратно в БД через api.updateOne
+ *  - checkRowIsSutable: фильтрация строк под подписку (augmentation.filterRowForCrdtEvent)
+ *  - push create/update/delete: автоматически из CRUD-методов ядра
+ *
+ * Включается одной опцией `crdt: { ws }` у CuboBackendApi и работает для всех
+ * сущностей с флагом `entity.crdt === true`.
+ */
+export class CuboCrdtAdapter<T extends CuboApiEntitiesMap<T>, A> {
+  public readonly server: CuboCrdtServer<T, A>
+
+  constructor(
+    private api: CuboBackendApi<T, A>,
+    ws: WsServer,
+    createCrdtServer: CreateCrdtServer,
+    private debug = false
+  ) {
+    const entities = (this.api.options.entities || []).filter((e) => e.crdt).map((e) => e.alias as Extract<keyof T, string>)
+
+    this.server = createCrdtServer<T, A>({
+      ws,
+      entities,
+      debug: this.debug,
+
+      // подписка -> строки из БД (хуки CRUD пропускаем, чтобы не зациклить)
+      fetchRows: async (client, subscribe: CuboCrdtServerSubscribe) => {
+        const { rows } = await this.api.getMany(subscribe.entity as Extract<keyof T, string>, { query: subscribe.filters }, {
+          auth: (client as CuboCrdtSocketClient<A>).auth,
+          excludeHooks: ['afterCrdtCreate', 'afterCrdtUpdate']
+        })
+
+        return rows as T[Extract<keyof T, string>][]
+      },
+
+      // сохранение состояния дока обратно в БД (origin прокидываем, чтобы не пушить заново)
+      storeRow: async (entity, entity_id, body, { origin, client }) => {
+        await this.api.updateOne(entity as Extract<keyof T, string>, { query: { id: entity_id }, body }, {
+          crdt: origin,
+          performer_id: (client as any)?.auth?.user_id,
+          auth: (client as any)?.auth,
+          excludeHooks: ['afterCrdtUpdate']
+        })
+      },
+
+      // фильтрация строки под конкретную подписку
+      checkRowIsSutable: (base, { entity, subscribe, row }) => {
+        const augmentation = this.api.options.augmentations?.[entity as Extract<keyof T, string>]
+        if (augmentation?.filterRowForCrdtEvent) {
+          return augmentation.filterRowForCrdtEvent(row, subscribe.filters || {})
+        }
+        return base
+      }
+    })
+  }
+
+  public async init() {
+    await this.server.init()
+  }
+
+  public async destroy() {
+    await this.server.destroy()
+  }
+
+  // lifecycle клиентов — приложение вызывает из ws onConnect/onDisconnect
+  public addClient(client: WsServerSocket<{ auth?: A }>) {
+    this.server.addClient(client)
+  }
+
+  public removeClient(client: WsServerSocket) {
+    this.server.removeClient(client)
+  }
+
+  /** Поддерживается ли CRDT для сущности. */
+  public isSupported(entity: CuboEntity): boolean {
+    return !!entity.crdt
+  }
+
+  // пуш изменений документов из CRUD-методов ядра
+  public pushCreate(entity: CuboEntity, row: any) {
+    if (!entity.crdt) return
+    this.server.ensureDocument(entity.alias as Extract<keyof T, string>, row)
+  }
+
+  public pushUpdate(entity: CuboEntity, row: any) {
+    if (!entity.crdt) return
+    this.server.ensureDocument(entity.alias as Extract<keyof T, string>, row)
+  }
+
+  public pushDelete(entity: CuboEntity, row: any, origin?: CuboCrdtServerDocumentOrigin) {
+    if (!entity.crdt) return
+    this.server.deleteDocument(entity.alias as Extract<keyof T, string>, row, origin)
+  }
+}

package/src/dialects/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Слой диалектов БД. Раньше SQL-генерация была заточена под Postgres
+ * (`ilike`, `returning`). Теперь различия спрятаны за интерфейсом CuboDialect,
+ * и движок одинаково работает с Postgres и MySQL.
+ *
+ * Сам @cuboapp/database уже умеет insert/update/delete под оба диалекта;
+ * здесь покрываются различия SELECT-билдера (в первую очередь ILIKE и
+ * пакетные insert/update).
+ */
+export type CuboDialectName = 'postgres' | 'mysql'
+
+export interface CuboDialect {
+  name: CuboDialectName
+
+  /** Регистронезависимый LIKE. Postgres — нативный ILIKE; MySQL — LOWER() LIKE LOWER(). */
+  ilike(field: string, param: string, isNot: boolean): string
+
+  /** Поддерживает ли RETURNING (Postgres). У MySQL — insertId / lastval. */
+  supportsReturning: boolean
+}
+
+export const postgresDialect: CuboDialect = {
+  name: 'postgres',
+  supportsReturning: true,
+  ilike: (field, param, isNot) => `${field} ${isNot ? 'not ilike' : 'ilike'} :${param}`
+}
+
+export const mysqlDialect: CuboDialect = {
+  name: 'mysql',
+  supportsReturning: false,
+  ilike: (field, param, isNot) => `lower(${field}) ${isNot ? 'not like' : 'like'} lower(:${param})`
+}
+
+export function getDialect(name?: string | null): CuboDialect {
+  return name === 'mysql' ? mysqlDialect : postgresDialect
+}

package/src/helpers/index.ts

@@ -3,7 +3,7 @@ import { Database, createDatabase } from '@cuboapp/database'
 import { CuboApiEntitiesMap, CuboEntity, CuboEntityField, CuboEntityFieldExtra, CuboEntityFieldType } from '@cuboapp/types'
 import { cloneDeep } from '@cuboapp/utils'
 
-import { CuboBackendApi } from '../..'
+import type { CuboBackendApi } from '../core'
 import {
   CUBO_CRUD_DEFAULT_FIELDS,
   CUBO_CRUD_DEFAULT_PAGE_LIMIT,
@@ -12,19 +12,25 @@ import {
   CUBO_CRUD_QUERY_KEY_REGEX,
   CUBO_CRUD_QUERY_SYMBOL_NOT
 } from '../constants'
-import { CuboBackendApiDbConnectionType, CuboCrudFindQuery, CuboCrudRequest } from '../types'
+import { CuboDialect, getDialect } from '../dialects'
+import { CuboBackendApiDbConnectionType, CuboCrudFindQuery, CuboCrudRequest, CuboDataFilter, CuboDataFiltersQuery } from '../types'
 
 import { ApiHelpersConvert } from './convert'
 import { ApiHelpersData } from './data'
 import { ApiHelpersWithes } from './withes'
 
-export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A> {
+export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A = unknown> {
   constructor(public api: CuboBackendApi<T, A>) {}
 
   public withes = new ApiHelpersWithes<T>(this)
   public convert = new ApiHelpersConvert<T>(this)
   public data = new ApiHelpersData<T>()
 
+  /** Текущий диалект БД (postgres по умолчанию). */
+  public get dialect(): CuboDialect {
+    return getDialect(this.api.options.db?.options?.dialect as string | undefined)
+  }
+
   private cache: Record<string, any> = {}
   private fetching: Record<string, Promise<any> | null> = {}
   private connections: Partial<Record<CuboBackendApiDbConnectionType, Database>> = {}
@@ -237,7 +243,8 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A> {
     // console.log(field, condition, value)
     switch (condition) {
       case CUBO_CRUD_QUERY_CONDITION.ILIKE:
-        conditions.push(`${field} ${is_not ? 'not ilike' : 'ilike'} :${replacement}`)
+        // диалект-зависимо: postgres -> ILIKE, mysql -> LOWER() LIKE LOWER()
+        conditions.push(this.dialect.ilike(field, replacement, is_not))
         replacements[replacement] = '%' + value + '%'
         break
       case CUBO_CRUD_QUERY_CONDITION.LIKE:
@@ -309,6 +316,106 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A> {
     }
   }
 
+  /**
+   * Разворачивает структурный query-параметр `filters` (JSON вида
+   * `{"filters":[{"field","op","value"}],"sort":[{"field","dir"}]}`) в обычные
+   * flat-DSL записи `req.query`. Дальше их подхватывает общий пайплайн
+   * (createFindQuery + withes): вложенные связи по dot-notation, приведение типов
+   * и сортировка работают без дополнительного кода. Мутирует и возвращает `query`.
+   *
+   * Ограничения наследуются от flat-DSL: одно условие на поле (при нескольких
+   * фильтрах на одно поле побеждает последний) и значения без `:` (двоеточие —
+   * разделитель условий). Для экзотики — `queryOptions.raw`.
+   */
+  public applyDataFilters(query: Record<string, any>): Record<string, any> {
+    const raw = query?.filters
+    if (raw === undefined || raw === null || raw === '') {
+      return query
+    }
+
+    let parsed: CuboDataFiltersQuery
+    try {
+      parsed = typeof raw === 'string' ? JSON.parse(raw) : raw
+    } catch {
+      throw { status: 400, text: 'Invalid "filters" query param: must be valid JSON' }
+    }
+
+    // убираем сырой ключ, чтобы пайплайн не принял "filters" за поле-условие
+    delete query.filters
+
+    for (const filter of parsed?.filters || []) {
+      if (!filter || !filter.field) {
+        continue
+      }
+
+      const value = this.dataFilterToQueryValue(filter)
+      if (value !== undefined) {
+        query[filter.field] = value
+      }
+    }
+
+    if (parsed?.sort?.length) {
+      const sort = parsed.sort
+        .filter((s) => s && s.field)
+        .map((s) => (s.dir === 'desc' ? '-' : '') + s.field)
+        .join(',')
+
+      if (sort) {
+        query.sort = sort
+      }
+    }
+
+    return query
+  }
+
+  /** Маппинг `CuboDataFilter.op` -> flat-DSL значение движка (`ilike:foo`, `not:gt:5`, `in:1,2`, ...). */
+  private dataFilterToQueryValue(filter: CuboDataFilter): string | undefined {
+    const C = CUBO_CRUD_QUERY_CONDITION
+    const NOT = CUBO_CRUD_QUERY_SYMBOL_NOT
+    const v = filter.value
+    const list = () => (Array.isArray(v) ? v.join(',') : `${v}`)
+
+    switch (filter.op) {
+      case 'eq':
+        return `${v}`
+      case 'ne':
+        return `${NOT}:${v}`
+      case 'contains':
+        return `${C.ILIKE}:${v}`
+      case 'notContains':
+        return `${NOT}:${C.ILIKE}:${v}`
+      case 'like':
+        return `${C.LIKE}:${v}`
+      case 'ilike':
+        return `${C.ILIKE}:${v}`
+      case 'gt':
+        return `${C.GT}:${v}`
+      case 'gte':
+        return `${C.GTE}:${v}`
+      case 'lt':
+        return `${C.LT}:${v}`
+      case 'lte':
+        return `${C.LTE}:${v}`
+      case 'in':
+        return `${C.IN}:${list()}`
+      case 'nin':
+        return `${C.NIN}:${list()}`
+      case 'between': {
+        const [from, to] = Array.isArray(v) ? v : `${v}`.split(':')
+        if (from === undefined || to === undefined) {
+          throw { status: 400, text: `Filter "${filter.field}": "between" requires [from, to]` }
+        }
+        return `${C.BTW}:${from}:${to}`
+      }
+      case 'isNull':
+        return 'null'
+      case 'isNotNull':
+        return `${NOT}:null`
+      default:
+        throw { status: 400, text: `Unsupported filter op "${(filter as any).op}" for "${filter.field}"` }
+    }
+  }
+
   public async dropConnection(type: CuboBackendApiDbConnectionType) {
     if (this.connections[type]) {
       await this.connections[type].disconnect()
@@ -376,7 +483,7 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A> {
     const havings = dto.havings ?? []
     const sorts = dto.sorts ?? []
     const replacements = dto.replacements ?? {}
-    const groupBy = dto.groupBy ?? undefined
+    const groupBy = dto.groupBy ?? []
 
     const { sort, limit: _limit, page, with: _withes, ...query } = cloneDeep(req.query || {})
 
@@ -452,7 +559,7 @@ export class ApiHelpers<T extends CuboApiEntitiesMap<T>, A> {
 
     let offsetString = ''
     let limitString = ''
-    let groupByString = queryDto?.groupBy ?? ''
+    const groupByString = groupBy.length ? 'group by ' + groupBy.join(', ') : ''
 
     if (!isCount && perPage > 0) {
       if (filtersOffset > 0) {

package/src/helpers/withes.ts

@@ -2,7 +2,7 @@ import { CuboApiEntitiesMap, CuboApiEntityDefaultUsersKeys, CuboEntity, CuboEnti
 import { cloneDeep } from '@cuboapp/utils'
 
 import { CUBO_CRUD_DEFAULT_FIELDS, CUBO_CRUD_QUERY_KEY_REGEX } from '../constants'
-import { CuboCrudFindQuery, CuboCrudMethodOptions, CuboCrudRequest, CuboCrudWith } from '../types'
+import { CuboCrudFindQuery, CuboCrudMethodOptions, CuboCrudRequest, CuboCrudWith, normalizeCuboCrudQueryOptions } from '../types'
 
 import { ApiHelpers } from '.'
 
@@ -20,7 +20,7 @@ export class ApiHelpersWithes<T extends CuboApiEntitiesMap<T>> {
       sorts?: string[]
       conditions?: string[]
       havings?: string[]
-      groupBy?: string
+      groupBy?: string[]
       conditionKey?: string
       conditionValue?: any
       sortKey?: string
@@ -141,7 +141,7 @@ export class ApiHelpersWithes<T extends CuboApiEntitiesMap<T>> {
       withes,
       joins: opts.joins,
       conditions: opts.conditions || undefined,
-      groupBy: opts.groupBy || undefined,
+      groupBy: opts.groupBy ?? [],
       havings: opts.havings || undefined,
       replacements: opts.replacements || undefined
     }
@@ -226,19 +226,23 @@ export class ApiHelpersWithes<T extends CuboApiEntitiesMap<T>> {
   public async prepare(req: CuboCrudRequest, entity: CuboEntity, opts?: CuboCrudMethodOptions): Promise<Partial<CuboCrudFindQuery>> {
     const { with: __withes, sort: _sort, limit: _limit, ...other } = req.query || {}
 
+    // нормализуем один раз: дальше работаем с гарантированными массивами (deep-copy,
+    // поэтому push'и ниже не затрагивают исходные queryOptions)
+    const queryOptions = normalizeCuboCrudQueryOptions(opts?.queryOptions)
+
     const _withes = (__withes || '').split(',').filter((i: string) => i !== '')
 
-    if (opts?.queryOptions?.withes?.length) {
-      _withes.push(...(opts?.queryOptions?.withes || []).filter((i: string) => i !== ''))
+    if (queryOptions.withes.length) {
+      _withes.push(...queryOptions.withes.filter((i: string) => i !== ''))
     }
 
-    const joins: string[] = [...(opts?.queryOptions?.joins || [])]
-    const selects: string[] = [...(opts?.queryOptions?.selects || [])]
-    const conditions: string[] = [...(opts?.queryOptions?.conditions || [])]
-    const havings: string[] = [...(opts?.queryOptions?.havings || [])]
-    const replacements: Record<string, any> = { ...(opts?.queryOptions?.replacements || {}) }
-    const groupBy: string = opts?.queryOptions?.groupBy || undefined
-    const sorts: string[] = opts?.queryOptions?.sorts || []
+    const joins = queryOptions.joins
+    const selects = queryOptions.selects
+    const conditions = queryOptions.conditions
+    const havings = queryOptions.havings
+    const replacements = queryOptions.replacements
+    const groupBy = queryOptions.groupBy
+    const sorts = queryOptions.sorts
 
     const withes: CuboCrudWith[] = []
 

package/src/hooks/constants.ts

@@ -0,0 +1,21 @@
+/**
+ * Единый источник правды по именам хуков. Раньше список ключей `excludeHooks`
+ * дублировался руками в типе CuboCrudMethodOptions и легко рассинхронизировался.
+ */
+export const CUBO_HOOKS = [
+  'beforeGetMany',
+  'afterGetMany',
+  'beforeGetOne',
+  'afterGetOne',
+  'beforeCreate',
+  'afterCreate',
+  'beforeUpdate',
+  'afterUpdate',
+  'beforeDelete',
+  'afterDelete',
+  'afterCrdtCreate',
+  'afterCrdtUpdate',
+  'baseHooks'
+] as const
+
+export type CuboHookName = (typeof CUBO_HOOKS)[number]

package/src/hooks/define.ts

@@ -0,0 +1,76 @@
+import { CuboApiEntitiesMap } from '@cuboapp/types'
+
+import { CuboAugmentation, CuboAugmentationsStore } from './types'
+
+/**
+ * Identity-хелпер: фиксирует тип строки сущности (и auth) ОДИН раз, после чего
+ * в каждом хуке `ctx` выводится контекстно — аннотировать `CuboHookCtx<...>`
+ * больше не нужно.
+ *
+ * @example
+ * export const taskAugmentation = defineAugmentation<Task, Auth>({
+ *   async beforeGetMany({ req, queryOptions }) {   // ← всё типизировано без аннотаций
+ *     // ctx.queryOptions уже нормализован: массивы/объекты гарантированно есть,
+ *     // можно сразу мутировать без `|| []` / `|| {}`
+ *     if (req.query?.company_id) queryOptions.replacements.company_id = Number(req.query.company_id)
+ *     return queryOptions
+ *   }
+ * })
+ */
+export function defineAugmentation<R, A = unknown>(augmentation: CuboAugmentation<R, A>): CuboAugmentation<R, A> {
+  return augmentation
+}
+
+/** Тип функции-хука аугментации по ключу `K` (без `undefined`). */
+export type CuboAugmentationHook<R, A, K extends keyof CuboAugmentation<R, A>> = NonNullable<CuboAugmentation<R, A>[K]>
+
+/**
+ * Identity-хелпер для ОДНОГО хука: фиксирует тип строки (R) и auth (A), а тип
+ * `callback` выводится из переданного `key` — например, для `'beforeGetMany'`
+ * это будет ровно сигнатура `beforeGetMany`. Возвращает типизированную функцию
+ * хука: её можно положить в нужный ключ аугментации или переиспользовать.
+ *
+ * Реализовано перегрузками (overloads): один вызов, R/A задаются явно, нужная
+ * сигнатура выбирается по строковому литералу `key`.
+ *
+ * @example
+ * const beforeGetMany = defineAugmentationHook<Task, Auth>('beforeGetMany', ({ req, queryOptions }) => {
+ *   if (req.query?.company_id) queryOptions.conditions.push('t1.company_id = :company_id')
+ *   return queryOptions
+ * })
+ *
+ * export const taskAugmentation: CuboAugmentation<Task, Auth> = { beforeGetMany }
+ */
+export function defineAugmentationHook<R, A = unknown>(key: 'beforeGetMany', callback: CuboAugmentationHook<R, A, 'beforeGetMany'>): CuboAugmentationHook<R, A, 'beforeGetMany'>
+export function defineAugmentationHook<R, A = unknown>(key: 'beforeGetOne', callback: CuboAugmentationHook<R, A, 'beforeGetOne'>): CuboAugmentationHook<R, A, 'beforeGetOne'>
+export function defineAugmentationHook<R, A = unknown>(key: 'beforeCreate', callback: CuboAugmentationHook<R, A, 'beforeCreate'>): CuboAugmentationHook<R, A, 'beforeCreate'>
+export function defineAugmentationHook<R, A = unknown>(key: 'beforeUpdate', callback: CuboAugmentationHook<R, A, 'beforeUpdate'>): CuboAugmentationHook<R, A, 'beforeUpdate'>
+export function defineAugmentationHook<R, A = unknown>(key: 'beforeDelete', callback: CuboAugmentationHook<R, A, 'beforeDelete'>): CuboAugmentationHook<R, A, 'beforeDelete'>
+export function defineAugmentationHook<R, A = unknown>(key: 'afterGetMany', callback: CuboAugmentationHook<R, A, 'afterGetMany'>): CuboAugmentationHook<R, A, 'afterGetMany'>
+export function defineAugmentationHook<R, A = unknown>(key: 'afterGetOne', callback: CuboAugmentationHook<R, A, 'afterGetOne'>): CuboAugmentationHook<R, A, 'afterGetOne'>
+export function defineAugmentationHook<R, A = unknown>(key: 'afterCreate', callback: CuboAugmentationHook<R, A, 'afterCreate'>): CuboAugmentationHook<R, A, 'afterCreate'>
+export function defineAugmentationHook<R, A = unknown>(key: 'afterUpdate', callback: CuboAugmentationHook<R, A, 'afterUpdate'>): CuboAugmentationHook<R, A, 'afterUpdate'>
+export function defineAugmentationHook<R, A = unknown>(key: 'afterDelete', callback: CuboAugmentationHook<R, A, 'afterDelete'>): CuboAugmentationHook<R, A, 'afterDelete'>
+export function defineAugmentationHook<R, A = unknown>(key: 'afterCrdtCreate', callback: CuboAugmentationHook<R, A, 'afterCrdtCreate'>): CuboAugmentationHook<R, A, 'afterCrdtCreate'>
+export function defineAugmentationHook<R, A = unknown>(key: 'afterCrdtUpdate', callback: CuboAugmentationHook<R, A, 'afterCrdtUpdate'>): CuboAugmentationHook<R, A, 'afterCrdtUpdate'>
+export function defineAugmentationHook<R, A = unknown>(key: 'can', callback: CuboAugmentationHook<R, A, 'can'>): CuboAugmentationHook<R, A, 'can'>
+export function defineAugmentationHook<R, A = unknown>(key: 'filterRowForCrdtEvent', callback: CuboAugmentationHook<R, A, 'filterRowForCrdtEvent'>): CuboAugmentationHook<R, A, 'filterRowForCrdtEvent'>
+export function defineAugmentationHook<R, A = unknown>(key: keyof CuboAugmentation<R, A>, callback: any): any {
+  return callback
+}
+
+/**
+ * То же, но сразу для всей карты аугментаций. Внутри каждой сущности `ctx`
+ * хуков типизируется по её строке автоматически.
+ *
+ * @example
+ * export const augmentations = defineAugmentations<Entities, Auth>({
+ *   task: { async beforeGetMany({ req, queryOptions }) { ... } },
+ *   user: { async afterGetOne({ row }) { ... } }
+ * })
+ */
+export function defineAugmentations<T extends CuboApiEntitiesMap<T>, A = unknown>(
+  store: Partial<CuboAugmentationsStore<T, A>>
+): Partial<CuboAugmentationsStore<T, A>> {
+  return store
+}

package/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export * from './constants'
+export * from './types'
+export * from './define'

package/src/hooks/types.ts

@@ -0,0 +1,52 @@
+import { CuboApiEntitiesMap, CuboEntity } from '@cuboapp/types'
+
+import { CuboCrudAction, CuboCrudGetManyResponse, CuboCrudRequest } from '../types/basic'
+import { CuboCrudQueryOptions, CuboCrudQueryOptionsInput } from '../types/db'
+
+export type MaybePromise<X> = X | Promise<X>
+
+/**
+ * Контекст хука. `queryOptions` — это per-call РАБОЧАЯ КОПИЯ опций: каждый вызов
+ * получает свой свежий объект, так что состояние НЕ «накапливается» и не
+ * протекает между вызовами (внутренние getOne после create/update чужие опции
+ * не наследуют). Хук может либо мутировать эту копию, либо вернуть свой объект
+ * опций — движок возьмёт возвращённое значение (если оно есть), иначе текущую
+ * (возможно, изменённую) копию.
+ */
+export type CuboHookCtx<R, A = unknown> = {
+  entity: CuboEntity
+  req: CuboCrudRequest
+  auth?: A
+  performer_id?: number
+  queryOptions: CuboCrudQueryOptions
+}
+
+export interface CuboAugmentation<R, A = unknown> {
+  // before*: формируют query-опции (мутируют ctx.queryOptions и/или возвращают патч опций)
+  beforeGetMany?(ctx: CuboHookCtx<R, A>): MaybePromise<CuboCrudQueryOptionsInput | void>
+  beforeGetOne?(ctx: CuboHookCtx<R, A>): MaybePromise<CuboCrudQueryOptionsInput | void>
+  beforeCreate?(ctx: CuboHookCtx<R, A>): MaybePromise<CuboCrudQueryOptionsInput | void>
+  beforeUpdate?(ctx: CuboHookCtx<R, A> & { row: R }): MaybePromise<CuboCrudQueryOptionsInput | void>
+  beforeDelete?(ctx: CuboHookCtx<R, A> & { row: R }): MaybePromise<CuboCrudQueryOptionsInput | void>
+
+  // after*: трансформируют результат
+  afterGetMany?(ctx: CuboHookCtx<R, A> & { result: CuboCrudGetManyResponse<R> }): MaybePromise<CuboCrudGetManyResponse<R>>
+  afterGetOne?(ctx: CuboHookCtx<R, A> & { row: R }): MaybePromise<R | undefined>
+  afterCreate?(ctx: CuboHookCtx<R, A> & { row: R }): MaybePromise<R>
+  afterUpdate?(ctx: CuboHookCtx<R, A> & { row: R; prev: R }): MaybePromise<R>
+  afterDelete?(ctx: CuboHookCtx<R, A> & { row: R }): MaybePromise<boolean>
+
+  // crdt-хуки (вызываются адаптером cubo-crdt)
+  afterCrdtCreate?(ctx: CuboHookCtx<R, A> & { row: R }): MaybePromise<void>
+  afterCrdtUpdate?(ctx: CuboHookCtx<R, A> & { row: R }): MaybePromise<void>
+
+  // авторизация конкретного действия над строкой
+  can?(action: CuboCrudAction, ctx: CuboHookCtx<R, A> & { row?: R }): MaybePromise<boolean>
+
+  // фильтр строки под CRDT-подписку
+  filterRowForCrdtEvent?(row: R, filters: Record<string, any>): boolean
+}
+
+export type CuboAugmentationsStore<T extends CuboApiEntitiesMap<T>, A = unknown> = {
+  [K in Extract<keyof T, string>]?: CuboAugmentation<T[K], A>
+}