letopis 0.21.0 → 1.0.0

package/dist/cache.js

@@ -0,0 +1,148 @@
+/**
+ * Кэш результатов (план, §2.12, этап 6, п. 13): строки ответа цепочки — в памяти процесса, только по
+ * явной пометке: `.cache()` / `.cache({ ttl })` или `cache: { ttl }` у всех классов чтения в модели.
+ *
+ * Ключ — текст запроса, параметры и тот, кто спрашивает (токен, актор, арендатор): под RLS один
+ * запрос разным пользователям отдаёт разные строки. Сброс:
+ *   - свои записи — сразу после фиксации, по классам из letopis.changed (туда попадают и классы
+ *     каскада, unset, смены класса и ключа); запись через db.sql — весь кэш;
+ *   - чужие записи — по сигналу базы с именем класса; классы прав и схемы (rule, Resource, member,
+ *     Account, Class) и «*» — весь кэш; `session:<16 hex>` — ответы погашенной сессии, `session:*` — все;
+ *   - гонка запроса и сигнала: счётчики сигналов по классам и сессиям снимаются до запроса, ответ
+ *     кладётся, только если они не изменились;
+ *   - (пере)подключение слушателя сигналов — весь кэш: сигналы за время обрыва потеряны; без слушателя
+ *     кэш выключен (с ttlOnly — работает только по сроку);
+ *   - срок (по умолчанию 60 с) — предохранитель; ответы истёкшей сессии не используются.
+ * Внутри db.begin() и в db.sql кэш не работает.
+ */
+import { createHash } from 'node:crypto';
+/** Классы, строки которых меняют права и схему: их сигнал сбрасывает весь кэш. */
+export const ACL_CLASSES = new Set(['rule', 'Resource', 'member', 'Account', 'Class']);
+/** Начало sha256 токена — так база называет сессию в сигнале session:<16 hex>. */
+export const sessionTag = (token) => token ? createHash('sha256').update(token, 'utf8').digest('hex').slice(0, 16) : '';
+export class ResultCache {
+    map = new Map();
+    classEpoch = new Map();
+    sessionEpoch = new Map();
+    epoch = 0;
+    listening = false;
+    st = { hits: 0, misses: 0, stores: 0, raced: 0, signals: 0, listens: 0 };
+    ttlMs;
+    ttlOnly;
+    max;
+    constructor(opts = {}) {
+        this.ttlMs = (opts.ttl ?? 60) * 1000;
+        this.ttlOnly = opts.ttlOnly === true;
+        this.max = opts.max ?? 10_000;
+    }
+    /** Кэш работает: слушатель на месте или режим только по сроку. */
+    get enabled() {
+        return this.listening || this.ttlOnly;
+    }
+    /** Ключ ответа: запрос, параметры и тот, кто спрашивает. */
+    key(text, params, who) {
+        return JSON.stringify([text, params, who.token ?? '', who.account ?? '', who.tenant ?? '']);
+    }
+    /** Снимок счётчиков классов и сессии — до запроса. */
+    token(classes, session) {
+        return {
+            epoch: this.epoch,
+            classes: classes.map((c) => [c, this.classEpoch.get(c) ?? 0]),
+            session: this.sessionEpoch.get(session) ?? 0,
+        };
+    }
+    get(key) {
+        if (!this.enabled)
+            return undefined;
+        const e = this.map.get(key);
+        const now = Date.now();
+        if (!e || e.expires <= now || (e.sessionExpires !== null && e.sessionExpires <= now)) {
+            if (e)
+                this.map.delete(key);
+            this.st.misses++;
+            return undefined;
+        }
+        this.st.hits++;
+        return e.value;
+    }
+    /** Положить ответ, если с момента снимка не было сигналов о его классах и сессии. */
+    set(key, value, classes, session, tok, ttlMs, sessionExpires) {
+        if (!this.enabled)
+            return false;
+        const stale = tok.epoch !== this.epoch
+            || tok.session !== (this.sessionEpoch.get(session) ?? 0)
+            || tok.classes.some(([c, n]) => (this.classEpoch.get(c) ?? 0) !== n);
+        if (stale) {
+            this.st.raced++;
+            return false;
+        }
+        if (this.map.size >= this.max)
+            this.map.delete(this.map.keys().next().value);
+        this.map.set(key, { value, classes: [...classes], session, expires: Date.now() + ttlMs, sessionExpires });
+        this.st.stores++;
+        return true;
+    }
+    /** Сбросить ответы, читавшие эти классы. */
+    invalidate(classes) {
+        const set = new Set(classes);
+        if (!set.size)
+            return;
+        for (const c of set)
+            this.classEpoch.set(c, (this.classEpoch.get(c) ?? 0) + 1);
+        for (const [k, e] of this.map)
+            if (e.classes.some((c) => set.has(c)))
+                this.map.delete(k);
+    }
+    /** Сбросить ответы сессии (тег — начало sha256 токена). */
+    invalidateSession(tag) {
+        this.sessionEpoch.set(tag, (this.sessionEpoch.get(tag) ?? 0) + 1);
+        for (const [k, e] of this.map)
+            if (e.session === tag)
+                this.map.delete(k);
+    }
+    /** Весь кэш. */
+    clear() {
+        this.epoch++;
+        this.map.clear();
+    }
+    /**
+     * Имена из сигнала или из letopis.changed своей транзакции: классы, `*`, `session:<тег>`,
+     * `session:*`. raw — запись через db.sql: весь кэш.
+     */
+    changed(names, raw = false) {
+        const classes = [];
+        let any = false;
+        for (const n of names) {
+            if (!n)
+                continue;
+            any = true;
+            if (n === '*' || n === 'session:*' || ACL_CLASSES.has(n)) {
+                this.clear();
+                return;
+            }
+            if (n.startsWith('session:'))
+                this.invalidateSession(n.slice(8));
+            else
+                classes.push(n);
+        }
+        if (raw && any) {
+            this.clear();
+            return;
+        }
+        this.invalidate(classes);
+    }
+    /** Сигнал от базы. */
+    signal(name) {
+        this.st.signals++;
+        this.changed([name]);
+    }
+    /** Слушатель (пере)подключился: сигналы за время обрыва потеряны — весь кэш. */
+    listen() {
+        this.st.listens++;
+        this.listening = true;
+        this.clear();
+    }
+    stats() {
+        return { size: this.map.size, ...this.st, enabled: this.enabled };
+    }
+}

