Skip to main content

Пакет @morphcluster/carabi

У

Предоставляет клиентские обёртки, хелперы и утилиты SQL

для работы с базой данных, документами, справочниками и миграциями.

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

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

  • OraLongTransactions - клиент для работы с длинными транзакциями Oracle-адаптера. (см. хост Postgres).
  • OraQueries - клиент для выполнения обычных (без транзакций) запросов в стиле Oracle.
  • PgQueryPool - клиент для работы с прямым пулом PostgreSQL (если используется режим pg).
  • Documents - низкоуровневая работа с информационными объектами (документами) без валидации и проверки прав.
  • DocumentLists - расширенные запросы списков документов с фильтрацией по статусам.
  • DockindStructure - работа со структурой информационных объектов (типы, свойства, статусы, права).

Утилиты SQL

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
}
Back to top