@atscript/db 0.1.39 → 0.1.40

package/dist/db-space-BUrQ5BFm.d.mts

@@ -0,0 +1,309 @@
+import { F as TDbInsertResult, H as TFkLookupResolver, O as TDbDeleteResult, P as TDbInsertManyResult, S as TCascadeResolver, Y as TTableResolver, Z as TWriteTableResolver, l as TGenericLogger, o as BaseDbAdapter, s as TableMetadata, t as AtscriptDbReadable, z as TDbUpdateResult } from "./db-readable-Bbr4CjMb.mjs";
+import { AtscriptQueryComparison, AtscriptQueryFieldRef, AtscriptQueryFieldRef as AtscriptQueryFieldRef$1, AtscriptQueryNode, AtscriptQueryNode as AtscriptQueryNode$1, AtscriptRef, FlatOf, NavPropsOf, OwnPropsOf, PrimaryKeyOf, TAtscriptAnnotatedType, TAtscriptDataType, Validator } from "@atscript/typescript/utils";
+import { FilterExpr } from "@uniqu/core";
+
+//#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 = FlatOf<T>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = 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>>;
+  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: Partial<DataType> & Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): 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).
+   */
+  insertMany(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+  }): Promise<TDbInsertManyResult>;
+  /**
+   * Replaces a single record identified by primary key(s).
+   * Delegates to {@link bulkReplace} for unified nested relation support.
+   */
+  replaceOne(payload: DataType & Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): 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).
+   */
+  bulkReplace(payloads: Array<DataType & Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+  }): Promise<TDbUpdateResult>;
+  /**
+   * Partially updates a single record identified by primary key(s).
+   * Delegates to {@link bulkUpdate} for unified nested relation support.
+   */
+  updateOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): 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).
+   */
+  bulkUpdate(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+  }): 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.
+   */
+  deleteOne(id: IdType): Promise<TDbDeleteResult>;
+  updateMany(filter: FilterExpr<FlatType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
+  replaceMany(filter: FilterExpr<FlatType>, data: Record<string, unknown>): 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>;
+  /**
+   * Applies default values for fields that are missing from the payload.
+   * Defaults handled natively by the DB engine are skipped — the field stays
+   * absent so the DB's own DEFAULT clause applies.
+   */
+  protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Extracts primary key field(s) from a payload to build a filter.
+   */
+  protected _extractPrimaryKeyFilter(payload: Record<string, unknown>): FilterExpr;
+  /**
+   * 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 = FlatOf<T>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = 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[];
+}
+//#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;
+/**
+ * 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;
+  protected readonly logger: TGenericLogger;
+  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?;
+  constructor(adapterFactory: TAdapterFactory, logger?: TGenericLogger);
+  /**
+   * 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>;
+  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 { AtscriptQueryComparison as a, AtscriptRef as c, translateQueryTree as d, AtscriptDbTable as f, TViewColumnMapping as i, TViewJoin as l, NativeIntegrity as m, TAdapterFactory as n, AtscriptQueryFieldRef$1 as o, IntegrityStrategy as p, AtscriptDbView as r, AtscriptQueryNode$1 as s, DbSpace as t, TViewPlan as u };

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

@@ -0,0 +1,309 @@
+import { F as TDbInsertResult, H as TFkLookupResolver, O as TDbDeleteResult, P as TDbInsertManyResult, S as TCascadeResolver, Y as TTableResolver, Z as TWriteTableResolver, l as TGenericLogger, o as BaseDbAdapter, s as TableMetadata, t as AtscriptDbReadable, z as TDbUpdateResult } from "./db-readable-BQQzfguJ.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 = FlatOf<T>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = 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>>;
+  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: Partial<DataType> & Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): 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).
+   */
+  insertMany(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+  }): Promise<TDbInsertManyResult>;
+  /**
+   * Replaces a single record identified by primary key(s).
+   * Delegates to {@link bulkReplace} for unified nested relation support.
+   */
+  replaceOne(payload: DataType & Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): 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).
+   */
+  bulkReplace(payloads: Array<DataType & Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+  }): Promise<TDbUpdateResult>;
+  /**
+   * Partially updates a single record identified by primary key(s).
+   * Delegates to {@link bulkUpdate} for unified nested relation support.
+   */
+  updateOne(payload: Partial<DataType> & Record<string, unknown>, opts?: {
+    maxDepth?: number;
+  }): 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).
+   */
+  bulkUpdate(payloads: Array<Partial<DataType> & Record<string, unknown>>, opts?: {
+    maxDepth?: number;
+  }): 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.
+   */
+  deleteOne(id: IdType): Promise<TDbDeleteResult>;
+  updateMany(filter: FilterExpr<FlatType>, data: Partial<DataType> & Record<string, unknown>): Promise<TDbUpdateResult>;
+  replaceMany(filter: FilterExpr<FlatType>, data: Record<string, unknown>): 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>;
+  /**
+   * Applies default values for fields that are missing from the payload.
+   * Defaults handled natively by the DB engine are skipped — the field stays
+   * absent so the DB's own DEFAULT clause applies.
+   */
+  protected _applyDefaults(data: Record<string, unknown>): Record<string, unknown>;
+  /**
+   * Extracts primary key field(s) from a payload to build a filter.
+   */
+  protected _extractPrimaryKeyFilter(payload: Record<string, unknown>): FilterExpr;
+  /**
+   * 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 = FlatOf<T>, A extends BaseDbAdapter = BaseDbAdapter, IdType = PrimaryKeyOf<T>, OwnProps = 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[];
+}
+//#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;
+/**
+ * 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;
+  protected readonly logger: TGenericLogger;
+  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?;
+  constructor(adapterFactory: TAdapterFactory, logger?: TGenericLogger);
+  /**
+   * 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>;
+  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 { AtscriptQueryComparison as a, AtscriptRef as c, translateQueryTree as d, AtscriptDbTable as f, TViewColumnMapping as i, TViewJoin as l, NativeIntegrity as m, TAdapterFactory as n, AtscriptQueryFieldRef$1 as o, IntegrityStrategy as p, AtscriptDbView as r, AtscriptQueryNode$1 as s, DbSpace as t, TViewPlan as u };

package/dist/db-validator-plugin-07kDiis2.d.cts

@@ -0,0 +1,22 @@
+import { TAtscriptAnnotatedType, TValidatorPlugin } from "@atscript/typescript/utils";
+
+//#region src/db-validator-plugin.d.ts
+interface DbValidationContext {
+  mode: "insert" | "replace" | "patch";
+  /** Flat map from the table — used to check if an array is a top-level array. */
+  flatMap?: Map<string, TAtscriptAnnotatedType>;
+}
+/**
+ * Validator plugin for database operations.
+ *
+ * Handles navigation field constraints and delegates to the standard validator
+ * for type checking. The annotated type tree already includes nav fields with
+ * their full target types — this plugin controls WHEN recursion is allowed
+ * based on the operation mode (insert/replace/patch).
+ *
+ * Replaces the old `navFieldsValidatorPlugin` (which blindly skipped all nav
+ * fields) and `_checkNavProps()` (which validated constraints separately).
+ */
+declare function createDbValidatorPlugin(): TValidatorPlugin;
+//#endregion
+export { createDbValidatorPlugin as n, DbValidationContext as t };

package/dist/db-validator-plugin-CiqsHTI_.d.mts

@@ -0,0 +1,22 @@
+import { TAtscriptAnnotatedType, TValidatorPlugin } from "@atscript/typescript/utils";
+
+//#region src/db-validator-plugin.d.ts
+interface DbValidationContext {
+  mode: "insert" | "replace" | "patch";
+  /** Flat map from the table — used to check if an array is a top-level array. */
+  flatMap?: Map<string, TAtscriptAnnotatedType>;
+}
+/**
+ * Validator plugin for database operations.
+ *
+ * Handles navigation field constraints and delegates to the standard validator
+ * for type checking. The annotated type tree already includes nav fields with
+ * their full target types — this plugin controls WHEN recursion is allowed
+ * based on the operation mode (insert/replace/patch).
+ *
+ * Replaces the old `navFieldsValidatorPlugin` (which blindly skipped all nav
+ * fields) and `_checkNavProps()` (which validated constraints separately).
+ */
+declare function createDbValidatorPlugin(): TValidatorPlugin;
+//#endregion
+export { createDbValidatorPlugin as n, DbValidationContext as t };