package/dist/chain.d.ts

@@ -1,225 +1,158 @@
-/**
- * Dot-цепочки: db.Сотрудник({name:'Вася'}).навык().Услуга().run()
- * db и цепочка — Proxy над реестром классов (id и alias работают одинаково).
- *
- * Выборка настраивается модификаторами: .limit(n) .offset(n) .sort(field, dir?)
- * Колонки — модификаторами: .tags(…) .account(…) .owner(…); ключ путей — .alias(…).
- * Запись: .create(data) / .update(data) / .delete({confirm}) / .anonymize(fields) — ЗВЕНЬЯ
- * (возвращают цепочку, продолжение — от результата); исполняет ТЕРМИНАЛ, весь план
- * одной транзакцией.
- */
-import type { Row, Path, Filter } from './types.js';
-import { type Ctx } from './sql.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';
+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';
+export interface ChainCtx {
+    readonly reg: Registry;
+    readonly schema: string;
+    /** Где исполнять: отдельной транзакцией из пула или в явной транзакции db.begin(). */
+    readonly exec: Executor;
+    /** Арендатор сессии. */
+    readonly tenant: () => string | null;
+    /** Владелец новых строк по умолчанию (db.as(…, { owner })). */
+    readonly owner?: string;
+    readonly onQuery?: (e: QueryEvent) => void;
+    readonly slowMs?: number;
+    /** Цепочка из батча: план копится в очереди до batch.run(). */
+    readonly batch?: BatchRef;
+    /** Кэш результатов подключения и тот, кто спрашивает (ключ ответа, §2.12). */
+    readonly cache?: {
+        store: ResultCache;
+        who(): {
+            token: string | null;
+            account?: string;
+            tenant?: string | null;
+        };
+    };
+}
+/** План в очереди батча; steps обновляется по мере роста цепочки. */
+export interface BatchEntry {
+    steps: Step[];
+}
+/** Ссылка цепочки на очередь: первый глагол регистрирует план, следующие — обновляют. */
+export interface BatchRef {
+    queue: BatchEntry[];
+    entry?: BatchEntry;
+}
+/** Батч db.batch(имя): классы копят планы; run() исполняет очередь одной транзакцией. */
+export type Batch = {
+    run(): Promise<Row[][]>;
+    discard(): void;
+    size(): number;
+} & {
+    [className: string]: StepFn;
+};
 export interface ChainCore {
-    /** Пути: [{шаг1: Row, шаг2: Row, …}, …] — все узлы каждого варианта (бывший execute). */
-    run(): Promise<Path[]>;
+    /** Пути: [{ шаг1: Row, шаг2: Row, … }] — узлы каждого варианта. */
+    paths(): Promise<Path[]>;
     /** Уникальные сущности последнего шага. */
     rows(): Promise<Row[]>;
     first(): Promise<Row | null>;
     ids(): Promise<string[]>;
-    count(): Promise<number>;
-    /** Максимум строк/путей. */
-    limit(n: number): Chain;
-    /** Пропустить N. */
-    offset(n: number): Chain;
-    /** Сортировка по полю последнего шага: 'updated' | 'data.<поле>' (каст по типу из Schema). */
-    sort(field: string, dir?: 'asc' | 'desc' | boolean): Chain;
-    /** Чтение «как было на момент T» (ISO-строка или Date): версии позже T невидимы. */
-    asOf(t: string | Date): Chain;
-    /** Keyset-пагинация: строго после курсора (см. cursorOf). Требует .sort(). */
-    after(cursor: import('./types.js').Cursor): Chain;
-    /**
-     * Включить в выдачу последнего шага удалённые (tombstone). Снимает ТОЛЬКО фильтр deleted —
-     * изоляция арендатора (enforceAccount) и ACL (enforceAcl) остаются в силе.
-     */
-    withDeleted(): Chain;
-    /** ВСЕ версии сущностей последнего шага (включая tombstone → $deleted), по возрастанию updated. */
-    versions(): Promise<Row[]>;
-    /** Рекурсивный self-обход: дети любой глубины (тот же класс), $depth в Row. */
-    deep(max?: number): Chain;
+    /** Число сущностей последнего шага; { paths: true } — число путей. */
+    count(opts?: {
+        paths?: boolean;
+    }): Promise<number>;
     /**
-     * Только ЭТОТ класс, без классов-потомков. По умолчанию шаг полиморфен: родитель отдаёт
-     * объединение с потомками (`db.Контрагент()` → Мастера + Клиенты). `.exact()` нужен, когда
-     * наследование в домене — переиспользование attributes, а не «is-a» для выборки:
-     * в демо `запись` наследует `окно`, но смена ≠ бронь, поэтому «смены мастера» —
-     * `db.Мастер(id).окно().exact()`.
+     * Все версии сущностей последнего шага (надгробия — $deleted), по id и номеру версии;
+     * { follow: true } — и через смену id при reclass и rekey, по времени.
      */
-    exact(): Chain;
-    /** Агрегации по полю последнего шага ('data.<путь>'), считает БД. */
+    versions(opts?: {
+        follow?: boolean;
+    }): Promise<Row[]>;
+    /** Агрегаты по полю последнего шага ('data.<путь>') — по сущностям, считает база. */
     sum(field: string): Promise<number | null>;
     avg(field: string): Promise<number | null>;
     min(field: string): Promise<unknown>;
     max(field: string): Promise<unknown>;
     countBy(field: string): Promise<Record<string, number>>;
-    /**
-     * GDPR-звено: новая версия с затёртыми string-полями ('[erased]') + тег 'anonymized'.
-     * История остаётся. Возвращает цепочку — исполняет терминал; продолжение — от затёртых версий.
-     */
-    anonymize(fields: string[]): Chain;
-    /** Переименовать ключ ТЕКУЩЕГО шага в выводе путей. */
+    limit(n: number): Chain;
+    offset(n: number): Chain;
+    /** Сортировка по полю последнего шага: 'at' | 'rev' | 'id' | 'data.<путь>'. */
+    sort(field: string, dir?: 'asc' | 'desc' | boolean): Chain;
+    /** Срез «как было на момент T»: версии журнала. */
+    asOf(t: string | Date): Chain;
+    /** Keyset-пагинация: строго после курсора (cursorOf). Требует sort(). */
+    after(cursor: Cursor): Chain;
+    /** Последний шаг включает удалённые (надгробия, $deleted). */
+    withDeleted(): Chain;
+    /** Дети любой глубины на переходе к тому же классу; $depth в строке. */
+    deep(max?: number): Chain;
+    /** Только сам класс шага, без потомков. */
+    exact(): Chain;
+    /** Ключ текущего шага в путях. */
     alias(name: string): Chain;
-    /** Колонка tags: строка | string[] (все) | has/hasAny/hasAll. В записи — значение тегов. */
+    /** Колонка tags: строка | список (все) | has / hasAny / hasAll. */
     tags(v: string | string[] | object): Chain;
-    /** Колонка account (uuid или Row/Account). В create() — значение. */
-    account(v: string | {
-        id: string;
-    }): Chain;
-    /** Колонка owner (uuid или Row/Account). В create() — значение. */
+    /** Колонка owner. */
     owner(v: string | {
         id: string;
     }): Chain;
-    /**
-     * Вставить узел в путь: 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().
-     */
+    /** Создать объект: концы — из пути и слотов; занятый ключ — ошибка exists с id. */
     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 — превью: терминал вернёт кандидатов
-     * (цели + каскад), БД не тронута.
-     */
+    /** Новая версия каждой цели шага: слияние патча в базе; inc(n) — приращение; { rev } — строгий режим. */
+    update(patch?: Record<string, unknown>, opts?: {
+        rev?: number;
+    }): Chain;
+    /** Создать или заменить целиком (класс с ключом); строка ответа несёт $upsert. */
+    upsert(data: Record<string, unknown>): Chain;
+    /** Удалить цели шага с каскадом; без { confirm: true } — превью замыкания ($action). */
     delete(opts?: {
         confirm?: boolean;
     }): Chain;
-    /**
-     * ФИЗИЧЕСКИЙ hard-erase (необратимо): сносит УЖЕ логически удалённые (tombstone) цели + всё
-     * поддерево по links (все версии). Живую сущность не трогает — сначала .delete(). { confirm: true }
-     * — стирает; без confirm — превью замыкания (что сотрётся), БД не тронута. Историю НЕ сохраняет
-     * (в отличие от .delete()). Реализуется серверной purge() (SET LOCAL letopis.purge отключает триггер).
-     */
+    /** Затереть строковые поля ('[erased]') и пометить тегом anonymized. */
+    anonymize(fields: string[]): Chain;
+    /** Сменить класс: у класса с ключом — новый id и перевод ссылок. */
+    reclass(cls: string, data?: Record<string, unknown>): Chain;
+    /** Чтение с блокировкой строк последнего шага до конца db.begin() (rows, first, ids). */
+    forUpdate(): Chain;
+    /** Восстановить удалённые объекты шага: последний снимок новой версией (id прежний). */
+    restore(): Chain;
+    /** Стереть историю удалённых объектов шага; без { confirm: true } — превью ($versions). */
     purge(opts?: {
         confirm?: boolean;
     }): Chain;
+    /** Новое значение ключа: строка с новым id, ссылки переведены (поля — данные, роли — концы). */
+    rekey(patch: Record<string, unknown>): Chain;
+    /** Кэш результатов (§2.12): ответ хранится в памяти процесса ttl секунд (по умолчанию 60). */
+    cache(opts?: {
+        ttl?: number;
+    }): Chain;
 }
 /**
- * Свойство-класс на цепочке:
- *   ВЫЗОВ  `Класс(фильтр?)` — шаг-навигация; повтор LINK-класса в пути = возврат
- *          к его узлу (pivot: ветвление к другому концу, дофильтровка AND);
- *   СЛОТ   `Класс` без скобок — конец links записываемой версии:
- *     .set(target) — установить конец (id | Row | вложенная цепочка: та же транзакция,
- *                    ровно одна сущность класса конца); союз-конец замещается целиком;
- *     .unset()     — снять optional-конец.
- * Слот валиден только для конца из Schema.links владельца и ТОЛЬКО после операции
- * записи: …create(…).Класс.set(x) / …update(…).Класс.unset() — та же версия строки.
+ * Шаг цепочки: вызов — переход (фильтр); после глагола записи без вызова — слот конца версии:
+ * `.Роль.set(id | [id] | строка | цепочка)`, `.unset()`, у множественного конца `.add()` и `.remove()`.
  */
