letopis 0.5.0

package/dist/chain.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Dot-цепочки: db.Сотрудник({name:'Вася'}).навык().Услуга().execute()
+ * db и цепочка — Proxy над реестром классов (id и alias работают одинаково).
+ *
+ * Выборка настраивается модификаторами: .limit(n) .offset(n) .sort(field, dir?)
+ * Колонки — модификаторами: .tags(…) .account(…) .owner(…); ключ путей — .alias(…).
+ * Запись: .set(data) — связи задаются контекст-шагами цепочки; .delete().
+ */
+import type { Row, Path, Filter } from './types.js';
+import { type Ctx } from './sql.js';
+import { type BatchOp } from './write.js';
+import { type Tables } from './tables.js';
+import type { Registry } from './schema.js';
+export interface ChainCore {
+    /** Пути: [{шаг1: Row, шаг2: Row, …}, …] — все узлы каждого варианта. */
+    execute(): Promise<Path[]>;
+    /** Уникальные сущности последнего шага. */
+    rows(): Promise<Row[]>;
+    first(): Promise<Row | null>;
+    ids(): Promise<string[]>;
+    count(): Promise<number>;
+    /** Максимум строк/путей. */
+    limit(n: number): Chain;
+    /** Пропустить N. */
+    offset(n: number): Chain;
+    /** Сортировка по полю последнего шага: 'updated' | 'data.<поле>' (каст по типу из Schema). */
+    sort(field: string, dir?: 'asc' | 'desc' | boolean): Chain;
+    /** Чтение «как было на момент T» (ISO-строка или Date): версии позже T невидимы. */
+    asOf(t: string | Date): Chain;
+    /** Keyset-пагинация: строго после курсора (см. cursorOf). Требует .sort(). */
+    after(cursor: import('./types.js').Cursor): Chain;
+    /** ВСЕ версии сущностей последнего шага (включая tombstone → $deleted), по возрастанию updated. */
+    versions(): Promise<Row[]>;
+    /** Рекурсивный self-обход: дети любой глубины (тот же класс), $depth в Row. */
+    deep(max?: number): Chain;
+    /** Агрегации по полю последнего шага ('data.<путь>'), считает БД. */
+    sum(field: string): Promise<number | null>;
+    avg(field: string): Promise<number | null>;
+    min(field: string): Promise<unknown>;
+    max(field: string): Promise<unknown>;
+    countBy(field: string): Promise<Record<string, number>>;
+    /** GDPR: новая версия с затёртыми string-полями ('[erased]') + тег 'anonymized'. История остаётся (см. README). */
+    anonymize(fields: string[]): Promise<Row[]>;
+    /** Переименовать ключ ТЕКУЩЕГО шага в выводе путей. */
+    alias(name: string): Chain;
+    /** Колонка tags: строка | string[] (все) | has/hasAny/hasAll. В set() — значение тегов. */
+    tags(v: string | string[] | object): Chain;
+    /** Колонка account (uuid или Row/Account). В set()-insert — значение. */
+    account(v: string | {
+        id: string;
+    }): Chain;
+    /** Колонка owner (uuid или Row/Account). В set()-insert — значение. */
+    owner(v: string | {
+        id: string;
+    }): Chain;
+    /**
+     * Записать. Связи — контекст-шагами до set() И/ИЛИ класс-вызовами после:
+     *   await db.Сотрудник(s).занятость(id).set({kind}).Окно(w)
+     *   const z = db.занятость(id).set({kind}); z.Сотрудник(s); z.Окно(w); await z
+     * Исполняется ОДНИМ INSERT при первом await (промис кешируется).
+     * Пустой фильтр без data.id → INSERT; id (фильтр или data.id) → UPSERT;
+     * фильтр-объект → версия каждого найденного.
+     */
+    set(data?: Record<string, unknown>): SetChain;
+    /** Серверный tombstone + каскад; возвращает всё удалённое с $deleted: true. */
+    delete(): Promise<Row[]>;
+}
+/** Ленивый билдер записи: довешивание связей + thenable (исполнение при await). */
+export type SetChain = PromiseLike<Row[]> & {
+    [className: string]: (target: string | {
+        id: string;
+    }) => SetChain;
+};
+export type Chain = ChainCore & {
+    [className: string]: (filter?: Filter) => Chain;
+};
+export interface DbCore {
+    /** Открыть транзакцию: tr — тот же API + commit/rollback/lock. */
+    begin(): Promise<EntityTx>;
+    commit(tr: EntityTx): Promise<void>;
+    rollback(tr: EntityTx): Promise<void>;
+    /** Именованный батч: те же цепочки, set/delete копятся до execute(). */
+    batch(name: string): Batch;
+    /**
+     * Realtime: события каждой вставленной версии (insert/update/delete-tombstone).
+     * watch(cb) — все классы; watch('Запись', cb) — один. Возврат — stop-функция.
+     */
+    watch(classOrCb: string | ((e: WatchEvent) => void), cb?: (e: WatchEvent) => void): Promise<() => void>;
+    close(): Promise<void>;
+    registry: Registry;
+    /** Голый postgres-клиент (тесты, EXPLAIN). */
+    sql: Ctx['sql'];
+    /** Служебные таблицы auth/ACL (обычные, вне версий/цепочек). */
+    accounts: Tables['accounts'];
+    credentials: Tables['credentials'];
+    resources: Tables['resources'];
+    rules: Tables['rules'];
+}
+export type EntityDb = DbCore & {
+    [className: string]: (filter?: Filter) => Chain;
+};
+export type EntityTx = EntityDb & {
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+    lock(...keys: (string | number)[]): Promise<void>;
+};
+/** Событие watch(): факт новой версии; данные дочитываются запросом при надобности. */
+export interface WatchEvent {
+    partition: string;
+    class: string;
+    id: string;
+    updated: string;
+    deleted: boolean;
+}
+export type Batch = {
+    execute(): Promise<Row[][]>;
+    discard(): void;
+    size(): number;
+} & {
+    [className: string]: (filter?: Filter) => Chain;
+};
+interface RootState {
+    batches: Map<string, BatchOp[]>;
+}
+export declare function makeDb(ctx: Ctx, root?: RootState): EntityDb;
+export {};

