letopis 0.5.0

package/dist/tables.js

@@ -0,0 +1,148 @@
+const T = (ctx, name) => `"${ctx.pgSchema.replace(/"/g, '""')}"."${name}"`;
+/** WHERE из простых equality-условий (+спец-обработчики). */
+function where(conds, params) {
+    if (!conds.length)
+        return '';
+    const parts = conds.map((c) => {
+        params.push(c.value);
+        return c.text(params.length);
+    });
+    return ' WHERE ' + parts.join(' AND ');
+}
+const eq = (col) => (n) => `"${col}" = $${n}`;
+// ---------------------------------------------------------------------------
+export function makeTables(ctx) {
+    const run = (text, params) => ctx.sql.unsafe(text, params);
+    const accounts = {
+        async find(f = {}) {
+            const conds = [];
+            if (f.id !== undefined)
+                conds.push({ text: eq('id'), value: f.id });
+            if (f.enabled !== undefined)
+                conds.push({ text: eq('enabled'), value: f.enabled });
+            if (f.category !== undefined)
+                conds.push({ text: (n) => `$${n} = ANY(categories)`, value: f.category });
+            const params = [];
+            return run(`SELECT * FROM ${T(ctx, 'Account')}${where(conds, params)} ORDER BY created`, params);
+        },
+        async get(id) {
+            return (await run(`SELECT * FROM ${T(ctx, 'Account')} WHERE id = $1`, [id]))[0] ?? null;
+        },
+        async set(a) {
+            if (a.id) {
+                const sets = ['updated = now()'];
+                const params = [];
+                for (const col of ['categories', 'data', 'meta', 'avatar', 'enabled']) {
+                    if (a[col] !== undefined) {
+                        params.push(a[col]);
+                        sets.push(`"${col}" = $${params.length}`);
+                    }
+                }
+                params.push(a.id);
+                const rows = await run(`UPDATE ${T(ctx, 'Account')} SET ${sets.join(', ')} WHERE id = $${params.length} RETURNING *`, params);
+                if (!rows[0])
+                    throw new Error(`letopis: account "${a.id}" not found`);
+                return rows[0];
+            }
+            const cols = [];
+            const params = [];
+            for (const col of ['categories', 'data', 'meta', 'avatar', 'enabled']) {
+                if (a[col] !== undefined) {
+                    params.push(a[col]);
+                    cols.push(`"${col}"`);
+                }
+            }
+            const ph = params.map((_, i) => `$${i + 1}`).join(', ');
+            const rows = await run(cols.length
+                ? `INSERT INTO ${T(ctx, 'Account')} (${cols.join(', ')}) VALUES (${ph}) RETURNING *`
+                : `INSERT INTO ${T(ctx, 'Account')} DEFAULT VALUES RETURNING *`, params);
+            return rows[0];
+        },
+        async delete(id) {
+            const rows = await run(`DELETE FROM ${T(ctx, 'Account')} WHERE id = $1 RETURNING id`, [id]);
+            return rows.length > 0;
+        },
+    };
+    const credentials = {
+        async find(f = {}) {
+            const conds = [];
+            if (f.id !== undefined)
+                conds.push({ text: eq('id'), value: f.id });
+            if (f.account !== undefined)
+                conds.push({ text: eq('account'), value: f.account });
+            if (f.category !== undefined)
+                conds.push({ text: eq('category'), value: f.category });
+            if (f.identifier !== undefined)
+                conds.push({ text: eq('identifier'), value: f.identifier });
+            if (f.confirmed !== undefined)
+                conds.push({ text: eq('confirmed'), value: f.confirmed });
+            const params = [];
+            let sql = `SELECT * FROM ${T(ctx, 'Credential')}${where(conds, params)}`;
+            if (!f.withDeleted)
+                sql += conds.length ? ' AND deleted IS NULL' : ' WHERE deleted IS NULL';
+            return run(sql + ' ORDER BY created', params);
+        },
+        async set(c) {
+            const rows = await run(`INSERT INTO ${T(ctx, 'Credential')} (account, category, identifier, meta, confirmed)
+         VALUES ($1, $2, $3, $4, $5)
+         ON CONFLICT (account, category, identifier) DO UPDATE
+           SET meta = EXCLUDED.meta, confirmed = EXCLUDED.confirmed, updated = now(), deleted = NULL
+         RETURNING *`, [c.account, c.category, c.identifier, c.meta ?? {}, c.confirmed ?? true]);
+            return rows[0];
+        },
+        async delete(id) {
+            const rows = await run(`UPDATE ${T(ctx, 'Credential')} SET deleted = now(), updated = now() WHERE id = $1 AND deleted IS NULL RETURNING id`, [id]);
+            return rows.length > 0;
+        },
+    };
+    const resources = {
+        async find(f = {}) {
+            const conds = [];
+            if (f.category !== undefined)
+                conds.push({ text: eq('category'), value: f.category });
+            const params = [];
+            return run(`SELECT * FROM ${T(ctx, 'Resource')}${where(conds, params)} ORDER BY alias`, params);
+        },
+        async get(alias) {
+            return (await run(`SELECT * FROM ${T(ctx, 'Resource')} WHERE alias = $1`, [alias]))[0] ?? null;
+        },
+        async set(r) {
+            const rows = await run(`INSERT INTO ${T(ctx, 'Resource')} (alias, category, pattern, meta) VALUES ($1, $2, $3, $4)
+         ON CONFLICT (alias) DO UPDATE SET category = EXCLUDED.category, pattern = EXCLUDED.pattern, meta = EXCLUDED.meta
+         RETURNING *`, [r.alias, r.category, r.pattern ?? null, r.meta ?? null]);
+            return rows[0];
+        },
+        async delete(alias) {
+            const rows = await run(`DELETE FROM ${T(ctx, 'Resource')} WHERE alias = $1 RETURNING alias`, [alias]);
+            return rows.length > 0;
+        },
+    };
+    const rules = {
+        async find(f = {}) {
+            const conds = [];
+            if (f.account !== undefined)
+                conds.push({ text: eq('account'), value: f.account });
+            if (f.resource !== undefined)
+                conds.push({ text: eq('resource'), value: f.resource });
+            if (f.permission !== undefined)
+                conds.push({ text: eq('permission'), value: f.permission });
+            if (f.enabled !== undefined)
+                conds.push({ text: eq('enabled'), value: f.enabled });
+            const params = [];
+            return run(`SELECT * FROM ${T(ctx, 'Rule')}${where(conds, params)} ORDER BY weight DESC NULLS LAST`, params);
+        },
+        async set(r) {
+            const rows = await run(`INSERT INTO ${T(ctx, 'Rule')} (account, resource, permission, weight, meta, enabled)
+         VALUES ($1, $2, $3, $4, $5, $6)
+         ON CONFLICT (account, resource) DO UPDATE
+           SET permission = EXCLUDED.permission, weight = EXCLUDED.weight, meta = EXCLUDED.meta, enabled = EXCLUDED.enabled
+         RETURNING *`, [r.account, r.resource, r.permission, r.weight ?? null, r.meta ?? null, r.enabled ?? true]);
+            return rows[0];
+        },
+        async delete(account, resource) {
+            const rows = await run(`DELETE FROM ${T(ctx, 'Rule')} WHERE account = $1 AND resource = $2 RETURNING account`, [account, resource]);
+            return rows.length > 0;
+        },
+    };
+    return { accounts, credentials, resources, rules };
+}

