@hazejs/orm 0.0.0-stage → 0.1.2

package/dist/model-CBky_ILK.d.mts

@@ -0,0 +1,728 @@
+import { ConfigInput, Logger } from "@hazejs/core";
+import { Column, InferInsertModel, InferSelectModel, SQL, Table } from "drizzle-orm";
+import { ClientSession, Db, Document, Filter, MongoClient, ObjectId, WithId } from "mongodb";
+type Row$1<T extends Table> = InferSelectModel<T>;
+type Insert<T extends Table> = InferInsertModel<T>;
+/** 表的列名（drizzle 表定义中的属性名） */
+type ColumnKey<T extends Table> = keyof Row$1<T> & string;
+type Operator = '=' | '!=' | '<>' | '>' | '>=' | '<' | '<=' | 'like' | 'not like' | 'in' | 'not in' | 'between' | 'not between';
+type Direction = 'asc' | 'desc';
+/** 分页结果（普通对象，可直接作为响应返回） */
+interface Paginated<T> {
+  data: T[];
+  total: number;
+  page: number;
+  perPage: number;
+  lastPage: number;
+}
+/** 不同驱动返回的 drizzle 实例类型不同，框架内部以统一接口调用 */
+type AnyDatabase = any;
+/** `{ status: 1, role: ['admin', 'owner'], deletedAt: null }`：数组为 IN，null 为 IS NULL */
+type WhereObject<T extends Table> = { [K in ColumnKey<T>]?: Row$1<T>[K] | Array<Row$1<T>[K]> | null; };
+type WhereCondition<T extends Table> = SQL | WhereObject<T> | ((group: Conditions<T>) => unknown);
+interface Part$1 {
+  bool: 'and' | 'or';
+  sql: SQL;
+}
+/** 条件构造：多次 where 以 AND 连接，orWhere 以 OR 连接（从左到右），回调参数用于分组 */
+declare class Conditions<T extends Table> {
+  readonly table: T;
+  protected parts: Part$1[];
+  constructor(table: T);
+  /**
+   * - `where('status', 1)` / `where('age', '>', 18)`
+   * - `where({ status: 1, role: ['a', 'b'] })`
+   * - `where(eq(users.id, 1))`（drizzle 表达式）
+   * - `where(q => q.where('a', 1).orWhere('b', 2))`（括号分组）
+   */
+  where(condition: WhereCondition<T>): this;
+  where<K extends ColumnKey<T>>(column: K, value: Row$1<T>[K] | Array<Row$1<T>[K]> | null): this;
+  where<K extends ColumnKey<T>>(column: K, operator: Operator, value: unknown): this;
+  orWhere(condition: WhereCondition<T>): this;
+  orWhere<K extends ColumnKey<T>>(column: K, value: Row$1<T>[K] | Array<Row$1<T>[K]> | null): this;
+  orWhere<K extends ColumnKey<T>>(column: K, operator: Operator, value: unknown): this;
+  whereIn<K extends ColumnKey<T>>(column: K, values: ReadonlyArray<Row$1<T>[K]>): this;
+  whereNotIn<K extends ColumnKey<T>>(column: K, values: ReadonlyArray<Row$1<T>[K]>): this;
+  whereNull(column: ColumnKey<T>): this;
+  whereNotNull(column: ColumnKey<T>): this;
+  whereBetween<K extends ColumnKey<T>>(column: K, range: [Row$1<T>[K], Row$1<T>[K]]): this;
+  whereNotBetween<K extends ColumnKey<T>>(column: K, range: [Row$1<T>[K], Row$1<T>[K]]): this;
+  whereLike(column: ColumnKey<T>, pattern: string): this;
+  whereNotLike(column: ColumnKey<T>, pattern: string): this;
+  /** 条件成立时才应用：`.when(keyword, q => q.whereLike('name', `%${keyword}%`))` */
+  when<V>(value: V, callback: (query: this, value: NonNullable<V>) => unknown): this;
+  /** 当前条件组合成的 SQL（无条件时为 undefined） */
+  buildWhere(): SQL | undefined;
+  get hasConditions(): boolean;
+  /** 列名 → drizzle 列对象 */
+  columnOf(key: string): Column;
+  protected addCondition(bool: Part$1['bool'], args: unknown[]): this;
+  protected pushCondition(bool: Part$1['bool'], sql: SQL): this;
+  protected parseCondition(args: unknown[]): SQL | undefined;
+  protected compare(key: string, operator: Operator, value: unknown): SQL;
+}
+interface TimestampOptions {
+  createdAt?: string | false;
+  updatedAt?: string | false;
+}
+/** 模型类上的静态配置 */
+interface ModelSettings {
+  readonly name: string;
+  table: Table;
+  connection?: string;
+  softDelete: boolean | string;
+  timestamps: boolean | TimestampOptions;
+  hidden: readonly string[];
+  append: readonly string[];
+}
+interface ModelMeta {
+  table: Table;
+  tableName: string;
+  columns: Record<string, Column>;
+  primaryKey: string | undefined;
+  softDelete: string | undefined;
+  createdAt: string | undefined;
+  updatedAt: string | undefined;
+}
+interface MongoSession {
+  name: string;
+  db: Db;
+  client: MongoClient;
+  /** 处于 Mongo.transaction() 中时的会话 */
+  session: ClientSession | undefined;
+}
+declare function resolveMongo(connection?: string): Promise<MongoSession>;
+/**
+ * MongoDB 事务（需要副本集或分片集群）。回调内的 Mongo / MongoModel 操作自动加入事务；
+ * MongoDB 不支持嵌套事务，嵌套调用直接复用外层事务。
+ */
+declare function mongoTransaction<R>(callback: (session: ClientSession) => Promise<R>, connection?: string): Promise<R>;
+/** Mongo 模型类上的静态配置 */
+interface MongoModelSettings {
+  readonly name: string;
+  collection: string;
+  connection?: string;
+  softDelete: boolean | string;
+  timestamps: boolean | TimestampOptions;
+}
+/** 泛型约束只检查品牌属性（原因同 SQL 的 ModelLike） */
+interface MongoModelLike {
+  readonly '~collection': any;
+}
+type MongoModelClass<M extends MongoModelLike = MongoModel<any>> = (new () => M) & MongoModelSettings;
+/** 文档类型 */
+type DocOf<M> = M extends {
+  readonly '~collection': infer D;
+} ? D : never;
+type MongoField<T> = (keyof T & string) | '_id';
+type MongoWhereArgs<T> = [condition: MongoWhere<T>] | [field: MongoField<T>, value: unknown] | [field: MongoField<T>, operator: Operator, value: unknown];
+/** MongoModel.define<Doc>(collection) 返回的基类：实例拥有文档的全部字段 */
+type DefinedMongoModel<T extends Document> = Omit<typeof MongoModel, 'prototype'> & (new () => MongoModel<T> & WithId<T>);
+interface MongoModelMeta {
+  softDelete: string | undefined;
+  createdAt: string | undefined;
+  updatedAt: string | undefined;
+}
+/** 解析软删除与时间戳字段（文档无固定结构，按配置决定） */
+declare function metaOfMongo(model: MongoModelSettings): MongoModelMeta;
+/**
+ * MongoDB 模型，API 与 SQL 的 Model 一致：
+ *
+ * ```ts
+ * interface UserDoc { name: string, email: string, status: number }
+ *
+ * export class User extends MongoModel.define<UserDoc>('users') {
+ *   static override softDelete = true
+ *   posts() {
+ *     return this.hasMany(Post, 'userId')
+ *   }
+ * }
+ *
+ * const user = await User.findOrFail('6650…')   // 字符串 _id 自动转为 ObjectId
+ * await User.where('status', 1).with('posts').paginate(1, 20)
+ * ```
+ */
+declare class MongoModel<T extends Document = Document> extends ActiveRecord<WithId<T>> {
+  /** 仅用于类型推导 */
+  readonly '~collection': T;
+  static collection: string;
+  static connection: string | undefined;
+  /** 软删除：true 使用 deletedAt 字段，或指定字段名 */
+  static softDelete: boolean | string;
+  /** 自动维护 createdAt / updatedAt，可指定字段名或设为 false */
+  static timestamps: boolean | TimestampOptions;
+  constructor();
+  /** 声明模型对应的集合：`class User extends MongoModel.define<UserDoc>('users') {}` */
+  static define<T extends Document>(collection: string): DefinedMongoModel<T>;
+  static primaryKeyName(): string;
+  static query<M extends MongoModelLike>(this: MongoModelClass<M>): MongoModelQuery<M>;
+  static where<M extends MongoModelLike>(this: MongoModelClass<M>, ...args: MongoWhereArgs<DocOf<M>>): MongoModelQuery<M>;
+  static whereIn<M extends MongoModelLike>(this: MongoModelClass<M>, field: (keyof DocOf<M> & string) | '_id', values: readonly unknown[]): MongoModelQuery<M>;
+  static order<M extends MongoModelLike>(this: MongoModelClass<M>, field: (keyof DocOf<M> & string) | '_id', direction?: 'asc' | 'desc'): MongoModelQuery<M>;
+  static with<M extends MongoModelLike>(this: MongoModelClass<M>, ...relations: Array<RelationName<M> | `${RelationName<M>}.${string}`>): MongoModelQuery<M>;
+  static scope<M extends MongoModelLike>(this: MongoModelClass<M>, name: string, ...args: unknown[]): MongoModelQuery<M>;
+  static withTrashed<M extends MongoModelLike>(this: MongoModelClass<M>): MongoModelQuery<M>;
+  static onlyTrashed<M extends MongoModelLike>(this: MongoModelClass<M>): MongoModelQuery<M>;
+  static find<M extends MongoModelLike>(this: MongoModelClass<M>, id: unknown): Promise<M | undefined>;
+  static findOrFail<M extends MongoModelLike>(this: MongoModelClass<M>, id: unknown): Promise<M>;
+  static all<M extends MongoModelLike>(this: MongoModelClass<M>): Promise<M[]>;
+  static paginate<M extends MongoModelLike>(this: MongoModelClass<M>, page?: number, perPage?: number): Promise<Paginated<M>>;
+  static count<M extends MongoModelLike>(this: MongoModelClass<M>): Promise<number>;
+  static create<M extends MongoModelLike>(this: MongoModelClass<M>, data: Partial<DocOf<M>>): Promise<M>;
+  static destroy<M extends MongoModelLike>(this: MongoModelClass<M>, ids: unknown | unknown[]): Promise<number>;
+  save(): Promise<this>;
+  delete(): Promise<boolean>;
+  forceDelete(): Promise<boolean>;
+  restore(): Promise<this>;
+  trashed(): boolean;
+  refresh(): Promise<this>;
+  /** 文档主键（ObjectId） */
+  get id(): ObjectId | undefined;
+  protected $meta(): MongoModelMeta;
+  protected $query(): MongoQuery<Document>;
+  protected $whereKey(): MongoQuery<Document>;
+}
+/** 由文档构造模型（供 MongoModelQuery 使用） */
+declare function hydrateMongoModel<M extends MongoModelLike>(model: MongoModelClass<M>, doc: Document): M;
+type Field<T> = (keyof T & string) | '_id';
+type MongoWhere<T> = { [K in Field<T>]?: unknown; } | ((group: MongoQuery<T>) => unknown);
+interface Part {
+  bool: 'and' | 'or';
+  filter: Document;
+}
+interface MongoQueryOptions {
+  connection?: string;
+}
+/** 把字符串形式的 _id 转为 ObjectId（其它字段原样保留） */
+declare function toObjectId(value: unknown): unknown;
+/**
+ * MongoDB 查询构造器，方法与 SQL 的 Db.table() 一致：
+ *
+ * ```ts
+ * await Mongo.collection<UserDoc>('users').where('status', 1).order('createdAt', 'desc').paginate(1, 20)
+ * ```
+ *
+ * Mongo 特有能力：`aggregate(pipeline)`、`where({ tags: { $all: ['a'] } })` 直接使用查询运算符。
+ */
+declare class MongoQuery<T = Document, R = WithId<T>> {
+  readonly collectionName: string;
+  protected connectionName: string | undefined;
+  protected parts: Part[];
+  protected sorts: Array<[string, 1 | -1]>;
+  protected limitValue: number | undefined;
+  protected offsetValue: number | undefined;
+  protected fields: string[] | undefined;
+  constructor(collection: string, options?: MongoQueryOptions);
+  connection(name: string): this;
+  where(condition: MongoWhere<T>): this;
+  where(field: Field<T>, value: unknown): this;
+  where(field: Field<T>, operator: Operator, value: unknown): this;
+  orWhere(condition: MongoWhere<T>): this;
+  orWhere(field: Field<T>, value: unknown): this;
+  orWhere(field: Field<T>, operator: Operator, value: unknown): this;
+  whereIn(field: Field<T>, values: readonly unknown[]): this;
+  whereNotIn(field: Field<T>, values: readonly unknown[]): this;
+  /** 字段为 null 或不存在 */
+  whereNull(field: Field<T>): this;
+  whereNotNull(field: Field<T>): this;
+  whereBetween(field: Field<T>, range: [unknown, unknown]): this;
+  whereNotBetween(field: Field<T>, range: [unknown, unknown]): this;
+  /** SQL 风格的 LIKE 模式（% 与 _），区分大小写 */
+  whereLike(field: Field<T>, pattern: string): this;
+  whereNotLike(field: Field<T>, pattern: string): this;
+  when<V>(value: V, callback: (query: this, value: NonNullable<V>) => unknown): this;
+  /** 当前条件组成的过滤器 */
+  buildFilter(): Document;
+  get hasConditions(): boolean;
+  order(field: Field<T>, direction?: Direction): this;
+  order(fields: Partial<Record<Field<T>, Direction>>): this;
+  limit(value: number): this;
+  offset(value: number): this;
+  page(page: number, perPage?: number): this;
+  field(...fields: Array<Field<T>>): this;
+  select(): Promise<R[]>;
+  find(): Promise<R | undefined>;
+  findOrFail(): Promise<R>;
+  value(field: Field<T>): Promise<unknown>;
+  column(field: Field<T>): Promise<unknown[]>;
+  count(): Promise<number>;
+  sum(field: Field<T>): Promise<number>;
+  avg(field: Field<T>): Promise<number | null>;
+  max(field: Field<T>): Promise<unknown>;
+  min(field: Field<T>): Promise<unknown>;
+  exists(): Promise<boolean>;
+  paginate(page?: number, perPage?: number): Promise<Paginated<R>>;
+  chunk(size: number, callback: (docs: R[], page: number) => unknown): Promise<void>;
+  /** 聚合管道（自动在开头加上当前条件的 $match） */
+  aggregate<O extends Document = Document>(pipeline: Document[]): Promise<O[]>;
+  /** 插入一条或多条，返回带 _id 的文档 */
+  insert(docs: Partial<T> | Array<Partial<T>>): Promise<Array<WithId<T>>>;
+  insertGetId(doc: Partial<T>): Promise<ObjectId>;
+  /** 按条件更新（普通字段使用 $set，也可直接传 $inc / $push 等运算符），返回匹配数量 */
+  update(values: Partial<T> | Document, options?: {
+    all?: boolean;
+  }): Promise<number>;
+  delete(options?: {
+    all?: boolean;
+  }): Promise<number>;
+  increment(field: Field<T>, step?: number): Promise<number>;
+  decrement(field: Field<T>, step?: number): Promise<number>;
+  /** 生成的过滤器（调试用） */
+  toFilter(): Filter<Document>;
+  clone(): this;
+  protected scopedFilter(): Document;
+  protected transform(docs: Document[]): Promise<R[]>;
+  protected label(): string;
+  protected session(): Promise<MongoSession>;
+  protected pushCondition(bool: Part['bool'], filter: Document): this;
+  protected addCondition(bool: Part['bool'], args: unknown[]): this;
+  protected parseCondition(args: unknown[]): Document | undefined;
+  protected compare(field: string, operator: Operator, raw: unknown): Document;
+  protected normalize(field: string, value: unknown): unknown;
+  protected normalizeList(field: string, values: readonly unknown[]): unknown[];
+  protected write<V>(run: () => Promise<V>): Promise<V>;
+  protected writableFilter(action: string, options: {
+    all?: boolean;
+  }): Document;
+  protected group(accumulator: Document): Promise<unknown>;
+}
+type TrashedMode$1 = 'without' | 'with' | 'only';
+/** Mongo 模型查询：结果为模型实例，应用软删除范围，支持预加载与作用域 */
+declare class MongoModelQuery<M extends MongoModelLike> extends MongoQuery<DocOf<M>, M> {
+  readonly model: MongoModelClass<M>;
+  protected trashed: TrashedMode$1;
+  protected eager: string[];
+  constructor(model: MongoModelClass<M>);
+  withTrashed(): this;
+  onlyTrashed(): this;
+  with(...relations: Array<RelationName<M> | `${RelationName<M>}.${string}`>): this;
+  scope(name: string, ...args: unknown[]): this;
+  /** 按 _id 查询（字符串自动转为 ObjectId）；不传时取第一条 */
+  find(id?: unknown): Promise<M | undefined>;
+  findOrFail(id?: unknown): Promise<M>;
+  /** 批量删除：启用软删除时只标记删除时间 */
+  delete(options?: {
+    all?: boolean;
+  }): Promise<number>;
+  forceDelete(options?: {
+    all?: boolean;
+  }): Promise<number>;
+  restore(options?: {
+    all?: boolean;
+  }): Promise<number>;
+  protected scopedFilter(): Document;
+  protected transform(docs: Document[]): Promise<M[]>;
+  protected label(): string;
+  clone(): this;
+}
+/**
+ * - `sqlite`：libsql 驱动（本地文件 `file:./data/app.db`、`:memory:`、Turso `libsql://…`）
+ * - `turso`：libsql 的纯 HTTP 客户端（Turso / sqld，`libsql://`、`https://`），不含原生二进制，可运行于 Edge 与 Serverless
+ * - `d1`：Cloudflare D1（通过 Workers 绑定访问，`binding` 为绑定名）
+ * - `postgres`：postgres-js
+ * - `pglite`：嵌入式 PostgreSQL（WASM），适合本地开发与测试，url 为数据目录，省略为内存库
+ * - `mysql`：mysql2
+ * - `mongodb`：官方 mongodb 驱动（使用 `@hazejs/orm/mongo` 的 Mongo / MongoModel）
+ */
+type Driver = 'sqlite' | 'turso' | 'd1' | 'postgres' | 'pglite' | 'mysql' | 'mongodb';
+type Dialect = 'sqlite' | 'postgres' | 'mysql' | 'mongodb';
+interface ConnectionConfig {
+  driver: Driver;
+  url?: string;
+  /** libsql / Turso 认证令牌 */
+  authToken?: string;
+  /** D1：Workers 绑定名（默认 `DB`），或直接传入 D1Database 对象 */
+  binding?: string | object;
+  /** 连接池大小（postgres / mysql / mongodb） */
+  pool?: number;
+  /** MongoDB 数据库名（默认取 url 中的路径） */
+  database?: string;
+  /** 以 debug 级别输出 SQL */
+  logging?: boolean;
+  /** drizzle 表定义目录（相对 srcDir），默认 `database/schema` */
+  schema?: string;
+  /** 迁移目录（相对 srcDir），默认连接为 `database/migrations`，其它连接为 `database/migrations/<name>` */
+  migrations?: string;
+}
+interface DatabaseConfig {
+  /** 默认连接名 */
+  default: string;
+  connections: Record<string, ConnectionConfig>;
+}
+/** `config/database.ts` 的默认导出 */
+declare function defineDatabaseConfig(config: ConfigInput<DatabaseConfig>): ConfigInput<DatabaseConfig>;
+declare function dialectOf(driver: Driver): Dialect;
+interface Connection {
+  name: string;
+  driver: Driver;
+  dialect: Dialect;
+  /** SQL 为 drizzle 实例，MongoDB 为 mongodb 的 Db */
+  db: AnyDatabase;
+  /** 底层客户端（MongoDB 事务需要） */
+  client?: unknown;
+  close: () => Promise<void>;
+}
+interface DatabaseManagerOptions {
+  logger?: Logger;
+  /** 解析 sqlite 相对路径的基准目录，默认 process.cwd() */
+  rootDir?: string;
+}
+declare class DatabaseManager {
+  #private;
+  readonly config: DatabaseConfig;
+  constructor(config: DatabaseConfig, options?: DatabaseManagerOptions);
+  get defaultConnection(): string;
+  connectionConfig(name?: string): ConnectionConfig;
+  /** 获取连接（首次使用时建立） */
+  connection(name?: string): Promise<Connection>;
+  /** 关闭连接（默认全部）；测试中可用于重建内存数据库 */
+  close(name?: string): Promise<void>;
+}
+/** 由 databaseProvider() 在应用启动时设置；脚本 / 测试中可直接调用 */
+declare function setDatabaseManager(value: DatabaseManager | undefined): void;
+declare function useDatabaseManager(): DatabaseManager;
+interface Session {
+  name: string;
+  driver: Driver;
+  dialect: Dialect;
+  /** 当前可用的 drizzle 实例（处于事务中时为事务对象） */
+  db: AnyDatabase;
+}
+declare function resolveSession(connection?: string): Promise<Session>;
+/**
+ * 在事务中执行；回调内通过 Db / Model 发起的查询自动加入该事务（隐式传播），
+ * 嵌套调用使用保存点。回调抛错时回滚。
+ */
+declare function transaction<R>(callback: (tx: AnyDatabase) => Promise<R>, connection?: string): Promise<R>;
+interface QueryOptions {
+  /** 连接名，默认使用 config/database.ts 的 default */
+  connection?: string;
+}
+interface WriteOptions {
+  /** 允许无条件更新 / 删除整张表（默认拒绝，防止误操作） */
+  all?: boolean;
+}
+/**
+ * ThinkPHP 风格的查询构造器，底层使用 drizzle：
+ *
+ * ```ts
+ * await Db.table(users).where('status', 1).order('id', 'desc').paginate(1, 20)
+ * ```
+ */
+declare class QueryBuilder<T extends Table, R = Row$1<T>> extends Conditions<T> {
+  protected connectionName: string | undefined;
+  protected orders: SQL[];
+  protected limitValue: number | undefined;
+  protected offsetValue: number | undefined;
+  protected fields: string[] | undefined;
+  constructor(table: T, options?: QueryOptions);
+  /** 切换连接 */
+  connection(name: string): this;
+  /** `order('id', 'desc')`、`order({ status: 'asc', id: 'desc' })` 或 drizzle 表达式 */
+  order(column: ColumnKey<T>, direction?: Direction): this;
+  order(columns: Partial<Record<ColumnKey<T>, Direction>>): this;
+  order(expression: SQL): this;
+  limit(value: number): this;
+  offset(value: number): this;
+  /** 分页：page 从 1 开始 */
+  page(page: number, perPage?: number): this;
+  /** 只查询指定列 */
+  field<K extends ColumnKey<T>>(...keys: K[]): QueryBuilder<T, Pick<Row$1<T>, K>>;
+  /** 查询全部结果 */
+  select(): Promise<R[]>;
+  /** 查询第一条，不存在时为 undefined */
+  find(): Promise<R | undefined>;
+  findOrFail(): Promise<R>;
+  /** 某一列的值（第一条） */
+  value<K extends ColumnKey<T>>(column: K): Promise<Row$1<T>[K] | undefined>;
+  /** 某一列的全部值 */
+  column<K extends ColumnKey<T>>(column: K): Promise<Array<Row$1<T>[K]>>;
+  count(): Promise<number>;
+  sum(column: ColumnKey<T>): Promise<number>;
+  avg(column: ColumnKey<T>): Promise<number | null>;
+  max<K extends ColumnKey<T>>(column: K): Promise<Row$1<T>[K] | null>;
+  min<K extends ColumnKey<T>>(column: K): Promise<Row$1<T>[K] | null>;
+  exists(): Promise<boolean>;
+  paginate(page?: number, perPage?: number): Promise<Paginated<R>>;
+  /** 分批处理大量数据，回调返回 false 时停止 */
+  chunk(size: number, callback: (rows: R[], page: number) => unknown): Promise<void>;
+  /** 插入一条或多条，返回插入后的完整记录（MySQL 通过主键回查） */
+  insert(values: Insert<T> | Array<Insert<T>>): Promise<Array<Row$1<T>>>;
+  /** 插入一条并返回主键值 */
+  insertGetId(values: Insert<T>): Promise<unknown>;
+  /** 按当前条件更新，返回影响行数 */
+  update(values: Partial<Insert<T>> | Record<string, unknown>, options?: WriteOptions): Promise<number>;
+  /** 按当前条件删除，返回影响行数 */
+  delete(options?: WriteOptions): Promise<number>;
+  increment(column: ColumnKey<T>, step?: number): Promise<number>;
+  decrement(column: ColumnKey<T>, step?: number): Promise<number>;
+  /** 生成的 SQL 与参数（调试用） */
+  toSQL(): Promise<{
+    sql: string;
+    params: unknown[];
+  }>;
+  clone(): this;
+  /** 子类（ModelQuery）追加的全局条件，例如软删除 */
+  protected scopedWhere(): SQL | undefined;
+  /** 子类（ModelQuery）把行转换为模型 */
+  protected transform(rows: Array<Record<string, unknown>>): Promise<R[]>;
+  protected label(): string;
+  protected session(): Promise<Session>;
+  protected aggregate(expression: SQL): Promise<unknown>;
+  /** 写操作：把唯一约束等数据库错误转换为框架异常（409） */
+  protected write<V>(run: () => Promise<V>): Promise<V>;
+  protected writableWhere(action: string, options: WriteOptions): SQL | undefined;
+}
+type TrashedMode = 'without' | 'with' | 'only';
+/** 模型查询：结果为模型实例，自动应用软删除范围，支持预加载关联与作用域 */
+declare class ModelQuery<M extends ModelLike> extends QueryBuilder<TableOf<M> & Table, M> {
+  readonly model: ModelClass<M>;
+  protected trashed: TrashedMode;
+  protected eager: string[];
+  constructor(model: ModelClass<M>);
+  /** 包含已软删除的数据 */
+  withTrashed(): this;
+  /** 只查询已软删除的数据 */
+  onlyTrashed(): this;
+  /** 预加载关联：`with('posts', 'posts.comments', 'profile')` */
+  with(...relations: Array<RelationName<M> | `${RelationName<M>}.${string}`>): this;
+  /** 调用模型上的 `static scopeXxx(query, ...args)`：`scope('active')` */
+  scope(name: string, ...args: unknown[]): this;
+  /** 按主键查询；不传主键时取第一条 */
+  find(id?: unknown): Promise<M | undefined>;
+  findOrFail(id?: unknown): Promise<M>;
+  paginate(page?: number, perPage?: number): Promise<Paginated<M>>;
+  /** 批量删除：启用软删除时只标记删除时间 */
+  delete(options?: {
+    all?: boolean;
+  }): Promise<number>;
+  /** 物理删除（忽略软删除） */
+  forceDelete(options?: {
+    all?: boolean;
+  }): Promise<number>;
+  /** 恢复软删除的数据 */
+  restore(options?: {
+    all?: boolean;
+  }): Promise<number>;
+  protected scopedWhere(): SQL | undefined;
+  protected transform(rows: Array<Record<string, unknown>>): Promise<M[]>;
+  protected label(): string;
+  clone(): this;
+  protected primaryKey(): string;
+}
+/** 关联查询所需的最小接口（SQL 的 ModelQuery 与 Mongo 的 MongoModelQuery 都满足） */
+interface RelationQuery<R> {
+  where: (field: never, value: never) => RelationQuery<R>;
+  whereIn: (field: never, values: never) => RelationQuery<R>;
+  with: (...relations: never[]) => RelationQuery<R>;
+  select: () => Promise<R[]>;
+  find: () => Promise<R | undefined>;
+}
+/**
+ * 记录类的查询类型：SQL 模型为 ModelQuery，Mongo 模型为 MongoModelQuery。
+ * 通过品牌属性判断而非结构比较，避免互相引用的模型类型无限展开。
+ */
+type QueryOf<R> = R extends {
+  readonly '~table': any;
+} ? ModelQuery<R & {
+  readonly '~table': any;
+}> : R extends {
+  readonly '~collection': any;
+} ? MongoModelQuery<R & {
+  readonly '~collection': any;
+}> : RelationQuery<R>;
+/**
+ * 关联关系。可直接 await 获取结果，也可继续构造查询：
+ *
+ * ```ts
+ * const posts = await user.posts()
+ * const recent = await user.posts().query().order('id', 'desc').limit(5).select()
+ * ```
+ */
+declare abstract class Relation<R extends ActiveRecord, Result> implements PromiseLike<Result> {
+  readonly parent: ActiveRecord;
+  readonly related: RecordClass<R>;
+  constructor(parent: ActiveRecord, related: RecordClass<R>);
+  /** 受当前关联约束的查询（返回关联模型自己的查询类型） */
+  abstract query(): QueryOf<R>;
+  /** 获取关联结果 */
+  abstract get(): Promise<Result>;
+  /** 批量预加载到一组父记录上 */
+  abstract eagerLoad(parents: ActiveRecord[], name: string, nested: string[]): Promise<void>;
+  then<A = Result, B = never>(onFulfilled?: ((value: Result) => A | PromiseLike<A>) | null, onRejected?: ((reason: unknown) => B | PromiseLike<B>) | null): Promise<A | B>;
+}
+declare abstract class HasOneOrMany<R extends ActiveRecord, Result> extends Relation<R, Result> {
+  readonly foreignKey: string;
+  readonly localKey: string;
+  constructor(parent: ActiveRecord, related: RecordClass<R>, foreignKey: string, localKey: string);
+  query(): QueryOf<R>;
+  protected loadFor(parents: ActiveRecord[], nested: string[]): Promise<Map<unknown, R[]>>;
+}
+declare class HasMany<R extends ActiveRecord> extends HasOneOrMany<R, R[]> {
+  get(): Promise<R[]>;
+  eagerLoad(parents: ActiveRecord[], name: string, nested: string[]): Promise<void>;
+}
+declare class HasOne<R extends ActiveRecord> extends HasOneOrMany<R, R | null> {
+  get(): Promise<R | null>;
+  eagerLoad(parents: ActiveRecord[], name: string, nested: string[]): Promise<void>;
+}
+declare class BelongsTo<R extends ActiveRecord> extends Relation<R, R | null> {
+  readonly foreignKey: string;
+  readonly ownerKey: string;
+  constructor(parent: ActiveRecord, related: RecordClass<R>, foreignKey: string, ownerKey: string);
+  query(): QueryOf<R>;
+  get(): Promise<R | null>;
+  eagerLoad(parents: ActiveRecord[], name: string, nested: string[]): Promise<void>;
+}
+/** 记录的字段名（SQL 模型为表的列，Mongo 模型为文档字段） */
+type FieldOf<R> = R extends {
+  readonly '~row': infer Row;
+} ? keyof Row & string : string;
+/** 记录上返回关联的方法名 */
+type OwnKey<M> = Exclude<keyof M, keyof ActiveRecord | `~${string}`>;
+type RelationName<M> = { [K in OwnKey<M>]: M[K] extends (() => Relation<any, any>) ? K : never; }[OwnKey<M>] & string;
+type RelationResult<F> = F extends (() => Relation<any, infer Result>) ? Result : never;
+/** 关联所需的类信息（构造器 + 查询入口） */
+type RecordClass<R extends ActiveRecord = ActiveRecord> = (new () => R) & {
+  readonly name: string;
+};
+type Hook = 'onBeforeWrite' | 'onAfterWrite' | 'onBeforeInsert' | 'onAfterInsert' | 'onBeforeUpdate' | 'onAfterUpdate' | 'onBeforeDelete' | 'onAfterDelete' | 'onBeforeRestore' | 'onAfterRestore';
+/**
+ * SQL 模型（Model）与 MongoDB 模型（MongoModel）共用的基类：
+ * 属性与脏检查、访问器 / 修改器、关联、序列化与事件。
+ *
+ * 内部状态使用 `$` 前缀的受保护字段，避免与真实字段名冲突。
+ */
+declare abstract class ActiveRecord<TRow extends object = any> {
+  /** 仅用于类型推导 */
+  readonly '~row': TRow;
+  /** 序列化时隐藏的字段 */
+  static hidden: readonly string[];
+  /** 序列化时追加的虚拟字段（需定义 getXxxAttr） */
+  static append: readonly string[];
+  protected $attributes: Record<string, unknown>;
+  protected $original: Record<string, unknown>;
+  protected $relations: Record<string, unknown>;
+  protected $exists: boolean;
+  /** 主键字段名（子类实现） */
+  static primaryKeyName(): string | undefined;
+  /** 由数据库行 / 文档构造已存在的记录 */
+  static hydrate<M extends ActiveRecord>(this: new () => M, row: Record<string, unknown>): M;
+  get exists(): boolean;
+  /** 主键值 */
+  getKey(): unknown;
+  /** 读取属性（经过 getXxxAttr 访问器） */
+  getAttr(key: string): unknown;
+  /** 写入属性（经过 setXxxAttr 修改器） */
+  setAttr(key: string, value: unknown): this;
+  /** 原始属性（不经过访问器） */
+  getRaw(key: string): unknown;
+  /** 批量赋值（SQL 模型忽略表中不存在的列） */
+  fill(data: Record<string, unknown>): this;
+  isDirty(key?: string): boolean;
+  /** 自上次同步以来修改过的字段 */
+  getDirty(): Record<string, unknown>;
+  getOriginal(key?: string): unknown;
+  /** 加载关联（可嵌套）：`await user.load('posts.comments')` */
+  load(...relations: Array<RelationName<this> | `${RelationName<this>}.${string}`>): Promise<this>;
+  /** 已加载的关联结果 */
+  getRelation<K extends RelationName<this>>(name: K): RelationResult<this[K]> | undefined;
+  setRelation(name: string, value: unknown): this;
+  protected hasMany<R>(related: new () => R, foreignKey: FieldOf<R>, localKey?: keyof TRow & string): HasMany<R & ActiveRecord>;
+  protected hasOne<R>(related: new () => R, foreignKey: FieldOf<R>, localKey?: keyof TRow & string): HasOne<R & ActiveRecord>;
+  protected belongsTo<R>(related: new () => R, foreignKey: keyof TRow & string, ownerKey?: FieldOf<R>): BelongsTo<R & ActiveRecord>;
+  /** 序列化：应用访问器、隐藏字段、追加字段与已加载的关联 */
+  toJSON(): Record<string, unknown>;
+  /** 是否接受批量赋值的字段 */
+  protected acceptsAttribute(_key: string): boolean;
+  protected runHook(name: Hook): Promise<void>;
+  /** 写入成功后同步原始值 */
+  protected syncOriginal(): void;
+}
+/** 通过品牌属性读取模型的表类型（避免结构比较时展开关联类型导致循环） */
+type TableOf<M> = M extends {
+  readonly '~table': infer T;
+} ? T : never;
+/**
+ * 泛型约束只检查品牌属性：用 `M extends Model` 会做结构比较，
+ * 在互相引用的模型之间展开关联类型导致循环
+ */
+interface ModelLike {
+  readonly '~table': any;
+}
+/** 模型类（构造器 + 静态配置） */
+type ModelClass<M extends ModelLike = Model<any>> = (new () => M) & ModelSettings;
+type WhereArgs<T extends Table> = [condition: WhereCondition<T>] | [column: ColumnKey<T>, value: unknown] | [column: ColumnKey<T>, operator: Operator, value: unknown];
+/** Model.define(table) 返回的基类：实例拥有表的全部列属性 */
+type DefinedModel<T extends Table> = Omit<typeof Model, 'prototype'> & (new () => Model<T> & Row$1<T>);
+/**
+ * ThinkPHP 风格模型，表结构来自 drizzle：
+ *
+ * ```ts
+ * export class User extends Model.define(users) {
+ *   static override softDelete = true
+ *   static override hidden = ['password']
+ *
+ *   posts() {
+ *     return this.hasMany(Post, 'userId')
+ *   }
+ *
+ *   static scopeActive(query: ModelQuery<User>) {
+ *     query.where('status', 1)
+ *   }
+ * }
+ *
+ * const user = await User.findOrFail(1)
+ * user.name = 'Ada'
+ * await user.save()
+ * await User.where('status', 1).with('posts').order('id', 'desc').paginate(1, 20)
+ * ```
+ *
+ * 访问器 / 修改器：定义 `getNameAttr(value, data)` / `setNameAttr(value, data)`；
+ * 事件：定义 `onBeforeInsert()`、`onAfterUpdate()` 等方法。
+ */
+declare class Model<T extends Table = Table> extends ActiveRecord<Row$1<T>> {
+  #private;
+  /** 仅用于类型推导 */
+  readonly '~table': T;
+  static table: Table;
+  /** 使用的连接名，默认使用 config/database.ts 的 default */
+  static connection: string | undefined;
+  /** 软删除：true 使用 deletedAt 列，或指定列名 */
+  static softDelete: boolean | string;
+  /** 自动维护 createdAt / updatedAt（列存在时），可指定列名或设为 false */
+  static timestamps: boolean | TimestampOptions;
+  /** 声明模型对应的表：`class User extends Model.define(users) {}` */
+  static define<T extends Table>(table: T): DefinedModel<T>;
+  static primaryKeyName(): string | undefined;
+  static query<M extends ModelLike>(this: ModelClass<M>): ModelQuery<M>;
+  static where<M extends ModelLike>(this: ModelClass<M>, ...args: WhereArgs<TableOf<M> & Table>): ModelQuery<M>;
+  static whereIn<M extends ModelLike, K extends ColumnKey<TableOf<M> & Table>>(this: ModelClass<M>, column: K, values: ReadonlyArray<Row$1<TableOf<M> & Table>[K]>): ModelQuery<M>;
+  static order<M extends ModelLike>(this: ModelClass<M>, column: ColumnKey<TableOf<M> & Table>, direction?: 'asc' | 'desc'): ModelQuery<M>;
+  static with<M extends ModelLike>(this: ModelClass<M>, ...relations: Array<RelationName<M> | `${RelationName<M>}.${string}`>): ModelQuery<M>;
+  static scope<M extends ModelLike>(this: ModelClass<M>, name: string, ...args: unknown[]): ModelQuery<M>;
+  static withTrashed<M extends ModelLike>(this: ModelClass<M>): ModelQuery<M>;
+  static onlyTrashed<M extends ModelLike>(this: ModelClass<M>): ModelQuery<M>;
+  static find<M extends ModelLike>(this: ModelClass<M>, id: unknown): Promise<M | undefined>;
+  static findOrFail<M extends ModelLike>(this: ModelClass<M>, id: unknown): Promise<M>;
+  static all<M extends ModelLike>(this: ModelClass<M>): Promise<M[]>;
+  static paginate<M extends ModelLike>(this: ModelClass<M>, page?: number, perPage?: number): Promise<Paginated<M>>;
+  static count<M extends ModelLike>(this: ModelClass<M>): Promise<number>;
+  /** 创建并保存（会触发事件与时间戳） */
+  static create<M extends ModelLike>(this: ModelClass<M>, data: Partial<Insert<TableOf<M> & Table>>): Promise<M>;
+  /** 按主键删除（逐个触发事件与软删除），返回删除数量 */
+  static destroy<M extends ModelLike>(this: ModelClass<M>, ids: unknown | unknown[]): Promise<number>;
+  /** 新模型插入，已存在模型更新修改过的字段 */
+  save(): Promise<this>;
+  /** 删除：启用软删除时只标记删除时间 */
+  delete(): Promise<boolean>;
+  /** 物理删除 */
+  forceDelete(): Promise<boolean>;
+  /** 恢复软删除 */
+  restore(): Promise<this>;
+  trashed(): boolean;
+  /** 从数据库重新读取 */
+  refresh(): Promise<this>;
+  protected acceptsAttribute(key: string): boolean;
+}
+export { TimestampOptions as $, DatabaseConfig as A, DefinedMongoModel as B, setDatabaseManager as C, DatabaseManager as D, Connection as E, MongoModelQuery as F, MongoModelSettings as G, MongoModel as H, MongoQuery as I, MongoSession as J, hydrateMongoModel as K, MongoQueryOptions as L, Driver as M, defineDatabaseConfig as N, DatabaseManagerOptions as O, dialectOf as P, ModelSettings as Q, MongoWhere as R, resolveSession as S, useDatabaseManager as T, MongoModelClass as U, DocOf as V, MongoModelMeta as W, resolveMongo as X, mongoTransaction as Y, ModelMeta as Z, ModelQuery as _, TableOf as a, Direction as at, WriteOptions as b, RecordClass as c, Paginated as ct, BelongsTo as d, Conditions as et, HasMany as f, RelationQuery as g, Relation as h, ModelLike as i, ColumnKey as it, Dialect as j, ConnectionConfig as k, RelationName as l, Row$1 as lt, QueryOf as m, Model as n, WhereObject as nt, ActiveRecord as o, Insert as ot, HasOne as p, metaOfMongo as q, ModelClass as r, AnyDatabase as rt, FieldOf as s, Operator as st, DefinedModel as t, WhereCondition as tt, RelationResult as u, QueryBuilder as v, transaction as w, Session as x, QueryOptions as y, toObjectId as z };