@lara-node/db 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1635 @@
+import mysql, { Pool, PoolConnection } from "mysql2/promise";
+import { ClientSession, Collection, Db, Document } from "mongodb";
+import util from "util";
+import { ServiceProvider } from "@lara-node/core";
+
+//#region src/connection.d.ts
+declare function getDbType(): "mysql" | "mongodb";
+declare function query<T = any>(sql: string, params?: any[]): Promise<T[]>;
+declare function initDatabase(): Promise<void>;
+declare function getPool(): mysql.Pool;
+declare function getMongoDb(): Db;
+declare function collection(name: string): Collection<Document>;
+//#endregion
+//#region src/DB.d.ts
+/**
+ * Base transaction interface with common methods
+ */
+interface ITransaction {
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+  isActive(): boolean;
+}
+/**
+ * MySQL Transaction interface
+ */
+interface IMysqlTransaction extends ITransaction {
+  query<T = any>(sql: string, bindings?: any[]): Promise<T[]>;
+  select<T = any>(sql: string, bindings?: any[]): Promise<T[]>;
+  insert(sql: string, bindings?: any[]): Promise<number>;
+  update(sql: string, bindings?: any[]): Promise<number>;
+  delete(sql: string, bindings?: any[]): Promise<number>;
+  statement(sql: string, bindings?: any[]): Promise<boolean>;
+  getConnection(): PoolConnection;
+  release(): void;
+}
+/**
+ * MongoDB Transaction interface
+ */
+interface IMongoTransaction extends ITransaction {
+  collection<T extends Document = Document>(name: string): Collection<T>;
+  getSession(): ClientSession;
+  endSession(): void;
+}
+/**
+ * Transaction class for managing MySQL database transactions
+ */
+declare class Transaction implements IMysqlTransaction {
+  private connection;
+  private committed;
+  private rolledBack;
+  constructor(connection: PoolConnection);
+  query<T = any>(sql: string, bindings?: any[]): Promise<T[]>;
+  select<T = any>(sql: string, bindings?: any[]): Promise<T[]>;
+  insert(sql: string, bindings?: any[]): Promise<number>;
+  update(sql: string, bindings?: any[]): Promise<number>;
+  delete(sql: string, bindings?: any[]): Promise<number>;
+  statement(sql: string, bindings?: any[]): Promise<boolean>;
+  getConnection(): PoolConnection;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+  isActive(): boolean;
+  release(): void;
+}
+/**
+ * MongoDB Transaction class
+ */
+declare class MongoTransaction implements IMongoTransaction {
+  private session;
+  private db;
+  private committed;
+  private rolledBack;
+  constructor(session: ClientSession, db: Db);
+  collection<T extends Document = Document>(name: string): Collection<T>;
+  getSession(): ClientSession;
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+  isActive(): boolean;
+  endSession(): void;
+}
+/**
+ * Unified Transaction type
+ */
+type UnifiedTransaction = Transaction | MongoTransaction;
+/**
+ * Transaction callback types
+ */
+
+type MysqlTransactionCallback<T> = (trx: IMysqlTransaction) => Promise<T>;
+type MongoTransactionCallback<T> = (trx: IMongoTransaction) => Promise<T>;
+type UnifiedTransactionCallback<T> = (trx: UnifiedTransaction) => Promise<T>;
+/**
+ * Query binding types
+ */
+
+/**
+ * DB Facade - Main entry point for database operations
+ * Automatically handles both MySQL and MongoDB based on configuration
+ *
+ * Supports Laravel-style transactions where Model operations automatically
+ * use the active transaction:
+ *
+ * @example
+ * await DB.beginTransaction();
+ * try {
+ *   await User.create({ name: 'John' }); // Uses the transaction
+ *   await user.save(); // Uses the transaction
+ *   await DB.commit();
+ * } catch (e) {
+ *   await DB.rollback();
+ * }
+ */
+declare class DB {
+  private static currentMysqlTransaction;
+  private static currentMongoTransaction;
+  private static transactionLevel;
+  /**
+   * Execute a query using the current transaction if one exists, otherwise use the pool.
+   * Emits a `db:query` event via the application EventDispatcher so Telescope and
+   * other listeners can observe all database activity without modifying call sites.
+   */
+  static executeQuery<T = any>(sql: string, params?: any[]): Promise<T[]>;
+  /**
+   * Execute a raw SQL query (MySQL only)
+   */
+  static query<T = any>(sql: string, bindings?: any[]): Promise<T[]>;
+  /**
+   * Execute a raw SELECT query (MySQL only)
+   */
+  static select<T = any>(sql: string, bindings?: any[]): Promise<T[]>;
+  /**
+   * Execute a raw INSERT query (MySQL only)
+   */
+  static insert(sql: string, bindings?: any[]): Promise<number>;
+  /**
+   * Execute a raw UPDATE query (MySQL only)
+   */
+  static update(sql: string, bindings?: any[]): Promise<number>;
+  /**
+   * Execute a raw DELETE query (MySQL only)
+   */
+  static delete(sql: string, bindings?: any[]): Promise<number>;
+  /**
+   * Execute a statement (for DDL or other non-returning queries) - MySQL only
+   */
+  static statement(sql: string, bindings?: any[]): Promise<boolean>;
+  /**
+   * Execute an unprepared query (without parameter binding) - MySQL only
+   */
+  static unprepared(sql: string): Promise<boolean>;
+  /**
+   * Start a query on a table - returns EloquentBuilder for the table
+   * Note: For raw table queries without a Model, use DB.query() with raw SQL
+   */
+  static table(name: string): {
+    where: (column: string, operatorOrValue: any, value?: any) => any;
+    insert: (data: Record<string, any>) => Promise<number>;
+    update: (data: Record<string, any>) => Promise<number>;
+    delete: () => Promise<number>;
+    get: () => Promise<any[]>;
+    first: () => Promise<any>;
+    count: () => Promise<number>;
+  };
+  /**
+   * Get a MongoDB collection (MongoDB only).
+   * The returned collection is transparently proxied so every operation
+   * (find, insertOne, updateMany, aggregate, …) emits a `db:query` event
+   * that Telescope's QueryWatcher captures.
+   */
+  static collection<T extends Document = Document>(name: string): Collection<T>;
+  /**
+  /** Delegates to the shared QueryInstrumentation proxy (same logic as db.config.ts:collection). */
+  private static instrumentMongoCollection;
+  /**
+   * Get the current MongoDB session options for use in queries
+   * Returns an object with { session } if in a transaction, or empty object
+   * This allows MongoDB operations to automatically use the transaction
+   *
+   * @example
+   * const collection = DB.collection('users');
+   * await collection.insertOne({ name: 'John' }, DB.getSessionOptions());
+   */
+  static getSessionOptions(): {
+    session?: ClientSession;
+  };
+  /**
+   * Execute a MongoDB operation with the current transaction session if available
+   * This is the main method that Models should use for MongoDB operations
+   *
+   * @example
+   * await DB.withSession(async (sessionOpts) => {
+   *   await collection.insertOne({ name: 'John' }, sessionOpts);
+   * });
+   */
+  static withSession<T>(callback: (sessionOptions: {
+    session?: ClientSession;
+  }) => Promise<T>): Promise<T>;
+  /**
+   * Begin a database transaction (auto-detects database type)
+   */
+  static beginTransaction(): Promise<UnifiedTransaction>;
+  /**
+   * Alias for beginTransaction
+   */
+  static begin(): Promise<UnifiedTransaction>;
+  /**
+   * Commit the current transaction
+   */
+  static commit(): Promise<void>;
+  /**
+   * Rollback the current transaction
+   */
+  static rollback(): Promise<void>;
+  /**
+   * Execute a callback within a transaction (auto-detects database type)
+   * Automatically commits on success, rolls back on error
+   *
+   * @example
+   * // Models automatically use the active transaction
+   * await DB.transaction(async () => {
+   *   await User.create({ name: 'John' });
+   *   await Invoice.create({ user_id: 1, amount: 100 });
+   * });
+   */
+  static transaction<T>(callback: UnifiedTransactionCallback<T> | (() => Promise<T>)): Promise<T>;
+  /**
+   * Execute a callback within a MySQL transaction (type-safe)
+   */
+  static mysqlTransaction<T>(callback: MysqlTransactionCallback<T>): Promise<T>;
+  /**
+   * Execute a callback within a MongoDB transaction (type-safe)
+   */
+  static mongoTransaction<T>(callback: MongoTransactionCallback<T>): Promise<T>;
+  /**
+   * Get the current transaction level
+   */
+  static getTransactionLevel(): number;
+  /**
+   * Check if currently in a transaction
+   */
+  static inTransaction(): boolean;
+  /**
+   * Get the current active transaction (if any)
+   */
+  static getCurrentTransaction(): UnifiedTransaction | null;
+  /**
+   * Get the current MySQL transaction (type-safe)
+   */
+  static getMysqlTransaction(): Transaction | null;
+  /**
+   * Get the current MongoDB transaction (type-safe)
+   */
+  static getMongoTransaction(): MongoTransaction | null;
+  /**
+   * Get the current MySQL connection (from transaction or null)
+   */
+  static getActiveConnection(): PoolConnection | null;
+  /**
+   * Get the current MongoDB session (from transaction or null)
+   */
+  static getActiveSession(): ClientSession | null;
+  /**
+   * Check if a value is a MySQL Transaction
+   */
+  static isTransaction(trx: any): trx is Transaction;
+  /**
+   * Check if a value is a MongoDB Transaction
+   */
+  static isMongoTransaction(trx: any): trx is MongoTransaction;
+  /**
+   * Get the database type (mysql or mongodb)
+   */
+  static getType(): "mysql" | "mongodb";
+  /**
+   * Check if using MySQL
+   */
+  static isMysql(): boolean;
+  /**
+   * Check if using MongoDB
+   */
+  static isMongo(): boolean;
+  /**
+   * Get the underlying connection pool (MySQL only)
+   */
+  static getPool(): Pool;
+  /**
+   * Get the MongoDB database instance
+   */
+  static getMongoDb(): Db;
+  /**
+   * Create a raw expression (to use raw SQL in queries)
+   */
+  static raw(value: string): {
+    __raw: true;
+    value: string;
+  };
+  /**
+   * Escape a value for safe use in queries (MySQL only)
+   */
+  static escape(value: any): string;
+  /**
+   * Quote a table or column name (MySQL only)
+   */
+  static quoteName(name: string): string;
+  /**
+   * Listen for query events (placeholder for query logging)
+   */
+  static listen(_callback: (query: {
+    sql: string;
+    bindings: any[];
+    time: number;
+  }) => void): void;
+}
+//#endregion
+//#region src/EloquentBuilder.d.ts
+declare class EloquentBuilder<T extends Model> {
+  private model;
+  private withRelations;
+  private nestedRelations;
+  private relationPathOptions;
+  private relationTree;
+  private whereClauses;
+  private havingClauses;
+  private joinClauses;
+  private limitValue?;
+  private offsetValue?;
+  private orderByColumn?;
+  private orderByDirection;
+  private groupByColumns;
+  private hasConditions;
+  private selectedColumns?;
+  private distinctValue;
+  private includeTrashed;
+  private appliedSoftDeleteFilter;
+  private onlyTrashedFlag;
+  private columnQualifier?;
+  private appliedScopes;
+  private removedScopes;
+  constructor(model: typeof Model);
+  /**
+   * Execute a SQL query using the active transaction if available
+   * This ensures all EloquentBuilder queries are transaction-aware
+   */
+  private runQuery;
+  /**
+   * Get MongoDB session options for transaction support
+   * Returns { session } if in a transaction, or empty object
+   */
+  private getMongoSessionOptions;
+  getRelationTree(): Record<string, any>;
+  withTrashed(): this;
+  /**
+   * Apply a named scope
+   */
+  namedScope(name: string, ...args: any[]): this;
+  /**
+   * Alias for namedScope
+   */
+  scope(name: string, ...args: any[]): this;
+  /**
+   * Apply multiple scopes
+   */
+  scopes(scopes: {
+    [name: string]: any[];
+  }): this;
+  /**
+   * Get applied scopes
+   */
+  getAppliedScopes(): string[];
+  /**
+   * Check if a scope has been applied
+   */
+  hasScope(name: string): boolean;
+  /**
+   * Remove a scope
+   */
+  withoutScope(name: string): this;
+  withThrashed(): this;
+  withoutTrashed(): this;
+  withoutThrashed(): this;
+  onlyTrashed(): this;
+  onlyThrashed(): this;
+  with(relations: string | string[] | Record<string, any>): this;
+  select(columns: string[] | string): this;
+  addSelect(columns: string[] | string): this;
+  distinct(): this;
+  where(column: string | ((builder: EloquentBuilder<T>) => void), operator?: any, value?: any): this;
+  orWhere(column: string | ((builder: EloquentBuilder<T>) => void), operator?: any, value?: any): this;
+  whereIn(column: string, values: any[]): this;
+  whereNotIn(column: string, values: any[]): this;
+  whereNull(column: string): this;
+  whereNotNull(column: string): this;
+  whereBetween(column: string, range: [any, any]): this;
+  whereNotBetween(column: string, range: [any, any]): this;
+  whereHas(relation: string, callback?: (query: EloquentBuilder<any>) => void, operator?: string, count?: number): this;
+  orWhereHas(relation: string, callback?: (query: EloquentBuilder<any>) => void, operator?: string, count?: number): this;
+  whereDoesntHave(relation: string, callback?: (query: EloquentBuilder<any>) => void): this;
+  join(table: string, first: string, operator: string, second: string, type?: "inner" | "left" | "right" | "cross"): this;
+  leftJoin(table: string, first: string, operator: string, second: string): this;
+  groupBy(columns: string | string[]): this;
+  having(column: string, operator: string, value: any): this;
+  limit(limit: number): this;
+  offset(offset: number): this;
+  orderBy(column: string, direction?: "asc" | "desc"): this;
+  latest(column?: string): this;
+  oldest(column?: string): this;
+  rightJoin(table: string, first: string, operator: string, second: string): this;
+  crossJoin(table: string): this;
+  orWhereNull(column: string): this;
+  orWhereNotNull(column: string): this;
+  orWhereIn(column: string, values: any[]): this;
+  orWhereNotIn(column: string, values: any[]): this;
+  orWhereBetween(column: string, range: [any, any]): this;
+  orWhereNotBetween(column: string, range: [any, any]): this;
+  whereLike(column: string, value: string): this;
+  whereNotLike(column: string, value: string): this;
+  orWhereLike(column: string, value: string): this;
+  orWhereNotLike(column: string, value: string): this;
+  whereRaw(sql: string, bindings?: any[]): this;
+  orWhereRaw(sql: string, bindings?: any[]): this;
+  /** Apply callback only when condition is truthy. */
+  when<V = boolean>(condition: V, callback: (builder: this, value: NonNullable<V>) => void, elseCallback?: (builder: this) => void): this;
+  /** Apply callback only when condition is falsy (inverse of when). */
+  unless<V = boolean>(condition: V, callback: (builder: this) => void): this;
+  /** Inspect the builder without interrupting the chain. */
+  tap(callback: (builder: this) => void): this;
+  /** Return a deep copy of this builder so mutations don't affect the original. */
+  clone(): EloquentBuilder<T>;
+  /** Shorthand for .where(column, op?, value).first() */
+  firstWhere(column: string | ((builder: EloquentBuilder<T>) => void), operator?: any, value?: any): Promise<T | null>;
+  /** Retrieve a single column value from the first matching row. */
+  value(column: string): Promise<any>;
+  /**
+   * Return the only record matching the query.
+   * Throws if zero or more than one records are found.
+   */
+  sole(): Promise<T>;
+  /** Pluck a single column into an array, optionally keyed by another column. */
+  pluck(column: string, key?: string): Promise<any[] | Record<string, any>>;
+  /**
+   * Process matching records in chunks to avoid loading everything into memory.
+   * Callback receives a page of records; return false to stop early.
+   */
+  chunk(size: number, callback: (rows: T[], page: number) => boolean | void | Promise<boolean | void>): Promise<void>;
+  /**
+   * Like chunk() but advances via the primary key for stability on live tables.
+   */
+  chunkById(size: number, callback: (rows: T[], page: number) => boolean | void | Promise<boolean | void>, column?: string): Promise<void>;
+  /** Async generator that yields results one at a time without holding all in memory. */
+  cursor(): AsyncGenerator<T>;
+  /** Return the SQL string (with ? placeholders) without executing the query. */
+  toSql(): string;
+  /**
+   * Return the MongoDB query descriptor without executing — the Mongo equivalent of toSql().
+   *
+   * Returns:
+   *   collection  — collection name derived from the model's table
+   *   filter      — MongoDB filter document (the full $and/$or object)
+   *   sort        — e.g. { created_at: -1 }  (only present when orderBy is set)
+   *   limit       — cursor limit              (only present when limit() was called)
+   *   skip        — cursor skip offset        (only present when offset() was called)
+   *   projection  — { col: 1 } map            (only present when select() was called)
+   */
+  toMongo(): {
+    collection: string;
+    filter: Record<string, any>;
+    sort?: Record<string, 1 | -1>;
+    limit?: number;
+    skip?: number;
+    projection?: Record<string, 1>;
+  };
+  get(): Promise<T[]>;
+  toArray(): Promise<any[]>;
+  first(): Promise<T | null>;
+  firstOrFail(): Promise<T>;
+  paginate(perPage?: number, page?: number): Promise<QueryResult<T>>;
+  count(column?: string): Promise<number>;
+  max(column: string): Promise<number>;
+  min(column: string): Promise<number>;
+  avg(column: string): Promise<number>;
+  sum(column: string): Promise<number>;
+  exists(): Promise<boolean>;
+  doesntExist(): Promise<boolean>;
+  find(id: number | string): Promise<T | null>;
+  findOrFail(id: number | string): Promise<T>;
+  all(): Promise<T[]>;
+  create(attributes: Record<string, any>): Promise<T>;
+  createMany(rows: Array<Record<string, any>>): Promise<T[]>;
+  /**
+   * Find a model matching the current query conditions or create a new one, then update with values
+   * @param values - The values to update or create the model with
+   * @param createAttributes - Additional attributes to use when creating a new record
+   * @returns The model instance (existing or newly created)
+   */
+  updateOrCreate(values?: Record<string, any>, createAttributes?: Record<string, any>): Promise<T>;
+  /**
+   * Alias for updateOrCreate method
+   * @param values - The values to update or create the model with
+   * @param createAttributes - Additional attributes to use when creating a new record
+   * @returns The model instance (existing or newly created)
+   */
+  createOrUpdate(values?: Record<string, any>, createAttributes?: Record<string, any>): Promise<T>;
+  update(values: Partial<Record<string, any>>): Promise<number>;
+  increment(column: string, amount?: number): Promise<number>;
+  decrement(column: string, amount?: number): Promise<number>;
+  delete(): Promise<number>;
+  insert(rows: Array<Record<string, any>>): Promise<number>;
+  insertGetId(row: Record<string, any>): Promise<number>;
+  has(relation: string, operator?: string, count?: number): this;
+  doesntHave(relation: string): this;
+  withCount(relations: string | string[]): this;
+  private aggregate;
+  private buildWhereClause;
+  private buildNestedWhere;
+  private getWhereClauses;
+  private buildHasConditionsSQL;
+  private applyHasConditionsMongo;
+  private executeQuery;
+  private getCount;
+  private loadRelationships;
+  private loadRelationTree;
+  private setRelation;
+  loadRelationship(models: T[], relation: string, options?: EagerLoadOptions): Promise<void>;
+  private loadHasOne;
+  private loadHasMany;
+  private loadBelongsTo;
+  private loadBelongsToMany;
+  private loadBelongsToManyMongo;
+  private loadMorphRelations;
+  private normalizeField;
+  private coerceId;
+  private isIdLikeField;
+  private coerceForField;
+  private expandIdForms;
+  /**
+   * Check if a document matches a MongoDB filter object in memory.
+   * Used for OR hasConditions where we need to verify if a doc matched the original where filter.
+   */
+  private docMatchesMongoFilter;
+  private buildMongoFilter;
+  private executeQueryMongo;
+  private updateMongo;
+  private deleteMongo;
+  private insertMongoMany;
+  private countMongo;
+  private aggregateMongo;
+  private loadHasOneMongo;
+  private loadHasManyMongo;
+  private loadBelongsToMongo;
+  private loadBelongsToManyMongo_;
+  private loadMorphRelationsMongo;
+}
+//# sourceMappingURL=EloquentBuilder.d.ts.map
+//#endregion
+//#region src/types.d.ts
+interface ModelAttributes {
+  [key: string]: any;
+}
+interface RelationshipConfig {
+  type: "hasOne" | "hasMany" | "belongsTo" | "belongsToMany" | "morphOne" | "morphMany" | "hasOneThrough" | "hasManyThrough";
+  model: typeof Model;
+  foreignKey?: string;
+  localKey?: string;
+  ownerKey?: string;
+  relatedKey?: string;
+  morphName?: string;
+  table?: string;
+  through?: typeof Model;
+  pivotModel?: typeof Model;
+  secondKey?: string;
+  secondLocalKey?: string;
+}
+interface Casts {
+  [key: string]: string | Function;
+}
+interface QueryResult<T> {
+  data: T[];
+  total?: number;
+  pagination?: {
+    currentPage: number;
+    perPage: number;
+    total: number;
+    lastPage: number;
+  };
+}
+interface EagerLoadOptions {
+  constraints?: (builder: EloquentBuilder<any>) => void;
+  columns?: string[];
+}
+//# sourceMappingURL=types.d.ts.map
+//#endregion
+//#region src/relationships.d.ts
+declare abstract class Relation<T extends Model> {
+  protected builder: EloquentBuilder<T>;
+  protected parent: Model;
+  protected related: typeof Model;
+  constructor(related: typeof Model, parent: Model);
+  abstract getResults(): Promise<T | T[] | null>;
+  then<TResult1 = T | T[] | null, TResult2 = never>(onfulfilled?: ((value: T | T[] | null) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+  catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<T | T[] | null | TResult>;
+  finally(onfinally?: (() => void) | null): Promise<T | T[] | null>;
+  protected applyConstraints(): boolean;
+  /**
+   * Return the underlying EloquentBuilder with the FK constraint pre-applied.
+   * Use this to chain additional builder methods before executing:
+   *   user.posts().query().where('published', 1).orderBy('created_at').get()
+   */
+  query(): EloquentBuilder<T>;
+  /**
+   * Execute the relation query and return all matching model instances.
+   *   await user.posts().get()
+   *   await user.posts().where('published', 1).get()
+   */
+  get(): Promise<T[]>;
+  first(): Promise<T | null>;
+  firstOrFail(): Promise<T>;
+  paginate(perPage?: number, page?: number): Promise<QueryResult<T>>;
+  pluck(column: string, key?: string): Promise<any[] | Record<string, any>>;
+  value(column: string): Promise<any>;
+  sole(): Promise<T>;
+  count(): Promise<number>;
+  exists(): Promise<boolean>;
+  doesntExist(): Promise<boolean>;
+  where(column: string, operator?: any, value?: any): this;
+  orWhere(column: string, operator?: any, value?: any): this;
+  whereIn(column: string, values: any[]): this;
+  whereNotIn(column: string, values: any[]): this;
+  whereNull(column: string): this;
+  whereNotNull(column: string): this;
+  orderBy(column: string, direction?: "asc" | "desc"): this;
+  latest(column?: string): this;
+  oldest(column?: string): this;
+  limit(limit: number): this;
+  offset(offset: number): this;
+  with(relations: string | string[] | Record<string, any>): this;
+  select(columns: string[] | string): this;
+  getQuery(): EloquentBuilder<T>;
+}
+declare class HasOne<T extends Model> extends Relation<T> {
+  protected relatedModel: typeof Model;
+  protected foreignKey: string;
+  protected localKey: string;
+  private defaultAttributes?;
+  private fkApplied;
+  constructor(relatedModel: typeof Model, foreignKey: string, localKey: string | undefined, parent: Model);
+  /**
+   * Apply the FK constraint exactly once; subsequent calls are no-ops.
+   * This prevents duplicate WHERE clauses when getResults()/first() are
+   * called more than once on the same relation instance.
+   */
+  protected applyFk(): boolean;
+  protected applyConstraints(): boolean;
+  getResults(): Promise<T | null>;
+  first(): Promise<T | null>;
+  /**
+   * Provide a default model when the relation returns null.
+   * Pass `true` for an empty instance, or a plain object for pre-filled attributes.
+   *
+   * @example user.profile().withDefault({ gender: 'unknown' })
+   */
+  withDefault(attributes?: Record<string, any> | true): this;
+  private resolveDefault;
+  create(attributes: Record<string, any>): Promise<T>;
+  update(attributes: Record<string, any>): Promise<number>;
+  save(model: T): Promise<T>;
+  associate(model: T | null): Promise<void>;
+  dissociate(): Promise<void>;
+}
+declare class HasMany<T extends Model> extends Relation<T> {
+  protected relatedModel: typeof Model;
+  protected foreignKey: string;
+  protected localKey: string;
+  private fkApplied;
+  constructor(relatedModel: typeof Model, foreignKey: string, localKey: string | undefined, parent: Model);
+  protected applyFk(): boolean;
+  protected applyConstraints(): boolean;
+  getResults(): Promise<T[]>;
+  first(): Promise<T | null>;
+  create(attributes: Record<string, any>): Promise<T>;
+  createMany(rows: Array<Record<string, any>>): Promise<T[]>;
+  save(model: T): Promise<T>;
+  attach(model: T | number | string): Promise<void>;
+  detach(model?: T | number | string): Promise<number>;
+  sync(models: (T | number | string)[], detaching?: boolean): Promise<{
+    attached: any[];
+    detached: any[];
+    updated: any[];
+  }>;
+}
+declare class BelongsTo<T extends Model> extends Relation<T> {
+  private relatedModel;
+  private foreignKey;
+  private ownerKey;
+  private defaultAttributes?;
+  private fkApplied;
+  constructor(relatedModel: typeof Model, foreignKey: string, ownerKey: string | undefined, parent: Model);
+  protected applyFk(): boolean;
+  protected applyConstraints(): boolean;
+  getResults(): Promise<T | null>;
+  first(): Promise<T | null>;
+  withDefault(attributes?: Record<string, any> | true): this;
+  private resolveDefault;
+  associate(model: T | number | string | null): Promise<void>;
+  dissociate(): Promise<void>;
+  update(attributes: Record<string, any>): Promise<number>;
+}
+declare class BelongsToMany<T extends Model> extends Relation<T> {
+  private relatedModel;
+  private pivotTable;
+  private foreignPivotKey;
+  private relatedPivotKey;
+  private parentPrimaryKey;
+  private relatedPrimaryKey;
+  pivotModel?: typeof Model | undefined;
+  private pivotColumns;
+  private pivotWheres;
+  constructor(relatedModel: typeof Model, pivotTable: string, foreignPivotKey: string, relatedPivotKey: string, parentPrimaryKey: string | undefined, relatedPrimaryKey: string | undefined, parent: Model, pivotModel?: typeof Model | undefined);
+  /** Returns true when the pivot model has the SoftDeletes trait applied */
+  private get pivotSoftDeletes();
+  /**
+   * Build the extra WHERE conditions from the pivot model's soft deletes + global scopes (SQL).
+   * Returns { sql, params } where sql is a fragment like ' AND deleted_at IS NULL AND ...'
+   */
+  private buildPivotModelFiltersSQL;
+  /**
+   * Build the extra filter conditions from the pivot model's soft deletes + global scopes (MongoDB).
+   */
+  private buildPivotModelFiltersMongo;
+  getResults(): Promise<T[]>;
+  get(): Promise<T[]>;
+  withPivot(...columns: string[]): this;
+  wherePivot(column: string, operator: any, value?: any): this;
+  attach(relatedId: number | string | Record<string, any> | (number | string | Record<string, any>)[], extra?: Record<string, any>): Promise<void>;
+  detach(relatedIds?: (number | string)[]): Promise<number>;
+  sync(relatedIds: (number | string | Record<string, any>)[], detaching?: boolean): Promise<{
+    attached: any[];
+    detached: any[];
+    updated: any[];
+  }>;
+  toggle(relatedIds: (number | string)[]): Promise<{
+    attached: any[];
+    detached: any[];
+  }>;
+  updateExistingPivot(relatedId: number | string, attributes: Record<string, any>): Promise<number>;
+  private createPivot;
+}
+/**
+ * HasOneThrough — reach a distant model through an intermediate one.
+ *
+ * Example: User hasOneThrough(Insurance, Policy, 'user_id', 'policy_id', 'id', 'id')
+ *   users → policies (via policies.user_id) → insurances (via insurances.policy_id)
+ */
+declare class HasOneThrough<T extends Model> extends Relation<T> {
+  protected relatedModel: typeof Model;
+  protected throughModel: typeof Model;
+  protected firstKey: string;
+  protected secondKey: string;
+  protected localKey: string;
+  protected secondLocalKey: string;
+  constructor(relatedModel: typeof Model, throughModel: typeof Model, firstKey: string, secondKey: string, localKey: string | undefined, secondLocalKey: string | undefined, parent: Model);
+  getResults(): Promise<T | null>;
+  get(): Promise<T[]>;
+  first(): Promise<T | null>;
+}
+/**
+ * HasManyThrough — reach many distant models through an intermediate one.
+ *
+ * Example: Country hasManyThrough(Post, User, 'country_id', 'user_id', 'id', 'id')
+ *   countries → users (via users.country_id) → posts (via posts.user_id)
+ */
+declare class HasManyThrough<T extends Model> extends Relation<T> {
+  protected relatedModel: typeof Model;
+  protected throughModel: typeof Model;
+  protected firstKey: string;
+  protected secondKey: string;
+  protected localKey: string;
+  protected secondLocalKey: string;
+  constructor(relatedModel: typeof Model, throughModel: typeof Model, firstKey: string, secondKey: string, localKey: string | undefined, secondLocalKey: string | undefined, parent: Model);
+  getResults(): Promise<T[]>;
+  get(): Promise<T[]>;
+  first(): Promise<T | null>;
+}
+//#endregion
+//#region src/interfaces.d.ts
+interface ModelEvents {
+  creating: ((model: Model) => void | Promise<void>)[];
+  created: ((model: Model) => void | Promise<void>)[];
+  updating: ((model: Model) => void | Promise<void>)[];
+  updated: ((model: Model) => void | Promise<void>)[];
+  saving: ((model: Model) => void | Promise<void>)[];
+  saved: ((model: Model) => void | Promise<void>)[];
+  deleting: ((model: Model) => void | Promise<void>)[];
+  deleted: ((model: Model) => void | Promise<void>)[];
+  restoring: ((model: Model) => void | Promise<void>)[];
+  restored: ((model: Model) => void | Promise<void>)[];
+  retrieved: ((model: Model) => void | Promise<void>)[];
+}
+interface ToJSONOptions {
+  maxDepth?: number;
+  currentDepth?: number;
+  visited?: WeakSet<any>;
+  include?: string[];
+  exclude?: string[];
+  withRelations?: boolean;
+  includeMetadata?: boolean;
+  relationTree?: any;
+  withAccessors?: boolean;
+  onlyAppended?: boolean;
+}
+//# sourceMappingURL=interfaces.d.ts.map
+//#endregion
+//#region src/Traits/traits.d.ts
+interface ScopeMethod<T extends Model> {
+  (builder: EloquentBuilder<T>, ...args: any[]): void;
+}
+interface ClassBasedTrait {
+  new (): any;
+  boot?(model: typeof Model): void;
+}
+/**
+ * Register a trait globally by name
+ */
+
+/**
+ * Apply traits to a model class (supports both string names and classes)
+ */
+declare function applyTraits(modelClass: typeof Model, traitNamesOrClasses: Array<string | ClassBasedTrait>): void;
+/**
+ * Define a scope trait
+ */
+//#endregion
+//#region src/Traits/helper.d.ts
+/** Merges the static/instance surface of all applied trait classes onto MClass. */
+type AttachTraits<MClass, Traits extends readonly any[]> = Traits extends readonly [infer Head, ...infer Tail] ? AttachTraits<MClass & (Head extends (new (...args: any[]) => infer I) ? I : Head), Tail> : MClass;
+//# sourceMappingURL=helper.d.ts.map
+//#endregion
+//#region src/Observers/Observer.d.ts
+declare abstract class Observer<T extends object> {
+  creating?(model: T): void | Promise<void>;
+  created?(model: T): void | Promise<void>;
+  updating?(model: T): void | Promise<void>;
+  updated?(model: T): void | Promise<void>;
+  saving?(model: T): void | Promise<void>;
+  saved?(model: T): void | Promise<void>;
+  deleting?(model: T): void | Promise<void>;
+  deleted?(model: T): void | Promise<void>;
+  restoring?(model: T): void | Promise<void>;
+  restored?(model: T): void | Promise<void>;
+  retrieved?(model: T): void | Promise<void>;
+}
+//# sourceMappingURL=Observer.d.ts.map
+//#endregion
+//#region src/Model.d.ts
+type ObserverConstructor<T extends object> = new () => Observer<T>;
+declare function use<Traits extends readonly any[]>(...traitClasses: Traits): <MClass extends new (...args: any) => Model>(ctor: MClass) => AttachTraits<MClass, Traits>;
+declare abstract class Model {
+  [key: string]: any;
+  static table: string;
+  static primaryKey: string;
+  static fillable: string[];
+  static guarded: string[];
+  static hidden: string[];
+  static appends: string[];
+  static casts: Casts;
+  static timestamps: boolean;
+  static softDeletes: boolean;
+  static relationships: {
+    [key: string]: RelationshipConfig;
+  };
+  static autoIncrement: boolean;
+  private static observers;
+  static traits: string[];
+  static localScopes: {
+    [name: string]: ScopeMethod<any>;
+  };
+  static globalScopes: {
+    [name: string]: (builder: EloquentBuilder<any>) => void;
+  };
+  static withoutGlobalScopes: string[];
+  static eventListeners: { [K in keyof ModelEvents]: ((model: Model) => boolean | void | Promise<boolean | void>)[] };
+  static _use?: ClassBasedTrait[];
+  private static _accessors;
+  private static _mutators;
+  static __traitClasses: ClassBasedTrait[];
+  id?: number | string;
+  created_at?: Date;
+  updated_at?: Date;
+  deleted_at?: Date | null;
+  protected attributes: ModelAttributes;
+  protected original: ModelAttributes;
+  protected relationshipsLoaded: {
+    [key: string]: any;
+  };
+  protected __exists: boolean;
+  protected __isGettingAttribute: boolean;
+  protected __attributeCache: Map<string, any>;
+  constructor(attributes?: ModelAttributes);
+  static getFillables(): string[];
+  /**
+   * Apply traits to instance (after static traits have been applied)
+   */
+  private applyTraitsToInstance;
+  /**
+   * Add a local scope to the model
+   */
+  static addLocalScope(name: string, scope: ScopeMethod<any>): void;
+  /**
+   * Add a global scope to the model
+   */
+  static addGlobalScope(name: string, scope: (builder: EloquentBuilder<any>) => void): void;
+  /**
+   * Remove a global scope
+   */
+  static removeGlobalScope(name: string): void;
+  /**
+   * Get all global scopes
+   */
+  static getGlobalScopes(): {
+    [name: string]: (builder: EloquentBuilder<any>) => void;
+  };
+  /**
+   * Apply scopes to a query builder
+   */
+  static applyScopes(builder: EloquentBuilder<any>): EloquentBuilder<any>;
+  /**
+   * Register a scope method (similar to Laravel's scope naming convention)
+   */
+  static registerScopeMethod(name: string, scope: ScopeMethod<any>): void;
+  /**
+   * Query with a local scope
+   */
+  static scope<T extends typeof Model>(this: T, name: string, ...args: any[]): EloquentBuilder<InstanceType<T>>;
+  /**
+   * Query without global scopes
+   */
+  static withoutGlobalScope<T extends typeof Model>(this: T, ...scopes: string[]): EloquentBuilder<InstanceType<T>>;
+  /**
+   * Query without any global scopes
+   */
+  static withoutGlobalScopes_<T extends typeof Model>(this: T): EloquentBuilder<InstanceType<T>>;
+  /**
+   * Register an event listener
+   */
+  addEventListener(event: keyof ModelEvents, callback: (model: Model) => boolean | void | Promise<boolean | void>): void;
+  /**
+   * Static method to register an event listener (chainable alternative to addEventListener)
+   * @param event The event name to listen to
+   * @param callback The callback function to execute when the event is triggered
+   * @returns The Model class for chaining
+   */
+  static on(event: keyof ModelEvents, callback: (model: Model) => boolean | void | Promise<boolean | void>): typeof Model;
+  static observe<T extends Model>(observer: ObserverConstructor<T>): typeof Model;
+  /**
+   * Dispatch an event
+   */
+  static dispatchEvent(event: keyof ModelEvents, model: Model): Promise<void>;
+  /**
+   * Fire model events (similar to Laravel's fireModelEvent)
+   */
+  static fireModelEvent(event: keyof ModelEvents, model: Model, halt?: boolean): Promise<boolean>;
+  /**
+   * Boot the model (similar to Laravel's boot method)
+   */
+  static boot(): void;
+  /**
+   * Ensure traits and static containers are initialized once per subclass.
+   * This runs automatically on first static call (e.g., query/ scope).
+   */
+  static ensureBooted(): void;
+  /**
+   * Check if model uses a trait
+   */
+  static usesTrait(traitName: string): boolean;
+  /**
+   * Add traits to the model
+   */
+  static addTraits(...traitNames: string[]): void;
+  /**
+   * Boot all traits (similar to Laravel's bootTraits)
+   */
+  static bootTraits(): void;
+  /**
+   * Add a macro to the model class
+   */
+  static macro(name: string, macro: Function): void;
+  /**
+   * Check if a macro exists
+   */
+  static hasMacro(name: string): boolean;
+  /**
+   * Mixin traits/macros from another class
+   */
+  static mixin(traitClass: any): void;
+  private static toStudlyCase;
+  private static buildMethodName;
+  /**
+   * Get raw attribute value (bypasses accessors)
+   */
+  getRawAttribute(key: string): any;
+  /**
+   * Set raw attribute value (bypasses mutators)
+   */
+  setRawAttribute(key: string, value: any): void;
+  /**
+   * Get property with support for direct field access
+   */
+  getProperty(prop: string): any;
+  /**
+   * Get an attribute with accessor support (sync/async)
+   * @param key Attribute name
+   * @param onlyAppended If true, only return value if it's in appends array
+   */
+  getAttributeAsync<T = any>(key: string, onlyAppended?: boolean): Promise<T>;
+  /**
+   * Get an attribute with accessor support (sync)
+   * @param key Attribute name
+   * @param onlyAppended If true, only return value if it's in appends array
+   */
+  getAttribute<T = any>(key: string, onlyAppended?: boolean): T;
+  /**
+   * Create a context for accessors that allows direct field access
+   */
+  private createAccessorContext;
+  /**
+   * Get attribute with accessor for proxy/getter
+   */
+  private getAttributeWithAccessor;
+  /**
+   * Set attribute with mutator support
+   */
+  setAttributeWithMutator(key: string, value: any): boolean;
+  /**
+   * Get all appended attributes with their values
+   */
+  getAppendedAttributesAsync(): Promise<ModelAttributes>;
+  /**
+   * Get all appended attributes with their values (sync)
+   */
+  getAppendedAttributes(): ModelAttributes;
+  /**
+   * Register a synchronous accessor
+   */
+  static registerAccessor(key: string, fn: (value: any, instance: Model) => any): void;
+  /**
+   * Register an asynchronous accessor
+   */
+  static registerAsyncAccessor(key: string, fn: (value: any, instance: Model) => Promise<any>): void;
+  /**
+   * Register a synchronous mutator
+   */
+  static registerMutator(key: string, fn: (value: any, instance: Model) => any): void;
+  /**
+   * Register an asynchronous mutator
+   */
+  static registerAsyncMutator(key: string, fn: (value: any, instance: Model) => Promise<any>): void;
+  /**
+   * Add attributes to appends array
+   */
+  static addAppends(...attributes: string[]): void;
+  /**
+   * Get a field value (alias for this.field_name in accessors)
+   */
+  getField(fieldName: string): any;
+  /**
+   * Get relationship count (for use in accessors)
+   */
+  getRelationshipCount(relationshipName: string): Promise<number>;
+  /**
+   * Get relationship query (for use in accessors)
+   */
+  getRelationshipQuery(relationshipName: string): any;
+  toJSONAsync(options?: ToJSONOptions): Promise<any>;
+  toJSON(options?: ToJSONOptions & {
+    relationTree?: Record<string, any>;
+  }): any;
+  /**
+   * Get attributes for array conversion (excludes hidden fields)
+   */
+  get attributesToArray(): ModelAttributes;
+  /**
+   * Get all attributes including appended ones
+   */
+  getAttributesWithAppends(): ModelAttributes;
+  /**
+   * Get all attributes including appended ones (async)
+   */
+  getAttributesWithAppendsAsync(): Promise<ModelAttributes>;
+  private serializeRelationshipsAsync;
+  private serializeRelationships;
+  setAttribute(key: string, value: any): void;
+  hydrate(attributes: ModelAttributes): this;
+  fill(attributes: ModelAttributes): this;
+  getAttributes(): ModelAttributes;
+  getOriginal(key?: string): any;
+  isDirty(key?: string): boolean;
+  getDirty(): ModelAttributes;
+  syncOriginal(): this;
+  /**
+   * Get relationship configuration for a given relation name
+   * Supports both static relationships and instance method relationships
+   */
+  protected getRelationship(relation: string): RelationshipConfig | null;
+  /**
+   * Convert a relation instance to a RelationshipConfig
+   */
+  private convertRelationToConfig;
+  /**
+   * Get all defined relationships (both static and instance)
+   */
+  protected getAllRelationships(): {
+    [key: string]: RelationshipConfig;
+  };
+  private getRelationSerializationOptions;
+  private applyAttributeFilters;
+  private addMetadata;
+  setLoadedRelation(name: string, value: any): void;
+  unsetRelation(name: string): void;
+  relationLoaded(name: string): boolean;
+  hasOne<T extends Model>(this: any, model: new () => T, foreignKey?: string, localKey?: string): HasOne<T>;
+  hasMany<T extends Model>(this: any, model: new () => T, foreignKey?: string, localKey?: string): HasMany<T>;
+  /**
+   * Define a has-one-through relationship.
+   *
+   * @param model       The distant (target) model
+   * @param through     The intermediate model
+   * @param firstKey    FK on the intermediate table pointing to the parent (default: parent_table_id)
+   * @param secondKey   FK on the target table pointing to the intermediate (default: through_table_id)
+   * @param localKey    PK on the parent (default: id)
+   * @param secondLocalKey  PK on the intermediate (default: id)
+   */
+  hasOneThrough<T extends Model>(this: any, model: new () => T, through: new () => Model, firstKey?: string, secondKey?: string, localKey?: string, secondLocalKey?: string): HasOneThrough<T>;
+  /**
+   * Define a has-many-through relationship.
+   *
+   * @param model       The distant (target) model
+   * @param through     The intermediate model
+   * @param firstKey    FK on the intermediate table pointing to the parent
+   * @param secondKey   FK on the target table pointing to the intermediate
+   * @param localKey    PK on the parent (default: id)
+   * @param secondLocalKey  PK on the intermediate (default: id)
+   */
+  hasManyThrough<T extends Model>(this: any, model: new () => T, through: new () => Model, firstKey?: string, secondKey?: string, localKey?: string, secondLocalKey?: string): HasManyThrough<T>;
+  belongsTo<T extends Model>(this: any, model: new () => T, foreignKey?: string, ownerKey?: string): BelongsTo<T>;
+  belongsToMany<T extends Model>(this: any, model: new () => T, table?: string | (new (...args: any[]) => Model) | typeof Model, foreignPivotKey?: string, relatedPivotKey?: string): BelongsToMany<T>;
+  morphOne<T extends Model>(this: any, model: new () => T, name: string): HasOne<T>;
+  morphMany<T extends Model>(this: any, model: new () => T, name: string): HasMany<T>;
+  morphTo<T extends Model = Model>(this: any, name: string): BelongsTo<T>;
+  save(options?: {
+    force?: boolean;
+  }): Promise<this>;
+  delete(force?: boolean): Promise<boolean>;
+  restore(): Promise<boolean>;
+  update(attributes: ModelAttributes): Promise<this>;
+  delete_(force?: boolean): Promise<boolean>;
+  restore_(): Promise<boolean>;
+  forceDelete(): Promise<boolean>;
+  refresh(): Promise<this>;
+  replicate(except?: string[]): this;
+  static create<M extends typeof Model>(this: M, attributes: ModelAttributes): Promise<InstanceType<M>>;
+  static createMany<M extends typeof Model>(this: M, rows: Array<ModelAttributes>): Promise<InstanceType<M>[]>;
+  /**
+   * Find a model matching the attributes or create a new one, then update with values
+   * @param attributes - The attributes to find the model by
+   * @param values - The values to update or create the model with
+   * @returns The model instance (existing or newly created)
+   */
+  static updateOrCreate<M extends typeof Model>(this: M, attributes: ModelAttributes, values?: ModelAttributes): Promise<InstanceType<M>>;
+  /**
+   * Alias for updateOrCreate method
+   * @param attributes - The attributes to find the model by
+   * @param values - The values to update or create the model with
+   * @returns The model instance (existing or newly created)
+   */
+  static createOrUpdate<M extends typeof Model>(this: M, attributes: ModelAttributes, values?: ModelAttributes): Promise<InstanceType<M>>;
+  static query_<M extends typeof Model>(this: M): EloquentBuilder<InstanceType<M>>;
+  static query<M extends typeof Model>(this: M): EloquentBuilder<InstanceType<M>>;
+  static with<M extends typeof Model>(this: M, relationships: string[]): EloquentBuilder<InstanceType<M>>;
+  static withTrashed<M extends typeof Model>(this: M): EloquentBuilder<InstanceType<M>>;
+  static withThrashed<M extends typeof Model>(this: M): EloquentBuilder<InstanceType<M>>;
+  static withoutTrashed<M extends typeof Model>(this: M): EloquentBuilder<InstanceType<M>>;
+  static withoutThrashed<M extends typeof Model>(this: M): EloquentBuilder<InstanceType<M>>;
+  static onlyTrashed<M extends typeof Model>(this: M): EloquentBuilder<InstanceType<M>>;
+  static onlyThrashed<M extends typeof Model>(this: M): EloquentBuilder<InstanceType<M>>;
+  static where<M extends typeof Model>(this: M, column: string, operator: any, value?: any): EloquentBuilder<InstanceType<M>>;
+  static find<M extends typeof Model>(this: M, id: number | string): Promise<InstanceType<M> | null>;
+  static findOrFail<M extends typeof Model>(this: M, id: number | string): Promise<InstanceType<M>>;
+  static all<M extends typeof Model>(this: M): Promise<InstanceType<M>[]>;
+  static first<M extends typeof Model>(this: M): Promise<InstanceType<M> | null>;
+  static getTable(): string;
+  private castAttribute;
+  protected getPrimaryKey(): string;
+  private static pluralize;
+  private static looksPlural;
+  [util.inspect.custom](depth: number, options: any): any;
+  load(relations: string[] | string): Promise<this>;
+  loadMissing(relations: string[] | string): Promise<this>;
+  /**
+   * Structured changes report comparing current attributes to original snapshot
+   */
+  changes(): {
+    before: ModelAttributes;
+    after: ModelAttributes;
+    keys: string[];
+    count: number;
+  };
+  static use<T1 extends ClassBasedTrait>(this: typeof Model, trait1: T1): AugmentedModel<typeof Model, [T1]>;
+  static use<T1 extends ClassBasedTrait, T2 extends ClassBasedTrait>(this: typeof Model, trait1: T1, trait2: T2): AugmentedModel<typeof Model, [T1, T2]>;
+  static use<T1 extends ClassBasedTrait, T2 extends ClassBasedTrait, T3 extends ClassBasedTrait>(this: typeof Model, trait1: T1, trait2: T2, trait3: T3): AugmentedModel<typeof Model, [T1, T2, T3]>;
+  static use<T1 extends ClassBasedTrait, T2 extends ClassBasedTrait, T3 extends ClassBasedTrait, T4 extends ClassBasedTrait>(this: typeof Model, trait1: T1, trait2: T2, trait3: T3, trait4: T4): AugmentedModel<typeof Model, [T1, T2, T3, T4]>;
+  static use<T1 extends ClassBasedTrait, T2 extends ClassBasedTrait, T3 extends ClassBasedTrait, T4 extends ClassBasedTrait, T5 extends ClassBasedTrait>(this: typeof Model, trait1: T1, trait2: T2, trait3: T3, trait4: T4, trait5: T5): AugmentedModel<typeof Model, [T1, T2, T3, T4, T5]>;
+}
+type TraitInstance<T extends ClassBasedTrait> = Omit<InstanceType<T>, "constructor">;
+type TraitStatics<T extends ClassBasedTrait> = Omit<T, "prototype">;
+type MergeInstances<Traits extends readonly ClassBasedTrait[]> = Traits extends [infer A, ...infer Rest] ? A extends ClassBasedTrait ? Rest extends readonly ClassBasedTrait[] ? TraitInstance<A> & MergeInstances<Rest> : TraitInstance<A> : {} : {};
+type MergeStatics<Traits extends readonly ClassBasedTrait[]> = Traits extends [infer A, ...infer Rest] ? A extends ClassBasedTrait ? Rest extends readonly ClassBasedTrait[] ? TraitStatics<A> & MergeStatics<Rest> : TraitStatics<A> : {} : {};
+type AugmentedModel<C extends typeof Model, Traits extends readonly ClassBasedTrait[]> = {
+  new (...args: ConstructorParameters<C>): InstanceType<C> & MergeInstances<Traits>;
+} & C & MergeStatics<Traits>;
+//#endregion
+//#region src/Traits/built-ins.d.ts
+/**
+ * SoftDeletes trait as a class (Laravel style)
+ * Usage: use SoftDeletes;
+ */
+declare class SoftDeletes {
+  /**
+   * Determine if the model has been soft-deleted
+   */
+  trashed(): boolean;
+  /**
+   * Determine if the model is not soft-deleted
+   */
+  isNotTrashed(): boolean;
+  /**
+   * Force delete the model (bypass soft delete)
+   */
+  forceDelete(): Promise<boolean>;
+  /**
+   * Restore a soft-deleted model
+   */
+  restore(): Promise<boolean>;
+  /**
+   * Boot method for the trait
+   */
+  static boot(modelClass: typeof Model): void;
+}
+/**
+ * Timestamps trait (auto-manages created_at and updated_at)
+ * Usage: use Timestamps;
+ */
+declare class Timestamps {
+  /**
+   * Touch the model's timestamps
+   */
+  touch(): Promise<void>;
+  /**
+   * Disable timestamps for the current operation
+   */
+  withoutTimestamps(callback: Function): any;
+  static boot(modelClass: typeof Model): void;
+}
+/**
+ * Sluggable trait for generating slugs
+ * Usage: use Sluggable;
+ */
+declare class Sluggable {
+  /**
+   * Generate a slug from a given string
+   */
+  generateSlug(text: string): string;
+  /**
+   * Set slug from attribute
+   */
+  setSlugFrom(sourceField?: string): void;
+  /**
+   * Scope: Find by slug
+   */
+  static scopeFindBySlug(builder: EloquentBuilder<any>, slug: string): EloquentBuilder<any>;
+  static boot(modelClass: typeof Model): void;
+}
+/**
+ * Sortable trait for ordering
+ * Usage: use Sortable;
+ */
+declare class Sortable {
+  /**
+   * Reorder models
+   */
+  static reorder(ids: number[]): Promise<void>;
+  static latest(this: typeof Model): EloquentBuilder<Model>;
+  static oldest(this: typeof Model): EloquentBuilder<Model>;
+  /**
+   * Move model up in order
+   */
+  moveUp(): Promise<void>;
+  /**
+   * Move model down in order
+   */
+  moveDown(): Promise<void>;
+  /**
+   * Scope: Order by order column
+   */
+  static scopeOrdered(builder: EloquentBuilder<any>, direction?: "asc" | "desc"): EloquentBuilder<any>;
+}
+/**
+ * Searchable trait for full-text search
+ * Usage: use Searchable;
+ */
+declare class Searchable {
+  /**
+   * Scope: Search in specified fields
+   */
+  static scopeSearch(builder: EloquentBuilder<any>, query: string, fields?: string[]): EloquentBuilder<any>;
+  /**
+   * Scope: Advanced search with filters
+   */
+  static scopeAdvancedSearch(builder: EloquentBuilder<any>, params: any): EloquentBuilder<any>;
+}
+/**
+ * Cacheable trait for caching queries
+ * Usage: use Cacheable;
+ */
+declare class Cacheable {
+  /**
+   * Cache a query result
+   */
+  static cached(callback: Function, key: string, ttl?: number): any;
+  /**
+   * Clear model cache
+   */
+  static clearCache(): void;
+  /**
+   * Get with cache
+   */
+  static getCached(id: number): any;
+}
+//# sourceMappingURL=built-ins.d.ts.map
+//#endregion
+//#region src/Database/MigrationRunner.d.ts
+declare function run$1(inputArgs?: {
+  command?: "up" | "down";
+  step?: number;
+  force?: boolean;
+  forceConfirm?: boolean;
+  lockName?: string;
+  lockTimeout?: number;
+  lockRetries?: number;
+  lockBackoffMs?: number;
+}): Promise<void>;
+//#endregion
+//#region src/Database/Schema.d.ts
+interface MigrationSchema {
+  createTable(name: string, callback: (table: TableBuilder) => void): any;
+  alterTable(name: string, callback: (table: TableBuilder) => void): any;
+  dropTable(name: string): any;
+  dropTableIfExists(name: string): any;
+  rename(from: string, to: string): any;
+  hasTable(name: string): Promise<boolean>;
+  hasColumn(table: string, column: string): Promise<boolean>;
+  hasColumns(table: string, columns: string[]): Promise<boolean>;
+  getColumnType(table: string, column: string): Promise<string | null>;
+  getColumnListing(table: string): Promise<string[]>;
+  dropColumns(table: string, columns: string[]): any;
+  renameColumn(table: string, from: string, to: string): any;
+}
+type DefaultValue = string | number | boolean | null | RawExpression;
+declare class RawExpression {
+  value: string;
+  constructor(value: string);
+  toString(): string;
+}
+declare class Column {
+  name: string;
+  type: string;
+  length?: number;
+  enumValues?: string[];
+  nullableFlag: boolean;
+  defaultValue?: DefaultValue;
+  unsignedFlag: boolean;
+  uniqueFlag: boolean;
+  primaryFlag: boolean;
+  autoIncrementFlag: boolean;
+  commentText?: string;
+  decimalPlaces?: number;
+  afterColumn?: string;
+  firstFlag: boolean;
+  virtualAsExpr?: string;
+  storedAsExpr?: string;
+  useCurrent__: boolean;
+  useCurrentOnUpdate__: boolean;
+  charset__?: string;
+  collation?: string;
+  invisibleFlag: boolean;
+  generatedAs__?: string;
+  alwaysAs?: string;
+  constructor(name: string, type: string, length?: number, decimalPlaces?: number);
+  enum(values: string[]): this;
+  nullable(): this;
+  notNullable(): this;
+  default(val: DefaultValue): this;
+  unsigned(): this;
+  unique(): this;
+  primary(): this;
+  increments(): this;
+  comment(text: string): this;
+  after(column: string): this;
+  first(): this;
+  useCurrent(): this;
+  useCurrentOnUpdate(): this;
+  charset(charset: string): this;
+  collate(collation: string): this;
+  invisible(): this;
+  virtualAs(expression: string): this;
+  storedAs(expression: string): this;
+  generatedAs(expression: string): this;
+  always(): this;
+  from(startingValue: number): this;
+  index(name?: string): this;
+  toSQL(omitName?: boolean): string;
+}
+declare class TableBuilder {
+  name: string;
+  columns: Column[];
+  primaryKeys: string[];
+  uniques: string[];
+  engine: string;
+  charset: string;
+  indexes: {
+    columns: string[];
+    name?: string;
+    unique?: boolean;
+  }[];
+  foreignKeys: {
+    columns: string[];
+    refTable: string;
+    refColumns: string[];
+    name?: string;
+    onDelete?: string;
+    onUpdate?: string;
+  }[];
+  dropIndexes: string[];
+  dropForeignKeys: string[];
+  lastForeignKeyIndex: number | null;
+  pendingForeign?: {
+    columns: string[];
+    refTable?: string;
+    refColumns?: string[];
+    name?: string;
+    onDelete?: string;
+    onUpdate?: string;
+  };
+  drops: string[];
+  changes: {
+    oldName: string;
+    col: Column;
+  }[];
+  renames: {
+    from: string;
+    to: string;
+  }[];
+  mode: "create" | "alter";
+  constructor(name: string, mode?: "create" | "alter");
+  column(type: string, name: string, length?: number): Column;
+  foreign(columns: string[] | string): this;
+  references(refColumns: string[] | string): this;
+  inTable(tableName: string, opts?: {
+    name?: string;
+  }): this;
+  enum(name: string, values: string[]): Column;
+  set(name: string, values: string[]): Column;
+  increments(name?: string): Column;
+  bigIncrements(name?: string): Column;
+  mediumIncrements(name?: string): Column;
+  smallIncrements(name?: string): Column;
+  tinyIncrements(name?: string): Column;
+  uuid(name?: string): Column;
+  ulid(name?: string): Column;
+  id(name?: string): Column;
+  foreignId(name: string): Column;
+  foreignUuid(name: string): Column;
+  foreignUlid(name: string): Column;
+  integer(name: string, length?: number): Column;
+  unsignedInteger(name: string): Column;
+  tinyInteger(name: string): Column;
+  unsignedTinyInteger(name: string): Column;
+  smallInteger(name: string): Column;
+  unsignedSmallInteger(name: string): Column;
+  mediumInteger(name: string): Column;
+  unsignedMediumInteger(name: string): Column;
+  bigInteger(name: string): Column;
+  unsignedBigInteger(name: string): Column;
+  boolean(name: string): Column;
+  string(name: string, length?: number): Column;
+  char(name: string, length?: number): Column;
+  text(name: string): Column;
+  tinyText(name: string): Column;
+  mediumText(name: string): Column;
+  longText(name: string): Column;
+  decimal(name: string, precision?: number, scale?: number): Column;
+  unsignedDecimal(name: string, precision?: number, scale?: number): Column;
+  float(name: string, precision?: number, scale?: number): Column;
+  unsignedFloat(name: string, precision?: number, scale?: number): Column;
+  double(name: string, precision?: number, scale?: number): Column;
+  unsignedDouble(name: string, precision?: number, scale?: number): Column;
+  datetime(name: string, precision?: number): Column;
+  date(name: string): Column;
+  time(name: string, precision?: number): Column;
+  timestamp(name: string, precision?: number): Column;
+  timestampTz(name: string, precision?: number): Column;
+  datetimeTz(name: string, precision?: number): Column;
+  timeTz(name: string, precision?: number): Column;
+  year(name: string): Column;
+  timestamps(precision?: number): this;
+  timestampsTz(precision?: number): this;
+  nullableTimestamps(precision?: number): this;
+  softDeletes(column?: string, precision?: number): this;
+  softDeletesTz(column?: string, precision?: number): this;
+  binary(name: string, length?: number): Column;
+  json(name: string): Column;
+  jsonb(name: string): Column;
+  geometry(name: string): Column;
+  point(name: string): Column;
+  lineString(name: string): Column;
+  polygon(name: string): Column;
+  geometryCollection(name: string): Column;
+  multiPoint(name: string): Column;
+  multiLineString(name: string): Column;
+  multiPolygon(name: string): Column;
+  ipAddress(name?: string): Column;
+  macAddress(name?: string): Column;
+  rememberToken(): Column;
+  morphs(name: string, indexName?: string): this;
+  nullableMorphs(name: string, indexName?: string): this;
+  uuidMorphs(name: string, indexName?: string): this;
+  nullableUuidMorphs(name: string, indexName?: string): this;
+  ulidMorphs(name: string, indexName?: string): this;
+  nullableUlidMorphs(name: string, indexName?: string): this;
+  unique(name: string): this;
+  primary(name: string): this;
+  index(columns: string[] | string, name?: string): this;
+  uniqueIndex(columns: string[] | string, name?: string): this;
+  dropIndex(name: string): this;
+  dropForeignKey(name: string): this;
+  foreignKey(columns: string[] | string, refTable: string, refColumns: string[] | string, opts?: {
+    name?: string;
+    onDelete?: string;
+    onUpdate?: string;
+  }): this;
+  onDelete(action: string): this;
+  onUpdate(action: string): this;
+  dropColumn(name: string): this;
+  renameColumn(from: string, to: string): this;
+  changeColumn(oldName: string, cb: (col: Column) => Column): this;
+  toSQL(): string;
+}
+declare class Schema implements MigrationSchema {
+  private queryFn?;
+  constructor(queryFn?: (sql: string, params?: any[]) => Promise<any>);
+  createTable(name: string, callback: (table: TableBuilder) => void): string;
+  alterTable(name: string, callback: (table: TableBuilder) => void): string;
+  dropTable(name: string): string;
+  dropTableIfExists(name: string): string;
+  rename(from: string, to: string): string;
+  hasTable(name: string): Promise<boolean>;
+  hasColumn(table: string, column: string): Promise<boolean>;
+  hasColumns(table: string, columns: string[]): Promise<boolean>;
+  getColumnType(table: string, column: string): Promise<string | null>;
+  getColumnListing(table: string): Promise<string[]>;
+  dropColumns(table: string, columns: string[]): string;
+  renameColumn(table: string, from: string, to: string): string;
+  createDatabase(name: string): string;
+  dropDatabaseIfExists(name: string): string;
+  enableForeignKeyConstraints(): string;
+  disableForeignKeyConstraints(): string;
+  getAllTables(): Promise<string[]>;
+  getAllViews(): Promise<string[]>;
+}
+//#endregion
+//#region src/Database/SeederRunner.d.ts
+interface SeederOptions {
+  class?: string;
+  force?: boolean;
+}
+declare function run$2(inputOptions?: SeederOptions): Promise<void>;
+//#endregion
+//#region src/Database/MigrateFresh.d.ts
+interface MigrateFreshOptions {
+  force?: boolean;
+  seed?: boolean;
+  seederClass?: string;
+}
+declare function run(inputArgs?: MigrateFreshOptions): Promise<void>;
+//#endregion
+//#region src/Database/index.d.ts
+declare function rollbackMigrations(options?: {
+  step?: number;
+}): Promise<void>;
+declare function makeMigration(name: string, options?: {
+  table?: string;
+  alter?: boolean;
+}): Promise<void>;
+//# sourceMappingURL=index.d.ts.map
+//#endregion
+//#region src/QueryInstrumentation.d.ts
+interface QueryEventPayload {
+  sql: string;
+  bindings?: any[];
+  duration: number;
+  rows?: number;
+  error?: string;
+  connection: string;
+  collection?: string;
+}
+/** Called by @lara-node/telescope or @lara-node/events to wire up query event emission. */
+declare function setQueryEventHook(hook: (payload: QueryEventPayload) => Promise<void>): void;
+/** Emit a query event via the registered hook (no-op if none registered). */
+
+/**
+ * Wraps a MongoCollection in a Proxy that times every operation and calls
+ * emitQueryEvent() so Telescope captures it regardless of which process runs it.
+ */
+declare function createMongoQueryProxy<T extends object>(collectionName: string, col: T): T;
+/** The Cache key pattern used for cross-process query entries. */
+declare const TELESCOPE_QUERY_CACHE_KEY: string;
+//# sourceMappingURL=QueryInstrumentation.d.ts.map
+//#endregion
+//#region src/DatabaseServiceProvider.d.ts
+declare class DatabaseServiceProvider extends ServiceProvider {
+  register(): void;
+  boot(): Promise<void>;
+}
+//# sourceMappingURL=DatabaseServiceProvider.d.ts.map
+
+//#endregion
+export { BelongsTo, BelongsToMany, Cacheable, type Casts, DB, DatabaseServiceProvider, EloquentBuilder, HasMany, HasManyThrough, HasOne, HasOneThrough, type IMysqlTransaction, type ITransaction, type MigrationSchema, Model, type ModelAttributes, Observer, type QueryResult, type RelationshipConfig, Schema, Searchable, Sluggable, SoftDeletes, Sortable, TELESCOPE_QUERY_CACHE_KEY, TableBuilder, Timestamps, applyTraits, collection, createMongoQueryProxy, getDbType, getMongoDb, getPool, initDatabase, makeMigration, run as migrateFresh, query, rollbackMigrations, run$1 as runMigrations, run$2 as runSeeders, setQueryEventHook, use };
+//# sourceMappingURL=index.d.ts.map