letopis 1.3.0 → 1.4.1

package/dist/sync.js

@@ -12,13 +12,19 @@ export async function syncModels(db, models, opts = {}) {
     const res = { applied: Boolean(opts.apply), created: [], updated: [], unchanged: [], skipped: [], lost: models.flatMap((m) => m.lostRules()) };
     const S = `"${db.schema.replace(/"/g, '""')}"`;
     // предок раньше потомка; класс-источник агрегата раньше цели: агрегат над классом, которого ещё нет, база отклоняет.
-    // Цикл агрегатов база отклоняет сама — обход его только не зацикливает
+    // Круг (агрегат над собственным потомком, цикл агрегатов) так не упорядочить — отказ до записи с самим кругом (хвост
+    // ревью доработок после 1.2.0: раньше обход молча ставил потомка раньше предка)
     const ordered = [];
-    const visiting = new Set();
+    const path = [];
     const visit = (m) => {
-        if (ordered.includes(m) || visiting.has(m))
+        if (ordered.includes(m))
             return;
-        visiting.add(m);
+        const at = path.indexOf(m);
+        if (at >= 0) {
+            throw new LetopisError('invalid_class', `syncModels: модели зависят друг от друга по кругу: ${[...path.slice(at), m].map((x) => x.name).join(' → ')} — `
+                + 'родителя и источник агрегата база ждёт раньше класса');
+        }
+        path.push(m);
         if (m.parent && models.includes(m.parent))
             visit(m.parent);
         for (const a of Object.values(m.describe().aggregate ?? {})) {
@@ -26,7 +32,7 @@ export async function syncModels(db, models, opts = {}) {
             if (src)
                 visit(src);
         }
-        visiting.delete(m);
+        path.pop();
         ordered.push(m);
     };
     models.forEach(visit);

package/dist/tx.js

@@ -282,7 +282,16 @@ export class ExplicitTx {
         let changed = null;
         try {
             // чтение letopis.changed и COMMIT — одним конвейером (как в runTx); обрыв — исход неизвестен
-            const [rows, res] = await Promise.all([this.conn.unsafe(`select current_setting('letopis.changed', true) as changed`), this.conn.unsafe('commit')]);
+            const read = this.conn.unsafe(`select current_setting('letopis.changed', true) as changed`);
+            const commit = this.conn.unsafe('commit');
+            const [rows, res] = (await Promise.all([read, commit]).catch(async (e) => {
+                // транзакцию уже прервала ошибка, которую код внутри db.begin() поймал и проглотил: чтение получает 25P02,
+                // а COMMIT того же конвейера отвечает ROLLBACK — это tx_rolled_back, а не сырая ошибка PostgreSQL
+                const tail = e.code === '25P02' ? await commit.catch(() => null) : null;
+                if (tail?.command === 'ROLLBACK')
+                    return [[], tail];
+                throw e;
+            }));
             changed = rows[0]?.changed ?? null;
             if (res.command === 'ROLLBACK') {
                 this.failure = new LetopisError('tx_rolled_back', 'commit: PostgreSQL откатил транзакцию (в ней была ошибка)');

package/dist/types.d.ts

@@ -1,23 +1,30 @@
 /**
  * Общие типы letopis 1.0. Файл наполняется по этапам плана (reports/PLAN-LETOPIS-1.0.md).
  */
-/** Ревизия движка в базе: штамп в lib/sql/99-revision.sql должен совпадать (этап 1). */
-export declare const DDL_REVISION = 6;
+/**
+ * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии `up()` обновляет только с `upgrade: true`,
+ * а `connect()` о ней предупреждает.
+ */
+export declare const DDL_REVISION = 7;
 /**
  * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
  * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
  */
 export declare const ACL_CLASS_NAMES: readonly string[];
-/** Методы цепочки: терминалы, модификаторы, глаголы записи (этап 4), охранники снесённого API. */
+/**
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then` и снятые методы прежних
+ * версий. После шага цепочки эти имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
+ */
 export declare const CHAIN_METHODS: readonly ["then", "entity", "paths", "rows", "first", "ids", "count", "limit", "offset", "sort", "asOf", "withDeleted", "deep", "exact", "sum", "avg", "min", "max", "countBy", "after", "versions", "create", "update", "upsert", "set", "unset", "add", "remove", "delete", "anonymize", "reclass", "restore", "purge", "alias", "tags", "owner", "forUpdate", "cache", "rekey", "run", "execute", "account", "diff", "blame"];
 /** Свойства корня db (и транзакции db.begin()). */
 export declare const DB_METHODS: readonly ["as", "begin", "commit", "rollback", "lock", "batch", "watch", "close", "registry", "sql", "load", "verify", "maintain", "reset", "describe", "auth", "acl", "idOf", "refresh", "transaction", "flushSignals", "schema", "token", "tenant", "reloadSchema", "accounts", "credentials", "resources", "rules", "compact", "trimHistory", "rekeyClass", "cache", "projector", "rebuildAggregates"];
 /** Свойства батча db.batch(name). */
 export declare const BATCH_METHODS: readonly ["discard", "size"];
 /**
- * Зарезервированные имена: Proxy разбирает их раньше классов, поэтому класс с таким именем
- * недостижим как шаг. Установщик подставляет список в функцию базы reserved_names(), которая
- * отклоняет связи с такими именами; совпадение со switch Proxy проверяет check-docs.
+ * Имена методов цепочки, корня `db` и батча. Там, где имя занято методом, библиотека не ищет его среди классов, и шаг с
+ * таким именем до класса не дойдёт; класс-связь (`link`) с таким именем база не создаст (`invalid_class`). Не давайте
+ * классам эти имена.
  */
 export declare const RESERVED_CLASS_NAMES: readonly string[];
 /** Строка ответа: текущая версия (или версия журнала для asOf, versions, withDeleted). */
@@ -78,7 +85,7 @@ export type Filter = string | string[] | Op | {
 } | {
     [field: string]: FieldFilter | undefined;
 };
-/** Курсор keyset-пагинации: значение поля сортировки и id последней строки страницы. */
+/** Курсор постраничного вывода для `after()`: значение поля сортировки и id последней строки страницы. */
 export interface Cursor {
     v: string | number | boolean | null;
     id: string;

package/dist/types.js

@@ -1,8 +1,12 @@
 /**
  * Общие типы letopis 1.0. Файл наполняется по этапам плана (reports/PLAN-LETOPIS-1.0.md).
  */
-/** Ревизия движка в базе: штамп в lib/sql/99-revision.sql должен совпадать (этап 1). */
-export const DDL_REVISION = 6;
+/**
+ * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии `up()` обновляет только с `upgrade: true`,
+ * а `connect()` о ней предупреждает.
+ */
+export const DDL_REVISION = 7;
 /**
  * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
  * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
@@ -11,7 +15,10 @@ export const ACL_CLASS_NAMES = ['rule', 'Resource', 'member', 'Account', 'Class'
 // ---------------------------------------------------------------------------
 // Методы цепочки — единственный источник зарезервированных имён (план, §2.14, этап 3, п. 10)
 // ---------------------------------------------------------------------------
-/** Методы цепочки: терминалы, модификаторы, глаголы записи (этап 4), охранники снесённого API. */
+/**
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then` и снятые методы прежних
+ * версий. После шага цепочки эти имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
+ */
 export const CHAIN_METHODS = [
     'then', 'entity', 'paths', 'rows', 'first', 'ids', 'count', 'limit', 'offset', 'sort', 'asOf', 'withDeleted',
     'deep', 'exact', 'sum', 'avg', 'min', 'max', 'countBy', 'after', 'versions', 'create', 'update', 'upsert', 'set',
@@ -28,9 +35,9 @@ export const DB_METHODS = [
 /** Свойства батча db.batch(name). */
 export const BATCH_METHODS = ['discard', 'size'];
 /**
- * Зарезервированные имена: Proxy разбирает их раньше классов, поэтому класс с таким именем
- * недостижим как шаг. Установщик подставляет список в функцию базы reserved_names(), которая
- * отклоняет связи с такими именами; совпадение со switch Proxy проверяет check-docs.
+ * Имена методов цепочки, корня `db` и батча. Там, где имя занято методом, библиотека не ищет его среди классов, и шаг с
+ * таким именем до класса не дойдёт; класс-связь (`link`) с таким именем база не создаст (`invalid_class`). Не давайте
+ * классам эти имена.
  */
 export const RESERVED_CLASS_NAMES = [...new Set([...CHAIN_METHODS, ...DB_METHODS, ...BATCH_METHODS])];
 /** Метка операторов фильтра (символ не пересекается с данными). */

package/dist/up.d.ts

@@ -8,28 +8,36 @@ export interface InstallOptions {
     schema: string;
     owner?: string;
     app?: string;
-    /** Константа установки: разрешён ли reset (план, §2.2). По умолчанию выключен. */
+    /**
+     * Разрешить `db.reset()` и `maintain({ now })` — для тестовых установок и стендов; по умолчанию запрещено. Значение
+     * задаётся при установке и хранится в схеме: каждый `up()` записывает его заново (план, §2.2).
+     */
     allowReset?: boolean;
     /**
-     * Константа установки: политика хранения истории для классов без своей (план, §2.11), например
-     * `{ all: '1 day', daily: '1 week', weekly: '1 month', monthly: '1 year', yearly: 'forever' }`.
-     * Не задана — история хранится вся.
+     * Политика хранения истории для классов без своей, например
+     * `{ all: '1 day', daily: '1 week', weekly: '1 month', monthly: '1 year', yearly: 'forever' }`; не задана — история
+     * хранится вся. Значение задаётся при установке и хранится в схеме: каждый `up()` записывает его заново (план, §2.11).
      */
     history?: HistoryPolicy;
     /** Номер последнего накатываемого файла — для пошаговых тестов. */
     upTo?: number;
     /** Сиды после ядра: имена lib/sql/seed.<имя>.sql (например 'booking') или пути к своим файлам .sql. */
     seeds?: string[];
-    /** Обновление (upgrade): ревизия схемы до наката — миграции lib/sql/migrate/ с номером выше неё. */
+    /**
+     * Обновление (upgrade): ревизия схемы до наката — миграции lib/sql/migrate/ с номером выше неё. Если под блокировкой
+     * схемы видна более новая ревизия (её уже обновил одновременный up()), миграции считаются от неё.
+     */
     migrateFrom?: number;
+    /** Удалить схему и поставить заново (up({ fresh })) — под той же блокировкой схемы, что и накат. ДАННЫЕ ТЕРЯЮТСЯ. */
+    fresh?: boolean;
     /** Каталог миграций (по умолчанию lib/sql/migrate). */
     migrationsDir?: string;
     /** Свой ключ сервиса: зарегистрировать, если такого ещё нет (вместо выпуска случайного). */
     serviceKey?: string;
     /**
-     * Режим сигналов NOTIFY (план 1.1, §2.2): 'class' (по умолчанию, как в 1.0) — имена классов; 'tenant' —
-     * имя класса и токен арендатора; 'opaque' — только токены; 'none' — сигналов нет. Режим хранится в
-     * схеме: накат без опции его не меняет, reset({ all }) — сохраняет.
+     * Что видно в сигналах базы (`NOTIFY`): `'class'` (у новой схемы по умолчанию) — имя класса; `'tenant'` — имя класса и
+     * псевдоним арендатора (токен); `'opaque'` — только псевдонимы класса и арендатора; `'none'` — сигналов нет.
+     * Режим хранится в схеме: `up()` без опции его не меняет, `reset({ all })` сохраняет (план 1.1, §2.2).
      */
     signals?: SignalMode;
 }
@@ -47,7 +55,11 @@ export interface InstallResult {
     schema: string;
     owner: string;
     app: string;
-    /** Ключ сервисного аккаунта; выдаётся только при первой установке (или зарегистрированный свой), дальше — null. */
+    /**
+     * Ключ API сервисного аккаунта, выпущенный или зарегистрированный этим накатом, иначе `null`. Без опции `serviceKey`
+     * новый ключ выпускается на любом накате, где в схеме не осталось ни одного неотозванного ключа API, — не только при
+     * первой установке; свой `serviceKey` регистрируется и возвращается, если неотозванного ключа с таким значением ещё нет.
+     */
     serviceKey: string | null;
     /** Применённые миграции. */
     migrations: string[];
@@ -57,8 +69,27 @@ export interface InstallResult {
 export declare const quoteIdent: (name: string) => string;
 /** Файлы ядра по номеру: `10-core.sql` … `99-revision.sql`; сиды демо-домена сюда не входят. */
 export declare function engineFiles(upTo?: number): Promise<string[]>;
+/** Штамп движка: версия пакета и хэш файлов ядра (`99-revision.sql` пишет его в комментарий схемы). */
+export interface EngineStamp {
+    version: string;
+    sql: string;
+}
+/**
+ * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF): одна и та же
+ * сборка даёт один штамп при любых опциях установки, а версия пакета без правок SQL штамп не меняет.
+ */
+export declare function engineStamp(): Promise<EngineStamp>;
+/** Сравнение версий semver (метаданные сборки не учитываются): меньше нуля, ноль, больше нуля. */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Штамп схемы (комментарий схемы) против файлов ядра пакета — текст предупреждения или null. Ревизия та же, а
+ * функции поставила другая версия движка: после обновления пакета не накатили up() (так было при 1.1 → 1.2).
+ */
+export declare function stampDrift(schema: string, comment: string): Promise<string | null>;
 export declare function substitute(text: string, vars: Record<string, string>): string;
-export declare function install(sql: postgres.Sql, opts: InstallOptions): Promise<InstallResult>;
+export declare function install(sql: postgres.Sql, opts: InstallOptions): Promise<InstallResult & {
+    found: number | null;
+}>;
 /** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */
 export declare function migrationFiles(dir: string, from: number): Promise<string[]>;
 export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'migrateFrom'> {
@@ -77,11 +108,16 @@ export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'mig
     /** Сколько ждать базу, мс (по умолчанию 60 000). */
     waitTimeoutMs?: number;
     /**
-     * База для разработки без PostgreSQL (решение 6 точки А): PGlite с pgcrypto через pglite-socket;
-     * одно соединение — connect({ dsn: r.pglite.dsn, listen: false, max: 1 }); не для гонок и CI.
+     * Запустить PGlite — PostgreSQL прямо в процессе Node — для разработки без своего сервера (решение 6 точки А);
+     * подключение к нему — `connect({ dsn: r.pglite.dsn, schema: r.schema, listen: false, max: 1, allowBypassRls: true })`.
+     * Соединение у PGlite одно, поэтому одновременные транзакции и гонки на нём не проверить: для таких тестов и в CI нужен
+     * настоящий PostgreSQL.
      */
     pglite?: boolean | PgliteOptions;
-    /** Арендатор и его первый пользователь — без своего сида (createTenant). */
+    /**
+     * Арендатор и его первый пользователь: после установки `up()` заводит их сам, как `createTenant()` с этими опциями, и
+     * кладёт итог в `r.tenant` — свой сид для этого не нужен.
+     */
     tenant?: TenantOptions;
 }
 export interface UpResult extends InstallResult {
@@ -117,14 +153,18 @@ export declare function ensureDatabase(dsn: string, log?: (m: string) => void):
  */
 export declare function checkServer(versionNum: number, encoding: string): string[];
 /** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
-export declare function schemaRevision(sql: postgres.Sql, schema: string): Promise<number | null>;
+export declare function schemaRevision(sql: Pick<postgres.Sql, 'unsafe'>, schema: string): Promise<number | null>;
 /**
- * Поставить или обновить установку letopis. Схема есть и её ревизия совпадает — повторный накат
- * (идемпотентный); ревизия отстала — только с upgrade: true; новее библиотеки — отказ.
+ * Ставит или обновляет установку letopis в схеме. Если схема уже есть и её ревизия та же, что у пакета, `up()` выполняет
+ * повторный накат: заново ставит функции, не трогая данные, — поэтому его можно вызывать при каждом запуске приложения.
+ * Схему отставшей ревизии `up()` обновляет только с `upgrade: true`, а на схеме новее пакета отказывает.
  */
 export declare function up(opts: UpOptions): Promise<UpResult>;
 export interface TenantOptions {
-    /** Имя арендатора (аккаунт в System; id — v5 от «tenant:<имя>», как у letopis import --tenant). */
+    /**
+     * Имя арендатора — его аккаунта в System. Из имени вычисляется id арендатора, поэтому одно имя — всегда один и тот же
+     * арендатор (так же его находит `letopis import --tenant`).
+     */
     name: string;
     /** Правило арендатора «аутентифицированным можно всё» (READ, WRITE, DELETE; по умолчанию да). */
     grantAll?: boolean;
@@ -133,6 +173,10 @@ export interface TenantOptions {
         name: string;
         login: string;
         password: string;
+        /**
+         * Вид пароля (по умолчанию PASSWORD) — как у auth.setPassword: `^[A-Z][A-Z0-9_]{1,31}$`, не служебный вид (SESSION,
+         * APIKEY, KEYSECRET, OTP, TOTP, KEY, PROJECTOR, LOCK); иначе invalid_data.
+         */
         kind?: string;
         ttl?: string;
         /** Роли членства (по умолчанию ['owner']); роли уже существующего членства повтор не меняет. */
@@ -150,14 +194,10 @@ export interface TenantResult {
     created: boolean;
 }
 /**
- * Арендатор и его первый пользователь — то, что раньше делал свой сид функциями владельца
- * (sys_create, sys_grant_all). Нужно администраторское подключение (роль может стать владельцем);
- * всё — одной транзакцией от владельца. Повтор с тем же именем и логином ничего не дублирует:
- * id — v5 от имени и логина, существующие строки пропускаются (пароль и роли членства не меняются),
- * сессия выдаётся заново. Удалённые арендатор, аккаунт пользователя или членство (строки нет, а
- * журнал id есть) — отказ invalid_data, транзакция откатывается целиком: повтор не воскрешает то,
- * что удалил администратор (up({ tenant }) идёт при каждом запуске), а sys_create пишет только
- * версию 1 — её занимает история; вернуть строку — restore() цепочкой.
+ * Заводит арендатора и, по желанию, его первого пользователя (аккаунт, членство, пароль, сессию) одной транзакцией от
+ * роли-владельца схемы — поэтому нужен администраторский пул. Повтор с тем же именем и логином ничего не дублирует и не
+ * меняет, только выдаёт пользователю новую сессию; одновременные вызовы заводят арендатора один раз. Если арендатор,
+ * пользователь или членство были удалены, повтор их не воскрешает — отказ `invalid_data`.
  */
 export declare function createTenant(sql: postgres.Sql, schema: string, opts: TenantOptions, owner?: string): Promise<TenantResult>;
 export {};