Пакет `@morphcluster/carabi`

Утилиты SQL

Клиенты удалённых сервисов

Все клиенты предоставляют методы, соответствующие удалённым запросам:

OraLongTransactions - клиент для работы с длинными транзакциями Oracle-адаптера. (см. хост Postgres).

OraQueries - клиент для выполнения обычных (без транзакций) запросов в стиле Oracle.

PgQueryPool - клиент для работы с прямым пулом PostgreSQL (если используется режим pg).

Documents - низкоуровневая работа с информационными объектами (документами) без валидации и проверки прав.

DocumentLists - расширенные запросы списков документов с фильтрацией по статусам.

DockindStructure - работа со структурой информационных объектов (типы, свойства, статусы, права).

SqlQuery

Назначение: построение сложных SQL-запросов программным способом. Поддерживает SELECT, FROM, JOIN, WHERE, ORDER BY, LIMIT/OFFSET.

const q = new SqlQuery()
  .select(['u.id', 'u.name'])
  .from('users', 'u')
  .leftJoin('orders', 'o', new WhereCondition('simple', 'u.id = o.user_id'))
  .orderBy('u.name');

const sql = q.build({ pretty: true });

Подробнее в отдельном документе

SqlModify

Назначение: упрощает создание запросов INSERT и UPDATE.

const mod = new SqlModify('users');
mod.set('name', 'varchar2', 'Alice');
mod.set('age', 'number', 30);
mod.setId('id', 'number', 123);
const { sql, params } = mod.getUpdateQuery();

Методы:

Метод	Описание
`set(column, type, value)`	Задать значение колонки
`setId(column, type, value)`	Задать идентификатор записи
`getInsertQuery()`	Возвращает `{sql, params}` для INSERT ... RETURNING
`getUpdateQuery()`	Возвращает `{sql, params}` для UPDATE

Параметры формируются в виде { name, type, value }, совместимом с QueriesHelper.

Сервисы-помошники

QueriesHelper

универсальный сервис-помощник для выполнения запросов к базе данных через выбранный адаптер (ora или pg). Является предпочтительным способом взаимодействия с БД в прикладных сервисах.

Подробнее смотрите в отдельном разделе

OLTHelper

Устаревший, сейчас его заменил QueriesHelper. Класс-помощник для упрощённой работы с длинными транзакциями (OraLongTransactions).

Не является сервисом, это обычный класс, который нужно создавать вручную.

Конструктор:

new OLTHelper(oltServiceInstance, workspace, oltId?, log, options?)

oltServiceInstance – экземпляр клиента OraLongTransactions.

workspace – рабочее пространство (обычно "main").

oltId – ID существующей транзакции (если не указана, создаётся автоматически при первом вызове).

log – экземпляр Logger.

options – { userId?, noUser? }.

Основные методы:

Метод	Описание
`create()`	Явно создать транзакцию
`getResult()`	Дождаться результата последнего выполнения
`fetch(OutParams, count)`	Извлечь строки курсора после выполнения
`execFuncMulti(queryName, params)`	Выполнить функцию и вернуть объект с выходными параметрами
`execFunc(queryName, params)`	Выполнить функцию и вернуть первое выходное значение
`selectFunc(queryName, params, count)`	Выполнить функцию и вернуть сфетченные строки курсора
`selectRowFunc(queryName, params)`	Выполнить функцию и вернуть первую строку курсора
`execSql(sql, params)`	Выполнить SQL
`selectSql(sql, params, count)`	Выполнить SQL и вернуть сфетченные строки
`selectRowSql(sql, params)`	Выполнить SQL и вернуть первую строку
`commit()`	Зафиксировать транзакцию
`rollback()`	Откатить транзакцию

Методы автоматически вызывают create(), если транзакция ещё не создана.

Пример:

const olt = new OLTHelper(this.OraLongTransactions, 'main', null, log, { noUser: true });
await olt.execFunc('PKG_TEST.DO_SOMETHING', { param1: 1 });
const rows = await olt.fetch(olt.result, 100);
await olt.commit();

Работа с документами

DockindCache

