letopis 1.4.2 → 3.0.0

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * Этап 2: connect() — подключение под сессией, реестр классов, отложенный сигнал, db.sql.
  * Этап 3: цепочки чтения t.Класс(…).Связь().rows(); этап 4 — запись цепочками и загрузчик.
  * Этап 5: db.auth (креды, вход, сессии), db.acl, db.as(аккаунт, { tenant }) — имперсонация.
- * Этап 6: история (restore, purge, rekey, trimHistory), verify, maintain, reset, watch, кэш результатов.
+ * Этап 6: история (versions, asOf, restore), maintain, watch, кэш результатов.
  */
 import postgres from 'postgres';
 import { Registry } from './registry.js';
@@ -13,58 +13,71 @@ import { type Tx } from './tx.js';
 import { type AuthApi } from './auth.js';
 import { type AclApi } from './acl.js';
 import { type LoadInput, type LoadOptions, type LoadReport } from './load.js';
-import { type Batch, type Chain, type StepFn } from './chain.js';
-import type { QueryEvent, Row } from './types.js';
+import { type Batch, type Chain, type ChainRef, type StepFn } from './chain.js';
+import type { LogOptions, QueryEvent, Row } from './types.js';
 import { type CacheOptions, type CacheStats } from './cache.js';
 import { Subscription, type WatchOptions } from './watch.js';
-import { Projector, type ProjectorOptions } from './project.js';
-import { type MaintainOptions, type MaintainReport, type ModelDescription, type ResetOptions, type ResetResult, type VerifyResult } from './admin.js';
-import type { AnyModelLike, StepsOf } from './typed.js';
+import { type MaintainReport } from './admin.js';
+import type { AnyModelLike, OrOp, StepsOf } from './typed.js';
 export { DDL_REVISION } from './types.js';
 export { uuidv5, v5Name, v5Id, idOf, type KeyedClass } from './uuid.js';
 export { LetopisError, ValidationError, fromDbError, type Issue } from './errors.js';
-export { Registry, type AggregateInfo, type ClassInfo, type EndInfo, type LeafType } from './registry.js';
+export { Registry, type ClassInfo, type EndInfo, type LeafType } from './registry.js';
 export { compileValidator, applyDefaults, type Validator } from './validate.js';
 export { syncModels, generateTypes, schemaToTs, type SyncResult } from './sync.js';
-export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, isOp } from './ops.js';
+export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, isOp } from './ops.js';
+/**
+ * Хотя бы один из фильтров: `db.Product(or({ sku: 'K-1' }, { price: lt(500) }))` — товар K-1 или дешевле 500. Ставится
+ * вместо всего фильтра шага, а не значением поля; условия внутри одного фильтра соединяются через «и». В шаге подключения
+ * с моделями (`TypedDb`) фильтры внутри — поля и роли класса шага: тип им даёт шаг (план 2.0, этап 4, п. 1). Та же
+ * фабрика, что в реестре операторов (ops.ts), — другой у неё только тип.
+ */
+export declare const or: <F extends object>(...filters: NoInfer<F>[]) => OrOp<F>;
 export { cursorOf } from './sql.js';
-export { inc, isInc, type IncMarker, type WriteRow } from './write.js';
+export { inc, isInc, type DeleteOptions, type Expected, type IncMarker, type RestoreOptions, type WriteRow } from './write.js';
 export { totpCode, hashPassword, verifyHash, type AuthApi, type LoginResult, type Credential, type SessionInfo } from './auth.js';
-export type { AclApi, AclDecision, AclDataDecision, AclOp } from './acl.js';
+export type { AclApi, AclDecision, AclDataDecision, AclOp, AclRule, AclRuleSpec, AclTarget } from './acl.js';
 export type { LoadOptions, LoadReport, LoadIssue, LoadInput } from './load.js';