package/dist/chain.js

@@ -0,0 +1,278 @@
+import { buildRead, runQuery } from './sql.js';
+import { setOp, delOp, anonymizeOp, executeBatch, toRow } from './write.js';
+import { beginTx, lock } from './tx.js';
+import { makeTables } from './tables.js';
+/** Фильтр-аргумент принимает и Row/Account-объект — берётся его id. */
+function normalizeFilter(f) {
+    if (f !== undefined &&
+        typeof f === 'object' &&
+        !Array.isArray(f) &&
+        typeof f.id === 'string' &&
+        (typeof f.class === 'string' || 'categories' in f)) {
+        return f.id;
+    }
+    return f;
+}
+const clsOf = (steps) => steps.map((s) => s.cls.id);
+async function runPaths(ctx, steps, mods) {
+    const q = buildRead(ctx, steps, mods, 'paths');
+    const res = await runQuery(ctx, q.text, q.params, 'paths', clsOf(steps));
+    return res.map((r) => {
+        const out = {};
+        for (const [k, v] of Object.entries(r.path))
+            out[k] = toRow(v);
+        return out;
+    });
+}
+async function runRows(ctx, steps, mods) {
+    const q = buildRead(ctx, steps, mods, 'rows');
+    const res = await runQuery(ctx, q.text, q.params, 'rows', clsOf(steps));
+    return res.map((r) => {
+        const row = toRow(r.row);
+        const d = r.row.depth;
+        return d != null ? { ...row, $depth: d } : row;
+    });
+}
+const idOf = (t) => (typeof t === 'object' ? t.id : t);
+/**
+ * Ленивый билдер set(): класс-вызовы довешивают связи (мутирует), await исполняет один раз.
+ * run() — исполнение (сразу setOp или отложенно через батч); links — общая ссылка,
+ * которую батч читает на execute().
+ */
+function makeSetChain(registry, links, run) {
+    let done;
+    const handler = {
+        get(_t, prop) {
+            if (typeof prop === 'symbol')
+                return undefined;
+            if (prop === 'then' || prop === 'catch' || prop === 'finally') {
+                done ??= run();
+                const m = done[prop];
+                return m.bind(done);
+            }
+            if (registry.has(prop)) {
+                const cls = registry.resolve(prop);
+                return (target) => {
+                    if (done)
+                        throw new Error(`letopis: set() already executed — link "${prop}" before the first await`);
+                    links[cls.id] = idOf(target);
+                    return proxy;
+                };
+            }
+            registry.resolve(prop);
+            return undefined;
+        },
+    };
+    const proxy = new Proxy({}, handler);
+    return proxy;
+}
+function makeChain(ctx, steps, mods, batchQueue) {
+    const withLast = (patch) => {
+        const next = steps.slice();
+        next[next.length - 1] = { ...next[next.length - 1], ...patch };
+        return makeChain(ctx, next, mods, batchQueue);
+    };
+    const withMods = (patch) => makeChain(ctx, steps, { ...mods, ...patch }, batchQueue);
+    const handler = {
+        get(_t, prop) {
+            if (typeof prop === 'symbol' || prop === 'then')
+                return undefined;
+            switch (prop) {
+                case 'execute':
+                    return () => runPaths(ctx, steps, mods);
+                case 'rows':
+                    return () => runRows(ctx, steps, mods);
+                case 'first':
+                    return async () => (await runRows(ctx, steps, { ...mods, limit: 1 }))[0] ?? null;
+                case 'ids':
+                    return async () => {
+                        const q = buildRead(ctx, steps, mods, 'ids');
+                        const res = await runQuery(ctx, q.text, q.params, 'ids', clsOf(steps));
+                        return res.map((r) => r.id);
+                    };
+                case 'count':
+                    return async () => {
+                        const q = buildRead(ctx, steps, mods, 'count');
+                        const res = await runQuery(ctx, q.text, q.params, 'count', clsOf(steps));
+                        return res[0].n;
+                    };
+                case 'limit':
+                    return (n) => withMods({ limit: n });
+                case 'offset':
+                    return (n) => withMods({ offset: n });
+                case 'sort':
+                    return (field, dir) => withMods({ order: field, desc: dir === true || dir === 'desc' });
+                case 'asOf':
+                    return (t) => withMods({ asOf: t instanceof Date ? t.toISOString() : t });
+                case 'deep':
+                    return (max = 32) => withLast({ deepMax: max });
+                case 'sum':
+                case 'avg':
+                case 'min':
+                case 'max':
+                    return async (field) => {
+                        const q = buildRead(ctx, steps, { ...mods, aggFn: prop, aggField: field }, 'agg');
+                        const res = await runQuery(ctx, q.text, q.params, 'agg', clsOf(steps));
+                        const v = res[0]?.v;
+                        return v === null || v === undefined ? null : typeof v === 'string' && prop !== 'min' && prop !== 'max' ? Number(v) : v;
+                    };
+                case 'countBy':
+                    return async (field) => {
+                        const q = buildRead(ctx, steps, { ...mods, aggFn: 'countBy', aggField: field }, 'agg');
+                        const res = await runQuery(ctx, q.text, q.params, 'agg', clsOf(steps));
+                        return Object.fromEntries(res.map((r) => [r.k ?? 'null', r.n]));
+                    };
+                case 'after':
+                    return (cursor) => withMods({ after: cursor });
+                case 'versions':
+                    return async () => {
+                        const q = buildRead(ctx, steps, mods, 'versions');
+                        const res = await runQuery(ctx, q.text, q.params, 'versions', clsOf(steps));
+                        return res.map((r) => {
+                            const raw = r.row;
+                            const row = toRow(r.row);
+                            return raw.deleted ? { ...row, $deleted: true } : row;
+                        });
+                    };
+                case 'anonymize':
+                    return (fields) => anonymizeOp(ctx, steps, mods, fields);
+                case 'alias':
+                    return (name) => withLast({ aliasKey: name });
+                case 'tags':
+                    return (v) => withLast({ tagsFilter: v });
+                case 'account':
+                    return (v) => withLast({ accountFilter: typeof v === 'object' ? v.id : v });
+                case 'owner':
+                    return (v) => withLast({ ownerFilter: typeof v === 'object' ? v.id : v });
+                case 'set':
+                    return (data = {}) => {
+                        const extraLinks = {};
+                        if (batchQueue) {
+                            const op = { kind: 'set', steps, mods, data, extraLinks };
+                            batchQueue.push(op);
+                            const index = batchQueue.length - 1;
+                            // билдер для довешивания связей; await возвращает № в очереди
+                            return makeSetChain(ctx.registry, extraLinks, async () => index);
+                        }
+                        return makeSetChain(ctx.registry, extraLinks, () => setOp(ctx, steps, mods, data, extraLinks));
+                    };
+                case 'delete':
+                    return () => {
+                        if (batchQueue) {
+                            batchQueue.push({ kind: 'delete', steps, mods });
+                            return batchQueue.length - 1;
+                        }
+                        return delOp(ctx, steps, mods);
+                    };
+            }
+            if (ctx.registry.has(prop)) {
+                const cls = ctx.registry.resolve(prop);
+                return (filter) => makeChain(ctx, [...steps, { name: prop, cls, filter: normalizeFilter(filter) }], mods, batchQueue);
+            }
+            ctx.registry.resolve(prop); // неизвестный класс — понятная ошибка со списком
+            return undefined;
+        },
+    };
+    return new Proxy({}, handler);
+}
+function makeBatch(ctx, queue) {
+    const handler = {
+        get(_t, prop) {
+            if (typeof prop === 'symbol' || prop === 'then')
+                return undefined;
+            switch (prop) {
+                case 'execute':
+                    return async () => {
+                        const ops = queue.splice(0, queue.length);
+                        return executeBatch(ctx, ops);
+                    };
+                case 'discard':
+                    return () => void queue.splice(0, queue.length);
+                case 'size':
+                    return () => queue.length;
+            }
+            if (ctx.registry.has(prop)) {
+                const cls = ctx.registry.resolve(prop);
+                return (filter) => makeChain(ctx, [{ name: String(prop), cls, filter: normalizeFilter(filter) }], {}, queue);
+            }
+            ctx.registry.resolve(prop);
+            return undefined;
+        },
+    };
+    return new Proxy({}, handler);
+}
+export function makeDb(ctx, root) {
+    const state = root ?? { batches: new Map() };
+    let tables; // лениво, на ctx этого фасада (работает и в tr)
+    const handler = {
+        get(_t, prop) {
+            if (typeof prop === 'symbol' || prop === 'then')
+                return undefined;
+            if (prop === 'accounts' || prop === 'credentials' || prop === 'resources' || prop === 'rules') {
+                tables ??= makeTables(ctx);
+                return tables[prop];
+            }
+            switch (prop) {
+                case 'begin':
+                    return async () => makeDb(await beginTx(ctx), state);
+                case 'commit':
+                    return (tr) => {
+                        if (tr)
+                            return tr.commit();
+                        const c = ctx;
+                        if (typeof c.commit === 'function')
+                            return c.commit();
+                        throw new Error('letopis: commit() needs a transaction: db.commit(tr) or tr.commit()');
+                    };
+                case 'rollback':
+                    return (tr) => {
+                        if (tr)
+                            return tr.rollback();
+                        const c = ctx;
+                        if (typeof c.rollback === 'function')
+                            return c.rollback();
+                        throw new Error('letopis: rollback() needs a transaction: db.rollback(tr) or tr.rollback()');
+                    };
+                case 'lock':
+                    return (...keys) => lock(ctx, ...keys);
+                case 'batch':
+                    return (name) => {
+                        let q = state.batches.get(name);
+                        if (!q) {
+                            q = [];
+                            state.batches.set(name, q);
+                        }
+                        return makeBatch(ctx, q);
+                    };
+                case 'watch':
+                    return async (a, b) => {
+                        const cls = typeof a === 'string' ? ctx.registry.resolve(a).id : undefined;
+                        const cb = typeof a === 'function' ? a : b;
+                        const listener = (payload) => {
+                            const e = JSON.parse(payload);
+                            if (e.partition !== ctx.partition)
+                                return;
+                            if (cls && e.class !== cls)
+                                return;
+                            cb(e);
+                        };
+                        const { unlisten } = await ctx.sql.listen(ctx.pgSchema, listener);
+                        return unlisten;
+                    };
+                case 'close':
+                    return () => ctx.sql.end();
+                case 'registry':
+                    return ctx.registry;
+                case 'sql':
+                    return ctx.sql;
+            }
+            if (ctx.registry.has(prop)) {
+                const cls = ctx.registry.resolve(prop);
+                return (filter) => makeChain(ctx, [{ name: String(prop), cls, filter: normalizeFilter(filter) }], {});
+            }
+            ctx.registry.resolve(prop);
+            return undefined;
+        },
+    };
+    return new Proxy({}, handler);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { type EntityDb } from './chain.js';
+import type { ConnectOpts } from './types.js';
+export declare function connect(opts: ConnectOpts): Promise<EntityDb>;
+/** Курсор keyset-пагинации из последней строки страницы (field как в .sort()). */
+export declare function cursorOf(row: import('./types.js').Row, field?: string): import('./types.js').Cursor;
+export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, } from './ops.js';
+export type { Row, Path, Filter, ChainMods, Cursor, ConnectOpts, QueryEvent, Account, Credential, Resource, Rule, } from './types.js';
+export type { EntityDb, EntityTx, Chain, Batch } from './chain.js';
+export type { Tables, AccountsApi, CredentialsApi, ResourcesApi, RulesApi } from './tables.js';
+export { ValidationError } from './write.js';
+export { Registry } from './schema.js';

