letopis 1.4.2 → 3.0.0

package/dist/types.js

@@ -3,10 +3,15 @@
  */
 /**
  * Ревизия схемы, которую знает эта версия пакета, — номер версии SQL-части letopis (таблиц и функций в схеме установки).
- * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии `up()` обновляет только с `upgrade: true`,
- * а `connect()` о ней предупреждает.
+ * После `up()` у схемы та же ревизия (`r.revision`); схему отставшей ревизии 2.x `up()` обновляет только с
+ * `upgrade: true`, а `connect()` о ней предупреждает.
  */
-export const DDL_REVISION = 7;
+export const DDL_REVISION = 11;
+/**
+ * Префикс версии в имени схемы `v<N>.<имя>`: `up({ schema: 'salon' })` и `connect({ schema: 'salon' })` дописывают его к
+ * имени без точки — `v2.salon`.
+ */
+export const SCHEMA_VERSION = 'v2';
 /**
  * Классы, строки которых меняют права и схему: их запись повышает счётчик прав (загрузчик), а сигнал
  * сбрасывает весь кэш результатов и пропуска прав. Тот же список — в триггерах базы (60-write.sql).
@@ -16,28 +21,26 @@ export const ACL_CLASS_NAMES = ['rule', 'Resource', 'member', 'Account', 'Class'
 // Методы цепочки — единственный источник зарезервированных имён (план, §2.14, этап 3, п. 10)
 // ---------------------------------------------------------------------------
 /**
- * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `then` и снятые методы прежних
- * версий. После шага цепочки эти имена библиотека не ищет среди классов; все они входят в `RESERVED_CLASS_NAMES`.
+ * Имена методов цепочки: модификаторы, терминалы, глаголы записи и слоты концов, а также `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',
-    'unset', 'add', 'remove', 'delete', 'anonymize', 'reclass', 'restore', 'purge', 'alias', 'tags', 'owner',
-    'forUpdate', 'cache', 'rekey', 'run', 'execute', 'account', 'diff', 'blame',
+    'unset', 'add', 'remove', 'delete', 'restore', 'alias', 'tags', 'owner', 'forUpdate', 'cache',
 ];
 /** Свойства корня db (и транзакции db.begin()). */
 export const DB_METHODS = [
-    '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',
+    'as', 'begin', 'commit', 'rollback', 'lock', 'batch', 'watch', 'close', 'registry', 'sql', 'load',
+    'maintain', 'auth', 'acl', 'idOf', 'refresh', 'transaction', 'flushSignals', 'schema', 'token', 'tenant', 'cache',
 ];
 /** Свойства батча db.batch(name). */
-export const BATCH_METHODS = ['discard', 'size'];
+export const BATCH_METHODS = ['run', 'discard', 'size'];
 /**
  * Имена методов цепочки, корня `db` и батча. Там, где имя занято методом, библиотека не ищет его среди классов, и шаг с
- * таким именем до класса не дойдёт; класс-связь (`link`) с таким именем база не создаст (`invalid_class`). Не давайте
- * классам эти имена.
+ * таким именем до класса не дойдёт. Хаб с таким именем отклоняют `hub()`, `syncModels` и база, связь (`link`) — база
+ * (`invalid_class`; план 2.0, этап 4, п. 2); хаб, заведённый мимо проверки базы, `up()` оставляет и называет в
+ * предупреждении.
  */
 export const RESERVED_CLASS_NAMES = [...new Set([...CHAIN_METHODS, ...DB_METHODS, ...BATCH_METHODS])];
 /** Метка операторов фильтра (символ не пересекается с данными). */

package/dist/up.d.ts

@@ -1,24 +1,26 @@
 import postgres from 'postgres';
+import { SCHEMA_VERSION, type LogOptions } from './types.js';
 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";
+export { SCHEMA_VERSION };
+/**
+ * Первая ревизия движка 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 +39,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 +67,9 @@ export interface EngineStamp {
     sql: string;
 }
 /**
- * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF): одна и та же
- * сборка даёт один штамп при любых опциях установки, а версия пакета без правок SQL штамп не меняет.
+ * Штамп движка этого пакета. Хэш — по исходному тексту файлов ядра до подстановок (переводы строк — LF) и по каталогу
+ * сообщений базы (разделы sql-*, подстановка @MESSAGES@): одна и та же сборка даёт один штамп при любых опциях
+ * установки, а версия пакета без правок SQL и этих разделов штамп не меняет.
  */
 export declare function engineStamp(): Promise<EngineStamp>;
 /** Сравнение версий semver (метаданные сборки не учитываются): меньше нуля, ноль, больше нуля. */
@@ -92,7 +85,7 @@ export declare function install(sql: postgres.Sql, opts: InstallOptions): Promis
 }>;
 /** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */
 export declare function migrationFiles(dir: string, from: number): Promise<string[]>;
-export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'migrateFrom'> {
+export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'migrateFrom'>, LogOptions {
     /** Администраторская строка подключения (роль-установщик). */
     dsn?: string;
     /** Готовый пул postgres.js вместо dsn (база уже существует). */
@@ -101,14 +94,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 +112,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 +133,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 +173,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 +197,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;
@@ -200,4 +222,3 @@ export interface TenantResult {
  * пользователь или членство были удалены, повтор их не воскрешает — отказ `invalid_data`.
  */
 export declare function createTenant(sql: postgres.Sql, schema: string, opts: TenantOptions, owner?: string): Promise<TenantResult>;
-export {};