letopis 0.20.3 → 1.0.0

package/dist/up.d.ts

@@ -1,56 +1,149 @@
-import type { EntityDb } from './chain.js';
-import type { ConnectOpts } from './types.js';
-export interface UpOpts extends Omit<ConnectOpts, 'dsn' | 'schema'> {
-    /** postgres://user:pass@host:port/db. Default postgres://postgres:test@localhost:15432/letopis. */
-    dsn?: string;
-    /** Базовое имя схемы БЕЗ версии и точек (напр. 'booking'). */
+import postgres from 'postgres';
+import { type PgliteOptions, type PgliteServer } from './pglite.js';
+export declare const SYSTEM_ID = "2eba6d0a-1edd-4bb6-a85a-a703dab49035";
+export declare const SCHEMA_VERSION = "v2";
+export interface InstallOptions {
+    /** Полное имя схемы с версией, например `v2.salon`. */
     schema: string;
-    /** Версия движка: итоговая PG-схема "v<N>.<schema>". Бамп руками при breaking-изменении DDL. */
-    version: number;
-    /** Имя dev-контейнера. Default 'letopis-timescale'. */
-    container?: string;
-    /** Имя docker-образа; при отсутствии соберётся из пакованного Dockerfile. Default 'letopis-db'. */
-    image?: string;
-    /**
-     * Где держать данные PG: путь на хосте (bind mount, на Windows/NTFS — на свой риск)
-     * либо имя docker-volume. Default — named volume 'letopis-pgdata' (кроссплатформенно;
-     * переживает пересоздание контейнера).
-     */
-    dataDir?: string;
-    /** Хост-порт Redis контейнера. Default 16379. */
-    redisPort?: number;
+    owner?: string;
+    app?: string;
+    /** Константа установки: разрешён ли reset (план, §2.2). По умолчанию выключен. */
+    allowReset?: boolean;
     /**
-     * Сиды после ddl: массив путей — свои файлы (маркер "<SCHEMA-NAME>" в них поддержан);
-     * default — демо booking + auth. Свой сид должен дать хотя бы один класс в Schema
-     * (иначе connect в конце честно упадёт «has no classes»); false — голая структура
-     * без сидов, годится только чтобы поставить движок — connect не переживёт.
+     * Константа установки: политика хранения истории для классов без своей (план, §2.11), например
+     * `{ all: '1 day', daily: '1 week', weekly: '1 month', monthly: '1 year', yearly: 'forever' }`.
+     * Не задана — история хранится вся.
      */
-    seeds?: string[] | false;
-    /** Дропнуть схему и накатить заново. ДАННЫЕ СХЕМЫ ТЕРЯЮТСЯ. */
+    history?: HistoryPolicy;
+    /** Номер последнего накатываемого файла — для пошаговых тестов. */
+    upTo?: number;
+    /** Сиды после ядра: имена lib/sql/seed.<имя>.sql (например 'booking') или пути к своим файлам .sql. */
+    seeds?: string[];
+    /** Обновление (upgrade): ревизия схемы до наката — миграции lib/sql/migrate/ с номером выше неё. */
+    migrateFrom?: number;
+    /** Каталог миграций (по умолчанию lib/sql/migrate). */
+    migrationsDir?: string;
+    /** Свой ключ сервиса: зарегистрировать, если такого ещё нет (вместо выпуска случайного). */
+    serviceKey?: string;
+}
+/** Политика хранения истории (§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;
+    app: string;
+    /** Ключ сервисного аккаунта; выдаётся только при первой установке (или зарегистрированный свой), дальше — null. */
+    serviceKey: string | null;
+    /** Применённые миграции. */
+    migrations: string[];
+}
+export declare const quoteIdent: (name: string) => string;
+/** Файлы ядра по номеру: `10-core.sql` … `99-revision.sql`; сиды демо-домена сюда не входят. */
+export declare function engineFiles(upTo?: number): Promise<string[]>;
+export declare function substitute(text: string, vars: Record<string, string>): string;
+export declare function install(sql: postgres.Sql, opts: InstallOptions): Promise<InstallResult>;
+/** Миграции с номером выше ревизии from и не выше DDL_REVISION: `0004-описание.sql`, по номеру. */
+export declare function migrationFiles(dir: string, from: number): Promise<string[]>;
+export interface UpOptions extends Omit<InstallOptions, 'schema' | 'upTo' | 'migrateFrom'> {
+    /** Администраторская строка подключения (роль-установщик). */
+    dsn?: string;
+    /** Готовый пул postgres.js вместо dsn (база уже существует). */
+    sql?: postgres.Sql;
+    /** Схема: полное имя v2.<имя> или только <имя> — версия структуры подставится сама. */
+    schema: string;
+    /** Удалить схему и поставить заново. ДАННЫЕ СХЕМЫ ТЕРЯЮТСЯ. */
     fresh?: boolean;
-    /**
-     * Перекатить `ddl.sql` на СУЩЕСТВУЮЩУЮ схему (сиды не трогаются, данные целы).
-     * Так доезжают аддитивные правки движка: схема, накатанная старой либой, не имеет новых
-     * функций/триггеров (например `purge`/`purge_account` из 0.19.0) и падает сырым
-     * «function … does not exist». О расхождении предупреждает `connect()` (см. `DDL_REVISION`).
-     * Идемпотентно; на несуществующей схеме — обычный первый накат.
-     */
+    /** Обновить схему отставшей ревизии: миграции и повторный накат; данные сохраняются. */
     upgrade?: boolean;
-    /** Без console.log-прогресса. */
+    /** Без сообщений в консоль. */
     quiet?: boolean;
-    /** Максимум ожидания готовности, мс. Default 120 000 (первый запуск: pull образа + initdb). */
+    /** Сколько ждать базу, мс (по умолчанию 60 000). */
     waitTimeoutMs?: number;
+    /**
+     * База для разработки без PostgreSQL (решение 6 точки А): PGlite с pgcrypto через pglite-socket;
+     * одно соединение — connect({ dsn: r.pglite.dsn, listen: false, max: 1 }); не для гонок и CI.
+     */
+    pglite?: boolean | PgliteOptions;
+    /** Арендатор и его первый пользователь — без своего сида (createTenant). */
+    tenant?: TenantOptions;
+}
+export interface UpResult extends InstallResult {
+    /** Схемы не было — поставлена. */
+    created: boolean;
+    /** Схема была отставшей ревизии — обновлена. */
+    upgraded: boolean;
+    /** Ревизия движка после наката. */
+    revision: number;
+    /** Таблицы, для которых выполнен ANALYZE (статистики не было). */
+    analyzed: string[];
+    /** up({ pglite }): запущенный PGlite — строка подключения и остановка. */
+    pglite?: PgliteServer;
+    /** up({ tenant }): арендатор (и его первый пользователь с сессией). */
+    tenant?: TenantResult;
+}
+type Ping = {
+    ok: true;
+} | {
+    ok: false;
+    kind: 'no-server' | 'no-database' | 'starting' | 'fatal';
+    err: unknown;
+};
+/** Проба сервера: ok | нет сервера | нет базы | запускается | роковая ошибка (неверный пароль). */
+export declare function pgPing(dsn: string): Promise<Ping>;
+/** Создать базу строки подключения, если её нет (гонка параллельных up() — 42P04 — не ошибка). */
+export declare function ensureDatabase(dsn: string, log?: (m: string) => void): Promise<boolean>;
+/** Версия сервера и кодировка базы: PostgreSQL 18+ и UTF8 (casefold и pg_unicode_fast требуют UTF8). */
+export declare function checkServer(versionNum: number, encoding: string): void;
+/** Ревизия движка схемы по комментарию 'letopis ddl_revision=N'; схемы нет — null. */
+export declare function schemaRevision(sql: postgres.Sql, schema: string): Promise<number | null>;
+/**
+ * Поставить или обновить установку letopis. Схема есть и её ревизия совпадает — повторный накат
+ * (идемпотентный); ревизия отстала — только с upgrade: true; новее библиотеки — отказ.
+ */
+export declare function up(opts: UpOptions): Promise<UpResult>;
+export interface TenantOptions {
+    /** Имя арендатора (аккаунт в System; id — v5 от «tenant:<имя>», как у letopis import --tenant). */
+    name: string;
+    /** Правило арендатора «аутентифицированным можно всё» (READ, WRITE, DELETE; по умолчанию да). */
+    grantAll?: boolean;
+    /** Первый пользователь: аккаунт, членство в арендаторе с ролями roles, пароль и сессия в арендаторе. */
+    user?: {
+        name: string;
+        login: string;
+        password: string;
+        kind?: string;
+        ttl?: string;
+        /** Роли членства (по умолчанию ['owner']); роли уже существующего членства повтор не меняет. */
+        roles?: string[];
+    };
 }