-export type { Chain, ChainCore, StepFn, BatchEntry } from './chain.js';
-export type { ModelLike, AnyModelLike, RowOf, FilterOf, FieldFilterOf, TypedChain, StepsOf, PatchOf } from './typed.js';
+export type { Chain, ChainCore, ChainRef, StepFn, BatchEntry } from './chain.js';
+export type { ModelLike, AnyModelLike, RowOf, FilterOf, FieldFilterOf, TypedChain, StepsOf, PatchOf, OrOp, SystemModels } from './typed.js';
 export type { Row, Path, Filter, FieldFilter, Cursor, ChainMods, QueryEvent, Op, Scalar } from './types.js';
-export type { DiffChange, DiffResult, DiffOptions, BlameField, BlameResult, BlameOptions } from './types.js';
 export type { CacheOptions, CacheStats } from './cache.js';
 export type { SignalMode } from './signals.js';
 export type { WatchOptions, WatchEvent, Subscription } from './watch.js';
-export type { Projector, ProjectorOptions, ProjectorChange, ProjectorOut, ProjectorRow, ProjectorReport, ProjectorStatus, ProjectorFailure } from './project.js';
-export type { VerifyResult, VerifyIssue, MaintainOptions, MaintainReport, ResetOptions, ResetResult, ModelDescription } from './admin.js';
-export { describeText } from './admin.js';
-export { up, createTenant, type UpOptions, type UpResult, type HistoryPolicy, type TenantOptions, type TenantResult } from './up.js';
+export type { MaintainReport } from './admin.js';
+export { up, createTenant, type UpOptions, type UpResult, type TenantOptions, type TenantResult, type LoginOptions } from './up.js';
 export { RESERVED_CLASS_NAMES, CHAIN_METHODS, DB_METHODS } from './types.js';
