letopis 1.4.2 → 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 { BlameOptions, BlameResult, ChainMods, Cursor, DiffOptions, DiffResult, 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 {
@@ -70,16 +76,10 @@ export interface ChainCore {
         paths?: boolean;
     }): Promise<number>;
     /**
-     * Все версии сущностей последнего шага (надгробия — $deleted), по id и номеру версии;
-     * { follow: true } — и через смену id при reclass и rekey, по времени.
+     * Все версии сущностей последнего шага (надгробия — $deleted), по id и номеру версии. Шаг с явными id находит и
+     * удалённые объекты: `db.Класс(id).versions()` отдаёт историю удалённого.
      */
-    versions(opts?: {
-        follow?: boolean;
-    }): Promise<Row[]>;
-    /** Что изменилось между двумя версиями или моментами (по умолчанию — предыдущая версия → последняя), план 1.1. */
-    diff(opts?: DiffOptions): Promise<DiffResult[]>;
-    /** Кто, когда и почему последним изменил каждое поле версии (по умолчанию текущей), план 1.1. */
-    blame(opts?: BlameOptions): Promise<BlameResult[]>;
+    versions(): Promise<Row[]>;
     /**
      * Сумма поля `'data.<путь>'` по объектам последнего шага: значения приводятся к числу, складывает база. `limit()` и
      * `offset()` на итог не влияют; нет ни одного значения — `null`.
@@ -123,12 +123,13 @@ export interface ChainCore {
      * Постраничный вывод по курсору: ответ начинается строго после строки, на которой кончилась прошлая страница, в
      * порядке `sort()` (без `sort()` — ошибка `invalid_query`). Курсор этой строки даёт `cursorOf(строка, поле)` с тем же
      * полем, что в `sort()`. Листает `rows()`, `ids()`, `versions()` и `paths()` (курсор пути — `cursorOf(путь, поле)`);
-     * `count()`, агрегаты, `diff()` и `blame()` курсор не учитывают.
+     * перед `count()` и агрегатами (`sum`, `avg`, `min`, `max`, `countBy`) — `invalid_query`: они считают по всем объектам.
      */
     after(cursor: Cursor): Chain;
     /**
-     * Последний шаг находит и удалённые объекты. Удалённый объект приходит надгробием — своей последней версией, версией
-     * удаления, — с `$deleted: true`.
+     * Шаг, после которого стоит, находит и удалённые объекты — модификатор своего шага, как `exact()`:
+     * `db.Member(id).withDeleted().Loan().withDeleted()` — удалённые выдачи удалённого участника. Удалённый объект приходит
+     * надгробием — своей последней версией, версией удаления, — с `$deleted: true`.
      */
     withDeleted(): Chain;
     /** Дети любой глубины на переходе к тому же классу; $depth в строке. */
@@ -161,14 +162,19 @@ export interface ChainCore {
      * же цепочка (та же переменная) второй раз в одном пути шагов не добавляет, а возвращает к своему последнему шагу:
      * следующий шаг пойдёт от него.
      */
-    entity(x: Chain | Row): Chain;
+    entity(x: ChainRef | Row): Chain;
     /** Создать объект: концы — из пути и слотов; занятый ключ — ошибка exists с id. */
     create(data?: Record<string, unknown>, opts?: {
         reason?: string;
     }): Chain;
-    /** Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — с проверкой версии. */
+    /**
+     * Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — с проверкой версии. Цели сужают
+     * фильтр, id, `tags()`, `owner()` или `limit()` хотя бы у одного шага, иначе `invalid_query`; правка всех строк —
+     * `{ all: true }`.
+     */
     update(patch?: Record<string, unknown>, opts?: {
         rev?: number;
+        all?: boolean;
         reason?: string;
     }): Chain;
     /** Создать или заменить целиком (класс с ключом); строка ответа несёт $upsert. */
@@ -178,42 +184,27 @@ export interface ChainCore {
     /**
      * Удаляет цели шага; строки, которые на них ссылаются, база удаляет вместе с ними, отвязывает или не даёт удалить цель —
      * как задано в `onDelete` их ссылок. Без `{ confirm: true }` — предпросмотр удаления: ничего не удаляется, терминал
-     * вернёт все строки, которых оно коснулось бы, у каждой `$action` — что с ней будет.
-     */
-    delete(opts?: {
-        confirm?: boolean;
-        reason?: string;
-    }): Chain;
-    /** Затереть строковые поля ('[erased]') и пометить тегом anonymized. */
-    anonymize(fields: string[], opts?: {
-        reason?: string;
-    }): Chain;
-    /** Сменить класс: у класса с ключом — новый id и перевод ссылок. */
-    reclass(cls: string, data?: Record<string, unknown>, opts?: {
-        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;
-    /**
-     * Стирает историю удалённых объектов шага: все их версии в журнале, от каждого остаётся одна запись `purge`. Удалённые
-     * объекты шаг находит сам, без `withDeleted()`. Без `{ confirm: true }` — предпросмотр: ничего не стирается, терминал
-     * вернёт надгробия с `$versions` — сколько версий сотрётся.
-     */
-    purge(opts?: {
-        confirm?: boolean;
-        reason?: string;
-    }): Chain;
     /**
-     * Новое значение ключа объектов шага. id вычисляется из ключа, поэтому объект получает новый id: ссылки других строк
-     * на него переводятся на новый id, а журнал связывает старый id с новым.
+     * Восстановить удалённые объекты шага: последний снимок новой версией (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 }`.
      */
-    rekey(patch: Record<string, unknown>, opts?: {
-        reason?: string;
-    }): Chain;
+    restore(opts: RestoreOptions): Chain;
     /** Кэш результатов (§2.12): ответ хранится в памяти процесса ttl секунд (по умолчанию 60). */
     cache(opts?: {
         ttl?: number;
@@ -234,6 +225,8 @@ export type StepFn = ((filter?: Filter) => Chain) & {
 export type Chain = ChainCore & {
     [className: string]: StepFn;
 };
+/** Любая цепочка — с типами по моделям (`TypedChain`) или без них (`Chain`): аргумент `entity()` и значение слота. */
+export type ChainRef = Pick<ChainCore, 'ids'>;
 /** Внутренний канал: план чужой ленивой цепочки (entity()). */
 export declare const PLAN: unique symbol;
 /** entity-идентичность: переменная-цепочка → nodeKey её узла в этом пути. */
@@ -243,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() исполняет очередь
@@ -253,5 +251,5 @@ export declare function makeBatch(ctx: ChainCtx, queue: BatchEntry[]): Batch;
 /** Старт пути от корня db: класс, алиас или роль. */
 export declare function startStep(ctx: ChainCtx, name: string): StepFn;
 /** Старт пути с готового узла: db.entity(row | цепочка). */
-export declare function startEntity(ctx: ChainCtx, x: Chain | Row): Chain;
+export declare function startEntity(ctx: ChainCtx, x: ChainRef | Row): Chain;
 export {};