-export interface RunCfg {
-    container: string;
-    image: string;
-    pgPort: string;
-    redisPort: number;
-    user: string;
-    password: string;
-    database: string;
-    dataDir?: string;
+export interface TenantResult {
+    /** id аккаунта-арендатора. */
+    tenant: string;
+    /** id аккаунта пользователя (если задан). */
+    user: string | null;
+    /** Токен сессии пользователя в арендаторе: connect({ token }) (если задан пользователь). */
+    token: string | null;
+    /** Арендатор создан этим вызовом (повтор с тем же именем — false). */
+    created: boolean;
 }
-/** argv для docker run (чистая функция — покрыта юнитом). dataDir: путь → bind, имя → volume. */
-export declare function dockerRunArgs(cfg: RunCfg): string[];
-export declare function up(opts: UpOpts): Promise<EntityDb>;
+/**
+ * Арендатор и его первый пользователь — то, что раньше делал свой сид функциями владельца
+ * (sys_create, sys_grant_all). Нужно администраторское подключение (роль может стать владельцем);
+ * всё — одной транзакцией от владельца. Повтор с тем же именем и логином ничего не дублирует:
+ * id — v5 от имени и логина, существующие строки пропускаются (пароль и роли членства не меняются),
+ * сессия выдаётся заново. Удалённые арендатор, аккаунт пользователя или членство (строки нет, а
+ * журнал id есть) — отказ invalid_data, транзакция откатывается целиком: повтор не воскрешает то,
+ * что удалил администратор (up({ tenant }) идёт при каждом запуске), а sys_create пишет только
+ * версию 1 — её занимает история; вернуть строку — restore() цепочкой.
+ */
+export declare function createTenant(sql: postgres.Sql, schema: string, opts: TenantOptions, owner?: string): Promise<TenantResult>;
+export {};