package/dist/tx.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Транзакции: db.begin() → tr (тот же API на выделенном соединении),
+ * db.commit(tr) / db.rollback(tr) / tr.commit() / tr.rollback().
+ * tr.lock(...) — pg_advisory_xact_lock (сериализация гонок, напр. двойная бронь).
+ */
+import type { Ctx } from './sql.js';
+export interface TxCtx extends Ctx {
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}
+export declare function beginTx(ctx: Ctx): Promise<TxCtx>;
+/** Advisory-lock на составной ключ; живёт до конца транзакции. */
+export declare function lock(ctx: Ctx, ...keys: (string | number)[]): Promise<void>;

package/dist/tx.js

@@ -0,0 +1,31 @@
+export async function beginTx(ctx) {
+    const reserved = await ctx.sql.reserve();
+    const r = reserved;
+    await r.unsafe('BEGIN');
+    let done = false;
+    const finish = async (cmd) => {
+        if (done)
+            return;
+        done = true;
+        try {
+            await r.unsafe(cmd);
+        }
+        finally {
+            r.release();
+        }
+    };
+    return {
+        ...ctx,
+        sql: reserved,
+        inTx: true,
+        commit: () => finish('COMMIT'),
+        rollback: () => finish('ROLLBACK'),
+    };
+}
+/** Advisory-lock на составной ключ; живёт до конца транзакции. */
+export async function lock(ctx, ...keys) {
+    if (!ctx.inTx) {
+        throw new Error('letopis: lock() works only inside db.begin() transaction (pg_advisory_xact_lock)');
+    }
+    await ctx.sql.unsafe('SELECT pg_advisory_xact_lock(hashtextextended($1, 0))', [keys.join('|')]);
+}

