letopis 0.20.3 → 1.0.0

package/dist/index.d.ts

@@ -1,29 +1,175 @@
 /**
- * letopis: dot-цепочки над append-only Entity-хранилищем (TimescaleDB).
+ * letopis 1.0 — основная точка входа пакета. Руководство — README.md пакета, машинный каталог API —
+ * docs/api-contract.json репозитория; решения и их причины — reports/PLAN-LETOPIS-1.0.md (этапы ниже).
  *
- * schema — ПОЛНОЕ имя PG-схемы С версией движка ("v1.booking"); префикс либа НЕ достраивает
- * (создаёт up({ schema: 'booking', version: 1 }) либо db/apply.mjs). Шаг цепочки — id ИЛИ
- * alias класса из таблицы Schema (db.Staff ≡ db.Мастер).
- *
- *   const db = await connect({ dsn, schema: 'v1.booking' })   // безличный пул
- *   const t  = await db.as(accountId)                          // арендатор ВЫЗОВА
- *   await t.Мастер({ name: 'Вася' }).навык().Услуга().run()
+ * Этап 2: connect() — подключение под сессией, реестр классов, отложенный сигнал, db.sql.
+ * Этап 3: цепочки чтения t.Класс(…).Связь().rows(); этап 4 — запись цепочками и загрузчик.
+ * Этап 5: db.auth (креды, вход, сессии), db.acl, db.as(аккаунт, { tenant }) — имперсонация.
+ * Этап 6: история (restore, purge, rekey, trimHistory), verify, maintain, reset, watch, кэш результатов.
  */