package/dist/index.js

@@ -0,0 +1,43 @@
+/**
+ * letopis: dot-цепочки над append-only Entity-хранилищем (TimescaleDB).
+ *
+ *   const db = await connect({ dsn, schema: 'booking' })
+ *   await db.Сотрудник({ name: 'Вася' }).навык().Услуга().execute()
+ */
+import postgres from 'postgres';
+import { loadRegistry } from './schema.js';
+import { makeDb } from './chain.js';
+export async function connect(opts) {
+    // timestamptz — строкой (JS Date режет микросекунды → ломал бы asOf/cursorOf по updated)
+    const sql = postgres(opts.dsn, {
+        max: opts.max ?? 10,
+        types: { timestamptz: { to: 1184, from: [1184], serialize: (v) => v, parse: (v) => v } },
+    });
+    const partition = opts.partition ?? 'entity';
+    const registry = await loadRegistry(sql, opts.schema, partition);
+    // Entity.account NOT NULL: fallback — System-аккаунт (семантика legacy-движка)
+    const ident = `"${opts.schema.replace(/"/g, '""')}"`;
+    const sys = (await sql.unsafe(`SELECT id FROM ${ident}."Account" WHERE 'System' = ANY(categories) LIMIT 1`));
+    const ctx = {
+        sql,
+        registry,
+        pgSchema: opts.schema,
+        partition,
+        account: opts.account,
+        owner: opts.owner,
+        systemAccount: sys[0]?.id,
+        enforceAccount: opts.enforceAccount,
+        onQuery: opts.onQuery,
+        slowMs: opts.slowMs,
+    };
+    return makeDb(ctx);
+}
+/** Курсор keyset-пагинации из последней строки страницы (field как в .sort()). */
+export function cursorOf(row, field = 'updated') {
+    const v = field === 'updated' ? row.updated : row.data[field.slice(5)];
+    return { v, id: row.id };
+}
+// операторы фильтров
+export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, } from './ops.js';
+export { ValidationError } from './write.js';
+export { Registry } from './schema.js';