package/dist/types.d.ts

@@ -0,0 +1,166 @@
+/**
+ * letopis: типы.
+ */
+/** Строка Entity (актуальная версия), как отдаёт либа. account/owner — NOT NULL. */
+export interface Row {
+    id: string;
+    class: string;
+    data: Record<string, unknown>;
+    links: Record<string, string>;
+    tags: string[];
+    account: string;
+    owner: string;
+    updated: string;
+    /** true у строк, возвращённых .delete() (цели + каскад) и tombstone-версий в .versions(). */
+    $deleted?: true;
+    /** Глубина узла при .deep()-обходе (1 = прямой ребёнок). */
+    $depth?: number;
+}
+/** Результат execute(): вариант пути — узел на каждый шаг цепочки. */
+export type Path = Record<string, Row>;
+/** Класс из таблицы Schema. */
+export interface ClassDef {
+    id: string;
+    alias: string;
+    category: 'HUB' | 'LINK';
+    ancestor: string | null;
+    ancestors: string[];
+    /** Все потомки (транзитивно) — считает триггер schema_lineage. */
+    descendants: string[];
+    attributes: Record<string, unknown>;
+    links: string[];
+    meta: Record<string, unknown>;
+    abstract: boolean;
+    order: number;
+    /** Скомпилированный fastest-validator: true | ошибки. */
+    check: (data: Record<string, unknown>) => true | {
+        field: string;
+        message?: string;
+    }[];
+    /** Тип каждого поля attributes — для SQL-кастов в фильтрах. */
+    fieldTypes: Map<string, FieldType>;
+}
+export type FieldType = {
+    kind: 'number';
+} | {
+    kind: 'date';
+} | {
+    kind: 'boolean';
+} | {
+    kind: 'string';
+} | {
+    kind: 'array';
+} | {
+    kind: 'record';
+    value: FieldType;
+} | {
+    kind: 'any';
+};
+/** Метка операторов фильтра (Symbol — не конфликтует с данными). */
+export declare const OP: unique symbol;
+export interface Op {
+    [OP]: string;
+    args: unknown[];
+}
+export type Scalar = string | number | boolean | null;
+/** Значение фильтра по полю: скаляр (eq), оператор или вложенный record-объект. */
+export type FieldFilter = Scalar | Scalar[] | Op | {
+    [key: string]: Scalar | Op;
+};
+/**
+ * Фильтр шага:
+ *  - строка / массив строк — id;
+ *  - объект: { поле data: значение (eq) | оператор | вложенный record-путь } + ключ id.
+ * Колонки tags/account/owner фильтруются модификаторами цепочки .tags()/.account()/.owner().
+ */
+export type Filter = string | string[] | Op | {
+    [field: string]: FieldFilter | undefined;
+};
+/** Курсор keyset-пагинации: значение поля сортировки + id последней строки страницы. */
+export interface Cursor {
+    v: string | number;
+    id: string;
+}
+/** Модификаторы выборки цепочки: .limit() / .offset() / .sort() / .asOf() / .after(). */
+export interface ChainMods {
+    limit?: number;
+    offset?: number;
+    /** 'updated' | 'data.<поле>' (каст по типу поля последнего шага). */
+    order?: string;
+    desc?: boolean;
+    /** Чтение «как было на момент T»: ISO-строка или Date. */
+    asOf?: string;
+    /** Keyset-пагинация от курсора (требует sort). */
+    after?: Cursor;
+    /** Внутреннее: агрегация терминалов .sum/.avg/.min/.max/.countBy. */
+    aggFn?: 'sum' | 'avg' | 'min' | 'max' | 'countBy';
+    aggField?: string;
+}
+export interface Account {
+    id: string;
+    categories: string[];
+    data: Record<string, unknown>;
+    meta: Record<string, unknown>;
+    avatar: string;
+    enabled: boolean;
+    created: string;
+    updated: string;
+}
+export interface Credential {
+    id: string;
+    account: string;
+    category: string;
+    identifier: string;
+    meta: Record<string, unknown>;
+    confirmed: boolean;
+    created: string;
+    updated: string;
+    deleted: string | null;
+}
+export interface Resource {
+    alias: string;
+    category: string;
+    pattern: Record<string, unknown> | null;
+    meta: Record<string, unknown> | null;
+}
+export interface Rule {
+    account: string;
+    resource: string;
+    permission: string;
+    weight: number | null;
+    meta: Record<string, unknown> | null;
+    enabled: boolean;
+}
+/** Событие хука onQuery: один SQL-запрос цепочки (чтение или запись). */
+export interface QueryEvent {
+    /** Режим чтения или write-операция. */
+    mode: 'paths' | 'rows' | 'ids' | 'count' | 'versions' | 'agg' | 'insert' | 'delete';
+    /** Классы шагов цепочки (id из Schema). */
+    classes: string[];
+    /** Длительность, мс. */
+    ms: number;
+    /** Число строк результата. */
+    rows: number;
+    /** true при ms > slowMs (если slowMs задан). */
+    slow: boolean;
+}
+export interface ConnectOpts {
+    /** postgres://user:pass@host:port/db */
+    dsn: string;
+    /** PG-схема с таблицами Entity/Schema (напр. 'booking'). */
+    schema: string;
+    /** Партиция данных. Default 'entity'. */
+    partition?: string;
+    /** Дефолтный account для записей. */
+    account?: string;
+    /** Дефолтный owner для записей. Default = account. */
+    owner?: string;
+    /** Размер пула соединений. Default 10. */
+    max?: number;
+    /** Жёсткая изоляция арендатора: чтения фильтруются по account, записи пришпилены к нему. */
+    enforceAccount?: boolean;
+    /** Хук на каждый запрос цепочки (метрики, лог). */
+    onQuery?: (e: QueryEvent) => void;
+    /** Порог «медленного» запроса, мс: событие получает slow: true; без onQuery — console.warn. */
+    slowMs?: number;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * letopis: типы.
+ */
+/** Метка операторов фильтра (Symbol — не конфликтует с данными). */
+export const OP = Symbol('letopis.op');

package/dist/write.d.ts

@@ -0,0 +1,60 @@
+import type { Row, ChainMods } from './types.js';
+import { type Ctx, type Step } from './sql.js';
+export declare class ValidationError extends Error {
+    issues: {
+        field: string;
+        message?: string;
+    }[];
+    constructor(cls: string, issues: {
+        field: string;
+        message?: string;
+    }[]);
+}
+interface RawRow {
+    partition: string;
+    id: string;
+    class: string;
+    data: Record<string, unknown>;
+    links: Record<string, string> | null;
+    tags: string[] | null;
+    account: string;
+    owner: string;
+    updated: string | Date;
+    deleted: string | Date | null;
+}
+export declare function toRow(r: RawRow): Row;
+/** Прочитать актуальные строки по цепочке. */
+export declare function readRows(ctx: Ctx, steps: Step[], mods?: ChainMods): Promise<Row[]>;
+/**
+ * Deep-merge патча в базу: меняются ТОЛЬКО указанные листья.
+ * Вложенные plain-объекты сливаются рекурсивно; массивы/скаляры/null — заменяются.
+ */
+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), нет → создать;
+ *  - фильтр-объект → новая версия каждого найденного (в границах контекста); пусто → [].
+ */
+export declare function setOp(ctx: Ctx, steps: Step[], mods: ChainMods, data: Record<string, unknown>, extraLinks?: Record<string, string>): Promise<Row[]>;
+/**
+ * .anonymize(fields): GDPR-затирание — новая версия с '[erased]' в указанных string-полях
+ * + тег 'anonymized'. Только string-поля (по Schema); история сохраняется (см. README).
+ */
+export declare function anonymizeOp(ctx: Ctx, steps: Step[], mods: ChainMods, fields: string[]): Promise<Row[]>;
+/**
+ * .delete(): цели = фильтр последнего шага + контекст-связи; серверное удаление.
+ * Триггер entity_delete: tombstone + рекурсивный каскад (+advisory-lock).
+ * Возвращает ВСЁ удалённое (цели + каскад) с $deleted: true.
+ */
+export declare function delOp(ctx: Ctx, steps: Step[], mods: ChainMods): Promise<Row[]>;
+export interface BatchOp {
+    kind: 'set' | 'delete';
+    steps: Step[];
+    mods: ChainMods;
+    data?: Record<string, unknown>;
+    /** Связи, довешенные после set() (мутируется билдером до execute()). */
+    extraLinks?: Record<string, string>;
+}
+export declare function executeBatch(ctx: Ctx, queue: BatchOp[]): Promise<Row[][]>;
+export {};