letopis 2.0.0 → 3.0.1

package/dist/messages/sql-core.js

@@ -14,6 +14,12 @@ export const sqlCore = {
         code: 'acl_denied',
         ru: 'нет права auth.impersonate',
     },
+    // 20-context.sql, ctx(): имперсонация аккаунта, которого нет (не заводили или удалён); id — значение letopis.account
+    'sql-core.impersonation_no_account': {
+        code: 'target_not_found',
+        ru: 'аккаунт {id} не найден',
+        hint: 'id аккаунта — из ответа verifyPassword(), createTenant() или db.auth.tenants(); удалённый аккаунт через as() не вернуть',
+    },
     // 20-context.sql, ctx(): имперсонация System, сервиса или системного администратора не системным администратором
     'sql-core.impersonation_denied': {
         code: 'acl_denied',
@@ -28,6 +34,7 @@ export const sqlCore = {
     'sql-core.bad_api_key': {
         code: 'no_session',
         ru: 'неверный ключ',
+        hint: 'ключ сервиса перевыпускает up({ fresh: true }): возьмите новый serviceKey из ответа up() или задайте свой — up({ serviceKey })',
     },
     // 30-validate.sql, jp_pattern(): pattern JSON Schema не переводится в регулярное выражение PostgreSQL
     'sql-core.pattern_trailing_backslash': {
@@ -105,9 +112,14 @@ export const sqlCore = {
         ru: 'minProperties внутри anyOf не поддерживается (узел {node})',
     },
     // 30-validate.sql, validate_data(): сообщения нарушений issues[].message — тексты не для ошибки (lt_text)
-    'sql-core.issue_string_length': {
+    // minLength, maxLength: limit — граница из описания (длина в символах)
+    'sql-core.issue_string_too_short': {
+        code: 'invalid_data',
+        ru: 'длина строки меньше {limit}',
+    },
+    'sql-core.issue_string_too_long': {
         code: 'invalid_data',
-        ru: 'длина строки вне границ',
+        ru: 'длина строки больше {limit}',
     },
     'sql-core.issue_unique_items': {
         code: 'invalid_data',
@@ -123,7 +135,12 @@ export const sqlCore = {
     },
     'sql-core.issue_enum': {
         code: 'invalid_data',
-        ru: 'значение не из перечисления',
+        ru: 'значение не из перечисления: допустимо {values}',
+    },
+    // лишний ключ объекта (additionalProperties: false); keys — имена лишних ключей через запятую
+    'sql-core.issue_additional': {
+        code: 'invalid_data',
+        ru: 'лишний ключ {keys}',
     },
     'sql-core.issue_rule': {
         code: 'invalid_data',

package/dist/messages/sql-time.d.ts

@@ -15,6 +15,21 @@ export declare const sqlTime: {
         code: "not_deleted";
         ru: string;
     };
+    'sql-time.restore_id_taken': {
+        code: "not_deleted";
+        ru: string;
+        hint: string;
+    };
+    'sql-time.restore_already': {
+        code: "not_deleted";
+        ru: string;
+        hint: string;
+    };
+    'sql-time.restore_stale': {
+        code: "not_deleted";
+        ru: string;
+        hint: string;
+    };
     'sql-time.restore_class_row': {
         code: "invalid_class";
         ru: string;

package/dist/messages/sql-time.js

@@ -19,6 +19,29 @@ export const sqlTime = {
         code: 'not_deleted',
         ru: 'объект не удалён: restore — только для удалённых',
     },
+    // 90-time.sql, restore(): живой объект, за последним надгробием которого — create: id занял новый объект с тем же
+    // ключом; detail — { id, rev }
+    'sql-time.restore_id_taken': {
+        code: 'not_deleted',
+        ru: 'id {id} занят новым объектом с тем же ключом — create по ключу удалённого берёт его id, восстанавливать нечего',
+        hint: 'объект с этим ключом уже живёт: прочитайте его; перед create() по ключу удалённого проверьте db.Класс({ ключ }).withDeleted()',
+    },
+    // 90-time.sql, restore(): живой объект, за последним надгробием которого — restore: уже восстановлен (другой запрос
+    // успел первым); detail — { id, rev }; библиотека отдаёт его как write.restore_already
+    'sql-time.restore_already': {
+        code: 'not_deleted',
+        ru: 'restore: {id} уже восстановлен — объект живой, восстанавливать нечего',
+        hint: 'его вернул другой запрос: прочитайте объект; восстанавливать снова не нужно',
+    },
+    // 90-time.sql, restore(p_id, p_rev): последняя версия id не p_rev, и это не «уже восстановлен» и не «id занят» (удалён
+    // снова, не удалялся, гонка). detail — { id, rev, expected, after, deleted, live }: after — вид записи журнала сразу
+    // за p_rev (в тексте «—», если её нет). Код базы — not_deleted (conflict в каталоге базы нет); библиотека отдаёт его
+    // как write.restore_stale (conflict)
+    'sql-time.restore_stale': {
+        code: 'not_deleted',
+        ru: 'restore: {id} уже не тот, что удаляли — последняя версия {rev}, ожидалась {expected}; после того удаления — {after}',
+        hint: 'объект менялся после показанного удаления (detail.after, detail.deleted, detail.live): вещь уже у другого — сообщить пользователю, а не восстанавливать',
+    },
     // 90-time.sql, restore()
     'sql-time.restore_class_row': {
         code: 'invalid_class',

package/dist/messages/write.d.ts

@@ -140,6 +140,58 @@ export declare const write: {
         code: "not_deleted";
         ru: string;
     };
+    'write.restore_id_taken': {
+        code: "not_deleted";
+        ru: string;
+        hint: string;
+    };
+    'write.restore_already': {
+        code: "not_deleted";
+        ru: string;
+        hint: string;
+    };
+    'write.restore_stale': {
+        code: "conflict";
+        ru: string;
+        hint: string;
+    };
+    'write.partial_without_expect': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'write.bad_expect': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'write.expect_without_confirm': {
+        code: "invalid_query";
+        ru: string;
+    };
+    'write.preview_changed': {
+        code: "conflict";
+        ru: string;
+        hint: string;
+    };
+    'write.delete_restricted': {
+        code: "delete_restricted";
+        ru: string;
+        hint: string;
+    };
+    'write.link_in_data': {
+        code: "invalid_data";
+        ru: string;
+        hint: string;
+    };
+    'write.confirm_without_expect': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
+    'write.restore_without_expect': {
+        code: "invalid_query";
+        ru: string;
+        hint: string;
+    };
     'write.commit_unknown': {
         code: "commit_unknown";
         ru: string;

package/dist/messages/write.js

@@ -62,7 +62,7 @@ export const write = {
     // create() или upsert() на возврате к узлу пути
     'write.create_on_pivot': {
         code: 'invalid_query',
-        ru: '{verb}() на возврате к узлу — он ведёт к существующей сущности, используйте update()',
+        ru: '{verb}() на возврате к узлу — он ведёт к существующему объекту, используйте update()',
     },
     // create() или upsert() после шага с фильтром, а не с id
     'write.create_with_filter': {
@@ -100,7 +100,7 @@ export const write = {
     // слот после глагола, который слотов не принимает
     'write.slot_bad_verb': {
         code: 'invalid_query',
-        ru: 'слот .{role} после {verb}() — слоты у create(), update() и upsert()',
+        ru: 'шаг роли .{role} после {verb}() — шаги ролей бывают только у create(), update() и upsert()',
     },
     // write.ts:slotRole: имя слота — не роль записываемого класса и не класс реестра
     'write.slot_unknown': {
@@ -115,22 +115,22 @@ export const write = {
     // write.ts:slotRole: класс слота принимают несколько ролей
     'write.slot_ambiguous': {
         code: 'invalid_query',
-        ru: 'слот {name} у класса {cls} неоднозначен: роли {roles} — назовите роль',
+        ru: 'шаг {name} у класса {cls} неоднозначен: роли {roles} — назовите роль',
     },
     // конец из пути: шаг подходит нескольким ролям
     'write.end_ambiguous': {
         code: 'invalid_query',
-        ru: 'конец класса {cls} для шага {step} неоднозначен: роли {roles} — назовите шаг ролью или задайте слот',
+        ru: 'конец класса {cls} для шага {step} неоднозначен: роли {roles} — назовите шаг ролью или задайте конец шагом роли после глагола',
     },
     // конец из пути: шаг дал не одну сущность; count — сколько найдено
     'write.end_not_single': {
         code: 'invalid_query',
-        ru: 'шаг {step} должен дать ровно одну сущность для конца {cls} (найдено {count})',
+        ru: 'шаг {step} должен дать ровно один объект для конца {cls} (найдено {count})',
     },
     // слот .роль.set() одиночного конца — значение дало несколько сущностей
     'write.slot_single_many': {
         code: 'invalid_query',
-        ru: 'слот .{role}.set(): конец одиночный, а значение дало {count} сущностей',
+        ru: 'шаг роли .{role}.set(): конец одиночный, а значение дало объектов: {count}',
     },
     // write.ts:existsError: create() — объект уже есть, id не вычислить
     'write.exists': {
@@ -177,6 +177,77 @@ export const write = {
         code: 'not_deleted',
         ru: 'объект не удалён: {verb}() — только для удалённых',
     },
+    // restore() живого объекта, который уже удаляли: за последним надгробием — create (id занял новый объект с тем же
+    // ключом); ids — такие id; detail.ids, с expect — ещё detail.stale (все цели, которые не восстановить, с why)
+    'write.restore_id_taken': {
+        code: 'not_deleted',
+        ru: '{verb}(): id {ids} занят новым объектом с тем же ключом — create() по ключу удалённого берёт его id, восстанавливать нечего; ничего не восстановлено',
+        hint: 'объект с этим ключом уже живёт: прочитайте его (db.Класс(id).first()); перед create() по ключу удалённого проверьте db.Класс({ ключ }).withDeleted(); восстановить остальное — restore({ expect, partial: true })',
+    },
+    // restore() живого объекта, который уже восстановили: за последним надгробием — restore (второй раунд 2.1, A2: другой
+    // запрос успел первым); ids — такие id; detail.ids, с expect — ещё detail.stale
+    'write.restore_already': {
+        code: 'not_deleted',
+        ru: '{verb}(): {ids} уже восстановлены — объекты живые, восстанавливать нечего; ничего не восстановлено',
+        hint: 'их вернул другой запрос: прочитайте их (db.Класс(id).first()); восстановить остальное — restore({ expect, partial: true })',
+    },
+    // restore({ expect }): последняя версия id не та, что в expect, и это не «уже восстановлено» и не «id занят» — удалён
+    // снова, не удалялся, гонка; ничего не восстановлено. ids — такие id; detail.ids — они же, detail.stale — все цели,
+    // которые не восстановить: { id, rev, expected, after, deleted, live, why }
+    'write.restore_stale': {
+        code: 'conflict',
+        ru: 'restore({ expect }): {ids} уже не те, что удаляли — после этого удаления их меняли (что было — err.detail.stale: after, deleted, live); ничего не восстановлено',
+        hint: 'надгробия — из ответа delete() или withDeleted(), их { id, rev } — в expect; расхождение значит, что вещь уже у другого — сообщить пользователю, а не восстанавливать; восстановить то, что можно, — restore({ expect, partial: true })',
+    },
+    // restore({ partial: true }) без expect: пропускать не по чему
+    'write.partial_without_expect': {
+        code: 'invalid_query',
+        ru: 'restore({ partial: true }) — только с { expect }: пропуск считается по показанным надгробиям',
+    },
+    // restore({ expect }), delete({ expect }): expect — не список строк { id, rev }; verb — глагол
+    'write.bad_expect': {
+        code: 'invalid_query',
+        ru: '{verb}({ expect }): expect — список строк { id, rev } (строки ответа; у delete — и строки-сводки предпросмотра как есть)',
+    },
+    // delete({ expect }) без confirm: превью сравнивать не с чем
+    'write.expect_without_confirm': {
+        code: 'invalid_query',
+        ru: 'delete({ expect }) — только с { confirm: true }: без него delete() и есть предпросмотр',
+    },
+    // delete({ confirm: true, expect }): превью в транзакции удаления не совпало с показанным; detail.preview — новое превью
+    'write.preview_changed': {
+        code: 'conflict',
+        ru: 'delete({ confirm: true, expect }): предпросмотр изменился с тех пор, как его показали — ничего не удалено',
+        hint: 'показать пользователю новый предпросмотр (err.detail.preview) и удалить с ним: delete({ confirm: true, expect: err.detail.preview })',
+    },
+    // write.ts, checkRestrict (3.0.1): сверенный предпросмотр delete({ confirm: true, expect }) содержит мешающие строки
+    // (restrict) — видимые или сводку скрытых правами; отказ до удаления. visible — число видимых, others — скрытых;
+    // detail — { rows: [{ id, class }], others }, как у отказа триггера (sql-write.delete_restricted)
+    'write.delete_restricted': {
+        code: 'delete_restricted',
+        ru: 'удалению мешают ссылающиеся строки: видимых {visible}, скрытых правами {others} — ничего не удалено',
+        hint: 'показать пользователю мешающие строки (err.detail.rows); скрытые правами (err.detail.others) видит только их владелец — обратиться к нему; удалить или перевести мешающие строки (или сменить у их конца onDelete) и заново показать предпросмотр delete()',
+    },
+    // write.ts, checkFullData и checkPatchEnds (3.0, вместо api.validation_failed_end): лишний ключ данных — конец класса
+    // (имя роли или класса на конце); keys — такие ключи, role — роль первого из них. Нарушения ValidationError дописывает
+    // к тексту сам
+    'write.link_in_data': {
+        code: 'invalid_data',
+        ru: '{verb}() у {cls}: {keys} — связь, а не поле данных; конец задают путь цепочки или шаг роли после глагола: .{role}.set(id)',
+        hint: 'конец (связь) — не поле данных: путь цепочки (db.Владелец(id).Класс().create(…)) или шаг роли после глагола: db.Класс.create({ … }).Роль.set(id); у конца-списка — .Роль.add(id) / .Роль.remove(id), снять — .Роль.unset()',
+    },
+    // 3.0: delete({ confirm: true }) без expect и без all — удаление не сверено с показанным превью
+    'write.confirm_without_expect': {
+        code: 'invalid_query',
+        ru: 'delete({ confirm: true }) без { expect }: удаление не сверено с предпросмотром, который видел пользователь — ничего не удалено',
+        hint: 'передайте expect из предпросмотра: const p = await db.Класс(id).delete().rows(); показать p пользователю; await db.Класс(id).delete({ confirm: true, expect: p }).rows(). Осознанно удалить текущий состав без сверки — delete({ confirm: true, all: true })',
+    },
+    // 3.0: restore() без expect и без all — и для явных id: последнее надгробие могло смениться с тех пор, как его видели
+    'write.restore_without_expect': {
+        code: 'invalid_query',
+        ru: 'restore() без { expect }: восстановление не сверено с надгробиями, которые видел пользователь — ничего не восстановлено',
+        hint: 'передайте expect — надгробия из ответа delete() или из db.Класс(id).withDeleted().rows(): restore({ expect }); восстановить то, что можно, — restore({ expect, partial: true }); осознанно вернуть все удалённые цели шага без сверки — restore({ all: true })',
+    },
     // tx.ts — tx.ts:commitUnknown: связь оборвалась во время commit
     'write.commit_unknown': {
         code: 'commit_unknown',

package/dist/model.d.ts

@@ -29,7 +29,11 @@ type TargetName<T> = T extends string ? T : T extends {
 type MinRequired<O> = O extends {
     min: infer N;
 } ? (N extends 0 | undefined ? false : number extends N ? boolean : true) : false;
-/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. `T` — имена классов целей (только для типов). */
+/**
+ * Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. Параметры типа: `Many` — конец-список, `Required` —
+ * обязателен, `T` — имена классов целей (только для типов). `min`, `max`, `onDeleteRule`, `metaData` необязательны:
+ * не заданы — `undefined`.
+ */
 export declare class End<Many extends boolean = boolean, Required extends boolean = boolean, T extends string = string> {
     readonly targets: readonly Target[];
     readonly many: Many;
@@ -38,7 +42,7 @@ export declare class End<Many extends boolean = boolean, Required extends boolea
     readonly max?: number;
     readonly onDeleteRule?: OnDelete;
     readonly metaData?: Record<string, unknown>;
-    /** Только для вывода типов: имена классов целей — строгие переходы и слоты цепочек (план 2.0, этап 4, п. 1). */
+    /** Только для вывода типов: имена классов целей — строгие переходы и шаги ролей цепочек. */
     readonly __targets?: T;
     constructor(targets: readonly Target[], opts: {
         many: Many;
@@ -210,7 +214,11 @@ type ModelOf<N extends string, D, S extends z.ZodRawShape> = Model<N, DataOf<Ext
  */
 export declare function hub<N extends string, S extends z.ZodRawShape, const O extends ClassOpts>(name: N, shape: S, opts: O): ModelOf<N, O, S>;
 export declare function hub<N extends string, const D extends ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>>(name: N, def?: D): ModelOf<N, D, ShapeOf<D['fields']>>;
+/** Короткая форма без опций: hub('Имя', { поле: z… }) — поля класса (полная форма { fields: z.object(…) } — выше). */
+export declare function hub<N extends string, S extends z.ZodRawShape>(name: N, shape: S): ModelOf<N, {}, S>;
 /** Связь — отношение между объектами со своими данными (бронь, навык). */
 export declare function link<N extends string, S extends z.ZodRawShape, const O extends ClassOpts>(name: N, shape: S, opts: O): ModelOf<N, O, S>;
 export declare function link<N extends string, const D extends ClassDef<z.ZodRawShape, EndsInput, AnyModel | undefined>>(name: N, def?: D): ModelOf<N, D, ShapeOf<D['fields']>>;
+/** Короткая форма без опций: link('Имя', { поле: z… }) — поля класса (полная форма { fields: z.object(…) } — выше). */
+export declare function link<N extends string, S extends z.ZodRawShape>(name: N, shape: S): ModelOf<N, {}, S>;
 export { normalizeSchema, translatePattern, type JsonSchema } from './jsonschema.js';

package/dist/model.js

@@ -14,7 +14,11 @@ import { z } from 'zod';
 import { lerr } from './errors.js';
 import { normalizeSchema } from './jsonschema.js';
 import { RESERVED_CLASS_NAMES } from './types.js';
-/** Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. `T` — имена классов целей (только для типов). */
+/**
+ * Конец класса: `one(X)`, `one(A, B)`, `many(X, { min, max })`. Параметры типа: `Many` — конец-список, `Required` —
+ * обязателен, `T` — имена классов целей (только для типов). `min`, `max`, `onDeleteRule`, `metaData` необязательны:
+ * не заданы — `undefined`.
+ */
 export class End {
     targets;
     many;
@@ -73,14 +77,17 @@ const DEF_KEYS = new Set(['alias', 'extends', 'abstract', 'ends', 'fields', 'key
 function isZod(v) {
     return typeof v === 'object' && v !== null && '_zod' in v;
 }
-/** Пути правил refine/superRefine в схеме Zod — их нет в JSON Schema. */
+/**
+ * Пути правил Zod, которых нет в JSON Schema: refine/superRefine (`refine`) и преобразования — `overwrite` (`.trim()`,
+ * `.toLowerCase()`, `.toUpperCase()`, `.normalize()` …) и `transform` (`.transform()`, `z.preprocess()`, `.pipe()`).
+ * Преобразования база и валидатор letopis не исполняют: их syncModels отклоняет (план 2.1, A11).
+ */
 function collectLost(schema, path, out) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const def = schema._zod.def;
-    for (const c of def.checks ?? []) {
-        if (c?._zod?.def?.check === 'custom')
-            out.push({ path, kind: 'refine' });
-    }
+    collectChecks(schema, path, out);
+    if (def.type === 'transform')
+        out.push({ path, kind: 'transform' });
     if (def.type === 'object')
         for (const [k, v] of Object.entries(def.shape))
             collectLost(v, `${path}.${k}`, out);
@@ -95,6 +102,17 @@ function collectLost(schema, path, out) {
     if (def.innerType)
         collectLost(def.innerType, path, out);
 }
+/** Проверки самой схемы (без вложенных): refine/superRefine/check — `refine`, `overwrite` — преобразование. */
+function collectChecks(schema, path, out) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    for (const c of schema._zod.def.checks ?? []) {
+        const check = c?._zod?.def?.check;
+        if (check === 'custom')
+            out.push({ path, kind: 'refine' });
+        else if (check === 'overwrite')
+            out.push({ path, kind: 'overwrite' });
+    }
+}
 function makeModel(kind, name, defArg, optsArg) {
     if (!NAME.test(name))
         throw lerr('model.class_name_invalid', { name });
@@ -222,6 +240,10 @@ function makeModel(kind, name, defArg, optsArg) {
         },
         lostRules() {
             const out = [];
+            // проверки z.object(…).refine/superRefine/check — на уровне объекта (между полями): в описание класса идёт
+            // только shape, поэтому они тоже потеряны — путь — имя класса
+            if (fields instanceof z.ZodObject)
+                collectChecks(fields, name, out);
             for (const [k, v] of Object.entries(ownShape))
                 collectLost(v, `${name}.${k}`, out);
             return out;

package/dist/registry.d.ts

@@ -41,6 +41,12 @@ interface ClassRow {
         resolved: Record<string, unknown>;
     };
 }
+/**
+ * Реестр классов сессии — `db.registry`: описания классов арендатора и системных классов, как их видит подключение.
+ * Методы: `has(имя)` — есть ли класс или алиас; `find(имя)` — описание `ClassInfo` или `undefined`; `resolve(имя)` — то же,
+ * а неизвестное имя — `invalid_class`; `all()` — все классы; `family(имя)` — класс и его потомки; `leafType(класс, путь)` —
+ * тип поля по пути в данных; `load(строки)` — заменить содержимое (его зовёт само подключение, `db.refresh()`).
+ */
 export declare class Registry {
     private byName;
     private byAlias;

package/dist/registry.js

@@ -5,6 +5,12 @@
  */
 import { lerr } from './errors.js';
 import { compileValidator } from './validate.js';
+/**
+ * Реестр классов сессии — `db.registry`: описания классов арендатора и системных классов, как их видит подключение.
+ * Методы: `has(имя)` — есть ли класс или алиас; `find(имя)` — описание `ClassInfo` или `undefined`; `resolve(имя)` — то же,
+ * а неизвестное имя — `invalid_class`; `all()` — все классы; `family(имя)` — класс и его потомки; `leafType(класс, путь)` —
+ * тип поля по пути в данных; `load(строки)` — заменить содержимое (его зовёт само подключение, `db.refresh()`).
+ */
 export class Registry {
     byName = new Map();
     byAlias = new Map();

package/dist/sql.d.ts

@@ -18,6 +18,8 @@ export interface Step {
     tagsFilter?: unknown;
     ownerFilter?: string;
     deepMax?: number;
+    /** withDeleted(): узел шага — живые и надгробия удалённых (модификатор шага, план 2.1, A9). */
+    withDeleted?: true;
     /** Звено плана записи (этап 4): глагол на этом шаге; построитель чтения его не видит. */
     op?: import('./write.js').PlanOp;
     /** Модификаторы цепочки на момент глагола: limit и sort сужают цели записи. */