letopis 0.20.3 → 1.0.0

package/dist/registry.js

@@ -0,0 +1,82 @@
+/**
+ * Реестр классов (план, этап 2, п. 3 и 6): описания из строк `Class` с развёрнутым `resolved`
+ * (собственные классы арендатора и системные), поиск по имени и алиасу, предки и потомки,
+ * типы листьев для фильтров и валидатор на TypeScript, скомпилированный из того же описания.
+ */
+import { LetopisError } from './errors.js';
+import { compileValidator } from './validate.js';
+export class Registry {
+    byName = new Map();
+    byAlias = new Map();
+    /** Заменить содержимое строками Class (собственные классы арендатора и системные). */
+    load(rows) {
+        this.byName.clear();
+        this.byAlias.clear();
+        for (const r of rows) {
+            const res = r.data.resolved;
+            let compiled = null;
+            const info = {
+                name: res.name,
+                tenant: r.tenant,
+                rev: r.rev,
+                kind: res.kind,
+                alias: r.data.alias,
+                abstract: Boolean(res.abstract),
+                ancestors: res.ancestors,
+                schema: res.schema,
+                ends: (res.ends ?? {}),
+                key: (res.key ?? []),
+                history: res.history,
+                ownerDefault: (res.ownerDefault ?? 'tenant'),
+                cache: (res.cache ?? undefined),
+                meta: (res.meta ?? {}),
+                validator: () => (compiled ??= compileValidator(res.schema)),
+            };
+            this.byName.set(info.name, info);
+            if (info.alias)
+                this.byAlias.set(info.alias, info.name);
+        }
+    }
+    has(name) {
+        return this.byName.has(name) || this.byAlias.has(name);
+    }
+    find(name) {
+        return this.byName.get(name) ?? this.byName.get(this.byAlias.get(name) ?? '');
+    }
+    resolve(name) {
+        const c = this.find(name);
+        if (!c)
+            throw new LetopisError('invalid_class', `класс ${name} не найден`);
+        return c;
+    }
+    all() {
+        return [...this.byName.values()];
+    }
+    /** Класс и все его потомки (семейство). */
+    family(name) {
+        const root = this.resolve(name).name;
+        return this.all().filter((c) => c.ancestors.includes(root));
+    }
+    /** Тип листа по пути полей класса: по JSON Schema (type и format). */
+    leafType(cls, path) {
+        let node = this.resolve(cls).schema;
+        for (const p of path) {
+            const props = node?.properties;
+            const next = props?.[p] ?? (typeof node?.additionalProperties === 'object' ? node.additionalProperties : undefined);
+            if (!next)
+                return 'jsonb';
+            node = next;
+        }
+        const types = Array.isArray(node?.type) ? node.type.filter((t) => t !== 'null') : [node?.type];
+        if (types.length !== 1)
+            return 'jsonb';
+        switch (types[0]) {
+            case 'integer':
+            case 'number': return 'numeric';
+            case 'boolean': return 'boolean';
+            case 'string':
+                return node?.format === 'date-time' ? 'timestamptz' : node?.format === 'date' ? 'date' : node?.format === 'uuid' ? 'uuid' : 'text';
+            default: return 'jsonb';
+        }
+    }
+}

package/dist/sql.d.ts

