@cuboapp/api-backend 1.0.38 → 3.0.0

package/src/core/index.ts

@@ -0,0 +1,703 @@
+import { QueryTypes } from '@cuboapp/database'
+import { CuboApiEntitiesMap, CuboEntity } from '@cuboapp/types'
+import { cloneDeep } from '@cuboapp/utils'
+
+import { CuboCrdtAdapter } from '../crdt'
+import { ApiHelpers } from '../helpers'
+import { CuboHookName } from '../hooks/constants'
+import { compileQuery, CuboQuery } from '../query'
+import {
+  CuboBackendApiAuth,
+  CuboBackendApiOptions,
+  CuboCrudGetManyResponse,
+  CuboCrudMethodOptions,
+  CuboCrudQueryOptions,
+  CuboCrudRequest,
+  normalizeCuboCrudQueryOptions
+} from '../types'
+
+/**
+ * CUBO Backend API — метаданные-ориентированный CRUD-движок.
+ *
+ * Перерисованная архитектура:
+ *  - типизированный query-DSL (../query) поверх «строкового» движка;
+ *  - ИММУТАБЕЛЬНЫЕ query-опции: на каждый вызов строится новый объект, хуки
+ *    `before*` возвращают патч, который мёржится в новый объект — состояние
+ *    больше не «протекает» между вложенными вызовами;
+ *  - пакетные операции createMany/updateMany/deleteMany одним запросом + транзакция;
+ *  - корректные read-back'и внутри транзакции (write-соединение, тот же tx);
+ *  - встроенная поддержка cubo-crdt (../crdt) для сущностей с entity.crdt;
+ *  - диалекты Postgres/MySQL (../dialects); s3-хелперы удалены.
+ */
+export class CuboBackendApi<T extends CuboApiEntitiesMap<T>, A extends unknown = unknown> {
+  constructor(public options: CuboBackendApiOptions<T, A>) {}
+
+  public auth: CuboBackendApiAuth
+  public helpers = new ApiHelpers<T, A>(this)
+  public crdt?: CuboCrdtAdapter<T, A>
+
+  private debounces = new Map<`${string}:${number}`, { started: number; promise: Promise<any> }>()
+
+  async init() {
+    try {
+      if (this.options.api !== undefined) {
+        this.auth = await this.request<{ variables: Record<string, any> }>('/auth/me?with=variables', { withAuth: true })
+
+        if (!this.auth) {
+          throw { code: 403, text: 'Авторизация Cubo-Backend не пройдена' }
+        }
+
+        if (this.auth.variables?.db !== undefined) {
+          this.options.db = this.options.db || {}
+          this.options.db.options = { ...(this.options.db.options || {}), ...(this.auth.variables?.db || {}) }
+        }
+      }
+    } catch (e) {
+      console.error('[API-BACKEND] startup error', e)
+    }
+
+    // встроенный cubo-crdt «из коробки».
+    // @cuboapp/crdt (и yjs) — опциональная зависимость: грузим лениво только если
+    // включён crdt, чтобы проекты без CRDT не тянули yjs.
+    if (this.options.crdt?.ws) {
+      let createCrdtServer: typeof import('@cuboapp/crdt')['createCrdtServer']
+      try {
+        ;({ createCrdtServer } = await import('@cuboapp/crdt'))
+      } catch (e) {
+        throw new Error("[API-BACKEND] опция 'crdt' требует пакета '@cuboapp/crdt' (и 'yjs'). Установите их: npm i @cuboapp/crdt @cuboapp/ws yjs")
+      }
+
+      this.crdt = new CuboCrdtAdapter<T, A>(this, this.options.crdt.ws, createCrdtServer, this.options.crdt.debug)
+      await this.crdt.init()
+    }
+  }
+
+  async destroy() {
+    await this.crdt?.destroy()
+
+    const read = await this.helpers.getConnection('read', false)
+    const write = await this.helpers.getConnection('write', false)
+
+    if (read) await read.disconnect()
+    if (write) await write.disconnect()
+  }
+
+  // ───────────────────────────────────────────────────────── transactions ──
+
+  /** Back-compat: вернуть «голую» транзакцию write-соединения. */
+  public async transaction() {
+    const db = await this.helpers.getConnection('write')
+    return db.connection.transaction()
+  }
+
+  /**
+   * Выполнить fn в транзакции с авто-commit/rollback. Внутри fn все CRUD-вызовы
+   * должны получать opts.transaction (и тогда read-back'и пойдут в write-соединение).
+   */
+  public async withTransaction<R>(fn: (tx: any) => Promise<R>): Promise<R> {
+    const db = await this.helpers.getConnection('write')
+    const tx = await db.connection.transaction()
+    try {
+      const result = await fn(tx)
+      await tx.commit()
+      return result
+    } catch (e) {
+      await tx.rollback()
+      throw e
+    }
+  }
+
+  // ───────────────────────────────────────────────────── typed shortcuts ──
+
+  find<K extends Extract<keyof T, string>>(alias: K, query?: CuboQuery<T[K]>, opts?: CuboCrudMethodOptions) {
+    return this.getMany<K>(alias, { query: compileQuery(query) }, opts)
+  }
+
+  findOne<K extends Extract<keyof T, string>>(alias: K, query?: CuboQuery<T[K]>, opts?: CuboCrudMethodOptions) {
+    return this.getOne<K>(alias, { query: compileQuery(query) }, opts)
+  }
+
+  create<K extends Extract<keyof T, string>>(alias: K, body: Partial<T[K]>, opts?: CuboCrudMethodOptions) {
+    return this.createOne<K>(alias, { body }, opts)
+  }
+
+  update<K extends Extract<keyof T, string>>(alias: K, id: number, body: Partial<T[K]>, opts?: CuboCrudMethodOptions) {
+    return this.updateOne<K>(alias, { query: { id }, body }, opts)
+  }
+
+  remove<K extends Extract<keyof T, string>>(alias: K, id: number, opts?: CuboCrudMethodOptions) {
+    return this.deleteOne<K>(alias, { query: { id } }, opts)
+  }
+
+  // ─────────────────────────────────────────────────────────── read CRUD ──
+
+  async getMany<K extends Extract<keyof T, string> = Extract<keyof T, string>>(
+    entityAlias: K,
+    req?: CuboCrudRequest,
+    opts?: CuboCrudMethodOptions
+  ): Promise<CuboCrudGetManyResponse<T[K]>> {
+    opts = opts || {}
+    req = { ...(req || {}), query: cloneDeep(req?.query || {}) }
+
+    const entity = await this.getEntity(entityAlias)
+    const augmentation = this.options?.augmentations?.[entityAlias]
+
+    let queryOptions = normalizeCuboCrudQueryOptions(opts.queryOptions)
+
+    if (augmentation?.beforeGetMany && !this.excluded(opts, 'beforeGetMany')) {
+      const result = await augmentation.beforeGetMany(this.ctx(entity, req, opts, queryOptions))
+      if (result) queryOptions = normalizeCuboCrudQueryOptions(result)
+    }
+
+    const localOpts: CuboCrudMethodOptions = { ...opts, queryOptions }
+
+    const queryDto = await this.helpers.withes.prepare(req, entity, localOpts)
+    queryDto.withDeleted = queryOptions.withDeleted
+    this.applyRawQueryOptions(queryDto, queryOptions)
+
+    const regularQuery = await this.helpers.createFindQuery(req, entity, queryDto)
+    const countQuery = await this.helpers.createFindQuery(req, entity, queryDto, true)
+
+    const db = await this.connForRead(opts)
+
+    if (opts.log) {
+      console.log(`QUERY:getMany "${String(entityAlias)}":`, regularQuery.sql, regularQuery.replacements)
+    }
+
+    const rows = await db.connection.query<any>(regularQuery.sql!, {
+      type: QueryTypes.SELECT,
+      replacements: regularQuery.replacements,
+      transaction: opts.transaction
+    })
+    const [totals] = await db.connection.query<any>(countQuery.sql!, {
+      type: QueryTypes.SELECT,
+      replacements: countQuery.replacements,
+      transaction: opts.transaction
+    })
+
+    let response: CuboCrudGetManyResponse<T[K]> = {
+      rows: await this.helpers.convert.prepareAll(req, entity, rows, regularQuery),
+      totals: { count: totals?.total !== undefined ? +totals.total : 0 }
+    }
+
+    if (augmentation?.afterGetMany && !this.excluded(opts, 'afterGetMany')) {
+      response = await augmentation.afterGetMany({ ...this.ctx(entity, req, opts, queryOptions), result: response })
+    }
+
+    return response
+  }
+
+  async getOne<K extends Extract<keyof T, string> = Extract<keyof T, string>>(
+    entityAlias: K,
+    req: CuboCrudRequest,
+    opts?: CuboCrudMethodOptions
+  ): Promise<T[K] | undefined> {
+    opts = opts || {}
+    req = { ...(req || {}), query: cloneDeep(req?.query || {}) }
+
+    const entity = await this.getEntity(entityAlias)
+    const augmentation = this.options?.augmentations?.[entityAlias]
+
+    let queryOptions = normalizeCuboCrudQueryOptions(opts.queryOptions)
+
+    if (augmentation?.beforeGetOne && !this.excluded(opts, 'beforeGetOne')) {
+      const result = await augmentation.beforeGetOne(this.ctx(entity, req, opts, queryOptions))
+      if (result) queryOptions = normalizeCuboCrudQueryOptions(result)
+    }
+
+    const localOpts: CuboCrudMethodOptions = { ...opts, queryOptions }
+
+    const queryDto = await this.helpers.withes.prepare(req, entity, localOpts)
+    queryDto.withDeleted = queryOptions.withDeleted
+    queryDto.limit = 1
+    this.applyRawQueryOptions(queryDto, queryOptions)
+
+    const query = await this.helpers.createFindQuery(req, entity, queryDto)
+
+    const db = await this.connForRead(opts)
+
+    if (opts.log) {
+      console.log(`QUERY:getOne "${String(entityAlias)}":`, query.sql, query.replacements)
+    }
+
+    const [row] = await db.connection.query<any>(query.sql!, {
+      type: QueryTypes.SELECT,
+      replacements: query.replacements,
+      transaction: opts.transaction
+    })
+
+    if (!row) {
+      return null as any
+    }
+
+    let response = await this.helpers.convert.prepareOne(req, entity, row, query)
+
+    if (augmentation?.afterGetOne && !this.excluded(opts, 'afterGetOne')) {
+      response = await augmentation.afterGetOne({ ...this.ctx(entity, req, opts, queryOptions), row: response })
+    }
+
+    return response
+  }
+
+  // ────────────────────────────────────────────────────────── write CRUD ──
+
+  async createOne<K extends Extract<keyof T, string> = Extract<keyof T, string>>(
+    entityAlias: K,
+    req: CuboCrudRequest,
+    opts?: CuboCrudMethodOptions
+  ): Promise<T[K]> {
+    opts = opts || {}
+    const entity = await this.getEntity(entityAlias)
+    const augmentation = this.options?.augmentations?.[entityAlias]
+
+    let queryOptions = normalizeCuboCrudQueryOptions(opts.queryOptions)
+    if (augmentation?.beforeCreate && !this.excluded(opts, 'beforeCreate' as CuboHookName)) {
+      const result = await augmentation.beforeCreate(this.ctx(entity, req, opts, queryOptions))
+      if (result) queryOptions = normalizeCuboCrudQueryOptions(result)
+    }
+
+    const dto = this.helpers.data.prepare('create', entity.fields, req.body, opts.performer_id || 0)
+    if (!Object.keys(dto).length) {
+      throw { status: 400, text: 'No keys to create' }
+    }
+
+    const db = await this.helpers.getConnection('write')
+    const [created_id] = await db.create(entity.alias, dto, {
+      transaction: opts.transaction,
+      log: opts.log,
+      pk_key: this.pkKey,
+      pk_type: this.pkType
+    })
+    if (!created_id) {
+      throw { status: 400, text: 'Unable to create entity' }
+    }
+
+    let response = await this.getOne<K>(entityAlias, { query: { id: created_id } }, this.readBackOpts(opts))
+    if (!response) {
+      throw { status: 400, text: 'Unable to find entity after create' }
+    }
+
+    if (augmentation?.afterCreate && !this.excluded(opts, 'afterCreate')) {
+      response = await augmentation.afterCreate({ ...this.ctx(entity, req, opts, queryOptions), row: response })
+    }
+    if (this.options.hooks?.onAfterCreate && !this.excluded(opts, 'baseHooks')) {
+      await this.options.hooks.onAfterCreate(entity, response, opts)
+    }
+
+    this.crdtPush('create', entity, response, opts)
+    if (augmentation?.afterCrdtCreate && !this.excluded(opts, 'afterCrdtCreate')) {
+      await augmentation.afterCrdtCreate({ ...this.ctx(entity, req, opts, queryOptions), row: response })
+    }
+
+    return response
+  }
+
+  async updateOne<K extends Extract<keyof T, string> = Extract<keyof T, string>>(
+    entityAlias: K,
+    req: CuboCrudRequest,
+    opts?: CuboCrudMethodOptions
+  ): Promise<T[K] | undefined> {
+    if (opts?.debounce) {
+      if (!req.query?.id) {
+        throw 'Debounce "updateOne" allowed only with "id"'
+      }
+
+      const key = `${entityAlias}:${+req.query.id}` as `${string}:${number}`
+      const ex = this.debounces.get(key)
+      if (ex && ex.started > +new Date() - opts.debounce) {
+        return ex.promise
+      }
+
+      const promise = new Promise<T[K] | undefined>((resolve, reject) => {
+        setTimeout(() => {
+          this.debounces.delete(key)
+          this.updateOne(entityAlias, req, { ...(opts || {}), debounce: undefined })
+            .then(resolve)
+            .catch(reject)
+        }, opts.debounce)
+      })
+
+      this.debounces.set(key, { started: +new Date(), promise })
+      return promise
+    }
+
+    opts = opts || {}
+    const entity = await this.getEntity(entityAlias)
+    const augmentation = this.options?.augmentations?.[entityAlias]
+
+    const item = await this.getOne(entityAlias, req, this.readBackOpts(opts))
+    if (!item) {
+      throw { status: 404, text: 'Entity not found' }
+    }
+    const prev = cloneDeep(item)
+
+    let queryOptions = normalizeCuboCrudQueryOptions(opts.queryOptions)
+    if (augmentation?.beforeUpdate && !this.excluded(opts, 'beforeUpdate')) {
+      const result = await augmentation.beforeUpdate({ ...this.ctx(entity, req, opts, queryOptions), row: item as T[K] })
+      if (result) queryOptions = normalizeCuboCrudQueryOptions(result)
+    }
+
+    if (augmentation?.can) {
+      const allowed = await augmentation.can('update', { ...this.ctx(entity, req, opts, queryOptions), row: item as T[K] })
+      if (!allowed) {
+        throw { status: 403, text: 'Updating entity forbidden' }
+      }
+    }
+
+    const dto = this.helpers.data.prepare('update', entity.fields, req.body, opts.performer_id || 0)
+    if (!Object.keys(dto).length) {
+      throw { status: 400, text: 'No keys to update' }
+    }
+
+    const db = await this.helpers.getConnection('write')
+    await db.update(entity.alias, 'id = :id', { id: (item as any).id }, dto, {
+      transaction: opts.transaction,
+      log: opts.log,
+      pk_key: this.pkKey,
+      pk_type: this.pkType
+    })
+
+    let response = await this.getOne<K>(entityAlias, { query: { id: (item as any).id } }, this.readBackOpts(opts))
+    if (!response) {
+      throw { status: 400, text: 'Unable to find entity after update' }
+    }
+
+    if (augmentation?.afterUpdate && !this.excluded(opts, 'afterUpdate')) {
+      response = await augmentation.afterUpdate({ ...this.ctx(entity, req, opts, queryOptions), row: response, prev: prev as T[K] })
+    }
+    if (this.options.hooks?.onAfterUpdate && !this.excluded(opts, 'baseHooks')) {
+      await this.options.hooks.onAfterUpdate(entity, response, prev as T[K], opts)
+    }
+
+    this.crdtPush('update', entity, response, opts)
+    if (augmentation?.afterCrdtUpdate && !this.excluded(opts, 'afterCrdtUpdate')) {
+      await augmentation.afterCrdtUpdate({ ...this.ctx(entity, req, opts, queryOptions), row: response })
+    }
+
+    return response
+  }
+
+  async deleteOne<K extends Extract<keyof T, string>>(
+    entityAlias: K,
+    req: CuboCrudRequest,
+    opts?: CuboCrudMethodOptions
+  ): Promise<boolean> {
+    opts = opts || {}
+    const entity = await this.getEntity(entityAlias)
+    const augmentation = this.options?.augmentations?.[entityAlias]
+
+    const item = await this.getOne(entityAlias, req, this.readBackOpts(opts))
+    if (!item) {
+      throw { status: 404, text: 'Entity not found' }
+    }
+
+    let queryOptions = normalizeCuboCrudQueryOptions(opts.queryOptions)
+    if (augmentation?.beforeDelete && !this.excluded(opts, 'beforeDelete' as CuboHookName)) {
+      const result = await augmentation.beforeDelete({ ...this.ctx(entity, req, opts, queryOptions), row: item as T[K] })
+      if (result) queryOptions = normalizeCuboCrudQueryOptions(result)
+    }
+
+    if (augmentation?.can) {
+      const allowed = await augmentation.can('delete', { ...this.ctx(entity, req, opts, queryOptions), row: item as T[K] })
+      if (!allowed) {
+        throw { status: 403, text: 'Deleting entity forbidden' }
+      }
+    }
+
+    const dto = this.helpers.data.prepare('delete', entity.fields, req.body || {}, opts.performer_id)
+    if (!Object.keys(dto).length) {
+      throw { status: 400, text: 'No keys to delete' }
+    }
+
+    const db = await this.helpers.getConnection('write')
+    await db.update(entity.alias, 'id = :id', { id: (item as any).id }, dto, {
+      transaction: opts.transaction,
+      log: opts.log,
+      pk_key: this.pkKey,
+      pk_type: this.pkType
+    })
+
+    if (this.options.hooks?.onAfterDelete && !this.excluded(opts, 'baseHooks')) {
+      await this.options.hooks.onAfterDelete(entity, item as T[K], opts)
+    }
+
+    this.crdtPush('delete', entity, item, opts)
+
+    if (augmentation?.afterDelete && !this.excluded(opts, 'afterDelete')) {
+      return augmentation.afterDelete({ ...this.ctx(entity, req, opts, queryOptions), row: item as T[K] })
+    }
+
+    return true
+  }
+
+  // ──────────────────────────────────────────────────────── batch CRUD ──
+
+  /** Пакетное создание одним INSERT (+ транзакция). Возвращает созданные строки. */
+  async createMany<K extends Extract<keyof T, string>>(
+    entityAlias: K,
+    rows: Partial<T[K]>[],
+    opts?: CuboCrudMethodOptions
+  ): Promise<T[K][]> {
+    opts = opts || {}
+    if (!rows.length) return []
+
+    const entity = await this.getEntity(entityAlias)
+    const dtos = rows.map((row) => this.helpers.data.prepare('create', entity.fields, row, opts!.performer_id || 0))
+
+    const run = async (tx: any): Promise<T[K][]> => {
+      const ids = await this.insertMany(entity, dtos, { transaction: tx, log: opts!.log })
+      if (!ids.length) return []
+      const { rows: created } = await this.getMany<K>(
+        entityAlias,
+        { query: { id: `in:${ids.join(',')}` } },
+        this.readBackOpts({ ...opts, transaction: tx })
+      )
+      return created
+    }
+
+    const created = opts.transaction ? await run(opts.transaction) : await this.withTransaction(run)
+
+    for (const row of created) {
+      if (this.options.hooks?.onAfterCreate && !this.excluded(opts, 'baseHooks')) {
+        await this.options.hooks.onAfterCreate(entity, row, opts)
+      }
+      this.crdtPush('create', entity, row, opts)
+    }
+
+    return created
+  }
+
+  /** Пакетное обновление: один UPDATE по id IN (...). Возвращает обновлённые строки. */
+  async updateMany<K extends Extract<keyof T, string>>(
+    entityAlias: K,
+    req: CuboCrudRequest,
+    opts?: CuboCrudMethodOptions
+  ): Promise<T[K][]> {
+    opts = opts || {}
+    const entity = await this.getEntity(entityAlias)
+
+    const { rows: items } = await this.getMany<K>(entityAlias, req, this.readBackOpts(opts))
+    const ids = items.map((r: any) => r.id)
+    if (!ids.length) return []
+
+    const dto = this.helpers.data.prepare('update', entity.fields, req.body, opts.performer_id || 0)
+    if (!Object.keys(dto).length) {
+      throw { status: 400, text: 'No keys to update' }
+    }
+
+    const run = async (tx: any): Promise<T[K][]> => {
+      await this.updateWhereIds(entity, ids, dto, { transaction: tx, log: opts!.log })
+      const { rows: updated } = await this.getMany<K>(
+        entityAlias,
+        { query: { id: `in:${ids.join(',')}` } },
+        this.readBackOpts({ ...opts, transaction: tx })
+      )
+      return updated
+    }
+
+    const updated = opts.transaction ? await run(opts.transaction) : await this.withTransaction(run)
+
+    const prevById = new Map(items.map((r: any) => [r.id, r]))
+    for (const row of updated) {
+      if (this.options.hooks?.onAfterUpdate && !this.excluded(opts, 'baseHooks')) {
+        await this.options.hooks.onAfterUpdate(entity, row, prevById.get((row as any).id) as T[K], opts)
+      }
+      this.crdtPush('update', entity, row, opts)
+    }
+
+    return updated
+  }
+
+  /** Пакетное (мягкое) удаление: один UPDATE по id IN (...). Возвращает кол-во. */
+  async deleteMany<K extends Extract<keyof T, string>>(
+    entityAlias: K,
+    req: CuboCrudRequest,
+    opts?: CuboCrudMethodOptions
+  ): Promise<number> {
+    opts = opts || {}
+    const entity = await this.getEntity(entityAlias)
+
+    const { rows: items } = await this.getMany<K>(entityAlias, req, this.readBackOpts(opts))
+    const ids = items.map((r: any) => r.id)
+    if (!ids.length) return 0
+
+    const dto = this.helpers.data.prepare('delete', entity.fields, req.body || {}, opts.performer_id)
+    if (!Object.keys(dto).length) {
+      throw { status: 400, text: 'No keys to delete' }
+    }
+
+    await (opts.transaction
+      ? this.updateWhereIds(entity, ids, dto, { transaction: opts.transaction, log: opts.log })
+      : this.withTransaction((tx) => this.updateWhereIds(entity, ids, dto, { transaction: tx, log: opts!.log })))
+
+    for (const item of items) {
+      if (this.options.hooks?.onAfterDelete && !this.excluded(opts, 'baseHooks')) {
+        await this.options.hooks.onAfterDelete(entity, item as T[K], opts)
+      }
+      this.crdtPush('delete', entity, item, opts)
+    }
+
+    return ids.length
+  }
+
+  // ─────────────────────────────────────────────────────── http client ──
+
+  public async request<R>(url: string, opts?: RequestInit & { debug?: boolean; withAuth?: boolean; withoutContentType?: boolean }) {
+    const baseUrl = this.options?.api?.base_url || 'https://api.cubo.sh'
+
+    const headers: Record<string, any> = { ...(opts?.headers || {}) }
+    if (opts?.withAuth) {
+      Object.assign(headers, this.options.api?.headers || {})
+    }
+    if (!headers['Content-Type'] && !opts?.withoutContentType) {
+      headers['Accept'] = 'application/json'
+      headers['Content-Type'] = 'application/json'
+    }
+
+    const requestUrl = baseUrl.replace(/\/$/, '') + '/' + url.replace(/^\//, '')
+    const requestOpts = { ...(opts || {}), headers }
+
+    try {
+      const response = await fetch(requestUrl, requestOpts)
+      if ([201, 200].includes(response.status)) {
+        try {
+          return (await response.json()) as Promise<R>
+        } catch {
+          const text = await response.text()
+          try {
+            return (text ? JSON.parse(text) : null) as Promise<R>
+          } catch {
+            throw { status: 500, error: 'Invalid response', text }
+          }
+        }
+      } else {
+        throw { status: response.status, error: response.statusText, text: await response.text() }
+      }
+    } catch (e) {
+      if (opts?.debug) {
+        console.log('[API BACKEND]', JSON.stringify({ request: { url: requestUrl, opts: requestOpts }, error: e }, null, 2))
+      }
+      throw e
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────── internals ──
+
+  private async getEntity(entityAlias: Extract<keyof T, string>): Promise<CuboEntity> {
+    const entity = await this.helpers.getEntityByAlias(entityAlias)
+    if (!entity) {
+      throw new Error('Entity not found: "' + String(entityAlias) + '"')
+    }
+    return entity
+  }
+
+  private get pkKey() {
+    return this.options.db?.options?.pk_key ?? 'id'
+  }
+
+  private get pkType(): 'string' | 'number' {
+    return this.options.db?.options?.pk_type ?? 'number'
+  }
+
+  private excluded(opts: CuboCrudMethodOptions, name: CuboHookName) {
+    return !!opts.excludeHooks?.includes(name)
+  }
+
+  /** read-back внутри write-транзакции должен идти в write-соединение и тем же tx. */
+  private async connForRead(opts: CuboCrudMethodOptions) {
+    return this.helpers.getConnection(opts.transaction ? 'write' : 'read')
+  }
+
+  /** Опции для внутренних read-back'ов: без наследования queryOptions и без хуков чтения. */
+  private readBackOpts(opts: CuboCrudMethodOptions): CuboCrudMethodOptions {
+    return {
+      transaction: opts.transaction,
+      performer_id: opts.performer_id,
+      auth: opts.auth,
+      log: opts.log,
+      excludeHooks: ['beforeGetOne', 'afterGetOne', 'beforeGetMany', 'afterGetMany']
+    }
+  }
+
+  /**
+   * Контекст хука. `queryOptions` передаётся ССЫЛКОЙ на per-call рабочую копию
+   * (свежий cloneDeep на каждый вызов), поэтому хук может либо мутировать её,
+   * либо вернуть свой объект — а накопления/протечки между вызовами нет.
+   */
+  private ctx(entity: CuboEntity, req: CuboCrudRequest, opts: CuboCrudMethodOptions, queryOptions: CuboCrudQueryOptions) {
+    return {
+      entity,
+      req,
+      auth: opts.auth as A,
+      performer_id: opts.performer_id,
+      queryOptions
+    }
+  }
+
+  /** Вливает raw-условия из query-опций в find-query. */
+  private applyRawQueryOptions(queryDto: any, queryOptions: CuboCrudQueryOptions) {
+    const raw = queryOptions.raw
+    if (!raw) return
+    if (raw.conditions?.length) queryDto.conditions = [...(queryDto.conditions || []), ...raw.conditions]
+    if (raw.havings?.length) queryDto.havings = [...(queryDto.havings || []), ...raw.havings]
+    if (raw.replacements) queryDto.replacements = { ...(queryDto.replacements || {}), ...raw.replacements }
+  }
+
+  private crdtPush(action: 'create' | 'update' | 'delete', entity: CuboEntity, row: any, opts: CuboCrudMethodOptions) {
+    // если апдейт пришёл ИЗ crdt (storeRow) — не пушим повторно, чтобы не зациклиться
+    if (!this.crdt || !entity.crdt || opts.crdt) return
+
+    if (action === 'create') this.crdt.pushCreate(entity, row)
+    else if (action === 'update') this.crdt.pushUpdate(entity, row)
+    else this.crdt.pushDelete(entity, row)
+  }
+
+  /** Многострочный INSERT. Postgres -> RETURNING; MySQL -> последовательные autoincrement id. */
+  private async insertMany(entity: CuboEntity, dtos: any[], opts: { transaction?: any; log?: boolean }): Promise<number[]> {
+    if (!dtos.length) return []
+
+    const db = await this.helpers.getConnection('write')
+    const dialect = this.helpers.dialect
+
+    // объединение колонок по всем строкам (отсутствующие -> null)
+    const cols = Array.from(new Set(dtos.flatMap((d) => Object.keys(d))))
+    const replacements: Record<string, any> = {}
+
+    const valuesSql = dtos
+      .map((dto, i) => '(' + cols.map((c) => {
+        const key = `b_${i}_${c}`
+        replacements[key] = dto[c] ?? null
+        return `:${key}`
+      }).join(', ') + ')')
+      .join(', ')
+
+    let sql = `insert into ${entity.alias} (${cols.join(', ')}) values ${valuesSql}`
+    if (dialect.supportsReturning) {
+      sql += ` returning ${this.pkKey}`
+    }
+
+    if (opts.log) {
+      console.warn('CREATE MANY:', sql)
+    }
+
+    const res: any = await db.connection.query(sql, { type: QueryTypes.INSERT, replacements, transaction: opts.transaction })
+
+    if (dialect.supportsReturning) {
+      return (res?.[0] || []).map((r: any) => +r[this.pkKey])
+    }
+
+    // MySQL: query() возвращает [insertId, affectedRows]; строки получают последовательные id
+    const insertId = Array.isArray(res) ? +res[0] : +res
+    return dtos.map((_, i) => insertId + i)
+  }
+
+  private async updateWhereIds(entity: CuboEntity, ids: number[], dto: any, opts: { transaction?: any; log?: boolean }) {
+    const db = await this.helpers.getConnection('write')
+    await db.update(entity.alias, 'id in (:__ids)', { __ids: ids }, dto, {
+      transaction: opts.transaction,
+      log: opts.log,
+      pk_key: this.pkKey,
+      pk_type: this.pkType
+    })
+  }
+}