-/** Снесено в 1.0.0: id v7 больше не выдаются (§2.3). */
-export declare function uuidv7(): never;
-/** Снесено в 1.0.0: пространство имён v5 — id арендатора. Любое использование значения — ошибка. */
-export declare const LETOPIS_NS: string;
-export interface ConnectOptions {
+export type { LogEvent, LogFn, LogLevel, LogObject, LogOptions, Logger } from './types.js';
+export { LOG_EVENTS, type LogEventName } from './messages/index.js';
+export interface ConnectOptions extends LogOptions {
     /** Строка подключения; либо готовый пул postgres.js в `sql`. */
     dsn?: string;
     sql?: postgres.Sql;
-    /** Схема установки, например `v2.salon`. */
+    /** Схема установки, например `v2.salon`; имя без точки (`salon`) — как у `up()`: `v2.salon`. */
     schema: string;
     /** Токен сессии; либо ключ `APIKEY` в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
     token?: string;
     apiKey?: string;
     service?: string;
-    /** Продлевать сессию раз в минуту работы (по умолчанию да, §2.9). */
+    /**
+     * Продлевать сессию раз в минуту работы (по умолчанию да, §2.9); после простоя дольше минуты — до операции: истёкшая
+     * сессия тогда даёт `no_session`, а не анонимное чтение с пустым ответом, а подключение по `apiKey` обменивает ключ
+     * заново. `false` — без продления и без этой проверки.
+     */
     refreshSession?: boolean;
     /** Разрешить роль, которая обходит RLS (суперпользователь, `BYPASSRLS`, член роли-владельца), — администраторское подключение (§2.9). */
     allowBypassRls?: boolean;
+    /**
+     * Один процесс малого приложения (план 2.0, этап 3): строка подключения администратора (или пул postgres.js). Второй
+     * пул — не больше двух соединений — открывается при первой надобности и служит только администраторским вызовам корня
+     * подключения: `load`, `maintain` и `syncModels`, с той же сессией.
+     * Цепочки и `db.sql` идут через пул приложения (`dsn`) под RLS. Роль строки — суперпользователь или роль с `SET` на
+     * роль-владельца, иначе `admin_required`. Пароль администратора в процессе приложения — только для малых приложений.
+     */
+    admin?: string | postgres.Sql;
     /** Имя роли-владельца (по умолчанию `letopis_owner`). */
     owner?: string;
-    /** Интервал отправки отложенного сигнала, мс (по умолчанию 100; решение 9 точки А). */
+    /** Интервал отправки отложенного сигнала, мс (по умолчанию 100). */
     notifyIntervalMs?: number;
     /** Размер пула, если подключение создаёт сам `connect()`. */
     max?: number;
@@ -87,7 +100,7 @@ export interface ConnectOptions {
      * Запускать `maintain()` по расписанию: интервал — число миллисекунд или строка вроде `'15m'`, `'1h'`, от 1 мс до
      * 2³¹−1 мс (около 24 суток); иначе `connect()` отказывает с `invalid_data`, не открывая соединений. Если обслуживание в
      * этот момент уже ведёт другой процесс или ещё идёт прошлый запуск, запуск пропускается. `close()` ждёт, пока идущий
-     * запуск доделает текущую пачку.
+     * запуск закончится.
      */
     maintain?: string | number;
 }
@@ -119,37 +132,10 @@ export interface DbCore {
     /** Отправить накопленные сигналы сейчас. */
     flushSignals(): Promise<void>;
     /**
-     * Проверяет целостность журнала всей установки: сходится ли хэш каждой версии с хэшем предыдущей и текущая строка
-     * объекта — с его последней версией; с `{ data: true }` проверяет ещё каждую строку. Якорь в ответе — один хэш текущих
-     * версий всех объектов: храните его вне базы, тогда заметна и подмена самых свежих версий. Нужно право `letopis.verify`
-     * (по умолчанию оно у системного администратора) или администраторское подключение.
-     */
-    verify(opts?: {
-        data?: boolean;
-    }): Promise<VerifyResult>;
-    /** Обслуживание: истёкшие сессии и коды, прореживание журнала по политике хранения, очередь сигналов. */
-    maintain(opts?: MaintainOptions): Promise<MaintainReport>;
-    /**
-     * Сбрасывает тестовую установку: сессии, данные одного арендатора или всё — смотря по `level`. Работает, только если
-     * установка поставлена с `up({ allowReset: true })`, у вызывающего есть право `letopis.reset` (или подключение
-     * администраторское), а `confirm` совпадает с именем схемы.
-     */
-    reset(opts: ResetOptions): Promise<ResetResult>;
-    /**
-     * Стирает версии, сделанные раньше момента `before`; текущая версия остаётся всегда. Вместо стёртого начала истории
-     * остаётся служебная запись `trim` со временем появления объекта.
-     */
-    trimHistory(target: string | string[] | Row | Row[], before: string | Date): Promise<number>;
-    /**
-     * Меняет ключ класса. Объекты его семейства (сам класс и потомки), у которых по новому ключу выходит другой id,
-     * переезжают на новый id, а ссылки на них переводятся.
-     */
-    rekeyClass(cls: string, key: string[]): Promise<number>;
-    /**
-     * Описание модели для программ и языковых моделей: классы арендатора сессии и общие классы System с полями, ключом,
-     * ссылками и метаданными `meta`. `describeText(db.describe())` превращает его в текст.
+     * Обслуживание: истёкшие и погашенные сессии, одноразовые коды, строки-замки удалённых классов, очередь сигналов. Нужно
+     * право `letopis.maintain` (по умолчанию оно у системного администратора) или администраторское подключение.
      */
-    describe(): ModelDescription;
+    maintain(): Promise<MaintainReport>;
     /** Подписка по курсору: `for await (const ev of db.watch({ from })) …`; `sub.cursor` — откуда продолжить. */
     watch(opts?: WatchOptions): Subscription;
     /** Кэш результатов подключения. */
@@ -158,7 +144,7 @@ export interface DbCore {
         stats(): CacheStats;
     };
     /** Начать путь с готового узла: `db.entity(row | цепочка)`. */
-    entity(x: Chain | Row): Chain;
+    entity(x: ChainRef | Row): Chain;
     /**
      * Подключение на том же пуле от имени другого аккаунта: запросы идут с его правами и в его арендаторе. Журнал
      * записывает автором версий этот аккаунт, а исполнителем (`agent`) — аккаунт сессии, например сервис. Нужно право
@@ -170,7 +156,7 @@ export interface DbCore {
         owner?: string;
         tenant?: string;
     }): Promise<Db>;
-    /** Явная транзакция `read committed`: те же цепочки, `commit()`, `rollback()`, `lock()`, `forUpdate()`; `reason` — причина изменения для всех операций блока (план 1.1). */
+    /** Явная транзакция `read committed`: те же цепочки, `commit()`, `rollback()`, `lock()`, `forUpdate()`; `reason` — причина изменения для всех операций блока. */
     begin(opts?: {
         reason?: string;
     }): Promise<DbTx>;
@@ -181,18 +167,6 @@ export interface DbCore {
      * от имени пользователя (опция `as`). Работает только на администраторском подключении, иначе `admin_required`.
      */
     load(input: LoadInput, opts?: LoadOptions): Promise<LoadReport>;
-    /**
-     * Проектор из журнала (план 1.1, §2.4): строит строки производных классов (`derivedBy: имя`) из изменений
-     * классов `from`; `run()` — догнать журнал и следовать за ним, `rebuild()` — перестроить с текущего состояния.
-     * Только на администраторском подключении (иначе `admin_required`).
-     */
-    projector(name: string, opts: ProjectorOptions): Projector;
-    /**
-     * Ремонт агрегатов в базе (план 1.1, §2.4): поля класса (с потомками) во всех арендаторах — заново из живых строк
-     * источников, под исключительными блокировками; версия — только у исправленных. Возвращает их число. Только на
-     * администраторском подключении (иначе `admin_required`).
-     */
-    rebuildAggregates(cls: string): Promise<number>;
     /**
      * Именованная очередь планов фасада: `batch.Класс(…).create(…)`; `batch.run()` — одной транзакцией. У корня,
      * у каждого `db.as()` и у каждой `db.begin()` очереди свои: план исполняется от имени фасада, который его поставил.
@@ -206,6 +180,10 @@ export interface DbCore {
     commit(tr?: DbTx): Promise<void>;
     /** Откатить транзакцию `tr` (то же, что `tr.rollback()`). */
     rollback(tr?: DbTx): Promise<void>;
+    /**
+     * Закрыть подключение: у корня — пул и подписки, в `db.begin()` — откат транзакции; у фасада `db.as()` ничего не делает
+     * (пул общий с корнем).
+     */
     close(): Promise<void>;
 }
 /** Подключение: служебные методы и классы как стартовые шаги цепочек — `db.Класс(фильтр)`. */
@@ -214,12 +192,22 @@ export type Db = DbCore & {
 };
 /** Явная транзакция `db.begin()`: тот же API; ошибка любого запроса её ломает (§2.5). */
 export type DbTx = Db;
-/** Подключение с типами шагов, строк и фильтров по моделям: `connect({ models })`. */
-export type TypedDb<M extends readonly AnyModelLike[]> = DbCore & StepsOf<M> & {
-    [className: string]: StepFn;
-};
+/**
+ * Подключение со строгими типами по моделям: `connect({ models })` или `connect<Models>()` с объявлениями
+ * `letopis types`. Шаг — только известный класс или алиас (модели и системные классы), переходы — по концам, слоты — роли
+ * класса; имена, известные только во время выполнения, — `loose(db)` (план 2.0, этап 4, п. 1). Модели без литеральных
+ * имён (`AnyModel[]` вместо списка `as const`) строгим типам не помогут — тогда это `Db`.
+ */
+export type TypedDb<M extends readonly AnyModelLike[]> = string extends M[number]['name'] ? Db : DbCore & StepsOf<M>;
 export type { Batch };
+/**
+ * То же подключение без строгих типов: шагом может быть любое имя, в том числе известное только во время выполнения, —
+ * `loose(db)[имя]()`. Объект тот же: проверки во время выполнения (неизвестное имя или поле, переход, слот) не меняются.
+ */
+export declare function loose(db: DbCore): Db;
 export declare function connect<const M extends readonly AnyModelLike[]>(opts: ConnectOptions & {
     models: M;
 }): Promise<TypedDb<M>>;
 export declare function connect(opts: ConnectOptions): Promise<Db>;
+/** Строгие типы без моделей Zod — из объявлений `letopis types`: `connect<Models>({ … })`. */
+export declare function connect<M extends readonly AnyModelLike[]>(opts: ConnectOptions): Promise<TypedDb<M>>;