letopis 0.13.0 → 0.18.0

package/dist/up.js

@@ -5,6 +5,34 @@
  *
  *   const db = await up({ schema: 'booking', version: 1 });   // → PG-схема "v1.booking"
  */
+// FILE: lib/src/up.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Dev-bootstrap — поднять Docker-контейнер Postgres (TimescaleDB) + Redis, обеспечить базу, накатить DDL-схему и сиды, дождаться готовности и подключиться.
+//   SCOPE: валидация схемы/версии; проба postgres; docker build/run/start контейнера; создание базы; ожидание готовности PG и Redis; применение схемы + сиды; connect
+//   DEPENDS: M-CONNECT, M-CHAIN, M-TYPES
+//   LINKS: M-UP, V-M-UP
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   UpOpts - опции up(): dsn, schema, version, контейнер/образ, dataDir, seeds, fresh, quiet, таймаут
+//   dockerRunArgs - чистая сборка argv для `docker run` (bind/volume, trust/пароль)
+//   RunCfg - конфиг запуска контейнера (порты, креды, база, dataDir)
+//   up - точка входа: контейнер -> база -> схема -> готовность -> connect (возвращает EntityDb)
+//   docker - (local) обёртка execFile над docker CLI (ENOENT -> понятная ошибка)
+//   ensureContainer - (local) reuse/start/build+run dev-контейнера
+//   pgPing - (local) проба postgres: ok | no-server | no-database | starting | fatal
+//   ensureDatabase - (local) создать базу, если её нет (гонка 42P04 глушится)
+//   tcpAlive - (local) TCP-проба хоста:порта (для redis)
+//   applySchema - (local) drop (fresh) -> накат ddl+сидов с подстановкой <SCHEMA-NAME>
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
+//
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { setTimeout as sleep } from 'node:timers/promises';
@@ -19,6 +47,13 @@ const DEFAULT_DSN = 'postgres://postgres:test@localhost:15432/letopis';
 const qi = (s) => `"${s.replace(/"/g, '""')}"`;
 const pkgPath = (rel) => fileURLToPath(new URL(rel, import.meta.url));
 /** argv для docker run (чистая функция — покрыта юнитом). dataDir: путь → bind, имя → volume. */
