letopis 2.0.0 → 3.0.0

package/dist/chain.d.ts

@@ -2,7 +2,9 @@ import { type ResultCache } from './cache.js';
 import type { ClassInfo, Registry } from './registry.js';
 import { type Step } from './sql.js';
 import type { Executor } from './tx.js';
-import type { ChainMods, Cursor, Filter, Path, QueryEvent, Row } from './types.js';
+import { type ChainMods, type Cursor, type Filter, type Path, type QueryEvent, type Row } from './types.js';
+import { type Log } from './log.js';
+import { type DeleteOptions, type RestoreOptions } from './write.js';
 export interface ChainCtx {
     readonly reg: Registry;
     readonly schema: string;
@@ -10,6 +12,8 @@ export interface ChainCtx {
     readonly exec: Executor;
     /** Арендатор сессии. */
     readonly tenant: () => string | null;
+    /** Фасад входит по токену сессии (connect({ token }), ключ API): без арендатора сессии шаг — sessionless(). */
+    readonly hasToken?: () => boolean;
     /** Владелец новых строк по умолчанию (db.as(…, { owner })). */
     readonly owner?: string;
     readonly onQuery?: (e: QueryEvent) => void;
@@ -28,6 +32,8 @@ export interface ChainCtx {
             tenant?: string | null;
         };
     };
+    /** Логгер фасада (lib/src/log.ts): события read, write, delete, restore, кэша и error. */
+    readonly log?: Log;
 }
 /** План в очереди батча; steps обновляется по мере роста цепочки. */
 export interface BatchEntry {
@@ -69,7 +75,10 @@ export interface ChainCore {
     count(opts?: {
         paths?: boolean;
     }): Promise<number>;
-    /** Все версии сущностей последнего шага (надгробия — $deleted), по id и номеру версии. */
+    /**
+     * Все версии сущностей последнего шага (надгробия — $deleted), по id и номеру версии. Шаг с явными id находит и
+     * удалённые объекты: `db.Класс(id).versions()` отдаёт историю удалённого.
+     */
     versions(): Promise<Row[]>;
     /**
      * Сумма поля `'data.<путь>'` по объектам последнего шага: значения приводятся к числу, складывает база. `limit()` и
@@ -118,8 +127,9 @@ export interface ChainCore {
      */
     after(cursor: Cursor): Chain;
     /**
-     * Последний шаг находит и удалённые объекты. Удалённый объект приходит надгробием — своей последней версией, версией
-     * удаления, — с `$deleted: true`.
+     * Шаг, после которого стоит, находит и удалённые объекты — модификатор своего шага, как `exact()`:
+     * `db.Member(id).withDeleted().Loan().withDeleted()` — удалённые выдачи удалённого участника. Удалённый объект приходит
+     * надгробием — своей последней версией, версией удаления, — с `$deleted: true`.
      */
     withDeleted(): Chain;
     /** Дети любой глубины на переходе к тому же классу; $depth в строке. */
@@ -174,21 +184,27 @@ export interface ChainCore {
     /**
      * Удаляет цели шага; строки, которые на них ссылаются, база удаляет вместе с ними, отвязывает или не даёт удалить цель —
      * как задано в `onDelete` их ссылок. Без `{ confirm: true }` — предпросмотр удаления: ничего не удаляется, терминал
-     * вернёт все строки, которых оно коснулось бы, у каждой `$action` — что с ней будет. С `{ confirm: true }` цели сужают
-     * фильтр, id, `tags()`, `owner()` или `limit()` хотя бы у одного шага, иначе `invalid_query`; удаление всех строк —
-     * `{ confirm: true, all: true }`.
-     */
-    delete(opts?: {
-        confirm?: boolean;
-        all?: boolean;
-        reason?: string;
-    }): Chain;
+     * вернёт все строки, которых оно коснулось бы, у каждой `$action` — что с ней будет. `{ confirm: true, expect: превью }`
+     * удаляет ровно показанное: в транзакции удаления превью строится заново и сравнивается с `expect` по `id`, `rev` и
+     * `$action`; расхождение — `conflict` (ничего не удалено, новое превью — `err.detail.preview`); цели сужают фильтр, id,
+     * `tags()`, `owner()` или `limit()` хотя бы у одного шага, иначе `invalid_query`. `{ confirm: true }` без `expect` —
+     * `invalid_query` (`write.confirm_without_expect`); осознанно удалить текущий состав целей без сверки (и без фильтра —
+     * все строки) — `{ confirm: true, all: true }`.
+     */
+    delete(opts?: DeleteOptions): Chain;
     /** Чтение с блокировкой строк последнего шага до конца db.begin() (rows, first, ids). */
     forUpdate(): Chain;
-    /** Восстановить удалённые объекты шага: последний снимок новой версией (id прежний). */
-    restore(opts?: {
-        reason?: string;
-    }): Chain;
+    /**
+     * Восстановить удалённые объекты шага: последний снимок новой версией (id прежний). `{ expect }` — надгробия `{ id, rev }`
+     * из ответа `delete()` или `withDeleted()`: восстанавливаются только цели из `expect`, и только если последняя версия
+     * каждой — та же; иначе ничего не восстановлено: уже восстановлена — `not_deleted` (`write.restore_already`), id занял
+     * новый объект — `not_deleted` (`write.restore_id_taken`), прочее (удалена снова, менялась) — `conflict`
+     * (`write.restore_stale`); причины по целям — `err.detail.stale`. `{ expect, partial: true }` — восстановить то, что
+     * можно: остальные цели приходят строками `{ …строка, $action: 'skip', $why }`. Без `expect` — `invalid_query`
+     * (`write.restore_without_expect`), и для явных id; осознанно вернуть все удалённые цели шага без сверки —
+     * `{ all: true }`.
+     */
+    restore(opts: RestoreOptions): Chain;
     /** Кэш результатов (§2.12): ответ хранится в памяти процесса ttl секунд (по умолчанию 60). */
     cache(opts?: {
         ttl?: number;
@@ -220,6 +236,11 @@ export declare function lookupStep(reg: Registry, name: string): {
     cls: ClassInfo;
     role?: string;
 } | undefined;
+/**
+ * Цепочка в читаемом виде: `Shop({"name":"A"}).Product.limit(10).rows()`. Фильтры — значениями (поля-секреты — '***'),
+ * данные записи — только именами полей.
+ */
+export declare function chainText(log: Log, steps: readonly Step[], mods?: ChainMods, term?: string, args?: readonly unknown[]): string;
 export declare function makeChain(ctx: ChainCtx, steps: Step[], mods: ChainMods, nodes?: NodeMap): Chain;
 /**
  * Батч: очередь планов; каждый вызов класса — своя ссылка на очередь (свой план). run() исполняет очередь