letopis 0.5.0 → 0.16.0

package/dist/chain.d.ts

@@ -1,19 +1,23 @@
 /**
- * Dot-цепочки: db.Сотрудник({name:'Вася'}).навык().Услуга().execute()
+ * Dot-цепочки: db.Сотрудник({name:'Вася'}).навык().Услуга().run()
  * db и цепочка — Proxy над реестром классов (id и alias работают одинаково).
  *
  * Выборка настраивается модификаторами: .limit(n) .offset(n) .sort(field, dir?)
  * Колонки — модификаторами: .tags(…) .account(…) .owner(…); ключ путей — .alias(…).
- * Запись: .set(data) — связи задаются контекст-шагами цепочки; .delete().
+ * Запись: .create(data) / .update(data) / .delete({confirm}) / .anonymize(fields) — ЗВЕНЬЯ
+ * (возвращают цепочку, продолжение — от результата); исполняет ТЕРМИНАЛ, весь план
+ * одной транзакцией.
  */
 import type { Row, Path, Filter } from './types.js';
 import { type Ctx } from './sql.js';
-import { type BatchOp } from './write.js';
+import { type BatchPlan } from './write.js';
 import { type Tables } from './tables.js';
+import { type AuthApi } from './auth.js';
+import { type AclApi } from './acl.js';
 import type { Registry } from './schema.js';
 export interface ChainCore {
-    /** Пути: [{шаг1: Row, шаг2: Row, …}, …] — все узлы каждого варианта. */
-    execute(): Promise<Path[]>;
+    /** Пути: [{шаг1: Row, шаг2: Row, …}, …] — все узлы каждого варианта (бывший execute). */
+    run(): Promise<Path[]>;
     /** Уникальные сущности последнего шага. */
     rows(): Promise<Row[]>;
     first(): Promise<Row | null>;
@@ -39,53 +43,88 @@ export interface ChainCore {
     min(field: string): Promise<unknown>;
     max(field: string): Promise<unknown>;
     countBy(field: string): Promise<Record<string, number>>;
-    /** GDPR: новая версия с затёртыми string-полями ('[erased]') + тег 'anonymized'. История остаётся (см. README). */
-    anonymize(fields: string[]): Promise<Row[]>;
+    /**
+     * GDPR-звено: новая версия с затёртыми string-полями ('[erased]') + тег 'anonymized'.
+     * История остаётся. Возвращает цепочку — исполняет терминал; продолжение — от затёртых версий.
+     */
+    anonymize(fields: string[]): Chain;
     /** Переименовать ключ ТЕКУЩЕГО шага в выводе путей. */
     alias(name: string): Chain;
-    /** Колонка tags: строка | string[] (все) | has/hasAny/hasAll. В set() — значение тегов. */
+    /** Колонка tags: строка | string[] (все) | has/hasAny/hasAll. В записи — значение тегов. */
     tags(v: string | string[] | object): Chain;
-    /** Колонка account (uuid или Row/Account). В set()-insert — значение. */
+    /** Колонка account (uuid или Row/Account). В create() — значение. */
     account(v: string | {
         id: string;
     }): Chain;
-    /** Колонка owner (uuid или Row/Account). В set()-insert — значение. */
+    /** Колонка owner (uuid или Row/Account). В create() — значение. */
     owner(v: string | {
         id: string;
     }): Chain;
     /**
-     * Записать. Связи — контекст-шагами до set() И/ИЛИ класс-вызовами после:
-     *   await db.Сотрудник(s).занятость(id).set({kind}).Окно(w)
-     *   const z = db.занятость(id).set({kind}); z.Сотрудник(s); z.Окно(w); await z
-     * Исполняется ОДНИМ INSERT при первом await (промис кешируется).
-     * Пустой фильтр без data.id → INSERT; id (фильтр или data.id) → UPSERT;
-     * фильтр-объект → версия каждого найденного.
+     * Вставить узел в путь: x — ленивая цепочка-паттерн (стык проверяется правилами
+     * переходов) либо Row (шаг его класса по id). ТА ЖЕ переменная-цепочка повторно
+     * в одном пути — возврат к её узлу (ветвление); разные переменные — разные узлы.
+     */
+    entity(x: Chain | Row): Chain;
+    /**
+     * Создать сущность (ЗВЕНО — вернёт цепочку, исполняет терминал):
+     *   await db.Организация(org).Сотрудник().create({ name: 'Вася' }).rows()
+     * Связи — контекст-шагами до create() + слотами .Класс.set(…) после. id — по Schema
+     * (attributes.id: v4 | v7 | v5-вычисляемый); известный id (Класс(id) / data.id / v5)
+     * уже существует → новая версия (идемпотентно). Фильтр-объект — ошибка: это update().
      */
-    set(data?: Record<string, unknown>): SetChain;
-    /** Серверный tombstone + каскад; возвращает всё удалённое с $deleted: true. */
-    delete(): Promise<Row[]>;
+    create(data?: Record<string, unknown>): Chain;
+    /**
+     * Новая версия КАЖДОГО найденного путём (deep-merge листьев data):
+     *   await db.Запись(з).позиция({ qty: 1 }).update({ qty: 2 }).rows()
+     * Класс() ≡ Класс({}) — все в границах контекста. Не найдено → [] (НИКОГДА не создаёт).
+     * Продолжение цепочки — от записанных строк (fan-out при множестве).
+     */
+    update(data?: Record<string, unknown>): Chain;
+    /**
+     * Удаление-звено. { confirm: true } — серверный tombstone + каскад (продолжение — от
+     * затомбстоуненных, $deleted: true); БЕЗ confirm — превью: терминал вернёт кандидатов
+     * (цели + каскад), БД не тронута.
+     */
+    delete(opts?: {
+        confirm?: boolean;
+    }): Chain;
 }
-/** Ленивый билдер записи: довешивание связей + thenable (исполнение при await). */
-export type SetChain = PromiseLike<Row[]> & {
-    [className: string]: (target: string | {
+/**
+ * Свойство-класс на цепочке:
+ *   ВЫЗОВ  `Класс(фильтр?)` — шаг-навигация; повтор LINK-класса в пути = возврат
+ *          к его узлу (pivot: ветвление к другому концу, дофильтровка AND);
+ *   СЛОТ   `Класс` без скобок — конец links записываемой версии:
+ *     .set(target) — установить конец (id | Row | вложенная цепочка: та же транзакция,
+ *                    ровно одна сущность класса конца); союз-конец замещается целиком;
+ *     .unset()     — снять optional-конец.
+ * Слот валиден только для конца из Schema.links владельца и ТОЛЬКО после операции
+ * записи: …create(…).Класс.set(x) / …update(…).Класс.unset() — та же версия строки.
+ */
+export type StepProp = ((filter?: Filter) => Chain) & {
+    set(target: string | {
         id: string;
-    }) => SetChain;
+    } | Chain): Chain;
+    unset(): Chain;
 };
 export type Chain = ChainCore & {
-    [className: string]: (filter?: Filter) => Chain;
+    [className: string]: StepProp;
 };
 export interface DbCore {
     /** Открыть транзакцию: tr — тот же API + commit/rollback/lock. */
     begin(): Promise<EntityTx>;
     commit(tr: EntityTx): Promise<void>;
     rollback(tr: EntityTx): Promise<void>;
-    /** Именованный батч: те же цепочки, set/delete копятся до execute(). */
+    /** Именованный батч: те же цепочки, планы записи копятся до run(). */
     batch(name: string): Batch;
     /**
      * Realtime: события каждой вставленной версии (insert/update/delete-tombstone).
      * watch(cb) — все классы; watch('Запись', cb) — один. Возврат — stop-функция.
+     * LISTEN-соединение переживает обрывы (re-listen автоматом), но NOTIFY за время
+     * разрыва потеряны — opts.onReconnect зовётся после восстановления: дочитайте пропущенное.
      */
-    watch(classOrCb: string | ((e: WatchEvent) => void), cb?: (e: WatchEvent) => void): Promise<() => void>;
+    watch(cb: (e: WatchEvent) => void, opts?: WatchOpts): Promise<() => void>;
+    watch(cls: string, cb: (e: WatchEvent) => void, opts?: WatchOpts): Promise<() => void>;
     close(): Promise<void>;
     registry: Registry;
     /** Голый postgres-клиент (тесты, EXPLAIN). */
@@ -95,6 +134,12 @@ export interface DbCore {
     credentials: Tables['credentials'];
     resources: Tables['resources'];
     rules: Tables['rules'];
+    /** Вход по кредам (пароль/api-key/key-secret/внешние identity) + сессии в Redis. */
+    auth: AuthApi;
+    /** ACL по Resource/Rule: check(эндпоинт) / checkData(класс, READ|WRITE|DELETE) / reload. */
+    acl: AclApi;
+    /** Начать путь с готового узла/паттерна: db.entity(pos).… (pos — ленивая цепочка или Row). */
+    entity(x: Chain | Row): Chain;
 }
 export type EntityDb = DbCore & {
     [className: string]: (filter?: Filter) => Chain;
@@ -112,15 +157,23 @@ export interface WatchEvent {
     updated: string;
     deleted: boolean;
 }
+/** Опции watch(): реакция на восстановление LISTEN-соединения. */
+export interface WatchOpts {
+    /** Зовётся после каждого re-listen (не на первом подключении): NOTIFY за разрыв потеряны. */
+    onReconnect?: () => void;
+}
 export type Batch = {
-    execute(): Promise<Row[][]>;
+    /** Исполнить всю очередь планов одной транзакцией (бывший execute). */
+    run(): Promise<Row[][]>;
     discard(): void;
     size(): number;
 } & {
     [className: string]: (filter?: Filter) => Chain;
 };
 interface RootState {
-    batches: Map<string, BatchOp[]>;
+    batches: Map<string, BatchPlan[]>;
 }
+/** Внутренний канал: план чужой ленивой цепочки (слот-значения, entity()). */
+export declare const PLAN: unique symbol;
 export declare function makeDb(ctx: Ctx, root?: RootState): EntityDb;
 export {};