letopis 1.4.1 → 2.0.0

package/dist/up.d.ts

@@ -3,22 +3,23 @@ import { type PgliteOptions, type PgliteServer } from './pglite.js';
 import { type SignalMode } from './signals.js';
 export declare const SYSTEM_ID = "2eba6d0a-1edd-4bb6-a85a-a703dab49035";
 export declare const SCHEMA_VERSION = "v2";
+/**
+ * Первая ревизия движка 2.0 (план 2.0, редакция 2): схема ниже неё — letopis 1.x или схема без штампа ревизии. Её
+ * `up()` не обновляет, а `connect()` к ней не подключается: 2.0 ставится только заново (`up({ fresh: true })`), данные
+ * 1.x не переносятся. Накат миграций `up({ upgrade })` — в пределах 2.x, от этой ревизии до `DDL_REVISION`.
+ */
+export declare const FIRST_REVISION = 8;
+/**
+ * Отказ на схеме letopis 1.x (план 2.0, 7.10 №5): ревизия из комментария схемы ниже `FIRST_REVISION` — 7 и ниже у 1.x,
+ * 0 — штампа ревизии нет. `up()` зовёт её до любых изменений (до общей части `install()`), `connect()` — до входа по
+ * ключу: функции схемы 1.x не вызываются.
+ */
+export declare function refuse1x(schema: string, rev: number): void;
 export interface InstallOptions {
     /** Полное имя схемы с версией, например `v2.salon`. */
     schema: string;
     owner?: string;
     app?: string;
-    /**
-     * Разрешить `db.reset()` и `maintain({ now })` — для тестовых установок и стендов; по умолчанию запрещено. Значение
-     * задаётся при установке и хранится в схеме: каждый `up()` записывает его заново (план, §2.2).
-     */
-    allowReset?: boolean;
-    /**
-     * Политика хранения истории для классов без своей, например
-     * `{ 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. */
@@ -37,20 +38,10 @@ export interface InstallOptions {
     /**
      * Что видно в сигналах базы (`NOTIFY`): `'class'` (у новой схемы по умолчанию) — имя класса; `'tenant'` — имя класса и
      * псевдоним арендатора (токен); `'opaque'` — только псевдонимы класса и арендатора; `'none'` — сигналов нет.
-     * Режим хранится в схеме: `up()` без опции его не меняет, `reset({ all })` сохраняет (план 1.1, §2.2).
+     * Режим хранится в схеме: `up()` без опции его не меняет.
      */
     signals?: SignalMode;
 }
-/** Политика хранения истории (§2.11): сроки ярусов по возрастанию, 'forever' — бессрочно. */
-export interface HistoryPolicy {
-    all: string;
-    daily?: string;
-    weekly?: string;
-    monthly?: string;
-    yearly?: string;
-    /** Часовой пояс границ периодов (по умолчанию UTC). */
-    tz?: string;
-}
 export interface InstallResult {
     schema: string;
     owner: string;
@@ -75,8 +66,9 @@ export interface EngineStamp {
     sql: string;
 }
 /**
- * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF): одна и та же
- * сборка даёт один штамп при любых опциях установки, а версия пакета без правок SQL штамп не меняет.
+ * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF) и по каталогу
+ * сообщений базы (разделы sql-*, подстановка @MESSAGES@): одна и та же сборка даёт один штамп при любых опциях
+ * установки, а версия пакета без правок SQL и этих разделов штамп не меняет.
  */
 export declare function engineStamp(): Promise<EngineStamp>;
 /** Сравнение версий semver (метаданные сборки не учитываются): меньше нуля, ноль, больше нуля. */
@@ -101,14 +93,14 @@ export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'mig
     schema: string;
     /** Удалить схему и поставить заново. ДАННЫЕ СХЕМЫ ТЕРЯЮТСЯ. */
     fresh?: boolean;
-    /** Обновить схему отставшей ревизии: миграции и повторный накат; данные сохраняются. */
+    /** Обновить схему отставшей ревизии 2.x: миграции и повторный накат; данные сохраняются. */
     upgrade?: boolean;
     /** Без сообщений в консоль. */
     quiet?: boolean;
     /** Сколько ждать базу, мс (по умолчанию 60 000). */
     waitTimeoutMs?: number;
     /**
-     * Запустить PGlite — PostgreSQL прямо в процессе Node — для разработки без своего сервера (решение 6 точки А);
+     * Запустить PGlite — PostgreSQL прямо в процессе Node — для разработки без своего сервера;
      * подключение к нему — `connect({ dsn: r.pglite.dsn, schema: r.schema, listen: false, max: 1, allowBypassRls: true })`.
      * Соединение у PGlite одно, поэтому одновременные транзакции и гонки на нём не проверить: для таких тестов и в CI нужен
      * настоящий PostgreSQL.
@@ -119,6 +111,19 @@ export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'mig
      * кладёт итог в `r.tenant` — свой сид для этого не нужен.
      */
     tenant?: TenantOptions;
+    /**
+     * Роль приложения с логином (план 2.0, этап 3): заводится или получает новый пароль и членство в роли приложения
+     * (`letopis_app`). Имя и пароль квотирует база (`format` с `%I` и `%L`). Привилегированную роль — суперпользователя,
+     * с `CREATEROLE`, `CREATEDB`, `REPLICATION`, `BYPASSRLS`, роль-владельца или её члена — up() не трогает
+     * (`invalid_data`). Строка подключения роли — `r.login.dsn`: с ней и `connect({ admin })` малое приложение работает
+     * одним процессом.
+     */
+    login?: LoginOptions;
+}
+/** Роль приложения up({ login }). */
+export interface LoginOptions {
+    user: string;
+    password: string;
 }
 export interface UpResult extends InstallResult {
     /** Схемы не было — поставлена. */
@@ -127,13 +132,28 @@ export interface UpResult extends InstallResult {
     upgraded: boolean;
     /** Ревизия движка после наката. */
     revision: number;
-    /** Таблицы, для которых выполнен ANALYZE (статистики не было). */
+    /**
+     * Таблицы, у которых статистики не было и ANALYZE от роли владельца её собрал; оставшиеся без статистики — в
+     * `warnings`.
+     */
     analyzed: string[];
     /** up({ pglite }): запущенный PGlite — строка подключения и остановка. */
     pglite?: PgliteServer;
     /** up({ tenant }): арендатор (и его первый пользователь с сессией). */
     tenant?: TenantResult;
-    /** Предупреждения (версия сервера); без quiet каждое уже напечатано через console.warn. */
+    /**
+     * up({ login }): роль приложения — заведена (`created`) или получила новый пароль; `dsn` — строка подключения роли
+     * (из `dsn` установки или PGlite; при готовом пуле `sql` её нет).
+     */
+    login?: {
+        user: string;
+        created: boolean;
+        dsn?: string;
+    };
+    /**
+     * Предупреждения (версия сервера, таблицы без статистики, хабы с зарезервированными именами); без quiet каждое уже
+     * напечатано через console.warn.
+     */
     warnings: string[];
 }
 type Ping = {
@@ -152,18 +172,19 @@ export declare function ensureDatabase(dsn: string, log?: (m: string) => void):
  * иначе отказ. Возвращает предупреждения: с чем установка работает, но рискует.
  */
 export declare function checkServer(versionNum: number, encoding: string): string[];
-/** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
+/** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null, штампа ревизии нет — 0. */
 export declare function schemaRevision(sql: Pick<postgres.Sql, 'unsafe'>, schema: string): Promise<number | null>;
 /**
  * Ставит или обновляет установку letopis в схеме. Если схема уже есть и её ревизия та же, что у пакета, `up()` выполняет
  * повторный накат: заново ставит функции, не трогая данные, — поэтому его можно вызывать при каждом запуске приложения.
- * Схему отставшей ревизии `up()` обновляет только с `upgrade: true`, а на схеме новее пакета отказывает.
+ * Схему отставшей ревизии 2.x `up()` обновляет только с `upgrade: true`, а на схеме новее пакета отказывает. Схему без
+ * штампа ревизии не трогает и отказывает (`invalid_data`): заново её ставит `up({ fresh: true })`.
  */
 export declare function up(opts: UpOptions): Promise<UpResult>;
 export interface TenantOptions {
     /**
      * Имя арендатора — его аккаунта в System. Из имени вычисляется id арендатора, поэтому одно имя — всегда один и тот же
-     * арендатор (так же его находит `letopis import --tenant`).
+     * арендатор.
      */
     name: string;
     /** Правило арендатора «аутентифицированным можно всё» (READ, WRITE, DELETE; по умолчанию да). */
@@ -175,7 +196,7 @@ export interface TenantOptions {
         password: string;
         /**
          * Вид пароля (по умолчанию PASSWORD) — как у auth.setPassword: `^[A-Z][A-Z0-9_]{1,31}$`, не служебный вид (SESSION,
-         * APIKEY, KEYSECRET, OTP, TOTP, KEY, PROJECTOR, LOCK); иначе invalid_data.
+         * APIKEY, KEYSECRET, OTP, TOTP, KEY, LOCK); иначе invalid_data.
          */
         kind?: string;
         ttl?: string;