+// START_CONTRACT: dockerRunArgs
+//   PURPOSE: Чистая функция — собирает argv для `docker run` dev-контейнера (порты PG/Redis, том данных, режим trust либо пароль).
+//   INPUTS: { cfg: RunCfg - контейнер/образ, порты, креды, база, dataDir (путь -> bind, имя -> volume) }
+//   OUTPUTS: { string[] - аргументы командной строки docker run }
+//   SIDE_EFFECTS: none
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: dockerRunArgs
 export function dockerRunArgs(cfg) {
     const args = ['run', '-d', '--name', cfg.container,
         '-p', `${cfg.pgPort}:5432`, '-p', `${cfg.redisPort}:6379`,
@@ -42,6 +77,13 @@ async function docker(args) {
         return { ok: false, out: (x.stdout ?? '').trim(), err: (x.stderr || x.message || '').trim() };
     }
 }
+// START_CONTRACT: ensureContainer
+//   PURPOSE: Гарантирует запущенный dev-контейнер — reuse запущенного, start остановленного, иначе build образа (если нет) и run.
+//   INPUTS: { cfg: RunCfg - параметры контейнера/образа/портов; log: (m: string) => void - прогресс }
+//   OUTPUTS: { Promise<void> }
+//   SIDE_EFFECTS: вызывает docker inspect/start/build/run через execFile; бросает при неудаче start/build/run
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: ensureContainer
 async function ensureContainer(cfg, log) {
     const st = await docker(['container', 'inspect', '--format', '{{.State.Running}}', cfg.container]);
     if (st.ok && st.out === 'true') {
@@ -68,6 +110,13 @@ async function ensureContainer(cfg, log) {
         throw new Error(`letopis.up: docker run ${cfg.container} failed: ${r.err}`);
     log(`container ${cfg.container} created (data: ${cfg.dataDir ?? 'volume letopis-pgdata'})`);
 }
+// START_CONTRACT: pgPing
+//   PURPOSE: Одноразовая проба postgres по dsn — классифицирует ответ: ok, no-database (3D000), starting (57P03), fatal (28P01/28000), no-server.
+//   INPUTS: { dsn: string - строка подключения }
+//   OUTPUTS: { Promise<Ping> - { ok: true } | { ok: false, kind, err } }
+//   SIDE_EFFECTS: открывает и закрывает разовое соединение postgres (max 1, connect_timeout 3)
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: pgPing
 async function pgPing(dsn) {
     const sql = postgres(dsn, { max: 1, connect_timeout: 3, onnotice: () => { } });
     try {
@@ -88,6 +137,13 @@ async function pgPing(dsn) {
         await sql.end({ timeout: 1 }).catch(() => { });
     }
 }
+// START_CONTRACT: ensureDatabase
+//   PURPOSE: Создаёт целевую базу, если её ещё нет — подключаясь к служебной базе postgres (гонку параллельных up() 42P04 глушит).
+//   INPUTS: { url: URL - разобранный dsn (имя базы из pathname/username); log: (m: string) => void }
+//   OUTPUTS: { Promise<void> }
+//   SIDE_EFFECTS: подключается к базе postgres, выполняет CREATE DATABASE; закрывает соединение
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: ensureDatabase
 async function ensureDatabase(url, log) {
     const dbName = decodeURIComponent(url.pathname.slice(1)) || url.username || 'postgres';
     const admin = new URL(url);
@@ -107,6 +163,13 @@ async function ensureDatabase(url, log) {
         await sql.end();
     }
 }
+// START_CONTRACT: tcpAlive
+//   PURPOSE: TCP-проба доступности хоста:порта (готовность Redis) с таймаутом 2 с.
+//   INPUTS: { host: string; port: number }
+//   OUTPUTS: { Promise<boolean> - true если соединение установилось }
+//   SIDE_EFFECTS: открывает и сразу закрывает TCP-сокет
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: tcpAlive
 function tcpAlive(host, port) {
     return new Promise((res) => {
         const s = net.connect({ host, port });
@@ -116,6 +179,13 @@ function tcpAlive(host, port) {
         s.setTimeout(2000, () => done(false));
     });
 }
+// START_CONTRACT: applySchema
+//   PURPOSE: Применяет DDL-схему и сиды — при fresh дропает схему; если схемы нет, накатывает ddl.sql (+ дефолтные booking/auth или свои сиды), подставляя <SCHEMA-NAME>.
+//   INPUTS: { dsn: string; full: string - полное имя схемы v<N>.<schema>; seeds: string[] | false | undefined - свои пути / false (без сидов) / undefined (дефолт); fresh: boolean; log: (m: string) => void }
+//   OUTPUTS: { Promise<void> }
+//   SIDE_EFFECTS: читает sql-файлы; выполняет DROP/накат схемы в postgres; закрывает соединение
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: applySchema
 async function applySchema(dsn, full, seeds, fresh, log) {
     const sql = postgres(dsn, { max: 1, onnotice: () => { } });
     try {
@@ -143,6 +213,13 @@ async function applySchema(dsn, full, seeds, fresh, log) {
         await sql.end();
     }
 }
+// START_CONTRACT: up
+//   PURPOSE: Единая точка входа dev-bootstrap — валидирует схему/версию, при живом postgres пропускает docker (иначе поднимает контейнер и ждёт готовности PG+Redis), применяет схему и подключается.
+//   INPUTS: { opts: UpOpts - dsn, schema, version, контейнер/образ, dataDir, redisPort, seeds, fresh, quiet, waitTimeoutMs + прочие ConnectOpts }
+//   OUTPUTS: { Promise<EntityDb> - подключённый фасад на схеме "v<version>.<schema>" }
+//   SIDE_EFFECTS: shell docker через M-UP.ensureContainer; TCP-пинги; чтение sql и накат схемы; console.log с префиксом [letopis.up]; connect (M-CONNECT); бросает при плохом имени схемы/версии и таймауте готовности
+//   LINKS: M-UP, V-M-UP
+// END_CONTRACT: up
 export async function up(opts) {
     const { dsn = DEFAULT_DSN, schema, version, container = 'letopis-timescale', image = 'letopis-db', dataDir, redisPort = 16379, seeds, fresh, quiet, waitTimeoutMs = 120_000, ...connectRest } = opts;
     if (!/^[a-zA-Z_][a-zA-Z0-9_$]*$/.test(schema))
@@ -166,6 +243,7 @@ export async function up(opts) {
         throw ping.err;
     }
     else {
+        // START_BLOCK_ENSURE_CONTAINER
         if (local) {
             await ensureContainer({
                 container, image, pgPort: url.port || '5432', redisPort,
@@ -176,6 +254,8 @@ export async function up(opts) {
         else {
             log(`waiting for remote postgres at ${host} (no docker for non-local dsn)…`);
         }
+        // END_BLOCK_ENSURE_CONTAINER
+        // START_BLOCK_WAIT_READY
         const t0 = Date.now();
         for (;;) {
             ping = await pgPing(dsn);
@@ -201,9 +281,12 @@ export async function up(opts) {
             }
             log(`redis ready on ${redisPort}`);
         }
+        // END_BLOCK_WAIT_READY
     }
+    // START_BLOCK_APPLY_SCHEMA
     await applySchema(dsn, full, seeds, fresh ?? false, log);
     const db = await connect({ ...connectRest, dsn, schema: full });
     log(`connected (schema "${full}")`);
+    // END_BLOCK_APPLY_SCHEMA
     return db;
 }

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,68 @@
+/**
+ * Генерация 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, второй станет версией).
+ */
+//
+// FILE: lib/src/uuid.ts
+// VERSION: 1.0.0
+// START_MODULE_CONTRACT
+//   PURPOSE: Детерминированная (v5) и упорядоченная по времени (v7) генерация UUID для id сущностей.
+//   SCOPE: namespace-константа LETOPIS_NS, форматирование 16 байт в каноничный UUID, v5 (sha1 от namespace+name), v7 (unix-ms в старших битах + random).
+//   DEPENDS: none
+//   LINKS: M-UUID, V-M-UUID
+//   ROLE: RUNTIME
+//   MAP_MODE: EXPORTS
+// END_MODULE_CONTRACT
+//
+// START_MODULE_MAP
+//   LETOPIS_NS - фиксированный namespace letopis для uuidv5 (стабильность id между релизами).
+//   fmt - (локальная) форматирует 16-байтный Buffer в каноничную строку UUID 8-4-4-4-12.
+//   uuidv5 - RFC 4122 v5: детерминированный uuid = sha1(namespace + name).
+//   uuidv7 - RFC 9562 v7: 48 бит unix-ms в старших битах + random.
+// END_MODULE_MAP
+//
+// START_CHANGE_SUMMARY
+//   LAST_CHANGE: [v1.0.0 - Documented existing module: reverse-engineered contract + markup]
+// END_CHANGE_SUMMARY
+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)}`;
+};
+// START_CONTRACT: uuidv5
+//   PURPOSE: Детерминированный UUID v5 из имени и namespace (одно имя → один uuid).
+//   INPUTS: { name: string - имя (склеенные значения from класса), ns: string - namespace (default LETOPIS_NS) }
+//   OUTPUTS: { string - каноничный UUID v5 (version=5, variant=10xx) }
+//   SIDE_EFFECTS: none (чистая функция — только хэширование входа)
+//   LINKS: M-UUID, V-M-UUID
+// END_CONTRACT: uuidv5
+/** 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);
+}
+// START_CONTRACT: uuidv7
+//   PURPOSE: Упорядоченный по времени UUID v7 — 48 бит unix-ms в старших битах + random.
+//   INPUTS: { none }
+//   OUTPUTS: { string - каноничный UUID v7 (version=7, variant=10xx) }
+//   SIDE_EFFECTS: недетерминирован — читает Date.now() и криптослучайные байты (randomBytes)
+//   LINKS: M-UUID, V-M-UUID
+// END_CONTRACT: uuidv7
+/** 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).