letopis 0.5.0 → 0.16.0

package/dist/schema.js

@@ -2,6 +2,8 @@
  * Загрузка таблицы Schema → реестр классов:
  *  - резолв имени по id и alias;
  *  - цепочка ancestors (walk по ancestor, если в БД не заполнена);
+ *  - attributes НАСЛЕДУЮТСЯ по цепочке (потомок поверх предка; поле = замена правила
+ *    целиком) — включая правило id (генерация v4/v5/v7); links НЕ наследуются;
  *  - скомпилированный fastest-validator per class;
  *  - карта типов полей (для SQL-кастов фильтров).
  */
@@ -62,6 +64,17 @@ export function fieldTypeOf(attr) {
         const t = attr.type;
         if (t === 'record')
             return { kind: 'record', value: fieldTypeOf(attr.value ?? 'any') };
+        if (t === 'object') {
+            // вложенная структура: {type:'object', props:{…}} — типы листьев любой глубины
+            const props = attr.props ?? attr.properties;
+            if (props && typeof props === 'object') {
+                const m = new Map();
+                for (const [k, v] of Object.entries(props))
+                    m.set(k, fieldTypeOf(v));
+                return { kind: 'object', props: m };
+            }
+            return { kind: 'any' };
+        }
         if (t === 'array')
             return { kind: 'array' };
         if (t === 'number')
@@ -77,6 +90,58 @@ export function fieldTypeOf(attr) {
     }
     return { kind: 'any' };
 }
+/**
+ * Элемент Schema.links: объект-конец v2 (jsonb) либо legacy-строка 'Org'
+ * (включая JSON-текст в text[] у старых схем). Возвращает [конец, isV2].
+ */
+function parseEnd(cls, raw) {
+    let o;
+    if (typeof raw === 'string') {
+        if (!raw.trimStart().startsWith('{'))
+            return [{ classes: [raw] }, false];
+        try {
+            o = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`letopis: class "${cls}" has malformed link end (bad JSON): ${raw}`);
+        }
+    }
+    else {
+        o = raw;
+    }
+    const classes = o.classes ?? (o.class ? [o.class] : []);
+    if (!classes.length || classes.some((c) => typeof c !== 'string' || !c)) {
+        throw new Error(`letopis: class "${cls}" has link end without classes: ${JSON.stringify(raw)}`);
+    }
+    return [{ classes, optional: o.optional === true, cardinality: o.cardinality }, true];
+}
+/**
+ * attributes.id: правило валидации + (объектом) спецификация генерации.
+ * generate/from — ключи letopis, вырезаются из правила перед компиляцией валидатора.
+ */
+function parseIdGen(cls, attributes) {
+    const raw = attributes.id;
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { idGen: { version: 4 }, attrs: attributes };
+    }
+    const { generate, from, ...rule } = raw;
+    const attrs = { ...attributes, id: rule };
+    if (generate === undefined)
+        return { idGen: { version: 4 }, attrs };
+    if (generate !== 4 && generate !== 5 && generate !== 7) {
+        throw new Error(`letopis: class "${cls}" — attributes.id.generate must be 4 | 5 | 7, got ${JSON.stringify(generate)}`);
+    }
+    if (generate === 5) {
+        if (!Array.isArray(from) || !from.length || from.some((f) => typeof f !== 'string' || !f)) {
+            throw new Error(`letopis: class "${cls}" — id generate:5 needs "from": non-empty string[] (link ends / data fields)`);
+        }
+        return { idGen: { version: 5, from: from }, attrs };
+    }
+    if (from !== undefined) {
+        throw new Error(`letopis: class "${cls}" — attributes.id.from is for generate:5 only`);
+    }
+    return { idGen: { version: generate }, attrs };
+}
 function buildDef(row, byId) {
     // цепочка наследования: из БД или walk по ancestor
     let ancestors = row.ancestors ?? [];
@@ -90,18 +155,54 @@ function buildDef(row, byId) {
             cur = byId.get(cur)?.ancestor ?? null;
         }
     }