package/dist/ops.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Операторы фильтров. Symbol-tagged объекты — не пересекаются с данными.
+ * Касты по типам полей делает sql.ts на основе Schema.attributes.
+ */
+import { type Op, type Scalar } from './types.js';
+export declare const isOp: (v: unknown) => v is Op;
+/** ≠ (IS DISTINCT FROM) */
+export declare const ne: (v: Scalar) => Op;
+/** > */
+export declare const gt: (v: Scalar) => Op;
+/** ≥ */
+export declare const gte: (v: Scalar) => Op;
+/** < */
+export declare const lt: (v: Scalar) => Op;
+/** ≤ */
+export declare const lte: (v: Scalar) => Op;
+/** a ≤ x ≤ b */
+export declare const between: (a: Scalar, b: Scalar) => Op;
+/** значение из списка */
+export declare const inList: (vs: Scalar[]) => Op;
+/** LIKE (шаблон с % и _) */
+export declare const like: (s: string) => Op;
+/** ILIKE (без регистра) */
+export declare const ilike: (s: string) => Op;
+/** начинается с */
+export declare const starts: (s: string) => Op;
+/** заканчивается на */
+export declare const ends: (s: string) => Op;
+/** массив-поле содержит значение */
+export declare const has: (v: Scalar) => Op;
+/** массив-поле содержит хотя бы одно из */
+export declare const hasAny: (vs: Scalar[]) => Op;
+/** массив-поле содержит все */
+export declare const hasAll: (vs: Scalar[]) => Op;
+/** поле присутствует (true) / отсутствует (false) в data */
+export declare const exists: (yes?: boolean) => Op;
+/** поле NULL или отсутствует */
+export declare const isNull: () => Op;
+/** НЕ-условие по полю: not(ilike('%тест%')); скаляр → «не равно» */
+export declare const not: (v: Scalar | Op) => Op;
+/** ИЛИ на уровне фильтра шага: db.Запись(or({status:'created'}, {status:'confirmed'})) */
+export declare const or: (...filters: Record<string, unknown>[]) => Op;