-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 { up } from './up.js';
-export type { UpOpts } from './up.js';
-export { uuidv5, uuidv7, LETOPIS_NS } from './uuid.js';
-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, AclOp, AclDecision, } from './types.js';
-export type { EntityDb, EntityTx, Chain, Batch, WatchEvent, WatchOpts } from './chain.js';
-export type { Tables, AccountsApi, CredentialsApi, ResourcesApi, RulesApi, SchemaApi } from './tables.js';
-export { totpCode } from './auth.js';
-export type { AuthApi, AuthResult } from './auth.js';
-export type { AclApi } from './acl.js';
-export type { SessionStore, Sessions, Session } from './sessions.js';
-export { ValidationError } from './write.js';
-export { Registry } from './schema.js';
+import postgres from 'postgres';
+import { Registry } from './registry.js';
+import { type Tx } from './tx.js';
+import { type AuthApi } from './auth.js';
+import { type AclApi } from './acl.js';
+import { type LoadInput, type LoadOptions, type LoadReport } from './load.js';
+import { type Batch, type Chain, type StepFn } from './chain.js';
+import type { QueryEvent, Row } from './types.js';
+import { type CacheOptions, type CacheStats } from './cache.js';
+import { Subscription, type WatchOptions } from './watch.js';
+import { type MaintainOptions, type MaintainReport, type ModelDescription, type ResetOptions, type ResetResult, type VerifyResult } from './admin.js';
+import type { AnyModelLike, StepsOf } from './typed.js';
+export { DDL_REVISION } from './types.js';
+export { uuidv5, v5Name, v5Id, idOf, type KeyedClass } from './uuid.js';
+export { LetopisError, ValidationError, fromDbError, type Issue } from './errors.js';
+export { Registry, type ClassInfo, type EndInfo, type LeafType } from './registry.js';
+export { compileValidator, applyDefaults, type Validator } from './validate.js';
+export { syncModels, generateTypes, schemaToTs, type SyncResult } from './sync.js';
+export { ne, gt, gte, lt, lte, between, inList, like, ilike, starts, ends, has, hasAny, hasAll, exists, isNull, not, or, isOp } from './ops.js';
+export { cursorOf } from './sql.js';
+export { inc, isInc, type IncMarker, type WriteRow } from './write.js';
+export { totpCode, hashPassword, verifyHash, type AuthApi, type LoginResult, type Credential } from './auth.js';
+export type { AclApi, AclDecision, AclDataDecision, AclOp } from './acl.js';
+export type { LoadOptions, LoadReport, LoadIssue, LoadInput } from './load.js';
+export type { Chain, ChainCore, StepFn, BatchEntry } from './chain.js';
+export type { ModelLike, AnyModelLike, RowOf, FilterOf, FieldFilterOf, TypedChain, StepsOf, PatchOf } from './typed.js';
+export type { Row, Path, Filter, FieldFilter, Cursor, ChainMods, QueryEvent, Op, Scalar } from './types.js';
+export type { CacheOptions, CacheStats } from './cache.js';
+export type { WatchOptions, WatchEvent, Subscription } from './watch.js';
+export type { VerifyResult, VerifyIssue, MaintainOptions, MaintainReport, ResetOptions, ResetResult, ModelDescription } from './admin.js';
+export { describeText } from './admin.js';
+export { up, createTenant, type UpOptions, type UpResult, type HistoryPolicy, type TenantOptions, type TenantResult } from './up.js';
+export { RESERVED_CLASS_NAMES, CHAIN_METHODS, DB_METHODS } from './types.js';
+/** Снесено в 1.0.0: id v7 больше не выдаются (§2.3). */
+export declare function uuidv7(): never;
+/** Снесено в 1.0.0: пространство имён v5 — id арендатора. Любое использование значения — ошибка. */
+export declare const LETOPIS_NS: string;
+export interface ConnectOptions {
+    /** Строка подключения; либо готовый пул postgres.js в `sql`. */
+    dsn?: string;
+    sql?: postgres.Sql;
+    /** Схема установки, например `v2.salon`. */
+    schema: string;
+    /** Токен сессии; либо ключ APIKEY в `apiKey` (он же `service` — ключ сервиса) — его обменяют на сессию. */
+    token?: string;
+    apiKey?: string;
+    service?: string;
+    /** Продлевать сессию раз в минуту работы (по умолчанию да, §2.9). */
+    refreshSession?: boolean;
+    /** Разрешить роль, которая обходит RLS (суперпользователь, BYPASSRLS, член роли-владельца), — администраторское подключение (§2.9). */
+    allowBypassRls?: boolean;
+    /** Имя роли-владельца (по умолчанию letopis_owner). */
+    owner?: string;
+    /** Интервал отправки отложенного сигнала, мс (по умолчанию 100; решение 9 точки А). */
+    notifyIntervalMs?: number;
+    /** Размер пула, если подключение создаёт сам connect(). */
+    max?: number;
+    /** Хук на каждый запрос цепочки (метрики, лог). */
+    onQuery?: (e: QueryEvent) => void;
+    /** Порог медленного запроса, мс: событие получает slow; без onQuery — console.warn. */
+    slowMs?: number;
+    /** Модели letopis/model — только для типов цепочек (TypedDb); описания классов берутся из базы. */
+    models?: readonly AnyModelLike[];
+    /**
+     * Слушать сигналы базы (LISTEN, по умолчанию да). false — пул в режиме транзакций (PgBouncer):
+     * реестр перечитывается через db.refresh(), подписка опрашивает журнал, кэш результатов выключен
+     * (с cache: { ttlOnly: true } — работает только по сроку).
+     */
+    listen?: boolean;
+    /** Кэш результатов (§2.12): срок по умолчанию, размер, ttlOnly; false — выключен. */
+    cache?: CacheOptions | false;
+    /** Запускать maintain() по расписанию ('1h', '15m', мс) под advisory-блокировкой: работает один процесс. */
+    maintain?: string | number;
+}
+export interface DbCore {
+    readonly schema: string;
+    readonly token: string | null;
+    /** Арендатор сессии. */
+    readonly tenant: string | null;
+    readonly registry: Registry;
+    /** Креды, вход и сессии (этап 5). */
+    readonly auth: AuthApi;
+    /** Решения прав: check(endpoint), checkData(class, op) (этап 5). */
+    readonly acl: AclApi;
+    /** Сырой SQL под сессией и RLS, одной транзакцией (в db.begin() — в ней): db.sql`select …`. */
+    sql(strings: TemplateStringsArray, ...values: unknown[]): Promise<postgres.Row[]>;
+    /** Транзакция под сессией: fn получает соединение postgres.js (в db.begin() — ту же транзакцию). */
+    transaction<T>(fn: (tx: Tx) => Promise<T>): Promise<T>;
+    /** id объекта класса с ключом в арендаторе сессии. */
+    idOf(cls: string, key: Readonly<Record<string, unknown>>): string;
+    /** Перечитать описания классов. */
+    refresh(): Promise<void>;
+    /** Отправить накопленные сигналы сейчас. */
+    flushSignals(): Promise<void>;
+    /**
+     * Проверка цепочек хэшей и якорь (хэш всех голов); { data: true } — ещё данные, концы, арендаторы,
+     * владельцы и id всех строк. Только системный администратор или администраторское подключение.
+     */
+    verify(opts?: {
+        data?: boolean;
+    }): Promise<VerifyResult>;
+    /** Обслуживание: истёкшие сессии и коды, прореживание журнала по политике хранения, очередь сигналов. */
+    maintain(opts?: MaintainOptions): Promise<MaintainReport>;
+    /** Сброс sessions | tenant | all (allowReset установки, право letopis.reset, confirm — имя схемы). */
+    reset(opts: ResetOptions): Promise<ResetResult>;
+    /** Обрезка истории до момента: класса (с потомками), id, списка id или строк; версия 1 → запись trim. */
+    trimHistory(target: string | string[] | Row | Row[], before: string | Date): Promise<number>;
+    /** Новый ключ класса: строки семейства переносятся на новые id, ссылки переводятся. */
+    rekeyClass(cls: string, key: string[]): Promise<number>;
+    /** Машинное описание модели с метаданными классов (describeText — то же текстом, llms.txt). */
+    describe(): ModelDescription;
+    /** Подписка по курсору: for await (const ev of db.watch({ from })) …; ev.cursor — откуда продолжить. */
+    watch(opts?: WatchOptions): Subscription;
+    /** Кэш результатов подключения. */
+    readonly cache: {
+        clear(): void;
+        stats(): CacheStats;
+    };
+    /** Начать путь с готового узла: db.entity(row | цепочка). */
+    entity(x: Chain | Row): Chain;
+    /**
+     * Тот же пул от имени аккаунта (letopis.account: имперсонацию проверяет база — право сервиса
+     * auth.impersonate), в арендаторе tenant (собственный аккаунта или по членству) и с явным владельцем
+     * новых строк: await db.as(account, { tenant, owner }). account = null — тот же актор.
+     */
+    as(account: string | {
+        id: string;
+    } | null, opts?: {
+        owner?: string;
+        tenant?: string;
+    }): Promise<Db>;
+    /** Явная транзакция read committed: те же цепочки, commit(), rollback(), lock(), forUpdate(). */
+    begin(): Promise<DbTx>;
+    /**
+     * Загрузчик (§2.6): строки любых классов — проверки в коде, COPY от роли владельца, один запрос по
+     * целям вне загрузки. Только на администраторском подключении (иначе admin_required).
+     */
+    load(input: LoadInput, opts?: LoadOptions): Promise<LoadReport>;
+    /**
+     * Именованная очередь планов фасада: batch.Класс(…).create(…); batch.run() — одной транзакцией. У корня,
+     * у каждого db.as() и у каждой db.begin() очереди свои: план исполняется от имени фасада, который его поставил.
+     */
+    batch(name: string): Batch;
+    /** Advisory-блокировка до конца транзакции — только в db.begin() (иначе tx_required). */
+    lock(...keys: (string | number)[]): Promise<void>;
+    /** Зафиксировать транзакцию tr (то же, что tr.commit()). */
+    commit(tr?: DbTx): Promise<void>;
+    /** Откатить транзакцию tr (то же, что tr.rollback()). */
+    rollback(tr?: DbTx): Promise<void>;
+    close(): Promise<void>;
+}
+/** Подключение: служебные методы и классы как стартовые шаги цепочек — db.Класс(фильтр). */
+export type Db = DbCore & {
+    [className: string]: StepFn;
+};
+/** Явная транзакция db.begin(): тот же API; ошибка любого запроса её ломает (§2.5). */
+export type DbTx = Db;
+/** Подключение с типами шагов, строк и фильтров по моделям: connect({ models }). */
+export type TypedDb<M extends readonly AnyModelLike[]> = DbCore & StepsOf<M> & {
+    [className: string]: StepFn;
+};
+export type { Batch };
+export declare function connect<const M extends readonly AnyModelLike[]>(opts: ConnectOptions & {
+    models: M;
+}): Promise<TypedDb<M>>;
+export declare function connect(opts: ConnectOptions): Promise<Db>;