ilana-orm 1.0.18 → 1.0.20

package/orm/MigrationRunner.js

@@ -417,28 +417,20 @@ class MigrationRunner {
 
     if (isCreate || name.includes('create_')) {
       return isTS ?
-        `import type { SchemaBuilder } from 'ilana-orm';
-
-export default class ${className} {
-  // connection = 'mysql'; // Uncomment to use specific connection
-  
-  async up(schema: SchemaBuilder): Promise<void> {
+        `export default class ${className} {
+  async up(schema) {
     await schema.createTable('${table}', (table) => {
       table.increments('id');
       table.timestamps();
     });
   }
 
-  async down(schema: SchemaBuilder): Promise<void> {
+  async down(schema) {
     await schema.dropTable('${table}');
   }
 }
 ` :
-        `const { SchemaBuilder } = require('ilana-orm');
-
-class ${className} {
-  // connection = 'mysql'; // Uncomment to use specific connection
-  
+        `class ${className} {
   async up(schema) {
     await schema.createTable('${table}', (table) => {
       table.increments('id');
@@ -455,42 +447,30 @@ module.exports = ${className};
 `;
     } else if (tableName) {
       return isTS ?
-        `import type { SchemaBuilder } from 'ilana-orm';
-
-export default class ${className} {
-  // connection = 'mysql'; // Uncomment to use specific connection
-  
-  async up(schema: SchemaBuilder): Promise<void> {
+        `export default class ${className} {
+  async up(schema) {
     await schema.table('${table}', (table) => {
-      // Add your column modifications here
-      // table.string('new_column').nullable();
+      // table.string('column_name').nullable();
     });
   }
 
-  async down(schema: SchemaBuilder): Promise<void> {
+  async down(schema) {
     await schema.table('${table}', (table) => {
-      // Reverse your modifications here
-      // table.dropColumn('new_column');
+      // table.dropColumn('column_name');
     });
   }
 }
 ` :
-        `const { SchemaBuilder } = require('ilana-orm');
-
-class ${className} {
-  // connection = 'mysql'; // Uncomment to use specific connection
-  
+        `class ${className} {
   async up(schema) {
     await schema.table('${table}', (table) => {
-      // Add your column modifications here
-      // table.string('new_column').nullable();
+      // table.string('column_name').nullable();
     });
   }
 
   async down(schema) {
     await schema.table('${table}', (table) => {
-      // Reverse your modifications here
-      // table.dropColumn('new_column');
+      // table.dropColumn('column_name');
     });
   }
 }
@@ -500,31 +480,19 @@ module.exports = ${className};
     }
 
     return isTS ?
-      `import type { SchemaBuilder } from 'ilana-orm';
-
-export default class ${className} {
-  // connection = 'mysql'; // Uncomment to use specific connection
-  
-  async up(schema: SchemaBuilder): Promise<void> {
-    // Add your migration logic here
+      `export default class ${className} {
+  async up(schema) {
   }
 
-  async down(schema: SchemaBuilder): Promise<void> {
-    // Add your rollback logic here
+  async down(schema) {
   }
 }
 ` :
-      `const { SchemaBuilder } = require('ilana-orm');
-
-class ${className} {
-  // connection = 'mysql'; // Uncomment to use specific connection
-  
+      `class ${className} {
   async up(schema) {
-    // Add your migration logic here
   }
 
   async down(schema) {
-    // Add your rollback logic here
   }
 }
 

package/orm/Model.d.ts

@@ -1,4 +1,5 @@
-import QueryBuilder from './QueryBuilder';
+import QueryBuilder, { PaginationResult, SimplePaginationResult, CursorPaginationResult } from './QueryBuilder';
+import Collection from './Collection';
 import { HasOne, HasMany, BelongsTo, BelongsToMany, HasManyThrough, MorphTo, MorphOne, MorphMany } from './Relation';
 
 export interface ModelAttributes {
@@ -36,7 +37,7 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   protected static table: string;
   protected static connection?: string;
   protected static primaryKey: string;
-  protected static keyType: 'number' | 'string';
+  protected static keyType: 'number' | 'string' | 'uuid' | 'ulid';
   protected static incrementing: boolean;
   protected static timestamps: boolean;
   protected static createdAt: string;
@@ -51,8 +52,12 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   protected static appends: string[];
   protected static timezone: string;
   static strictLoading: boolean;
+  static preventsSilentlyDiscardingAttributes: boolean;
   static touches: string[];
   static enums: { [column: string]: string[] };
+  static embeddingColumn: string;
+  static embeddingDimensions: number;
+  static embeddingProvider?: (text: string) => Promise<number[]>;
 
   // Instance properties
   attributes: ModelAttributes;
@@ -72,6 +77,7 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
 
   // Static methods
   static register(): void;
+  static _autoRegister(): void;
   static resolveRelatedModel(related: string | typeof Model): typeof Model;
   static query(): QueryBuilder;
   static with(...relations: string[]): QueryBuilder;
@@ -86,19 +92,136 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   static oldest(column?: string): QueryBuilder;
   static withTrashed(): QueryBuilder;
   static onlyTrashed(): QueryBuilder;
+  static withoutTrashed(): QueryBuilder;
+  static findOrFail(id: number | string): Promise<Model>;
+  static insertGetId(data: { [key: string]: any }): Promise<number | string>;
   static upsert(data: any[], uniqueBy: string[], update?: string[]): Promise<any>;
   static withoutGlobalScopes(): QueryBuilder;
   static make(attributes?: ModelAttributes): Model;
   static create(attributes?: ModelAttributes): Promise<Model>;
   static generateUuid(): string;
+  static generateUlid(): string;
+  static _generateKey(): string;
+  static withoutEvents<T>(callback: () => Promise<T>): Promise<T>;
+  static prunable(): QueryBuilder;
+  static prune(): Promise<number>;
   static insert(data: ModelAttributes | ModelAttributes[]): Promise<any>;
   static destroy(ids: any | any[]): Promise<number>;
   static truncate(): Promise<void>;
   static seed(count?: number): Promise<any[]>;
+  static nearestTo(vector: number[], options?: { limit?: number; column?: string; distance?: 'cosine' | 'l2' | 'inner' }): Promise<Collection<any>>;
+  static search(text: string, options?: { limit?: number; column?: string; distance?: 'cosine' | 'l2' | 'inner'; provider?: (text: string) => Promise<number[]> }): Promise<Collection<any>>;
   static firstOrCreate(attributes: ModelAttributes, values?: ModelAttributes): Promise<Model>;
   static firstOrNew(attributes: ModelAttributes, values?: ModelAttributes): Promise<Model>;
   static updateOrCreate(attributes: ModelAttributes, values?: ModelAttributes): Promise<Model>;
 
+  // QueryBuilder methods forwarded from Model.query() — at runtime, any
+  // QueryBuilder method not already declared above is proxied automatically
+  // from Model.<method>() to Model.query().<method>() (see Model.js), so this
+  // list exists purely to give TypeScript users type information for it.
+  static where(column: string, value: any): QueryBuilder;
+  static where(column: string, operator: string, value: any): QueryBuilder;
+  static orWhere(column: string, value: any): QueryBuilder;
+  static orWhere(column: string, operator: string, value: any): QueryBuilder;
+  static whereIn(column: string, values: any[]): QueryBuilder;
+  static whereNotIn(column: string, values: any[]): QueryBuilder;
+  static whereNull(column: string): QueryBuilder;
+  static whereNotNull(column: string): QueryBuilder;
+  static whereBetween(column: string, range: [any, any]): QueryBuilder;
+  static whereNotBetween(column: string, range: [any, any]): QueryBuilder;
+  static whereJsonContains(column: string, value: any): QueryBuilder;
+  static whereJsonLength(column: string, operator: string, value: number): QueryBuilder;
+  static whereDate(column: string, value: string): QueryBuilder;
+  static whereDate(column: string, operator: string, value: string): QueryBuilder;
+  static whereMonth(column: string, month: number): QueryBuilder;
+  static whereYear(column: string, year: number): QueryBuilder;
+  static whereDay(column: string, operatorOrValue: any, value?: any): QueryBuilder;
+  static whereTime(column: string, operatorOrValue: any, value?: any): QueryBuilder;
+  static whereRaw(sql: string, bindings?: any[]): QueryBuilder;
+  static orWhereNull(column: string): QueryBuilder;
+  static orWhereNotNull(column: string): QueryBuilder;
+  static orWhereIn(column: string, values: any[]): QueryBuilder;
+  static orWhereNotIn(column: string, values: any[]): QueryBuilder;
+  static orWhereRaw(sql: string, bindings?: any[]): QueryBuilder;
+  static whereExists(callback: (query: QueryBuilder) => void): QueryBuilder;
+  static whereNotExists(callback: (query: QueryBuilder) => void): QueryBuilder;
+  static when<T>(condition: T, callback: (query: QueryBuilder, condition: T) => void, otherwise?: (query: QueryBuilder) => void): QueryBuilder;
+  static unless<T>(condition: T, callback: (query: QueryBuilder) => void, otherwise?: (query: QueryBuilder, condition: T) => void): QueryBuilder;
+
+  static join(table: string, first: string, operator: string, second: string): QueryBuilder;
+  static leftJoin(table: string, first: string, operator: string, second: string): QueryBuilder;
+  static rightJoin(table: string, first: string, operator: string, second: string): QueryBuilder;
+  static innerJoin(table: string, first: string, operator: string, second: string): QueryBuilder;
+  static crossJoin(table: string): QueryBuilder;
+
+  static orderBy(column: string, direction?: 'asc' | 'desc'): QueryBuilder;
+  static orderByRaw(sql: string): QueryBuilder;
+  static orderBySubquery(callback: (query: QueryBuilder) => void, direction?: 'asc' | 'desc'): QueryBuilder;
+  static inRandomOrder(): QueryBuilder;
+  static limit(count: number): QueryBuilder;
+  static offset(count: number): QueryBuilder;
+  static take(count: number): QueryBuilder;
+  static skip(count: number): QueryBuilder;
+  static from(table: string): QueryBuilder;
+  static forPage(page: number, perPage?: number): QueryBuilder;
+
+  static groupBy(...columns: string[]): QueryBuilder;
+  static having(column: string, operator: string, value: any): QueryBuilder;
+  static having(rawSql: string): QueryBuilder;
+  static havingRaw(sql: string, bindings?: any[]): QueryBuilder;
+
+  static lockForUpdate(): QueryBuilder;
+  static sharedLock(): QueryBuilder;
+  static skipLocked(): QueryBuilder;
+  static noWait(): QueryBuilder;
+
+  static select(...columns: any[]): QueryBuilder;
+  static addSelect(...columns: any[]): QueryBuilder;
+  static addSelect(subqueries: { [alias: string]: (query: QueryBuilder) => void }): QueryBuilder;
+  static distinct(): QueryBuilder;
+  static selectRaw(sql: string, bindings?: any[]): QueryBuilder;
+
+  static withPendingAttributes(attributes: { [key: string]: any }): QueryBuilder;
+  static withConstraints(relation: string, callback: (query: QueryBuilder) => void): QueryBuilder;
+  static withConstraints(relations: { [key: string]: (query: QueryBuilder) => void }): QueryBuilder;
+  static whereHas(relation: string, callback?: (query: QueryBuilder) => void): QueryBuilder;
+  static doesntHave(relation: string): QueryBuilder;
+  static whereDoesntHave(relation: string, callback?: (query: QueryBuilder) => void): QueryBuilder;
+  static has(relation: string, operator?: '=' | '!=' | '<' | '<=' | '>' | '>=', count?: number): QueryBuilder;
+
+  static count(column?: string): Promise<number>;
+  static sum(column: string): Promise<number>;
+  static avg(column: string): Promise<number>;
+  static min(column: string): Promise<any>;
+  static max(column: string): Promise<any>;
+
+  static pluck(column: string): Promise<any[]>;
+  static exists(): Promise<boolean>;
+  static doesntExist(): Promise<boolean>;
+  static sole(): Promise<Model>;
+  static tap(callback: (query: QueryBuilder) => void): QueryBuilder;
+  static get(): Promise<Collection<Model>>;
+
+  static paginate(page?: number, perPage?: number): Promise<PaginationResult<Model>>;
+  static simplePaginate(page?: number, perPage?: number): Promise<SimplePaginationResult<Model>>;
+  static cursorPaginate(perPage?: number, cursor?: string, column?: string, direction?: 'asc' | 'desc'): Promise<CursorPaginationResult<Model>>;
+
+  static chunk(size: number, callback: (models: Collection<Model>) => Promise<void>): Promise<void>;
+  static cursor(chunkSize?: number): AsyncGenerator<Model, void, unknown>;
+  static lazy(chunkSize?: number): AsyncGenerator<Model, void, unknown>;
+
+  static update(data: any): Promise<number>;
+  static increment(column: string, amount?: number): Promise<number>;
+  static decrement(column: string, amount?: number): Promise<number>;
+  static delete(): Promise<number>;
+  static restore(): Promise<number>;
+
+  static clone(): QueryBuilder;
+  static toKnex(): any;
+  static toSql(): string;
+  static values(): Promise<any[]>;
+  static new(attributes?: { [key: string]: any }): Promise<Model>;
+
   // Scopes
   static addGlobalScope(name: string, scope: (query: QueryBuilder) => void): void;
   static removeGlobalScope(name: string): void;
@@ -129,6 +252,7 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   // Instance methods
   getKey(): any;
   fill(attributes: ModelAttributes): this;
+  forceFill(attributes: ModelAttributes): this;
   load(...relations: string[]): Promise<this>;
   loadMissing(...relations: string[]): Promise<this>;
   getRelation(key: string): any;
@@ -156,6 +280,8 @@ export default class Model<TAttributes extends ModelAttributes = ModelAttributes
   forceDelete(): Promise<boolean>;
   fresh(): Promise<this | null>;
   is(other: Model): boolean;
+  isNot(other: Model | null | undefined): boolean;
+  replicate(except?: string[]): this;
   toJSON(): any;
 
   // Relationships

package/orm/Model.js

@@ -3,21 +3,24 @@ const QueryBuilder = require('./QueryBuilder');
 const { HasOne, HasMany, BelongsTo, BelongsToMany, HasManyThrough, MorphTo, MorphMany, MorphOne } = require('./Relation');
 const ModelRegistry = require('./ModelRegistry');
 const Database = require('../database/connection');
-
-// Auto-load configuration on first import
-(function autoLoadConfig() {
-  const fs = require('fs');
-  const path = require('path');
-  const configPathJs = path.join(process.cwd(), 'ilana.config.js');
-  const configPathMjs = path.join(process.cwd(), 'ilana.config.mjs');
-  
-  if (fs.existsSync(configPathJs)) {
-    delete require.cache[configPathJs];
-    require(configPathJs);
-  } else if (fs.existsSync(configPathMjs)) {
-    // For ES modules, we'll handle this in the _getConfig method
-  }
-})();
+const { MassAssignmentException } = require('./Errors');
+
+// Auto-load configuration on first import (skipped in edge runtime)
+if (typeof process !== 'undefined' && process.versions && process.versions.node && !global.__ILANA_EDGE__) {
+  (function autoLoadConfig() {
+    const fs = require('fs');
+    const path = require('path');
+    const configPathJs = path.join(process.cwd(), 'ilana.config.js');
+    const configPathMjs = path.join(process.cwd(), 'ilana.config.mjs');
+
+    if (fs.existsSync(configPathJs)) {
+      delete require.cache[configPathJs];
+      require(configPathJs);
+    } else if (fs.existsSync(configPathMjs)) {
+      // For ES modules, handled in _getConfig
+    }
+  })();
+}
 
 class Model {
   // --- Static defaults ---
@@ -36,8 +39,11 @@ class Model {
   static appends = [];
   static timezone = 'UTC';
   static strictLoading = false;
+  static preventsSilentlyDiscardingAttributes = false;
   static touches = [];
   static enums = {};
+  static embeddingColumn = 'embedding';
+  static embeddingDimensions = 1536;
 
   // --- Instance props ---
   attributes = {};
@@ -53,6 +59,8 @@ class Model {
   _deferred;
 
   constructor(attrs = {}) {
+    this.constructor._autoRegister();
+
     // instance-level fillable/guarded/casts
     this.fillable = Array.isArray(this.fillable) && this.fillable.length
       ? this.fillable
@@ -164,10 +172,21 @@ class Model {
     ModelRegistry.register(this.name, this);
   }
 
+  // Registers this class the first time it's actually used (constructed or
+  // queried), so string-based relations (this.hasMany('Post')) resolve
+  // without requiring an explicit Post.register() call, as long as Post gets
+  // used somewhere before the relation is loaded. Cheap to call repeatedly:
+  // skips the registry write once this class is already registered as itself.
+  static _autoRegister() {
+    if (ModelRegistry.get(this.name) !== this) {
+      ModelRegistry.register(this.name, this);
+    }
+  }
+
   static resolveRelatedModel(related) {
     if (typeof related === 'string') {
       const cls = ModelRegistry.get(related);
-      if (!cls) throw new Error(`Model '${related}' not found. Make sure to call ${related}.register().`);
+      if (!cls) throw new Error(`Model '${related}' not found. It gets registered automatically the first time it's queried or constructed, so require/use ${related} somewhere before this point, or call ${related}.register() explicitly.`);
       return cls;
     }
 
@@ -189,6 +208,7 @@ class Model {
 
   // --- Query builder ---
   static query() {
+    this._autoRegister();
 
     const qb = new QueryBuilder(this.getTableName(), this, this.getConnectionName());
 
@@ -225,6 +245,9 @@ class Model {
   static oldest(col) { return this.query().oldest(col || this.createdAt || 'created_at'); }
   static withTrashed() { return this.query().withTrashed(); }
   static onlyTrashed() { return this.query().onlyTrashed(); }
+  static withoutTrashed() { return this.query().withoutTrashed(); }
+  static async findOrFail(id) { return this.query().findOrFail(id); }
+  static async insertGetId(data) { return this.query().insertGetId(data); }
   static async upsert(data, uniqueBy, update) { return this.query().upsert(data, uniqueBy, update); }
   static withoutGlobalScopes() {
     return new QueryBuilder(this.getTableName(), this, this.getConnectionName());
@@ -233,8 +256,8 @@ class Model {
   static make(attrs = {}) {
     const inst = new this(attrs);
     inst._initialize();
-    if (!this.incrementing && this.keyType === 'string' && !inst.getKey()) {
-      inst.setAttribute(this.primaryKey, this.generateUuid());
+    if (!this.incrementing && (this.keyType === 'string' || this.keyType === 'uuid' || this.keyType === 'ulid') && !inst.getKey()) {
+      inst.setAttribute(this.primaryKey, this._generateKey());
     }
     return inst;
   }
@@ -252,8 +275,63 @@ class Model {
     });
   }
 
+  static generateUlid() {
+    const CHARS = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+    const now = Date.now();
+    let t = now;
+    let ts = '';
+    for (let i = 9; i >= 0; i--) {
+      ts = CHARS[t % 32] + ts;
+      t = Math.floor(t / 32);
+    }
+    let rand = '';
+    for (let i = 0; i < 16; i++) rand += CHARS[Math.floor(Math.random() * 32)];
+    return ts + rand;
+  }
+
+  static _generateKey() {
+    if (this.keyType === 'ulid') return this.generateUlid();
+    return this.generateUuid();
+  }
+
   static async insert(data) { return this.query().insert(data); }
   static async truncate() { return this.query().toKnex().truncate(); }
+
+  static _assertPgVector() {
+    const conn = Database.connection(this.connection);
+    const client = conn?.client?.config?.client || '';
+    if (!client.includes('pg')) {
+      throw new Error(
+        `${this.name}.search() and ${this.name}.nearestTo() require PostgreSQL with the pgvector extension. ` +
+        `Current database client is '${client || 'unknown'}'. ` +
+        `Vector search is not supported on MySQL or SQLite.`
+      );
+    }
+  }
+
+  static async nearestTo(vector, { limit = 10, column, distance = 'cosine' } = {}) {
+    this._assertPgVector();
+    const col = column || this.embeddingColumn;
+    const ops = { cosine: '<=>', l2: '<->', inner: '<#>' };
+    const op = ops[distance] || '<=>';
+    const vectorStr = `[${Array.from(vector).join(',')}]`;
+    return this.query()
+      .selectRaw(`*, (${col} ${op} ?) as distance`, [vectorStr])
+      .orderByRaw(`${col} ${op} ?`, [vectorStr])
+      .limit(limit)
+      .get();
+  }
+
+  static async search(text, { limit = 10, column, distance = 'cosine', provider } = {}) {
+    this._assertPgVector();
+    const embed = provider || this.embeddingProvider;
+    if (!embed) throw new Error(
+      `${this.name}.search() requires an embedding provider. ` +
+      `Pass { provider: async (text) => number[] } or set ${this.name}.embeddingProvider.`
+    );
+    const vector = await embed(text);
+    return this.nearestTo(vector, { limit, column, distance });
+  }
   static async seed(count = 1) {
     const { factory } = require('./Factory');
     return factory(this).times(count).create();
@@ -341,6 +419,7 @@ class Model {
   }
   // static async fireEvent(evt, mdl) { for (const h of this.events[evt] || []) if (await h(mdl) === false) return false; }
   static async fireEvent(evt, mdl) {
+    if (this._mutingEvents) return true;
     const ownEvents = Object.hasOwn(this, 'events') ? this.events : {};
     const handlers = ownEvents[evt] || [];
     for (const handler of handlers) {
@@ -349,6 +428,31 @@ class Model {
     return true;
   }
 
+  static async withoutEvents(callback) {
+    this._mutingEvents = true;
+    try {
+      return await callback();
+    } finally {
+      this._mutingEvents = false;
+    }
+  }
+
+  static prunable() {
+    throw new Error(`${this.name} must implement a static prunable() method that returns a QueryBuilder.`);
+  }
+
+  static async prune() {
+    const query = this.prunable();
+    let pruned = 0;
+    await query.chunk(1000, async (models) => {
+      for (const model of models) {
+        await model.delete();
+        pruned++;
+      }
+    });
+    return pruned;
+  }
+
   // --- Instance methods ---
   static getTableName() { return this.table || this.name.toLowerCase() + 's'; }
   static getPrimaryKey() { return this.primaryKey; }
@@ -359,8 +463,29 @@ class Model {
   getKey() { return this.attributes[this.constructor.primaryKey]; }
 
   fill(attrs) {
+    const discarded = [];
+    for (const [k, v] of Object.entries(attrs)) {
+      if (!this.isFillable(k)) { discarded.push(k); continue; }
+      this.setAttribute(k, v);
+    }
+    // Off by default, matching every prior release: a key rejected by
+    // fillable/guarded is silently dropped, same as always. Opt in per-model
+    // with `static preventsSilentlyDiscardingAttributes = true` to instead
+    // throw on any discarded key — useful for catching a forgotten
+    // `fillable` declaration or a typo'd column name in update() calls,
+    // without changing behavior for anyone who hasn't asked for it.
+    if (discarded.length > 0 && this.constructor.preventsSilentlyDiscardingAttributes) {
+      throw new MassAssignmentException(this.constructor.name, discarded);
+    }
+    return this;
+  }
+
+  // Sets attributes bypassing fillable/guarded entirely, for trusted,
+  // programmatic data (factories, seeders, internal code) rather than
+  // user-supplied mass assignment — mirrors fill()'s counterpart in
+  // Eloquent-style ORMs.
+  forceFill(attrs) {
     for (const [k, v] of Object.entries(attrs)) {
-      if (!this.isFillable(k)) continue;
       this.setAttribute(k, v);
     }
     return this;
@@ -531,9 +656,10 @@ class Model {
         this.setAttribute(createdAtCol, now).setAttribute(updatedAtCol, now);
       }
 
-      // Generate UUID if needed
-      if (!this.constructor.incrementing && this.constructor.keyType === 'string' && !this.getKey()) {
-        this.setAttribute(this.constructor.primaryKey, this.constructor.generateUuid());
+      // Generate UUID/ULID if needed
+      const kt = this.constructor.keyType;
+      if (!this.constructor.incrementing && (kt === 'string' || kt === 'uuid' || kt === 'ulid') && !this.getKey()) {
+        this.setAttribute(this.constructor.primaryKey, this.constructor._generateKey());
       }
 
       const qb = this.constructor.query();
@@ -704,6 +830,27 @@ class Model {
     return this.getKey() === other.getKey();
   }
 
+  isNot(other) {
+    return !this.is(other);
+  }
+
+  replicate(except = []) {
+    const exclude = new Set([
+      this.constructor.primaryKey,
+      ...(this.constructor.timestamps ? ['created_at', 'updated_at'] : []),
+      ...except,
+    ]);
+    const attrs = {};
+    for (const [k, v] of Object.entries(this.attributes)) {
+      if (!exclude.has(k)) attrs[k] = v;
+    }
+    const copy = new this.constructor(attrs);
+    copy._initialize();
+    copy.exists = false;
+    copy.wasRecentlyCreated = false;
+    return copy;
+  }
+
   // JSON serialization
   toJSON() {
     this._initialize();
@@ -799,4 +946,21 @@ class Model {
   }
 }
 
-module.exports = Model;
+// Any QueryBuilder instance method not already forwarded above (e.g. where(),
+// orderBy(), whereIn(), paginate()...) is auto-forwarded from Model.<method>()
+// to Model.query().<method>(), so new QueryBuilder methods don't need a
+// matching static added here to be callable directly on a Model subclass.
+const ModelStaticHandler = {
+  get(target, prop, receiver) {
+    if (typeof prop === 'symbol' || prop in target) {
+      return Reflect.get(target, prop, receiver);
+    }
+    const qbMethod = QueryBuilder.prototype[prop];
+    if (typeof prop === 'string' && prop[0] !== '_' && typeof qbMethod === 'function') {
+      return (...args) => receiver.query()[prop](...args);
+    }
+    return Reflect.get(target, prop, receiver);
+  }
+};
+
+module.exports = new Proxy(Model, ModelStaticHandler);

package/orm/QueryBuilder.d.ts

@@ -104,12 +104,21 @@ export default class QueryBuilder {
   // Selection
   select(...columns: any[]): this;
   addSelect(...columns: any[]): this;
+  addSelect(subqueries: { [alias: string]: (query: QueryBuilder) => void }): this;
   distinct(): this;
 
   // Raw queries
   whereRaw(sql: string, bindings?: any[]): this;
   selectRaw(sql: string, bindings?: any[]): this;
 
+  // Advanced subqueries
+  orderBySubquery(callback: (query: QueryBuilder) => void, direction?: 'asc' | 'desc'): this;
+
+  // Pending attributes (scope defaults)
+  withPendingAttributes(attributes: { [key: string]: any }): this;
+  new(attributes?: { [key: string]: any }): Promise<import('./Model').default>;
+  create(attributes?: { [key: string]: any }): Promise<import('./Model').default>;
+
   // Aggregates
   count(column?: string): Promise<number>;
   sum(column: string): Promise<number>;
@@ -125,6 +134,7 @@ export default class QueryBuilder {
   whereHas(relation: string, callback?: (query: QueryBuilder) => void): this;
   doesntHave(relation: string): this;
   whereDoesntHave(relation: string, callback?: (query: QueryBuilder) => void): this;
+  has(relation: string, operator?: '=' | '!=' | '<' | '<=' | '>' | '>=', count?: number): this;
 
   // Execution methods
   get(): Promise<Collection<Model>>;