+    // attributes НАСЛЕДУЮТСЯ по цепочке ancestor: потомок ПОВЕРХ предка, переопределение
+    // поля — замена правила ЦЕЛИКОМ (не слияние объекта-правила). links не наследуются.
+    const merged = {};
+    for (let i = ancestors.length - 1; i >= 0; i--) {
+        Object.assign(merged, byId.get(ancestors[i])?.attributes ?? {});
+    }
+    // attributes.id: спецификация генерации (generate/from) отделяется от правила валидации
+    const { idGen, attrs } = parseIdGen(row.id, merged);
     // fastest-validator: валидируем {id, ...data}; СТРОГО — лишние поля запрещены
-    const compiled = v.compile({ ...row.attributes, $$strict: true });
+    const compiled = v.compile({ ...attrs, $$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)) {
+    for (const [field, attr] of Object.entries(attrs)) {
         if (field.startsWith('$$'))
             continue;
         fieldTypes.set(field, fieldTypeOf(attr));
     }
+    let strictEnds = false;
+    // jsonb-массив; text[] у legacy-схем даёт string[]; jsonb-строка "[…]" (двойная
+    // сериализация внешних писателей) — распарсить
+    let rawLinks = row.links ?? [];
+    if (typeof rawLinks === 'string')
+        rawLinks = JSON.parse(rawLinks);
+    const ends = rawLinks.map((raw) => {
+        const [end, v2] = parseEnd(row.id, raw);
+        if (v2)
+            strictEnds = true;
+        return end;
+    });
+    // id v5: каждый источник from — обязательный конец links (класс или полное имя союза
+    // 'Service|Complex') ЛИБО поле data
+    if (idGen.version === 5) {
+        for (const f of idGen.from) {
+            const end = ends.find((e) => e.classes.includes(f) || e.classes.join('|') === f);
+            if (end) {
+                if (end.optional) {
+                    throw new Error(`letopis: class "${row.id}" — id (uuid v5) can't depend on optional end "${f}"`);
+                }
+                continue;
+            }
+            if (f !== 'id' && f in attrs)
+                continue;
+            throw new Error(`letopis: class "${row.id}" — id "from" source "${f}" is neither a link end nor a data field`);
+        }
+    }
     return {
         id: row.id,
         alias: row.alias,
@@ -109,8 +210,10 @@ function buildDef(row, byId) {
         ancestor: row.ancestor,
         ancestors,
         descendants: row.descendants ?? [], // считает триггер schema_lineage
-        attributes: row.attributes,
-        links: row.links ?? [],
+        attributes: merged,
+        links: ends,
+        strictEnds,
+        idGen,
         meta: row.meta ?? {},
         abstract: row.meta?.abstract === true || row.meta?.abstract === 'true',
         order: row.order,

package/dist/sessions.d.ts

@@ -0,0 +1,32 @@
+/** Минимальный срез Redis-клиента (ioredis подходит как есть). */
+export interface SessionStore {
+    set(key: string, value: string, mode: 'EX', ttlSec: number): Promise<unknown>;
+    get(key: string): Promise<string | null>;
+    del(...keys: string[]): Promise<unknown>;
+    sadd(key: string, ...members: string[]): Promise<unknown>;
+    srem(key: string, ...members: string[]): Promise<unknown>;
+    smembers(key: string): Promise<string[]>;
+    expire(key: string, ttlSec: number): Promise<unknown>;
+}
+export interface Session {
+    account: string;
+    meta: Record<string, unknown>;
+    created: string;
+}
+export interface Sessions {
+    /** Новая сессия → токен (отдаётся один раз; в Redis — только его sha256). Default ttl 7 суток. */
+    start(account: string | {
+        id: string;
+    }, opts?: {
+        ttlSec?: number;
+        meta?: Record<string, unknown>;
+    }): Promise<string>;
+    /** null — нет/просрочена/отозвана. */
+    check(token: string): Promise<Session | null>;
+    revoke(token: string): Promise<boolean>;
+    /** Гасит все сессии аккаунта, возвращает сколько было в индексе. */
+    revokeAll(account: string | {
+        id: string;
+    }): Promise<number>;
+}
+export declare function makeSessions(store: SessionStore): Sessions;

package/dist/sessions.js

@@ -0,0 +1,48 @@
+/**
+ * Сессии во внешнем KV (Redis): db.auth.sessions(store).
+ * Клиент НЕ входит в зависимости — инжектируется пользователем (интерфейс ioredis-совместим).
+ * В store лежит только sha256-хэш токена: дамп Redis не раскрывает действующие токены.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+const sha256 = (s) => createHash('sha256').update(s).digest('hex');
+const accId = (a) => (typeof a === 'object' ? a.id : a);
+const DEFAULT_TTL = 7 * 24 * 3600;
+export function makeSessions(store) {
+    const kTok = (h) => `sess:${h}`;
+    // индекс аккаунта без TTL: протухшие хэши безвредны, полная чистка — revokeAll
+    const kAcc = (id) => `sess:acc:${id}`;
+    return {
+        async start(account, opts = {}) {
+            const id = accId(account);
+            const token = randomBytes(32).toString('hex');
+            const h = sha256(token);
+            const ttl = opts.ttlSec ?? DEFAULT_TTL;
+            const payload = { account: id, meta: opts.meta ?? {}, created: new Date().toISOString() };
+            await store.set(kTok(h), JSON.stringify(payload), 'EX', ttl);
+            await store.sadd(kAcc(id), h);
+            return token;
+        },
+        async check(token) {
+            const raw = await store.get(kTok(sha256(token)));
+            return raw ? JSON.parse(raw) : null;
+        },
+        async revoke(token) {
+            const h = sha256(token);
+            const raw = await store.get(kTok(h));
+            if (!raw)
+                return false;
+            const { account } = JSON.parse(raw);
+            await store.del(kTok(h));
+            await store.srem(kAcc(account), h);
+            return true;
+        },
+        async revokeAll(account) {
+            const id = accId(account);
+            const hs = await store.smembers(kAcc(id));
+            if (hs.length)
+                await store.del(...hs.map(kTok));
+            await store.del(kAcc(id));
+            return hs.length;
+        },
+    };
+}

package/dist/sql.d.ts

@@ -18,7 +18,7 @@
  * Цепочка шагов соединяется JOIN LATERAL — комбинации путей сохраняются.
  */
 import type { Sql } from 'postgres';
-import type { ClassDef, ChainMods, Filter, QueryEvent } from './types.js';
+import type { AclOp, AclDecision, ClassDef, ChainMods, FieldType, Filter, QueryEvent } from './types.js';
 import type { Registry } from './schema.js';
 export interface Ctx {
     sql: Sql;
@@ -31,23 +31,49 @@ export interface Ctx {
     systemAccount?: string;
     /** Жёсткая изоляция арендатора: все чтения фильтруются, записи пришпилены к account. */
     enforceAccount?: boolean;
+    /** enforceAcl: скомпилированный на connect резолвер Rule/Resource (READ/WRITE/DELETE). */
+    aclDecide?: (cls: ClassDef, op: AclOp) => AclDecision;
     /** true внутри db.begin()-транзакции (write не оборачивает в begin повторно). */
     inTx?: boolean;
+    /** true только у db.begin()-транзакций (не у внутренних): управляет подсказкой при 40P01/40001. */
+    userTx?: boolean;
     /** Наблюдаемость: хук на каждый запрос цепочки. */
     onQuery?: (e: QueryEvent) => void;
     /** Порог «медленного» запроса, мс (без onQuery — console.warn). */
     slowMs?: number;
 }
+/** Транзиентные ошибки 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;
 export interface Step {
     /** Имя, как вызвано в цепочке (алиас или id). */
     name: string;
     cls: ClassDef;
     filter?: Filter;
+    /** Метка узла (есть у каждого реального шага). */
+    nodeKey?: number;
+    /**
+     * Pivot: шаг-ВОЗВРАТ к уже введённому узлу (повтор LINK-класса / entity(та же переменная)).
+     * Не создаёт узел; его фильтры дофильтровывают узел (AND); следующий шаг ветвится от узла.
+     */
+    pivotKey?: number;
     /** .alias(name) — ключ шага в путях. */
     aliasKey?: string;
     /** .tags(…) — фильтр по колонке tags: строка | string[] (все) | has/hasAny/hasAll. */
@@ -58,11 +84,27 @@ export interface Step {
     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;
 }
 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';