letopis 0.13.0 → 0.16.0

package/dist/sql.js

@@ -55,6 +55,9 @@ export async function runQuery(ctx, text, params, mode, classes) {
         }
     }
 }
+let nodeSeq = 0;
+/** Уникальная метка узла пути (для pivot-возвратов; переживает нарезку плана). */
+export const nextNodeKey = () => ++nodeSeq;
 /** Накопитель позиционных параметров. */
 class Params {
     list = [];
@@ -305,6 +308,10 @@ function compileFilter(cls, filter, p) {
     }
     return out;
 }
+/** Класс target входит в какой-нибудь конец def (союзы учитываются). */
+export function linksTo(def, target) {
+    return def.links.some((end) => end.classes.includes(target));
+}
 /** Правило обхода между шагами (по реестру Schema). */
 export function resolveHop(prev, next) {
     if (prev.category === 'HUB' && next.category === 'LINK')
@@ -315,9 +322,9 @@ export function resolveHop(prev, next) {
         // self-переход (Папка→Папка) = reverse: дети; родитель и так лежит в row.links
         if (prev.id === next.id)
             return 'reverse';
-        if (prev.links.includes(next.id))
+        if (linksTo(prev, next.id))
             return 'forward';
-        if (next.links.includes(prev.id))
+        if (linksTo(next, prev.id))
             return 'reverse';
         throw new Error(`letopis: no path ${prev.id} → ${next.id}: neither embeds the other (Schema.links)`);
     }
@@ -338,25 +345,60 @@ function orderExpr(alias, cls, mods) {
         return '';
     return ` ORDER BY ${sortField(alias, cls, mods.order)}${mods.desc ? ' DESC' : ''}`;
 }
-/** Keyset-пагинация: (поле сортировки, id) строго после курсора. Требует .sort(). */
-function afterCond(alias, cls, mods, p) {
+/** Keyset-пагинация: (поле сортировки, id) строго после курсора. Требует .sort(). Выражение без WHERE. */
+function afterExpr(alias, cls, mods, p) {
     if (!mods.after)
-        return '';
+        return undefined;
     if (!mods.order)
         throw new Error('letopis: .after(cursor) requires .sort(field)');
     const expr = sortField(alias, cls, mods.order);
     const cast = mods.order === 'updated' ? '::timestamptz' : castOf(leafType(cls, mods.order.slice(5).split('.')));
     const cmp = mods.desc ? '<' : '>';
-    return ` WHERE (${expr}, ${alias}.id) ${cmp} (${p.push(mods.after.v)}${cast}, ${p.push(mods.after.id)})`;
+    return `(${expr}, ${alias}.id) ${cmp} (${p.push(mods.after.v)}${cast}, ${p.push(mods.after.id)})`;
 }
+const whereOf = (conds) => {
+    const list = conds.filter((c) => !!c);
+    return list.length ? ` WHERE ${list.join(' AND ')}` : '';
+};
 /** Построить читающий запрос по цепочке. */
 export function buildRead(ctx, steps, mods, mode) {
     const p = new Params();
     const ent = entityTable(ctx.pgSchema);
     const pPart = p.push(ctx.partition);
+    // pivot: карта эффективных блоков. real[i] — индекс блока-узла шага i
+    // (pivot-шаг блока не строит, ссылается на узел по pivotKey).
+    const real = [];
+    const byNodeKey = new Map();
+    const tailConds = []; // дофильтры pivot-шагов (alias подставлен) — в хвостовой WHERE
+    for (let i = 0; i < steps.length; i++) {
+        const s = steps[i];
+        if (s.pivotKey !== undefined) {
+            const at = byNodeKey.get(s.pivotKey);
+            if (at === undefined)
+                throw new Error(`letopis: pivot "${s.name}" — node is not in this path`);
+            real[i] = at;
+        }
+        else {
+            real[i] = i;
+            if (s.nodeKey !== undefined)
+                byNodeKey.set(s.nodeKey, i);
+        }
+    }
     const blocks = [];
     for (let i = 0; i < steps.length; i++) {
         const step = steps[i];
+        // pivot-шаг: узел уже есть — только дофильтры (AND на алиас узла)
+        if (step.pivotKey !== undefined) {
+            const a = `h${real[i]}`;
+            const f = compileFilter(step.cls, step.filter, p);
+            for (const c of f.idConds)
+                tailConds.push(c(a));
+            for (const fr of f.finalFrags)
+                tailConds.push(fr(a));
+            if (step.tagsFilter !== undefined)
+                tailConds.push(compileTags(step.tagsFilter, p)(a));
+            continue;
+        }
         const pCls = p.push(step.cls.id);
         const f = compileFilter(step.cls, step.filter, p);
         // модификаторы шага: .tags() / .account() / .owner()
@@ -420,16 +462,17 @@ export function buildRead(ctx, steps, mods, mode) {
         const isDeep = step.deepMax !== undefined;
         if (i > 0 && !isDeep) { // deep строит containment сам (recursive CTE)
             const prev = steps[i - 1];
+            const prevAlias = `h${real[i - 1]}`; // pivot: ветвление от узла-возврата
             const hop = resolveHop(prev.cls, step.cls);
             if (hop === 'forward') {
                 // id неизменен — условие сразу во внутренний WHERE, перепроверка не нужна
-                innerWhere.push(`e.id = h${i - 1}.links->>${p.push(step.cls.id)}`);
+                innerWhere.push(`e.id = ${prevAlias}.links->>${p.push(step.cls.id)}`);
             }
             else {
                 // reverse containment: кандидаты по GIN + перепроверка на latest
                 const pKey = p.push(prev.cls.id);
-                candWhere.push(`c.links @> jsonb_build_object(${pKey}::text, h${i - 1}.id)`);
-                outerWhere.push(`t.links @> jsonb_build_object(${pKey}::text, h${i - 1}.id)`);
+                candWhere.push(`c.links @> jsonb_build_object(${pKey}::text, ${prevAlias}.id)`);
+                outerWhere.push(`t.links @> jsonb_build_object(${pKey}::text, ${prevAlias}.id)`);
             }
         }
         if (candWhere.length) {
@@ -456,7 +499,7 @@ export function buildRead(ctx, steps, mods, mode) {
                 ` WHERE t.deleted IS NULL AND t.links @> jsonb_build_object(${p.push(step.cls.id)}::text, ${ref}))`;
             block =
                 `(WITH RECURSIVE d AS (` +
-                    `SELECT k.*, 1 AS depth FROM ${kids(`h${i - 1}.id`)} k` +
+                    `SELECT k.*, 1 AS depth FROM ${kids(`h${real[i - 1]}.id`)} k` +
                     ` UNION ALL ` +
                     `SELECT k.*, d.depth + 1 FROM d JOIN LATERAL ${kids('d.id')} k ON true WHERE d.depth < ${pMax}::int` +
                     `) SELECT * FROM d) h${i}`;
@@ -464,45 +507,49 @@ export function buildRead(ctx, steps, mods, mode) {
         blocks.push(i === 0 ? `FROM ${block}` : `JOIN LATERAL ${block} ON true`);
     }
     const fromClause = blocks.join('\n');
-    const last = steps.length - 1;
-    const lastCls = steps[last].cls;
-    // ключи шагов в путях: alias → имя вызова; дубликаты получают _2, _3…
-    const keys = [];
+    const last = real[steps.length - 1]; // pivot в конце → терминал на его узле
+    const lastCls = steps[steps.length - 1].cls;
+    // ключи шагов в путях: alias → имя вызова; pivot узла не добавляет; дубликаты — _2, _3…
+    const keyed = [];
     const seen = new Map();
-    for (const s of steps) {
+    for (let i = 0; i < steps.length; i++) {
+        const s = steps[i];
+        if (s.pivotKey !== undefined)
+            continue;
         const base = s.aliasKey ?? s.name;
         const n = (seen.get(base) ?? 0) + 1;
         seen.set(base, n);
-        keys.push(n === 1 ? base : `${base}_${n}`);
+        keyed.push({ key: n === 1 ? base : `${base}_${n}`, block: i });
     }
+    const keys = keyed.map((k) => k.key);
     const limitOffset = (mods.limit !== undefined ? ` LIMIT ${p.push(mods.limit)}` : '') +
         (mods.offset !== undefined ? ` OFFSET ${p.push(mods.offset)}` : '');
     let text;
     switch (mode) {
         case 'paths': {
-            const obj = keys.map((k, i) => `${p.push(k)}::text, to_jsonb(h${i})`).join(', ');
+            const obj = keyed.map(({ key, block }) => `${p.push(key)}::text, to_jsonb(h${block})`).join(', ');
             text =
                 `SELECT jsonb_build_object(${obj}) AS path\n${fromClause}` +
-                    afterCond(`h${last}`, lastCls, mods, p) +
+                    whereOf([...tailConds, afterExpr(`h${last}`, lastCls, mods, p)]) +
                     orderExpr(`h${last}`, lastCls, mods) +
                     limitOffset;
             break;
         }
         case 'rows':
         case 'ids': {
-            const inner = `SELECT DISTINCT ON (h${last}.id) h${last}.* \n${fromClause}\n` +
+            const inner = `SELECT DISTINCT ON (h${last}.id) h${last}.* \n${fromClause}${whereOf(tailConds)}\n` +
                 `ORDER BY h${last}.id, h${last}.updated DESC`;
             const sel = mode === 'rows' ? 'to_jsonb(z) AS row' : 'z.id';
             text =
                 `SELECT ${sel} FROM (${inner}) z` +
-                    afterCond('z', lastCls, mods, p) +
+                    whereOf([afterExpr('z', lastCls, mods, p)]) +
                     orderExpr('z', lastCls, mods) +
                     limitOffset;
             break;
         }
         case 'versions': {
             // ВСЕ версии (включая tombstone) сущностей последнего шага, по возрастанию updated
-            const inner = `SELECT DISTINCT h${last}.id \n${fromClause}`;
+            const inner = `SELECT DISTINCT h${last}.id \n${fromClause}${whereOf(tailConds)}`;
             text =
                 `SELECT to_jsonb(v) AS row FROM (${inner}) z ` +
                     `JOIN ${ent} v ON v.partition = ${pPart} AND v.class = ${p.push(lastCls.id)} AND v.id = z.id ` +
@@ -511,7 +558,7 @@ export function buildRead(ctx, steps, mods, mode) {
             break;
         }
         case 'count':
-            text = `SELECT count(*)::int AS n\n${fromClause}`;
+            text = `SELECT count(*)::int AS n\n${fromClause}${whereOf(tailConds)}`;
             break;
         case 'agg': {
             const { aggFn, aggField } = mods;
@@ -521,12 +568,12 @@ export function buildRead(ctx, steps, mods, mode) {
             const path = aggField.slice(5).split('.');
             const acc = accessor(path)(`h${last}`); // data-путь любой глубины
             if (aggFn === 'countBy') {
-                text = `SELECT ${acc} AS k, count(*)::int AS n\n${fromClause}\nGROUP BY 1 ORDER BY 2 DESC`;
+                text = `SELECT ${acc} AS k, count(*)::int AS n\n${fromClause}${whereOf(tailConds)}\nGROUP BY 1 ORDER BY 2 DESC`;
             }
             else {
                 // sum/avg — всегда numeric; min/max — по типу листа
                 const cast = aggFn === 'sum' || aggFn === 'avg' ? '::numeric' : castOf(leafType(lastCls, path));
-                text = `SELECT ${aggFn}((${acc})${cast}) AS v\n${fromClause}`;
+                text = `SELECT ${aggFn}((${acc})${cast}) AS v\n${fromClause}${whereOf(tailConds)}`;
             }
             break;
         }

package/dist/types.d.ts

@@ -18,6 +18,32 @@ export interface Row {
 }
 /** Результат run(): вариант пути — узел на каждый шаг цепочки. */
 export type Path = Record<string, Row>;
+/**
+ * Конец связи класса (Schema.links v2). В БД элемент text[]: JSON-объект
+ * `{"class":"Org","cardinality":1}` / `{"classes":["Service","Complex"],"cardinality":1}`
+ * (союз ролей); legacy-строка 'Org' — сахар для {classes:['Org']} (старые схемы).
+ */
+export interface LinkEnd {
+    /** Допустимые классы конца; ровно один из них присутствует в Entity.links. */
+    classes: string[];
+    /** Конец может отсутствовать. Default false. */
+    optional?: boolean;
+    /** ЗАРЕЗЕРВИРОВАНО (не имплементировано): 0 — безлимит, N — точное число. Default 1. */
+    cardinality?: number;
+}
+/**
+ * Генерация id класса — из attributes.id:
+ *   "uuid" | {type:'uuid'}                    → v4 (random, дефолт);
+ *   {type:'uuid', generate: 7}                → v7 (время в старших битах);
+ *   {type:'uuid', generate: 5, from: ['Slot','Staff']} → v5: детерминированный id из значений
+ *     from — имена ОБЯЗАТЕЛЬНЫХ концов Schema.links (класс или полное имя союза
+ *     'Service|Complex') и/или скалярных полей data.
+ */
+export interface IdGen {
+    version: 4 | 5 | 7;
+    /** Только v5: источники имени (порядок значим). */
+    from?: string[];
+}
 /** Класс из таблицы Schema. */
 export interface ClassDef {
     id: string;
@@ -27,11 +53,20 @@ export interface ClassDef {
     ancestors: string[];
     /** Все потомки (транзитивно) — считает триггер schema_lineage. */
     descendants: string[];
+    /** Поля data с НАСЛЕДОВАНИЕМ по ancestor-цепочке (потомок поверх предка). */
     attributes: Record<string, unknown>;
-    links: string[];
+    links: LinkEnd[];
+    /**
+     * true — хотя бы один конец объявлен объектом (схема v2): строгая валидация
+     * (жадный матчинг по порядку, союзы, optional, лишние связи — ошибка).
+     * false — все концы legacy-строками: старое поведение ('Entity' = полиморф, лишние молчат).
+     */
+    strictEnds: boolean;
     meta: Record<string, unknown>;
     abstract: boolean;
     order: number;
+    /** Как генерить id новой сущности (attributes.id). */
+    idGen: IdGen;
     /** Скомпилированный fastest-validator: true | ошибки. */
     check: (data: Record<string, unknown>) => true | {
         field: string;
@@ -85,12 +120,13 @@ export interface Cursor {
     id: string;
 }
 /**
- * Операция записи, привязанная к шагу цепочки: .set() / .delete() / .anonymize().
+ * Операция записи, привязанная к шагу цепочки:
+ * .create() / .update() / .delete() / .anonymize().
  * Терминал исполняет план (все операции + финальное чтение) одной транзакцией.
  */
 export interface PlanOp {
-    kind: 'set' | 'delete' | 'anonymize';
-    /** set: данные новой версии (deep-merge листьев). */
+    kind: 'create' | 'update' | 'delete' | 'anonymize';
+    /** create/update: данные новой версии (deep-merge листьев). */
     data?: Record<string, unknown>;
     /** anonymize: string-поля под '[erased]'. */
     fields?: string[];

package/dist/uuid.d.ts

@@ -0,0 +1,6 @@
+/** Namespace letopis для uuidv5 (фиксированная константа — стабильность id между релизами). */
+export declare const LETOPIS_NS = "c7a2f9d4-3b61-4e8a-9f05-8d2c1e6b7a90";
+/** RFC 4122 v5: sha1(namespace + name); детерминирован — одно имя → один uuid. */
+export declare function uuidv5(name: string, ns?: string): string;
+/** RFC 9562 v7: 48 бит unix-ms + random — время в старших битах, вставки ложатся в хвост индекса. */
+export declare function uuidv7(): string;

package/dist/uuid.js

@@ -0,0 +1,32 @@
+/**
+ * Генерация id по Schema (attributes.id):
+ *   "uuid"                                    → v4 (random) — дефолт;
+ *   { type: 'uuid', generate: 7 }             → v7 (unix-время в старших битах: btree-локальность);
+ *   { type: 'uuid', generate: 5, from: […] }  → v5: sha1 от «схема:партиция:класс:значения from» —
+ *     детерминированный id из концов/полей: та же комбинация → тот же id (идемпотентный create,
+ *     дубль невозможен даже в гонке — оба запроса вычислят один id, второй станет версией).
+ */
+import { createHash, randomBytes } from 'node:crypto';
+/** Namespace letopis для uuidv5 (фиксированная константа — стабильность id между релизами). */
+export const LETOPIS_NS = 'c7a2f9d4-3b61-4e8a-9f05-8d2c1e6b7a90';
+const fmt = (b) => {
+    const h = b.toString('hex');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`;
+};
+/** RFC 4122 v5: sha1(namespace + name); детерминирован — одно имя → один uuid. */
+export function uuidv5(name, ns = LETOPIS_NS) {
+    const nsBytes = Buffer.from(ns.replace(/-/g, ''), 'hex');
+    const h = createHash('sha1').update(nsBytes).update(name, 'utf8').digest().subarray(0, 16);
+    h[6] = (h[6] & 0x0f) | 0x50; // version 5
+    h[8] = (h[8] & 0x3f) | 0x80; // variant 10xx
+    return fmt(h);
+}
+/** RFC 9562 v7: 48 бит unix-ms + random — время в старших битах, вставки ложатся в хвост индекса. */
+export function uuidv7() {
+    const b = Buffer.alloc(16);
+    b.writeUIntBE(Date.now(), 0, 6);
+    randomBytes(10).copy(b, 6);
+    b[6] = (b[6] & 0x0f) | 0x70; // version 7
+    b[8] = (b[8] & 0x3f) | 0x80; // variant 10xx
+    return fmt(b);
+}

package/dist/write.d.ts

@@ -31,12 +31,19 @@ export declare function readRows(ctx: Ctx, steps: Step[], mods?: ChainMods): Pro
  */
 export declare function deepMerge(base: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
 /**
- * .set(data):
- *  - пустой фильтр последнего шага и нет data.id → INSERT (links = контекст);
- *  - id (фильтр-строка или data.id) → UPSERT: есть → новая версия (deep-merge), нет → создать;
- *  - фильтр-объект → новая версия каждого найденного (в границах контекста); пусто → [].
+ * .create(data) — «чтобы сущность существовала»:
+ *  - id не задан → INSERT (id по IdGen класса; links = концы из пути + слоты);
+ *  - id известен (Класс(id) / data.id / вычислен v5): есть → новая версия (deep-merge),
+ *    нет → INSERT с этим id (идемпотентный create, REST-PUT семантика);
+ *  - фильтр-объект / pivot — ошибка: create не ищет, это update().
  */
-export declare function setOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>): Promise<Row[]>;
+export declare function createOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>): Promise<Row[]>;
+/**
+ * .update(data?) — новая версия КАЖДОГО найденного путём (deep-merge листьев);
+ * цели: Класс() ≡ Класс({}) — все в границах контекста, id/фильтр/pivot — как в чтении.
+ * Не найдено → [] — update НИКОГДА не создаёт.
+ */
+export declare function updateOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>): Promise<Row[]>;
 /**
  * .anonymize(fields): GDPR-затирание — новая версия с '[erased]' в указанных string-полях
  * + тег 'anonymized'. Только string-поля (по Schema); история сохраняется (см. README).