-export type StepProp = ((filter?: Filter) => Chain) & {
-    set(target: string | {
-        id: string;
-    } | Chain): Chain;
+export type StepFn = ((filter?: Filter) => Chain) & {
+    set(value: unknown): Chain;
     unset(): Chain;
+    add(value: unknown): Chain;
+    remove(value: unknown): Chain;
 };
 export type Chain = ChainCore & {
-    [className: string]: StepProp;
-};
-export interface DbCore {
-    /**
-     * Идентичность ВЫЗОВА: хендл того же пула, работающий от имени account.
-     * Арендатор — свойство вызова, а не подключения (в connect() опции account нет):
-     *
-     *   const db = await connect({ dsn, schema })   // пул, безличный
-     *   const t  = await db.as(req.accountId)       // кто именно делает этот вызов
-     *   await t.Клиент().rows()                     // изолировано по account
-     *
-     * При enforceAccount (default) чтение/запись возможны только с такого хендла.
-     * При enforceAcl энфорсер компилится под ЭТОГО субъекта (у каждого scope свой).
-     * owner по умолчанию = account; переопределяется вторым аргументом.
-     */
-    as(account: string | {
-        id: string;
-    }, opts?: {
-        owner?: string;
-    }): Promise<EntityDb>;
-    /** Открыть транзакцию: tr — тот же API + commit/rollback/lock. */
-    begin(): Promise<EntityTx>;
-    commit(tr: EntityTx): Promise<void>;
-    rollback(tr: EntityTx): Promise<void>;
-    /** Именованный батч: те же цепочки, планы записи копятся до run(). */
-    batch(name: string): Batch;
-    /**
-     * Realtime: события каждой вставленной версии (insert/update/delete-tombstone).
-     * watch(cb) — все классы; watch('Запись', cb) — один. Возврат — stop-функция.
-     * LISTEN-соединение переживает обрывы (re-listen автоматом), но NOTIFY за время
-     * разрыва потеряны — opts.onReconnect зовётся после восстановления: дочитайте пропущенное.
-     */
-    watch(cb: (e: WatchEvent) => void, opts?: WatchOpts): Promise<() => void>;
-    watch(cls: string, cb: (e: WatchEvent) => void, opts?: WatchOpts): Promise<() => void>;
-    close(): Promise<void>;
-    /**
-     * Перечитать определения классов из таблицы Schema (после правки её простым SQL / db.schema.define):
-     * пересобирает registry и, при enforceAcl, ACL-резолвер — без реконнекта. Подхват «сразу».
-     */
-    reloadSchema(): Promise<void>;
-    registry: Registry;
-    /** Голый postgres-клиент (тесты, EXPLAIN). */
-    sql: Ctx['sql'];
-    /** Служебные таблицы auth/ACL (обычные, вне версий/цепочек). */
-    accounts: Tables['accounts'];
-    credentials: Tables['credentials'];
-    resources: Tables['resources'];
-    rules: Tables['rules'];
-    /** Определения классов: db.schema.define(def) — upsert в таблицу Schema + reloadSchema(). */
-    schema: Tables['schema'];
-    /** Вход по кредам (пароль/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;
+    [className: string]: StepFn;
 };
-export type EntityTx = EntityDb & {
-    commit(): Promise<void>;
-    rollback(): Promise<void>;
-    lock(...keys: (string | number)[]): Promise<void>;
-};
-/** Событие watch(): факт новой версии; данные дочитываются запросом при надобности. */
-export interface WatchEvent {
-    partition: string;
-    class: string;
-    id: string;
-    updated: string;
-    deleted: boolean;
-}
-/** Опции watch(): реакция на восстановление LISTEN-соединения. */
-export interface WatchOpts {
-    /** Зовётся после каждого re-listen (не на первом подключении): NOTIFY за разрыв потеряны. */
-    onReconnect?: () => void;
-}
-export type Batch = {
-    /** Исполнить всю очередь планов одной транзакцией (бывший execute). */
-    run(): Promise<Row[][]>;
-    discard(): void;
-    size(): number;
-} & {
-    [className: string]: (filter?: Filter) => Chain;
-};
-interface RootState {
-    batches: Map<string, BatchPlan[]>;
-}
-/** Внутренний канал: план чужой ленивой цепочки (слот-значения, entity()). */
+/** Внутренний канал: план чужой ленивой цепочки (entity()). */
 export declare const PLAN: unique symbol;
-export declare function makeDb(ctx: Ctx, root?: RootState): EntityDb;
+/** entity-идентичность: переменная-цепочка → nodeKey её узла в этом пути. */
+type NodeMap = ReadonlyMap<object, number>;
+/** Класс, алиас или роль → класс шага (для роли — первый класс её целей). */
+export declare function lookupStep(reg: Registry, name: string): {
+    cls: ClassInfo;
+    role?: string;
+} | undefined;
+export declare function makeChain(ctx: ChainCtx, steps: Step[], mods: ChainMods, nodes?: NodeMap): Chain;
+/**
+ * Батч: очередь планов; каждый вызов класса — своя ссылка на очередь (свой план). run() исполняет очередь
+ * в контексте ctx (актор, арендатор, владелец, транзакция) — поэтому очередь принадлежит фасаду этого ctx
+ * и общей с другими фасадами быть не может: иначе план исполнился бы от имени чужого актора.
+ */
+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 {};