Сервис кэширования метаданных типов документов (DocumentKind) и имён справочников. Автоматически сбрасывает кэш при получении события onChanged от DockindStructure.

Методы:

Метод	Сигнатура	Описание
`get(log, docKindName)`	`(log, name) → DocumentKind`	Получить закэшированный объект типа документа
`getById(log, docKindId)`	`(log, id) → DocumentKind`	Получить тип по числовому ID
`getIdByName(log, docKindName)`	`(log, name) → number`	Получить ID по имени
`getNameById(log, docKindId)`	`(log, id) → string`	Получить имя по ID
`clearCache()`	–	Принудительно сбросить все кэши

DocumentKind

Назначение: представляет метаданные одного типа информационного объекта (документа). Загружается из БД через CSP_DOCUMENTS.GET_DOCKIND_INFO и связанные запросы.

Конструктор:

new DocumentKind(queriesHelper)

После создания нужно вызвать await docKind.load(log).

Основные свойства (после загрузки):

name, id, description, tableName

properties – массив DocProperty

propEvents – массив DocEventProperty

statuses – массив объектов {id, name, descr}

Методы:

getTableName() – имя таблицы БД для этого типа.

getPropFieldName(prop) – имя колонки для свойства.

getUniqueProps() – массив уникальных свойств.

Класс DocProperty:

{
  id, name, fieldName, propKind,
  formatBase, formatLogic,
  object, multi, unique,
  fpath, SQL, rule, raw
}

Класс DocEventProperty:

{
  propId, statusId,
  writable, readable, notNull
}

Справочники

VocabsHelper

Назначение: сервис для загрузки и кэширования справочников.

Методы:

Метод	Сигнатура	Описание
`getVocab(log, vocabName)`	`→ Vocab`	Получить загруженный справочник по имени

При первом запросе загружает справочник асинхронно, последующие вызовы возвращают уже загруженный экземпляр.

Vocab

Назначение: представляет один справочник (простейшая модель).

Конструктор: new Vocab(name, queriesHelper)

Методы:

load(log) – загружает ID справочника по имени.

Свойства после загрузки: id, name, loaded = true.

Document

Назначение: представляет один экземпляр информационного объекта с кэшированием значений и отслеживанием изменений.

Конструктор:

new Document(log, session, docKind, { Documents, QueriesHelper, trxId? })

Основные методы:

Метод	Описание
`loadFromJson(data)`	Загрузить данные из объекта (обычно после поиска)
`getValues(propNames)`	Получить значения свойств (с кэшированием)
`getValue(propName)`	Получить одно значение
`setValues(values, autocommit?)`	Установить значения (накапливаются в `valuesChanged`)
`commitValues()`	Сохранить накопленные изменения в БД
`insertRefs(propName, values)`	Добавить ссылки
`setStatus(newStatusName)`	Изменить статус документа

Пример:

const doc = new Document(log, session, dockind, { QueriesHelper: this.QueriesHelper, Documents: this.Documents, trxId });
doc.id = 123;
await doc.getValues(['Name', 'Age']);
await doc.setValues({ Name: 'Alice' }); // изменится, но не сохранено
await doc.setValues({ Age: 30 }, false); // ещё изменение
await doc.commitValues(); // одно сохранение двух полей

DocumentsHelper

Назначение: высокоуровневый сервис для работы с документами. Создаёт документы, загружает их по ID, выполняет поиск списков.

Методы:

Метод	Сигнатура	Описание
`createDocument(log, session, docKindName, trxId?)`	`→ Document`	Создать новый документ, возвращает объект `Document`
`loadDocument(log, session, docKindName, documentId, trxId?)`	`→ Document`	Загрузить существующий документ
`loadDocList(log, session, docKindName, options)`	`→ Document[]`	Загрузить список документов с фильтрацией
`getDocKindByDocumentId(log, documentId)`	`→ DocumentKind`	Получить тип документа по ID экземпляра

Параметры loadDocList:

{
  props: ['Name', 'Age'],     // поля для выборки
  filter: { Name: 'Alice' },  // фильтр
  statuses: ['Active'],       // ограничение по статусам
  notStatuses: ['Deleted'],   // исключаемые статусы
  count: 100,
  trxId: null
}