letopis 0.5.0

package/dist/schema.js

@@ -0,0 +1,133 @@
+/**
+ * Загрузка таблицы Schema → реестр классов:
+ *  - резолв имени по id и alias;
+ *  - цепочка ancestors (walk по ancestor, если в БД не заполнена);
+ *  - скомпилированный fastest-validator per class;
+ *  - карта типов полей (для SQL-кастов фильтров).
+ */
+import { createRequire } from 'node:module';
+const Validator = createRequire(import.meta.url)('fastest-validator');
+const v = new Validator({ useNewCustomCheckerFunction: true });
+export class Registry {
+    byName = new Map();
+    all = [];
+    add(def) {
+        this.all.push(def);
+        this.byName.set(def.id, def);
+        this.byName.set(def.alias, def);
+    }
+    /** Класс по id или alias; undefined если нет. */
+    find(name) {
+        return this.byName.get(name);
+    }
+    /** Класс по id или alias; иначе понятная ошибка со списком. */
+    resolve(name) {
+        const def = this.byName.get(name);
+        if (!def) {
+            const names = this.all.map((d) => `${d.id}·${d.alias}`).join(', ');
+            throw new Error(`letopis: unknown class "${name}". Known: ${names}`);
+        }
+        return def;
+    }
+    has(name) {
+        return this.byName.has(name);
+    }
+}
+/** Тип поля из fastest-validator DSL — для каста в SQL. */
+export function fieldTypeOf(attr) {
+    if (typeof attr === 'string') {
+        const base = attr.split('|')[0].trim();
+        switch (base) {
+            case 'number':
+                return { kind: 'number' };
+            case 'date':
+                return { kind: 'date' };
+            case 'boolean':
+                return { kind: 'boolean' };
+            case 'array':
+                return { kind: 'array' };
+            case 'string':
+            case 'uuid':
+            case 'email':
+            case 'url':
+            case 'enum':
+                return { kind: 'string' };
+            default:
+                return { kind: 'any' };
+        }
+    }
+    if (Array.isArray(attr))
+        return attr.length ? fieldTypeOf(attr[0]) : { kind: 'any' };
+    if (typeof attr === 'object' && attr !== null) {
+        const t = attr.type;
+        if (t === 'record')
+            return { kind: 'record', value: fieldTypeOf(attr.value ?? 'any') };
+        if (t === 'array')
+            return { kind: 'array' };
+        if (t === 'number')
+            return { kind: 'number' };
+        if (t === 'date')
+            return { kind: 'date' };
+        if (t === 'boolean')
+            return { kind: 'boolean' };
+        if (t === 'enum' || t === 'string' || t === 'uuid' || t === 'email' || t === 'url')
+            return { kind: 'string' };
+        if (typeof t === 'string')
+            return fieldTypeOf(t);
+    }
+    return { kind: 'any' };
+}
+function buildDef(row, byId) {
+    // цепочка наследования: из БД или walk по ancestor
+    let ancestors = row.ancestors ?? [];
+    if (!ancestors.length) {
+        ancestors = [row.id];
+        let cur = row.ancestor;
+        const seen = new Set([row.id]);
+        while (cur && !seen.has(cur)) {
+            ancestors.push(cur);
+            seen.add(cur);
+            cur = byId.get(cur)?.ancestor ?? null;
+        }
+    }
+    // fastest-validator: валидируем {id, ...data}; СТРОГО — лишние поля запрещены
+    const compiled = v.compile({ ...row.attributes, $$strict: true });
+    const check = (data) => {
+        const res = compiled(data);
+        return res === true ? true : res;
+    };
+    const fieldTypes = new Map();
+    for (const [field, attr] of Object.entries(row.attributes)) {
+        if (field.startsWith('$$'))
+            continue;
+        fieldTypes.set(field, fieldTypeOf(attr));
+    }
+    return {
+        id: row.id,
+        alias: row.alias,
+        category: row.category,
+        ancestor: row.ancestor,
+        ancestors,
+        descendants: row.descendants ?? [], // считает триггер schema_lineage
+        attributes: row.attributes,
+        links: row.links ?? [],
+        meta: row.meta ?? {},
+        abstract: row.meta?.abstract === true || row.meta?.abstract === 'true',
+        order: row.order,
+        check,
+        fieldTypes,
+    };
+}
+export async function loadRegistry(sql, pgSchema, partition) {
+    const ident = `"${pgSchema.replace(/"/g, '""')}"`;
+    const rows = (await sql.unsafe(`SELECT id, alias, category, ancestor, attributes, links, meta, "order", ancestors, descendants
+       FROM ${ident}."Schema" WHERE partition = $1 ORDER BY category, "order"`, [partition]));
+    if (!rows.length) {
+        throw new Error(`letopis: schema "${pgSchema}" has no classes for partition "${partition}"`);
+    }
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    const registry = new Registry();
+    for (const row of rows)
+        registry.add(buildDef(row, byId));
+    return registry;
+}

package/dist/sql.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 { ClassDef, ChainMods, Filter, QueryEvent } from './types.js';
+import type { Registry } from './schema.js';
+export interface Ctx {
+    sql: Sql;
+    registry: Registry;
+    pgSchema: string;
+    partition: string;
+    account?: string;
+    owner?: string;
+    /** System-аккаунт — fallback для NOT NULL Entity.account (загружается при connect). */
+    systemAccount?: string;
+    /** Жёсткая изоляция арендатора: все чтения фильтруются, записи пришпилены к account. */
+    enforceAccount?: boolean;
+    /** true внутри db.begin()-транзакции (write не оборачивает в begin повторно). */
+    inTx?: boolean;
+    /** Наблюдаемость: хук на каждый запрос цепочки. */
+    onQuery?: (e: QueryEvent) => void;
+    /** Порог «медленного» запроса, мс (без onQuery — console.warn). */
+    slowMs?: number;
+}
+/**
+ * Единая точка исполнения запросов цепочек: sql.unsafe + событие onQuery/slowMs.
+ * Служебные запросы (loadRegistry, tables, listen) через неё не идут.
+ */
+export declare function runQuery<T>(ctx: Ctx, text: string, params: unknown[], mode: QueryEvent['mode'], classes: string[]): Promise<T[]>;
+export interface Step {
+    /** Имя, как вызвано в цепочке (алиас или id). */
+    name: string;
+    cls: ClassDef;
+    filter?: Filter;
+    /** .alias(name) — ключ шага в путях. */
+    aliasKey?: string;
+    /** .tags(…) — фильтр по колонке tags: строка | string[] (все) | has/hasAny/hasAll. */
+    tagsFilter?: unknown;
+    /** .account(uuid|Row) — фильтр по колонке account. */
+    accountFilter?: string;
+    /** .owner(uuid|Row) — фильтр по колонке owner. */
+    ownerFilter?: string;
+    /** Внутреннее (write-цепочки): containment по links — контекст-связи. */
+    linksFilter?: Record<string, string>;
+    /** .deep(max): рекурсивный self-обход (дети любой глубины), только reverse того же класса. */
+    deepMax?: number;
+}
+export declare const entityTable: (pgSchema: string) => string;
+type HopMode = 'forward' | 'reverse';
+/** Правило обхода между шагами (по реестру 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). */
+    keys: string[];
+}
+/** Построить читающий запрос по цепочке. */
+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;
+export {};