@atscript/db 0.1.135 → 0.1.137

package/dist/db-space-BdtBNTeH.d.cts

@@ -1,439 +0,0 @@
-import { Ct as TWriteTableResolver, H as TDbInsertManyResult, Ht as TGenericLogger, I as TDbDeleteResult, Lt as DbEncryption, Nt as BaseDbAdapter, Ot as TableMetadata, Pt as AtscriptDbReadable, Rt as TDbEncryptionOptions, St as TWriteOptions, U as TDbInsertResult, X as TDbUpdateResult, bt as TTouchManyOptions, et as TDeleteOptions, g as DbRow, lt as TIdResolveOptions, m as DbPatch, mt as TReferencingForeignKey, ot as TFkLookupResolver, w as TCascadeResolver, x as NullableOptional, yt as TTableResolver } from "./buckets-D6PBXKRJ.cjs";
-import { FilterExpr } from "@uniqu/core";
-import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
-
-//#region src/strategies/integrity.d.ts
-/**
- * Strategy for referential integrity enforcement.
- * Two implementations: {@link NativeIntegrity} (DB handles FK constraints)
- * and `ApplicationIntegrity` (generic layer validates + cascades).
- */
-declare abstract class IntegrityStrategy {
-  abstract validateForeignKeys(items: Array<Record<string, unknown>>, meta: TableMetadata, fkLookupResolver: TFkLookupResolver | undefined, writeTableResolver: TWriteTableResolver | undefined, partial?: boolean, excludeTargetTable?: string): Promise<void>;
-  abstract cascadeBeforeDelete(filter: FilterExpr, tableName: string, meta: TableMetadata, cascadeResolver: TCascadeResolver, translateFilter: (f: FilterExpr) => FilterExpr, adapter: BaseDbAdapter): Promise<void>;
-  abstract needsCascade(cascadeResolver: TCascadeResolver | undefined): boolean;
-}
-/**
- * Integrity strategy for adapters with native FK support (e.g. SQLite, MySQL).
- * All operations are no-ops — the database engine enforces constraints.
- */
-declare class NativeIntegrity extends IntegrityStrategy {
-  validateForeignKeys(): Promise<void>;
-  cascadeBeforeDelete(): Promise<void>;
-  needsCascade(): boolean;
-}
-//#endregion
-//#region src/table/db-table.d.ts
-declare class AtscriptDbTable<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, FlatType = NullableOptional<FlatOf<T>>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = NullableOptional<OwnPropsOf<T>>, NavType extends Record<string, unknown> = NavPropsOf<T>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
-  protected _cascadeResolver?: TCascadeResolver;
-  protected _fkLookupResolver?: TFkLookupResolver;
-  protected readonly _integrity: IntegrityStrategy;
-  protected readonly validators: Map<string, Validator<T, DataType>>;
-  private _fromDepthMap?;
-  constructor(_type: T, adapter: A, logger?: TGenericLogger, _tableResolver?: TTableResolver, _writeTableResolver?: TWriteTableResolver);
-  /**
-   * Sets the cascade resolver for application-level cascade deletes.
-   * Called by DbSpace after table creation.
-   */
-  setCascadeResolver(resolver: TCascadeResolver): void;
-  /**
-   * Sets the FK lookup resolver for application-level FK validation.
-   * Called by DbSpace after table creation.
-   */
-  setFkLookupResolver(resolver: TFkLookupResolver): void;
-  /**
-   * Returns a cached validator for the given purpose.
-   * Built with adapter plugins from {@link BaseDbAdapter.getValidatorPlugins}.
-   *
-   * Standard purposes: `'insert'`, `'update'`, `'patch'`.
-   * Adapters may define additional purposes.
-   */
-  getValidator(purpose: string): Validator<T, DataType>;
-  /**
-   * Inserts a single record. Delegates to {@link insertMany} for unified
-   * nested creation support.
-   */
-  insertOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbInsertResult>;
-  /**
-   * Inserts multiple records with batch-optimized nested creation.
-   *
-   * Supports **nested creation**: if payloads include data for navigation
-   * fields (`@db.rel.to` / `@db.rel.from`), related records are created
-   * automatically in batches. TO dependencies are batch-created first
-   * (their PKs become our FKs), FROM dependents are batch-created after
-   * (they receive our PKs as their FKs). Fully recursive — nested records
-   * with their own nav data trigger further batch inserts at each level.
-   * Recursive up to `maxDepth` (default 3).
-   *
-   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
-   * defaults + validation, with the prepared rows — see {@link TWriteOptions}.
-   */
-  insertMany(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbInsertManyResult>;
-  /**
-   * Replaces a single record identified by primary key(s).
-   * Delegates to {@link bulkReplace} for unified nested relation support.
-   */
-  replaceOne(payload: DbRow<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
-  /**
-   * Replaces multiple records with deep nested relation support.
-   *
-   * Supports all relation types (TO, FROM, VIA). TO dependencies are
-   * replaced first (their PKs become our FKs), FROM dependents are replaced
-   * after (they receive our PKs as their FKs), VIA relations clear and
-   * re-create junction rows. Fully recursive up to `maxDepth` (default 3).
-   *
-   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
-   * `$cas` extraction, defaults + validation — see {@link TWriteOptions}.
-   */
-  bulkReplace(payloads: Array<DbRow<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
-  /**
-   * Partially updates a single record identified by primary key(s).
-   * Delegates to {@link bulkUpdate} for unified nested relation support.
-   */
-  updateOne(payload: DbPatch<DataType>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
-  /**
-   * Partially updates multiple records with deep nested relation support.
-   *
-   * Only TO relations (1:1, N:1) are supported for patching. FROM/VIA
-   * relations will error — use {@link bulkReplace} for those.
-   * Recursive up to `maxDepth` (default 3).
-   *
-   * `opts.guard` (since 0.1.128) runs once inside the transaction, after
-   * `$cas` extraction and validation, with the patches (identifying fields
-   * present, `$cas` removed) — see {@link TWriteOptions}.
-   */
-  bulkUpdate(payloads: Array<DbPatch<DataType>>, opts?: TWriteOptions<DataType>): Promise<TDbUpdateResult>;
-  /**
-   * Batch versioned touch (since 0.1.129): bumps the version of every listed
-   * row by exactly one, each row guarded by its own expected version. This is
-   * the batch fence `updateMany(orFilter, {})` used to be before 0.1.128 (an
-   * empty patch is a no-op since then and takes no lock).
-   *
-   * Each key carries the primary key field(s) (composite supported) plus the
-   * version column and NOTHING else — a touch has no payload. Unique indexes
-   * do not identify a touch key. `undefined`-valued properties are ignored,
-   * like in every write payload. Empty `keys` → `{ 0, 0 }` without a statement.
-   *
-   * `require: 'all'` (default): one count over the whole key set runs FIRST;
-   * a stale or missing row throws {@link CasMismatchError} before any write.
-   * The bumps then run as `updateMany(orFilter, {})` chunks of at most
-   * {@link TOUCH_MANY_CHUNK} keys inside one adapter transaction; a summed
-   * `matchedCount` short of `keys.length` (a row moved between the count and
-   * the bump) throws the same error — SQL engines roll every bump back. The
-   * pre-count is therefore a deliberate double check on SQL: it is what makes
-   * the guarantee hold on adapters whose `withTransaction` is a passthrough
-   * (the memory adapter, a Mongo standalone topology) — there it covers the
-   * common stale case and the residual race window is accepted.
-   * `require: 'any'`: no pre-count, the honest summed result is returned.
-   *
-   * No `guard`, no `onWrite`; not exposed over HTTP.
-   */
-  touchMany(keys: Array<DbPatch<DataType>>, opts?: TTouchManyOptions): Promise<TDbUpdateResult>;
-  /**
-   * Deletes a single record by any type-compatible identifier — primary key
-   * or single-field unique index. Uses the same resolution logic as `findById`.
-   *
-   * When the adapter does not support native foreign keys (e.g. MongoDB),
-   * cascade and setNull actions are applied before the delete.
-   *
-   * `opts.guard` (since 0.1.128) runs inside the transaction once the id has
-   * resolved to a filter, before cascade / delete — see {@link TDeleteOptions}.
-   * An id that resolves to no filter answers `{ deletedCount: 0 }` without
-   * calling the guard.
-   */
-  deleteOne(id: IdType, opts?: TDeleteOptions<DataType>): Promise<TDbDeleteResult>;
-  updateMany(filter: FilterExpr<FlatType>, data: DbPatch<DataType>): Promise<TDbUpdateResult>;
-  replaceMany(filter: FilterExpr<FlatType>, data: DbRow<DataType>): Promise<TDbUpdateResult>;
-  deleteMany(filter: FilterExpr<FlatType>): Promise<TDbDeleteResult>;
-  /**
-   * Synchronizes indexes between Atscript definitions and the database.
-   */
-  syncIndexes(): Promise<void>;
-  /**
-   * Ensures the table/collection exists in the database.
-   */
-  ensureTable(): Promise<void>;
-  /** Engine-agnostic guard for user-supplied mutation filters (updateMany/deleteMany/…). */
-  protected _guardMutationFilter(filter: FilterExpr): void;
-  /**
-   * Encrypts `@db.encrypted` field values in place on (already validated)
-   * write payloads — between validation and `prepareForWrite`, so adapters
-   * only ever see envelope strings.
-   *
-   * Parent objects along an encrypted path are shallow-cloned before
-   * mutation so caller-shared nested objects are never modified.
-   *
-   * In `patch` mode, operator objects (`$inc`, `$insert`, …) targeting an
-   * encrypted field are rejected with `ENC_FIELD_PATCH_OP` — ciphertext is
-   * opaque; only plain re-assignment (which re-encrypts) is allowed.
-   */
-  protected _encryptItems(items: Array<Record<string, unknown>>, mode: "write" | "patch"): Promise<void>;
-  /**
-   * Lazy pre-image read for a guard's `current(i)`: `null` when the row has
-   * no identifying key (e.g. an auto-increment insert) or the key cannot be
-   * resolved — never throws for a missing key.
-   * @internal
-   */
-  _readPreImage(row: unknown): Promise<DataType | null>;
-  /**
-   * Applies `@db.default` values in place to a row's absent fields — the
-   * defaults pass every insert / replace path runs before validation.
-   * Static value defaults (`@db.default 'x'`) are filled on EVERY adapter
-   * (since 0.1.128 — writing the column's own default explicitly is
-   * equivalent to leaving it to the DDL `DEFAULT`, and write guards see the
-   * full row). Function defaults (`now` / `uuid` / `increment` / custom) the
-   * adapter handles natively are NOT filled — the field stays absent so the
-   * engine's own default applies. The version column is never touched.
-   */
-  protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
-  /**
-   * The JS value for a `@db.default 'literal'`: strings (including unions of
-   * string literals) are used as-is, every other design type is parsed as
-   * JSON — the same value the SQL adapters put into the DDL `DEFAULT` clause.
-   * A literal that is not valid JSON falls back to the raw string so the
-   * validator reports it against the field instead of a bare `SyntaxError`.
-   */
-  private _parseValueDefault;
-  /**
-   * Extracts a record-identifying filter from a payload.
-   *
-   * Resolution order:
-   * 1. Primary key field(s) — if all PK fields are present in the payload.
-   * 2. Single-field unique index — first `@db.index.unique` field found.
-   * 3. Compound unique index — first compound unique index whose fields are all present.
-   *
-   * Throws when no identifying fields can be found. With `isFieldVisible`
-   * (since 0.1.134), a unique index over a hidden field is skipped, as if it
-   * did not exist — see {@link identificationsVisibleTo}.
-   */
-  protected _extractRecordFilter(payload: Record<string, unknown>, opts?: TIdResolveOptions): FilterExpr;
-  private _prepareFilterValue;
-  /**
-   * Lazy — builds a `normalized-path → from-depth` map from `this._meta.flatMap`
-   * on first use. Only paths reachable through an unbroken chain of `db.rel.from`
-   * nav fields from the root are included (chains crossing `to`/`via` are excluded).
-   */
-  private _getFromDepthMap;
-  /**
-   * Populate the depth-limit bundle on a `DbValidationContext`. Only the root
-   * write call (`depth === 0`) enforces — nested re-entries leave `depthCheck`
-   * unset so the full tree is validated once at the root.
-   */
-  private _applyDepthCtx;
-  /**
-   * Pre-validate items (type validation + FK constraints) without inserting them.
-   * Used by parent tables to validate FROM children before the main insert,
-   * ensuring errors are caught before the parent is committed.
-   *
-   * @param opts.excludeFkTargetTable - Skip FK validation to this table (the parent).
-   */
-  preValidateItems(items: Array<Record<string, unknown>>, opts?: {
-    excludeFkTargetTable?: string;
-  }): Promise<void>;
-  /**
-   * Builds a validator for a given purpose with adapter plugins.
-   *
-   * Uses annotation-based `replace` callback to make `@meta.id` and
-   * `@db.default` fields optional — works at all nesting levels
-   * (including inside nav field target types).
-   */
-  protected _buildValidator(purpose: string): Validator<T, DataType>;
-}
-//#endregion
-//#region src/query/query-tree.d.ts
-/** A single join in a view query plan. */
-interface TViewJoin {
-  targetType: () => TAtscriptAnnotatedType;
-  targetTable: string;
-  condition: AtscriptQueryNode;
-}
-/** Resolved view query plan produced by AtscriptDbView. */
-interface TViewPlan {
-  entryType: () => TAtscriptAnnotatedType;
-  entryTable: string;
-  joins: TViewJoin[];
-  filter?: AtscriptQueryNode;
-  having?: AtscriptQueryNode;
-  materialized: boolean;
-}
-/**
- * Translates a JS-emitted query tree into a FilterExpr.
- * Resolves field references (type + field path) to physical column names
- * via the provided resolver function.
- */
-declare function translateQueryTree(node: AtscriptQueryNode, resolveField: (ref: AtscriptQueryFieldRef) => string): FilterExpr;
-//#endregion
-//#region src/table/db-view.d.ts
-interface TViewColumnMapping {
-  viewColumn: string;
-  sourceTable: string;
-  sourceColumn: string;
-  /** Aggregate function name ('sum'|'avg'|'count'|'min'|'max') if this is an aggregate column. */
-  aggFn?: string;
-  /** Source field for the aggregate function ('*' for COUNT(*)). */
-  aggField?: string;
-}
-/**
- * Database view abstraction driven by Atscript `@db.view.*` annotations.
- *
- * Extends {@link AtscriptDbReadable} with view plan resolution — entry table,
- * joins, filter, and materialization flag. Read operations are inherited;
- * write operations are not available on views.
- *
- * ```typescript
- * const adapter = new SqliteAdapter(db)
- * const activeUsers = new AtscriptDbView(ActiveUsersType, adapter)
- * const users = await activeUsers.findMany({ filter: {}, controls: {} })
- * ```
- */
-declare class AtscriptDbView<T extends TAtscriptAnnotatedType = TAtscriptAnnotatedType, DataType = TAtscriptDataType<T>, FlatType = NullableOptional<FlatOf<T>>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = NullableOptional<OwnPropsOf<T>>, NavType extends Record<string, unknown> = NavPropsOf<T>> extends AtscriptDbReadable<T, DataType, FlatType, A, IdType, OwnProps, NavType> {
-  private _viewPlan?;
-  get isView(): boolean;
-  /**
-   * Whether this is an external view — declared with `@db.view` only,
-   * without `@db.view.for`. External views reference pre-existing DB views
-   * and are not managed (created/dropped) by schema sync.
-   */
-  get isExternal(): boolean;
-  /**
-   * Lazily resolves the view plan from `@db.view.*` metadata.
-   *
-   * - `db.view.for` → entry type ref (required)
-   * - `db.view.joins` → array of `{ target, condition }` (optional, multiple)
-   * - `db.view.filter` → query tree (optional)
-   * - `db.view.materialized` → boolean (optional)
-   */
-  get viewPlan(): TViewPlan;
-  /**
-   * Resolves a query field ref to a quoted `table.column` SQL fragment.
-   *
-   * @param ref - The field reference from the query tree.
-   * @param qi - Identifier quoting function (e.g. backtick for MySQL, double-quote for SQLite).
-   *             Defaults to double-quote wrapping for backwards compatibility.
-   */
-  resolveFieldRef(ref: AtscriptQueryFieldRef, qi?: (name: string) => string): string;
-  /**
-   * Maps each view field to its source table and column via ref chain.
-   * Fields without refs (inline definitions) map to the entry table with the same name.
-   */
-  getViewColumnMappings(): TViewColumnMapping[];
-}
-/**
- * Structural type guard for views: `true` when the readable reports
- * `isView`, whether or not it is an `AtscriptDbView` instance of THIS copy
- * of `@atscript/db`. Adapters must use this (or `readable.isView`) instead of
- * `instanceof AtscriptDbView` — in a bundle that carries two copies of the
- * core (app bundle + external adapter), `instanceof` is false and the adapter
- * would create an empty physical table under the view's name.
- * @since 0.1.128
- */
-declare function isAtscriptDbView(readable: AtscriptDbReadable<any, any, any, any, any, any, any>): readable is AtscriptDbView<any, any, any, any, any, any, any>;
-//#endregion
-//#region src/table/db-space.d.ts
-/**
- * Adapter factory function. Called once per table/view to create a fresh adapter instance.
- * Each readable gets its own adapter (1:1 relationship required by BaseDbAdapter).
- */
-type TAdapterFactory = () => BaseDbAdapter;
-/** Options bag for {@link DbSpace} (second constructor argument). */
-interface TDbSpaceOptions {
-  /** Logger shared by all tables/views in the space. */
-  logger?: TGenericLogger;
-  /** Field-level encryption configuration for `@db.encrypted` fields. */
-  encryption?: TDbEncryptionOptions;
-}
-/**
- * A database space — a registry of tables and views sharing the same adapter type and driver.
- *
- * `DbSpace` solves the cross-table discovery problem: when table A has a relation
- * to table B, it needs to find and query table B. The space acts as the registry
- * that makes this possible via the table resolver callback.
- *
- * Each table/view gets its own adapter instance (created by the factory), but all
- * share the same space and can discover each other for `$with` relation loading.
- *
- * ```typescript
- * // SQLite
- * const driver = new BetterSqlite3Driver(':memory:')
- * const db = new DbSpace(() => new SqliteAdapter(driver))
- * const users = db.getTable(UsersType)
- * const activeUsers = db.getView(ActiveUsersType)
- * ```
- */
-declare class DbSpace {
-  protected readonly adapterFactory: TAdapterFactory;
-  private _readables;
-  /** All tables created in this space — used for reverse FK lookup during cascade. */
-  private _allTables;
-  /** Lazily created adapter for administrative ops (drop table/view) that don't need a registered readable. */
-  private _adminAdapter?;
-  protected readonly logger: TGenericLogger;
-  /** Encryption service for `@db.encrypted` fields — validated eagerly at construction. */
-  protected readonly _encryption?: DbEncryption;
-  /**
-   * @param adapterFactory - Creates a fresh adapter per table/view.
-   * @param loggerOrOptions - Either a logger (legacy signature) or a
-   *   {@link TDbSpaceOptions} bag carrying `logger` and/or `encryption`.
-   */
-  constructor(adapterFactory: TAdapterFactory, loggerOrOptions?: TGenericLogger | TDbSpaceOptions);
-  /**
-   * Auto-detects whether the type is a table or view and returns the
-   * appropriate instance. Uses `@db.view` or `@db.view.for` presence to distinguish.
-   */
-  get<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbReadable<T>;
-  /**
-   * Returns the table for the given annotated type.
-   * Creates the table + adapter on first access, caches for subsequent calls.
-   */
-  getTable<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbTable<T>;
-  /**
-   * Returns the view for the given annotated type.
-   * Creates the view + adapter on first access, caches for subsequent calls.
-   */
-  getView<T extends TAtscriptAnnotatedType>(type: T, logger?: TGenericLogger): AtscriptDbView<T>;
-  /**
-   * Returns the adapter for the given annotated type.
-   * Creates the table/view + adapter on first access if needed.
-   */
-  getAdapter(type: TAtscriptAnnotatedType): BaseDbAdapter;
-  /**
-   * Drops a table by name. Used by schema sync to remove tables no longer in the schema.
-   */
-  dropTableByName(tableName: string): Promise<void>;
-  /**
-   * Drops a view by name. Used by schema sync to remove views no longer in the schema.
-   */
-  dropViewByName(viewName: string): Promise<void>;
-  /**
-   * Drops a group of mutually referencing tables as one operation.
-   * Used by schema sync to remove a foreign-key cycle no longer in the schema.
-   * @since 0.1.128
-   */
-  dropTablesByName(tableNames: string[]): Promise<void>;
-  /**
-   * Live foreign keys referencing `tableName`, or `undefined` when the
-   * adapter cannot introspect them. Used by schema sync for drop ordering
-   * and surviving-reference checks of tables without a registered readable.
-   * @since 0.1.128
-   */
-  getReferencingForeignKeys(tableName: string): Promise<TReferencingForeignKey[] | undefined>;
-  /**
-   * A factory-fresh adapter with NO registered readable. Only the name-taking
-   * primitives may run on it (`dropTableByName`, `dropViewByName`,
-   * `dropTablesByName`, `getReferencingForeignKeys`) — adapters derive the
-   * schema for those from the driver/connection, not from a bound table.
-   */
-  private _getAdminAdapter;
-  /**
-   * Finds all child tables with FKs pointing to the given parent table name.
-   * Accesses `table.foreignKeys` which triggers `_flatten()` if needed.
-   */
-  private _getCascadeTargets;
-  /**
-   * Resolves a table name to a queryable target for FK validation.
-   * Searches all registered tables for one with the matching table name.
-   */
-  private _getFkLookupTarget;
-}
-//#endregion
-export { TViewColumnMapping as a, AtscriptQueryFieldRef$1 as c, TViewJoin as d, TViewPlan as f, NativeIntegrity as g, IntegrityStrategy as h, AtscriptDbView as i, AtscriptQueryNode$1 as l, AtscriptDbTable as m, TAdapterFactory as n, isAtscriptDbView as o, translateQueryTree as p, TDbSpaceOptions as r, AtscriptQueryComparison as s, DbSpace as t, AtscriptRef as u };