@@ -1,159 +1,76 @@
-/**
- * SQL-билдер. Ключевая идея (замена «медленных» вью движка):
- * «последняя версия» считается ПОСЛЕ сужения по class + GIN-кандидатам, а не по всей таблице.
- *
- * Шаблон шага:
- *   SELECT * FROM (
- *     SELECT DISTINCT ON (e.id) e.* FROM Entity e
- *     WHERE e.partition=$ AND e.class=$
- *       [AND e.id = $ | e.id IN (…)]                    -- id-фильтр
- *       [AND e.id = hPrev.links->>$cls]                 -- forward-джойн (id неизменен)
- *       [AND e.id IN (SELECT c.id FROM Entity c         -- GIN-кандидаты: containment-фильтры
- *                     WHERE c.partition=$ AND c.class=$ AND c.data @> $ [AND c.links @> …])]
- *     ORDER BY e.id, e.updated DESC                     -- latest-версия кандидатов
- *   ) t
- *   WHERE t.deleted IS NULL [AND все фильтры на t]      -- перепроверка на АКТУАЛЬНОЙ версии
- *
- * Кандидатное сужение — оптимизация (GIN); истина — перепроверка условий на latest.
- * Цепочка шагов соединяется JOIN LATERAL — комбинации путей сохраняются.
- */
-import type { Sql } from 'postgres';
-import type { AclOp, AclDecision, ClassDef, ChainMods, FieldType, Filter, QueryEvent } from './types.js';
-import type { Registry } from './schema.js';
-export interface Ctx {
-    sql: Sql;
-    registry: Registry;
-    pgSchema: string;
-    partition: string;
-    /** Арендатор ВЫЗОВА: заполнен у scoped-хендла db.as(account), пуст у корневого. */
-    account?: string;
-    /** Дефолтный owner записей этого scope (db.as(account, { owner })). Default = account. */
-    owner?: string;
-    /** System-аккаунт — fallback для NOT NULL Entity.account (загружается при connect). */
-    systemAccount?: string;
-    /** Жёсткая изоляция арендатора: все чтения фильтруются, записи пришпилены к account. */
-    enforceAccount?: boolean;
-    /** enforceAcl: скомпилированный резолвер Rule/Resource (READ/WRITE/DELETE) для account ЭТОГО ctx. */
-    aclDecide?: (cls: ClassDef, op: AclOp) => AclDecision;
-    /**
-     * enforceAcl: скомпилировать энфорсер под субъекта переданного ctx (пишет в c.aclDecide).
-     * Ставит connect(); зовут db.as() и reload. Один энфорсер = один субъект: memo в acl.ts
-     * ключуется классом+операцией БЕЗ аккаунта, переиспользование между scope — утечка решения.
-     */
-    compileAcl?: (c: Ctx) => Promise<void>;
-    /** true внутри db.begin()-транзакции (write не оборачивает в begin повторно). */
-    inTx?: boolean;
-    /** true только у db.begin()-транзакций (не у внутренних): управляет подсказкой при 40P01/40001. */
-    userTx?: boolean;
-    /** Наблюдаемость: хук на каждый запрос цепочки. */
-    onQuery?: (e: QueryEvent) => void;
-    /** Порог «медленного» запроса, мс (без onQuery — console.warn). */
-    slowMs?: number;
-    /** Перечитать определения классов из таблицы Schema: пересобрать registry (+ enforcer при enforceAcl). Ставит connect(). */
-    reload?: () => Promise<void>;
-}
-/** Транзиентные ошибки PG — гонка, снимаемая повтором: deadlock / serialization failure. */
-export declare function isTransient(e: unknown): boolean;
-/** Внутри db.begin() повтор невозможен (вся транзакция aborted) — дописываем подсказку. */
-export declare function hintTxRetry(e: unknown): void;
-export declare const RETRIES = 3;
-export declare const retryDelay: (attempt: number) => Promise<void>;
-/**
- * Единая точка исполнения запросов цепочек: sql.unsafe + событие onQuery/slowMs.
- * Чтения в автокоммите ретраят transient-ошибки (40P01/40001); внутри db.begin()
- * повтор запрещён семантикой PG — ошибка уходит наружу с подсказкой.
- * Служебные запросы (loadRegistry, tables, listen) через неё не идут.
- */
-export declare function runQuery<T>(ctx: Ctx, text: string, params: unknown[], mode: QueryEvent['mode'], classes: string[]): Promise<T[]>;
-/** Значение слота связи: id | вложенный план | null (снять конец). */
-export type SlotValue = string | {
-    plan: Step[];
-    mods?: ChainMods;
-} | null;
-/** Уникальная метка узла пути (для pivot-возвратов; переживает нарезку плана). */
-export declare const nextNodeKey: () => number;
+import type { ClassInfo, LeafType, Registry } from './registry.js';
+import { type ChainMods, type Cursor, type Filter, type Row } from './types.js';
 export interface Step {
-    /** Имя, как вызвано в цепочке (алиас или id). */
+    /** Имя, как вызвано в цепочке (класс, алиас или роль). */
     name: string;
-    cls: ClassDef;
+    /** Класс узла (для роли — первый класс её целей): типы листьев, вид hub/link. */
+    cls: ClassInfo;
+    /** Шаг вызван именем роли (конца): переход идёт именно этим концом. */
+    role?: string;
     filter?: Filter;
-    /** Метка узла (есть у каждого реального шага). */
+    /** Метка узла — у каждого реального шага. */
     nodeKey?: number;
-    /**
-     * Pivot: шаг-ВОЗВРАТ к уже введённому узлу (повтор LINK-класса / entity(та же переменная)).
-     * Не создаёт узел; его фильтры дофильтровывают узел (AND); следующий шаг ветвится от узла.
-     */
+    /** Возврат к уже введённому узлу (повтор связи, entity() той же переменной). */
     pivotKey?: number;
-    /** .alias(name) — ключ шага в путях. */
     aliasKey?: string;
-    /**
-     * .exact() — только ЭТОТ класс, без классов-потомков. По умолчанию шаг полиморфен
-     * (родитель отдаёт объединение с потомками); нужно, когда наследование в домене
-     * использовано для переиспользования attributes, а не как «is-a» для выборки
-     * (демо: `запись` наследует `окно`, но смена ≠ бронь).
-     */
-    exactClass?: boolean;
-    /** .tags(…) — фильтр по колонке tags: строка | string[] (все) | has/hasAny/hasAll. */
+    /** Только сам класс, без потомков. */
+    exact?: boolean;
     tagsFilter?: unknown;
-    /** .account(uuid|Row) — фильтр по колонке account. */
-    accountFilter?: string;
-    /** .owner(uuid|Row) — фильтр по колонке owner. */
     ownerFilter?: string;
-    /** Внутреннее (write-цепочки): containment по links — контекст-связи. */
-    linksFilter?: Record<string, string>;
-    /**
-     * Слоты связей (`.Класс.set(target)` / `.Класс.unset()`): значения концов записываемой
-     * версии БЕЗ участия в фильтре целей. string — id; {plan} — вложенная цепочка (та же
-     * транзакция, ровно одна сущность класса конца); null — снять optional-конец.
-     */
-    extraLinks?: Record<string, SlotValue>;
-    /** Внутреннее (enforceAcl): предикат WRITE/DELETE-правила — цели ищутся только среди своих. */
-    aclFilter?: Record<string, unknown>;
-    /** .deep(max): рекурсивный self-обход (дети любой глубины), только reverse того же класса. */
     deepMax?: number;
-    /** Операция записи на шаге (.create/.update/.delete/.anonymize) — исполняется терминалом плана. */
-    op?: import('./types.js').PlanOp;
-    /** Внутреннее: шаг «те же сущности» (операция сразу после операции) — цель = строки старта. */
-    self?: boolean;
+    /** Звено плана записи (этап 4): глагол на этом шаге; построитель чтения его не видит. */
+    op?: import('./write.js').PlanOp;
+    /** Модификаторы цепочки на момент глагола: limit и sort сужают цели записи. */
+    opMods?: ChainMods;
+    /** Слоты концов записываемой версии: .Роль.set/unset/add/remove. */
+    slots?: import('./write.js').Slot[];
+    /** Глагол сразу после глагола — пишет в те же сущности. */
+    self?: true;
+}
+/** Уникальная метка узла пути. */
+export declare const nextNodeKey: () => number;
+export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'countPaths' | 'versions' | 'agg';
+export interface AggSpec {
+    fn: 'sum' | 'avg' | 'min' | 'max' | 'countBy';
+    field: string;
 }