package/dist/ops.js

@@ -0,0 +1,43 @@
+/**
+ * Операторы фильтров. Symbol-tagged объекты — не пересекаются с данными.
+ * Касты по типам полей делает sql.ts на основе Schema.attributes.
+ */
+import { OP } from './types.js';
+const op = (name, ...args) => ({ [OP]: name, args });
+export const isOp = (v) => typeof v === 'object' && v !== null && OP in v;
+/** ≠ (IS DISTINCT FROM) */
+export const ne = (v) => op('ne', v);
+/** > */
+export const gt = (v) => op('gt', v);
+/** ≥ */
+export const gte = (v) => op('gte', v);
+/** < */
+export const lt = (v) => op('lt', v);
+/** ≤ */
+export const lte = (v) => op('lte', v);
+/** a ≤ x ≤ b */
+export const between = (a, b) => op('between', a, b);
+/** значение из списка */
+export const inList = (vs) => op('in', vs);
+/** LIKE (шаблон с % и _) */
+export const like = (s) => op('like', s);
+/** ILIKE (без регистра) */
+export const ilike = (s) => op('ilike', s);
+/** начинается с */
+export const starts = (s) => op('like', s + '%');
+/** заканчивается на */
+export const ends = (s) => op('like', '%' + s);
+/** массив-поле содержит значение */
+export const has = (v) => op('has', v);
+/** массив-поле содержит хотя бы одно из */
+export const hasAny = (vs) => op('hasAny', vs);
+/** массив-поле содержит все */
+export const hasAll = (vs) => op('hasAll', vs);
+/** поле присутствует (true) / отсутствует (false) в data */
+export const exists = (yes = true) => op('exists', yes);
+/** поле NULL или отсутствует */
+export const isNull = () => op('isNull');
+/** НЕ-условие по полю: not(ilike('%тест%')); скаляр → «не равно» */
+export const not = (v) => op('not', v);
+/** ИЛИ на уровне фильтра шага: db.Запись(or({status:'created'}, {status:'confirmed'})) */
+export const or = (...filters) => op('or', filters);

package/dist/schema.d.ts

@@ -0,0 +1,15 @@
+import type { Sql } from 'postgres';
+import type { ClassDef, FieldType } from './types.js';
+export declare class Registry {
+    private byName;
+    readonly all: ClassDef[];
+    add(def: ClassDef): void;
+    /** Класс по id или alias; undefined если нет. */
+    find(name: string): ClassDef | undefined;
+    /** Класс по id или alias; иначе понятная ошибка со списком. */
+    resolve(name: string): ClassDef;
+    has(name: string): boolean;
+}
+/** Тип поля из fastest-validator DSL — для каста в SQL. */
+export declare function fieldTypeOf(attr: unknown): FieldType;
+export declare function loadRegistry(sql: Sql, pgSchema: string, partition: string): Promise<Registry>;