-export declare const entityTable: (pgSchema: string) => string;
-/** Тип листа data-пути по Schema: спуск через record (значение) и object (props). */
-export declare function leafType(cls: ClassDef, path: string[]): FieldType | undefined;
-type HopMode = 'forward' | 'reverse';
-/** Класс target входит в какой-нибудь конец def (союзы учитываются). */
-export declare function linksTo(def: ClassDef, target: string): boolean;
-/** Правило обхода между шагами (по реестру Schema). */
-export declare function resolveHop(prev: ClassDef, next: ClassDef): HopMode;
-export type ReadMode = 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg';
 export interface BuiltQuery {
     text: string;
     params: unknown[];
-    /** Ключи шагов в путях (после alias/dedupe). */
+    /** Ключи шагов в путях (алиасы, повторы — _2, _3). */
     keys: string[];
+    /** Тип листа агрегата (min/max числового поля приводятся к числу). */
+    aggLeaf?: LeafType;
+}
+/** Классы, которые объявляют роль. */
+export declare function roleOwners(reg: Registry, role: string): ClassInfo[];
+/** Классы целей роли (имя конца однозначно во всей схеме — проверяет база). */
+export declare function roleTargets(reg: Registry, role: string): string[];
+/** Конкретные классы, которые матчит шаг: класс (роль — её цели) и потомки, если не exact(). */
+export declare function stepClasses(reg: Registry, step: Step): string[];
+/** Принимает ли список классов конца класс cls (с учётом его предков). */
+export declare const accepts: (reg: Registry, targets: string[], cls: string) => boolean;
+export interface Hop {
+    dir: 'forward' | 'reverse';
+    /** Только эти роли; null — любой конец (целостность ссылок гарантирует, что подходят только допустимые). */
+    roles: string[] | null;
 }
-/** Корневой хендл при enforceAccount читать/писать не может: арендатора называет db.as(). */
-export declare function guardScoped(ctx: Ctx): void;
-/** Построить читающий запрос по цепочке. */
-export declare function buildRead(ctx: Ctx, steps: Step[], mods: ChainMods, mode: ReadMode): BuiltQuery;
-/** INSERT новой версии/tombstone. $9 = updated прошлой версии (или null), $10 = deleted. */
-export declare function insertSql(pgSchema: string): string;
-/** Мульти-INSERT новых строк (батч): n строк × 8 параметров, updated/deleted по умолчанию. */
-export declare function multiInsertSql(pgSchema: string, n: number): string;
-/**
- * Серверное удаление: DELETE перехватывает триггер entity_delete —
- * tombstone актуальной живой версии + рекурсивный каскад по links, всё в БД.
- * $1 partition, $2 class, дальше — id-шники.
- */
-export declare function deleteSql(pgSchema: string, n: number): string;
-/**
- * Замыкание удаления: цели + все живые зависимые рекурсивно (то, что каскад затомбстоунит).
- * Рекурсивный CTE; каждый узел — актуальная живая версия. $1 partition, $2 class, $3+ — ids.
- */
-export declare function closureSql(pgSchema: string, n: number): string;
 /**
- * Вызов серверной purge(): $4 dry → превью (актуальные версии замыкания, БД цела), иначе двухфазный
- * физический снос корня+поддерева. RETURNS SETOF Entity (по строке на сущность). Вся логика
- * (замыкание, двухфазность, отключение триггера через SET LOCAL) — в БД. $1 partition, $2 class, $3 id, $4 dry.
+ * Направление перехода между узлами (расширение resolveHop 0.21):
+ *  - шаг-роль после владельца роли — вперёд этим концом; шаг после роли — назад этим концом;
+ *  - иначе по концам всех классов обоих семейств: в своём семействе (папка → папки) — назад, к детям;
+ *    хаб → связь — назад; связь → хаб и хаб → хаб — вперёд; нет нужного — другое направление.
  */
-export declare function purgeCallSql(pgSchema: string): string;
-export {};
+export declare function resolveHop(reg: Registry, prev: Step, next: Step): Hop;
+/** Курсор keyset-пагинации из последней строки страницы. */
+export declare function cursorOf(row: Row, field: string): Cursor;
+export interface BuildOptions {
+    /**
+     * Режим сверки (тест find-ids-parity): вместо функций владельца find_* — те же запросы прямо
+     * под RLS. Индексы GIN тогда не работают, зато видимость решают политики, а не row_visible().
+     */
+    direct?: boolean;
+}
+export declare function buildRead(reg: Registry, schema: string, steps: Step[], mods: ChainMods, mode: ReadMode, agg?: AggSpec, opts?: BuildOptions): BuiltQuery;
+/** Строка из to_jsonb(узла): служебные поля в $deleted / $depth, пустые необязательные — без ключа. */
+export declare function toRow(raw: Record<string, unknown>): Row;